Software APIs
Data Structures | Macros | Typedefs | Functions
bitfield.h File Reference

(dcee03a)

Bitfield Manipulation Functions. More...

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

Go to the source code of this file.

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_indexth 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_indexth 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

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
bitfieldBitfield to get the bit from.
bit_indexBit 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_indexThe 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
bitfieldBitfield to update the bit in.
bit_indexBit to update.
valueBit 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
bitfieldBitfield 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
bitfieldBitfield 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
bitfieldBitfield 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
bitfieldBitfield to get the field from.
fieldField 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
bitfieldBitfield to set the field in.
fieldField within bitfield to be set.
valueValue 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
bitfieldBitfield 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
bitfieldBitfield 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
bitfieldBitfield to count 1-bits from.
Returns
The number of 1-bits in bitfield.

Definition at line 232 of file bitfield.h.