mirror of
https://github.com/torvalds/linux.git
synced 2025-12-01 07:26:02 +07:00
0988099646
Add support for declaring arrays of registers available from a variable base. This is effectively a combination of the relative and array registers features. nova-core does not make much use of this yet, but it will become helpful to have for GSP boot. Reviewed-by: Lyude Paul <lyude@redhat.com> Link: https://lore.kernel.org/r/20250718-nova-regs-v2-19-7b6a762aa1cd@nvidia.com Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
961 lines
36 KiB
Rust
961 lines
36 KiB
Rust
// SPDX-License-Identifier: GPL-2.0
|
|
|
|
//! `register!` macro to define register layout and accessors.
|
|
//!
|
|
//! A single register typically includes several fields, which are accessed through a combination
|
|
//! of bit-shift and mask operations that introduce a class of potential mistakes, notably because
|
|
//! not all possible field values are necessarily valid.
|
|
//!
|
|
//! The `register!` macro in this module provides an intuitive and readable syntax for defining a
|
|
//! dedicated type for each register. Each such type comes with its own field accessors that can
|
|
//! return an error if a field's value is invalid.
|
|
|
|
/// Trait providing a base address to be added to the offset of a relative register to obtain
|
|
/// its actual offset.
|
|
///
|
|
/// The `T` generic argument is used to distinguish which base to use, in case a type provides
|
|
/// several bases. It is given to the `register!` macro to restrict the use of the register to
|
|
/// implementors of this particular variant.
|
|
pub(crate) trait RegisterBase<T> {
|
|
const BASE: usize;
|
|
}
|
|
|
|
/// Defines a dedicated type for a register with an absolute offset, including getter and setter
|
|
/// methods for its fields and methods to read and write it from an `Io` region.
|
|
///
|
|
/// Example:
|
|
///
|
|
/// ```no_run
|
|
/// register!(BOOT_0 @ 0x00000100, "Basic revision information about the GPU" {
|
|
/// 3:0 minor_revision as u8, "Minor revision of the chip";
|
|
/// 7:4 major_revision as u8, "Major revision of the chip";
|
|
/// 28:20 chipset as u32 ?=> Chipset, "Chipset model";
|
|
/// });
|
|
/// ```
|
|
///
|
|
/// This defines a `BOOT_0` type which can be read or written from offset `0x100` of an `Io`
|
|
/// region. It is composed of 3 fields, for instance `minor_revision` is made of the 4 least
|
|
/// significant bits of the register. Each field can be accessed and modified using accessor
|
|
/// methods:
|
|
///
|
|
/// ```no_run
|
|
/// // Read from the register's defined offset (0x100).
|
|
/// let boot0 = BOOT_0::read(&bar);
|
|
/// pr_info!("chip revision: {}.{}", boot0.major_revision(), boot0.minor_revision());
|
|
///
|
|
/// // `Chipset::try_from` is called with the value of the `chipset` field and returns an
|
|
/// // error if it is invalid.
|
|
/// let chipset = boot0.chipset()?;
|
|
///
|
|
/// // Update some fields and write the value back.
|
|
/// boot0.set_major_revision(3).set_minor_revision(10).write(&bar);
|
|
///
|
|
/// // Or, just read and update the register in a single step:
|
|
/// BOOT_0::alter(&bar, |r| r.set_major_revision(3).set_minor_revision(10));
|
|
/// ```
|
|
///
|
|
/// Fields are defined as follows:
|
|
///
|
|
/// - `as <type>` simply returns the field value casted to <type>, typically `u32`, `u16`, `u8` or
|
|
/// `bool`. Note that `bool` fields must have a range of 1 bit.
|
|
/// - `as <type> => <into_type>` calls `<into_type>`'s `From::<<type>>` implementation and returns
|
|
/// the result.
|
|
/// - `as <type> ?=> <try_into_type>` calls `<try_into_type>`'s `TryFrom::<<type>>` implementation
|
|
/// and returns the result. This is useful with fields for which not all values are valid.
|
|
///
|
|
/// The documentation strings are optional. If present, they will be added to the type's
|
|
/// definition, or the field getter and setter methods they are attached to.
|
|
///
|
|
/// It is also possible to create a alias register by using the `=> ALIAS` syntax. This is useful
|
|
/// for cases where a register's interpretation depends on the context:
|
|
///
|
|
/// ```no_run
|
|
/// register!(SCRATCH @ 0x00000200, "Scratch register" {
|
|
/// 31:0 value as u32, "Raw value";
|
|
/// });
|
|
///
|
|
/// register!(SCRATCH_BOOT_STATUS => SCRATCH, "Boot status of the firmware" {
|
|
/// 0:0 completed as bool, "Whether the firmware has completed booting";
|
|
/// });
|
|
/// ```
|
|
///
|
|
/// In this example, `SCRATCH_0_BOOT_STATUS` uses the same I/O address as `SCRATCH`, while also
|
|
/// providing its own `completed` field.
|
|
///
|
|
/// ## Relative registers
|
|
///
|
|
/// A register can be defined as being accessible from a fixed offset of a provided base. For
|
|
/// instance, imagine the following I/O space:
|
|
///
|
|
/// ```text
|
|
/// +-----------------------------+
|
|
/// | ... |
|
|
/// | |
|
|
/// 0x100--->+------------CPU0-------------+
|
|
/// | |
|
|
/// 0x110--->+-----------------------------+
|
|
/// | CPU_CTL |
|
|
/// +-----------------------------+
|
|
/// | ... |
|
|
/// | |
|
|
/// | |
|
|
/// 0x200--->+------------CPU1-------------+
|
|
/// | |
|
|
/// 0x210--->+-----------------------------+
|
|
/// | CPU_CTL |
|
|
/// +-----------------------------+
|
|
/// | ... |
|
|
/// +-----------------------------+
|
|
/// ```
|
|
///
|
|
/// `CPU0` and `CPU1` both have a `CPU_CTL` register that starts at offset `0x10` of their I/O
|
|
/// space segment. Since both instances of `CPU_CTL` share the same layout, we don't want to define
|
|
/// them twice and would prefer a way to select which one to use from a single definition
|
|
///
|
|
/// This can be done using the `Base[Offset]` syntax when specifying the register's address.
|
|
///
|
|
/// `Base` is an arbitrary type (typically a ZST) to be used as a generic parameter of the
|
|
/// [`RegisterBase`] trait to provide the base as a constant, i.e. each type providing a base for
|
|
/// this register needs to implement `RegisterBase<Base>`. Here is the above example translated
|
|
/// into code:
|
|
///
|
|
/// ```no_run
|
|
/// // Type used to identify the base.
|
|
/// pub(crate) struct CpuCtlBase;
|
|
///
|
|
/// // ZST describing `CPU0`.
|
|
/// struct Cpu0;
|
|
/// impl RegisterBase<CpuCtlBase> for Cpu0 {
|
|
/// const BASE: usize = 0x100;
|
|
/// }
|
|
/// // Singleton of `CPU0` used to identify it.
|
|
/// const CPU0: Cpu0 = Cpu0;
|
|
///
|
|
/// // ZST describing `CPU1`.
|
|
/// struct Cpu1;
|
|
/// impl RegisterBase<CpuCtlBase> for Cpu1 {
|
|
/// const BASE: usize = 0x200;
|
|
/// }
|
|
/// // Singleton of `CPU1` used to identify it.
|
|
/// const CPU1: Cpu1 = Cpu1;
|
|
///
|
|
/// // This makes `CPU_CTL` accessible from all implementors of `RegisterBase<CpuCtlBase>`.
|
|
/// register!(CPU_CTL @ CpuCtlBase[0x10], "CPU core control" {
|
|
/// 0:0 start as bool, "Start the CPU core";
|
|
/// });
|
|
///
|
|
/// // The `read`, `write` and `alter` methods of relative registers take an extra `base` argument
|
|
/// // that is used to resolve its final address by adding its `BASE` to the offset of the
|
|
/// // register.
|
|
///
|
|
/// // Start `CPU0`.
|
|
/// CPU_CTL::alter(bar, &CPU0, |r| r.set_start(true));
|
|
///
|
|
/// // Start `CPU1`.
|
|
/// CPU_CTL::alter(bar, &CPU1, |r| r.set_start(true));
|
|
///
|
|
/// // Aliases can also be defined for relative register.
|
|
/// register!(CPU_CTL_ALIAS => CpuCtlBase[CPU_CTL], "Alias to CPU core control" {
|
|
/// 1:1 alias_start as bool, "Start the aliased CPU core";
|
|
/// });
|
|
///
|
|
/// // Start the aliased `CPU0`.
|
|
/// CPU_CTL_ALIAS::alter(bar, &CPU0, |r| r.set_alias_start(true));
|
|
/// ```
|
|
///
|
|
/// ## Arrays of registers
|
|
///
|
|
/// Some I/O areas contain consecutive values that can be interpreted in the same way. These areas
|
|
/// can be defined as an array of identical registers, allowing them to be accessed by index with
|
|
/// compile-time or runtime bound checking. Simply define their address as `Address[Size]`, and add
|
|
/// an `idx` parameter to their `read`, `write` and `alter` methods:
|
|
///
|
|
/// ```no_run
|
|
/// # fn no_run() -> Result<(), Error> {
|
|
/// # fn get_scratch_idx() -> usize {
|
|
/// # 0x15
|
|
/// # }
|
|
/// // Array of 64 consecutive registers with the same layout starting at offset `0x80`.
|
|
/// register!(SCRATCH @ 0x00000080[64], "Scratch registers" {
|
|
/// 31:0 value as u32;
|
|
/// });
|
|
///
|
|
/// // Read scratch register 0, i.e. I/O address `0x80`.
|
|
/// let scratch_0 = SCRATCH::read(bar, 0).value();
|
|
/// // Read scratch register 15, i.e. I/O address `0x80 + (15 * 4)`.
|
|
/// let scratch_15 = SCRATCH::read(bar, 15).value();
|
|
///
|
|
/// // This is out of bounds and won't build.
|
|
/// // let scratch_128 = SCRATCH::read(bar, 128).value();
|
|
///
|
|
/// // Runtime-obtained array index.
|
|
/// let scratch_idx = get_scratch_idx();
|
|
/// // Access on a runtime index returns an error if it is out-of-bounds.
|
|
/// let some_scratch = SCRATCH::try_read(bar, scratch_idx)?.value();
|
|
///
|
|
/// // Alias to a particular register in an array.
|
|
/// // Here `SCRATCH[8]` is used to convey the firmware exit code.
|
|
/// register!(FIRMWARE_STATUS => SCRATCH[8], "Firmware exit status code" {
|
|
/// 7:0 status as u8;
|
|
/// });
|
|
///
|
|
/// let status = FIRMWARE_STATUS::read(bar).status();
|
|
///
|
|
/// // Non-contiguous register arrays can be defined by adding a stride parameter.
|
|
/// // Here, each of the 16 registers of the array are separated by 8 bytes, meaning that the
|
|
/// // registers of the two declarations below are interleaved.
|
|
/// register!(SCRATCH_INTERLEAVED_0 @ 0x000000c0[16 ; 8], "Scratch registers bank 0" {
|
|
/// 31:0 value as u32;
|
|
/// });
|
|
/// register!(SCRATCH_INTERLEAVED_1 @ 0x000000c4[16 ; 8], "Scratch registers bank 1" {
|
|
/// 31:0 value as u32;
|
|
/// });
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
///
|
|
/// ## Relative arrays of registers
|
|
///
|
|
/// Combining the two features described in the sections above, arrays of registers accessible from
|
|
/// a base can also be defined:
|
|
///
|
|
/// ```no_run
|
|
/// # fn no_run() -> Result<(), Error> {
|
|
/// # fn get_scratch_idx() -> usize {
|
|
/// # 0x15
|
|
/// # }
|
|
/// // Type used as parameter of `RegisterBase` to specify the base.
|
|
/// pub(crate) struct CpuCtlBase;
|
|
///
|
|
/// // ZST describing `CPU0`.
|
|
/// struct Cpu0;
|
|
/// impl RegisterBase<CpuCtlBase> for Cpu0 {
|
|
/// const BASE: usize = 0x100;
|
|
/// }
|
|
/// // Singleton of `CPU0` used to identify it.
|
|
/// const CPU0: Cpu0 = Cpu0;
|
|
///
|
|
/// // ZST describing `CPU1`.
|
|
/// struct Cpu1;
|
|
/// impl RegisterBase<CpuCtlBase> for Cpu1 {
|
|
/// const BASE: usize = 0x200;
|
|
/// }
|
|
/// // Singleton of `CPU1` used to identify it.
|
|
/// const CPU1: Cpu1 = Cpu1;
|
|
///
|
|
/// // 64 per-cpu scratch registers, arranged as an contiguous array.
|
|
/// register!(CPU_SCRATCH @ CpuCtlBase[0x00000080[64]], "Per-CPU scratch registers" {
|
|
/// 31:0 value as u32;
|
|
/// });
|
|
///
|
|
/// let cpu0_scratch_0 = CPU_SCRATCH::read(bar, &Cpu0, 0).value();
|
|
/// let cpu1_scratch_15 = CPU_SCRATCH::read(bar, &Cpu1, 15).value();
|
|
///
|
|
/// // This won't build.
|
|
/// // let cpu0_scratch_128 = CPU_SCRATCH::read(bar, &Cpu0, 128).value();
|
|
///
|
|
/// // Runtime-obtained array index.
|
|
/// let scratch_idx = get_scratch_idx();
|
|
/// // Access on a runtime value returns an error if it is out-of-bounds.
|
|
/// let cpu0_some_scratch = CPU_SCRATCH::try_read(bar, &Cpu0, scratch_idx)?.value();
|
|
///
|
|
/// // `SCRATCH[8]` is used to convey the firmware exit code.
|
|
/// register!(CPU_FIRMWARE_STATUS => CpuCtlBase[CPU_SCRATCH[8]],
|
|
/// "Per-CPU firmware exit status code" {
|
|
/// 7:0 status as u8;
|
|
/// });
|
|
///
|
|
/// let cpu0_status = CPU_FIRMWARE_STATUS::read(bar, &Cpu0).status();
|
|
///
|
|
/// // Non-contiguous register arrays can be defined by adding a stride parameter.
|
|
/// // Here, each of the 16 registers of the array are separated by 8 bytes, meaning that the
|
|
/// // registers of the two declarations below are interleaved.
|
|
/// register!(CPU_SCRATCH_INTERLEAVED_0 @ CpuCtlBase[0x00000d00[16 ; 8]],
|
|
/// "Scratch registers bank 0" {
|
|
/// 31:0 value as u32;
|
|
/// });
|
|
/// register!(CPU_SCRATCH_INTERLEAVED_1 @ CpuCtlBase[0x00000d04[16 ; 8]],
|
|
/// "Scratch registers bank 1" {
|
|
/// 31:0 value as u32;
|
|
/// });
|
|
/// # Ok(())
|
|
/// # }
|
|
/// ```
|
|
macro_rules! register {
|
|
// Creates a register at a fixed offset of the MMIO space.
|
|
($name:ident @ $offset:literal $(, $comment:literal)? { $($fields:tt)* } ) => {
|
|
register!(@core $name $(, $comment)? { $($fields)* } );
|
|
register!(@io_fixed $name @ $offset);
|
|
};
|
|
|
|
// Creates an alias register of fixed offset register `alias` with its own fields.
|
|
($name:ident => $alias:ident $(, $comment:literal)? { $($fields:tt)* } ) => {
|
|
register!(@core $name $(, $comment)? { $($fields)* } );
|
|
register!(@io_fixed $name @ $alias::OFFSET);
|
|
};
|
|
|
|
// Creates a register at a relative offset from a base address provider.
|
|
($name:ident @ $base:ty [ $offset:literal ] $(, $comment:literal)? { $($fields:tt)* } ) => {
|
|
register!(@core $name $(, $comment)? { $($fields)* } );
|
|
register!(@io_relative $name @ $base [ $offset ]);
|
|
};
|
|
|
|
// Creates an alias register of relative offset register `alias` with its own fields.
|
|
($name:ident => $base:ty [ $alias:ident ] $(, $comment:literal)? { $($fields:tt)* }) => {
|
|
register!(@core $name $(, $comment)? { $($fields)* } );
|
|
register!(@io_relative $name @ $base [ $alias::OFFSET ]);
|
|
};
|
|
|
|
// Creates an array of registers at a fixed offset of the MMIO space.
|
|
(
|
|
$name:ident @ $offset:literal [ $size:expr ; $stride:expr ] $(, $comment:literal)? {
|
|
$($fields:tt)*
|
|
}
|
|
) => {
|
|
static_assert!(::core::mem::size_of::<u32>() <= $stride);
|
|
register!(@core $name $(, $comment)? { $($fields)* } );
|
|
register!(@io_array $name @ $offset [ $size ; $stride ]);
|
|
};
|
|
|
|
// Shortcut for contiguous array of registers (stride == size of element).
|
|
(
|
|
$name:ident @ $offset:literal [ $size:expr ] $(, $comment:literal)? {
|
|
$($fields:tt)*
|
|
}
|
|
) => {
|
|
register!($name @ $offset [ $size ; ::core::mem::size_of::<u32>() ] $(, $comment)? {
|
|
$($fields)*
|
|
} );
|
|
};
|
|
|
|
// Creates an array of registers at a relative offset from a base address provider.
|
|
(
|
|
$name:ident @ $base:ty [ $offset:literal [ $size:expr ; $stride:expr ] ]
|
|
$(, $comment:literal)? { $($fields:tt)* }
|
|
) => {
|
|
static_assert!(::core::mem::size_of::<u32>() <= $stride);
|
|
register!(@core $name $(, $comment)? { $($fields)* } );
|
|
register!(@io_relative_array $name @ $base [ $offset [ $size ; $stride ] ]);
|
|
};
|
|
|
|
// Shortcut for contiguous array of relative registers (stride == size of element).
|
|
(
|
|
$name:ident @ $base:ty [ $offset:literal [ $size:expr ] ] $(, $comment:literal)? {
|
|
$($fields:tt)*
|
|
}
|
|
) => {
|
|
register!($name @ $base [ $offset [ $size ; ::core::mem::size_of::<u32>() ] ]
|
|
$(, $comment)? { $($fields)* } );
|
|
};
|
|
|
|
// Creates an alias of register `idx` of relative array of registers `alias` with its own
|
|
// fields.
|
|
(
|
|
$name:ident => $base:ty [ $alias:ident [ $idx:expr ] ] $(, $comment:literal)? {
|
|
$($fields:tt)*
|
|
}
|
|
) => {
|
|
static_assert!($idx < $alias::SIZE);
|
|
register!(@core $name $(, $comment)? { $($fields)* } );
|
|
register!(@io_relative $name @ $base [ $alias::OFFSET + $idx * $alias::STRIDE ] );
|
|
};
|
|
|
|
// Creates an alias of register `idx` of array of registers `alias` with its own fields.
|
|
// This rule belongs to the (non-relative) register arrays set, but needs to be put last
|
|
// to avoid it being interpreted in place of the relative register array alias rule.
|
|
($name:ident => $alias:ident [ $idx:expr ] $(, $comment:literal)? { $($fields:tt)* }) => {
|
|
static_assert!($idx < $alias::SIZE);
|
|
register!(@core $name $(, $comment)? { $($fields)* } );
|
|
register!(@io_fixed $name @ $alias::OFFSET + $idx * $alias::STRIDE );
|
|
};
|
|
|
|
// All rules below are helpers.
|
|
|
|
// Defines the wrapper `$name` type, as well as its relevant implementations (`Debug`,
|
|
// `Default`, `BitOr`, and conversion to the value type) and field accessor methods.
|
|
(@core $name:ident $(, $comment:literal)? { $($fields:tt)* }) => {
|
|
$(
|
|
#[doc=$comment]
|
|
)?
|
|
#[repr(transparent)]
|
|
#[derive(Clone, Copy)]
|
|
pub(crate) struct $name(u32);
|
|
|
|
impl ::core::ops::BitOr for $name {
|
|
type Output = Self;
|
|
|
|
fn bitor(self, rhs: Self) -> Self::Output {
|
|
Self(self.0 | rhs.0)
|
|
}
|
|
}
|
|
|
|
impl ::core::convert::From<$name> for u32 {
|
|
fn from(reg: $name) -> u32 {
|
|
reg.0
|
|
}
|
|
}
|
|
|
|
register!(@fields_dispatcher $name { $($fields)* });
|
|
};
|
|
|
|
// Captures the fields and passes them to all the implementers that require field information.
|
|
//
|
|
// Used to simplify the matching rules for implementers, so they don't need to match the entire
|
|
// complex fields rule even though they only make use of part of it.
|
|
(@fields_dispatcher $name:ident {
|
|
$($hi:tt:$lo:tt $field:ident as $type:tt
|
|
$(?=> $try_into_type:ty)?
|
|
$(=> $into_type:ty)?
|
|
$(, $comment:literal)?
|
|
;
|
|
)*
|
|
}
|
|
) => {
|
|
register!(@field_accessors $name {
|
|
$(
|
|
$hi:$lo $field as $type
|
|
$(?=> $try_into_type)?
|
|
$(=> $into_type)?
|
|
$(, $comment)?
|
|
;
|
|
)*
|
|
});
|
|
register!(@debug $name { $($field;)* });
|
|
register!(@default $name { $($field;)* });
|
|
};
|
|
|
|
// Defines all the field getter/methods methods for `$name`.
|
|
(
|
|
@field_accessors $name:ident {
|
|
$($hi:tt:$lo:tt $field:ident as $type:tt
|
|
$(?=> $try_into_type:ty)?
|
|
$(=> $into_type:ty)?
|
|
$(, $comment:literal)?
|
|
;
|
|
)*
|
|
}
|
|
) => {
|
|
$(
|
|
register!(@check_field_bounds $hi:$lo $field as $type);
|
|
)*
|
|
|
|
#[allow(dead_code)]
|
|
impl $name {
|
|
$(
|
|
register!(@field_accessor $name $hi:$lo $field as $type
|
|
$(?=> $try_into_type)?
|
|
$(=> $into_type)?
|
|
$(, $comment)?
|
|
;
|
|
);
|
|
)*
|
|
}
|
|
};
|
|
|
|
// Boolean fields must have `$hi == $lo`.
|
|
(@check_field_bounds $hi:tt:$lo:tt $field:ident as bool) => {
|
|
#[allow(clippy::eq_op)]
|
|
const _: () = {
|
|
::kernel::build_assert!(
|
|
$hi == $lo,
|
|
concat!("boolean field `", stringify!($field), "` covers more than one bit")
|
|
);
|
|
};
|
|
};
|
|
|
|
// Non-boolean fields must have `$hi >= $lo`.
|
|
(@check_field_bounds $hi:tt:$lo:tt $field:ident as $type:tt) => {
|
|
#[allow(clippy::eq_op)]
|
|
const _: () = {
|
|
::kernel::build_assert!(
|
|
$hi >= $lo,
|
|
concat!("field `", stringify!($field), "`'s MSB is smaller than its LSB")
|
|
);
|
|
};
|
|
};
|
|
|
|
// Catches fields defined as `bool` and convert them into a boolean value.
|
|
(
|
|
@field_accessor $name:ident $hi:tt:$lo:tt $field:ident as bool => $into_type:ty
|
|
$(, $comment:literal)?;
|
|
) => {
|
|
register!(
|
|
@leaf_accessor $name $hi:$lo $field
|
|
{ |f| <$into_type>::from(if f != 0 { true } else { false }) }
|
|
$into_type => $into_type $(, $comment)?;
|
|
);
|
|
};
|
|
|
|
// Shortcut for fields defined as `bool` without the `=>` syntax.
|
|
(
|
|
@field_accessor $name:ident $hi:tt:$lo:tt $field:ident as bool $(, $comment:literal)?;
|
|
) => {
|
|
register!(@field_accessor $name $hi:$lo $field as bool => bool $(, $comment)?;);
|
|
};
|
|
|
|
// Catches the `?=>` syntax for non-boolean fields.
|
|
(
|
|
@field_accessor $name:ident $hi:tt:$lo:tt $field:ident as $type:tt ?=> $try_into_type:ty
|
|
$(, $comment:literal)?;
|
|
) => {
|
|
register!(@leaf_accessor $name $hi:$lo $field
|
|
{ |f| <$try_into_type>::try_from(f as $type) } $try_into_type =>
|
|
::core::result::Result<
|
|
$try_into_type,
|
|
<$try_into_type as ::core::convert::TryFrom<$type>>::Error
|
|
>
|
|
$(, $comment)?;);
|
|
};
|
|
|
|
// Catches the `=>` syntax for non-boolean fields.
|
|
(
|
|
@field_accessor $name:ident $hi:tt:$lo:tt $field:ident as $type:tt => $into_type:ty
|
|
$(, $comment:literal)?;
|
|
) => {
|
|
register!(@leaf_accessor $name $hi:$lo $field
|
|
{ |f| <$into_type>::from(f as $type) } $into_type => $into_type $(, $comment)?;);
|
|
};
|
|
|
|
// Shortcut for non-boolean fields defined without the `=>` or `?=>` syntax.
|
|
(
|
|
@field_accessor $name:ident $hi:tt:$lo:tt $field:ident as $type:tt
|
|
$(, $comment:literal)?;
|
|
) => {
|
|
register!(@field_accessor $name $hi:$lo $field as $type => $type $(, $comment)?;);
|
|
};
|
|
|
|
// Generates the accessor methods for a single field.
|
|
(
|
|
@leaf_accessor $name:ident $hi:tt:$lo:tt $field:ident
|
|
{ $process:expr } $to_type:ty => $res_type:ty $(, $comment:literal)?;
|
|
) => {
|
|
::kernel::macros::paste!(
|
|
const [<$field:upper _RANGE>]: ::core::ops::RangeInclusive<u8> = $lo..=$hi;
|
|
const [<$field:upper _MASK>]: u32 = ((((1 << $hi) - 1) << 1) + 1) - ((1 << $lo) - 1);
|
|
const [<$field:upper _SHIFT>]: u32 = Self::[<$field:upper _MASK>].trailing_zeros();
|
|
);
|
|
|
|
$(
|
|
#[doc="Returns the value of this field:"]
|
|
#[doc=$comment]
|
|
)?
|
|
#[inline(always)]
|
|
pub(crate) fn $field(self) -> $res_type {
|
|
::kernel::macros::paste!(
|
|
const MASK: u32 = $name::[<$field:upper _MASK>];
|
|
const SHIFT: u32 = $name::[<$field:upper _SHIFT>];
|
|
);
|
|
let field = ((self.0 & MASK) >> SHIFT);
|
|
|
|
$process(field)
|
|
}
|
|
|
|
::kernel::macros::paste!(
|
|
$(
|
|
#[doc="Sets the value of this field:"]
|
|
#[doc=$comment]
|
|
)?
|
|
#[inline(always)]
|
|
pub(crate) fn [<set_ $field>](mut self, value: $to_type) -> Self {
|
|
const MASK: u32 = $name::[<$field:upper _MASK>];
|
|
const SHIFT: u32 = $name::[<$field:upper _SHIFT>];
|
|
let value = (u32::from(value) << SHIFT) & MASK;
|
|
self.0 = (self.0 & !MASK) | value;
|
|
|
|
self
|
|
}
|
|
);
|
|
};
|
|
|
|
// Generates the `Debug` implementation for `$name`.
|
|
(@debug $name:ident { $($field:ident;)* }) => {
|
|
impl ::core::fmt::Debug for $name {
|
|
fn fmt(&self, f: &mut ::core::fmt::Formatter<'_>) -> ::core::fmt::Result {
|
|
f.debug_struct(stringify!($name))
|
|
.field("<raw>", &format_args!("{:#x}", &self.0))
|
|
$(
|
|
.field(stringify!($field), &self.$field())
|
|
)*
|
|
.finish()
|
|
}
|
|
}
|
|
};
|
|
|
|
// Generates the `Default` implementation for `$name`.
|
|
(@default $name:ident { $($field:ident;)* }) => {
|
|
/// Returns a value for the register where all fields are set to their default value.
|
|
impl ::core::default::Default for $name {
|
|
fn default() -> Self {
|
|
#[allow(unused_mut)]
|
|
let mut value = Self(Default::default());
|
|
|
|
::kernel::macros::paste!(
|
|
$(
|
|
value.[<set_ $field>](Default::default());
|
|
)*
|
|
);
|
|
|
|
value
|
|
}
|
|
}
|
|
};
|
|
|
|
// Generates the IO accessors for a fixed offset register.
|
|
(@io_fixed $name:ident @ $offset:expr) => {
|
|
#[allow(dead_code)]
|
|
impl $name {
|
|
pub(crate) const OFFSET: usize = $offset;
|
|
|
|
/// Read the register from its address in `io`.
|
|
#[inline(always)]
|
|
pub(crate) fn read<const SIZE: usize, T>(io: &T) -> Self where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
{
|
|
Self(io.read32($offset))
|
|
}
|
|
|
|
/// Write the value contained in `self` to the register address in `io`.
|
|
#[inline(always)]
|
|
pub(crate) fn write<const SIZE: usize, T>(self, io: &T) where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
{
|
|
io.write32(self.0, $offset)
|
|
}
|
|
|
|
/// Read the register from its address in `io` and run `f` on its value to obtain a new
|
|
/// value to write back.
|
|
#[inline(always)]
|
|
pub(crate) fn alter<const SIZE: usize, T, F>(
|
|
io: &T,
|
|
f: F,
|
|
) where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
F: ::core::ops::FnOnce(Self) -> Self,
|
|
{
|
|
let reg = f(Self::read(io));
|
|
reg.write(io);
|
|
}
|
|
}
|
|
};
|
|
|
|
// Generates the IO accessors for a relative offset register.
|
|
(@io_relative $name:ident @ $base:ty [ $offset:expr ]) => {
|
|
#[allow(dead_code)]
|
|
impl $name {
|
|
pub(crate) const OFFSET: usize = $offset;
|
|
|
|
/// Read the register from `io`, using the base address provided by `base` and adding
|
|
/// the register's offset to it.
|
|
#[inline(always)]
|
|
pub(crate) fn read<const SIZE: usize, T, B>(
|
|
io: &T,
|
|
#[allow(unused_variables)]
|
|
base: &B,
|
|
) -> Self where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
B: crate::regs::macros::RegisterBase<$base>,
|
|
{
|
|
const OFFSET: usize = $name::OFFSET;
|
|
|
|
let value = io.read32(
|
|
<B as crate::regs::macros::RegisterBase<$base>>::BASE + OFFSET
|
|
);
|
|
|
|
Self(value)
|
|
}
|
|
|
|
/// Write the value contained in `self` to `io`, using the base address provided by
|
|
/// `base` and adding the register's offset to it.
|
|
#[inline(always)]
|
|
pub(crate) fn write<const SIZE: usize, T, B>(
|
|
self,
|
|
io: &T,
|
|
#[allow(unused_variables)]
|
|
base: &B,
|
|
) where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
B: crate::regs::macros::RegisterBase<$base>,
|
|
{
|
|
const OFFSET: usize = $name::OFFSET;
|
|
|
|
io.write32(
|
|
self.0,
|
|
<B as crate::regs::macros::RegisterBase<$base>>::BASE + OFFSET
|
|
);
|
|
}
|
|
|
|
/// Read the register from `io`, using the base address provided by `base` and adding
|
|
/// the register's offset to it, then run `f` on its value to obtain a new value to
|
|
/// write back.
|
|
#[inline(always)]
|
|
pub(crate) fn alter<const SIZE: usize, T, B, F>(
|
|
io: &T,
|
|
base: &B,
|
|
f: F,
|
|
) where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
B: crate::regs::macros::RegisterBase<$base>,
|
|
F: ::core::ops::FnOnce(Self) -> Self,
|
|
{
|
|
let reg = f(Self::read(io, base));
|
|
reg.write(io, base);
|
|
}
|
|
}
|
|
};
|
|
|
|
// Generates the IO accessors for an array of registers.
|
|
(@io_array $name:ident @ $offset:literal [ $size:expr ; $stride:expr ]) => {
|
|
#[allow(dead_code)]
|
|
impl $name {
|
|
pub(crate) const OFFSET: usize = $offset;
|
|
pub(crate) const SIZE: usize = $size;
|
|
pub(crate) const STRIDE: usize = $stride;
|
|
|
|
/// Read the array register at index `idx` from its address in `io`.
|
|
#[inline(always)]
|
|
pub(crate) fn read<const SIZE: usize, T>(
|
|
io: &T,
|
|
idx: usize,
|
|
) -> Self where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
{
|
|
build_assert!(idx < Self::SIZE);
|
|
|
|
let offset = Self::OFFSET + (idx * Self::STRIDE);
|
|
let value = io.read32(offset);
|
|
|
|
Self(value)
|
|
}
|
|
|
|
/// Write the value contained in `self` to the array register with index `idx` in `io`.
|
|
#[inline(always)]
|
|
pub(crate) fn write<const SIZE: usize, T>(
|
|
self,
|
|
io: &T,
|
|
idx: usize
|
|
) where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
{
|
|
build_assert!(idx < Self::SIZE);
|
|
|
|
let offset = Self::OFFSET + (idx * Self::STRIDE);
|
|
|
|
io.write32(self.0, offset);
|
|
}
|
|
|
|
/// Read the array register at index `idx` in `io` and run `f` on its value to obtain a
|
|
/// new value to write back.
|
|
#[inline(always)]
|
|
pub(crate) fn alter<const SIZE: usize, T, F>(
|
|
io: &T,
|
|
idx: usize,
|
|
f: F,
|
|
) where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
F: ::core::ops::FnOnce(Self) -> Self,
|
|
{
|
|
let reg = f(Self::read(io, idx));
|
|
reg.write(io, idx);
|
|
}
|
|
|
|
/// Read the array register at index `idx` from its address in `io`.
|
|
///
|
|
/// The validity of `idx` is checked at run-time, and `EINVAL` is returned is the
|
|
/// access was out-of-bounds.
|
|
#[inline(always)]
|
|
pub(crate) fn try_read<const SIZE: usize, T>(
|
|
io: &T,
|
|
idx: usize,
|
|
) -> ::kernel::error::Result<Self> where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
{
|
|
if idx < Self::SIZE {
|
|
Ok(Self::read(io, idx))
|
|
} else {
|
|
Err(EINVAL)
|
|
}
|
|
}
|
|
|
|
/// Write the value contained in `self` to the array register with index `idx` in `io`.
|
|
///
|
|
/// The validity of `idx` is checked at run-time, and `EINVAL` is returned is the
|
|
/// access was out-of-bounds.
|
|
#[inline(always)]
|
|
pub(crate) fn try_write<const SIZE: usize, T>(
|
|
self,
|
|
io: &T,
|
|
idx: usize,
|
|
) -> ::kernel::error::Result where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
{
|
|
if idx < Self::SIZE {
|
|
Ok(self.write(io, idx))
|
|
} else {
|
|
Err(EINVAL)
|
|
}
|
|
}
|
|
|
|
/// Read the array register at index `idx` in `io` and run `f` on its value to obtain a
|
|
/// new value to write back.
|
|
///
|
|
/// The validity of `idx` is checked at run-time, and `EINVAL` is returned is the
|
|
/// access was out-of-bounds.
|
|
#[inline(always)]
|
|
pub(crate) fn try_alter<const SIZE: usize, T, F>(
|
|
io: &T,
|
|
idx: usize,
|
|
f: F,
|
|
) -> ::kernel::error::Result where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
F: ::core::ops::FnOnce(Self) -> Self,
|
|
{
|
|
if idx < Self::SIZE {
|
|
Ok(Self::alter(io, idx, f))
|
|
} else {
|
|
Err(EINVAL)
|
|
}
|
|
}
|
|
}
|
|
};
|
|
|
|
// Generates the IO accessors for an array of relative registers.
|
|
(
|
|
@io_relative_array $name:ident @ $base:ty
|
|
[ $offset:literal [ $size:expr ; $stride:expr ] ]
|
|
) => {
|
|
#[allow(dead_code)]
|
|
impl $name {
|
|
pub(crate) const OFFSET: usize = $offset;
|
|
pub(crate) const SIZE: usize = $size;
|
|
pub(crate) const STRIDE: usize = $stride;
|
|
|
|
/// Read the array register at index `idx` from `io`, using the base address provided
|
|
/// by `base` and adding the register's offset to it.
|
|
#[inline(always)]
|
|
pub(crate) fn read<const SIZE: usize, T, B>(
|
|
io: &T,
|
|
#[allow(unused_variables)]
|
|
base: &B,
|
|
idx: usize,
|
|
) -> Self where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
B: crate::regs::macros::RegisterBase<$base>,
|
|
{
|
|
build_assert!(idx < Self::SIZE);
|
|
|
|
let offset = <B as crate::regs::macros::RegisterBase<$base>>::BASE +
|
|
Self::OFFSET + (idx * Self::STRIDE);
|
|
let value = io.read32(offset);
|
|
|
|
Self(value)
|
|
}
|
|
|
|
/// Write the value contained in `self` to `io`, using the base address provided by
|
|
/// `base` and adding the offset of array register `idx` to it.
|
|
#[inline(always)]
|
|
pub(crate) fn write<const SIZE: usize, T, B>(
|
|
self,
|
|
io: &T,
|
|
#[allow(unused_variables)]
|
|
base: &B,
|
|
idx: usize
|
|
) where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
B: crate::regs::macros::RegisterBase<$base>,
|
|
{
|
|
build_assert!(idx < Self::SIZE);
|
|
|
|
let offset = <B as crate::regs::macros::RegisterBase<$base>>::BASE +
|
|
Self::OFFSET + (idx * Self::STRIDE);
|
|
|
|
io.write32(self.0, offset);
|
|
}
|
|
|
|
/// Read the array register at index `idx` from `io`, using the base address provided
|
|
/// by `base` and adding the register's offset to it, then run `f` on its value to
|
|
/// obtain a new value to write back.
|
|
#[inline(always)]
|
|
pub(crate) fn alter<const SIZE: usize, T, B, F>(
|
|
io: &T,
|
|
base: &B,
|
|
idx: usize,
|
|
f: F,
|
|
) where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
B: crate::regs::macros::RegisterBase<$base>,
|
|
F: ::core::ops::FnOnce(Self) -> Self,
|
|
{
|
|
let reg = f(Self::read(io, base, idx));
|
|
reg.write(io, base, idx);
|
|
}
|
|
|
|
/// Read the array register at index `idx` from `io`, using the base address provided
|
|
/// by `base` and adding the register's offset to it.
|
|
///
|
|
/// The validity of `idx` is checked at run-time, and `EINVAL` is returned is the
|
|
/// access was out-of-bounds.
|
|
#[inline(always)]
|
|
pub(crate) fn try_read<const SIZE: usize, T, B>(
|
|
io: &T,
|
|
base: &B,
|
|
idx: usize,
|
|
) -> ::kernel::error::Result<Self> where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
B: crate::regs::macros::RegisterBase<$base>,
|
|
{
|
|
if idx < Self::SIZE {
|
|
Ok(Self::read(io, base, idx))
|
|
} else {
|
|
Err(EINVAL)
|
|
}
|
|
}
|
|
|
|
/// Write the value contained in `self` to `io`, using the base address provided by
|
|
/// `base` and adding the offset of array register `idx` to it.
|
|
///
|
|
/// The validity of `idx` is checked at run-time, and `EINVAL` is returned is the
|
|
/// access was out-of-bounds.
|
|
#[inline(always)]
|
|
pub(crate) fn try_write<const SIZE: usize, T, B>(
|
|
self,
|
|
io: &T,
|
|
base: &B,
|
|
idx: usize,
|
|
) -> ::kernel::error::Result where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
B: crate::regs::macros::RegisterBase<$base>,
|
|
{
|
|
if idx < Self::SIZE {
|
|
Ok(self.write(io, base, idx))
|
|
} else {
|
|
Err(EINVAL)
|
|
}
|
|
}
|
|
|
|
/// Read the array register at index `idx` from `io`, using the base address provided
|
|
/// by `base` and adding the register's offset to it, then run `f` on its value to
|
|
/// obtain a new value to write back.
|
|
///
|
|
/// The validity of `idx` is checked at run-time, and `EINVAL` is returned is the
|
|
/// access was out-of-bounds.
|
|
#[inline(always)]
|
|
pub(crate) fn try_alter<const SIZE: usize, T, B, F>(
|
|
io: &T,
|
|
base: &B,
|
|
idx: usize,
|
|
f: F,
|
|
) -> ::kernel::error::Result where
|
|
T: ::core::ops::Deref<Target = ::kernel::io::Io<SIZE>>,
|
|
B: crate::regs::macros::RegisterBase<$base>,
|
|
F: ::core::ops::FnOnce(Self) -> Self,
|
|
{
|
|
if idx < Self::SIZE {
|
|
Ok(Self::alter(io, base, idx, f))
|
|
} else {
|
|
Err(EINVAL)
|
|
}
|
|
}
|
|
}
|
|
};
|
|
}
|