[PATCH 0/6] rust: add `bitfield!` and `register!` macros

[Alexandre Courbot <acourbot@nvidia.com>]

Add an improved version of nova-core's `bitfield!` and `register!`
macros 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,
- Extended documentation,
- Doccomments now build and run,
- `register!` supports visibility and different storage sizes.

These updates basically turn a register into a bitfield extended with
some controlled I/O. This is reflected in the syntax of the macros,
which are mostly identical save for the additional `@` parameter of
`register!` and the fact that the `struct` keyword is omitted in the
latter, i.e:

  bitfield! {
      pub struct Foo(u32) {
        ...
      }
    }

vs

  register! {
      pub FOO(u32) @ 0x00000100 {
        ...
      }
    }

The use of `struct` in `register!` looks superfluous to me, but we can
of course add it if consistency between the two macros is deemed more
important.

The first commit 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. Second commit adds another convenience method to obtain a
`bool` from single-bit `Bounded`s.

Patches 3-5 add the `bitfield!` and `register!` macros.

The last patch illustrates how these macros are used by converting
nova-core to them, 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 the inclusion
of the KUNIT tests from the previous effort.

This patchset is based on `rust-fixes`, but should apply equally well on
`rust-next`.

[1] https://lore.kernel.org/all/20251003154748.1687160-1-joelagnelf@nvidia.com/

Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>

---
Alexandre Courbot (5):
      rust: num: add `shr` and `shl` methods to `Bounded`
      rust: num: add `as_bool` method to `Bounded<_, 1>`
      rust: add `bitfield!` macro
      rust: io: add `register!` macro
      [FOR REFERENCE] gpu: nova-core: use the kernel `register!` and `bitfield!` macros

Joel Fernandes (1):
      rust: bitfield: Add KUNIT tests for bitfield

 drivers/gpu/nova-core/bitfield.rs                  | 330 ---------
 drivers/gpu/nova-core/falcon.rs                    | 127 ++--
 drivers/gpu/nova-core/falcon/gsp.rs                |  10 +-
 drivers/gpu/nova-core/falcon/hal/ga102.rs          |   5 +-
 drivers/gpu/nova-core/falcon/sec2.rs               |  13 +-
 drivers/gpu/nova-core/fb/hal/ga100.rs              |   9 +-
 drivers/gpu/nova-core/gpu.rs                       |  24 +-
 drivers/gpu/nova-core/gsp/cmdq.rs                  |   2 +-
 drivers/gpu/nova-core/gsp/fw.rs                    |   5 +-
 drivers/gpu/nova-core/nova_core.rs                 |   3 -
 drivers/gpu/nova-core/regs.rs                      | 265 +++----
 rust/kernel/bitfield.rs                            | 821 +++++++++++++++++++++
 rust/kernel/io.rs                                  |   1 +
 .../regs/macros.rs => rust/kernel/io/register.rs   | 561 +++++++++-----
 rust/kernel/lib.rs                                 |   1 +
 rust/kernel/num/bounded.rs                         |  61 ++
 16 files changed, 1490 insertions(+), 748 deletions(-)
---
base-commit: 2af6ad09fc7dfe9b3610100983cccf16998bf34d
change-id: 20260117-register-ccaba1d21713

Best regards,
-- 
Alexandre Courbot <acourbot@nvidia.com>