Bit#

Defined in namespace hal

#include <libhal-util/bit.hpp>

group Bit

Functions

template<std::uint32_t position1, std::uint32_t position2 = position1> static inline consteval bit_mask from()#

Generate, at compile time, a bit_mask that spans the from position1 to position2.

If position1 is the same position2 then the bit_mask will have length of 1 and the bit position will be the value of position1.

position1 and position2 can be in any order so long as they span the distance from the start and end of the bit_mask range.

Use this when you REQUIRE the bit mask to be generated at compile time, because template arguments are required to be known at compile time.

Template Parameters:

position1 – - bit position 1
position2 – - bit position 2

Returns:

consteval bit_mask - bit bit_mask represented by the two bit positions

static inline constexpr bit_mask from(std::uint32_t position1, std::uint32_t position2)#

Generate, at compile time, a bit_mask that spans the from position1 to position2.

If position1 is the same position2 then the bit_mask will have length of 1 and the bit position will be the value of position1.

position1 and position2 can be in any order so long as they span the distance from the start and end of the bit_mask range.

Parameters:

position1 – - bit position 1
position2 – - bit position 2

Returns:

consteval bit_mask - bit bit_mask represented by the two bit positions

static inline constexpr bit_mask from(std::uint32_t position)#

Generate, at runtime, a single bit width bit_mask at position.

Parameters:: position – - the bit to make the bit_mask for
Returns:: constexpr bit_mask - bit bit_mask with the position bit set to position

template<std::unsigned_integral T> inline constexpr auto origin() const#

Convert bit_mask to a integral representation but with bit position at 0.

The integral presentation will have 1 bits starting from the position bit up to bit position + width. All other bits will be 0s.

For example:

 value<std::uint16_t>(bit_mask{
     .position = 1,
     .width = 4,
 }); // returns = 0b0000'0000'0000'1111;

Template Parameters:: T – - unsigned integral type to hold the bit_mask
Returns:: constexpr auto - bit_mask value as an unsigned integer

template<std::unsigned_integral T> inline constexpr auto value() const#

Convert mask to a integral representation.

The integral presentation will have 1 bits starting from the position bit up to bit position + width. All other bits will be 0s.

For example:

 value<std::uint16_t>(bit_mask{
     .position = 1,
     .width = 4,
 }); // returns = 0b0000'0000'0001'1110;

Template Parameters:: T – - unsigned integral type to hold the mask
Returns:: constexpr auto - mask value as an unsigned integer

inline constexpr bool operator==(bit_mask const &other)#

Comparison operator between this mask and another.

Parameters:: other – - the other mask to compare against
Returns:: true - the masks are the same
Returns:: false - the masks are not the same

template<bit_mask field> constexpr auto bit_extract(std::unsigned_integral auto p_value)#

Extracts a specific field from an unsigned integral value using a compile time (template) bit mask.

Prefer to use this function over the non-template function if the bit mask can be known at compile time. This will allow the compiler to optimize this bit extract even further.

USAGE:

static constexpr auto peripheral_state = hal::bit_mask::from<4, 9>();
auto state = hal::bit_extract<peripheral_state>(reg->status);
// Proceed to use `state` for something

Template Parameters:: field – - The bit mask defining the position and width of the field to be extracted.
Parameters:: p_value – The unsigned integral value from which the field will be extracted.
Returns:: A value representing only the specified field, with all other bits set to zero.

constexpr auto bit_extract(bit_mask p_field, std::unsigned_integral auto p_value)#

Extracts a specific field from an unsigned integral value using a bit mask.

If the bit mask is known and constant at compile time, use the hal::bit_extract<mask> function as it provides more information to the compiler that it can use to optimize the bit extraction operation.

USAGE:

auto const peripheral_state = hal::bit_mask::from(4, 9);
auto state = hal::bit_extract(peripheral_state, reg->status);
// Proceed to use `state` for something

Parameters:

p_field – - The bit mask defining the position and width of the field to be extracted.
p_value – The unsigned integral value from which the field will be extracted.

Returns:

A value representing only the specified field, with all other bits set to zero.

Variables

static constexpr hal::bit_mask value {.position = bits_per_byte * start_byte,.width = bits_per_byte * (1 + (end_byte - start_byte)),}: Mask value defined at compile time.

template<size_t ByteIndex1, size_t ByteIndex2 = ByteIndex1> constexpr hal::bit_mask byte_m = byte_mask<ByteIndex1, ByteIndex2>::value#

Shorthand for using hal::byte_mask<N>::value.

Template Parameters:

ByteIndex1 – - the byte position to make a mask for
ByteIndex2 – - the byte position to make a mask for

template<std::size_t NibbleIndex1, std::size_t NibbleIndex2 = NibbleIndex1> constexpr hal::bit_mask nibble_m = nibble_mask<NibbleIndex1, NibbleIndex2>::value#

Shorthand for using hal::nibble_mask<N, M>::value.

Template Parameters:

NibbleIndex1 – - starting nibble position
NibbleIndex2 – - ending nibble position

struct bit_mask#

#include <bit.hpp>

Represents a bit mask of contiguous bits.

Public Functions

template<std::unsigned_integral T> inline constexpr auto origin() const#

Convert bit_mask to a integral representation but with bit position at 0.

The integral presentation will have 1 bits starting from the position bit up to bit position + width. All other bits will be 0s.

For example:

 value<std::uint16_t>(bit_mask{
     .position = 1,
     .width = 4,
 }); // returns = 0b0000'0000'0000'1111;

Template Parameters:: T – - unsigned integral type to hold the bit_mask
Returns:: constexpr auto - bit_mask value as an unsigned integer

template<std::unsigned_integral T> inline constexpr auto value() const#

Convert mask to a integral representation.

The integral presentation will have 1 bits starting from the position bit up to bit position + width. All other bits will be 0s.

For example:

 value<std::uint16_t>(bit_mask{
     .position = 1,
     .width = 4,
 }); // returns = 0b0000'0000'0001'1110;

Template Parameters:: T – - unsigned integral type to hold the mask
Returns:: constexpr auto - mask value as an unsigned integer

inline constexpr bool operator==(bit_mask const &other)#

Comparison operator between this mask and another.

Parameters:: other – - the other mask to compare against
Returns:: true - the masks are the same
Returns:: false - the masks are not the same

Public Members

std::uint32_t position#: Where the bit mask starts.

std::uint32_t width#: The number of bits after position contained in the mask.

Public Static Functions

template<std::uint32_t position1, std::uint32_t position2 = position1> static inline consteval bit_mask from()#

Generate, at compile time, a bit_mask that spans the from position1 to position2.

If position1 is the same position2 then the bit_mask will have length of 1 and the bit position will be the value of position1.

position1 and position2 can be in any order so long as they span the distance from the start and end of the bit_mask range.

Use this when you REQUIRE the bit mask to be generated at compile time, because template arguments are required to be known at compile time.

Template Parameters:

position1 – - bit position 1
position2 – - bit position 2

Returns:

consteval bit_mask - bit bit_mask represented by the two bit positions

static inline constexpr bit_mask from(std::uint32_t position1, std::uint32_t position2)#

Generate, at compile time, a bit_mask that spans the from position1 to position2.

If position1 is the same position2 then the bit_mask will have length of 1 and the bit position will be the value of position1.

position1 and position2 can be in any order so long as they span the distance from the start and end of the bit_mask range.

Parameters:

position1 – - bit position 1
position2 – - bit position 2

Returns:

consteval bit_mask - bit bit_mask represented by the two bit positions

static inline constexpr bit_mask from(std::uint32_t position)#

Generate, at runtime, a single bit width bit_mask at position.

Parameters:: position – - the bit to make the bit_mask for
Returns:: constexpr bit_mask - bit bit_mask with the position bit set to position

template<size_t ByteIndex1, size_t ByteIndex2 = ByteIndex1> struct byte_mask#

#include <bit.hpp>

Helper for generating byte position masks.

This type can be used to make a byte mask for a single byte or for multiple bytes.

USAGE:

 // Equivalent to:
 //     hal::bit_mask::from(8, 23)
 //     or
 //     hal::bit_mask{ position = 8, width = 16 }
 auto mask = byte_mask<1, 2>::value;

Note that the order of the mask indexes do not matter. If you order this <2, 1> or <1, 2> you will get the same result which is a mask of bytes from one end to the other.

Template Parameters:

ByteIndex1 – - starting byte position
ByteIndex2 – - ending byte position

Public Static Attributes

static constexpr hal::bit_mask value {.position = bits_per_byte * start_byte,.width = bits_per_byte * (1 + (end_byte - start_byte)),}: Mask value defined at compile time.

template<std::size_t NibbleIndex1, std::size_t NibbleIndex2 = NibbleIndex1> struct nibble_mask#

#include <bit.hpp>

Helper for generating nibble position masks.

This type can be used to make a nibble mask for a single nibble or for multiple nibbles.

USAGE:

 // Equivalent to:
 //     hal::bit_mask::from(4, 12)
 //     or
 //     hal::bit_mask{ position = 4, width = 8 }
 auto mask = nibble_mask<1, 2>::value;

Note that the order of the mask indexes do not matter. If you order this <2, 1> or <1, 2> you will get the same result which is a mask of nibbles from one end to the other.

Template Parameters:

NibbleIndex1 – - starting nibble position
NibbleIndex2 – - ending nibble position

template<std::unsigned_integral T = std::uint32_t> class bit_value#

#include <bit.hpp>

A class for representing a value as a sequence of bits.

This class provides a flexible way to manipulate and work with bit-level values, allowing for efficient and expressive operations on large integers.

This class provides template and non-template options for manipulating bits. If the bitmask is KNOWN at COMPILE TIME, OPT to use the template versions of the APIs as the compiler will have enough information to deduce the bit mask and reduce the set of operations needed to perform the bit manipulation.

USAGE:

static constexpr auto pre_scalar = hal::bit_mask::from<3, 18>();
static constexpr auto enable = hal::bit_mask::from<19>();
hal::bit_value my_value;
my_value.insert<pre_scalar>(120UL)
   .set<enable>();
reg->control = my_value.get();

Template Parameters:: T – - defaults to std::uint32_t, but can be any unsigned integral type.

Public Functions

inline constexpr bit_value(T p_initial_value = 0)#

Constructs a new bit_value instance with an initial value.

Parameters:: p_initial_value – The initial value to use. Defaults to 0.

template<bit_mask field> inline constexpr auto &set()#

Sets (sets to a 1) multiple bits in the represented value.

Template Parameters:: field – A bit_mask type, which represents the position and size of the bit to set.
Returns:: A reference to this instance for method chaining.

inline constexpr auto &set(bit_mask p_field)#

Sets (sets to a 1) multiple bits in the represented value.

Parameters:: p_field – A bit_mask instance, which represents the position and size of the bit to set.
Returns:: A reference to this instance for chaining.

template<bit_mask field> inline constexpr auto &clear()#

Clears (sets to 0) multiple bits in the represented value.

Template Parameters:: field – A bit_mask type, which represents the position and size of the bit to clear.
Returns:: A reference to this instance for chaining.

inline constexpr auto &clear(bit_mask p_field)#

Clears (sets to 0) multiple bits in the represented value.

Parameters:: p_field – A bit_mask instance, which represents the position and size of the bit to clear.
Returns:: A reference to this instance for chaining.

template<bit_mask field> inline constexpr auto &toggle()#

Toggles multiple bits in the represented value.

Template Parameters:: field – A bit_mask type, which represents the position and size of the bit to toggle.
Returns:: A reference to this instance for chaining.

inline constexpr auto &toggle(bit_mask p_field)#

Toggles a single bit in the represented value.

Parameters:: p_field – A bit_mask instance, which represents the position and size of the bit to toggle.
Returns:: A reference to this instance for chaining.

template<bit_mask field> inline constexpr auto &insert(std::unsigned_integral auto p_value)#

Inserts a new value into the represented bit sequence.

Template Parameters:: field – A bit_mask type, which represents the position and size of the bit to insert.
Parameters:: p_value – The new value to insert.
Returns:: A reference to this instance for chaining.

inline constexpr auto &insert(bit_mask p_field, std::unsigned_integral auto p_value)#

Inserts a new value into the represented bit sequence.

Parameters:

p_field – A bit_mask instance, which represents the position and size of the bit to insert.
p_value – The new value to insert.

Returns:

A reference to this instance for chaining.

template<bit_mask p_field, std::unsigned_integral auto p_value> inline constexpr auto &insert()#

Inserts a new value into the represented bit sequence.

Template Parameters:

p_field – A bit_mask instance, which represents the position and size of the bit to insert.
p_value – The new value to insert.

Returns:

A reference to this instance for chaining.

template<std::integral U> inline constexpr auto to()#

Returns the represented value as an instance of U.

Performs truncating static cast if the sizeof(T) > sizeof(U)

Returns:: The represented value as type U.

inline constexpr T get()#

Returns the represented value as a T instance.

Returns:: The represented value.

Public Static Attributes

static constexpr std::uint32_t width = sizeof(T) * CHAR_BIT#

The total number of bits in the represented value.

This is calculated as the product of the size of T and the number of bits per byte (CHAR_BIT).

template<std::unsigned_integral T> class bit_modify : public hal::bit_value<T>#

#include <bit.hpp>

A class for modifying a register value by manipulating its bits.

This class provides a convenient and expressive way to perform bitwise operations on a register value, allowing for efficient and safe modifications without compromising performance.

USAGE:

static constexpr auto pre_scalar = hal::bit_mask::from<3, 18>();
static constexpr auto enable = hal::bit_mask::from<19>();

hal::bit_modify(reg->control)
   .insert<pre_scalar>(120UL)
   .set<enable>();
// At this line, reg->control will be updated

Template Parameters:: T – - defaults to std::uint32_t, but can be any unsigned integral type.

Public Functions

inline constexpr bit_modify(T volatile &p_register_reference)#

Constructs a new bit_modify instance with an initial value and a pointer to the register.

Parameters:: p_register_reference – A reference to the register whose bits will be modified.

inline ~bit_modify()#: On destruction, update the original register’s value with the final modified bits.