spmi_hwreg/

common.rs

// Copyright 2026 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

use zerocopy::{FromBytes, FromZeros, Immutable, IntoBytes};

/// Trait for types that can represent a register's value.
///
/// It is implemented by the `Value` structs generated by the
/// `spmi_register!` macro, bounding it by Sized, FromBytes, IntoBytes,
/// FromZeros, and Immutable for safe memory casting.
pub trait RegisterValue: Sized + FromBytes + IntoBytes + FromZeros + Immutable {}

/// Trait implemented by register blocks to provide metadata like address unit size.
pub trait RegisterBlock {
    /// The size in bytes of an address unit for this register block.
    /// Defaults to 1 (byte-addressed).
    const ADDRESS_UNIT_BYTES: u16 = 1;
}

/// Helper function to retrieve `ADDRESS_UNIT_BYTES` for a register block as a `const fn`.
#[doc(hidden)]
#[inline(always)]
pub const fn block_address_unit_bytes<B: RegisterBlock>(_: &B) -> u16 {
    B::ADDRESS_UNIT_BYTES
}

/// Base trait implemented by register definitions providing device-independent metadata.
pub trait SpmiRegisterDef {
    /// The type representing the value of this register.
    type Value: RegisterValue;

    /// The typestate access mode marker for this register.
    type Mode;

    /// The address of this register.
    const ADDRESS: u16;
}

/// Trait implemented by register definitions to provide type-safe access.
///
/// `D` is the device type (e.g., `DeviceType` or custom wrapper implementing [`SpmiDevice`]).
pub trait SpmiRegister<D>: SpmiRegisterDef {
    /// The type representing the accessor for this register.
    type Accessor<'a>
    where
        Self: 'a,
        D: 'a;

    /// Constructs the accessor for this register.
    fn get_accessor<'a>(spmi: &'a D) -> Self::Accessor<'a>;
}

/// Helper function that triggers the compile-time contiguity assertion.
#[doc(hidden)]
#[inline(always)]
pub const fn assert_contiguous<B, R1, R2>(_: &B)
where
    B: RegisterBlock,
    R1: SpmiRegisterDef,
    R2: SpmiRegisterDef,
{
    struct ContiguityCheck<B, R1, R2>(std::marker::PhantomData<(B, R1, R2)>);

    impl<B, R1, R2> ContiguityCheck<B, R1, R2>
    where
        B: RegisterBlock,
        R1: SpmiRegisterDef,
        R2: SpmiRegisterDef,
    {
        const ASSERT: () = {
            let unit = B::ADDRESS_UNIT_BYTES as u32;
            let val_size = std::mem::size_of::<R1::Value>() as u32;
            let r1_addr = R1::ADDRESS as u32;
            let r2_addr = R2::ADDRESS as u32;
            let step = (val_size + unit - 1) / unit;
            assert!(r2_addr == r1_addr + step, "Registers are not contiguous");
        };
    }

    let _ = ContiguityCheck::<B, R1, R2>::ASSERT;
}

// --- Typestate Access Modes ---
// These markers are used to enforce register access rules
// (Read-Only, Write-Only, Read-Write) at compile time using
// the typestate pattern.

/// Marker struct representing Read-Only register access.
pub struct ReadOnly;

/// Marker struct representing Write-Only register access.
pub struct WriteOnly;

/// Marker struct representing Read-Write register access.
pub struct ReadWrite;

/// Trait implemented by access modes that allow reading.
///
/// This is used as a generic bound on `Register::read` to prevent compile-time
/// errors when attempting to read from write-only registers.
pub trait Readable {}
impl Readable for ReadOnly {}
impl Readable for ReadWrite {}

/// Trait implemented by access modes that allow writing.
///
/// This is used as a generic bound on `Register::write` to prevent compile-time
/// errors when attempting to write to read-only registers.
pub trait Writable {}
impl Writable for WriteOnly {}
impl Writable for ReadWrite {}

/// A generic register accessor.
///
/// This struct provides type-safe access to a specific hardware register.
/// It is parameterized by:
/// * `T` - The typed `RegisterValue` (usually the generated `Value` struct).
/// * `M` - The access mode (`ReadOnly`, `WriteOnly`, or `ReadWrite`).
/// * `D` - The underlying device implementation (implements `SpmiDevice`).
/// * `ADDR` - The constant hardware address of the register.
pub struct _Register<'a, T, M, D, const ADDR: u16> {
    /// The underlying SPMI device.
    pub spmi: &'a D,
    _marker: std::marker::PhantomData<(T, M)>,
}

impl<'a, T, M, D, const ADDR: u16> _Register<'a, T, M, D, ADDR> {
    /// Creates a new register accessor.
    pub fn new(spmi: &'a D) -> Self {
        Self { spmi, _marker: std::marker::PhantomData }
    }
}

// Inherent read method available ONLY if M is Readable and D is SpmiDevice
impl<'a, T, M, D, const ADDR: u16> _Register<'a, T, M, D, ADDR>
where
    M: Readable,
    T: RegisterValue,
    D: SpmiDevice,
{
    /// Reads the register value from the hardware.
    ///
    /// This method performs an asynchronous read operation on the underlying
    /// SPMI device and deserializes the raw bytes into the typed value `T`.
    pub async fn read(&self) -> Result<T, crate::Error> {
        let size = std::mem::size_of::<T>();
        let bytes = self.spmi.read_reg(ADDR, size as u32).await?;
        T::read_from_bytes(&bytes).map_err(|_| crate::Error::SizeMismatch)
    }
}

// Inherent write method available ONLY if M is Writable and D is SpmiDevice
impl<'a, T, M, D, const ADDR: u16> _Register<'a, T, M, D, ADDR>
where
    M: Writable,
    T: RegisterValue,
    D: SpmiDevice,
{
    /// Writes the register value to the hardware.
    ///
    /// This method serializes the typed value `T` into raw bytes and performs
    /// an asynchronous write operation on the underlying SPMI device.
    pub async fn write(&self, val: T) -> Result<(), crate::Error> {
        let bytes = val.as_bytes();
        self.spmi.write_reg(ADDR, bytes).await?;
        Ok(())
    }
}

/// Defines a module for accessing a single SPMI hardware register.
///
/// This macro generates a public module named `$name` containing:
/// -   `ADDRESS`: A `u16` constant for the register address.
/// -   `Value`: A struct wrapping the raw register value (`$value_type`)
///     and providing const-fn accessors for defined fields.
/// -   `Register<'a>`: A struct with an asynchronous `read` and
///     potentially `write` method to interact with the SPMI device.
///
/// # Arguments
///
/// 1.  `$name`: The identifier for the generated module.
/// 2.  `$value_type:ty`: The Rust integer type representing the register's
///     width (e.g., `u8`, `u16`, `u32`).
/// 3.  `$addr:expr`: The base address of the register as a `u16`.
/// 4.  `$mode:ident`: The access mode, one of `RO` (Read Only), `WO` (Write
///     Only), or `RW` (Read/Write).
/// 5.  `$endianness:ident`: The endianness of the register. Required for `u16`
///     and larger. Can be `LE` (Little Endian) or `BE` (Big Endian). For `u8`
///     registers, this argument is omitted because endianness is irrelevant
///     for `u8` registers.
/// 6.  `{ ... }`: A block defining the fields within the register. Each
///     field definition ends with a semicolon. The following formats are
///     supported within the block:
///     *   **Single-bit field:** `$vis $field_name $(, $setter_name)? : $bit;`
///         -   `$vis`: Visibility (e.g., `pub`).
///         -   `$field_name`: The name of the getter method (returns `bool`).
///         -   `$setter_name`: (Optional) The name of the setter method
///             (takes `bool`, returns `Self`).
///         -   `$bit_index`: The index of the single bit (e.g., `7`).
///         Example: `pub enable, set_enable: 7;`
///
///     *   **Multi-bit field:** `$vis $field_name $(, $setter_name)? \
///         : $msb, $lsb;`
///         -   `$vis`: Visibility.
///         -   `$field_name`: The getter method (returns `$value_type`).
///         -   `$setter_name`: (Optional) The setter method (takes
///             `$value_type`, returns `Self`).
///         -   `$msb`: The Most Significant Bit index.
///         -   `$lsb`: The Least Significant Bit index.
///         Example: `pub field_val, set_field_val: 5, 2;`
///
///     *   **Enum field (external type):** `$vis enum $enum_type, $field_name \
///         $(, $setter_name)? : $msb, $lsb;`
///         -   `$vis`: Visibility.
///         -   `$enum_type`: The path to an existing enum type (e.g.,
///             `super::PowerMode`). This enum must have a `pub const fn \
///             from_val(val: $value_type) -> Self` associated function.
///         -   `$field_name`: The getter method (returns `$enum_type`).
///         -   `$setter_name`: (Optional) The setter method (takes
///             `$enum_type`, returns `Self`).
///         -   `$msb`, `$lsb`: The bit range.
///         Example: `pub enum super::PowerMode, mode, set_mode: 3, 2;`
///
///     *   **In-line Enum field:** `$vis enum $enum_name { ... }, $field_name \
///         $(, $setter_name)? : $msb, $lsb;`
///         -   `$vis`: Visibility.
///         -   `$enum_name`: The name for the enum type, defined within
///             the generated module.
///         -   `{ ... }`: The enum variants and their `$value_type` values.
///         -   `$field_name`: The getter method (returns `Result<$enum_name, \
///             $value_type>`).
///         -   `$setter_name`: (Optional) The setter method (takes
///             `$enum_name`, returns `Self`).
///         -   `$msb`, `$lsb`: The bit range.
///         Example: `pub enum InlineMode { A = 0, B = 1 }, \
///             mode, set_mode: 1, 0;`
///
///     *   **Custom constant:** `pub const $const_name : $type = $val;`
///         -   Allows defining constants within the generated register module.
///         Example: `pub const MAX_VALUE: u8 = 0xFF;`
///
/// # Examples
///
/// ```
/// // Define a register at address 0x10, 8-bit, Read/Write,
/// // Little Endian (default)
/// spmi_register! {
///     my_reg, u8, 0x10, RW, {
///         // Single bit flag
///         pub enable, set_enable: 7;
///         // 4-bit field
///         pub value, set_value: 3, 0;
///         // Inline enum field
///         pub enum Status {
///             Idle = 0,
///             Active = 1,
///             Error = 2,
///         }, status, set_status: 6, 5;
///     }
/// }
///
/// // Define a register at address 0x20, 16-bit, Read Only, Big Endian
/// spmi_register! {
///     status_be_reg, u16, 0x20, RO, BE, {
///         pub error_code: 15, 8;
///         pub ready: 0;
///     }
/// }
/// ```
#[macro_export]
macro_rules! spmi_register {
    // Helper to map mode to marker types
    (@mode_type RO) => { $crate::ReadOnly };
    (@mode_type WO) => { $crate::WriteOnly };
    (@mode_type RW) => { $crate::ReadWrite };

    // Explicit-endian byteorder helpers inside macro
    (@byteorder_type u8, $endianness:ident) => { u8 };
    (@byteorder_type u16, LE) => { $crate::U16<$crate::LittleEndian> };
    (@byteorder_type u16, BE) => { $crate::U16<$crate::BigEndian> };
    (@byteorder_type u32, LE) => { $crate::U32<$crate::LittleEndian> };
    (@byteorder_type u32, BE) => { $crate::U32<$crate::BigEndian> };

    (@new u8, $endianness:ident, $val:expr) => { Self($val) };
    (@new u16, $endianness:ident, $val:expr) => {
        Self($crate::U16::new($val))
    };
    (@new u32, $endianness:ident, $val:expr) => {
        Self($crate::U32::new($val))
    };

    (@get u8, $endianness:ident, $val:expr) => { $val };
    (@get u16, $endianness:ident, $val:expr) => { $val.get() };
    (@get u32, $endianness:ident, $val:expr) => { $val.get() };

    // Explicit endianness provided via single arm
    (
        $name:ident,
        $value_type:ident,
        $addr:expr,
        $mode:ident,
        $endianness:ident,
        {
            $($tail:tt)*
        }
    ) => {
        #[allow(unused_imports)]
        #[allow(dead_code)]
        pub mod $name {
            use super::*;
            use $crate::zerocopy_reexport as zerocopy;

            /// The address of the register.
            pub const ADDRESS: u16 = $addr;

            $crate::spmi_register_extract_enums!($value_type, $($tail)*);

            /// Represents the value of the register.
            #[derive(
                Copy,
                Clone,
                Debug,
                PartialEq,
                Eq,
                zerocopy::FromBytes,
                zerocopy::IntoBytes,
                zerocopy::Immutable,
            )]
            #[repr(transparent)]
            pub struct Value(
                pub spmi_register!(@byteorder_type $value_type, $endianness),
            );

            impl Value {
                pub const fn new(val: $value_type) -> Self {
                    spmi_register!(@new $value_type, $endianness, val)
                }
                pub const fn reg_value(&self) -> $value_type {
                    spmi_register!(@get $value_type, $endianness, self.0)
                }

                /// Reconstructs a typed `Value` from a slice of raw bytes.
                pub fn from_bytes(bytes: &[u8]) -> Result<Self, $crate::Error> {
                    zerocopy::FromBytes::read_from_bytes(bytes)
                        .map_err(|_| $crate::Error::SizeMismatch)
                }

                /// Converts the `Value` into its raw byte representation.
                pub fn to_bytes(
                    &self,
                ) -> [u8; std::mem::size_of::<$value_type>()] {
                    let mut arr = [0u8; std::mem::size_of::<$value_type>()];
                    arr.copy_from_slice($crate::IntoBytes::as_bytes(self));
                    arr
                }

                $crate::spmi_register_fields!($value_type, $($tail)*);
            }

            impl $crate::RegisterValue for Value {}

            impl Default for Value {
                fn default() -> Self {
                    Self::new(0 as $value_type)
                }
            }

            impl $crate::SpmiRegisterDef for Value {
                type Value = Self;
                type Mode = spmi_register!(@mode_type $mode);
                const ADDRESS: u16 = $addr;
            }

            impl<D> $crate::SpmiRegister<D> for Value {
                type Accessor<'a> =
                    $crate::_Register<'a, Self, spmi_register!(@mode_type $mode), D, $addr>
                where
                    Self: 'a,
                    D: 'a;

                fn get_accessor<'a>(spmi: &'a D) -> Self::Accessor<'a> {
                    $crate::_Register::new(spmi)
                }
            }

            /// The register accessor type.
            pub type Register<'a, D = $crate::DeviceType> =
                $crate::_Register<'a, Value, spmi_register!(@mode_type $mode), D, $addr>;
        }
    };
    // Specialized arm for u8 where endianness is irrelevant
    (
        $name:ident, u8, $addr:expr, $mode:ident, {
            $($tail:tt)*
        }
    ) => {
        spmi_register!($name, u8, $addr, $mode, LE, { $($tail)* });
    };
    (@is_big BE) => { true };
    (@is_big LE) => { false };
}

/// Helper macro for `spmi_register!` to extract inline enums.
#[macro_export]
#[doc(hidden)]
macro_rules! spmi_register_extract_enums {
    // In-line Enum
    (
        $value_type:ty,
        $(#[$attr:meta])*
        $vis:vis enum $enum_name:ident {
            $( $variant_name:ident = $variant_val:expr ),* $(,)?
        },
        $field:ident $(, $setter:ident)? : $msb:expr, $lsb:expr;
        $($tail:tt)*
    ) => {
        #[derive(Debug, PartialEq, Eq, Copy, Clone)]
        #[repr($value_type)]
        $vis enum $enum_name {
            $( $variant_name = $variant_val ),*
        }
        $crate::spmi_register_extract_enums!($value_type, $($tail)*);
    };

    // Forwarding other cases
    (
        $value_type:ty,
        $(#[$attr:meta])*
        $vis:vis $field:ident $(, $setter:ident)? : $bit:expr;
        $($tail:tt)*
    ) => {
        $crate::spmi_register_extract_enums!($value_type, $($tail)*);
    };
    (
        $value_type:ty,
        $(#[$attr:meta])*
        $vis:vis $field:ident $(, $setter:ident)? : $msb:expr, $lsb:expr;
        $($tail:tt)*
    ) => {
        $crate::spmi_register_extract_enums!($value_type, $($tail)*);
    };
    (
        $value_type:ty,
        $(#[$attr:meta])*
        $vis:vis enum $enum_type:ty,
        $field:ident $(, $setter:ident)? : $msb:expr, $lsb:expr;
        $($tail:tt)*
    ) => {
        $crate::spmi_register_extract_enums!($value_type, $($tail)*);
    };
    (
        $value_type:ty,
        pub const $name:ident : $type:ty = $val:expr;
        $($tail:tt)*
    ) => {
        $crate::spmi_register_extract_enums!($value_type, $($tail)*);
    };
    ($value_type:ty) => {};
    ($value_type:ty,) => {};
}

/// Helper macro for `spmi_register!` to generate field accessors.
#[macro_export]
#[doc(hidden)]
macro_rules! spmi_register_fields {
    // Terminating cases
    ($value_type:ty) => {};
    ($value_type:ty,) => {};

    // 1. Single-bit field
    (
        $value_type:ty,
        $(#[$attr:meta])*
        $vis:vis $field:ident $(, $setter:ident)? : $bit:expr;
        $($tail:tt)*
    ) => {
        $(#[$attr])*
        #[allow(non_snake_case)]
        #[allow(dead_code)]
        $vis const fn $field(&self) -> bool {
            const _: () = assert!(
                $bit < <$value_type>::BITS as u8,
                "Bit index out of bounds"
            );
            let bit_mask = (1 as $value_type) << $bit;
            (self.reg_value() & bit_mask) != 0
        }
        $(
            #[allow(non_snake_case)]
            #[allow(dead_code)]
            $vis const fn $setter(self, val: bool) -> Self {
                const _: () = assert!(
                    $bit < <$value_type>::BITS as u8,
                    "Bit index out of bounds"
                );
                let bit_mask = (1 as $value_type) << $bit;
                let raw = (self.reg_value() & !bit_mask)
                    | ((val as $value_type) << $bit);
                Self::new(raw)
            }
        )?
        $crate::spmi_register_fields!($value_type, $($tail)*);
    };

    // 2. Multi-bit field
    (
        $value_type:ty,
        $(#[$attr:meta])*
        $vis:vis $field:ident $(, $setter:ident)? : $msb:expr, $lsb:expr;
        $($tail:tt)*
    ) => {
        $(#[$attr])*
        #[allow(non_snake_case)]
        #[allow(dead_code)]
        $vis const fn $field(&self) -> $value_type {
            const _: () = assert!(
                $msb < <$value_type>::BITS as u8,
                "MSB index out of bounds"
            );
            const _: () = assert!(
                $lsb < $msb,
                "LSB must be strictly less than MSB. \
                 Use single-bit syntax (e.g., 'field: bit;') for 1-bit fields."
            );
            let bit_count = $msb - $lsb + 1;
            let bit_mask = ((!0 as $value_type)
                >> (<$value_type>::BITS as u8 - bit_count))
                << $lsb;
            (self.reg_value() & bit_mask) >> $lsb
        }
        $(
            #[allow(non_snake_case)]
            #[allow(dead_code)]
            $vis const fn $setter(self, val: $value_type) -> Self {
                const _: () = assert!(
                    $msb < <$value_type>::BITS as u8,
                    "MSB index out of bounds"
                );
                const _: () = assert!(
                    $lsb < $msb,
                    "LSB must be strictly less than MSB. \
                     Use single-bit syntax (e.g., 'field: bit;') \
                     for 1-bit fields."
                );
                let bit_count = $msb - $lsb + 1;
                let bit_mask = ((!0 as $value_type)
                    >> (<$value_type>::BITS as u8 - bit_count))
                    << $lsb;
                let raw = (self.reg_value() & !bit_mask)
                    | ((val << $lsb) & bit_mask);
                Self::new(raw)
            }
        )?
        $crate::spmi_register_fields!($value_type, $($tail)*);
    };

    // 3. Enum field
    (
        $value_type:ty,
        $(#[$attr:meta])*
        $vis:vis enum $enum_type:ty,
        $field:ident $(, $setter:ident)? : $msb:expr, $lsb:expr;
        $($tail:tt)*
    ) => {
        $(#[$attr])*
        #[allow(non_snake_case)]
        #[allow(dead_code)]
        $vis const fn $field(&self) -> $enum_type {
            const _: () = assert!(
                $msb < <$value_type>::BITS as u8,
                "MSB index out of bounds"
            );
            const _: () = assert!(
                $lsb <= $msb,
                "LSB must be less than or equal to MSB"
            );
            let bit_count = $msb - $lsb + 1;
            let bit_mask = ((!0 as $value_type)
                >> (<$value_type>::BITS as u8 - bit_count))
                << $lsb;
            <$enum_type>::from_val((self.reg_value() & bit_mask) >> $lsb)
        }
        $(
            #[allow(non_snake_case)]
            #[allow(dead_code)]
            $vis const fn $setter(self, val: $enum_type) -> Self {
                const _: () = assert!(
                    $msb < <$value_type>::BITS as u8,
                    "MSB index out of bounds"
                );
                const _: () = assert!(
                    $lsb <= $msb,
                    "LSB must be less than or equal to MSB"
                );
                let bit_count = $msb - $lsb + 1;
                let bit_mask = ((!0 as $value_type)
                    >> (<$value_type>::BITS as u8 - bit_count))
                    << $lsb;
                let raw = (self.reg_value() & !bit_mask)
                    | (((val as $value_type) << $lsb) & bit_mask);
                Self::new(raw)
            }
        )?
        $crate::spmi_register_fields!($value_type, $($tail)*);
    };

    // 4. In-line Enum field
    (
        $value_type:ty,
        $(#[$attr:meta])*
        $vis:vis enum $enum_name:ident {
            $( $variant_name:ident = $variant_val:expr ),* $(,)?
        },
        $field:ident $(, $setter:ident)? : $msb:expr, $lsb:expr;
        $($tail:tt)*
    ) => {
        $(#[$attr])*
        #[allow(non_snake_case)]
        #[allow(dead_code)]
        $vis const fn $field(&self) -> Result<$enum_name, $value_type> {
            const _: () = assert!(
                $msb < <$value_type>::BITS as u8,
                "MSB index out of bounds"
            );
            const _: () = assert!(
                $lsb <= $msb,
                "LSB must be less than or equal to MSB"
            );
            let bit_count = $msb - $lsb + 1;
            let bit_mask = ((!0 as $value_type)
                >> (<$value_type>::BITS as u8 - bit_count))
                << $lsb;
            let val = (self.reg_value() & bit_mask) >> $lsb;
            $(
                if val == $enum_name::$variant_name as $value_type {
                    return Ok($enum_name::$variant_name);
                }
            )*
            Err(val)
        }
        $(
            #[allow(non_snake_case)]
            #[allow(dead_code)]
            $vis const fn $setter(self, val: $enum_name) -> Self {
                const _: () = assert!(
                    $msb < <$value_type>::BITS as u8,
                    "MSB index out of bounds"
                );
                const _: () = assert!(
                    $lsb <= $msb,
                    "LSB must be less than or equal to MSB"
                );
                let bit_count = $msb - $lsb + 1;
                let bit_mask = ((!0 as $value_type)
                    >> (<$value_type>::BITS as u8 - bit_count))
                    << $lsb;
                let raw = (self.reg_value() & !bit_mask)
                    | (((val as $value_type) << $lsb) & bit_mask);
                Self::new(raw)
            }
        )?
        $crate::spmi_register_fields!($value_type, $($tail)*);
    };

    // 5. Custom constant
    (
        $value_type:ty,
        pub const $name:ident : $type:ty = $val:expr;
        $($tail:tt)*
    ) => {
        pub const $name: $type = $val;
        $crate::spmi_register_fields!($value_type, $($tail)*);
    };
}

/// Verifies at compile-time that a list of registers is contiguous.
#[macro_export]
#[doc(hidden)]
macro_rules! assert_contiguous {
    ($regs:expr, $prev:ident, $curr:ident $(, $rest:ident)*) => {
        $crate::assert_contiguous::<_, $prev::Value, $curr::Value>($regs);
        $crate::assert_contiguous!($regs, $curr $(, $rest)*);
    };
    ($regs:expr, $last:ident) => {};
}

/// Defines a struct to group multiple SPMI registers.
///
/// This macro generates a public struct named `$name` that holds a
/// device client and provides methods to access individual registers
/// defined by `spmi_register!`, as well as `read_bulk` and `write_bulk`
/// methods for contiguous accesses.
///
/// # Arguments
///
/// 1.  `address_unit: $unit_type:ident` (optional): Specifies the type representing an address unit
///     for this block (e.g. `u8` for byte-addressed [default], or `u16` for word-addressed).
/// 2.  `$name`: The identifier for the generated register block struct.
/// 3.  `{ ... }`: A block defining the registers contained within this block.
///     The format of each register definition is:
///     `$vis $field_name => $reg_mod,`
///     -   `$vis`: Visibility of the register accessor method (e.g., `pub`).
///     -   `$field_name`: The name of the method generated on the block
///         struct to access the register.
///     -   `$reg_mod`: The module identifier of the register defined
///         via `spmi_register!`.
///
/// # Examples
///
/// ```
/// spmi_register! {
///     my_reg, u8, 0x10, RW, {
///         pub enable, set_enable: 7;
///     }
/// }
///
/// spmi_register! {
///     status_reg, u16, 0x12, RO, LE, {
///         pub ready: 0;
///     }
/// }
///
/// spmi_register_block! {
///     pub struct MyDeviceRegisters {
///         pub control => my_reg,
///         pub status => status_reg,
///     }
/// }
///
/// // Usage:
/// // let regs = MyDeviceRegisters::new(spmi_device);
/// // let ctrl_val = regs.control().read().await?;
/// // let is_ready = regs.status().read().await?.ready();
/// ```
#[macro_export]
macro_rules! spmi_register_block {
    // Arm 1: with address_unit override
    (
        address_unit: $unit_type:ty,
        $struct_vis:vis struct $name:ident {
            $($tail:tt)*
        }
    ) => {
        $crate::spmi_register_block!(@struct $struct_vis, $name, $($tail)*);

        impl<D> $crate::RegisterBlock for $name<D> {
            const ADDRESS_UNIT_BYTES: u16 = std::mem::size_of::<$unit_type>() as u16;
        }
    };

    // Arm 2: default (byte-addressed)
    (
        $struct_vis:vis struct $name:ident {
            $($tail:tt)*
        }
    ) => {
        $crate::spmi_register_block!(@struct $struct_vis, $name, $($tail)*);

        impl<D> $crate::RegisterBlock for $name<D> {
            const ADDRESS_UNIT_BYTES: u16 = 1;
        }
    };

    // Helper to generate the struct and impl block
    (
        @struct $struct_vis:vis, $name:ident,
        $($tail:tt)*
    ) => {
        #[derive(Clone)]
        $struct_vis struct $name<D = $crate::DeviceType> {
            pub spmi: D,
        }

        #[allow(dead_code)]
        impl<D: $crate::SpmiDevice> $name<D> {
            $struct_vis fn new(spmi: D) -> Self {
                Self { spmi }
            }

            /// Reads a raw byte slice from the contiguous register range.
            ///
            /// # Note
            /// This method is public but hidden because it is required by the
            /// `spmi_read_contiguous!` macro. Direct use is discouraged.
            #[doc(hidden)]
            #[allow(dead_code)]
            pub async fn read_bulk(
                &self,
                address: u16,
                size: u32,
            ) -> Result<Vec<u8>, $crate::Error> {
                let data = $crate::SpmiDevice::read_reg(
                    &self.spmi,
                    address,
                    size,
                ).await?;
                if data.len() == size as usize {
                    Ok(data)
                } else {
                    Err($crate::Error::SizeMismatch)
                }
            }

            /// Reads a raw byte slice from the contiguous register range into a
            /// mutable buffer.
            ///
            /// # Note
            /// This method is public but hidden to discourage direct use,
            /// keeping the bulk API consistent with `read_bulk`.
            #[doc(hidden)]
            #[allow(dead_code)]
            pub async fn read_bulk_into(
                &self,
                address: u16,
                out: &mut [u8],
            ) -> Result<(), $crate::Error> {
                let data = $crate::SpmiDevice::read_reg(
                    &self.spmi,
                    address,
                    out.len() as u32,
                ).await?;
                if data.len() == out.len() {
                    out.copy_from_slice(&data);
                    Ok(())
                } else {
                    Err($crate::Error::SizeMismatch)
                }
            }

            /// Writes the specified data to the contiguous register range.
            ///
            /// # Note
            /// This method is public but hidden because it is required by the
            /// `spmi_write_contiguous!` macro. Direct use is discouraged.
            #[doc(hidden)]
            #[allow(dead_code)]
            pub async fn write_bulk(
                &self,
                address: u16,
                data: &[u8],
            ) -> Result<(), $crate::Error> {
                $crate::SpmiDevice::write_reg(&self.spmi, address, data).await?;
                Ok(())
            }

            $crate::spmi_register_block!(@fields D, $($tail)*);
        }
    };

    (@fields $d:ident) => {};
    (@fields $d:ident,) => {};

    // Case 1: Individual register with trailing fields
    (@fields $d:ident, $(#[$meta:meta])* $vis:vis $field:ident => $reg_mod:ident, $($tail:tt)*) => {
        $(#[$meta])*
        #[allow(dead_code)]
        $vis fn $field(&self) -> <$reg_mod::Value as $crate::SpmiRegister<$d>>::Accessor<'_> {
            <$reg_mod::Value as $crate::SpmiRegister<$d>>::get_accessor(&self.spmi)
        }
        $crate::spmi_register_block!(@fields $d, $($tail)*);
    };

    // Case 2: Individual register at end of token stream
    (@fields $d:ident, $(#[$meta:meta])* $vis:vis $field:ident => $reg_mod:ident) => {
        $(#[$meta])*
        #[allow(dead_code)]
        $vis fn $field(&self) -> <$reg_mod::Value as $crate::SpmiRegister<$d>>::Accessor<'_> {
            <$reg_mod::Value as $crate::SpmiRegister<$d>>::get_accessor(&self.spmi)
        }
    };
}

/// Reads multiple contiguous registers in a single async call to the hardware.
///
/// This macro accepts an SPMI device proxy and a list of register
/// modules, calculates the base address and combined size, and performs
/// a single async contiguous read.
///
/// # Arguments
///
/// 1.  `$regs:expr`: The block struct instance.
/// 2.  `$( $reg:ident ),*`: A comma-separated list of already-declared
///     register modules.
///
/// # Examples
///
/// ```
/// // Read both 'general' and 'status' registers together, update,
/// // and write back:
/// // let regs = MySpmiRegisters::new(spmi_proxy);
/// let (mut general_val, status_val) = spmi_read_contiguous!(
///     &regs,
///     my_reg,
///     status_be_reg
/// ).await?;
///
/// general_val = general_val.set_field1(true);
///
/// spmi_write_contiguous!(
///     &regs,
///     my_reg => general_val,
///     status_be_reg => status_val
/// ).await?;
/// ```
/// Helper macro that calculates contiguous block layout (unit size, base address, and total bytes).
#[doc(hidden)]
#[macro_export]
macro_rules! spmi_contiguous_layout {
    (@last $head:ident) => {
        ($head::ADDRESS, std::mem::size_of::<$head::Value>())
    };

    (@last $head:ident, $( $tail:ident ),+) => {
        $crate::spmi_contiguous_layout!(@last $( $tail ),+)
    };

    (@last_val $head:ident) => {
        $head::Value
    };

    (@last_val $head:ident, $( $tail:ident ),+) => {
        $crate::spmi_contiguous_layout!(@last_val $( $tail ),+)
    };

    ($regs_ref:expr, $head:ident $(, $tail:ident )*) => {{
        let unit = $crate::block_address_unit_bytes($regs_ref) as usize;
        let base_addr = $head::ADDRESS;
        let (last_addr, last_size) = $crate::spmi_contiguous_layout!(@last $head $(, $tail)*);
        let last_step = (last_size + unit - 1) / unit;
        let total_units = (last_addr - base_addr) as usize + last_step;
        let total_bytes = total_units * unit;
        (unit, base_addr, total_bytes)
    }};
}

/// Reads multiple contiguous registers in a single async call to the hardware.
///
/// # Module Names and Paths
/// The macro expects register module names available directly in scope (e.g. `my_reg`).
/// Module paths (e.g. `submod::my_reg`) are not supported as variable binding identifiers.
///
/// # Arguments
///
/// 1.  `$regs:expr`: The block struct instance.
/// 2.  `$head:ident $(, $tail:ident )*`: The register modules to read.
///
/// # Examples
///
/// ```
/// // Read both 'general' and 'status' registers together:
/// // let regs = MySpmiRegisters::new(spmi_proxy);
/// let (general_val, status_val) = spmi_read_contiguous!(
///     &regs,
///     my_reg,
///     status_be_reg
/// ).await?;
/// ```
#[macro_export]
macro_rules! spmi_read_contiguous {
    (
        $regs:expr,
        $head:ident $(, $tail:ident )* $(,)?
    ) => {
        async {
            #[allow(dead_code, non_camel_case_types)]
            struct ReadAccessCheck<$head: $crate::SpmiRegisterDef, $( $tail: $crate::SpmiRegisterDef ),*>(
                std::marker::PhantomData<($head, $( $tail ),*)>,
            )
            where
                $head::Mode: $crate::Readable,
                $( $tail::Mode: $crate::Readable, )*;

            let _ = ReadAccessCheck::<$head::Value, $( $tail::Value ),*>(std::marker::PhantomData);

            let regs_ref = $regs;
            $crate::assert_contiguous!(regs_ref, $head $(, $tail)*);
            let res: Result<
                ($head::Value, $( $tail::Value ),*),
                $crate::Error
            > = async move {
                let (unit, base_addr, total_bytes) =
                    $crate::spmi_contiguous_layout!(regs_ref, $head $(, $tail)*);

                let data = regs_ref.read_bulk(
                    base_addr,
                    total_bytes as u32,
                ).await?;

                let head_offset = ($head::ADDRESS - base_addr) as usize * unit;
                let $head = $head::Value::from_bytes(
                    &data[head_offset..head_offset + std::mem::size_of::<$head::Value>()],
                )?;
                $(
                    let tail_offset = ($tail::ADDRESS - base_addr) as usize * unit;
                    let $tail = $tail::Value::from_bytes(
                        &data[tail_offset..tail_offset + std::mem::size_of::<$tail::Value>()],
                    )?;
                )*

                Ok(($head, $( $tail ),*))
            }.await;
            res
        }
    };
}

/// Writes multiple contiguous registers in a single async call to the hardware.
///
/// # Sub-Word Padding
/// When writing to word-addressed blocks (`address_unit: u16`) containing sub-word registers (e.g. `u8`),
/// unwritten padding byte positions within a word unit are zero-filled before issuing the bulk write.
///
/// # Module Names and Paths
/// The macro expects register module names available directly in scope (e.g. `my_reg`).
/// Module paths (e.g. `submod::my_reg`) are not supported as variable binding identifiers.
///
/// # Arguments
///
/// 1.  `$regs:expr`: The block struct instance.
/// 2.  `$( $reg:ident => $val:expr ),*`: A comma-separated mapping from
///     register modules to their values.
///
/// # Examples
///
/// ```
/// // Write both 'general' and 'status' registers together:
/// // let regs = MySpmiRegisters::new(spmi_proxy);
/// spmi_write_contiguous!(
///     &regs,
///     my_reg => val_a,
///     status_be_reg => val_b
/// ).await?;
/// ```
#[macro_export]
macro_rules! spmi_write_contiguous {
    (
        $regs:expr,
        $head:ident => $head_val:expr $(, $tail:ident => $tail_val:expr )* $(,)?
    ) => {
        async {
            #[allow(dead_code, non_camel_case_types)]
            struct WriteAccessCheck<$head: $crate::SpmiRegisterDef, $( $tail: $crate::SpmiRegisterDef ),*>(
                std::marker::PhantomData<($head, $( $tail ),*)>,
            )
            where
                $head::Mode: $crate::Writable,
                $( $tail::Mode: $crate::Writable, )*;

            let _ = WriteAccessCheck::<$head::Value, $( $tail::Value ),*>(std::marker::PhantomData);

            let regs_ref = $regs;
            $crate::assert_contiguous!(regs_ref, $head $(, $tail)*);
            let res: Result<(), $crate::Error> = async move {
                let (unit, base_addr, total_bytes) =
                    $crate::spmi_contiguous_layout!(regs_ref, $head $(, $tail)*);

                let mut bytes = vec![0u8; total_bytes];

                let head_offset = ($head::ADDRESS - base_addr) as usize * unit;
                bytes[head_offset..head_offset + std::mem::size_of::<$head::Value>()]
                    .copy_from_slice(&$head_val.to_bytes());
                $(
                    let tail_offset = ($tail::ADDRESS - base_addr) as usize * unit;
                    bytes[tail_offset..tail_offset + std::mem::size_of::<$tail::Value>()]
                        .copy_from_slice(&$tail_val.to_bytes());
                )*

                regs_ref.write_bulk(base_addr, &bytes).await?;

                Ok(())
            }.await;
            res
        }
    };
}

/// Trait for SPMI devices to abstract register read/write operations.
///
/// This trait allows the `Register` and `spmi_register_block!` macros to
/// interact with any underlying hardware interface or mock device that
/// implements these basic SPMI read and write operations.
///
/// Implementations must handle the low-level transport (e.g., FIDL calls
/// to a Fuchsia SPMI driver) and handle error mapping.
#[allow(async_fn_in_trait)]
pub trait SpmiDevice {
    /// Reads a contiguous sequence of bytes from the device.
    ///
    /// # Arguments
    ///
    /// * `address` - The 16-bit base register address to read from.
    /// * `size` - The number of bytes to read.
    ///
    /// # Returns
    ///
    /// Returns a vector containing the read bytes on success, or a
    /// `crate::Error` on failure.
    async fn read_reg(&self, address: u16, size: u32) -> Result<Vec<u8>, crate::Error>;

    /// Writes a contiguous sequence of bytes to the device.
    ///
    /// # Arguments
    ///
    /// * `address` - The 16-bit base register address to write to.
    /// * `data` - The byte slice to write to the device.
    ///
    /// # Returns
    ///
    /// Returns `Ok(())` on success, or a `crate::Error` on failure.
    async fn write_reg(&self, address: u16, data: &[u8]) -> Result<(), crate::Error>;
}

#[cfg(test)]
/// A mock SPMI device that stores register values in memory.
/// Used for testing register access without a real device or FIDL connection.
pub struct TestSpmiDevice {
    registers: std::sync::Mutex<std::collections::HashMap<u16, u8>>,
}

#[cfg(test)]
impl TestSpmiDevice {
    /// Creates a new empty `TestSpmiDevice`.
    pub fn new() -> Self {
        Self { registers: std::sync::Mutex::new(std::collections::HashMap::new()) }
    }
}

#[cfg(test)]
impl SpmiDevice for TestSpmiDevice {
    async fn read_reg(&self, address: u16, size: u32) -> Result<Vec<u8>, crate::Error> {
        let regs = self.registers.lock().unwrap();
        let mut data = Vec::new();
        for i in 0..size {
            let addr = address + i as u16;
            let val = regs.get(&addr).copied().unwrap_or(0);
            data.push(val);
        }
        Ok(data)
    }

    async fn write_reg(&self, address: u16, data: &[u8]) -> Result<(), crate::Error> {
        let mut regs = self.registers.lock().unwrap();
        for (i, &val) in data.iter().enumerate() {
            let addr = address + i as u16;
            regs.insert(addr, val);
        }
        Ok(())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    // Note: For single-byte width registers (u8), explicit endianness is
    // not required.
    spmi_register! {
        test_u8_reg, u8, 0xCD, RW, {
            pub flag, set_flag: 4;
            pub field, set_field: 3, 0;
        }
    }

    spmi_register_block! {
        pub struct MockU8Regs {
            pub test => test_u8_reg,
        }
    }

    spmi_register! {
        test_u16_from_bytes_reg, u16, 0x99, RW, LE, {
            pub field, set_field: 15, 0;
        }
    }

    spmi_register_block! {
        pub struct MockU16FromBytesRegs {
            pub test => test_u16_from_bytes_reg,
        }
    }

    spmi_register! {
        test_u16_contig_reg, u16, 0xCE, RW, LE, {
            pub field, set_field: 15, 0;
        }
    }

    #[fuchsia::test]
    async fn test_u16_from_bytes() {
        let device = TestSpmiDevice::new();
        device.write_reg(0x99, &[0x34, 0x12]).await.unwrap();

        let regs = MockU16FromBytesRegs::new(device);
        let val = regs.test().read().await.unwrap();
        assert_eq!(val.reg_value(), 0x1234);
    }

    #[fuchsia::test]
    async fn test_u8_register() {
        let device = TestSpmiDevice::new();
        device.write_reg(0xCD, &[0x1A]).await.unwrap();

        let regs = MockU8Regs::new(device);
        let val = regs.test().read().await.unwrap();
        assert_eq!(val.reg_value(), 0x1A);
        assert_eq!(val.flag(), true);
        assert_eq!(val.field(), 0x0A);
    }

    spmi_register! {
        test_reg, u16, 0xAB, RW, LE, {
            pub test_bit, set_test_bit: 7;
            pub test_field, set_test_field: 3, 0;
        }
    }

    spmi_register_block! {
        pub struct MockRegs {
            pub test => test_reg,
        }
    }

    #[fuchsia::test]
    async fn test_read() {
        let device = TestSpmiDevice::new();
        device.write_reg(0xAB, &[0x8A, 0x00]).await.unwrap();

        let regs = MockRegs::new(device);
        let val = regs.test().read().await.unwrap();
        assert_eq!(val.reg_value(), 0x008A);
        assert_eq!(val.test_bit(), true);
        assert_eq!(val.test_field(), 0x0A);
    }

    #[fuchsia::test]
    async fn test_write() {
        let device = TestSpmiDevice::new();

        let regs = MockRegs::new(device);
        let v = test_reg::Value::new(0x008A);
        regs.test().write(v).await.unwrap();

        let data = regs.spmi.read_reg(0xAB, 2).await.unwrap();
        assert_eq!(data, &[0x8A, 0x00]);
    }

    struct MockWrapper {
        device: TestSpmiDevice,
    }

    impl SpmiDevice for MockWrapper {
        async fn read_reg(&self, address: u16, size: u32) -> Result<Vec<u8>, crate::Error> {
            self.device.read_reg(address, size).await
        }
        async fn write_reg(&self, address: u16, data: &[u8]) -> Result<(), crate::Error> {
            self.device.write_reg(address, data).await
        }
    }

    spmi_register_block! {
        pub struct MockWrappedRegs {
            pub test => test_reg,
        }
    }

    #[fuchsia::test]
    async fn test_wrapped_read() {
        let device = TestSpmiDevice::new();
        device.write_reg(0xAB, &[0x8A, 0x00]).await.unwrap();

        let wrapper = MockWrapper { device };
        let regs = MockWrappedRegs::new(wrapper);
        let val = regs.test().read().await.unwrap();
        assert_eq!(val.reg_value(), 0x008A);
        assert_eq!(val.test_bit(), true);
    }

    spmi_register! {
        test_be_reg, u16, 0xEF, RW, BE, {
            pub flag, set_flag: 4;
            pub field, set_field: 3, 0;
        }
    }

    spmi_register_block! {
        pub struct MockBERegs {
            pub test => test_be_reg,
        }
    }

    #[fuchsia::test]
    async fn test_be_register() {
        let device = TestSpmiDevice::new();
        device.write_reg(0xEF, &[0x00, 0x8A]).await.unwrap();

        let regs = MockBERegs::new(device);
        let val = regs.test().read().await.unwrap();
        assert_eq!(val.reg_value(), 0x8A);
    }

    #[derive(Debug, PartialEq, Eq, Copy, Clone)]
    #[repr(u16)]
    pub enum PowerMode {
        Normal = 0,
        Hibernate = 1,
        LowPower = 2,
        Unknown = 0xFFFF,
    }

    impl PowerMode {
        pub const fn from_val(val: u16) -> Self {
            match val {
                0 => PowerMode::Normal,
                1 => PowerMode::Hibernate,
                2 => PowerMode::LowPower,
                _ => PowerMode::Unknown,
            }
        }
    }

    spmi_register! {
        test_enum_reg, u16, 0x44, RW, LE, {
            pub enum PowerMode, mode, set_mode: 3, 2;
        }
    }

    spmi_register_block! {
        pub struct MockEnumRegs {
            pub test => test_enum_reg,
        }
    }

    #[fuchsia::test]
    async fn test_enum_register() {
        let device = TestSpmiDevice::new();

        let regs = MockEnumRegs::new(device);
        let v = test_enum_reg::Value::new(0).set_mode(PowerMode::Hibernate);
        regs.test().write(v).await.unwrap();

        let data = regs.spmi.read_reg(0x44, 2).await.unwrap();
        assert_eq!(data, &[0x04, 0x00]);
    }

    spmi_register! {
        test_inline_enum_reg, u16, 0x55, RW, LE, {
            pub enum InlineMode {
                A = 0,
                B = 1,
            }, mode, set_mode: 1, 0;
        }
    }

    spmi_register_block! {
        pub struct MockInlineEnumRegs {
            pub test => test_inline_enum_reg,
        }
    }

    #[fuchsia::test]
    async fn test_inline_enum() {
        let device = TestSpmiDevice::new();

        let regs = MockInlineEnumRegs::new(device);
        let v = test_inline_enum_reg::Value::new(1).set_mode(test_inline_enum_reg::InlineMode::B);
        assert_eq!(v.mode(), Ok(test_inline_enum_reg::InlineMode::B));
        regs.test().write(v).await.unwrap();

        let data = regs.spmi.read_reg(0x55, 2).await.unwrap();
        assert_eq!(data, &[0x01, 0x00]);
    }

    #[fuchsia::test]
    async fn test_contiguous_read_write() {
        let device = TestSpmiDevice::new();
        device.write_reg(0xCD, &[0x1A, 0x34, 0x12]).await.unwrap();

        spmi_register_block! {
            pub struct ContiguousRegs {
                pub r1 => test_u8_reg,
                pub r2 => test_u16_contig_reg,
            }
        }
        let regs = ContiguousRegs::new(device);

        let (val_1, val_2) =
            spmi_read_contiguous!(&regs, test_u8_reg, test_u16_contig_reg,).await.unwrap();

        assert_eq!(val_1.reg_value(), 0x1A);
        assert_eq!(val_2.reg_value(), 0x1234);

        spmi_write_contiguous!(
            &regs,
            test_u8_reg => val_1,
            test_u16_contig_reg => val_2
        )
        .await
        .unwrap();

        let data = regs.spmi.read_reg(0xCD, 3).await.unwrap();
        assert_eq!(data, &[0x1A, 0x34, 0x12]);
    }

    spmi_register! {
        test_word_reg_1, u16, 0x10, RW, LE, {}
    }
    spmi_register! {
        test_word_reg_2, u16, 0x11, RW, LE, {}
    }
    spmi_register! {
        test_word_reg_3, u16, 0x12, RW, LE, {}
    }

    spmi_register_block! {
        address_unit: u16,
        pub struct WordAddressedRegs {
            pub r1 => test_word_reg_1,
            pub r2 => test_word_reg_2,
            pub r3 => test_word_reg_3,
        }
    }

    #[fuchsia::test]
    async fn test_word_addressed_contiguous() {
        let device = TestSpmiDevice::new();
        device.write_reg(0x10, &[0x34, 0x12, 0x78, 0x56]).await.unwrap();

        let regs = WordAddressedRegs::new(device);

        // Note on SPMI addressing: Standard SPMI register addresses refer to byte offsets (where a
        // 16-bit register spans 2 byte addresses, so contiguous u16 registers have an address diff
        // of 2). However, some hardware devices use 16-bit word-addressed registers where each
        // address offset 0x10, 0x11 represents a 16-bit word (address diff of 1). Specifying
        // `address_unit: u16` in `spmi_register_block!` handles these word-addressed hardware
        // blocks.
        let (val_1, val_2) =
            spmi_read_contiguous!(&regs, test_word_reg_1, test_word_reg_2).await.unwrap();
        assert_eq!(val_1.reg_value(), 0x1234);
        assert_eq!(val_2.reg_value(), 0x5678);

        // Write contiguous
        spmi_write_contiguous!(
            &regs,
            test_word_reg_1 => val_1,
            test_word_reg_2 => val_2
        )
        .await
        .unwrap();

        let data = regs.spmi.read_reg(0x10, 4).await.unwrap();
        assert_eq!(data, &[0x34, 0x12, 0x78, 0x56]);
    }

    #[fuchsia::test]
    async fn test_read_write_bulk() {
        let device = TestSpmiDevice::new();
        device.write_reg(0x88, &[0x1A, 0x2B, 0x3C]).await.unwrap();

        let regs = MockU8Regs::new(device);
        let bytes = regs.read_bulk(0x88, 3).await.unwrap();
        assert_eq!(bytes, vec![0x1A, 0x2B, 0x3C]);

        let mut buf = [0u8; 3];
        regs.read_bulk_into(0x88, &mut buf).await.unwrap();
        assert_eq!(buf, [0x1A, 0x2B, 0x3C]);

        regs.write_bulk(0x88, &[0x1A, 0x2B, 0x3C]).await.unwrap();
        let data = regs.spmi.read_reg(0x88, 3).await.unwrap();
        assert_eq!(data, &[0x1A, 0x2B, 0x3C]);
    }

    spmi_register! {
        test_mixed_u8, u8, 0x20, RW, {}
    }
    spmi_register! {
        test_mixed_u16, u16, 0x21, RW, LE, {}
    }

    spmi_register_block! {
        address_unit: u16,
        pub struct WordAddressedMixedRegs {
            pub u8_reg => test_mixed_u8,
            pub u16_reg => test_mixed_u16,
        }
    }

    #[fuchsia::test]
    async fn test_word_addressed_mixed_sizes_contiguous() {
        let device = TestSpmiDevice::new();
        // 0x20 is u8 (occupies byte 0, byte 1 padded 0x00). 0x21 is u16 (bytes 2..4).
        device.write_reg(0x20, &[0xAB, 0x00, 0x34, 0x12]).await.unwrap();

        let regs = WordAddressedMixedRegs::new(device);
        let (val_u8, val_u16) =
            spmi_read_contiguous!(&regs, test_mixed_u8, test_mixed_u16).await.unwrap();

        assert_eq!(val_u8.reg_value(), 0xAB);
        assert_eq!(val_u16.reg_value(), 0x1234);

        spmi_write_contiguous!(
            &regs,
            test_mixed_u8 => val_u8,
            test_mixed_u16 => val_u16
        )
        .await
        .unwrap();

        let data = regs.spmi.read_reg(0x20, 4).await.unwrap();
        assert_eq!(data, &[0xAB, 0x00, 0x34, 0x12]);
    }

    #[derive(
        Copy,
        Clone,
        Debug,
        PartialEq,
        Eq,
        zerocopy::FromBytes,
        zerocopy::IntoBytes,
        zerocopy::KnownLayout,
        zerocopy::Immutable,
    )]
    #[repr(C)]
    pub struct Reg3Byte([u8; 3]);
    impl RegisterValue for Reg3Byte {}

    impl Reg3Byte {
        fn from_bytes(bytes: &[u8]) -> Result<Self, crate::Error> {
            let slice: [u8; 3] = bytes.try_into().unwrap();
            Ok(Self(slice))
        }
        fn to_bytes(&self) -> [u8; 3] {
            self.0
        }
        fn reg_value(&self) -> Self {
            *self
        }
    }

    mod test_3byte_reg {
        use super::*;
        pub type Value = Reg3Byte;
        pub const ADDRESS: u16 = 0x30;
    }

    impl SpmiRegisterDef for Reg3Byte {
        type Value = Self;
        type Mode = crate::ReadWrite;
        const ADDRESS: u16 = 0x30;
    }

    impl<D> SpmiRegister<D> for Reg3Byte {
        type Accessor<'a>
            = &'a D
        where
            Self: 'a,
            D: 'a;
        fn get_accessor<'a>(spmi: &'a D) -> Self::Accessor<'a> {
            spmi
        }
    }
    spmi_register! {
        test_after_3byte_reg, u16, 0x32, RW, LE, {}
    }

    spmi_register_block! {
        address_unit: u16,
        pub struct WordAddressed3ByteRegs {
            pub r3b => test_3byte_reg,
            pub r_next => test_after_3byte_reg,
        }
    }

    #[fuchsia::test]
    async fn test_word_addressed_non_multiple_size_contiguous() {
        let device = TestSpmiDevice::new();
        // 0x30 is 3 bytes (takes 2 word units = 4 bytes: [0x11, 0x22, 0x33, 0x00]).
        // 0x32 is u16 (starts at 0x32 = byte offset 4: [0x56, 0x78]).
        device.write_reg(0x30, &[0x11, 0x22, 0x33, 0x00, 0x56, 0x78]).await.unwrap();

        let regs = WordAddressed3ByteRegs::new(device);
        let (val_3b, val_next) =
            spmi_read_contiguous!(&regs, test_3byte_reg, test_after_3byte_reg).await.unwrap();

        assert_eq!(val_3b.reg_value(), Reg3Byte([0x11, 0x22, 0x33]));
        assert_eq!(val_next.reg_value(), 0x7856);

        spmi_write_contiguous!(
            &regs,
            test_3byte_reg => val_3b,
            test_after_3byte_reg => val_next
        )
        .await
        .unwrap();

        let data = regs.spmi.read_reg(0x30, 6).await.unwrap();
        assert_eq!(data, &[0x11, 0x22, 0x33, 0x00, 0x56, 0x78]);
    }

    spmi_register! {
        synth_u8_reg, u8, 0x60, RW, {
            pub enum SynthU8Mode {
                Mode0 = 0,
                Mode1 = 1,
                Mode2 = 2,
                Mode3 = 3,
            }, mode, set_mode: 2, 1;
            pub enable, set_enable: 3;
            pub multi, set_multi: 6, 5;
        }
    }

    spmi_register! {
        synth_u16_le_reg, u16, 0x62, RW, LE, {
            pub flag_low, set_flag_low: 1;
            pub enum SynthU16LeMode {
                Off = 0,
                On = 1,
                Standby = 2,
                Active = 3,
            }, mode, set_mode: 5, 4;
            pub data, set_data: 11, 8;
            pub flag_high, set_flag_high: 14;
        }
    }

    spmi_register! {
        synth_u16_be_reg, u16, 0x64, RW, BE, {
            pub flag_low, set_flag_low: 2;
            pub enum SynthU16BeMode {
                Alpha = 0,
                Beta = 1,
                Gamma = 2,
                Delta = 3,
            }, mode, set_mode: 6, 5;
            pub count, set_count: 12, 9;
            pub flag_high, set_flag_high: 15;
        }
    }

    spmi_register! {
        synth_u32_le_reg, u32, 0x70, RW, LE, {
            pub flag_low, set_flag_low: 3;
            pub enum SynthU32LeMode {
                Zero = 0,
                One = 1,
                Two = 2,
                Three = 3,
            }, mode, set_mode: 8, 7;
            pub range, set_range: 22, 16;
            pub flag_high, set_flag_high: 30;
        }
    }

    spmi_register! {
        synth_u32_be_reg, u32, 0x74, RW, BE, {
            pub flag_low, set_flag_low: 2;
            pub enum SynthU32BeMode {
                Primary = 0,
                Secondary = 1,
                Tertiary = 2,
                Quaternary = 3,
            }, mode, set_mode: 10, 9;
            pub chunk, set_chunk: 23, 17;
            pub flag_high, set_flag_high: 31;
        }
    }

    spmi_register_block! {
        pub struct SynthRegs {
            pub u8_reg => synth_u8_reg,
            pub u16_le_reg => synth_u16_le_reg,
            pub u16_be_reg => synth_u16_be_reg,
            pub u32_le_reg => synth_u32_le_reg,
            pub u32_be_reg => synth_u32_be_reg,
        }
    }

    // Synthetic u8 register bitmasks (fields: mode [2:1], enable [3], multi [6:5]).
    // Reserved bits: 0, 4, 7 (mask: 0x91).
    const U8_MODE_MASK: u8 = 0x06;
    const U8_ENABLE_MASK: u8 = 0x08;
    const U8_MULTI_MASK: u8 = 0x60;
    const U8_RESERVED_MASK: u8 = !(U8_MODE_MASK | U8_ENABLE_MASK | U8_MULTI_MASK);
    const U8_MULTI_FIELD_MASK: u8 = 0x03;

    // Synthetic u16 LE register bitmasks
    // (fields: flag_low [1], mode [5:4], data [11:8], flag_high [14]).
    // Reserved bits: 0, 2, 3, 6, 7, 12, 13, 15 (mask: 0xB0CD).
    const U16_LE_FLAG_LOW_MASK: u16 = 0x0002;
    const U16_LE_MODE_MASK: u16 = 0x0030;
    const U16_LE_DATA_MASK: u16 = 0x0F00;
    const U16_LE_FLAG_HIGH_MASK: u16 = 0x4000;
    const U16_LE_RESERVED_MASK: u16 =
        !(U16_LE_FLAG_LOW_MASK | U16_LE_MODE_MASK | U16_LE_DATA_MASK | U16_LE_FLAG_HIGH_MASK);
    const U16_LE_DATA_FIELD_MASK: u16 = 0x0F;

    // Synthetic u16 BE register bitmasks
    // (fields: flag_low [2], mode [6:5], count [12:9], flag_high [15]).
    // Reserved bits: 0, 1, 3, 4, 7, 8, 13, 14 (mask: 0x619B).
    const U16_BE_FLAG_LOW_MASK: u16 = 0x0004;
    const U16_BE_MODE_MASK: u16 = 0x0060;
    const U16_BE_COUNT_MASK: u16 = 0x1E00;
    const U16_BE_FLAG_HIGH_MASK: u16 = 0x8000;
    const U16_BE_RESERVED_MASK: u16 =
        !(U16_BE_FLAG_LOW_MASK | U16_BE_MODE_MASK | U16_BE_COUNT_MASK | U16_BE_FLAG_HIGH_MASK);
    const U16_BE_COUNT_FIELD_MASK: u16 = 0x0F;

    // Synthetic u32 LE register bitmasks
    // (fields: flag_low [3], mode [8:7], range [22:16], flag_high [30]).
    // Reserved bits: 0..2, 4..6, 9..15, 23..29, 31 (mask: 0xBF80_FE77).
    const U32_LE_FLAG_LOW_MASK: u32 = 0x0000_0008;
    const U32_LE_MODE_MASK: u32 = 0x0000_0180;
    const U32_LE_RANGE_MASK: u32 = 0x007F_0000;
    const U32_LE_FLAG_HIGH_MASK: u32 = 0x4000_0000;
    const U32_LE_RESERVED_MASK: u32 =
        !(U32_LE_FLAG_LOW_MASK | U32_LE_MODE_MASK | U32_LE_RANGE_MASK | U32_LE_FLAG_HIGH_MASK);
    const U32_LE_RANGE_FIELD_MASK: u32 = 0x7F;

    // Synthetic u32 BE register bitmasks
    // (fields: flag_low [2], mode [10:9], chunk [23:17], flag_high [31]).
    // Reserved bits: 0..1, 3..8, 11..16, 24..30 (mask: 0x7F01_F9FB).
    const U32_BE_FLAG_LOW_MASK: u32 = 0x0000_0004;
    const U32_BE_MODE_MASK: u32 = 0x0000_0600;
    const U32_BE_CHUNK_MASK: u32 = 0x00FE_0000;
    const U32_BE_FLAG_HIGH_MASK: u32 = 0x8000_0000;
    const U32_BE_RESERVED_MASK: u32 =
        !(U32_BE_FLAG_LOW_MASK | U32_BE_MODE_MASK | U32_BE_CHUNK_MASK | U32_BE_FLAG_HIGH_MASK);
    const U32_BE_CHUNK_FIELD_MASK: u32 = 0x7F;

    // Background patterns for bitfield isolation tests.
    const U8_ALTERNATING_BITS_HIGH: u8 = 0xAA;
    const U8_ALTERNATING_BITS_LOW: u8 = 0x55;
    const U8_TEST_PATTERNS: [u8; 4] =
        [u8::MIN, u8::MAX, U8_ALTERNATING_BITS_HIGH, U8_ALTERNATING_BITS_LOW];

    const U16_ALTERNATING_BITS_HIGH: u16 = 0xAAAA;
    const U16_ALTERNATING_BITS_LOW: u16 = 0x5555;
    const U16_TEST_PATTERNS: [u16; 4] =
        [u16::MIN, u16::MAX, U16_ALTERNATING_BITS_HIGH, U16_ALTERNATING_BITS_LOW];

    const U32_ALTERNATING_BITS_HIGH: u32 = 0xAAAA_AAAA;
    const U32_ALTERNATING_BITS_LOW: u32 = 0x5555_5555;
    const U32_TEST_PATTERNS: [u32; 4] =
        [u32::MIN, u32::MAX, U32_ALTERNATING_BITS_HIGH, U32_ALTERNATING_BITS_LOW];

    // Register byte lengths for SPMI read operations.
    const U8_REG_BYTES: u32 = std::mem::size_of::<u8>() as u32;
    const U16_REG_BYTES: u32 = std::mem::size_of::<u16>() as u32;
    const U32_REG_BYTES: u32 = std::mem::size_of::<u32>() as u32;

    // Verifies bitfield isolation, field mutators, and reserved bit preservation for u8 registers.
    #[test]
    fn test_bitfield_isolation_and_reserved_bits_u8() {
        assert_eq!(U8_RESERVED_MASK | U8_ENABLE_MASK | U8_MULTI_MASK | U8_MODE_MASK, u8::MAX);

        let u8_chained_multi = 2;

        for &base in &U8_TEST_PATTERNS {
            let v = synth_u8_reg::Value::new(base);
            let reserved = base & U8_RESERVED_MASK;

            let v_en = v.set_enable(!v.enable());
            assert_eq!(v_en.enable(), !v.enable());
            assert_eq!(v_en.reg_value() & U8_RESERVED_MASK, reserved);
            assert_eq!(v_en.multi(), v.multi());
            assert_eq!(v_en.mode(), v.mode());
            assert_eq!(v_en.reg_value() ^ v.reg_value(), U8_ENABLE_MASK);

            let new_multi = (v.multi() + 1) & U8_MULTI_FIELD_MASK;
            let v_multi = v.set_multi(new_multi);
            assert_eq!(v_multi.multi(), new_multi);
            assert_eq!(v_multi.reg_value() & U8_RESERVED_MASK, reserved);
            assert_eq!(v_multi.enable(), v.enable());
            assert_eq!(v_multi.mode(), v.mode());
            assert_eq!((v_multi.reg_value() ^ v.reg_value()) & !U8_MULTI_MASK, 0);

            let new_mode = synth_u8_reg::SynthU8Mode::Mode2;
            let v_mode = v.set_mode(new_mode);
            assert_eq!(v_mode.mode(), Ok(new_mode));
            assert_eq!(v_mode.reg_value() & U8_RESERVED_MASK, reserved);
            assert_eq!(v_mode.enable(), v.enable());
            assert_eq!(v_mode.multi(), v.multi());
            assert_eq!((v_mode.reg_value() ^ v.reg_value()) & !U8_MODE_MASK, 0);

            let v_chained = v
                .set_enable(true)
                .set_multi(u8_chained_multi)
                .set_mode(synth_u8_reg::SynthU8Mode::Mode1);
            assert!(v_chained.enable());
            assert_eq!(v_chained.multi(), u8_chained_multi);
            assert_eq!(v_chained.mode(), Ok(synth_u8_reg::SynthU8Mode::Mode1));
            assert_eq!(v_chained.reg_value() & U8_RESERVED_MASK, reserved);
        }
    }

    // Verifies bitfield isolation, field mutators, and reserved bit preservation for u16 registers.
    #[test]
    fn test_bitfield_isolation_and_reserved_bits_u16() {
        // 1. Little-endian u16 register
        assert_eq!(
            U16_LE_RESERVED_MASK
                | U16_LE_FLAG_LOW_MASK
                | U16_LE_MODE_MASK
                | U16_LE_DATA_MASK
                | U16_LE_FLAG_HIGH_MASK,
            u16::MAX
        );

        let u16_le_chained_data = 0x7;

        for &base in &U16_TEST_PATTERNS {
            let v = synth_u16_le_reg::Value::new(base);
            let reserved = base & U16_LE_RESERVED_MASK;

            let v_fl = v.set_flag_low(!v.flag_low());
            assert_eq!(v_fl.flag_low(), !v.flag_low());
            assert_eq!(v_fl.reg_value() & U16_LE_RESERVED_MASK, reserved);
            assert_eq!(v_fl.mode(), v.mode());
            assert_eq!(v_fl.data(), v.data());
            assert_eq!(v_fl.flag_high(), v.flag_high());
            assert_eq!(v_fl.reg_value() ^ v.reg_value(), U16_LE_FLAG_LOW_MASK);

            let new_mode = synth_u16_le_reg::SynthU16LeMode::Active;
            let v_mode = v.set_mode(new_mode);
            assert_eq!(v_mode.mode(), Ok(new_mode));
            assert_eq!(v_mode.reg_value() & U16_LE_RESERVED_MASK, reserved);
            assert_eq!(v_mode.flag_low(), v.flag_low());
            assert_eq!(v_mode.data(), v.data());
            assert_eq!(v_mode.flag_high(), v.flag_high());
            assert_eq!((v_mode.reg_value() ^ v.reg_value()) & !U16_LE_MODE_MASK, 0);

            let new_data = (v.data() + 1) & U16_LE_DATA_FIELD_MASK;
            let v_data = v.set_data(new_data);
            assert_eq!(v_data.data(), new_data);
            assert_eq!(v_data.reg_value() & U16_LE_RESERVED_MASK, reserved);
            assert_eq!(v_data.flag_low(), v.flag_low());
            assert_eq!(v_data.mode(), v.mode());
            assert_eq!(v_data.flag_high(), v.flag_high());
            assert_eq!((v_data.reg_value() ^ v.reg_value()) & !U16_LE_DATA_MASK, 0);

            let v_fh = v.set_flag_high(!v.flag_high());
            assert_eq!(v_fh.flag_high(), !v.flag_high());
            assert_eq!(v_fh.reg_value() & U16_LE_RESERVED_MASK, reserved);
            assert_eq!(v_fh.flag_low(), v.flag_low());
            assert_eq!(v_fh.mode(), v.mode());
            assert_eq!(v_fh.data(), v.data());
            assert_eq!(v_fh.reg_value() ^ v.reg_value(), U16_LE_FLAG_HIGH_MASK);

            let v_chained = v
                .set_flag_low(true)
                .set_mode(synth_u16_le_reg::SynthU16LeMode::Standby)
                .set_data(u16_le_chained_data)
                .set_flag_high(false);
            assert!(v_chained.flag_low());
            assert_eq!(v_chained.mode(), Ok(synth_u16_le_reg::SynthU16LeMode::Standby));
            assert_eq!(v_chained.data(), u16_le_chained_data);
            assert!(!v_chained.flag_high());
            assert_eq!(v_chained.reg_value() & U16_LE_RESERVED_MASK, reserved);
        }

        // 2. Big-endian u16 register
        assert_eq!(
            U16_BE_RESERVED_MASK
                | U16_BE_FLAG_LOW_MASK
                | U16_BE_MODE_MASK
                | U16_BE_COUNT_MASK
                | U16_BE_FLAG_HIGH_MASK,
            u16::MAX
        );

        let u16_be_chained_count = 0xC;

        for &base in &U16_TEST_PATTERNS {
            let v = synth_u16_be_reg::Value::new(base);
            let reserved = base & U16_BE_RESERVED_MASK;

            let v_fl = v.set_flag_low(!v.flag_low());
            assert_eq!(v_fl.flag_low(), !v.flag_low());
            assert_eq!(v_fl.reg_value() & U16_BE_RESERVED_MASK, reserved);
            assert_eq!(v_fl.reg_value() ^ v.reg_value(), U16_BE_FLAG_LOW_MASK);

            let new_mode = synth_u16_be_reg::SynthU16BeMode::Gamma;
            let v_mode = v.set_mode(new_mode);
            assert_eq!(v_mode.mode(), Ok(new_mode));
            assert_eq!(v_mode.reg_value() & U16_BE_RESERVED_MASK, reserved);
            assert_eq!((v_mode.reg_value() ^ v.reg_value()) & !U16_BE_MODE_MASK, 0);

            let new_count = (v.count() + 1) & U16_BE_COUNT_FIELD_MASK;
            let v_count = v.set_count(new_count);
            assert_eq!(v_count.count(), new_count);
            assert_eq!(v_count.reg_value() & U16_BE_RESERVED_MASK, reserved);
            assert_eq!((v_count.reg_value() ^ v.reg_value()) & !U16_BE_COUNT_MASK, 0);

            let v_fh = v.set_flag_high(!v.flag_high());
            assert_eq!(v_fh.flag_high(), !v.flag_high());
            assert_eq!(v_fh.reg_value() & U16_BE_RESERVED_MASK, reserved);
            assert_eq!(v_fh.reg_value() ^ v.reg_value(), U16_BE_FLAG_HIGH_MASK);

            let v_chained = v
                .set_flag_low(false)
                .set_mode(synth_u16_be_reg::SynthU16BeMode::Beta)
                .set_count(u16_be_chained_count)
                .set_flag_high(true);
            assert!(!v_chained.flag_low());
            assert_eq!(v_chained.mode(), Ok(synth_u16_be_reg::SynthU16BeMode::Beta));
            assert_eq!(v_chained.count(), u16_be_chained_count);
            assert!(v_chained.flag_high());
            assert_eq!(v_chained.reg_value() & U16_BE_RESERVED_MASK, reserved);
        }
    }

    // Verifies bitfield isolation, field mutators, and reserved bit preservation for u32 registers.
    #[test]
    fn test_bitfield_isolation_and_reserved_bits_u32() {
        // 1. Little-endian u32 register
        assert_eq!(
            U32_LE_RESERVED_MASK
                | U32_LE_FLAG_LOW_MASK
                | U32_LE_MODE_MASK
                | U32_LE_RANGE_MASK
                | U32_LE_FLAG_HIGH_MASK,
            u32::MAX
        );

        let u32_le_chained_range = 0x3B;

        for &base in &U32_TEST_PATTERNS {
            let v = synth_u32_le_reg::Value::new(base);
            let reserved = base & U32_LE_RESERVED_MASK;

            let v_fl = v.set_flag_low(!v.flag_low());
            assert_eq!(v_fl.flag_low(), !v.flag_low());
            assert_eq!(v_fl.reg_value() & U32_LE_RESERVED_MASK, reserved);
            assert_eq!(v_fl.mode(), v.mode());
            assert_eq!(v_fl.range(), v.range());
            assert_eq!(v_fl.flag_high(), v.flag_high());
            assert_eq!(v_fl.reg_value() ^ v.reg_value(), U32_LE_FLAG_LOW_MASK);

            let new_mode = synth_u32_le_reg::SynthU32LeMode::Two;
            let v_mode = v.set_mode(new_mode);
            assert_eq!(v_mode.mode(), Ok(new_mode));
            assert_eq!(v_mode.reg_value() & U32_LE_RESERVED_MASK, reserved);
            assert_eq!(v_mode.flag_low(), v.flag_low());
            assert_eq!(v_mode.range(), v.range());
            assert_eq!(v_mode.flag_high(), v.flag_high());
            assert_eq!((v_mode.reg_value() ^ v.reg_value()) & !U32_LE_MODE_MASK, 0);

            let new_range = (v.range() + 1) & U32_LE_RANGE_FIELD_MASK;
            let v_range = v.set_range(new_range);
            assert_eq!(v_range.range(), new_range);
            assert_eq!(v_range.reg_value() & U32_LE_RESERVED_MASK, reserved);
            assert_eq!(v_range.flag_low(), v.flag_low());
            assert_eq!(v_range.mode(), v.mode());
            assert_eq!(v_range.flag_high(), v.flag_high());
            assert_eq!((v_range.reg_value() ^ v.reg_value()) & !U32_LE_RANGE_MASK, 0);

            let v_fh = v.set_flag_high(!v.flag_high());
            assert_eq!(v_fh.flag_high(), !v.flag_high());
            assert_eq!(v_fh.reg_value() & U32_LE_RESERVED_MASK, reserved);
            assert_eq!(v_fh.flag_low(), v.flag_low());
            assert_eq!(v_fh.mode(), v.mode());
            assert_eq!(v_fh.range(), v.range());
            assert_eq!(v_fh.reg_value() ^ v.reg_value(), U32_LE_FLAG_HIGH_MASK);

            let v_chained = v
                .set_flag_low(true)
                .set_mode(synth_u32_le_reg::SynthU32LeMode::Three)
                .set_range(u32_le_chained_range)
                .set_flag_high(false);
            assert!(v_chained.flag_low());
            assert_eq!(v_chained.mode(), Ok(synth_u32_le_reg::SynthU32LeMode::Three));
            assert_eq!(v_chained.range(), u32_le_chained_range);
            assert!(!v_chained.flag_high());
            assert_eq!(v_chained.reg_value() & U32_LE_RESERVED_MASK, reserved);
        }

        // 2. Big-endian u32 register
        assert_eq!(
            U32_BE_RESERVED_MASK
                | U32_BE_FLAG_LOW_MASK
                | U32_BE_MODE_MASK
                | U32_BE_CHUNK_MASK
                | U32_BE_FLAG_HIGH_MASK,
            u32::MAX
        );

        let u32_be_chained_chunk = 0x6E;

        for &base in &U32_TEST_PATTERNS {
            let v = synth_u32_be_reg::Value::new(base);
            let reserved = base & U32_BE_RESERVED_MASK;

            let v_fl = v.set_flag_low(!v.flag_low());
            assert_eq!(v_fl.flag_low(), !v.flag_low());
            assert_eq!(v_fl.reg_value() & U32_BE_RESERVED_MASK, reserved);
            assert_eq!(v_fl.reg_value() ^ v.reg_value(), U32_BE_FLAG_LOW_MASK);

            let new_mode = synth_u32_be_reg::SynthU32BeMode::Quaternary;
            let v_mode = v.set_mode(new_mode);
            assert_eq!(v_mode.mode(), Ok(new_mode));
            assert_eq!(v_mode.reg_value() & U32_BE_RESERVED_MASK, reserved);
            assert_eq!((v_mode.reg_value() ^ v.reg_value()) & !U32_BE_MODE_MASK, 0);

            let new_chunk = (v.chunk() + 1) & U32_BE_CHUNK_FIELD_MASK;
            let v_chunk = v.set_chunk(new_chunk);
            assert_eq!(v_chunk.chunk(), new_chunk);
            assert_eq!(v_chunk.reg_value() & U32_BE_RESERVED_MASK, reserved);
            assert_eq!((v_chunk.reg_value() ^ v.reg_value()) & !U32_BE_CHUNK_MASK, 0);

            let v_fh = v.set_flag_high(!v.flag_high());
            assert_eq!(v_fh.flag_high(), !v.flag_high());
            assert_eq!(v_fh.reg_value() & U32_BE_RESERVED_MASK, reserved);
            assert_eq!(v_fh.reg_value() ^ v.reg_value(), U32_BE_FLAG_HIGH_MASK);

            let v_chained = v
                .set_flag_low(false)
                .set_mode(synth_u32_be_reg::SynthU32BeMode::Secondary)
                .set_chunk(u32_be_chained_chunk)
                .set_flag_high(true);
            assert!(!v_chained.flag_low());
            assert_eq!(v_chained.mode(), Ok(synth_u32_be_reg::SynthU32BeMode::Secondary));
            assert_eq!(v_chained.chunk(), u32_be_chained_chunk);
            assert!(v_chained.flag_high());
            assert_eq!(v_chained.reg_value() & U32_BE_RESERVED_MASK, reserved);
        }
    }

    // Verifies read-modify-write over SPMI preserves unmapped and reserved bits in LE registers.
    #[fuchsia::test]
    async fn test_spmi_read_modify_write_preserves_reserved_bits_le() {
        let device = TestSpmiDevice::new();
        let regs = SynthRegs::new(device);

        // 1. Test u8 register with complementary seeds (verifies 0 and 1 bit preservation).
        let u8_write_multi = 3;
        for u8_reserved_seed in [
            U8_RESERVED_MASK & U8_ALTERNATING_BITS_HIGH,
            U8_RESERVED_MASK & U8_ALTERNATING_BITS_LOW,
        ] {
            // Verify the seed has a non-trivial mixture of 0 and 1 bits.
            assert!(u8_reserved_seed != 0 && u8_reserved_seed != U8_RESERVED_MASK);

            regs.spmi.write_reg(synth_u8_reg::ADDRESS, &[u8_reserved_seed]).await.unwrap();
            let val_u8 = regs.u8_reg().read().await.unwrap();
            let updated_u8 = val_u8
                .set_enable(true)
                .set_multi(u8_write_multi)
                .set_mode(synth_u8_reg::SynthU8Mode::Mode1);
            regs.u8_reg().write(updated_u8).await.unwrap();

            let raw_u8 = regs.spmi.read_reg(synth_u8_reg::ADDRESS, U8_REG_BYTES).await.unwrap()[0];
            assert_eq!(
                raw_u8 & U8_RESERVED_MASK,
                u8_reserved_seed,
                "u8 reserved bits mismatch for seed {u8_reserved_seed:#04x}"
            );
            let final_u8 = regs.u8_reg().read().await.unwrap();
            assert!(final_u8.enable());
            assert_eq!(final_u8.multi(), u8_write_multi);
            assert_eq!(final_u8.mode(), Ok(synth_u8_reg::SynthU8Mode::Mode1));
        }

        // 2. Test u16 LE register with complementary seeds (verifies 0 and 1 bit preservation).
        let u16_le_write_data = 0x9;
        for u16_le_reserved_seed in [
            U16_LE_RESERVED_MASK & U16_ALTERNATING_BITS_HIGH,
            U16_LE_RESERVED_MASK & U16_ALTERNATING_BITS_LOW,
        ] {
            // Verify the seed has a non-trivial mixture of 0 and 1 bits.
            assert!(u16_le_reserved_seed != 0 && u16_le_reserved_seed != U16_LE_RESERVED_MASK);

            regs.spmi
                .write_reg(synth_u16_le_reg::ADDRESS, &u16_le_reserved_seed.to_le_bytes())
                .await
                .unwrap();
            let val_u16 = regs.u16_le_reg().read().await.unwrap();
            let updated_u16 = val_u16
                .set_flag_low(true)
                .set_flag_high(true)
                .set_data(u16_le_write_data)
                .set_mode(synth_u16_le_reg::SynthU16LeMode::Active);
            regs.u16_le_reg().write(updated_u16).await.unwrap();

            let raw_u16_bytes =
                regs.spmi.read_reg(synth_u16_le_reg::ADDRESS, U16_REG_BYTES).await.unwrap();
            let raw_u16 = u16::from_le_bytes(raw_u16_bytes.try_into().unwrap());
            assert_eq!(
                raw_u16 & U16_LE_RESERVED_MASK,
                u16_le_reserved_seed,
                "u16 LE reserved bits mismatch for seed {u16_le_reserved_seed:#06x}"
            );
            let final_u16 = regs.u16_le_reg().read().await.unwrap();
            assert!(final_u16.flag_low());
            assert!(final_u16.flag_high());
            assert_eq!(final_u16.data(), u16_le_write_data);
            assert_eq!(final_u16.mode(), Ok(synth_u16_le_reg::SynthU16LeMode::Active));
        }

        // 3. Test u32 LE register with complementary seeds (verifies 0 and 1 bit preservation).
        let u32_le_write_range = 0x42;
        for u32_le_reserved_seed in [
            U32_LE_RESERVED_MASK & U32_ALTERNATING_BITS_HIGH,
            U32_LE_RESERVED_MASK & U32_ALTERNATING_BITS_LOW,
        ] {
            // Verify the seed has a non-trivial mixture of 0 and 1 bits.
            assert!(u32_le_reserved_seed != 0 && u32_le_reserved_seed != U32_LE_RESERVED_MASK);

            regs.spmi
                .write_reg(synth_u32_le_reg::ADDRESS, &u32_le_reserved_seed.to_le_bytes())
                .await
                .unwrap();
            let val_u32 = regs.u32_le_reg().read().await.unwrap();
            let updated_u32 = val_u32
                .set_flag_low(true)
                .set_flag_high(true)
                .set_range(u32_le_write_range)
                .set_mode(synth_u32_le_reg::SynthU32LeMode::Two);
            regs.u32_le_reg().write(updated_u32).await.unwrap();

            let raw_u32_bytes =
                regs.spmi.read_reg(synth_u32_le_reg::ADDRESS, U32_REG_BYTES).await.unwrap();
            let raw_u32 = u32::from_le_bytes(raw_u32_bytes.try_into().unwrap());
            assert_eq!(
                raw_u32 & U32_LE_RESERVED_MASK,
                u32_le_reserved_seed,
                "u32 LE reserved bits mismatch for seed {u32_le_reserved_seed:#010x}"
            );
            let final_u32 = regs.u32_le_reg().read().await.unwrap();
            assert!(final_u32.flag_low());
            assert!(final_u32.flag_high());
            assert_eq!(final_u32.range(), u32_le_write_range);
            assert_eq!(final_u32.mode(), Ok(synth_u32_le_reg::SynthU32LeMode::Two));
        }
    }

    // Verifies read-modify-write over SPMI preserves unmapped and reserved bits in BE registers.
    #[fuchsia::test]
    async fn test_spmi_read_modify_write_preserves_reserved_bits_be() {
        let device = TestSpmiDevice::new();
        let regs = SynthRegs::new(device);

        // 1. Test u16 BE register with complementary seeds (verifies 0 and 1 bit preservation).
        let u16_be_write_count = 0xB;
        for u16_be_reserved_seed in [
            U16_BE_RESERVED_MASK & U16_ALTERNATING_BITS_HIGH,
            U16_BE_RESERVED_MASK & U16_ALTERNATING_BITS_LOW,
        ] {
            // Verify the seed has a non-trivial mixture of 0 and 1 bits.
            assert!(u16_be_reserved_seed != 0 && u16_be_reserved_seed != U16_BE_RESERVED_MASK);

            regs.spmi
                .write_reg(synth_u16_be_reg::ADDRESS, &u16_be_reserved_seed.to_be_bytes())
                .await
                .unwrap();
            let val_u16 = regs.u16_be_reg().read().await.unwrap();
            let updated_u16 = val_u16
                .set_flag_low(true)
                .set_flag_high(true)
                .set_count(u16_be_write_count)
                .set_mode(synth_u16_be_reg::SynthU16BeMode::Delta);
            regs.u16_be_reg().write(updated_u16).await.unwrap();

            let raw_u16_bytes =
                regs.spmi.read_reg(synth_u16_be_reg::ADDRESS, U16_REG_BYTES).await.unwrap();
            let raw_u16 = u16::from_be_bytes(raw_u16_bytes.try_into().unwrap());
            assert_eq!(
                raw_u16 & U16_BE_RESERVED_MASK,
                u16_be_reserved_seed,
                "u16 BE reserved bits mismatch for seed {u16_be_reserved_seed:#06x}"
            );
            let final_u16 = regs.u16_be_reg().read().await.unwrap();
            assert!(final_u16.flag_low());
            assert!(final_u16.flag_high());
            assert_eq!(final_u16.count(), u16_be_write_count);
            assert_eq!(final_u16.mode(), Ok(synth_u16_be_reg::SynthU16BeMode::Delta));
        }

        // 2. Test u32 BE register with complementary seeds (verifies 0 and 1 bit preservation).
        let u32_be_write_chunk = 0x55;
        for u32_be_reserved_seed in [
            U32_BE_RESERVED_MASK & U32_ALTERNATING_BITS_HIGH,
            U32_BE_RESERVED_MASK & U32_ALTERNATING_BITS_LOW,
        ] {
            // Verify the seed has a non-trivial mixture of 0 and 1 bits.
            assert!(u32_be_reserved_seed != 0 && u32_be_reserved_seed != U32_BE_RESERVED_MASK);

            regs.spmi
                .write_reg(synth_u32_be_reg::ADDRESS, &u32_be_reserved_seed.to_be_bytes())
                .await
                .unwrap();
            let val_u32 = regs.u32_be_reg().read().await.unwrap();
            let updated_u32 = val_u32
                .set_flag_low(true)
                .set_flag_high(true)
                .set_chunk(u32_be_write_chunk)
                .set_mode(synth_u32_be_reg::SynthU32BeMode::Tertiary);
            regs.u32_be_reg().write(updated_u32).await.unwrap();

            let raw_u32_bytes =
                regs.spmi.read_reg(synth_u32_be_reg::ADDRESS, U32_REG_BYTES).await.unwrap();
            let raw_u32 = u32::from_be_bytes(raw_u32_bytes.try_into().unwrap());
            assert_eq!(
                raw_u32 & U32_BE_RESERVED_MASK,
                u32_be_reserved_seed,
                "u32 BE reserved bits mismatch for seed {u32_be_reserved_seed:#010x}"
            );
            let final_u32 = regs.u32_be_reg().read().await.unwrap();
            assert!(final_u32.flag_low());
            assert!(final_u32.flag_high());
            assert_eq!(final_u32.chunk(), u32_be_write_chunk);
            assert_eq!(final_u32.mode(), Ok(synth_u32_be_reg::SynthU32BeMode::Tertiary));
        }
    }
}