Bit#
Defined in namespace hal
#include <libhal-util/bit.hpp>
- group Bit
Functions
-
template<std::uint32_t position1, std::uint32_t position2>
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<std::uint32_t position>
static inline consteval bit_mask from()# Generate, at compile time, a single bit width bit_mask at position.
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.
-
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.
-
static inline constexpr bit_mask from(std::uint32_t position)#
Generate, at runtime, a single bit width bit_mask at 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<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 = ByteIndex, .width = 8 }
Mask value defined at compile time.
-
template<size_t ByteIndex>
constexpr hal::bit_mask byte_m = byte_mask<ByteIndex>::value# Shorthand for using hal::byte_mask<N>::value.
- Template Parameters:
ByteIndex – - the byte position to make a mask for
-
template<size_t NibbleIndex>
constexpr hal::bit_mask nibble_m = nibble_mask<NibbleIndex>::value# Shorthand for using hal::nibble_mask<N>::value.
- Template Parameters:
NibbleIndex – - the nibble position to make a mask for
-
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<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
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>
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<std::uint32_t position>
static inline consteval bit_mask from()# Generate, at compile time, a single bit width bit_mask at position.
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.
-
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.
-
template<std::unsigned_integral T>
-
template<size_t ByteIndex>
struct byte_mask# - #include <bit.hpp>
Helper for generating byte position masks.
- Template Parameters:
ByteIndex – - the byte position to make a mask for
Public Static Attributes
- static constexpr hal::bit_mask value = { .position = ByteIndex, .width = 8 }
Mask value defined at compile time.
-
template<size_t NibbleIndex>
struct nibble_mask# - #include <bit.hpp>
Helper for generating nibble position masks.
A nibble is considered 4 bits or half a byte’s width in bits.
- Template Parameters:
NibbleIndex – - the nibble position to make a mask for
-
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.
-
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.
-
template<std::uint32_t position1, std::uint32_t position2>