illumos: manual page: bitset8.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);
}