Message-Id: <20251106-bounded_ints-v3-0-47104986a5c3@nvidia.com>
Date: Thu, 06 Nov 2025 16:07:12 +0900
From: Alexandre Courbot <acourbot@...dia.com>
To: Alice Ryhl <aliceryhl@...gle.com>, Danilo Krummrich <dakr@...nel.org>, 
 Miguel Ojeda <ojeda@...nel.org>, Joel Fernandes <joelagnelf@...dia.com>, 
 Yury Norov <yury.norov@...il.com>, Jesung Yang <y.j3ms.n@...il.com>, 
 Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>, 
 Björn Roy Baron <bjorn3_gh@...tonmail.com>, 
 Benno Lossin <lossin@...nel.org>, Andreas Hindborg <a.hindborg@...nel.org>, 
 Trevor Gross <tmgross@...ch.edu>
Cc: linux-kernel@...r.kernel.org, rust-for-linux@...r.kernel.org, 
 Alexandre Courbot <acourbot@...dia.com>
Subject: [PATCH v3 0/4] rust: add Bounded integer type

New revision, where we rename `BitInt` to `Bounded` and consolidate
things a bit. The `Integer` trait also exposes more common features of
integers to generic code, which makes it more useful - to the point
where we can now use it in place of the `Boundable` trait.

Patch 3 adds a MAINTAINERS entry in case the Rust core team would like
us to maintain this, but please ignore it if you prefer to take it under
the core umbrella.

This series provides `Bounded`, a wrapper type for primitive integers
that guarantees that only a given number of bits are used to represent
values. This is particularly useful when working with bitfields, as the
guarantee that a given value fits within the number of assigned bits can
be enforced by the type system, saving cumbersome runtime checks, or
(worse) stripping data when bits are silently dropped.

For a basic usage, please see the rustdoc of the `Bounded` type on the
second patch.

The first use of this will be to represent bitfields in Nova register
types to guarantee that no data is ever stripped when manipulating them.
This should eventually allow the `bitfield` and `register` macros to
move out of Nova and into the kernel crate.

The last patch is just here to illustrate the use of this module; it is
not intended to be merged this cycle as it would likely result in big
merge conflicts with the drm tree.

This series applies on top of drm-rust-next for the needs of the last
patch, but the first 2 patches should apply cleanly on rust-next. A
branch with this series and its dependencies is available here:

https://github.com/Gnurou/linux/tree/b4/bounded_ints

Signed-off-by: Alexandre Courbot <acourbot@...dia.com>
---
Changes in v3:
- Rename to `Bounded` to avoid confusion with C's `_BitInt`.
- Request all common integer features on `Integer` trait and remove
  unneeded `Boundable`.
- Use `assert` instead of `build_assert` in const blocks. (thanks Alice!)
- Implement `Integer` for `u/isize` and `u/i128`.
- Support `usize`/`isize` as `Bounded` types.
- Implement arithmetic and logic ops between two `Bounded` of the same
  backing type (but not necessarily same length).
- Move addition of `num` module to its own patch.
- Add MAINTAINERS entry for `num`.
- Link to v2: https://lore.kernel.org/r/20251102-bounded_ints-v2-0-7ef0c26b1d36@nvidia.com

Changes in v2:
- Move type invariants of `BitInt` to a centralizing private
  constructor.
- Simplify `From` implementations to and from primitive types.
- Remove ability to convert between unsigned and signed types as it was
  buggy, and its utility doubtful.
- Use macro to implement `Integer` and avoid repeating code.
- Fix a few typos.
- More doctests, and split them into different paragraphs in the
  `BitInt` main doccomment.
- Fix build with Rust 1.78.
- Finish implementing relevant `core::ops` traits.
- Link to v1: https://lore.kernel.org/r/20251031-bounded_ints-v1-0-e2dbcd8fda71@nvidia.com

Changes in v1:
- Rebase on top of `drm-rust-next`.
- Rename `BoundedInt` to `BitInt` (thanks Yury!).
- Add lots of documentation.
- Use shifts to validate bounds, as it works with both unsigned and
  signed types contrary to the mask method.
- Support signed types (albeit with some bugs).
- Use `new` for the const static constructor and make it the preferred
  way to build values (thanks Alice and Joel!).
- Rename `LargerThanX` into `AtLeastX` (thanks Joel!).
- Support basic arithmetic operations (+, -, etc.) against the backing
  type.
- Add `Deref` implementation as alternative to the `get` method.
- Write correct `Default` implementation for bitfields.
- Make the new bitfield accessors `inline(always)`.
- Update bitfield documentation to the new usage.
- Link to RFC v2: https://lore.kernel.org/r/20251009-bounded_ints-v2-0-ff3d7fee3ffd@nvidia.com

Changes in RFC v2:
- Thorough implementation of `BoundedInt`.
- nova-core fully adapted to use `BoundedInt`.
- Link to RFC v1: https://lore.kernel.org/r/20251002-bounded_ints-v1-0-dd60f5804ea4@nvidia.com

---
Alexandre Courbot (4):
      rust: add num module and Integer trait
      rust: num: add Bounded integer wrapping type
      MAINTAINERS: add entry for the Rust `num` module
      [FOR REFERENCE] gpu: nova-core: use BitInt for bitfields

 MAINTAINERS                               |    8 +
 drivers/gpu/nova-core/bitfield.rs         |  366 +++++-----
 drivers/gpu/nova-core/falcon.rs           |  140 ++--
 drivers/gpu/nova-core/falcon/hal/ga102.rs |    5 +-
 drivers/gpu/nova-core/fb/hal/ga100.rs     |    3 +-
 drivers/gpu/nova-core/gpu.rs              |    9 +-
 drivers/gpu/nova-core/regs.rs             |  139 ++--
 rust/kernel/lib.rs                        |    1 +
 rust/kernel/num.rs                        |   79 +++
 rust/kernel/num/bounded.rs                | 1045 +++++++++++++++++++++++++++++
 10 files changed, 1492 insertions(+), 303 deletions(-)
---
base-commit: ade19c5060dfa39b84a9475a4a6b05e2a8a2b3ac
change-id: 20251001-bounded_ints-1d0457d9ae26

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

Powered by blists - more mailing lists