Add an improved version of nova-core's `register!` macro to the `kernel`
crate for all drivers to use.
This is not a direct move from `nova-core`, but rather a new
introduction to facilitate code review and introduce features that are
missing in the nova-core versions. Differences notably include:
- Use of `Bounded` to prevent any data truncation when manipulating
bitfields,
- Much better syntax (thanks to Gary for all the suggestions!)
- Extended documentation,
- Doccomments now build and run,
- Supports visibility and different storage sizes.
The `bitfield!` macro of nova-core has for the moment been wrapped into
`register!`, as a set of private rules, to allow `register!` to be
merged first while `bitfield!` undergoes review during the next cycle.
Thus, some of the code from v1 (including `bitfield!`'s doccomments and
Kunit tests) are kept for later.
Another notable difference is that I have removed the `Default`
implementation for registers and instead implement `Zeroable` to provide
a start value. I have deemed this preferable because implementing
`Default` for a register requires that each of its field types also
implements it, which is quite constraining and doesn't always makes
sense (for instance, what is the default architecture for a family of
chips?). Fields for which zero is not a valid value must implement the
fallible getter anyway, so we are not at risk of undefined behavior, and
`Default` can always be implemented on a per-case basis.
The first patch enables the `generic_arg_infer` feature, which is
required for generic type inference and used in subsequent patches. This
feature is stable since rustc 1.89.
The second patch adds `shr` and `shl` methods to `Bounded`. These were
suggested by Alice during LPC as a way to avoid the use of the
controversial `Bounded::from_expr` in both the bitfield macro and the
Nova code. Third patch adds another convenience method to obtain a
`bool` from single-bit `Bounded`s.
Patch 4 adds the `register!` macro. Since it falls under
`rust/kernel/io` it is covered by the corresponding MAINTAINERS entry so
I refrained from adding one just for this file, especially since the
bitfield-related parts will eventually move and what remains is very
tightly related to I/O.
Patch 5 updates the Rust PCI sample driver to use the `register!`, as
per its TODO item.
The last patch illustrates more largely how this macro is used by
converting nova-core to use it, and removing the local implementation.
This patch is to be merged one cycle after the other patches.
Previous work to extract the macros was done in the partially-merged
[1]. The current series can be considered a reboot with more features
and the `bitfield!` macro being postponed.
This patchset is based on `driver-core-next`.
Note that it also need `rust-fixes` to avoid an `unused_unsafe` warning.
[1] https://lore.kernel.org/all/20251003154748.1687160-1-joelagnelf@nvidia.com/
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
---
Changes in v3:
- Sort the Rust features list alphabetically.
- Rebase on top of latest `driver-core-next` including the new Io trait.
- Remove references to `bitfield!` macro.
- Fix doccomment of `shr` and `shl`.
- Use `+` syntax for relative register offsets.
- Move register arrays size and stride to after the backing type declaration.
- Use regular doccomments to document registers and fields (thanks Gary!).
- Remove `Default` implementation and implement the more predictable
`Zeroable` instead.
- Improve doccomments a bit.
- Link to v2: https://patch.msgid.link/20260121-register-v2-0-79d9b8d5e36a@nvidia.com
Changes in v2:
- Remove `bitfield!` and put its rules into `register!` to give it more
time to get reviewed.
- Allow output type larger than strictly required for `shr` and `shl` on
`Bounded`.
- Enable the `generic_arg_infer` feature, required for rustc < 1.89.
- Link to v1: https://patch.msgid.link/20260120-register-v1-0-723a1743b557@nvidia.com
---
Alexandre Courbot (6):
rust: enable the `generic_arg_infer` feature
rust: num: add `shr` and `shl` methods to `Bounded`
rust: num: add `as_bool` method to `Bounded<_, 1>`
rust: io: add `register!` macro
sample: rust: pci: use `register!` macro
[FOR REFERENCE] gpu: nova-core: use the kernel `register!` macro
drivers/gpu/nova-core/falcon.rs | 175 ++--
drivers/gpu/nova-core/falcon/gsp.rs | 12 +-
drivers/gpu/nova-core/falcon/hal/ga102.rs | 15 +-
drivers/gpu/nova-core/falcon/sec2.rs | 13 +-
drivers/gpu/nova-core/fb/hal/ga100.rs | 13 +-
drivers/gpu/nova-core/fb/hal/tu102.rs | 2 +-
drivers/gpu/nova-core/gpu.rs | 31 +-
drivers/gpu/nova-core/gsp/cmdq.rs | 4 +-
drivers/gpu/nova-core/regs.rs | 494 +++++++-----
drivers/gpu/nova-core/regs/macros.rs | 739 -----------------
rust/kernel/io.rs | 1 +
rust/kernel/io/register.rs | 1234 +++++++++++++++++++++++++++++
rust/kernel/lib.rs | 3 +
rust/kernel/num/bounded.rs | 63 ++
samples/rust/rust_driver_pci.rs | 23 +-
scripts/Makefile.build | 3 +-
16 files changed, 1714 insertions(+), 1111 deletions(-)
---
base-commit: 1cab0874875a1c37f71edf1e1e3029b1cf31d81e
change-id: 20260117-register-ccaba1d21713
Best regards,
--
Alexandre Courbot <acourbot@nvidia.com>