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);
}