(dcee03a)

Bitfield Manipulation Functions. More...

#include <stdbool.h>
#include <stdint.h>

Data Structures
struct	bitfield_field32
	A field of a 32-bit bitfield. More...

Macros
#define	BITFIELD_WARN_UNUSED_RESULT __attribute__((warn_unused_result))
	All the bitfield functions are pure (they do not modify their arguments), so the result must be used. More...

Typedefs
typedef struct bitfield_field32	bitfield_field32_t
	A field of a 32-bit bitfield. More...

typedef uint32_t	bitfield_bit32_index_t
	A single bit in a 32-bit bitfield. More...

Functions
BITFIELD_WARN_UNUSED_RESULT uint32_t	bitfield_field32_read (uint32_t bitfield, bitfield_field32_t field)
	Reads a value from `field` in `bitfield`. More...

BITFIELD_WARN_UNUSED_RESULT uint32_t	bitfield_field32_write (uint32_t bitfield, bitfield_field32_t field, uint32_t value)
	Writes `value` to `field` in `bitfield`. More...

BITFIELD_WARN_UNUSED_RESULT bitfield_field32_t	bitfield_bit32_to_field32 (bitfield_bit32_index_t bit_index)
	Turns a `bitfield_bit32_index_t` into a `bitfield_field32_t` (which is more general). More...

BITFIELD_WARN_UNUSED_RESULT bool	bitfield_bit32_read (uint32_t bitfield, bitfield_bit32_index_t bit_index)
	Reads the `bit_index`th bit in `bitfield`. More...

BITFIELD_WARN_UNUSED_RESULT uint32_t	bitfield_bit32_write (uint32_t bitfield, bitfield_bit32_index_t bit_index, bool value)
	Writes `value` to the `bit_index`th bit in `bitfield`. More...

BITFIELD_WARN_UNUSED_RESULT int32_t	bitfield_find_first_set32 (int32_t bitfield)
	Find First Set Bit. More...

BITFIELD_WARN_UNUSED_RESULT int32_t	bitfield_count_leading_zeroes32 (uint32_t bitfield)
	Count Leading Zeroes. More...

BITFIELD_WARN_UNUSED_RESULT int32_t	bitfield_count_trailing_zeroes32 (uint32_t bitfield)
	Count Trailing Zeroes. More...

BITFIELD_WARN_UNUSED_RESULT int32_t	bitfield_popcount32 (uint32_t bitfield)
	Count Set Bits. More...

BITFIELD_WARN_UNUSED_RESULT int32_t	bitfield_parity32 (uint32_t bitfield)
	Parity. More...

BITFIELD_WARN_UNUSED_RESULT uint32_t	bitfield_byteswap32 (uint32_t bitfield)
	Byte Swap. More...

Detailed Description

Bitfield Manipulation Functions.

Definition in file bitfield.h.

Data Structure Documentation

◆ bitfield_field32

struct bitfield_field32

A field of a 32-bit bitfield.

The following field definition: { .mask = 0b11, .index = 12 }

Denotes the X-marked bits in the following 32-bit bitfield:

field:  0b--------'--------'--XX----'--------
index:   31                                 0

Restrictions: The index plus the width of the mask must not be greater than 31.

Definition at line 39 of file bitfield.h.

Data Fields
uint32_t	index	The field position in the bitfield, counting from the zero-bit.
uint32_t	mask	The field mask. Usually all ones.

Macro Definition Documentation

◆ BITFIELD_WARN_UNUSED_RESULT

#define BITFIELD_WARN_UNUSED_RESULT __attribute__((warn_unused_result))

All the bitfield functions are pure (they do not modify their arguments), so the result must be used.

We enable warnings to ensure this happens.

Definition at line 24 of file bitfield.h.

Typedef Documentation

◆ bitfield_bit32_index_t

typedef uint32_t bitfield_bit32_index_t

A single bit in a 32-bit bitfield.

This denotes the position of a single bit, counting from the zero-bit.

For instance, (bitfield_bit_index_t)4 denotes the X-marked bit in the following 32-bit bitfield:

field:  0b--------'--------'--------'---X----
index:   31                                 0

Restrictions: The value must not be greater than 31.

Definition at line 97 of file bitfield.h.

◆ bitfield_field32_t

typedef struct bitfield_field32 bitfield_field32_t

A field of a 32-bit bitfield.

The following field definition: { .mask = 0b11, .index = 12 }

Denotes the X-marked bits in the following 32-bit bitfield:

field:  0b--------'--------'--XX----'--------
index:   31                                 0

Restrictions: The index plus the width of the mask must not be greater than 31.

Function Documentation

◆ bitfield_bit32_read()

BITFIELD_WARN_UNUSED_RESULT bool bitfield_bit32_read	(	uint32_t	bitfield,
		bitfield_bit32_index_t	bit_index
	)

inline

Reads the bit_indexth bit in bitfield.

Parameters

bitfield	Bitfield to get the bit from.
bit_index	Bit to read.

Returns: true if the bit was one, false otherwise.

Definition at line 122 of file bitfield.h.

◆ bitfield_bit32_to_field32()

BITFIELD_WARN_UNUSED_RESULT bitfield_field32_t bitfield_bit32_to_field32 ( bitfield_bit32_index_t bit_index )

inline

Turns a bitfield_bit32_index_t into a bitfield_field32_t (which is more general).

Parameters

bit_index The corresponding single bit to turn into a field.

Returns: A 1-bit field that corresponds to bit_index.

Definition at line 107 of file bitfield.h.

◆ bitfield_bit32_write()

BITFIELD_WARN_UNUSED_RESULT uint32_t bitfield_bit32_write	(	uint32_t	bitfield,
		bitfield_bit32_index_t	bit_index,
		bool	value
	)

inline

Writes value to the bit_indexth bit in bitfield.

Parameters

bitfield	Bitfield to update the bit in.
bit_index	Bit to update.
value	Bit value to write to `bitfield`.

Returns: bitfield with the bit_indexth bit set to value.

Definition at line 137 of file bitfield.h.

◆ bitfield_byteswap32()

BITFIELD_WARN_UNUSED_RESULT uint32_t bitfield_byteswap32 ( uint32_t bitfield )

inline

Byte Swap.

Returns field with the order of the bytes reversed. Bytes here always means exactly 8 bits.

For instance, byteswap(field) of the below 32-bit value returns 1.

field:  0bAAAAAAAA'BBBBBBBB'CCCCCCCC'DDDDDDDD
index:   31                                 0

returns: 0bDDDDDDDD'CCCCCCCC'BBBBBBBB'AAAAAAAA

This is the canonical definition for the GCC/Clang builtin __builtin_bswap32.

Parameters

bitfield Bitfield to reverse bytes of.

Returns: bitfield with the order of bytes reversed.

Definition at line 277 of file bitfield.h.

◆ bitfield_count_leading_zeroes32()

BITFIELD_WARN_UNUSED_RESULT int32_t bitfield_count_leading_zeroes32 ( uint32_t bitfield )

inline

Count Leading Zeroes.

Returns the number of leading 0-bits in bitfield, starting at the most significant bit position. If bitfield is 0, the result is 32, to match the RISC-V B Extension.

For instance, bitfield_count_leading_zeroes32(field) of the below 32-bit value returns 16.

field:  0b00000000'00000000'11111111'00010000
index:   31                                 0

This is the canonical definition for the GCC/Clang builtin __builtin_clz, and hence returns a signed integer.

Parameters

bitfield Bitfield to count leading 0-bits from.

Returns: The number of leading 0-bits in bitfield.

Definition at line 186 of file bitfield.h.

◆ bitfield_count_trailing_zeroes32()

BITFIELD_WARN_UNUSED_RESULT int32_t bitfield_count_trailing_zeroes32 ( uint32_t bitfield )

inline

Count Trailing Zeroes.

Returns the number of trailing 0-bits in bitfield, starting at the least significant bit position. If bitfield is 0, the result is 32, to match the RISC-V B Extension.

For instance, bitfield_count_trailing_zeroes32(field) of the below 32-bit value returns 4.

field:  0b00000000'00000000'11111111'00010000
index:   31                                 0

This is the canonical definition for the GCC/Clang builtin __builtin_ctz, and hence returns a signed integer.

Parameters

bitfield Bitfield to count trailing 0-bits from.

Returns: The number of trailing 0-bits in bitfield.

Definition at line 210 of file bitfield.h.

◆ bitfield_field32_read()

BITFIELD_WARN_UNUSED_RESULT uint32_t bitfield_field32_read	(	uint32_t	bitfield,
		bitfield_field32_t	field
	)

inline

Reads a value from field in bitfield.

This function uses the field parameter to read the value from bitfield. The resulting value will be shifted right and zero-extended so the field's zero-bit is the return value's zero-bit.

Parameters

bitfield	Bitfield to get the field from.
field	Field to read out from.

Returns: Zero-extended field from bitfield.

Definition at line 58 of file bitfield.h.

◆ bitfield_field32_write()

BITFIELD_WARN_UNUSED_RESULT uint32_t bitfield_field32_write	(	uint32_t	bitfield,
		bitfield_field32_t	field,
		uint32_t	value
	)

inline

Writes value to field in bitfield.

This function uses the field parameter to set specific bits in bitfield. The relevant portion of bitfield is zeroed before the bits are set to value.

Parameters

bitfield	Bitfield to set the field in.
field	Field within bitfield to be set.
value	Value for the new field.

Returns: bitfield with field set to value.

Definition at line 76 of file bitfield.h.

◆ bitfield_find_first_set32()

BITFIELD_WARN_UNUSED_RESULT int32_t bitfield_find_first_set32 ( int32_t bitfield )

inline

Find First Set Bit.

Returns one plus the index of the least-significant 1-bit of a 32-bit word.

For instance, bitfield_find_first_set32(field) of the below 32-bit value returns 5.

field:  0b00000000'00000000'11111111'00010000
index:   31                                 0

This is the canonical definition for the GCC/Clang builtin __builtin_ffs, and hence takes and returns a signed integer.

Parameters

bitfield Bitfield to find the first set bit in.

Returns: One plus the index of the least-significant 1-bit of bitfield.

Definition at line 162 of file bitfield.h.

◆ bitfield_parity32()

BITFIELD_WARN_UNUSED_RESULT int32_t bitfield_parity32 ( uint32_t bitfield )

inline

Parity.

Returns the number of 1-bits in bitfield, modulo 2.

For instance, bitfield_parity32(field) of the below 32-bit value returns 1.

field:  0b00000000'00000000'11111111'00010000
index:   31                                 0

This is the canonical definition for the GCC/Clang builtin __builtin_parity, and hence returns a signed integer.

Parameters

bitfield Bitfield to count 1-bits from.

Returns: The number of 1-bits in bitfield, modulo 2.

Definition at line 254 of file bitfield.h.

◆ bitfield_popcount32()

BITFIELD_WARN_UNUSED_RESULT int32_t bitfield_popcount32 ( uint32_t bitfield )

inline

Count Set Bits.

Returns the number of 1-bits in bitfield.

For instance, bitfield_popcount32(field) of the below 32-bit value returns 9.

field:  0b00000000'00000000'11111111'00010000
index:   31                                 0

This is the canonical definition for the GCC/Clang builtin __builtin_popcount, and hence returns a signed integer.

Parameters

bitfield Bitfield to count 1-bits from.

Returns: The number of 1-bits in bitfield.

Definition at line 232 of file bitfield.h.

(dcee03a)

Data Structures

Macros

Typedefs

Functions

Detailed Description

Data Structure Documentation

◆ bitfield_field32

Macro Definition Documentation

◆ BITFIELD_WARN_UNUSED_RESULT

Typedef Documentation

◆ bitfield_bit32_index_t

◆ bitfield_field32_t

Function Documentation

◆ bitfield_bit32_read()

◆ bitfield_bit32_to_field32()

◆ bitfield_bit32_write()

◆ bitfield_byteswap32()

◆ bitfield_count_leading_zeroes32()

◆ bitfield_count_trailing_zeroes32()

◆ bitfield_field32_read()

◆ bitfield_field32_write()

◆ bitfield_find_first_set32()

◆ bitfield_parity32()

◆ bitfield_popcount32()