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>

On Tue, Jan 20, 2026 at 7:23 AM Alexandre Courbot <acourbot@nvidia.com> wrote:
>
>       rust: num: add `shr` and `shl` methods to `Bounded`
>       rust: num: add `as_bool` method to `Bounded<_, 1>`

I could apply these two this cycle if that would help, since they are
straightforward and you say in the cover letter that you also use it
in Nova code -- does that mean outside the macro? (I don't see it in
linux-next, but perhaps I am blind...)

Thanks!

Cheers,
Miguel

On Tue Jan 20, 2026 at 2:14 PM CET, Miguel Ojeda wrote:
> On Tue, Jan 20, 2026 at 7:23 AM Alexandre Courbot <acourbot@nvidia.com> wrote:
>>
>>       rust: num: add `shr` and `shl` methods to `Bounded`
>>       rust: num: add `as_bool` method to `Bounded<_, 1>`
>
> I could apply these two this cycle if that would help, since they are
> straightforward and you say in the cover letter that you also use it
> in Nova code -- does that mean outside the macro? (I don't see it in
> linux-next, but perhaps I am blind...)

I discussed with Alex and Alice that it would be good to land the register!()
macro this cycle (having some local to register.rs bitfield support), so drivers
can start using it next cycle.

Subsequently, we can follow up on the discussions for global bitfield support.

For this purpose, it would be nice if I could pick up those two prerequisites as
part of this.

On Tue, Jan 20, 2026 at 2:38 PM Danilo Krummrich <dakr@kernel.org> wrote:
>
> I discussed with Alex and Alice that it would be good to land the register!()
> macro this cycle (having some local to register.rs bitfield support), so drivers
> can start using it next cycle.

By "local to register.rs bitfield support", do you mean something else
than this series?

To be honest, I think this is all quite late for the cycle.

Cheers,
Miguel

On Tue Jan 20, 2026 at 2:50 PM CET, Miguel Ojeda wrote:
> On Tue, Jan 20, 2026 at 2:38 PM Danilo Krummrich <dakr@kernel.org> wrote:
>>
>> I discussed with Alex and Alice that it would be good to land the register!()
>> macro this cycle (having some local to register.rs bitfield support), so drivers
>> can start using it next cycle.
>
> By "local to register.rs bitfield support", do you mean something else
> than this series?

Correct, this series came from a misunderstanding, I think Alex plans to follow
up on it tomorrow.

> To be honest, I think this is all quite late for the cycle.

I think there has been consensus on the register!() macro, so it seems possible.
But as always, if it works out, great -- if not, that's okay too.

On Tue, Jan 20, 2026 at 3:18 PM Danilo Krummrich <dakr@kernel.org> wrote:
>
> Correct, this series came from a misunderstanding, I think Alex plans to follow
> up on it tomorrow.

I see, thanks.

> I think there has been consensus on the register!() macro, so it seems possible.
> But as always, if it works out, great -- if not, that's okay too.

I want to make things easy for everyone, and I know there is pressure
to deliver etc., but yeah... I am supposed to also push back when
things get stretched a bit too much... :)

Having said that, depending on what the "local bitfield!" entails,
i.e. how much of a hack/workaround/extra work it is, it may be best to
avoid it and go directly for `bitfield!`.

But for that to happen, we would need Linus to really do the -rc8, and
very fast agreements and reviews on it.

It seems to me the easiest is that I give you a branch/tag for you
(and others that want it) to merge with the `bitfield!` one next
cycle. That would avoid the workaround too and Alexandre having to
come up with another series etc.

Cheers,
Miguel

On Tue Jan 20, 2026 at 3:57 PM CET, Miguel Ojeda wrote:
> I want to make things easy for everyone, and I know there is pressure
> to deliver etc., but yeah... I am supposed to also push back when
> things get stretched a bit too much... :)

I think it would be good if drivers other than nova-core would finally be able
to use the register!() macro, rather than having to go with raw I/O operations.

> Having said that, depending on what the "local bitfield!" entails,
> i.e. how much of a hack/workaround/extra work it is, it may be best to
> avoid it and go directly for `bitfield!`.

I think it's just about pasting the current bitfield work into register.rs, such
that it can only be used from there. In a follow up we can work out how it
should turn out finally and have to patches: 1. introduce bitfield.rs and 2.
move register!() to use the code from bitfield.rs.

I also proposed that at the end of last cycle [1] because I think the two things
are mostly orthogonal and we don't need to stall register!() on the generic
bitfield work.

[1] https://lore.kernel.org/all/DDC49ZIRX79X.2Q4KW0UY7WUF3@kernel.org/

> But for that to happen, we would need Linus to really do the -rc8, and
> very fast agreements and reviews on it.

The register!() macro code is worked on by Alex for about 10 month in nova-core,
the first RFC for general I/O infrastructure is from March 2025 and the current
series has been discussed on the list for about two cycles.

Given the above, that doesn't seem too unrealistic, let's see.

> It seems to me the easiest is that I give you a branch/tag for you
> (and others that want it) to merge with the `bitfield!` one next
> cycle. That would avoid the workaround too and Alexandre having to
> come up with another series etc.

You mean a tag with the bitfield!() code? Yeah, that would help if we don't make
it this cycle.

On Tue, Jan 20, 2026 at 4:27 PM Danilo Krummrich <dakr@kernel.org> wrote:
>
> I think it's just about pasting the current bitfield work into register.rs, such
> that it can only be used from there. In a follow up we can work out how it
> should turn out finally and have to patches: 1. introduce bitfield.rs and 2.
> move register!() to use the code from bitfield.rs.

Hmm... I am generally not a fan of putting local code. I know you did
it for the DRM `register!` itself, which is fine given the constraints
you have, but here perhaps we could put it in the right file but as
private/hidden as possible just to be used by the other file?

i.e. that way we can debate improvements on top of what we have,
rather than having a move or new code and a drop of the old one?

I mention this since you say "pasting", i.e. I guess it is still
smaller, but it sounds like you would essentially use it more or less
as-is?

> The register!() macro code is worked on by Alex for about 10 month in nova-core,
> the first RFC for general I/O infrastructure is from March 2025 and the current
> series has been discussed on the list for about two cycles.

I meant the `bitfield!` one, i.e. landing the patches as they are here
if we get very fast agreement etc. etc. I can see that possibility,
especially if private/hidden.

> You mean a tag with the bitfield!() code? Yeah, that would help if we don't make
> it this cycle.

Yeah.

Cheers,
Miguel

On Tue Jan 20, 2026 at 4:48 PM CET, Miguel Ojeda wrote:
> On Tue, Jan 20, 2026 at 4:27 PM Danilo Krummrich <dakr@kernel.org> wrote:
>>
>> I think it's just about pasting the current bitfield work into register.rs, such
>> that it can only be used from there. In a follow up we can work out how it
>> should turn out finally and have to patches: 1. introduce bitfield.rs and 2.
>> move register!() to use the code from bitfield.rs.
>
> Hmm... I am generally not a fan of putting local code. I know you did
> it for the DRM `register!` itself, which is fine given the constraints
> you have, but here perhaps we could put it in the right file but as
> private/hidden as possible just to be used by the other file?
>
> i.e. that way we can debate improvements on top of what we have,
> rather than having a move or new code and a drop of the old one?

I'm fine either way; the reason I proposed it the way I did was that I think it
sets the least precedence for how bitfields should turn out eventually.

> I mention this since you say "pasting", i.e. I guess it is still
> smaller, but it sounds like you would essentially use it more or less
> as-is?

I left this to Alex, he knows best what makes sense.

>> The register!() macro code is worked on by Alex for about 10 month in nova-core,
>> the first RFC for general I/O infrastructure is from March 2025 and the current
>> series has been discussed on the list for about two cycles.
>
> I meant the `bitfield!` one, i.e. landing the patches as they are here
> if we get very fast agreement etc. etc. I can see that possibility,
> especially if private/hidden.

I think it's rather unlikely to land bitfields this cycle. I think Yury
explicitly requested more discussion on bitfields and also encouraged the "two
stage" approach [1] moving register!() first and then extract bitfields
subsequently.

[1] https://lore.kernel.org/lkml/aOaIIV8KDA0GjF6E@yury/

On Tue, Jan 20, 2026 at 9:01 PM Danilo Krummrich <dakr@kernel.org> wrote:
>
> I think it's rather unlikely to land bitfields this cycle. I think Yury
> explicitly requested more discussion on bitfields and also encouraged the "two
> stage" approach [1] moving register!() first and then extract bitfields
> subsequently.

Does Yury want to maintain it? From his messages back then I am not
sure if he does or not (he suggested "some non-rust person from a
related kernel subsystem", not sure if that meant himself in this case
too).

At least, he suggested adding a `MAINTAINERS` entry, which I agreed it
was a good idea (by the way, this patch series should add it, or at
least the eventual one that adds `bitfield!`).

In any case, it has been a while since those discussions. It would be
nice to know what people think nowadays about the macro here etc.

But yeah, from my side, no rush. And if Alexandre wants to maintain
the new file and he wants a tree, I am happy to set it one more up.

Thanks!

Cheers,
Miguel

On Tue, Jan 20, 2026 at 09:31:14PM +0100, Miguel Ojeda wrote:
> On Tue, Jan 20, 2026 at 9:01 PM Danilo Krummrich <dakr@kernel.org> wrote:
> >
> > I think it's rather unlikely to land bitfields this cycle. I think Yury
> > explicitly requested more discussion on bitfields and also encouraged the "two
> > stage" approach [1] moving register!() first and then extract bitfields
> > subsequently.
> 
> Does Yury want to maintain it? From his messages back then I am not
> sure if he does or not (he suggested "some non-rust person from a
> related kernel subsystem", not sure if that meant himself in this case
> too).

I can become a reviewer or maintainer, assuming Alex will become the first
maintainer as the main developer. I can also move it with my branch if you
prefer, guys. In this case it's better to make me a maintainer. 

> At least, he suggested adding a `MAINTAINERS` entry, which I agreed it
> was a good idea (by the way, this patch series should add it, or at
> least the eventual one that adds `bitfield!`).

Yes it is. Alexandre, can you please add a maintenance section(s) for
all new files?
 
> In any case, it has been a while since those discussions. It would be
> nice to know what people think nowadays about the macro here etc.
> 
> But yeah, from my side, no rush. And if Alexandre wants to maintain
> the new file and he wants a tree, I am happy to set it one more up.
> 
> Thanks!
> 
> Cheers,
> Miguel

On Jan 21, 2026, at 12:57 AM, Yury Norov <ynorov@nvidia.com> wrote:
> On Tue, Jan 20, 2026 at 09:31:14PM +0100, Miguel Ojeda wrote:
>>> On Tue, Jan 20, 2026 at 9:01 PM Danilo Krummrich <dakr@kernel.org> wrote:
>>>
>>> I think it's rather unlikely to land bitfields this cycle. I think Yury
>>> explicitly requested more discussion on bitfields and also encouraged
>>> the "two stage" approach [1] moving register!() first and then extract
>>> bitfields subsequently.
>>
>> Does Yury want to maintain it? From his messages back then I am not
>> sure if he does or not (he suggested "some non-rust person from a
>> related kernel subsystem", not sure if that meant himself in this case
>> too).
>
> I can become a reviewer or maintainer, assuming Alex will become the first
> maintainer as the main developer. I can also move it with my branch if you
> prefer, guys. In this case it's better to make me a maintainer.

Happy to co-maintain it with you guys as well, since the initial idea to add a
Bitfield macro to use for Bitfield and the initial work to improve it based on
nova's register macro came from me. I am also intimately familiar with it due
to usage with the nova memory management series:
https://lore.kernel.org/all/20260120204303.3229303-1-joelagnelf@nvidia.com/

>> At least, he suggested adding a `MAINTAINERS` entry, which I agreed it
>> was a good idea (by the way, this patch series should add it, or at
>> least the eventual one that adds `bitfield!`).
>
> Yes it is. Alexandre, can you please add a maintenance section(s) for
> all new files?

Agreed.

-- 
Joel Fernandes

On Wed Jan 21, 2026 at 2:57 PM JST, Yury Norov wrote:
> On Tue, Jan 20, 2026 at 09:31:14PM +0100, Miguel Ojeda wrote:
>> On Tue, Jan 20, 2026 at 9:01 PM Danilo Krummrich <dakr@kernel.org> wrote:
>> >
>> > I think it's rather unlikely to land bitfields this cycle. I think Yury
>> > explicitly requested more discussion on bitfields and also encouraged the "two
>> > stage" approach [1] moving register!() first and then extract bitfields
>> > subsequently.
>> 
>> Does Yury want to maintain it? From his messages back then I am not
>> sure if he does or not (he suggested "some non-rust person from a
>> related kernel subsystem", not sure if that meant himself in this case
>> too).
>
> I can become a reviewer or maintainer, assuming Alex will become the first
> maintainer as the main developer. I can also move it with my branch if you
> prefer, guys. In this case it's better to make me a maintainer. 
>
>> At least, he suggested adding a `MAINTAINERS` entry, which I agreed it
>> was a good idea (by the way, this patch series should add it, or at
>> least the eventual one that adds `bitfield!`).
>
> Yes it is. Alexandre, can you please add a maintenance section(s) for
> all new files?

It looks like we are heading towards introducing `bitfield!` a bit
later (v2 will only have `register!`). I will add a MAINTAINERS entry
once we re-introduce `bitfield!`.