Skip to content

Conversation

@nwf
Copy link
Member

@nwf nwf commented Jul 21, 2025

Introduce a Bitpack class, representing a packed bit-field within an unsigned integral type. Bitpacks are intended for use instead of C++ bit-fields or manual bit twiddling and should...

  • not have any undefined or implementation-defined behavior or layout (besides endianness); Field definitions are interpreted as one might expect using <<, |, &, and ~ (see Bitpack<>::Field<>::raw_view and raw_with for the core of all this C++ syntax);

  • readily serve as superclasses for classes fronting particular hardware control registers or other bit-packed types;

  • work in constexpr context and in volatile-qualified forms;

  • be reasonably ergonomic to use in as many contexts as possible.

The fundamental perspective is one of Field::View proxies to contiguous spans of bits within a Bitpack<T>'s underlying storage T. Said spans are defined using FieldInfo structures. Field proxies to fields of type F and with FieldInfo I may be explicitly constructed with .view<F, I>(), but there is also some convenience machinery for defining Bitpacks as products of differently-typed fields, such that a proxy to a given field with type F can be accessed uniformly as .view<F>() (where, effectively, the FieldInfo I is computed from F).

There are also some gross C-preprocessor macros that aim to de-clutter use of Bitpacks, especially in combination with enum classes.

The raw implementation is in sdk/include/bitpacks.hh and a small smattering of tests (mostly checking operation in combination with constexpr and volatile) and demonstration of use is available in tests/bitpacks-test.cc. It is probably sensible to review the two in parallel, as the implementation is probably confusing without examples of use, and the use is probably confusing without some understanding of the implementation.

This is still a little bit of an experiment and a request for comments / opinions, so please, fire away!

@nwf nwf force-pushed the nwf/202507-bitpacks branch 2 times, most recently from ba5da3b to 5f1210b Compare July 28, 2025 22:19
@nwf nwf force-pushed the nwf/202507-bitpacks branch from 5f1210b to d25c840 Compare August 5, 2025 18:11
@nwf
Copy link
Member Author

nwf commented Aug 5, 2025

Updates from continued use in anger.

  • Fetch a slightly newer version of __macro_map.h and document its provenance a little better (a separate commit in front of the main one).
  • Various bug fixes here and there as things have cropped up.
  • Simplification (!) of some of the type-level machinery.
  • .field renamed to .view to be more honest in what was being returned. Field::View objects can get back to their enclosing Field with ::Field.
  • Tests now show an additional pair of different possible approaches to Bitpack use: types within and without the Bitpack-based class.
  • Expanded C preprocessor terror for working with both "unqualified" (native) C++ values and "qualified" values that get decltype(the_bitpack):: shoved in front. See especially BITPACK_QUALIFY and its users.
  • Introduce BITPACK_MASKED_OP to make implicitly masked queries of Bitpack values.

Surely more work to be done and things to shake out, but this might be moving towards reasonable. Certainly moreso than enum_utils.hh-based approaches, IMHO.

@nwf nwf force-pushed the nwf/202507-bitpacks branch 4 times, most recently from 80bbdfc to 0bdf5d5 Compare August 6, 2025 18:32
@nwf nwf force-pushed the nwf/202507-bitpacks branch from 0bdf5d5 to f481dc0 Compare August 18, 2025 21:32
@nwf
Copy link
Member Author

nwf commented Aug 18, 2025

Further use in anger has generated...

  • BITPACK_QVAL_ASSIGN, BITPACK_UVAL_ASSIGN use-side macros,
  • replacing BITPACK_ENUM_EQUAL with BITPACK_ENUM_OP, and similar for ENUM_QTYPE_EQUAL and ENUM_UTYPE_EQUAL.
  • BITPACK_USUAL_PREFIX, BITPACK_DEFINE_TYPE_ENUM_CLASS, and BITPACK_DEFINE_TYPE_NUMERIC definition-side macros.

@nwf nwf force-pushed the nwf/202507-bitpacks branch 7 times, most recently from e7241c9 to aeb591a Compare October 24, 2025 21:11
@nwf nwf force-pushed the nwf/202507-bitpacks branch from aeb591a to 0f48ee0 Compare December 30, 2025 04:35
@nwf
Copy link
Member Author

nwf commented Dec 30, 2025

Some further work from use in anger. Notably, adds TQTYPE helpers for using dependently-typed bitpacks, the BITPACK_NUMERIC_..._VALUE macros, and some additional .raw() accessors to elide some static_cast<>s in user code.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants