Tribblix: manual page: bitset64.9f

BITSET64(9F) Kernel Functions for Drivers BITSET64(9F)

NAME

bitset8, bitset16, bitset32, bitset64 - set bitfield values in an
integer

SYNOPSIS

#include <sys/bitext.h>

uint8_t
bitset8(uint8_t base, uint_t high, uint_t low, uint8_t value);

uint16_t
bitset16(uint16_t base, uint_t high, uint_t low, uint16_t value);

uint32_t
bitset32(uint32_t base, uint_t high, uint_t low, uint32_t value);

uint64_t
bitset64(uint64_t base, uint_t high, uint_t low, uint64_t value);

INTERFACE LEVEL

Volatile - This interface is still evolving in illumos. API and ABI
stability is not guaranteed.

PARAMETERS

base The starting integer that will have a value ORed into it.

high The high end, inclusive, of the bit range to insert value
into base.

low The low end, inclusive, of the bit range to extract from
value.

value A value to insert into base.

DESCRIPTION

The bitset8(), bitset16(), bitset32(), and bitset64() functions are
used to logically bitwise-OR in the integer value into a specified bit
position in base. Effectively, the function zeros out the bit range in
base, described by high and low and then performs a bitwise-OR of base
which has been adjusted to start at low.

The high and low arguments describe an inclusive bit range ([low,
high]) which describes where value should be inserted. It is illegal
for low to be greater than high, for low or high to exceed the
integer's bit range (e.g. neither can be greater than 7 for bitset8()),
and value must not exceed the described bit range. That is, if high
was 2 and low was 1, value could not be larger than a 2-bit value.

Note, these functions do not modify either base or value.

RETURN VALUES

Upon successful completion, the bitset8(), bitset16(), bitset32(), and
bitset64() functions all return a new value that has first cleared the
specified bit range from base and then replaced it with value.

EXAMPLES

Example 1 - Using the bitset32() function to build up a register value.

A common use case for these functions is to help deal with registers
that are defined as a series of bit values. The following example
shows a register's bit definitions and then how they are used to
construct a value to write.

/*
* This represents a token register definition. It is normally a
* uint32_t.
*/
#define DF_IO_BASE_V2_SET_BASE(r, v) bitx32(r, 24, 12, v)
#define DF_IO_BASE_V2_SET_IE(r, v) bitset32(r, 5, 5, v)
#define DF_IO_BASE_V2_SET_WE(r, v) bitset32(r, 1, 1, v)
#define DF_IO_BASE_V2_SET_RE(r, v) bitset32(r, 0, 0, v)

void
setup_register(uint32_t base)
{
uint32_t reg = 0;

/*
* Set read enable, write enable, and the base. Then write the
* hardware register.
*/
reg = DF_IO_BASE_V2_SET_RE(reg, 1);
reg = DF_IO_BASE_V2_SET_WE(reg, 1);
reg = DF_IO_BASE_V2_SET_BASE(reg, base);
write_register(XXX, reg);
}