This new revision took some time because it is (yet another) overhaul.
^_^;

Thanks to a breakthrough by Gary, we found a way to have the I/O type
perform the actual I/O instead of the register type, which moves us from
this access pattern:

    let boot0 = regs::NV_PMC_BOOT_0::read(bar);

to this arguably more natural one:

    let boot0 = bar.read(regs::NV_PMC_BOOT_0);

It also has the benefit of taking advantage of deref coercion for types
that wrap an `Io`, something the register-based methods couldn't do and
which would have required extra `AsRef` implementations just for this
purpose.

Furthermore, this resolves the inconsistency of the former register API
that couldn't use the `try_` I/O accessors (and even had methods whose
names clashed with them). Now if `Io` supports it, it can be done on a
register.

Another benefit is that there is less work done within macros, and more
in generic code, which is (generally) a win for readability. The
`register!` macro is considerably smaller and easier to work on, and now
mostly made up of the bitfield accessors that will eventually be moved
into another macro.

I decided to remove a couple of tags because the code has changed quite
a bit since they were obtained.

Gary is listed as co-developer on two patches that bring his idea to
life; I took the freedom to add his signoff for convenience, but would
be more comfortable to get an explicit ack after he sees the code. :)

This revision is based on `driver-core-testing` as of 2026-01-16 with
[1] applied. A tree with this series and its dependencies is available
at [2].

[1] https://lore.kernel.org/all/20260206-io-v2-0-71dea20a06e6@nvidia.com/
[2] https://github.com/Gnurou/linux/tree/b4/register

Initial cover letter follows:

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,
- I/O accesses are performed by `Io` instead of the register type.

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.

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. The third patch adds another convenience method to obtain a
`bool` from single-bit `Bounded`s, while the fourth patch turns
`Bounded::get` into a const method in order to make register setter
methods const.

Patches 5 and 6 introduce the `IoRef` and `IoWrite` types around which
I/O accesses are centered. This allows registers to be accessed using
the same `read` and `write` methods as primitive types.

Patch 7 adds the `register!` macro and the types it requires.

Patch 8 updates the Rust PCI sample driver to use `register!`, as per
its TODO item.

The last patch illustrates more extensively 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.

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

---
Changes in v6:
- Remove Tested-by tags as the code has considerably changed.
- Make `Bounded::get` const so it can be used with registers.
- Use the `pin_init::zeroed()` const function instead of defining our
  own method.
- Generalize all `Io` around the new `IoRef` and `IoWrite` types, and
  make registers use these as well.
- Use the more natural pattern of having the `Io` type perform the I/O
  access instead of the register type.
- Convert the whole PCI driver example, and not only the PCI
  configuration space.
- Rename `Bounded::as_bool` to `Bounded::into_bool`.
- Drop `Bounded::into_inner` in favor of making `Bounded::get` const.
- Link to v5: https://patch.msgid.link/20260129-register-v5-0-c4587c902514@nvidia.com

Changes in v5:
- Rename all setters to `with_*` and `with_const_*`.
- Use `, stride = ` to specify the stride of register arrays.
- Remove `Deref` requirement on the `RegisterIo` trait and make it
  `#[doc(hidden)`.
- Simplify the top dispatch rule a bit.
- Link to v4: https://patch.msgid.link/20260128-register-v4-0-aee3a33d9649@nvidia.com

Changes in v4:
- Add `with_` const field setter methods (removing the need to call
  `Bounded::new` for constant field values).
- Add `into_inner` const method for `Bounded`.
- Add `from_raw` and const `zeroed` method to create initial register
  values.
- More documentation improvements.
- Link to v3: https://patch.msgid.link/20260126-register-v3-0-2328a59d7312@nvidia.com

Changes in v3:
- Sort the Rust features list alphabetically.
- Rebase on top of latest `driver-core-next` including the new Io trait.
- Allow several registers to be defined from the same macro invocation.
- 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 (9):
      rust: enable the `generic_arg_infer` feature
      rust: num: add `shr` and `shl` methods to `Bounded`
      rust: num: add `into_bool` method to `Bounded`
      rust: num: make Bounded::get const
      rust: io: add IoRef and IoWrite types
      rust: io: use generic read/write accessors for primitive accesses
      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           |  249 +++----
 drivers/gpu/nova-core/falcon/gsp.rs       |   23 +-
 drivers/gpu/nova-core/falcon/hal/ga102.rs |   65 +-
 drivers/gpu/nova-core/falcon/hal/tu102.rs |   11 +-
 drivers/gpu/nova-core/falcon/sec2.rs      |   17 +-
 drivers/gpu/nova-core/fb.rs               |    6 +-
 drivers/gpu/nova-core/fb/hal/ga100.rs     |   40 +-
 drivers/gpu/nova-core/fb/hal/ga102.rs     |    7 +-
 drivers/gpu/nova-core/fb/hal/tu102.rs     |   22 +-
 drivers/gpu/nova-core/gfw.rs              |   11 +-
 drivers/gpu/nova-core/gpu.rs              |   36 +-
 drivers/gpu/nova-core/gsp/boot.rs         |   11 +-
 drivers/gpu/nova-core/gsp/cmdq.rs         |   10 +-
 drivers/gpu/nova-core/regs.rs             |  544 ++++++++------
 drivers/gpu/nova-core/regs/macros.rs      |  739 -------------------
 rust/kernel/io.rs                         |  345 +++++++--
 rust/kernel/io/register.rs                | 1125 +++++++++++++++++++++++++++++
 rust/kernel/lib.rs                        |    3 +
 rust/kernel/num/bounded.rs                |   70 +-
 samples/rust/rust_driver_pci.rs           |   84 ++-
 scripts/Makefile.build                    |    3 +-
 21 files changed, 2106 insertions(+), 1315 deletions(-)
---
base-commit: 916328497055bdfc1d633f04a33ab7d4dc91f45f
change-id: 20260117-register-ccaba1d21713

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

Hi Alexandre,

On 16.02.26 09:04, Alexandre Courbot wrote:
> This new revision took some time because it is (yet another) overhaul.
> ^_^;
> 
> Thanks to a breakthrough by Gary, we found a way to have the I/O type
> perform the actual I/O instead of the register type, which moves us from
> this access pattern:
> 
>     let boot0 = regs::NV_PMC_BOOT_0::read(bar);
> 
> to this arguably more natural one:
> 
>     let boot0 = bar.read(regs::NV_PMC_BOOT_0);
> 
> It also has the benefit of taking advantage of deref coercion for types
> that wrap an `Io`, something the register-based methods couldn't do and
> which would have required extra `AsRef` implementations just for this
> purpose.
> 
> Furthermore, this resolves the inconsistency of the former register API
> that couldn't use the `try_` I/O accessors (and even had methods whose
> names clashed with them). Now if `Io` supports it, it can be done on a
> register.
> 
> Another benefit is that there is less work done within macros, and more
> in generic code, which is (generally) a win for readability. The
> `register!` macro is considerably smaller and easier to work on, and now
> mostly made up of the bitfield accessors that will eventually be moved
> into another macro.
> 
> I decided to remove a couple of tags because the code has changed quite
> a bit since they were obtained.

Last time I gave this a try was with v2. From my aarch64 simple timer
test on that version I have [1] below. Could you give a hint how to
convert this to v6? :)

Many thanks!

Dirk

[1]

register!(TCR(u16) @ 0x10 {
        9:9    icpf;
        8:8    unf;
        7:6    icpe;
	5:5    unie;
	4:3    ckeg;
	2:0    tpsc;
});


impl TCR {
	fn handle_underflow<const SIZE: usize, T>(io: &T)
	where
	    T: Deref<Target = Io<SIZE>>,
	{
	    let tcr = Self::read(io);
	    if tcr.unf().into() {
	        tcr.set_unf(false).write(io);
	    }
	}
}

...

// Reset the underflow flag
TCR::handle_underflow(io);

Hi Dirk,

On Fri Feb 20, 2026 at 10:20 PM JST, Dirk Behme wrote:
> Hi Alexandre,
>
> On 16.02.26 09:04, Alexandre Courbot wrote:
>> This new revision took some time because it is (yet another) overhaul.
>> ^_^;
>> 
>> Thanks to a breakthrough by Gary, we found a way to have the I/O type
>> perform the actual I/O instead of the register type, which moves us from
>> this access pattern:
>> 
>>     let boot0 = regs::NV_PMC_BOOT_0::read(bar);
>> 
>> to this arguably more natural one:
>> 
>>     let boot0 = bar.read(regs::NV_PMC_BOOT_0);
>> 
>> It also has the benefit of taking advantage of deref coercion for types
>> that wrap an `Io`, something the register-based methods couldn't do and
>> which would have required extra `AsRef` implementations just for this
>> purpose.
>> 
>> Furthermore, this resolves the inconsistency of the former register API
>> that couldn't use the `try_` I/O accessors (and even had methods whose
>> names clashed with them). Now if `Io` supports it, it can be done on a
>> register.
>> 
>> Another benefit is that there is less work done within macros, and more
>> in generic code, which is (generally) a win for readability. The
>> `register!` macro is considerably smaller and easier to work on, and now
>> mostly made up of the bitfield accessors that will eventually be moved
>> into another macro.
>> 
>> I decided to remove a couple of tags because the code has changed quite
>> a bit since they were obtained.
>
> Last time I gave this a try was with v2. From my aarch64 simple timer
> test on that version I have [1] below. Could you give a hint how to
> convert this to v6? :)

Yeah I'm sorry, this is quite a heavy change. An LLM should do a good
job at updating your code once you give it an example.

>
> Many thanks!
>
> Dirk
>
> [1]
>
> register!(TCR(u16) @ 0x10 {
>         9:9    icpf;
>         8:8    unf;
>         7:6    icpe;
> 	5:5    unie;
> 	4:3    ckeg;
> 	2:0    tpsc;
> });

This would become:

register! {
    TCR(u16) @ 0x10 {
        9:9    icpf;
        8:8    unf;
        7:6    icpe;
        5:5    unie;
        4:3    ckeg;
        2:0    tpsc;
    }
}

This part doesn't change much - it would however if the fields were
documented.

Note also that you can now declare several registers in the same
`register!` invocation.

>
>
> impl TCR {
> 	fn handle_underflow<const SIZE: usize, T>(io: &T)
> 	where
> 	    T: Deref<Target = Io<SIZE>>,

`Io` is a trait now, so this will need updating as well.

> 	{
> 	    let tcr = Self::read(io);

        // Note `TCR` exists as both the type and the contant. `read`
        // expects the latter, so you cannot use `Self` here.
        let tcr = io.read(TCR);

> 	    if tcr.unf().into() {
> 	        tcr.set_unf(false).write(io);
> 	    }

        if tcr.unf().into_bool() {
            // You will need to have `IoRef` (`IoLoc` in v7) in scope
            // for `set` to be visible.
            io.write(TCR.set(tcr.with_unf(false)));
        }

The direction of `read` and `write` is now more natural (and more
flexible with respect to the way I/O now works).

I am also contemplating allowing the following syntax for the write:

            io.write(tcr.with_unf(false));

which is shorter, but will also only work for fixed registers. Guess I
should ask for opinions as an RFC patch.

Hope this helps - let me know if anything is unclear or if you notice
pain points!