bitfield.cxxm

Go to the documentation of this file.

/// SPDX-License-Identifier: Apache-2.0
/// @file bitfield.cxxm
/// @brief C++26 unified field descriptor
 
export module lib.bitfield;
import lib.fixed_string;
import lib.rwonce;
import lib.pack_indexing;
import lib.error;
import zxfoundation.base.types;
import zxfoundation.sys.syschk.barebones;
import lib.stl;
 
#define __zxmacro_want_assert
#include macro_extensions
 
export {
 
using lib::literals::operator""_f;
 
namespace lib {
 
    /// @brief Compile-time bit slice descriptor (record domain).
    /// @tparam Start First bit boundary
    /// @tparam End   Second bit boundary
    template<usize Start, usize End = Start>
    struct bit_slice {
        static constexpr usize start = Start;
        static constexpr usize end = End;
        static constexpr usize min_bit = (Start <= End) ? Start : End;
        static constexpr usize max_bit = (Start <= End) ? End : Start;
        static constexpr usize width = max_bit - min_bit + 1;
    };
 
    template<usize Start, usize End>
    using bit_span = bit_slice<Start, End>;
 
    /// @brief MSB0 bit numbering policy (Bit 0 = Most Significant Bit)
    struct msb0_t {
        [[nodiscard]] static constexpr auto bit_shift(usize total_bits, usize n) noexcept -> usize {
            chk_assert(n < total_bits);
            return total_bits - 1 - n;
        }
 
        [[nodiscard]] static constexpr auto range_shift_width(usize total_bits, usize a,
                                                              usize b) noexcept -> std::pair<usize, usize> {
            const usize min_bit = (a <= b) ? a : b;
            const usize max_bit = (a <= b) ? b : a;
            chk_assert(max_bit < total_bits);
            const usize width = max_bit - min_bit + 1;
            const usize shift = total_bits - 1 - max_bit;
            return {shift, width};
        }
    };
 
    /// @brief LSB0 bit numbering policy (Bit 0 = Least Significant Bit)
    struct lsb0_t {
        [[nodiscard]] static constexpr auto bit_shift(usize, usize n) noexcept -> usize {
            return n;
        }
 
        [[nodiscard]] static constexpr auto range_shift_width(usize total_bits, usize a,
                                                              usize b) noexcept -> std::pair<usize, usize> {
            const usize min_bit = (a <= b) ? a : b;
            const usize max_bit = (a <= b) ? b : a;
            chk_assert(max_bit < total_bits);
            const usize width = max_bit - min_bit + 1;
            const usize shift = min_bit;
            return {shift, width};
        }
    };
 
    inline constexpr msb0_t msb0{};
    inline constexpr lsb0_t lsb0{};
 
    /// @brief Bit-window locator within a byte-addressed unit (structure domain).
    template<usize ByteOffset, usize StartBit, usize EndBit, class Numbering = msb0_t>
    struct slice {
        static constexpr usize byte_offset = ByteOffset;
        static constexpr usize start = StartBit;
        static constexpr usize end = EndBit;
        using numbering = Numbering;
        static constexpr usize min_bit = (StartBit <= EndBit) ? StartBit : EndBit;
        static constexpr usize max_bit = (StartBit <= EndBit) ? EndBit : StartBit;
        static constexpr usize width = max_bit - min_bit + 1;
        /// @brief Exclusive end byte offset physically touched by this window.
        static constexpr usize end_byte = ByteOffset + (max_bit >> 3) + 1;
    };
 
    /// @brief Byte-offset anchor for hierarchical register addressing.
    template<usize Offset>
    struct addr {
        static constexpr usize byte_offset = Offset;
 
        template<usize K>
        using at_byte = addr<Offset + K>;
        template<usize K>
        using at_halfword = addr<Offset + K * 2>;
        template<usize K>
        using at_word = addr<Offset + K * 4>;
        template<usize K>
        using at_dword = addr<Offset + K * 8>;
        template<usize K>
        using at_qword = addr<Offset + K * 16>;
 
        template<usize A, usize B, class Numbering = msb0_t>
        using at_bits = slice<Offset, A, B, Numbering>;
 
        template<usize B, class Numbering = msb0_t>
        using at_bit = slice<Offset, B, B, Numbering>;
    };
 
    /// @name Absolute byte anchors.
    /// @{
    template<usize N>
    using at_byte = addr<N>;
    template<usize N>
    using at_halfword = addr<N * 2>;
    template<usize N>
    using at_word = addr<N * 4>;
    template<usize N>
    using at_dword = addr<N * 8>;
    template<usize N>
    using at_qword = addr<N * 16>;
    /// @}
 
    /// @brief Byte-range locator (structure domain, whole bytes).
    template<usize Start, usize End>
    struct byte_span {
        static constexpr usize start = Start;
        static constexpr usize end = End;
        static constexpr usize min_byte = (Start <= End) ? Start : End;
        static constexpr usize max_byte = (Start <= End) ? End : Start;
        static constexpr usize size = max_byte - min_byte + 1;
    };
 
    /// @brief Strided-array locator (structure domain).
    template<usize Count, usize Stride>
    struct bank {
        static constexpr usize count = Count;
        static constexpr usize stride = Stride;
    };
 
    /// @brief Automatic-layout locator (structure domain).
    struct auto_layout {
    };
 
    namespace endian {
        struct big {
        };
 
        struct little {
        };
 
        struct native {
        };
    }
 
    /// @brief Field attribute tags (the closed modifier set for @c field).
    namespace attr {
        // -- access policy --
        struct rw {
        }; ///< Read-Write
        struct ro {
        }; ///< Read-Only
        struct wo {
        }; ///< Write-Only
        struct w1c {
        }; ///< Write-1-to-Clear
        struct w1s {
        }; ///< Write-1-to-Set
        struct w1t {
        }; ///< Write-1-to-Toggle
        struct w0c {
        }; ///< Write-0-to-Clear
        struct rc {
        }; ///< Read-to-Clear
        struct rz {
        }; ///< Reserved-Zero
        struct raz {
        }; ///< Read-As-Zero
        struct rao {
        }; ///< Read-As-One
        struct wac {
        }; ///< Write-Any-to-Clear
        struct woo {
        }; ///< Write-Once-Only
 
        template<usize A>
        struct aligned {
        }; ///< address = raw << log2(A)
        template<usize S>
        struct shifted_by {
        }; ///< value = raw << S
        struct inverted {
        }; ///< active-low
 
        struct endian_big {
        };
 
        struct endian_little {
        };
 
        struct unaligned {
        };
 
        template<class W>
        struct word {
        }; ///< bus granularity (u8/u16/u32/u64)
        struct overlay {
        }; ///< intentional alias
 
        template<auto V>
        struct init {
            static constexpr auto value = V;
        }; ///< default/reset value
        template<auto V>
        struct fixed {
            static constexpr auto value = V;
        }; ///< architectural constant (always V)
    }
 
    /// @brief Backward-compatible access-tag namespace (aliases of @c attr).
    namespace access {
        using rw = attr::rw;
        using ro = attr::ro;
        using wo = attr::wo;
        using w1c = attr::w1c;
        using w1s = attr::w1s;
        using w1t = attr::w1t;
        using w0c = attr::w0c;
        using rc = attr::rc;
        using rz = attr::rz;
        using raz = attr::raz;
        using rao = attr::rao;
        using wac = attr::wac;
        using woo = attr::woo;
    }
 
    /// @brief Value transformer contract (carries caller bit width).
    template<usize Alignment>
    struct aligned_address {
        static_assert(std::has_single_bit(Alignment), "lib::bitfield: Alignment must be a power of two!");
        static constexpr usize shift = std::countr_zero(Alignment);
 
        template<usize = 0>
        [[nodiscard]] static constexpr auto from_bits(u64 raw_bits) noexcept -> u64 {
            return raw_bits << shift;
        }
 
        template<usize = 0>
        [[nodiscard]] static constexpr auto to_bits(u64 address) noexcept -> u64 {
            chk_assert((address & (Alignment - 1)) == 0 && "Hardware address violates alignment boundary!");
            return address >> shift;
        }
    };
 
    template<usize Shift>
    struct shifted {
        template<usize = 0>
        [[nodiscard]] static constexpr auto from_bits(auto raw_bits) noexcept {
            return raw_bits << Shift;
        }
 
        template<usize = 0>
        [[nodiscard]] static constexpr auto to_bits(auto val) noexcept {
            using V = decltype(val);
            constexpr V low_mask = static_cast<V>((static_cast<V>(1) << Shift) - static_cast<V>(1));
            chk_assert((val & low_mask) == 0 && "lib::bitfield: shifted value violates 2**Shift granularity!");
            return val >> Shift;
        }
    };
 
    struct inverted {
    private:
        template<class T, usize Width>
        [[nodiscard]] static consteval auto field_mask() noexcept -> T {
            if constexpr (Width >= sizeof(T) * 8) return static_cast<T>(~T{0});
            else return static_cast<T>((static_cast<T>(1) << (Width - 1) << 1) - static_cast<T>(1));
        }
 
    public:
        template<usize Width = 0>
        [[nodiscard]] static constexpr auto from_bits(auto raw_bits) noexcept {
            using T = decltype(raw_bits);
            if constexpr (Width == 0) return static_cast<T>(~raw_bits);
            else return static_cast<T>(~raw_bits & field_mask<T, Width>());
        }
 
        template<usize Width = 0>
        [[nodiscard]] static constexpr auto to_bits(auto val) noexcept {
            using T = decltype(val);
            if constexpr (Width == 0) return static_cast<T>(~val);
            else return static_cast<T>(~val & field_mask<T, Width>());
        }
    };
 
    template<template <class> class... Mixins>
    struct extensions {
    };
 
    template<class T>
    struct is_byte_array : std::false_type {
    };
 
    template<usize N>
    struct is_byte_array<std::array<u8, N> > : std::true_type {
    };
 
    /// @brief Exact-width unsigned integer type (compile-time bit width 1..128).
    template<usize Bits>
    struct exact_uint;
 
    template<class T>
    struct is_exact_uint : std::false_type {
    };
 
    template<usize Bits>
    struct is_exact_uint<exact_uint<Bits> > : std::true_type {
    };
 
    template<class T>
    inline constexpr bool is_exact_uint_v = is_exact_uint<std::remove_cvref_t<T> >::value;
 
    namespace detail {
        template<class T>
        concept unsigned_word =
                (std::unsigned_integral<T> && !std::same_as<std::remove_cv_t<T>, bool>)
#if defined(__SIZEOF_INT128__)
                || std::same_as<std::remove_cv_t<T>, u128>
                || std::same_as<std::remove_cv_t<T>, unsigned __int128>
#endif
                ;
 
        template<fixed_string FullPath>
        struct path_split {
            static constexpr usize split_pos = []() consteval -> usize {
                for (usize i = 0; i < FullPath.size(); ++i) {
                    if (FullPath.c_str()[i] == '\\') return i;
                }
                return static_cast<usize>(-1);
            }();
 
            static constexpr bool has_tail = (split_pos != static_cast<usize>(-1));
 
            static constexpr auto head = []() consteval {
                if constexpr (!has_tail) return FullPath;
                else {
                    char buf[split_pos + 1]{};
                    for (usize i = 0; i < split_pos; ++i) buf[i] = FullPath.c_str()[i];
                    buf[split_pos] = '\0';
                    return fixed_string(buf);
                }
            }();
 
            static constexpr auto tail = []() consteval {
                if constexpr (!has_tail) return fixed_string("");
                else {
                    constexpr usize tail_len = FullPath.size() - split_pos - 1;
                    char buf[tail_len + 1]{};
                    for (usize i = 0; i < tail_len; ++i) buf[i] = FullPath.c_str()[split_pos + 1 + i];
                    buf[tail_len] = '\0';
                    return fixed_string(buf);
                }
            }();
        };
 
        template<class T, class... Ts>
        inline constexpr bool is_one_of_v = (std::is_same_v<T, Ts> || ...);
 
        template<class T>
        inline constexpr bool is_access_v = is_one_of_v<T,
            attr::rw, attr::ro, attr::wo, attr::w1c, attr::w1s, attr::w1t, attr::w0c,
            attr::rc, attr::rz, attr::raz, attr::rao, attr::wac, attr::woo>;
 
        template<class T>
        struct is_transform_tag : std::false_type {
        };
 
        template<usize A>
        struct is_transform_tag<attr::aligned<A> > : std::true_type {
        };
 
        template<usize S>
        struct is_transform_tag<attr::shifted_by<S> > : std::true_type {
        };
 
        template<>
        struct is_transform_tag<attr::inverted> : std::true_type {
        };
 
        template<class T>
        inline constexpr bool is_transform_v = is_transform_tag<T>::value;
 
        template<class T>
        struct transform_of {
            using type = void;
        };
 
        template<usize A>
        struct transform_of<attr::aligned<A> > {
            using type = aligned_address<A>;
        };
 
        template<usize S>
        struct transform_of<attr::shifted_by<S> > {
            using type = shifted<S>;
        };
 
        template<>
        struct transform_of<attr::inverted> {
            using type = inverted;
        };
 
        template<class T>
        inline constexpr bool is_endian_v = is_one_of_v<T, attr::endian_big, attr::endian_little>;
 
        template<class T>
        struct is_word_tag : std::false_type {
        };
 
        template<class W>
        struct is_word_tag<attr::word<W> > : std::true_type {
        };
 
        template<class T>
        inline constexpr bool is_word_v = is_word_tag<T>::value;
 
        template<class T>
        struct word_type_of {
            using type = void;
        };
 
        template<class W>
        struct word_type_of<attr::word<W> > {
            using type = W;
        };
 
        template<class T>
        struct is_init_tag : std::false_type {
        };
 
        template<auto V>
        struct is_init_tag<attr::init<V> > : std::true_type {
        };
 
        template<class T>
        inline constexpr bool is_init_v = is_init_tag<T>::value;
 
        template<class T>
        struct is_fixed_tag : std::false_type {
        };
 
        template<auto V>
        struct is_fixed_tag<attr::fixed<V> > : std::true_type {
        };
 
        template<class T>
        inline constexpr bool is_fixed_v = is_fixed_tag<T>::value;
 
        template<class T>
        inline constexpr bool is_overlay_v = std::is_same_v<T, attr::overlay>;
        template<class T>
        inline constexpr bool is_unaligned_v = std::is_same_v<T, attr::unaligned>;
 
        struct none_token {
        };
 
        template<template <class> class Pred, class... Ts>
        struct first_of {
            using type = none_token;
        };
 
        template<template <class> class Pred, class H, class... T>
        struct first_of<Pred, H, T...> {
            using type = std::conditional_t<Pred<H>::value, H, typename first_of<Pred, T...>::type>;
        };
 
        template<class... Attrs>
        struct select_access {
            using type = attr::rw;
        };
 
        template<class H, class... T>
        struct select_access<H, T...> {
            using type = std::conditional_t<is_access_v<H>, H, typename select_access<T...>::type>;
        };
 
        template<class H, bool = is_transform_v<H> >
        struct as_transform {
            using type = void;
        };
 
        template<class H>
        struct as_transform<H, true> {
            using type = typename transform_of<H>::type;
        };
 
        template<class...>
        struct select_transform {
            using type = void;
        };
 
        template<class H, class... T>
        struct select_transform<H, T...> {
            using type = std::conditional_t<
                !std::is_void_v<typename as_transform<H>::type>,
                typename as_transform<H>::type,
                typename select_transform<T...>::type>;
        };
 
        template<class... Attrs>
        struct select_endian {
            using type = endian::native;
        };
 
        template<class H, class... T>
        struct select_endian<H, T...> {
            using type = std::conditional_t<
                std::is_same_v<H, attr::endian_big>,
                endian::big,
                std::conditional_t<
                    std::is_same_v<H, attr::endian_little>,
                    endian::little,
                    typename select_endian<T...>::type> >;
        };
 
        template<class... Attrs>
        struct select_word {
            using type = void;
        };
 
        template<class H, class... T>
        struct select_word<H, T...> {
            using type = std::conditional_t<is_word_v<H>, typename word_type_of<H>::type, typename select_word<T
                ...>::type>;
        };
 
        template<class... Attrs>
        struct select_init_tag {
            using type = none_token;
        };
 
        template<class H, class... T>
        struct select_init_tag<H, T...> {
            using type = std::conditional_t<is_init_v<H>, H, typename select_init_tag<T...>::type>;
        };
 
        template<class... Attrs>
        struct select_fixed_tag {
            using type = none_token;
        };
 
        template<class H, class... T>
        struct select_fixed_tag<H, T...> {
            using type = std::conditional_t<is_fixed_v<H>, H, typename select_fixed_tag<T...>::type>;
        };
 
        template<auto V>
        [[nodiscard]] consteval auto to_raw_bits() noexcept -> u64 {
            using D = decltype(V);
            if constexpr (std::is_enum_v<D>) return static_cast<u64>(static_cast<std::underlying_type_t<D>>(V));
            else if constexpr (std::is_same_v<D, bool>) return V ? 1ULL : 0ULL;
            else return static_cast<u64>(V);
        }
 
        template<class Tag>
        struct raw_tag_bits {
            static constexpr u64 value = 0;
        };
 
        template<auto V>
        struct raw_tag_bits<attr::init<V> > {
            static constexpr u64 value = to_raw_bits<V>();
        };
 
        template<auto V>
        struct raw_tag_bits<attr::fixed<V> > {
            static constexpr u64 value = to_raw_bits<V>();
        };
 
        template<class L>
        struct record_slices {
            using type = std::tuple<>;
        };
 
        template<usize A, usize B>
        struct record_slices<bit_slice<A, B> > {
            using type = std::tuple<bit_slice<A, B> >;
        };
 
        template<class... Ss>
        struct record_slices<std::tuple<Ss...> > {
            using type = std::tuple<Ss...>;
        };
    } // namespace detail
 
    template<class T>
    concept bit_storage =
            detail::unsigned_word<T> ||
            is_byte_array<std::remove_cvref_t<T> >::value ||
            is_exact_uint_v<T>;
 
    template<class T>
    struct storage_traits;
 
    template<detail::unsigned_word T>
    struct storage_traits<T> {
        static constexpr bool is_scalar = true;
        static constexpr usize total_bits = sizeof(T) * 8;
        static constexpr usize byte_size = sizeof(T);
 
        [[nodiscard]] static constexpr auto bitmask(usize count) noexcept -> T {
            if (count >= total_bits) return static_cast<T>(~T{0});
            if (count == 0) return T{0};
            return static_cast<T>((static_cast<T>(1) << (count - 1) << 1) - static_cast<T>(1));
        }
    };
 
    template<usize N>
    struct storage_traits<std::array<u8, N> > {
        static constexpr bool is_scalar = false;
        static constexpr usize total_bits = N * 8;
        static constexpr usize byte_size = N;
 
        [[nodiscard]] static constexpr auto bitmask(usize count) noexcept -> u64 {
            if (count >= 64) return static_cast<u64>(~u64{0});
            if (count == 0) return u64{0};
            return (1ULL << count) - 1ULL;
        }
    };
 
    namespace detail {
        template<unsigned_word T>
        [[nodiscard]] constexpr auto safe_bitmask(usize count, usize total_bits) noexcept -> T {
            if (count >= total_bits) return static_cast<T>(~T{0});
            if (count == 0) return T{0};
            return static_cast<T>((static_cast<T>(1) << (count - 1) << 1) - static_cast<T>(1));
        }
 
        template<std::signed_integral TargetType, usize Width, unsigned_word InT>
        [[nodiscard]] constexpr auto sign_extend(InT val) noexcept -> TargetType {
            constexpr usize in_bits = sizeof(InT) * 8;
            static_assert(Width <= in_bits, "sign_extend: Width exceeds input integer width");
            if constexpr (Width == in_bits) {
                return static_cast<TargetType>(static_cast<std::make_signed_t<InT>>(val));
            } else {
                constexpr usize shift = in_bits - Width;
                return static_cast<TargetType>(static_cast<std::make_signed_t<InT>>(val << shift) >> shift);
            }
        }
 
        template<class Numbering, usize TotalBits>
        [[nodiscard]] constexpr auto get_bit_from_bytes(const u8 *data, usize bit_idx) noexcept -> bool {
            chk_assert(bit_idx < TotalBits);
            const usize byte_idx = bit_idx >> 3;
            const usize bit_in_byte = (std::is_same_v<Numbering, msb0_t>) ? (7 - (bit_idx & 7)) : (bit_idx & 7);
            return ((data[byte_idx] >> bit_in_byte) & 1) != 0;
        }
 
        template<class Numbering, usize TotalBits>
        constexpr auto set_bit_in_bytes(u8 *data, usize bit_idx, bool val) noexcept -> void {
            chk_assert(bit_idx < TotalBits);
            const usize byte_idx = bit_idx >> 3;
            const usize bit_in_byte = (std::is_same_v<Numbering, msb0_t>) ? (7 - (bit_idx & 7)) : (bit_idx & 7);
            const u8 mask = static_cast<u8>(1U << bit_in_byte);
            if (val) data[byte_idx] |= mask;
            else data[byte_idx] &= static_cast<u8>(~mask);
        }
 
        template<unsigned_word OutT, class Numbering, usize TotalBits>
        [[nodiscard]] constexpr auto extract_slice_from_bytes(const u8 *data, usize a, usize b) noexcept -> OutT {
            chk_assert((a <= b ? (b - a + 1) : (a - b + 1)) <= sizeof(OutT) * 8);
            OutT result = 0;
            const usize min_bit = (a <= b) ? a : b;
            const usize width = (a <= b) ? (b - a + 1) : (a - b + 1);
            if constexpr (std::is_same_v<Numbering, msb0_t>) {
                for (usize i = 0; i < width; ++i) {
                    bool bit_val = get_bit_from_bytes<Numbering, TotalBits>(data, min_bit + i);
                    result = static_cast<OutT>((result << 1) | (bit_val ? 1 : 0));
                }
            } else {
                for (usize i = 0; i < width; ++i) {
                    bool bit_val = get_bit_from_bytes<Numbering, TotalBits>(data, min_bit + i);
                    if (bit_val) result = static_cast<OutT>(result | (static_cast<OutT>(1) << i));
                }
            }
            return result;
        }
 
        template<unsigned_word InT, class Numbering, usize TotalBits>
        constexpr auto insert_slice_to_bytes(u8 *data, usize a, usize b, InT val) noexcept -> void {
            const usize min_bit = (a <= b) ? a : b;
            const usize width = (a <= b) ? (b - a + 1) : (a - b + 1);
            chk_assert(width <= sizeof(InT) * 8);
            if constexpr (std::is_same_v<Numbering, msb0_t>) {
                for (usize i = 0; i < width; ++i) {
                    bool bit_val = ((val >> (width - 1 - i)) & 1) != 0;
                    set_bit_in_bytes<Numbering, TotalBits>(data, min_bit + i, bit_val);
                }
            } else {
                for (usize i = 0; i < width; ++i) {
                    bool bit_val = ((val >> i) & 1) != 0;
                    set_bit_in_bytes<Numbering, TotalBits>(data, min_bit + i, bit_val);
                }
            }
        }
 
        template<usize Count>
        consteval auto smallest_uint_for_bits() {
            if constexpr (Count <= 8) return u8{};
            else if constexpr (Count <= 16) return u16{};
            else if constexpr (Count <= 32) return u32{};
            else if constexpr (Count <= 64) return u64{};
            else {
#if defined(__SIZEOF_INT128__)
                static_assert(Count <= 128, "lib::bitfield: width exceeds 128 bits.");
                return u128{};
#else
                static_assert(Count <= 64, "lib::bitfield: width exceeds 64 bits without __int128.");
                return u64{};
#endif
            }
        }
 
        template<usize Count>
        using optimal_uint_t = decltype(smallest_uint_for_bits<Count>());
 
        template<class T>
        struct is_extensions_pack : std::false_type {
        };
 
        template<template <class> class... Ms>
        struct is_extensions_pack<extensions<Ms...> > : std::true_type {
        };
 
        template<class... Ts>
        struct find_extensions {
            using type = std::tuple<>;
        };
 
        template<class Head, class... Tail>
        struct find_extensions<Head, Tail...> {
            using type = std::conditional_t<
                is_extensions_pack<Head>::value,
                Head,
                typename find_extensions<Tail...>::type>;
        };
 
        template<bool HasExt, class... Ts>
        struct filter_extensions_dispatch {
            using type = std::tuple<>;
        };
 
        template<class... Ts>
        struct filter_extensions_dispatch<true, Ts...> {
            using type = typename find_extensions<Ts...>::type;
        };
 
        template<class... Ts>
        struct filter_extensions {
            using type = typename filter_extensions_dispatch<(is_extensions_pack<Ts>::value || ...), Ts...>::type;
        };
 
        template<class FilteredTuple, class... Rest>
        struct filter_fields_impl;
 
        template<class... Collected>
        struct filter_fields_impl<std::tuple<Collected...> > {
            using type = std::tuple<Collected...>;
        };
 
        template<bool IsExt, class Acc, class Head, class... Tail>
        struct filter_fields_step;
 
        template<class... Collected, class Head, class... Tail>
        struct filter_fields_step<true, std::tuple<Collected...>, Head, Tail...> {
            using type = typename filter_fields_impl<std::tuple<Collected...>, Tail...>::type;
        };
 
        template<class... Collected, class Head, class... Tail>
        struct filter_fields_step<false, std::tuple<Collected...>, Head, Tail...> {
            using type = typename filter_fields_impl<std::tuple<Collected..., Head>, Tail...>::type;
        };
 
        template<class Acc, class Head, class... Tail>
        struct filter_fields_impl<Acc, Head, Tail...> {
            using type = typename filter_fields_step<is_extensions_pack<Head>::value, Acc, Head, Tail...>::type;
        };
 
        template<bool AllFields, class... Ts>
        struct filter_fields_dispatch {
            using type = std::tuple<Ts...>;
        };
 
        template<class... Ts>
        struct filter_fields_dispatch<false, Ts...> {
            using type = typename filter_fields_impl<std::tuple<>, Ts...>::type;
        };
 
        template<class... Ts>
        struct filter_fields {
            using type = typename filter_fields_dispatch<(!is_extensions_pack<Ts>::value && ...), Ts...>::type;
        };
 
        template<class ExtensionsHolder, class Derived>
        struct mixin_invoker;
 
        template<template <class> class... Ms, class Derived>
        struct mixin_invoker<extensions<Ms...>, Derived> : public Ms<Derived>... {
        };
 
        template<class Derived>
        struct mixin_invoker<std::tuple<>, Derived> {
        };
 
        /// @brief Duck-typed detection of a bitfield record *value* type.
        template<class T>
        concept record_value_type = requires
        {
            typename std::remove_cvref_t<T>::storage_type;
            typename std::remove_cvref_t<T>::numbering;
            typename std::remove_cvref_t<T>::ref_type;
            typename std::remove_cvref_t<T>::mmio_ref_type;
        } && !requires { typename std::remove_cvref_t<T>::value_record; };
 
        template<class T>
        [[nodiscard]] consteval auto field_type_fits(usize width) noexcept -> bool {
            using C = std::remove_cvref_t<T>;
            if constexpr (std::is_void_v<C>) return true;
            else if constexpr (record_value_type<C>) return width == sizeof(typename C::storage_type) * 8;
            else if constexpr (std::is_same_v<C, bool>) return width == 1;
            else if constexpr (std::is_enum_v<C>) return width <= sizeof(std::underlying_type_t<C>) * 8;
            else if constexpr (std::is_integral_v<C>) return width <= sizeof(C) * 8;
            else if constexpr (requires { C::width; }) return width <= C::width;
            else return true;
        }
    } // namespace detail
 
    /// @brief Exact-width unsigned integer (compile-time bit width 1..128).
    template<usize Bits>
    struct exact_uint {
        static_assert(Bits >= 1 && Bits <= 128,
                      "lib::bitfield: exact_uint width must be within [1, 128].");
        using value_type = detail::optimal_uint_t<Bits>;
        static constexpr usize width = Bits;
 
        constexpr exact_uint() noexcept = default;
 
        constexpr exact_uint(value_type v) noexcept : value(v) {
        }
 
        [[nodiscard]] constexpr operator value_type() const noexcept { return value; }
 
        [[nodiscard]] friend constexpr auto operator==(exact_uint, exact_uint) noexcept -> bool = default;
 
        [[nodiscard]] friend constexpr auto operator<=>(exact_uint, exact_uint) noexcept = default;
 
        value_type value{};
    };
 
    template<usize Bits>
    using uint_c = exact_uint<Bits>;
 
    template<usize Bits>
    struct storage_traits<exact_uint<Bits> > {
        using value_type = typename exact_uint<Bits>::value_type;
        static constexpr bool is_scalar = true;
        static constexpr usize total_bits = Bits;
        static constexpr usize byte_size = sizeof(value_type);
 
        [[nodiscard]] static constexpr auto bitmask(usize count) noexcept -> value_type {
            if (count >= Bits) {
                if constexpr (Bits == sizeof(value_type) * 8) return static_cast<value_type>(~value_type{0});
                else return static_cast<value_type>(
                    (static_cast<value_type>(1) << (Bits - 1) << 1) - static_cast<value_type>(1));
            }
            if (count == 0) return value_type{0};
            return static_cast<value_type>((static_cast<value_type>(1) << (count - 1) << 1) - static_cast<
                                               value_type>(1));
        }
    };
 
    /// @brief Unified field descriptor
    /// @tparam Name    Structural compile-time field name.
    /// @tparam Locator Position descriptor: @c bit_slice for records; @c slice,
    ///                 @c byte_span, @c bank, @c auto_layout, or a @c std::tuple of
    ///                 any of these (disjoint) for structures.
    /// @tparam Type    Value type (void = inferred from storage/width).
    /// @tparam Attr    Modifier tags: access policy, value transform, endianness,
    ///                 alignment, bus granularity, overlay, init<>, fixed<>.
    template<fixed_string Name, class Locator, class Type = void, class... Attr>
    struct field {
        static constexpr auto name = Name;
        using locator = Locator;
        using type = Type;
 
        using access = typename detail::select_access<Attr...>::type;
        using transformer = typename detail::select_transform<Attr...>::type;
        using endian_mode = typename detail::select_endian<Attr...>::type;
        using granularity = typename detail::select_word<Attr...>::type;
 
        using init_tag = typename detail::select_init_tag<Attr...>::type;
        using fixed_tag = typename detail::select_fixed_tag<Attr...>::type;
 
        static constexpr bool is_overlay = (detail::is_overlay_v<Attr> || ...);
        static constexpr bool is_unaligned = (detail::is_unaligned_v<Attr> || ...);
        static constexpr bool has_init = !std::is_same_v<init_tag, detail::none_token>;
        static constexpr bool has_fixed = !std::is_same_v<fixed_tag, detail::none_token>;
 
        static constexpr u64 init_value = detail::raw_tag_bits<init_tag>::value;
        static constexpr u64 fixed_value = detail::raw_tag_bits<fixed_tag>::value;
    };
 
    /// @name Prefab field aliases (generic over locator; variadic extra attrs).
    /// @{
    template<fixed_string N, class L, class T = void, class... Extra>
    using rw = field<N, L, T, attr::rw, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using ro = field<N, L, T, attr::ro, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using wo = field<N, L, T, attr::wo, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using w1c = field<N, L, T, attr::w1c, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using w1s = field<N, L, T, attr::w1s, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using w1t = field<N, L, T, attr::w1t, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using w0c = field<N, L, T, attr::w0c, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using rc = field<N, L, T, attr::rc, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using rz = field<N, L, T, attr::rz, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using raz = field<N, L, T, attr::raz, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using rao = field<N, L, T, attr::rao, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using wac = field<N, L, T, attr::wac, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using woo = field<N, L, T, attr::woo, Extra...>;
 
    template<fixed_string N, class L, class T = void, class... Extra>
    using overlay_rw = field<N, L, T, attr::rw, attr::overlay, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using overlay_ro = field<N, L, T, attr::ro, attr::overlay, Extra...>;
    template<fixed_string N, class L, class T = void, class... Extra>
    using overlay_wo = field<N, L, T, attr::wo, attr::overlay, Extra...>;
 
    template<fixed_string N, class L, usize Aln, class... Extra>
    using aligned_rw = field<N, L, u64, attr::rw, attr::aligned<Aln>, Extra...>;
    template<fixed_string N, class L, usize Aln, class... Extra>
    using aligned_ro = field<N, L, u64, attr::ro, attr::aligned<Aln>, Extra...>;
    template<fixed_string N, class L, usize Aln, class... Extra>
    using aligned_wo = field<N, L, u64, attr::wo, attr::aligned<Aln>, Extra...>;
    /// @}
 
    /// @name Locator shorthands.
    /// @{
    template<usize A, usize B = A>
    using bits = bit_slice<A, B>;
    template<usize S, usize E>
    using bytes = byte_span<S, E>;
    /// @}
 
    namespace detail {
        template<class Tuple>
        struct fold_total_width {
            static constexpr usize value = 0;
        };
 
        template<class... Ss>
        struct fold_total_width<std::tuple<Ss...>> {
            static constexpr usize value = (Ss::width + ...);
        };
 
        template<class Tuple>
        struct fold_min_bit {
            static constexpr usize value = 0;
        };
 
        template<class... Ss>
        struct fold_min_bit<std::tuple<Ss...> > {
            static constexpr usize value = std::min({Ss::min_bit...});
        };
 
        template<class Tuple>
        struct fold_max_bit {
            static constexpr usize value = 0;
        };
 
        template<class... Ss>
        struct fold_max_bit<std::tuple<Ss...> > {
            static constexpr usize value = std::max({Ss::max_bit...});
        };
 
        template<class Field>
        struct record_field_view : Field {
            using slices = typename record_slices<typename Field::locator>::type;
 
            static constexpr usize total_width = fold_total_width<slices>::value;
            static constexpr usize min_bit = fold_min_bit<slices>::value;
            static constexpr usize max_bit = fold_max_bit<slices>::value;
        };
 
        template<class Tuple>
        struct map_record_fields;
 
        template<class... Fs>
        struct map_record_fields<std::tuple<Fs...> > {
            using type = std::tuple<record_field_view<Fs>...>;
        };
    } // namespace detail
 
    template<class T>
    class bit_ref {
    public:
        constexpr bit_ref(T &storage, usize shift) noexcept
            : storage_(&storage), shift_(shift) {
        }
 
        [[nodiscard]] constexpr operator bool() const noexcept {
            return ((*storage_ >> shift_) & T{1}) != T{0};
        }
 
        constexpr auto operator=(bool v) noexcept -> bit_ref & {
            if (v) *storage_ = static_cast<T>(*storage_ | (T{1} << shift_));
            else *storage_ = static_cast<T>(*storage_ & ~(T{1} << shift_));
            return *this;
        }
 
        constexpr auto operator=(const bit_ref &other) noexcept -> bit_ref & {
            return *this = static_cast<bool>(other);
        }
 
        constexpr auto operator&=(bool v) noexcept -> bit_ref & {
            return *this = (static_cast<bool>(*this) && v);
        }
 
        constexpr auto operator|=(bool v) noexcept -> bit_ref & {
            return *this = (static_cast<bool>(*this) || v);
        }
 
        constexpr auto operator^=(bool v) noexcept -> bit_ref & {
            return *this = (static_cast<bool>(*this) ^ v);
        }
 
        [[nodiscard]] constexpr auto operator~() const noexcept -> bool {
            return !static_cast<bool>(*this);
        }
 
        constexpr auto flip() noexcept -> bit_ref & {
            *storage_ = static_cast<T>(*storage_ ^ (T{1} << shift_));
            return *this;
        }
 
    private:
        T *storage_;
        usize shift_;
    };
 
    template<class Numbering, usize TotalBits>
    class byte_bit_ref {
    public:
        constexpr byte_bit_ref(u8 *data, usize bit_idx) noexcept
            : data_(data), bit_idx_(bit_idx) {
        }
 
        [[nodiscard]] constexpr operator bool() const noexcept {
            return detail::get_bit_from_bytes<Numbering, TotalBits>(data_, bit_idx_);
        }
 
        constexpr auto operator=(bool v) noexcept -> byte_bit_ref & {
            detail::set_bit_in_bytes<Numbering, TotalBits>(data_, bit_idx_, v);
            return *this;
        }
 
        constexpr auto operator=(const byte_bit_ref &other) noexcept -> byte_bit_ref & {
            return *this = static_cast<bool>(other);
        }
 
        constexpr auto operator&=(bool v) noexcept -> byte_bit_ref & {
            return *this = (static_cast<bool>(*this) && v);
        }
 
        constexpr auto operator|=(bool v) noexcept -> byte_bit_ref & {
            return *this = (static_cast<bool>(*this) || v);
        }
 
        constexpr auto operator^=(bool v) noexcept -> byte_bit_ref & {
            return *this = (static_cast<bool>(*this) ^ v);
        }
 
        [[nodiscard]] constexpr auto operator~() const noexcept -> bool {
            return !static_cast<bool>(*this);
        }
 
        constexpr auto flip() noexcept -> byte_bit_ref & {
            return *this = !static_cast<bool>(*this);
        }
 
    private:
        u8 *data_;
        usize bit_idx_;
    };
 
    template<bit_storage T, class Numbering = msb0_t>
    class bit_field {
    public:
        using storage_type = T;
        using numbering = Numbering;
        using traits = storage_traits<T>;
        static constexpr usize extent = traits::total_bits;
 
        constexpr bit_field() noexcept = default;
 
        constexpr bit_field(T v) noexcept : value_(v) {
        }
 
        [[nodiscard]] constexpr auto operator[](this auto &&self, usize bit) noexcept {
            chk_assert(bit < extent);
            using SelfType = std::remove_reference_t<decltype(self)>;
            if constexpr (std::is_rvalue_reference_v<decltype(self)> || std::is_const_v<SelfType>) {
                if constexpr (traits::is_scalar) {
                    const usize shift = Numbering::bit_shift(extent, bit);
                    return ((self.value_ >> shift) & T{1}) != T{0};
                } else {
                    return detail::get_bit_from_bytes<Numbering, extent>(self.value_.data(), bit);
                }
            } else {
                if constexpr (traits::is_scalar) {
                    const usize shift = Numbering::bit_shift(extent, bit);
                    return bit_ref<T>(self.value_, shift);
                } else {
                    return byte_bit_ref<Numbering, extent>(self.value_.data(), bit);
                }
            }
        }
 
        template<usize A, usize B, class Transformer = void>
        [[nodiscard]] constexpr auto extract() const noexcept {
            constexpr auto sw = Numbering::range_shift_width(extent, A, B);
            using RawT = detail::optimal_uint_t<sw.second>;
            RawT raw_val{};
            if constexpr (traits::is_scalar) {
                raw_val = static_cast<RawT>((value_ >> sw.first) & traits::bitmask(sw.second));
            } else {
                raw_val = detail::extract_slice_from_bytes<RawT, Numbering, extent>(value_.data(), A, B);
            }
            if constexpr (!std::is_void_v<Transformer>) {
                return Transformer::template from_bits<sw.second>(raw_val);
            } else {
                return raw_val;
            }
        }
 
        template<usize A, usize B, usize Alignment>
        [[nodiscard]] constexpr auto extract_aligned() const noexcept -> u64 {
            return extract<A, B, aligned_address<Alignment> >();
        }
 
        template<usize A, usize B, class Transformer = void, class ValT>
        constexpr auto insert(ValT &&v) noexcept -> bit_field & {
            constexpr auto sw = Numbering::range_shift_width(extent, A, B);
            auto raw_val = [&]() {
                if constexpr (!std::is_void_v<Transformer>) {
                    return Transformer::template to_bits<sw.second>(std::forward<ValT>(v));
                } else {
                    return std::forward<ValT>(v);
                }
            }();
            if constexpr (traits::is_scalar) {
                const T m = traits::bitmask(sw.second);
                value_ = static_cast<T>((value_ & static_cast<T>(~(m << sw.first))) |
                                        static_cast<T>((static_cast<T>(raw_val) & m) << sw.first));
            } else {
                detail::insert_slice_to_bytes<decltype(raw_val), Numbering, extent>(value_.data(), A, B, raw_val);
            }
            return *this;
        }
 
        template<usize A, usize B, usize Alignment>
        constexpr auto insert_aligned(u64 address) noexcept -> bit_field & {
            return insert<A, B, aligned_address<Alignment> >(address);
        }
 
        [[nodiscard]] constexpr auto test(usize bit) const noexcept -> bool { return (*this)[bit]; }
 
        constexpr auto set(usize bit, bool v = true) noexcept -> bit_field & {
            (*this)[bit] = v;
            return *this;
        }
 
        constexpr auto clear(usize bit) noexcept -> bit_field & {
            (*this)[bit] = false;
            return *this;
        }
 
        constexpr auto flip(usize bit) noexcept -> bit_field & {
            (*this)[bit].flip();
            return *this;
        }
 
        [[nodiscard]] constexpr auto try_test(usize bit) const noexcept
            -> std::expected<bool, kernel_error> {
            if (bit >= extent) return std::unexpected(kernel_error::from_generic(generic_error::out_of_range));
            return (*this)[bit];
        }
 
        constexpr auto try_set(usize bit, bool v = true) noexcept
            -> std::expected<void, kernel_error> {
            if (bit >= extent) return std::unexpected(kernel_error::from_generic(generic_error::out_of_range));
            (*this)[bit] = v;
            return {};
        }
 
        constexpr auto try_clear(usize bit) noexcept
            -> std::expected<void, kernel_error> {
            if (bit >= extent) return std::unexpected(kernel_error::from_generic(generic_error::out_of_range));
            (*this)[bit] = false;
            return {};
        }
 
        constexpr auto try_flip(usize bit) noexcept
            -> std::expected<void, kernel_error> {
            if (bit >= extent) return std::unexpected(kernel_error::from_generic(generic_error::out_of_range));
            (*this)[bit].flip();
            return {};
        }
 
        [[nodiscard]] constexpr auto value() const noexcept -> T { return value_; }
        [[nodiscard]] constexpr auto raw() noexcept -> T & { return value_; }
        [[nodiscard]] constexpr auto raw() const noexcept -> const T & { return value_; }
 
        constexpr operator T() const noexcept requires traits::is_scalar {
            return value_;
        }
 
        [[nodiscard]] friend constexpr auto operator==(const bit_field &, const bit_field &) noexcept -> bool
        = default;
 
        [[nodiscard]] friend constexpr auto operator<=>(const bit_field &, const bit_field &) noexcept = default;
 
    private:
        T value_{};
    };
 
    template<bit_storage T, class Numbering = msb0_t>
    class bitfield_ref {
    public:
        using storage_type = T;
        using numbering = Numbering;
        using traits = storage_traits<T>;
        static constexpr usize extent = traits::total_bits;
 
        constexpr explicit bitfield_ref(T &storage) noexcept : ptr_(&storage) {
        }
 
        constexpr explicit bitfield_ref(void *ptr) noexcept : ptr_(static_cast<T *>(ptr)) {
        }
 
        constexpr explicit bitfield_ref(const void *ptr) noexcept : ptr_(
            const_cast<T *>(static_cast<const T *>(ptr))) {
        }
 
        [[nodiscard]] constexpr auto operator[](this auto &&self, usize bit) noexcept {
            chk_assert(bit < extent);
            using SelfType = std::remove_reference_t<decltype(self)>;
            if constexpr (std::is_const_v<SelfType>) {
                if constexpr (traits::is_scalar) {
                    const usize shift = Numbering::bit_shift(extent, bit);
                    return ((*self.ptr_ >> shift) & T{1}) != T{0};
                } else {
                    return detail::get_bit_from_bytes<Numbering, extent>(self.ptr_->data(), bit);
                }
            } else {
                if constexpr (traits::is_scalar) {
                    const usize shift = Numbering::bit_shift(extent, bit);
                    return bit_ref<T>(*self.ptr_, shift);
                } else {
                    return byte_bit_ref<Numbering, extent>(self.ptr_->data(), bit);
                }
            }
        }
 
        template<usize A, usize B, class Transformer = void>
        [[nodiscard]] constexpr auto extract() const noexcept {
            constexpr auto sw = Numbering::range_shift_width(extent, A, B);
            using RawT = detail::optimal_uint_t<sw.second>;
            RawT raw_val{};
            if constexpr (traits::is_scalar) {
                raw_val = static_cast<RawT>((*ptr_ >> sw.first) & traits::bitmask(sw.second));
            } else {
                raw_val = detail::extract_slice_from_bytes<RawT, Numbering, extent>(ptr_->data(), A, B);
            }
            if constexpr (!std::is_void_v<Transformer>) {
                return Transformer::template from_bits<sw.second>(raw_val);
            } else {
                return raw_val;
            }
        }
 
        template<usize A, usize B, usize Alignment>
        [[nodiscard]] constexpr auto extract_aligned() const noexcept -> u64 {
            return extract<A, B, aligned_address<Alignment> >();
        }
 
        template<usize A, usize B, class Transformer = void, class ValT>
        constexpr auto insert(ValT &&v) noexcept -> bitfield_ref & {
            constexpr auto sw = Numbering::range_shift_width(extent, A, B);
            auto raw_val = [&]() {
                if constexpr (!std::is_void_v<Transformer>) {
                    return Transformer::template to_bits<sw.second>(std::forward<ValT>(v));
                } else {
                    return std::forward<ValT>(v);
                }
            }();
            if constexpr (traits::is_scalar) {
                const T m = traits::bitmask(sw.second);
                *ptr_ = static_cast<T>((*ptr_ & static_cast<T>(~(m << sw.first))) |
                                       static_cast<T>((static_cast<T>(raw_val) & m) << sw.first));
            } else {
                detail::insert_slice_to_bytes<decltype(raw_val), Numbering, extent>(ptr_->data(), A, B, raw_val);
            }
            return *this;
        }
 
        template<usize A, usize B, usize Alignment>
        constexpr auto insert_aligned(u64 address) noexcept -> bitfield_ref & {
            return insert<A, B, aligned_address<Alignment> >(address);
        }
 
        [[nodiscard]] constexpr auto test(usize bit) const noexcept -> bool { return (*this)[bit]; }
 
        constexpr auto set(usize bit, bool v = true) noexcept -> bitfield_ref & {
            (*this)[bit] = v;
            return *this;
        }
 
        constexpr auto clear(usize bit) noexcept -> bitfield_ref & {
            (*this)[bit] = false;
            return *this;
        }
 
        [[nodiscard]] constexpr auto try_test(usize bit) const noexcept
            -> std::expected<bool, kernel_error> {
            if (bit >= extent) return std::unexpected(kernel_error::from_generic(generic_error::out_of_range));
            return (*this)[bit];
        }
 
        constexpr auto try_set(usize bit, bool v = true) noexcept
            -> std::expected<void, kernel_error> {
            if (bit >= extent) return std::unexpected(kernel_error::from_generic(generic_error::out_of_range));
            (*this)[bit] = v;
            return {};
        }
 
        constexpr auto try_clear(usize bit) noexcept
            -> std::expected<void, kernel_error> {
            if (bit >= extent) return std::unexpected(kernel_error::from_generic(generic_error::out_of_range));
            (*this)[bit] = false;
            return {};
        }
 
        [[nodiscard]] constexpr auto value() const noexcept -> T { return *ptr_; }
        [[nodiscard]] constexpr auto raw() noexcept -> T & { return *ptr_; }
        [[nodiscard]] constexpr auto raw() const noexcept -> const T & { return *ptr_; }
 
        constexpr operator T() const noexcept requires traits::is_scalar {
            return *ptr_;
        }
 
    private:
        T *ptr_;
    };
 
    namespace detail {
        template<class Tuple>
        struct record_layout_info;
 
        template<class... Fs>
        struct record_layout_info<std::tuple<Fs...> > {
            static constexpr usize count = sizeof...(Fs);
            static constexpr std::array<std::string_view, count> names = {
                std::string_view(Fs::name.c_str(), Fs::name.size())...
            };
 
            template<fixed_string Name>
            static consteval auto index_of() noexcept -> usize {
                constexpr std::string_view target(Name.c_str(), Name.size());
                for (usize i = 0; i < count; ++i) {
                    if (names[i] == target) return i;
                }
                return static_cast<usize>(-1);
            }
        };
 
        template<class Field, class Storage>
        struct resolve_field_type_impl {
            static_assert(detail::field_type_fits<typename Field::type>(Field::total_width),
                          "lib::bitfield: declared field Type is narrower than its bit span (use void for auto-width).")
            ;
            using raw_optimal = optimal_uint_t<Field::total_width>;
            using type = std::conditional_t<
                !std::is_void_v<typename Field::type>,
                typename Field::type,
                std::conditional_t<storage_traits<Storage>::is_scalar, Storage, raw_optimal>
            >;
        };
 
        template<class Field, class Storage>
        using resolve_field_type = typename resolve_field_type_impl<Field, Storage>::type;
 
        template<class Field, class Numbering, class BitFieldT>
        [[nodiscard]] constexpr auto read_field(BitFieldT &bits) noexcept {
            static_assert(!std::is_same_v<typename Field::access, attr::wo>,
                          "lib::bitfield: Illegal read from Write-Only (WO) field.");
 
            constexpr bool is_const_context = std::is_const_v<std::remove_reference_t<BitFieldT> >;
            if constexpr (std::is_same_v<typename Field::access, attr::rc>) {
                static_assert(!is_const_context,
                              "lib::bitfield: Cannot perform Read-to-Clear (RC) on a const record instance!");
            }
 
            using TargetType = resolve_field_type<Field, typename std::remove_cvref_t<BitFieldT>::storage_type>;
 
            if constexpr (Field::has_fixed) {
                return static_cast<TargetType>(Field::fixed_value);
            } else if constexpr (std::is_same_v<typename Field::access, attr::rz> ||
                                 std::is_same_v<typename Field::access, attr::raz>) {
                return TargetType{0};
            } else if constexpr (std::is_same_v<typename Field::access, attr::rao>) {
                return static_cast<TargetType>(storage_traits<TargetType>::bitmask(Field::total_width));
            } else {
                using Slices = typename Field::slices;
                constexpr usize slice_count = std::tuple_size_v<Slices>;
 
                auto extract_val = [&]() {
                    if constexpr (slice_count == 1) {
                        using S = pack_indexing_element_t<0, Slices>;
                        return bits.template extract<S::start, S::end>();
                    } else {
                        using AccumT = optimal_uint_t<Field::total_width>;
                        AccumT accum = 0;
                        auto extract_all = [&]<usize... Is>(std::index_sequence<Is...>) {
                            auto process_slice = [&]<class Sl>(Sl) {
                                constexpr usize width = Sl::width;
                                constexpr usize accum_bits = sizeof(AccumT) * 8;
                                auto part = bits.template extract<Sl::start, Sl::end>();
                                if constexpr (width < accum_bits) {
                                    accum = static_cast<AccumT>(accum << width);
                                }
                                accum = static_cast<AccumT>(accum | static_cast<AccumT>(part));
                            };
                            (process_slice(pack_indexing_element_t<Is, Slices>{}), ...);
                        };
                        extract_all(std::make_index_sequence<slice_count>{});
                        return accum;
                    }
                };
 
                auto raw_val = extract_val();
 
                if constexpr (std::is_same_v<typename Field::access, attr::rc>) {
                    if constexpr (slice_count == 1) {
                        using S = pack_indexing_element_t<0, Slices>;
                        bits.template insert<S::start, S::end>(0);
                    } else {
                        auto clear_all = [&]<usize... Is>(std::index_sequence<Is...>) {
                            ((bits.template insert<pack_indexing_element_t<Is, Slices>::start,
                                pack_indexing_element_t<Is, Slices>::end>(0)), ...);
                        };
                        clear_all(std::make_index_sequence<slice_count>{});
                    }
                }
 
                if constexpr (!std::is_void_v<typename Field::transformer>) {
                    return Field::transformer::template from_bits<Field::total_width>(raw_val);
                } else if constexpr (record_value_type<TargetType>) {
                    using RecStorage = typename TargetType::storage_type;
                    return TargetType{static_cast<RecStorage>(raw_val)};
                } else if constexpr (std::signed_integral<TargetType>) {
                    return detail::sign_extend<TargetType, Field::total_width>(raw_val);
                } else {
                    return static_cast<TargetType>(raw_val);
                }
            }
        }
 
        /// @brief Commit a raw value into a record field's slices (no access policy).
        template<class Field, class Numbering, class BitFieldT, class RawT>
        constexpr auto commit_raw(BitFieldT &bits, RawT raw_val) noexcept -> void {
            using Slices = typename Field::slices;
            constexpr usize slice_count = std::tuple_size_v<Slices>;
            if constexpr (slice_count == 1) {
                using S = pack_indexing_element_t<0, Slices>;
                bits.template insert<S::start, S::end>(raw_val);
            } else {
                auto write_all = [&]<usize... Is>(std::index_sequence<Is...>) {
                    auto process_slice_rev = [&]<class Sl>(Sl) {
                        constexpr usize width = Sl::width;
                        constexpr usize raw_bits = sizeof(RawT) * 8;
                        RawT part_mask = safe_bitmask<RawT>(width, raw_bits);
                        RawT part_val = static_cast<RawT>(raw_val & part_mask);
                        bits.template insert<Sl::start, Sl::end>(part_val);
                        if constexpr (width < raw_bits) {
                            raw_val = static_cast<RawT>(raw_val >> width);
                        }
                    };
                    (process_slice_rev(pack_indexing_element_t<slice_count - 1 - Is, Slices>{}), ...);
                };
                write_all(std::make_index_sequence<slice_count>{});
            }
        }
 
        template<class Field, class Numbering, class BitFieldT, class ValT>
        constexpr auto write_field(BitFieldT &bits, ValT &&val) noexcept -> void {
            static_assert(!std::is_same_v<typename Field::access, attr::ro>,
                          "lib::bitfield: Illegal write to Read-Only (RO) field.");
 
            if constexpr (std::is_same_v<typename Field::access, attr::rz>) {
                chk_assert(val == 0 && "lib::bitfield: Write non-zero to Reserved-Zero (RZ) field!");
            }
 
            using Slices = typename Field::slices;
            constexpr usize slice_count = std::tuple_size_v<Slices>;
 
            auto get_raw_input = [&]() {
                if constexpr (!std::is_void_v<typename Field::transformer>) {
                    return Field::transformer::template to_bits<Field::total_width>(val);
                } else if constexpr (std::is_enum_v<std::remove_cvref_t<ValT> >) {
                    return static_cast<std::underlying_type_t<std::remove_cvref_t<ValT> >>(val);
                } else if constexpr (requires { val.underlying(); }) {
                    return val.underlying();
                } else {
                    return val;
                }
            };
 
            using RawT = optimal_uint_t<Field::total_width>;
            auto raw_val = static_cast<RawT>(get_raw_input());
 
            if constexpr (Field::has_fixed) {
                chk_assert(raw_val == static_cast<RawT>(Field::fixed_value) &&
                    "lib::bitfield: write to architectural constant field must equal its fixed value!");
            } else if constexpr (std::is_same_v<typename Field::access, attr::wac>) {
                raw_val = RawT{0};
            } else if constexpr (std::is_same_v<typename Field::access, attr::woo>) {
                static_assert(slice_count == 1,
                              "lib::bitfield: Write-Once-Only (woo) requires a contiguous field.");
                using S = pack_indexing_element_t<0, Slices>;
                auto cur = bits.template extract<S::start, S::end>();
                chk_assert(
                    cur == 0 &&
                    "lib::bitfield: Write-Once-Only (woo) field already latched (must be written exactly once).");
            } else if constexpr (std::is_same_v<typename Field::access, attr::w1c>) {
                static_assert(slice_count == 1,
                              "lib::bitfield: w1c access requires a contiguous (single-slice) field.");
                using S = pack_indexing_element_t<0, Slices>;
                auto cur = bits.template extract<S::start, S::end>();
                raw_val = static_cast<RawT>(cur & ~raw_val);
            } else if constexpr (std::is_same_v<typename Field::access, attr::w0c>) {
                static_assert(slice_count == 1,
                              "lib::bitfield: w0c access requires a contiguous (single-slice) field.");
                using S = pack_indexing_element_t<0, Slices>;
                auto cur = bits.template extract<S::start, S::end>();
                raw_val = static_cast<RawT>(cur & raw_val);
            } else if constexpr (std::is_same_v<typename Field::access, attr::w1s>) {
                static_assert(slice_count == 1,
                              "lib::bitfield: w1s access requires a contiguous (single-slice) field.");
                using S = pack_indexing_element_t<0, Slices>;
                auto cur = bits.template extract<S::start, S::end>();
                raw_val = static_cast<RawT>(cur | raw_val);
            } else if constexpr (std::is_same_v<typename Field::access, attr::w1t>) {
                static_assert(slice_count == 1,
                              "lib::bitfield: w1t access requires a contiguous (single-slice) field.");
                using S = pack_indexing_element_t<0, Slices>;
                auto cur = bits.template extract<S::start, S::end>();
                raw_val = static_cast<RawT>(cur ^ raw_val);
            }
 
            commit_raw<Field, Numbering>(bits, raw_val);
        }
 
        template<class Field, class Numbering, class BitFieldT>
        constexpr auto apply_default(BitFieldT &bits) noexcept -> void {
            if constexpr (Field::has_fixed || Field::has_init) {
                constexpr u64 c = Field::has_fixed ? Field::fixed_value : Field::init_value;
                using RawT = optimal_uint_t<Field::total_width>;
                commit_raw<Field, Numbering>(bits, static_cast<RawT>(c));
            }
        }
 
        template<class... Fs>
        consteval auto verify_field_overlaps() -> bool {
            constexpr usize N = sizeof...(Fs);
            if constexpr (N <= 1) {
                return true;
            } else {
                struct field_bounds {
                    usize min_bit = 0;
                    usize max_bit = 0;
                    bool is_overlay = false;
                };
                const std::array<field_bounds, N> bounds = {
                    field_bounds{.min_bit = Fs::min_bit, .max_bit = Fs::max_bit, .is_overlay = Fs::is_overlay}...
                };
                for (usize i = 0; i < N; ++i) {
                    if (bounds[i].is_overlay) continue;
                    for (usize j = i + 1; j < N; ++j) {
                        if (bounds[j].is_overlay) continue;
                        const bool overlap = !(
                            bounds[i].max_bit < bounds[j].min_bit || bounds[j].max_bit < bounds[i].min_bit);
                        chk_assert(
                            !overlap &&
                            "lib::record: Accidental bit overlap between fields! Use overlay_rw for intentional aliases.");
                    }
                }
                return true;
            }
        }
    } // namespace detail
 
    template<bit_storage T, class Numbering, class... FieldOrExts>
    class record_ref;
 
    template<rwonce::Word T, class Numbering, class... FieldOrExts>
    class mmio_record_ref;
 
    template<bit_storage T, class Numbering, class... FieldOrExts>
    class record : public detail::mixin_invoker<
                typename detail::filter_extensions<FieldOrExts...>::type,
                record<T, Numbering, FieldOrExts...>
            > {
    private:
        using RawFieldTuple = typename detail::filter_fields<FieldOrExts...>::type;
        using FieldTuple = typename detail::map_record_fields<RawFieldTuple>::type;
        using Layout = detail::record_layout_info<FieldTuple>;
 
        template<class Tuple>
        struct overlap_checker;
 
        template<class... Fs>
        struct overlap_checker<std::tuple<Fs...> > {
            static constexpr bool valid = detail::verify_field_overlaps<Fs...>();
        };
 
        static_assert(overlap_checker<FieldTuple>::valid);
        static_assert(std::tuple_size_v<RawFieldTuple> == std::tuple_size_v<FieldTuple>);
 
    public:
        using storage_type = T;
        using numbering = Numbering;
        static constexpr usize field_count = std::tuple_size_v<FieldTuple>;
        static constexpr usize extent = storage_traits<T>::total_bits;
 
        constexpr record() noexcept : bits_{} {
            apply_defaults();
        }
 
        constexpr record(T v) noexcept : bits_(v) {
        }
 
        template<class... Bindings>
            requires ((requires { Bindings::name; }) && ...)
        constexpr explicit record(Bindings &&... bindings) noexcept : bits_{} {
            (this->template set<Bindings::name>(std::forward<decltype(bindings.value)>(bindings.value)), ...);
        }
 
        template<fixed_string... FieldNames, class... Values>
        [[nodiscard]] static constexpr auto make(Values &&... vals) noexcept -> record {
            static_assert(sizeof...(FieldNames) == sizeof...(Values),
                          "Number of field names must match the number of values!");
            record s{};
            (s.template set<FieldNames>(std::forward<Values>(vals)), ...);
            return s;
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto get() const noexcept {
            constexpr usize exact_idx = Layout::template index_of<Path>();
            if constexpr (exact_idx != static_cast<usize>(-1)) {
                using F = pack_indexing_element_t<exact_idx, FieldTuple>;
                return detail::read_field<F, Numbering>(bits_);
            } else {
                using Split = detail::path_split<Path>;
                constexpr auto head_name = Split::head;
                constexpr usize idx = Layout::template index_of<head_name>();
                static_assert(idx != static_cast<usize>(-1), "record: unknown field identifier");
                using F = pack_indexing_element_t<idx, FieldTuple>;
                auto val = detail::read_field<F, Numbering>(bits_);
                if constexpr (Split::has_tail) {
                    return val.template get<Split::tail>();
                } else {
                    return val;
                }
            }
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto get() noexcept {
            constexpr usize exact_idx = Layout::template index_of<Path>();
            if constexpr (exact_idx != static_cast<usize>(-1)) {
                using F = pack_indexing_element_t<exact_idx, FieldTuple>;
                return detail::read_field<F, Numbering>(bits_);
            } else {
                using Split = detail::path_split<Path>;
                constexpr auto head_name = Split::head;
                constexpr usize idx = Layout::template index_of<head_name>();
                static_assert(idx != static_cast<usize>(-1), "record: unknown field identifier");
                using F = pack_indexing_element_t<idx, FieldTuple>;
                auto val = detail::read_field<F, Numbering>(bits_);
                if constexpr (Split::has_tail) {
                    return val.template get<Split::tail>();
                } else {
                    return val;
                }
            }
        }
 
        template<usize I>
        [[nodiscard]] constexpr auto get() const noexcept {
            static_assert(I < field_count, "record: field index out of bounds");
            using F = pack_indexing_element_t<I, FieldTuple>;
            return detail::read_field<F, Numbering>(bits_);
        }
 
        template<usize I>
        [[nodiscard]] constexpr auto get() noexcept {
            static_assert(I < field_count, "record: field index out of bounds");
            using F = pack_indexing_element_t<I, FieldTuple>;
            return detail::read_field<F, Numbering>(bits_);
        }
 
        template<fixed_string Path, class ValueType>
        constexpr decltype(auto) set(this auto &&self, ValueType &&v) noexcept {
            constexpr usize exact_idx = Layout::template index_of<Path>();
            if constexpr (exact_idx != static_cast<usize>(-1)) {
                using F = pack_indexing_element_t<exact_idx, FieldTuple>;
                detail::write_field<F, Numbering>(self.bits_, std::forward<ValueType>(v));
                return std::forward<decltype(self)>(self);
            } else {
                using Split = detail::path_split<Path>;
                constexpr auto head_name = Split::head;
                constexpr usize idx = Layout::template index_of<head_name>();
                static_assert(idx != static_cast<usize>(-1), "record: unknown field identifier");
                using F = pack_indexing_element_t<idx, FieldTuple>;
                if constexpr (Split::has_tail) {
                    auto sub = detail::read_field<F, Numbering>(self.bits_);
                    sub.template set<Split::tail>(std::forward<ValueType>(v));
                    detail::write_field<F, Numbering>(self.bits_, sub);
                } else {
                    detail::write_field<F, Numbering>(self.bits_, std::forward<ValueType>(v));
                }
                return std::forward<decltype(self)>(self);
            }
        }
 
        template<usize I, class ValueType>
        constexpr decltype(auto) set(this auto &&self, ValueType &&v) noexcept {
            static_assert(I < field_count, "record: field index out of bounds");
            using F = pack_indexing_element_t<I, FieldTuple>;
            detail::write_field<F, Numbering>(self.bits_, std::forward<ValueType>(v));
            return std::forward<decltype(self)>(self);
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto operator[](field_tag<Path>) const noexcept {
            return get<Path>();
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto operator[](field_tag<Path>) noexcept {
            return get<Path>();
        }
 
        [[nodiscard]] constexpr auto underlying() const noexcept -> T { return bits_.value(); }
 
        [[nodiscard]] constexpr operator T() const noexcept requires storage_traits<T>::is_scalar {
            return bits_.value();
        }
 
        [[nodiscard]] constexpr auto bits() noexcept -> bit_field<T, Numbering> & { return bits_; }
        [[nodiscard]] constexpr auto bits() const noexcept -> const bit_field<T, Numbering> & { return bits_; }
 
        using ref_type = record_ref<T, Numbering, FieldOrExts...>;
        using mmio_ref_type = mmio_record_ref<T, Numbering, FieldOrExts...>;
 
        [[nodiscard]] constexpr auto ref() noexcept -> ref_type { return ref_type(bits_.raw()); }
        [[nodiscard]] constexpr auto mmio_ref() noexcept -> mmio_ref_type { return mmio_ref_type(bits_.raw()); }
 
        [[nodiscard]] friend constexpr auto operator==(const record &, const record &) noexcept -> bool = default;
 
        [[nodiscard]] friend constexpr auto operator<=>(const record &, const record &) noexcept = default;
 
    private:
        constexpr void apply_defaults() noexcept {
            apply_defaults_impl(static_cast<FieldTuple *>(nullptr));
        }
 
        template<class... Fs>
        constexpr void apply_defaults_impl(std::tuple<Fs...> *) noexcept {
            (detail::apply_default<Fs, Numbering>(bits_), ...);
        }
 
        bit_field<T, Numbering> bits_{};
    };
 
    template<bit_storage T, class Numbering, class... FieldOrExts>
    class record_ref : public detail::mixin_invoker<
                typename detail::filter_extensions<FieldOrExts...>::type,
                record_ref<T, Numbering, FieldOrExts...>
            > {
    private:
        using RawFieldTuple = typename detail::filter_fields<FieldOrExts...>::type;
        using FieldTuple = typename detail::map_record_fields<RawFieldTuple>::type;
        using Layout = detail::record_layout_info<FieldTuple>;
 
    public:
        using storage_type = T;
        using numbering = Numbering;
        static constexpr usize field_count = std::tuple_size_v<FieldTuple>;
        static constexpr usize extent = storage_traits<T>::total_bits;
 
        constexpr explicit record_ref(T &storage) noexcept : bits_(storage) {
        }
 
        constexpr explicit record_ref(void *ptr) noexcept : bits_(*static_cast<T *>(ptr)) {
        }
 
        constexpr explicit record_ref(const void *ptr) noexcept : bits_(
            *const_cast<T *>(static_cast<const T *>(ptr))) {
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto get() const noexcept {
            constexpr usize exact_idx = Layout::template index_of<Path>();
            if constexpr (exact_idx != static_cast<usize>(-1)) {
                using F = pack_indexing_element_t<exact_idx, FieldTuple>;
                return detail::read_field<F, Numbering>(bits_);
            } else {
                using Split = detail::path_split<Path>;
                constexpr auto head_name = Split::head;
                constexpr usize idx = Layout::template index_of<head_name>();
                static_assert(idx != static_cast<usize>(-1), "record_ref: unknown field identifier");
                using F = pack_indexing_element_t<idx, FieldTuple>;
                auto val = detail::read_field<F, Numbering>(bits_);
                if constexpr (Split::has_tail) {
                    return val.template get<Split::tail>();
                } else {
                    return val;
                }
            }
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto get() noexcept {
            constexpr usize exact_idx = Layout::template index_of<Path>();
            if constexpr (exact_idx != static_cast<usize>(-1)) {
                using F = pack_indexing_element_t<exact_idx, FieldTuple>;
                return detail::read_field<F, Numbering>(bits_);
            } else {
                using Split = detail::path_split<Path>;
                constexpr auto head_name = Split::head;
                constexpr usize idx = Layout::template index_of<head_name>();
                static_assert(idx != static_cast<usize>(-1), "record_ref: unknown field identifier");
                using F = pack_indexing_element_t<idx, FieldTuple>;
                auto val = detail::read_field<F, Numbering>(bits_);
                if constexpr (Split::has_tail) {
                    return val.template get<Split::tail>();
                } else {
                    return val;
                }
            }
        }
 
        template<usize I>
        [[nodiscard]] constexpr auto get() const noexcept {
            static_assert(I < field_count, "record_ref: field index out of bounds");
            using F = pack_indexing_element_t<I, FieldTuple>;
            return detail::read_field<F, Numbering>(bits_);
        }
 
        template<usize I>
        [[nodiscard]] constexpr auto get() noexcept {
            static_assert(I < field_count, "record_ref: field index out of bounds");
            using F = pack_indexing_element_t<I, FieldTuple>;
            return detail::read_field<F, Numbering>(bits_);
        }
 
        template<fixed_string Path, class ValueType>
        constexpr decltype(auto) set(this auto &&self, ValueType &&v) noexcept {
            constexpr usize exact_idx = Layout::template index_of<Path>();
            if constexpr (exact_idx != static_cast<usize>(-1)) {
                using F = pack_indexing_element_t<exact_idx, FieldTuple>;
                detail::write_field<F, Numbering>(self.bits_, std::forward<ValueType>(v));
                return std::forward<decltype(self)>(self);
            } else {
                using Split = detail::path_split<Path>;
                constexpr auto head_name = Split::head;
                constexpr usize idx = Layout::template index_of<head_name>();
                static_assert(idx != static_cast<usize>(-1), "record_ref: unknown field identifier");
                using F = pack_indexing_element_t<idx, FieldTuple>;
                if constexpr (Split::has_tail) {
                    auto sub = detail::read_field<F, Numbering>(self.bits_);
                    sub.template set<Split::tail>(std::forward<ValueType>(v));
                    detail::write_field<F, Numbering>(self.bits_, sub);
                } else {
                    detail::write_field<F, Numbering>(self.bits_, std::forward<ValueType>(v));
                }
                return std::forward<decltype(self)>(self);
            }
        }
 
        template<usize I, class ValueType>
        constexpr decltype(auto) set(this auto &&self, ValueType &&v) noexcept {
            static_assert(I < field_count, "record_ref: field index out of bounds");
            using F = pack_indexing_element_t<I, FieldTuple>;
            detail::write_field<F, Numbering>(self.bits_, std::forward<ValueType>(v));
            return std::forward<decltype(self)>(self);
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto operator[](field_tag<Path>) const noexcept {
            return get<Path>();
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto operator[](field_tag<Path>) noexcept {
            return get<Path>();
        }
 
        [[nodiscard]] constexpr auto underlying() const noexcept -> T { return bits_.value(); }
 
        [[nodiscard]] constexpr operator T() const noexcept requires storage_traits<T>::is_scalar {
            return bits_.value();
        }
 
        [[nodiscard]] constexpr auto bits() noexcept -> bitfield_ref<T, Numbering> & { return bits_; }
        [[nodiscard]] constexpr auto bits() const noexcept -> const bitfield_ref<T, Numbering> & { return bits_; }
 
    private:
        bitfield_ref<T, Numbering> bits_;
    };
 
    template<rwonce::Word T, class Numbering, class... FieldOrExts>
    class mmio_record_ref : public detail::mixin_invoker<
                typename detail::filter_extensions<FieldOrExts...>::type,
                mmio_record_ref<T, Numbering, FieldOrExts...>
            > {
    public:
        using storage_type = T;
        using numbering = Numbering;
        using value_record = record<T, Numbering, FieldOrExts...>;
        static constexpr usize extent = storage_traits<T>::total_bits;
 
        constexpr explicit mmio_record_ref(T &storage) noexcept
            : ptr_(std::addressof(storage)) {
        }
 
        constexpr explicit mmio_record_ref(volatile void *ptr) noexcept
            : ptr_(static_cast<T *>(const_cast<void *>(ptr))) {
        }
 
        [[nodiscard]] constexpr auto load() const noexcept -> value_record {
            return value_record(rwonce::read_once(*ptr_));
        }
 
        constexpr auto store(value_record val) const noexcept -> void {
            rwonce::write_once(*ptr_, val.underlying());
        }
 
        constexpr auto store(T val) const noexcept -> void {
            rwonce::write_once(*ptr_, val);
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto get() const noexcept {
            return load().template get<Path>();
        }
 
        template<fixed_string Path, class ValueType>
        constexpr auto set(ValueType &&v) const noexcept -> void {
            auto r = load();
            r.template set<Path>(std::forward<ValueType>(v));
            store(r);
        }
 
        template<fixed_string Path>
        [[nodiscard]] constexpr auto operator[](field_tag<Path>) const noexcept {
            return get<Path>();
        }
 
        [[nodiscard]] constexpr operator value_record() const noexcept {
            return load();
        }
 
        [[nodiscard]] auto atomic_load(
            std::memory_order order = std::memory_order_seq_cst) const noexcept -> value_record {
            static_assert(std::is_trivially_copyable_v<T>,
                          "lib::bitfield: Storage must be trivially copyable for atomic operations.");
            std::atomic_ref<T> aref(*ptr_);
            return value_record(aref.load(order));
        }
 
        auto atomic_store(value_record val,
                          std::memory_order order = std::memory_order_seq_cst) const noexcept -> void {
            static_assert(std::is_trivially_copyable_v<T>,
                          "lib::bitfield: Storage must be trivially copyable for atomic operations.");
            std::atomic_ref<T> aref(*ptr_);
            aref.store(val.underlying(), order);
        }
 
        auto atomic_compare_exchange(value_record &expected, value_record desired,
                                     std::memory_order success = std::memory_order_seq_cst,
                                     std::memory_order failure = std::memory_order_seq_cst) const noexcept -> bool {
            static_assert(std::is_trivially_copyable_v<T>,
                          "lib::bitfield: Storage must be trivially copyable for atomic operations.");
            std::atomic_ref<T> aref(*ptr_);
            T exp_raw = expected.underlying();
            bool ok = aref.compare_exchange_strong(exp_raw, desired.underlying(), success, failure);
            if (!ok) expected = value_record(exp_raw);
            return ok;
        }
 
        template<fixed_string Path, class ValT>
        auto atomic_set(ValT &&val, std::memory_order order = std::memory_order_seq_cst) const noexcept -> void {
            static_assert(std::is_trivially_copyable_v<T>,
                          "lib::bitfield: Storage must be trivially copyable for atomic operations.");
            std::atomic_ref<T> aref(*ptr_);
            T exp_raw = aref.load(std::memory_order_relaxed);
            value_record desired_rec{};
            do {
                desired_rec = value_record(exp_raw);
                desired_rec.template set<Path>(std::forward<ValT>(val));
            } while (!aref.compare_exchange_weak(exp_raw, desired_rec.underlying(), order,
                                                 std::memory_order_relaxed));
        }
 
        template<fixed_string Path>
        auto atomic_bit_set(std::memory_order order = std::memory_order_seq_cst) const noexcept -> void {
            atomic_set<Path>(true, order);
        }
 
        template<fixed_string Path>
        auto atomic_bit_clear(std::memory_order order = std::memory_order_seq_cst) const noexcept -> void {
            atomic_set<Path>(false, order);
        }
 
        template<fixed_string Path>
        auto atomic_bit_toggle(std::memory_order order = std::memory_order_seq_cst) const noexcept -> void {
            static_assert(std::is_trivially_copyable_v<T>,
                          "lib::bitfield: Storage must be trivially copyable for atomic operations.");
            std::atomic_ref<T> aref(*ptr_);
            T exp_raw = aref.load(std::memory_order_relaxed);
            value_record desired_rec{};
            do {
                desired_rec = value_record(exp_raw);
                bool cur = desired_rec.template get<Path>();
                desired_rec.template set<Path>(!cur);
            } while (!aref.compare_exchange_weak(exp_raw, desired_rec.underlying(), order,
                                                 std::memory_order_relaxed));
        }
 
    private:
        T *ptr_;
    };
 
    template<class RecordT>
    struct record_traits;
 
    template<bit_storage T, class Numbering, class... Fs>
    struct record_traits<record<T, Numbering, Fs...> > {
        using storage_type = T;
        using numbering = Numbering;
        using value_type = record<T, Numbering, Fs...>;
        using ref_type = record_ref<T, Numbering, Fs...>;
        using mmio_ref_type = mmio_record_ref<T, Numbering, Fs...>;
        static constexpr usize total_bits = storage_traits<T>::total_bits;
    };
 
    template<bit_storage T, class Numbering, class... Fs>
    struct record_traits<record_ref<T, Numbering, Fs...> > {
        using storage_type = T;
        using numbering = Numbering;
        using value_type = record<T, Numbering, Fs...>;
        using ref_type = record_ref<T, Numbering, Fs...>;
        using mmio_ref_type = mmio_record_ref<T, Numbering, Fs...>;
        static constexpr usize total_bits = storage_traits<T>::total_bits;
    };
 
    template<rwonce::Word T, class Numbering, class... Fs>
    struct record_traits<mmio_record_ref<T, Numbering, Fs...> > {
        using storage_type = T;
        using numbering = Numbering;
        using value_type = record<T, Numbering, Fs...>;
        using ref_type = record_ref<T, Numbering, Fs...>;
        using mmio_ref_type = mmio_record_ref<T, Numbering, Fs...>;
        static constexpr usize total_bits = storage_traits<T>::total_bits;
    };
 
    template<class RecordT>
    using record_as_ref_t = typename record_traits<RecordT>::ref_type;
 
    template<class RecordT>
    using record_as_mmio_ref_t = typename record_traits<RecordT>::mmio_ref_type;
 
    using bf8 = bit_field<u8, msb0_t>;
    using bf16 = bit_field<u16, msb0_t>;
    using bf32 = bit_field<u32, msb0_t>;
    using bf64 = bit_field<u64, msb0_t>;
#if defined(__SIZEOF_INT128__)
    using bf128 = bit_field<u128, msb0_t>;
    using bf128_ref = bitfield_ref<u128, msb0_t>;
#else
    using bf128 = bit_field<std::array<u8, 16>, msb0_t>;
    using bf128_ref = bitfield_ref<std::array<u8, 16>, msb0_t>;
#endif
    using bf8_ref = bitfield_ref<u8, msb0_t>;
    using bf16_ref = bitfield_ref<u16, msb0_t>;
    using bf32_ref = bitfield_ref<u32, msb0_t>;
    using bf64_ref = bitfield_ref<u64, msb0_t>;
 
    using lf8 = bit_field<u8, lsb0_t>;
    using lf16 = bit_field<u16, lsb0_t>;
    using lf32 = bit_field<u32, lsb0_t>;
    using lf64 = bit_field<u64, lsb0_t>;
#if defined(__SIZEOF_INT128__)
    using lf128 = bit_field<u128, lsb0_t>;
    using lf128_ref = bitfield_ref<u128, lsb0_t>;
#else
    using lf128 = bit_field<std::array<u8, 16>, msb0_t>;
    using lf128_ref = bitfield_ref<std::array<u8, 16>, lsb0_t>;
#endif
    using lf8_ref = bitfield_ref<u8, lsb0_t>;
    using lf16_ref = bitfield_ref<u16, lsb0_t>;
    using lf32_ref = bitfield_ref<u32, lsb0_t>;
    using lf64_ref = bitfield_ref<u64, lsb0_t>;
 
    // Compile-time self-checks.
    static_assert(at_byte<0>::byte_offset == 0);
    static_assert(at_halfword<3>::byte_offset == 6);
    static_assert(at_word<2>::byte_offset == 8);
    static_assert(at_dword<2>::byte_offset == 16);
    static_assert(at_qword<1>::byte_offset == 16);
    static_assert(at_dword<2>::at_byte<3>::byte_offset == 19);
    static_assert(at_dword<2>::at_byte<3>::at_bits<8, 15>::byte_offset == 19);
    static_assert(at_dword<2>::at_byte<3>::at_bits<8, 15>::width == 8);
    static_assert(at_dword<2>::at_byte<3>::at_bits<8, 15>::end_byte == 21);
    static_assert(slice<1, 0, 23>::end_byte == 4);
    static_assert(slice<1, 0, 23>::width == 24);
    static_assert(exact_uint<96>::width == 96);
    static_assert(storage_traits<exact_uint<96> >::total_bits == 96);
    static_assert(sizeof(exact_uint<24>::value_type) == 4);
    static_assert(storage_traits<exact_uint<24> >::bitmask(24) == 0x00FF'FFFFu);
    static_assert(std::is_same_v<field<"a", bit_slice<0, 0>, void>::access, attr::rw>);
    static_assert(std::is_same_v<field<"a", bit_slice<0, 0>, void, attr::ro>::access, attr::ro>);
    static_assert(field<"a", bit_slice<0, 0>, void, attr::fixed<1> >::fixed_value == 1);
    static_assert(field<"a", bit_slice<0, 3>, void, attr::init<5> >::init_value == 5);
 
} // namespace lib
 
template<class T, class Numbering, class... FieldOrExts>
struct std::tuple_size<lib::record<T, Numbering, FieldOrExts...> >
        : std::integral_constant<usize, lib::record<T, Numbering, FieldOrExts...>::field_count> {
};
 
template<usize I, class T, class Numbering, class... FieldOrExts>
struct std::tuple_element<I, lib::record<T, Numbering, FieldOrExts...> > {
private:
    using RawFieldTuple = typename lib::detail::filter_fields<FieldOrExts...>::type;
    using FieldTuple = typename lib::detail::map_record_fields<RawFieldTuple>::type;
    using Field = lib::pack_indexing_element_t<I, FieldTuple>;
 
public:
    using type = lib::detail::resolve_field_type<Field, T>;
};
 
} // export