Skip to contentSkip to conversation

rust: bounded integer types and use in register macro

RFC PATCH Superseded Alexandre Courbot 7 participants 26 messages Oct 9, 2025 – Oct 16, 2025

Subsystems (5)

v2 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Alexandre Courbot

author maintainer
#0 lore raw

v2 cover rust: bounded integer types and use in register macro

Second revision, much more complete, of the RFC/PoC for an idea I submitted a bit earlier [1] regarding how to handle truncated bits in the register/bitfield macro field setters.

Currently, the register macro allows to define fields that are shorter than the primitive type used to set them. For instance, in the following register:

  register!(NV_PFALCON_FALCON_DMATRFBASE1 @ PFalconBase[0x00000128] {
        8:0     base as u16;
  });

The base field is 9 bits long, but is set using the following setter method:

fn set_base(self, value: u16) -> Self

which discards bits of value higher than 9 without any error or warning if some happen to be set. And so you happily start a DMA transfer from the wrong base address...

While this behavior is not UB, this can also be a source of bugs. Several ideas have been submitted to not let these unnoticed, including making the register setters fallible, or panicking or printing a warning whenever extra bits are discarded. These solutions are either too risky (like panicking), or add extra code and checks on what can be a critical path as registers are commonly accessed in interrupt handlers.

In pure Rust fashion, we would prefer to guarantee at compile-time, whenever possible, that no bits are discarded when setting register fields with a non-round number of bits.

This PoC proposes a possible solution for that. It introduces a new BoundedInt type that wraps a primitive integer type and, using a const generic parameter, limits the number of bits that can actually be used within it. This is similar in spirit to NonZero or Alignment in that it provides a static guarantee that the value it contains is limited to a certain subset of the possible values of its primitive type.

Instances of BoundedInt can be constructed infallibly when the compiler is able to guarantee that the passed value fits within the allowed bounds, or fallibly using try_new(primitive).

This type is then used by the register/bitfield macros to let the fields getter and (more importantly) setter methods work with the exact number of bits they can handle. For instance, the above method would become:

fn set_base(self, value: impl Into<BoundedInt<u32, 9>>) -> Self

which guarantees that no bits are ever discarded by the setter, since the type of value carries an invariant that only the 9 lowest bits can ever be set.

It is then the responsibility of the caller to build the adequate BoundedInt, which very often can be done infallibly, but all the cases that require a fallible operation are cases that the caller should have checked anyway (lest you beam out the wrong memory region on your DMA transfer!).

Compared to v1, this version of the RFC is much more complete. It notably provides many From implementations for conversions from/to bounded types that cannot fail, which removes a lot of the friction one would expect when introducing new integer types.

Another side effect of this is that the bitfield definitions are considerably simplified, since their type can now be automatically inferred. This means that

        8:0     base as u16;

could become simply

        8:0     base;

And the getter/setters would work with a BoundedInt<u32, 9> (provided the bitfield type is backed by a u32).

For convenience, this PoC is based on drm-rust-next. If we decide to proceed with it, we would do it after the patchset extracting and moving the bitfield logic [2] lands, as the two would conflict heavily.

Patch 1 is a pre-requisite that should be merged to nova-core, but can be considered external to this series.

Patch 2 is the BoundedInt implementation.

Patch 3 makes nova-core use BoundedInt for its register macro, and serves to illustrate how callers of the register field accessors are affected by the change (rather minimally imho).

Feedback is welcome! If there is no pushback I will remove the RFC tag for the next revision as I think the BoundedInt implementation is already rather exhaustive.

[1] https://lore.kernel.org/rust-for-linux/[email protected]/
[2] https://lore.kernel.org/rust-for-linux/[email protected]/T/

---
Changes in v2:
- Thorough implementation of BoundedInt.
- nova-core fully adapted to use BoundedInt.
- Link to v1: https://lore.kernel.org/r/[email protected]

---
Alexandre Courbot (3):
gpu: nova-core: register: use field type for Into implementation
rust: kernel: add bounded integer types
gpu: nova-core: use BoundedInt

 drivers/gpu/nova-core/falcon.rs           | 118 ++++---
 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 ++++-----
 drivers/gpu/nova-core/regs/macros.rs      | 264 ++++++++--------
 rust/kernel/lib.rs                        |   1 +
 rust/kernel/num.rs                        | 499 ++++++++++++++++++++++++++++++
 8 files changed, 783 insertions(+), 255 deletions(-)

---
base-commit: 299eb32863e584cfff7c6b667c3e92ae7d4d2bf9
change-id: 20251001-bounded_ints-1d0457d9ae26

Best regards,

Signature · 1 line
Alexandre Courbot <[email protected]>
author maintainer
#1 lore raw

RFC PATCH v2 1/3 gpu: nova-core: register: use field type for Into implementation

The getter method of a field works with the field type, but its setter expects the type of the register. This leads to an asymmetry in the From/Into implementations required for a field with a dedicated type. For instance, a field declared as

    pub struct ControlReg(u32) {
        3:0 mode as u8 ?=> Mode;
        ...
    }

currently requires the following implementations:

    impl TryFrom<u8> for Mode {
      ...
    }

    impl From<Mode> for u32 {
      ...
    }

Change this so the From<Mode> now needs to be implemented for u8, i.e. the primitive type of the field. This is more consistent, and will become a requirement once we start using the TryFrom/Into derive macros to implement these automatically.

---
 drivers/gpu/nova-core/falcon.rs      | 38 +++++++++++++++++++++++++-----------
 drivers/gpu/nova-core/regs/macros.rs | 10 +++++-----
 2 files changed, 32 insertions(+), 16 deletions(-)
drivers/gpu/nova-core/falcon.rs +27 -11
index 37e6298195e4..3f505b870601 100644
@@ -22,11 +22,11 @@
 pub(crate) mod sec2;
 
 // TODO[FPRI]: Replace with `ToPrimitive`.
-macro_rules! impl_from_enum_to_u32 {
+macro_rules! impl_from_enum_to_u8 {
     ($enum_type:ty) => {
-        impl From<$enum_type> for u32 {
+        impl From<$enum_type> for u8 {
             fn from(value: $enum_type) -> Self {
-                value as u32
+                value as u8
             }
         }
     };
@@ -46,7 +46,7 @@ pub(crate) enum FalconCoreRev {
     Rev6 = 6,
     Rev7 = 7,
 }
-impl_from_enum_to_u32!(FalconCoreRev);
+impl_from_enum_to_u8!(FalconCoreRev);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconCoreRev {
@@ -81,7 +81,7 @@ pub(crate) enum FalconCoreRevSubversion {
     Subversion2 = 2,
     Subversion3 = 3,
 }
-impl_from_enum_to_u32!(FalconCoreRevSubversion);
+impl_from_enum_to_u8!(FalconCoreRevSubversion);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconCoreRevSubversion {
@@ -125,7 +125,7 @@ pub(crate) enum FalconSecurityModel {
     /// Also known as High-Secure, Privilege Level 3 or PL3.
     Heavy = 3,
 }
-impl_from_enum_to_u32!(FalconSecurityModel);
+impl_from_enum_to_u8!(FalconSecurityModel);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconSecurityModel {
@@ -157,7 +157,7 @@ pub(crate) enum FalconModSelAlgo {
     #[default]
     Rsa3k = 1,
 }
-impl_from_enum_to_u32!(FalconModSelAlgo);
+impl_from_enum_to_u8!(FalconModSelAlgo);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconModSelAlgo {
@@ -179,7 +179,7 @@ pub(crate) enum DmaTrfCmdSize {
     #[default]
     Size256B = 0x6,
 }
-impl_from_enum_to_u32!(DmaTrfCmdSize);
+impl_from_enum_to_u8!(DmaTrfCmdSize);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for DmaTrfCmdSize {
@@ -202,7 +202,6 @@ pub(crate) enum PeregrineCoreSelect {
     /// RISC-V core is active.
     Riscv = 1,
 }
-impl_from_enum_to_u32!(PeregrineCoreSelect);
 
 impl From<bool> for PeregrineCoreSelect {
     fn from(value: bool) -> Self {
@@ -213,6 +212,15 @@ fn from(value: bool) -> Self {
     }
 }
 
+impl From<PeregrineCoreSelect> for bool {
+    fn from(value: PeregrineCoreSelect) -> Self {
+        match value {
+            PeregrineCoreSelect::Falcon => false,
+            PeregrineCoreSelect::Riscv => true,
+        }
+    }
+}
+
 /// Different types of memory present in a falcon core.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum FalconMem {
@@ -236,7 +244,7 @@ pub(crate) enum FalconFbifTarget {
     /// Non-coherent system memory (System DRAM).
     NoncoherentSysmem = 2,
 }
-impl_from_enum_to_u32!(FalconFbifTarget);
+impl_from_enum_to_u8!(FalconFbifTarget);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconFbifTarget {
@@ -263,7 +271,6 @@ pub(crate) enum FalconFbifMemType {
     /// Physical memory addresses.
     Physical = 1,
 }
-impl_from_enum_to_u32!(FalconFbifMemType);
 
 /// Conversion from a single-bit register field.
 impl From<bool> for FalconFbifMemType {
@@ -275,6 +282,15 @@ fn from(value: bool) -> Self {
     }
 }
 
+impl From<FalconFbifMemType> for bool {
+    fn from(value: FalconFbifMemType) -> Self {
+        match value {
+            FalconFbifMemType::Virtual => false,
+            FalconFbifMemType::Physical => true,
+        }
+    }
+}
+
 /// Type used to represent the `PFALCON` registers address base for a given falcon engine.
 pub(crate) struct PFalconBase(());
 
drivers/gpu/nova-core/regs/macros.rs +5 -5
index 754c14ee7f40..73811a115762 100644
@@ -482,7 +482,7 @@ impl $name {
         register!(
             @leaf_accessor $name $hi:$lo $field
             { |f| <$into_type>::from(if f != 0 { true } else { false }) }
-            $into_type => $into_type $(, $comment)?;
+            bool $into_type => $into_type $(, $comment)?;
         );
     };
 
@@ -499,7 +499,7 @@ impl $name {
             $(, $comment:literal)?;
     ) => {
         register!(@leaf_accessor $name $hi:$lo $field
-            { |f| <$try_into_type>::try_from(f as $type) } $try_into_type =>
+            { |f| <$try_into_type>::try_from(f as $type) } $type $try_into_type =>
             ::core::result::Result<
                 $try_into_type,
                 <$try_into_type as ::core::convert::TryFrom<$type>>::Error
@@ -513,7 +513,7 @@ impl $name {
             $(, $comment:literal)?;
     ) => {
         register!(@leaf_accessor $name $hi:$lo $field
-            { |f| <$into_type>::from(f as $type) } $into_type => $into_type $(, $comment)?;);
+            { |f| <$into_type>::from(f as $type) } $type $into_type => $into_type $(, $comment)?;);
     };
 
     // Shortcut for non-boolean fields defined without the `=>` or `?=>` syntax.
@@ -527,7 +527,7 @@ impl $name {
     // Generates the accessor methods for a single field.
     (
         @leaf_accessor $name:ident $hi:tt:$lo:tt $field:ident
-            { $process:expr } $to_type:ty => $res_type:ty $(, $comment:literal)?;
+            { $process:expr } $prim_type:tt $to_type:ty => $res_type:ty $(, $comment:literal)?;
     ) => {
         ::kernel::macros::paste!(
         const [<$field:upper _RANGE>]: ::core::ops::RangeInclusive<u8> = $lo..=$hi;
@@ -559,7 +559,7 @@ pub(crate) fn $field(self) -> $res_type {
         pub(crate) fn [<set_ $field>](mut self, value: $to_type) -> Self {
             const MASK: u32 = $name::[<$field:upper _MASK>];
             const SHIFT: u32 = $name::[<$field:upper _SHIFT>];
-            let value = (u32::from(value) << SHIFT) & MASK;
+            let value = (u32::from($prim_type::from(value)) << SHIFT) & MASK;
             self.0 = (self.0 & !MASK) | value;
 
             self
Signature · 1 line
2.51.0
#2 lore raw

Re: [PATCH RFC v2 1/3] gpu: nova-core: register: use field type for Into implementation

Hi Alex,

Quoted 20 lines · Alexandre Courbot

The getter method of a field works with the field type, but its setter expects the type of the register. This leads to an asymmetry in the From/Into implementations required for a field with a dedicated type. For instance, a field declared as

    pub struct ControlReg(u32) {
        3:0 mode as u8 ?=> Mode;
        ...
    }

currently requires the following implementations:

    impl TryFrom<u8> for Mode {
      ...
    }

    impl From<Mode> for u32 {
      ...
    }
Quoted 7 lines

Change this so the From<Mode> now needs to be implemented for u8, i.e. the primitive type of the field. This is more consistent, and will become a requirement once we start using the TryFrom/Into derive macros to implement these automatically.

As these are incremental improvements, could you please rebase on top of the v6 bitfield series so it does not conflict?

https://git.kernel.org/pub/scm/linux/kernel/git/jfern/linux.git/log/?h=nova.dev.bitfield.submitted.v6

Thanks.

Reviewed-by
#3 lore raw

Re: [PATCH RFC v2 1/3] gpu: nova-core: register: use field type for Into implementation

Quoted 32 lines · Joel Fernandes

Hi Alex,

Quoted 26 lines · Alexandre Courbot

The getter method of a field works with the field type, but its setter expects the type of the register. This leads to an asymmetry in the From/Into implementations required for a field with a dedicated type. For instance, a field declared as

   pub struct ControlReg(u32) {
       3:0 mode as u8 ?=> Mode;
       ...
   }

currently requires the following implementations:

   impl TryFrom<u8> for Mode {
     ...
   }

   impl From<Mode> for u32 {
     ...
   }

Change this so the From<Mode> now needs to be implemented for u8, i.e. the primitive type of the field. This is more consistent, and will become a requirement once we start using the TryFrom/Into derive macros to implement these automatically.

Quoted 7 lines
Quoted 2 lines

As these are incremental improvements, could you please rebase on top of the v6 bitfield series so it does not conflict?

https://git.kernel.org/pub/scm/linux/kernel/git/jfern/linux.git/log/?h=nova.dev.bitfield.submitted.v6

On second thought, I could just carry this patch on top of my v6 series and avoid too much conflict.

So if it is ok with you, please only carry the last 2 patches of this series whenever applying.

For this patch:

I will review the other two patches as well. Thanks.

Quoted 2 lines

Thanks.

author maintainer
#4 lore raw

Re: [PATCH RFC v2 1/3] gpu: nova-core: register: use field type for Into implementation

Quoted 40 lines · Joel Fernandes
Quoted 32 lines · Joel Fernandes

Hi Alex,

Quoted 26 lines · Alexandre Courbot

The getter method of a field works with the field type, but its setter expects the type of the register. This leads to an asymmetry in the From/Into implementations required for a field with a dedicated type. For instance, a field declared as

   pub struct ControlReg(u32) {
       3:0 mode as u8 ?=> Mode;
       ...
   }

currently requires the following implementations:

   impl TryFrom<u8> for Mode {
     ...
   }

   impl From<Mode> for u32 {
     ...
   }

Change this so the From<Mode> now needs to be implemented for u8, i.e. the primitive type of the field. This is more consistent, and will become a requirement once we start using the TryFrom/Into derive macros to implement these automatically.

Quoted 7 lines
Quoted 2 lines

As these are incremental improvements, could you please rebase on top of the v6 bitfield series so it does not conflict?

https://git.kernel.org/pub/scm/linux/kernel/git/jfern/linux.git/log/?h=nova.dev.bitfield.submitted.v6

Quoted 8 lines

On second thought, I could just carry this patch on top of my v6 series and avoid too much conflict.

So if it is ok with you, please only carry the last 2 patches of this series whenever applying.

For this patch:

I will review the other two patches as well. Thanks.

The idea is for this patch to go *before* your series, to avoid the asymmetry in the From/Into implementions of bitfields. We could also put it after, but it would become larger as a result and I think it can be merge soon after -rc1 is tagged anyway.

author maintainer
#5 lore raw

Re: [PATCH RFC v2 1/3] gpu: nova-core: register: use field type for Into implementation

Quoted 48 lines · Alexandre Courbot
Quoted 47 lines · Joel Fernandes
Quoted 32 lines · Joel Fernandes

Hi Alex,

Quoted 26 lines · Alexandre Courbot

The getter method of a field works with the field type, but its setter expects the type of the register. This leads to an asymmetry in the From/Into implementations required for a field with a dedicated type. For instance, a field declared as

   pub struct ControlReg(u32) {
       3:0 mode as u8 ?=> Mode;
       ...
   }

currently requires the following implementations:

   impl TryFrom<u8> for Mode {
     ...
   }

   impl From<Mode> for u32 {
     ...
   }

Change this so the From<Mode> now needs to be implemented for u8, i.e. the primitive type of the field. This is more consistent, and will become a requirement once we start using the TryFrom/Into derive macros to implement these automatically.

Quoted 7 lines
Quoted 2 lines

As these are incremental improvements, could you please rebase on top of the v6 bitfield series so it does not conflict?

https://git.kernel.org/pub/scm/linux/kernel/git/jfern/linux.git/log/?h=nova.dev.bitfield.submitted.v6

On second thought, I could just carry this patch on top of my v6 series and avoid too much conflict.

So if it is ok with you, please only carry the last 2 patches of this series whenever applying.

For this patch:

Quoted 6 lines
Quoted 1 line

I will review the other two patches as well. Thanks.

The idea is for this patch to go *before* your series, to avoid the asymmetry in the From/Into implementions of bitfields. We could also put it after, but it would become larger as a result and I think it can be merge soon after -rc1 is tagged anyway.

I forgot to mention that this patch is not really part of the series ; it's just here to allow it to apply on top of drm-rust-next should anyone want to try it.

#6 lore raw

Re: [PATCH RFC v2 1/3] gpu: nova-core: register: use field type for Into implementation

Quoted 51 lines · Alexandre Courbot
Quoted 50 lines · Alexandre Courbot
Quoted 48 lines · Joel Fernandes
Quoted 32 lines · Joel Fernandes

Hi Alex,

Quoted 26 lines · Alexandre Courbot

The getter method of a field works with the field type, but its setter expects the type of the register. This leads to an asymmetry in the From/Into implementations required for a field with a dedicated type. For instance, a field declared as

   pub struct ControlReg(u32) {
       3:0 mode as u8 ?=> Mode;
       ...
   }

currently requires the following implementations:

   impl TryFrom<u8> for Mode {
     ...
   }

   impl From<Mode> for u32 {
     ...
   }

Change this so the From<Mode> now needs to be implemented for u8, i.e. the primitive type of the field. This is more consistent, and will become a requirement once we start using the TryFrom/Into derive macros to implement these automatically.

Quoted 7 lines
Quoted 2 lines

As these are incremental improvements, could you please rebase on top of the v6 bitfield series so it does not conflict?

https://git.kernel.org/pub/scm/linux/kernel/git/jfern/linux.git/log/?h=nova.dev.bitfield.submitted.v6

On second thought, I could just carry this patch on top of my v6 series and avoid too much conflict.

So if it is ok with you, please only carry the last 2 patches of this series whenever applying.

For this patch:

I will review the other two patches as well. Thanks.

Quoted 8 lines
Quoted 4 lines

The idea is for this patch to go *before* your series, to avoid the asymmetry in the From/Into implementions of bitfields. We could also put it after, but it would become larger as a result and I think it can be merge soon after -rc1 is tagged anyway.

I forgot to mention that this patch is not really part of the series ; it's just here to allow it to apply on top of drm-rust-next should anyone want to try it.

These are incremental improvements, I don't see the point in making the improvements before bitfield extraction within Nova. Very least, we can apply the bitfield extraction within nova and then make the improvements (within nova), since the extraction work happened well before (and it was a non-trivial amount of work), before any of these improvements. Let us work together to make sure we don't have to throw away old work due to new patches please. :)

thanks,

- Joel

Reviewed-by on v2 1/3
#7 lore raw

Re: [PATCH RFC v2 1/3] gpu: nova-core: register: use field type for Into implementation

In reply to Alexandre Courbot

drivers/gpu/nova-core/regs/macros.rs

Quoted 157 lines · Alexandre Courbot

The getter method of a field works with the field type, but its setter expects the type of the register. This leads to an asymmetry in the From/Into implementations required for a field with a dedicated type. For instance, a field declared as

   pub struct ControlReg(u32) {
       3:0 mode as u8 ?=> Mode;
       ...
   }

currently requires the following implementations:

   impl TryFrom<u8> for Mode {
     ...
   }

   impl From<Mode> for u32 {
     ...
   }

Change this so the From<Mode> now needs to be implemented for u8, i.e. the primitive type of the field. This is more consistent, and will become a requirement once we start using the TryFrom/Into derive macros to implement these automatically.

---
drivers/gpu/nova-core/falcon.rs | 38 +++++++++++++++++++++++++-----------
drivers/gpu/nova-core/regs/macros.rs | 10 +++++-----

2 files changed, 32 insertions(+), 16 deletions(-)
drivers/gpu/nova-core/falcon.rs +27 -11
index 37e6298195e4..3f505b870601 100644
@@ -22,11 +22,11 @@
 pub(crate) mod sec2;
 
 // TODO[FPRI]: Replace with `ToPrimitive`.
-macro_rules! impl_from_enum_to_u32 {
+macro_rules! impl_from_enum_to_u8 {
    ($enum_type:ty) => {
-        impl From<$enum_type> for u32 {
+        impl From<$enum_type> for u8 {
            fn from(value: $enum_type) -> Self {
-                value as u32
+                value as u8
            }
        }
    };
@@ -46,7 +46,7 @@ pub(crate) enum FalconCoreRev {
    Rev6 = 6,
    Rev7 = 7,
 }
-impl_from_enum_to_u32!(FalconCoreRev);
+impl_from_enum_to_u8!(FalconCoreRev);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconCoreRev {
@@ -81,7 +81,7 @@ pub(crate) enum FalconCoreRevSubversion {
    Subversion2 = 2,
    Subversion3 = 3,
 }
-impl_from_enum_to_u32!(FalconCoreRevSubversion);
+impl_from_enum_to_u8!(FalconCoreRevSubversion);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconCoreRevSubversion {
@@ -125,7 +125,7 @@ pub(crate) enum FalconSecurityModel {
    /// Also known as High-Secure, Privilege Level 3 or PL3.
    Heavy = 3,
 }
-impl_from_enum_to_u32!(FalconSecurityModel);
+impl_from_enum_to_u8!(FalconSecurityModel);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconSecurityModel {
@@ -157,7 +157,7 @@ pub(crate) enum FalconModSelAlgo {
    #[default]
    Rsa3k = 1,
 }
-impl_from_enum_to_u32!(FalconModSelAlgo);
+impl_from_enum_to_u8!(FalconModSelAlgo);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconModSelAlgo {
@@ -179,7 +179,7 @@ pub(crate) enum DmaTrfCmdSize {
    #[default]
    Size256B = 0x6,
 }
-impl_from_enum_to_u32!(DmaTrfCmdSize);
+impl_from_enum_to_u8!(DmaTrfCmdSize);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for DmaTrfCmdSize {
@@ -202,7 +202,6 @@ pub(crate) enum PeregrineCoreSelect {
    /// RISC-V core is active.
    Riscv = 1,
 }
-impl_from_enum_to_u32!(PeregrineCoreSelect);
 
 impl From<bool> for PeregrineCoreSelect {
    fn from(value: bool) -> Self {
@@ -213,6 +212,15 @@ fn from(value: bool) -> Self {
    }
 }
 
+impl From<PeregrineCoreSelect> for bool {
+    fn from(value: PeregrineCoreSelect) -> Self {
+        match value {
+            PeregrineCoreSelect::Falcon => false,
+            PeregrineCoreSelect::Riscv => true,
+        }
+    }
+}
+
 /// Different types of memory present in a falcon core.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum FalconMem {
@@ -236,7 +244,7 @@ pub(crate) enum FalconFbifTarget {
    /// Non-coherent system memory (System DRAM).
    NoncoherentSysmem = 2,
 }
-impl_from_enum_to_u32!(FalconFbifTarget);
+impl_from_enum_to_u8!(FalconFbifTarget);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconFbifTarget {
@@ -263,7 +271,6 @@ pub(crate) enum FalconFbifMemType {
    /// Physical memory addresses.
    Physical = 1,
 }
-impl_from_enum_to_u32!(FalconFbifMemType);
 
 /// Conversion from a single-bit register field.
 impl From<bool> for FalconFbifMemType {
@@ -275,6 +282,15 @@ fn from(value: bool) -> Self {
    }
 }
 
+impl From<FalconFbifMemType> for bool {
+    fn from(value: FalconFbifMemType) -> Self {
+        match value {
+            FalconFbifMemType::Virtual => false,
+            FalconFbifMemType::Physical => true,
+        }
+    }
+}
+
 /// Type used to represent the `PFALCON` registers address base for a given falcon engine.
 pub(crate) struct PFalconBase(());
 
drivers/gpu/nova-core/regs/macros.rs +0 -0

The examples in the doc comments should also be updated. Otherwise, LGTM.

Regards,
Edwin Peer

Quoted 52 lines

index 754c14ee7f40..73811a115762 100644

drivers/gpu/nova-core/regs/macros.rs +5 -5
@@ -482,7 +482,7 @@ impl $name {
        register!(
            @leaf_accessor $name $hi:$lo $field
            { |f| <$into_type>::from(if f != 0 { true } else { false }) }
-            $into_type => $into_type $(, $comment)?;
+            bool $into_type => $into_type $(, $comment)?;
        );
    };
 
@@ -499,7 +499,7 @@ impl $name {
            $(, $comment:literal)?;
    ) => {
        register!(@leaf_accessor $name $hi:$lo $field
-            { |f| <$try_into_type>::try_from(f as $type) } $try_into_type =>
+            { |f| <$try_into_type>::try_from(f as $type) } $type $try_into_type =>
            ::core::result::Result<
                $try_into_type,
                <$try_into_type as ::core::convert::TryFrom<$type>>::Error
@@ -513,7 +513,7 @@ impl $name {
            $(, $comment:literal)?;
    ) => {
        register!(@leaf_accessor $name $hi:$lo $field
-            { |f| <$into_type>::from(f as $type) } $into_type => $into_type $(, $comment)?;);
+            { |f| <$into_type>::from(f as $type) } $type $into_type => $into_type $(, $comment)?;);
    };
 
    // Shortcut for non-boolean fields defined without the `=>` or `?=>` syntax.
@@ -527,7 +527,7 @@ impl $name {
    // Generates the accessor methods for a single field.
    (
        @leaf_accessor $name:ident $hi:tt:$lo:tt $field:ident
-            { $process:expr } $to_type:ty => $res_type:ty $(, $comment:literal)?;
+            { $process:expr } $prim_type:tt $to_type:ty => $res_type:ty $(, $comment:literal)?;
    ) => {
        ::kernel::macros::paste!(
        const [<$field:upper _RANGE>]: ::core::ops::RangeInclusive<u8> = $lo..=$hi;
@@ -559,7 +559,7 @@ pub(crate) fn $field(self) -> $res_type {
        pub(crate) fn [<set_ $field>](mut self, value: $to_type) -> Self {
            const MASK: u32 = $name::[<$field:upper _MASK>];
            const SHIFT: u32 = $name::[<$field:upper _SHIFT>];
-            let value = (u32::from(value) << SHIFT) & MASK;
+            let value = (u32::from($prim_type::from(value)) << SHIFT) & MASK;
            self.0 = (self.0 & !MASK) | value;
 
            self
Signature · 2 lines
-- 
2.51.0
Reviewed-by on v2 1/3
#8 lore raw

Re: [PATCH RFC v2 1/3] gpu: nova-core: register: use field type for Into implementation

In reply to Alexandre Courbot
Quoted 20 lines · Alexandre Courbot

The getter method of a field works with the field type, but its setter expects the type of the register. This leads to an asymmetry in the From/Into implementations required for a field with a dedicated type. For instance, a field declared as

    pub struct ControlReg(u32) {
        3:0 mode as u8 ?=> Mode;
        ...
    }

currently requires the following implementations:

    impl TryFrom<u8> for Mode {
      ...
    }

    impl From<Mode> for u32 {
      ...
    }
Quoted 7 lines

Change this so the From<Mode> now needs to be implemented for u8, i.e. the primitive type of the field. This is more consistent, and will become a requirement once we start using the TryFrom/Into derive macros to implement these automatically.

thanks,

- Joel

Quoted 179 lines
---
 drivers/gpu/nova-core/falcon.rs      | 38 +++++++++++++++++++++++++-----------
 drivers/gpu/nova-core/regs/macros.rs | 10 +++++-----
 2 files changed, 32 insertions(+), 16 deletions(-)
drivers/gpu/nova-core/falcon.rs +27 -11
index 37e6298195e4..3f505b870601 100644
@@ -22,11 +22,11 @@
 pub(crate) mod sec2;
 
 // TODO[FPRI]: Replace with `ToPrimitive`.
-macro_rules! impl_from_enum_to_u32 {
+macro_rules! impl_from_enum_to_u8 {
     ($enum_type:ty) => {
-        impl From<$enum_type> for u32 {
+        impl From<$enum_type> for u8 {
             fn from(value: $enum_type) -> Self {
-                value as u32
+                value as u8
             }
         }
     };
@@ -46,7 +46,7 @@ pub(crate) enum FalconCoreRev {
     Rev6 = 6,
     Rev7 = 7,
 }
-impl_from_enum_to_u32!(FalconCoreRev);
+impl_from_enum_to_u8!(FalconCoreRev);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconCoreRev {
@@ -81,7 +81,7 @@ pub(crate) enum FalconCoreRevSubversion {
     Subversion2 = 2,
     Subversion3 = 3,
 }
-impl_from_enum_to_u32!(FalconCoreRevSubversion);
+impl_from_enum_to_u8!(FalconCoreRevSubversion);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconCoreRevSubversion {
@@ -125,7 +125,7 @@ pub(crate) enum FalconSecurityModel {
     /// Also known as High-Secure, Privilege Level 3 or PL3.
     Heavy = 3,
 }
-impl_from_enum_to_u32!(FalconSecurityModel);
+impl_from_enum_to_u8!(FalconSecurityModel);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconSecurityModel {
@@ -157,7 +157,7 @@ pub(crate) enum FalconModSelAlgo {
     #[default]
     Rsa3k = 1,
 }
-impl_from_enum_to_u32!(FalconModSelAlgo);
+impl_from_enum_to_u8!(FalconModSelAlgo);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconModSelAlgo {
@@ -179,7 +179,7 @@ pub(crate) enum DmaTrfCmdSize {
     #[default]
     Size256B = 0x6,
 }
-impl_from_enum_to_u32!(DmaTrfCmdSize);
+impl_from_enum_to_u8!(DmaTrfCmdSize);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for DmaTrfCmdSize {
@@ -202,7 +202,6 @@ pub(crate) enum PeregrineCoreSelect {
     /// RISC-V core is active.
     Riscv = 1,
 }
-impl_from_enum_to_u32!(PeregrineCoreSelect);
 
 impl From<bool> for PeregrineCoreSelect {
     fn from(value: bool) -> Self {
@@ -213,6 +212,15 @@ fn from(value: bool) -> Self {
     }
 }
 
+impl From<PeregrineCoreSelect> for bool {
+    fn from(value: PeregrineCoreSelect) -> Self {
+        match value {
+            PeregrineCoreSelect::Falcon => false,
+            PeregrineCoreSelect::Riscv => true,
+        }
+    }
+}
+
 /// Different types of memory present in a falcon core.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum FalconMem {
@@ -236,7 +244,7 @@ pub(crate) enum FalconFbifTarget {
     /// Non-coherent system memory (System DRAM).
     NoncoherentSysmem = 2,
 }
-impl_from_enum_to_u32!(FalconFbifTarget);
+impl_from_enum_to_u8!(FalconFbifTarget);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
 impl TryFrom<u8> for FalconFbifTarget {
@@ -263,7 +271,6 @@ pub(crate) enum FalconFbifMemType {
     /// Physical memory addresses.
     Physical = 1,
 }
-impl_from_enum_to_u32!(FalconFbifMemType);
 
 /// Conversion from a single-bit register field.
 impl From<bool> for FalconFbifMemType {
@@ -275,6 +282,15 @@ fn from(value: bool) -> Self {
     }
 }
 
+impl From<FalconFbifMemType> for bool {
+    fn from(value: FalconFbifMemType) -> Self {
+        match value {
+            FalconFbifMemType::Virtual => false,
+            FalconFbifMemType::Physical => true,
+        }
+    }
+}
+
 /// Type used to represent the `PFALCON` registers address base for a given falcon engine.
 pub(crate) struct PFalconBase(());
 
drivers/gpu/nova-core/regs/macros.rs +5 -5
index 754c14ee7f40..73811a115762 100644
@@ -482,7 +482,7 @@ impl $name {
         register!(
             @leaf_accessor $name $hi:$lo $field
             { |f| <$into_type>::from(if f != 0 { true } else { false }) }
-            $into_type => $into_type $(, $comment)?;
+            bool $into_type => $into_type $(, $comment)?;
         );
     };
 
@@ -499,7 +499,7 @@ impl $name {
             $(, $comment:literal)?;
     ) => {
         register!(@leaf_accessor $name $hi:$lo $field
-            { |f| <$try_into_type>::try_from(f as $type) } $try_into_type =>
+            { |f| <$try_into_type>::try_from(f as $type) } $type $try_into_type =>
             ::core::result::Result<
                 $try_into_type,
                 <$try_into_type as ::core::convert::TryFrom<$type>>::Error
@@ -513,7 +513,7 @@ impl $name {
             $(, $comment:literal)?;
     ) => {
         register!(@leaf_accessor $name $hi:$lo $field
-            { |f| <$into_type>::from(f as $type) } $into_type => $into_type $(, $comment)?;);
+            { |f| <$into_type>::from(f as $type) } $type $into_type => $into_type $(, $comment)?;);
     };
 
     // Shortcut for non-boolean fields defined without the `=>` or `?=>` syntax.
@@ -527,7 +527,7 @@ impl $name {
     // Generates the accessor methods for a single field.
     (
         @leaf_accessor $name:ident $hi:tt:$lo:tt $field:ident
-            { $process:expr } $to_type:ty => $res_type:ty $(, $comment:literal)?;
+            { $process:expr } $prim_type:tt $to_type:ty => $res_type:ty $(, $comment:literal)?;
     ) => {
         ::kernel::macros::paste!(
         const [<$field:upper _RANGE>]: ::core::ops::RangeInclusive<u8> = $lo..=$hi;
@@ -559,7 +559,7 @@ pub(crate) fn $field(self) -> $res_type {
         pub(crate) fn [<set_ $field>](mut self, value: $to_type) -> Self {
             const MASK: u32 = $name::[<$field:upper _MASK>];
             const SHIFT: u32 = $name::[<$field:upper _SHIFT>];
-            let value = (u32::from(value) << SHIFT) & MASK;
+            let value = (u32::from($prim_type::from(value)) << SHIFT) & MASK;
             self.0 = (self.0 & !MASK) | value;
 
             self
Signature · 2 lines
-- 
2.51.0
author maintainer
#9 lore raw

RFC PATCH v2 2/3 rust: kernel: add bounded integer types

In reply to Alexandre Courbot

Add the BoundedInt type, which restricts the number of bits allowed to be used in a given integer value. This is useful to carry guarantees when setting bitfields.

Alongside this type, many From and TryFrom implementations are provided to reduce friction when using with regular integer types. Proxy implementations of common integer traits are also provided.

---
 rust/kernel/lib.rs |   1 +
 rust/kernel/num.rs | 499 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 500 insertions(+)
rust/kernel/lib.rs +1 -0
index fcffc3988a90..21c1f452ee6a 100644
@@ -101,6 +101,7 @@
 pub mod mm;
 #[cfg(CONFIG_NET)]
 pub mod net;
+pub mod num;
 pub mod of;
 #[cfg(CONFIG_PM_OPP)]
 pub mod opp;
rust/kernel/num.rs new file +499 -0

499 lines not on this page · raw message

Signature · 1 line
2.51.0
#10 lore raw

Re: [PATCH RFC v2 2/3] rust: kernel: add bounded integer types

Hi Alex,

Great effort, thanks. I replied with few comments below. Since the patch is large, it would be great if could be possibly split. Maybe the From primitives deserve a separate patch.

Quoted 90 lines · Alexandre Courbot

Add the BoundedInt type, which restricts the number of bits allowed to be used in a given integer value. This is useful to carry guarantees when setting bitfields.

Alongside this type, many From and TryFrom implementations are provided to reduce friction when using with regular integer types. Proxy implementations of common integer traits are also provided.

---
 rust/kernel/lib.rs |   1 +
 rust/kernel/num.rs | 499 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 500 insertions(+)
rust/kernel/lib.rs +1 -0
index fcffc3988a90..21c1f452ee6a 100644
@@ -101,6 +101,7 @@
 pub mod mm;
 #[cfg(CONFIG_NET)]
 pub mod net;
+pub mod num;
 pub mod of;
 #[cfg(CONFIG_PM_OPP)]
 pub mod opp;
rust/kernel/num.rs new file +58 -0
new file mode 100644
index 000000000000..b2aad95ce51c
@@ -0,0 +1,499 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Numerical types for the kernel.
+
+use kernel::prelude::*;
+
+/// Integer type for which only the bits `0..NUM_BITS` are valid.
+///
+/// # Invariants
+///
+/// Stored values are represented with at most `NUM_BITS` bits.
+#[repr(transparent)]
+#[derive(Clone, Copy, Debug, Default, Hash)]
+pub struct BoundedInt<T, const NUM_BITS: u32>(T);
+
+/// Returns `true` if `$value` can be represented with at most `$NUM_BITS` on `$type`.
+macro_rules! is_in_bounds {
+    ($value:expr, $type:ty, $num_bits:expr) => {{
+        let v = $value;
+        v & <$type as Boundable<NUM_BITS>>::MASK == v
+    }};
+}
+
+/// Trait for primitive integer types that can be used with `BoundedInt`.
+pub trait Boundable<const NUM_BITS: u32>
+where
+    Self: Sized + Copy + core::ops::BitAnd<Output = Self> + core::cmp::PartialEq,
+    Self: TryInto<u8> + TryInto<u16> + TryInto<u32> + TryInto<u64>,
+{
+    /// Mask of the valid bits for this type.
+    const MASK: Self;
+
+    /// Returns `true` if `value` can be represented with at most `NUM_BITS`.
+    ///
+    /// TODO: post-RFC: replace this with a left-shift followed by right-shift operation. This will
+    /// allow us to handle signed values as well.
+    fn is_in_bounds(value: Self) -> bool {
+        is_in_bounds!(value, Self, NUM_BITS)
+    }
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u8 {
+    const MASK: u8 = crate::bits::genmask_u8(0..=(NUM_BITS - 1));
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u16 {
+    const MASK: u16 = crate::bits::genmask_u16(0..=(NUM_BITS - 1));
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u32 {
+    const MASK: u32 = crate::bits::genmask_u32(0..=(NUM_BITS - 1));
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u64 {
+    const MASK: u64 = crate::bits::genmask_u64(0..=(NUM_BITS - 1));
+}
+
+impl<T, const NUM_BITS: u32> BoundedInt<T, NUM_BITS>

rust/kernel/num.rs line 68

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+where
+    T: Boundable<NUM_BITS>,
+{
+    /// Checks that `value` is valid for this type at compile-time and build a new value.
+    ///
+    /// This relies on [`build_assert!`] to perform validation at compile-time. If `value` cannot
+    /// be inferred to be in bounds at compile-time, use the fallible [`Self::try_new`] instead.
+    ///
+    /// When possible, use one of the `new_const` methods instead of this method as it statically
+    /// validates `value` instead of relying on the compiler's optimizations.

This sounds like, users might use the less-optimal API first with the same build_assert issues we had with the IO accessors, since new() sounds very obvious. How about the following naming?

new::<VALUE>()        // Primary constructor for constants using const generics.
try_new(value)        // Keep as-is for fallible runtime
new_from_expr(value)  // For compile-time validated runtime values

If new::<VALUE>() does not work for the user, the compiler will fail.

Or, new_from_expr() could be from_value(), Ok with either naming or a better name.

Quoted 57 lines
rust/kernel/num.rs new file +57 -0
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///
+    /// # fn some_number() -> u32 { 0xffffffff }
+    ///
+    /// assert_eq!(BoundedInt::<u8, 1>::new(1).get(), 1);
+    /// assert_eq!(BoundedInt::<u16, 8>::new(0xff).get(), 0xff);
+    ///
+    /// // Triggers a build error as `0x1ff` doesn't fit into 8 bits.
+    /// // assert_eq!(BoundedInt::<u32, 8>::new(0x1ff).get(), 0x1ff);
+    ///
+    /// let v: u32 = some_number();
+    /// // Triggers a build error as `v` cannot be asserted to fit within 4 bits...
+    /// // let _ = BoundedInt::<u32, 4>::new(v);
+    /// // ... but this works as the compiler can assert the range from the mask.
+    /// let _ = BoundedInt::<u32, 4>::new(v & 0xf);
+    /// ```
+    pub fn new(value: T) -> Self {
+        crate::build_assert!(
+            T::is_in_bounds(value),
+            "Provided parameter is larger than maximal supported value"
+        );
+
+        Self(value)
+    }
+
+    /// Attempts to convert `value` into a value bounded by `NUM_BITS`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///
+    /// assert_eq!(BoundedInt::<u8, 1>::try_new(1).map(|v| v.get()), Ok(1));
+    /// assert_eq!(BoundedInt::<u16, 8>::try_new(0xff).map(|v| v.get()), Ok(0xff));
+    ///
+    /// // `0x1ff` doesn't fit into 8 bits.
+    /// assert_eq!(BoundedInt::<u32, 8>::try_new(0x1ff), Err(EOVERFLOW));
+    /// ```
+    pub fn try_new(value: T) -> Result<Self> {
+        if !T::is_in_bounds(value) {
+            Err(EOVERFLOW)
+        } else {
+            Ok(Self(value))
+        }
+    }
+
+    /// Returns the contained value as a primitive type.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///

rust/kernel/num.rs line 135

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+    /// let v = BoundedInt::<u32, 4>::new_const::<7>();
+    /// assert_eq!(v.get(), 7u32);
+    /// ```
+    pub fn get(self) -> T {
+        if !T::is_in_bounds(self.0) {
+            // SAFETY: Per the invariants, `self.0` cannot have bits set outside of `MASK`, so
+            // this block will
+            // never be reached.
+            unsafe { core::hint::unreachable_unchecked() }
+        }

Does this if block help the compiler generate better code? I wonder if code gen could be checked to confirm the rationale.

Quoted 11 lines
rust/kernel/num.rs new file +11 -0
+        self.0
+    }
+
+    /// Increase the number of bits usable for `self`.
+    ///
+    /// This operation cannot fail.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;

rust/kernel/num.rs line 156

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+    ///
+    /// let v = BoundedInt::<u32, 4>::new_const::<7>();
+    /// let larger_v = v.enlarge::<12>();
+    /// // The contained values are equal even though `larger_v` has a bigger capacity.
+    /// assert_eq!(larger_v, v);
+    /// ```
+    pub const fn enlarge<const NEW_NUM_BITS: u32>(self) -> BoundedInt<T, NEW_NUM_BITS>
+    where
+        T: Boundable<NEW_NUM_BITS>,
+        T: Copy,

Boundable already implies copy so T: Copy is redundant.

Quoted 18 lines
rust/kernel/num.rs new file +18 -0
+    {
+        build_assert!(NEW_NUM_BITS >= NUM_BITS);
+
+        // INVARIANT: the value did fit within `NUM_BITS`, so it will all the more fit within
+        // `NEW_NUM_BITS` which is larger.
+        BoundedInt(self.0)
+    }
+
+    /// Shrink the number of bits usable for `self`.
+    ///
+    /// Returns `EOVERFLOW` if the value of `self` cannot be represented within `NEW_NUM_BITS`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///
+    /// let v = BoundedInt::<u32, 12>::new_const::<7>();

rust/kernel/num.rs line 184

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+    /// let smaller_v = v.shrink::<4>()?;
+    /// // The contained values are equal even though `smaller_v` has a smaller capacity.
+    /// assert_eq!(smaller_v, v);
+    ///
+    /// # Ok::<(), Error>(())
+    /// ```
+    pub fn shrink<const NEW_NUM_BITS: u32>(self) -> Result<BoundedInt<T, NEW_NUM_BITS>>
+    where
+        T: Boundable<NEW_NUM_BITS>,
+        T: Copy,

Here too.

[...]

Quoted 11 lines
rust/kernel/num.rs new file +11 -0
+impl_const_new!(u8 u16 u32 u64);
+
+/// Declares a new `$trait` and implements it for all bounded types represented using `$num_bits`.
+///
+/// This is used to declare properties as traits that we can use for later implementations.
+macro_rules! impl_size_rule {
+    ($trait:ident, $($num_bits:literal)*) => {
+        trait $trait {}
+
+        $(
+        impl<T> $trait for BoundedInt<T, $num_bits> where T: Boundable<$num_bits> {}

rust/kernel/num.rs line 270

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+        )*
+    };
+}
+
+// Bounds that are larger than a `u64`.
+impl_size_rule!(LargerThanU64, 64);
+
+// Bounds that are larger than a `u32`.
+impl_size_rule!(LargerThanU32,
+    32 33 34 35 36 37 38 39

If num_bits == 32 (number of bits), how could BoundedInt<T, 32> a LargerThanU32? It should be AtleastU32 or something.

Or the above list should start from 33. Only a >= 33-bit wide integer can be LargerThanU32.

Thanks.

author maintainer
#11 lore raw

Re: [PATCH RFC v2 2/3] rust: kernel: add bounded integer types

Quoted 5 lines · Joel Fernandes

Hi Alex,

Great effort, thanks. I replied with few comments below. Since the patch is large, it would be great if could be possibly split. Maybe the From primitives deserve a separate patch.

I'm all for smaller patches when it makes reviewing easier, but in this case all it would achieve is making the second patch append code right after the next. :) Is there a benefit in doing so?

Quoted 107 lines · Alexandre Courbot
Quoted 90 lines

Add the BoundedInt type, which restricts the number of bits allowed to be used in a given integer value. This is useful to carry guarantees when setting bitfields.

Alongside this type, many From and TryFrom implementations are provided to reduce friction when using with regular integer types. Proxy implementations of common integer traits are also provided.

---
 rust/kernel/lib.rs |   1 +
 rust/kernel/num.rs | 499 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 500 insertions(+)
rust/kernel/lib.rs +1 -0
index fcffc3988a90..21c1f452ee6a 100644
@@ -101,6 +101,7 @@
 pub mod mm;
 #[cfg(CONFIG_NET)]
 pub mod net;
+pub mod num;
 pub mod of;
 #[cfg(CONFIG_PM_OPP)]
 pub mod opp;
rust/kernel/num.rs new file +58 -0
new file mode 100644
index 000000000000..b2aad95ce51c
@@ -0,0 +1,499 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Numerical types for the kernel.
+
+use kernel::prelude::*;
+
+/// Integer type for which only the bits `0..NUM_BITS` are valid.
+///
+/// # Invariants
+///
+/// Stored values are represented with at most `NUM_BITS` bits.
+#[repr(transparent)]
+#[derive(Clone, Copy, Debug, Default, Hash)]
+pub struct BoundedInt<T, const NUM_BITS: u32>(T);
+
+/// Returns `true` if `$value` can be represented with at most `$NUM_BITS` on `$type`.
+macro_rules! is_in_bounds {
+    ($value:expr, $type:ty, $num_bits:expr) => {{
+        let v = $value;
+        v & <$type as Boundable<NUM_BITS>>::MASK == v
+    }};
+}
+
+/// Trait for primitive integer types that can be used with `BoundedInt`.
+pub trait Boundable<const NUM_BITS: u32>
+where
+    Self: Sized + Copy + core::ops::BitAnd<Output = Self> + core::cmp::PartialEq,
+    Self: TryInto<u8> + TryInto<u16> + TryInto<u32> + TryInto<u64>,
+{
+    /// Mask of the valid bits for this type.
+    const MASK: Self;
+
+    /// Returns `true` if `value` can be represented with at most `NUM_BITS`.
+    ///
+    /// TODO: post-RFC: replace this with a left-shift followed by right-shift operation. This will
+    /// allow us to handle signed values as well.
+    fn is_in_bounds(value: Self) -> bool {
+        is_in_bounds!(value, Self, NUM_BITS)
+    }
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u8 {
+    const MASK: u8 = crate::bits::genmask_u8(0..=(NUM_BITS - 1));
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u16 {
+    const MASK: u16 = crate::bits::genmask_u16(0..=(NUM_BITS - 1));
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u32 {
+    const MASK: u32 = crate::bits::genmask_u32(0..=(NUM_BITS - 1));
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u64 {
+    const MASK: u64 = crate::bits::genmask_u64(0..=(NUM_BITS - 1));
+}
+
+impl<T, const NUM_BITS: u32> BoundedInt<T, NUM_BITS>

rust/kernel/num.rs line 68

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+where
+    T: Boundable<NUM_BITS>,
+{
+    /// Checks that `value` is valid for this type at compile-time and build a new value.
+    ///
+    /// This relies on [`build_assert!`] to perform validation at compile-time. If `value` cannot
+    /// be inferred to be in bounds at compile-time, use the fallible [`Self::try_new`] instead.
+    ///
+    /// When possible, use one of the `new_const` methods instead of this method as it statically
+    /// validates `value` instead of relying on the compiler's optimizations.

This sounds like, users might use the less-optimal API first with the same build_assert issues we had with the IO accessors, since new() sounds very obvious. How about the following naming?

Quoted 7 lines
new::<VALUE>()        // Primary constructor for constants using const generics.
try_new(value)        // Keep as-is for fallible runtime
new_from_expr(value)  // For compile-time validated runtime values

If new::<VALUE>() does not work for the user, the compiler will fail.

Or, new_from_expr() could be from_value(), Ok with either naming or a better name.

Agreed, the preferred method should appear first. IIRC Alice also made a similar suggestion about v1 during the DRM sync, sorry for not picking it up.

Quoted 63 lines
Quoted 63 lines
rust/kernel/num.rs new file +62 -0
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///
+    /// # fn some_number() -> u32 { 0xffffffff }
+    ///
+    /// assert_eq!(BoundedInt::<u8, 1>::new(1).get(), 1);
+    /// assert_eq!(BoundedInt::<u16, 8>::new(0xff).get(), 0xff);
+    ///
+    /// // Triggers a build error as `0x1ff` doesn't fit into 8 bits.
+    /// // assert_eq!(BoundedInt::<u32, 8>::new(0x1ff).get(), 0x1ff);
+    ///
+    /// let v: u32 = some_number();
+    /// // Triggers a build error as `v` cannot be asserted to fit within 4 bits...
+    /// // let _ = BoundedInt::<u32, 4>::new(v);
+    /// // ... but this works as the compiler can assert the range from the mask.
+    /// let _ = BoundedInt::<u32, 4>::new(v & 0xf);
+    /// ```
+    pub fn new(value: T) -> Self {
+        crate::build_assert!(
+            T::is_in_bounds(value),
+            "Provided parameter is larger than maximal supported value"
+        );
+
+        Self(value)
+    }
+
+    /// Attempts to convert `value` into a value bounded by `NUM_BITS`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///
+    /// assert_eq!(BoundedInt::<u8, 1>::try_new(1).map(|v| v.get()), Ok(1));
+    /// assert_eq!(BoundedInt::<u16, 8>::try_new(0xff).map(|v| v.get()), Ok(0xff));
+    ///
+    /// // `0x1ff` doesn't fit into 8 bits.
+    /// assert_eq!(BoundedInt::<u32, 8>::try_new(0x1ff), Err(EOVERFLOW));
+    /// ```
+    pub fn try_new(value: T) -> Result<Self> {
+        if !T::is_in_bounds(value) {
+            Err(EOVERFLOW)
+        } else {
+            Ok(Self(value))
+        }
+    }
+
+    /// Returns the contained value as a primitive type.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///
+    /// let v = BoundedInt::<u32, 4>::new_const::<7>();
+    /// assert_eq!(v.get(), 7u32);
+    /// ```
+    pub fn get(self) -> T {
+        if !T::is_in_bounds(self.0) {
Quoted 8 lines

rust/kernel/num.rs line 135

Quoted 5 lines
rust/kernel/num.rs new file +5 -0
+            // SAFETY: Per the invariants, `self.0` cannot have bits set outside of `MASK`, so
+            // this block will
+            // never be reached.
+            unsafe { core::hint::unreachable_unchecked() }
+        }

Does this if block help the compiler generate better code? I wonder if code gen could be checked to confirm the rationale.

Benno suggested that it would on a different patch:

https://lore.kernel.org/rust-for-linux/[email protected]/

OTOH as shown in patch 3/3, this doesn't exempt us from handling impossible values when using this in a match expression...

Quoted 23 lines
Quoted 12 lines
rust/kernel/num.rs new file +11 -0
+        self.0
+    }
+
+    /// Increase the number of bits usable for `self`.
+    ///
+    /// This operation cannot fail.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;

rust/kernel/num.rs line 156

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+    ///
+    /// let v = BoundedInt::<u32, 4>::new_const::<7>();
+    /// let larger_v = v.enlarge::<12>();
+    /// // The contained values are equal even though `larger_v` has a bigger capacity.
+    /// assert_eq!(larger_v, v);
+    /// ```
+    pub const fn enlarge<const NEW_NUM_BITS: u32>(self) -> BoundedInt<T, NEW_NUM_BITS>
+    where
+        T: Boundable<NEW_NUM_BITS>,
+        T: Copy,
Quoted 1 line

Boundable already implies copy so T: Copy is redundant.

Thanks. I need to do a thorough review of all the contraints as I've changed them quite a bit as the implementation matured.

Quoted 58 lines
Quoted 19 lines
rust/kernel/num.rs new file +18 -0
+    {
+        build_assert!(NEW_NUM_BITS >= NUM_BITS);
+
+        // INVARIANT: the value did fit within `NUM_BITS`, so it will all the more fit within
+        // `NEW_NUM_BITS` which is larger.
+        BoundedInt(self.0)
+    }
+
+    /// Shrink the number of bits usable for `self`.
+    ///
+    /// Returns `EOVERFLOW` if the value of `self` cannot be represented within `NEW_NUM_BITS`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///
+    /// let v = BoundedInt::<u32, 12>::new_const::<7>();

rust/kernel/num.rs line 184

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+    /// let smaller_v = v.shrink::<4>()?;
+    /// // The contained values are equal even though `smaller_v` has a smaller capacity.
+    /// assert_eq!(smaller_v, v);
+    ///
+    /// # Ok::<(), Error>(())
+    /// ```
+    pub fn shrink<const NEW_NUM_BITS: u32>(self) -> Result<BoundedInt<T, NEW_NUM_BITS>>
+    where
+        T: Boundable<NEW_NUM_BITS>,
+        T: Copy,

Here too.

[...]

Quoted 11 lines
rust/kernel/num.rs new file +11 -0
+impl_const_new!(u8 u16 u32 u64);
+
+/// Declares a new `$trait` and implements it for all bounded types represented using `$num_bits`.
+///
+/// This is used to declare properties as traits that we can use for later implementations.
+macro_rules! impl_size_rule {
+    ($trait:ident, $($num_bits:literal)*) => {
+        trait $trait {}
+
+        $(
+        impl<T> $trait for BoundedInt<T, $num_bits> where T: Boundable<$num_bits> {}

rust/kernel/num.rs line 270

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+        )*
+    };
+}
+
+// Bounds that are larger than a `u64`.
+impl_size_rule!(LargerThanU64, 64);
+
+// Bounds that are larger than a `u32`.
+impl_size_rule!(LargerThanU32,
+    32 33 34 35 36 37 38 39

If num_bits == 32 (number of bits), how could BoundedInt<T, 32> a LargerThanU32? It should be AtleastU32 or something.

Quoted 2 lines

Or the above list should start from 33. Only a >= 33-bit wide integer can be LargerThanU32.

The name is a bit ambiguous indeed. An accurate one would be LargerOrEqualThanU32, but AtLeastU32 should also work.

#12 lore raw

Re: [PATCH RFC v2 2/3] rust: kernel: add bounded integer types

Quoted 10 lines · Alexandre Courbot
Quoted 5 lines · Joel Fernandes

Hi Alex,

Great effort, thanks. I replied with few comments below. Since the patch is large, it would be great if could be possibly split. Maybe the From primitives deserve a separate patch.

I'm all for smaller patches when it makes reviewing easier, but in this case all it would achieve is making the second patch append code right after the next. :) Is there a benefit in doing so?

I think there is a benefit, because reviewers don't have to scroll through huge emails :). Plus separate commit messages would be added in too, to reason about new code. There's other possible logical splits too, was just giving example but I am Ok with it if you still want to keep it singular. :)

Quoted 32 lines
Quoted 32 lines
Quoted 13 lines
rust/kernel/num.rs new file +13 -0
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u16 {
+    const MASK: u16 = crate::bits::genmask_u16(0..=(NUM_BITS - 1));
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u32 {
+    const MASK: u32 = crate::bits::genmask_u32(0..=(NUM_BITS - 1));
+}
+
+impl<const NUM_BITS: u32> Boundable<NUM_BITS> for u64 {
+    const MASK: u64 = crate::bits::genmask_u64(0..=(NUM_BITS - 1));
+}
+
+impl<T, const NUM_BITS: u32> BoundedInt<T, NUM_BITS>

rust/kernel/num.rs line 68

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+where
+    T: Boundable<NUM_BITS>,
+{
+    /// Checks that `value` is valid for this type at compile-time and build a new value.
+    ///
+    /// This relies on [`build_assert!`] to perform validation at compile-time. If `value` cannot
+    /// be inferred to be in bounds at compile-time, use the fallible [`Self::try_new`] instead.
+    ///
+    /// When possible, use one of the `new_const` methods instead of this method as it statically
+    /// validates `value` instead of relying on the compiler's optimizations.

This sounds like, users might use the less-optimal API first with the same build_assert issues we had with the IO accessors, since new() sounds very obvious. How about the following naming?

new::<VALUE>()        // Primary constructor for constants using const generics.
try_new(value)        // Keep as-is for fallible runtime
new_from_expr(value)  // For compile-time validated runtime values
Quoted 7 lines
Quoted 3 lines

If new::<VALUE>() does not work for the user, the compiler will fail.

Or, new_from_expr() could be from_value(), Ok with either naming or a better name.

Agreed, the preferred method should appear first. IIRC Alice also made a similar suggestion about v1 during the DRM sync, sorry for not picking it up.

Cool, sounds good.

[..]>>> + /// Returns the contained value as a primitive type.

Quoted 20 lines
Quoted 17 lines
Quoted 6 lines
rust/kernel/num.rs new file +6 -0
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///

rust/kernel/num.rs line 135

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+    /// let v = BoundedInt::<u32, 4>::new_const::<7>();
+    /// assert_eq!(v.get(), 7u32);
+    /// ```
+    pub fn get(self) -> T {
+        if !T::is_in_bounds(self.0) {
+            // SAFETY: Per the invariants, `self.0` cannot have bits set outside of `MASK`, so
+            // this block will
+            // never be reached.
+            unsafe { core::hint::unreachable_unchecked() }
+        }
Quoted 2 lines

Does this if block help the compiler generate better code? I wonder if code gen could be checked to confirm the rationale.

Quoted 6 lines

Benno suggested that it would on a different patch:

https://lore.kernel.org/rust-for-linux/[email protected]/

OTOH as shown in patch 3/3, this doesn't exempt us from handling impossible values when using this in a match expression...

Interesting, TIL.

Quoted 22 lines
Quoted 22 lines
Quoted 21 lines
rust/kernel/num.rs new file +21 -0
+        self.0
+    }
+
+    /// Increase the number of bits usable for `self`.
+    ///
+    /// This operation cannot fail.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use kernel::num::BoundedInt;
+    ///
+    /// let v = BoundedInt::<u32, 4>::new_const::<7>();
+    /// let larger_v = v.enlarge::<12>();
+    /// // The contained values are equal even though `larger_v` has a bigger capacity.
+    /// assert_eq!(larger_v, v);
+    /// ```
+    pub const fn enlarge<const NEW_NUM_BITS: u32>(self) -> BoundedInt<T, NEW_NUM_BITS>
+    where
+        T: Boundable<NEW_NUM_BITS>,
+        T: Copy,
Quoted 4 lines
Quoted 1 line

Boundable already implies copy so T: Copy is redundant.

Thanks. I need to do a thorough review of all the contraints as I've changed them quite a bit as the implementation matured.

Cool. :)

Quoted 26 lines
Quoted 26 lines

[...]

Quoted 11 lines
rust/kernel/num.rs new file +11 -0
+impl_const_new!(u8 u16 u32 u64);
+
+/// Declares a new `$trait` and implements it for all bounded types represented using `$num_bits`.
+///
+/// This is used to declare properties as traits that we can use for later implementations.
+macro_rules! impl_size_rule {
+    ($trait:ident, $($num_bits:literal)*) => {
+        trait $trait {}
+
+        $(
+        impl<T> $trait for BoundedInt<T, $num_bits> where T: Boundable<$num_bits> {}

rust/kernel/num.rs line 270

Quoted 10 lines
rust/kernel/num.rs new file +10 -0
+        )*
+    };
+}
+
+// Bounds that are larger than a `u64`.
+impl_size_rule!(LargerThanU64, 64);
+
+// Bounds that are larger than a `u32`.
+impl_size_rule!(LargerThanU32,
+    32 33 34 35 36 37 38 39

If num_bits == 32 (number of bits), how could BoundedInt<T, 32> a LargerThanU32? It should be AtleastU32 or something.

Quoted 5 lines
Quoted 2 lines

Or the above list should start from 33. Only a >= 33-bit wide integer can be LargerThanU32.

The name is a bit ambiguous indeed. An accurate one would be LargerOrEqualThanU32, but AtLeastU32 should also work.

Sure, I prefer AtLeastU32 since it is shorter :)

thanks,

- Joel

maintainer
#13 lore raw

Re: [PATCH RFC v2 2/3] rust: kernel: add bounded integer types

In reply to Alexandre Courbot
Quoted 10 lines · Alexandre Courbot

Add the BoundedInt type, which restricts the number of bits allowed to be used in a given integer value. This is useful to carry guarantees when setting bitfields.

Alongside this type, many From and TryFrom implementations are provided to reduce friction when using with regular integer types. Proxy implementations of common integer traits are also provided.

rust/kernel/num.rs line 158

Quoted 6 lines
rust/kernel/num.rs new file +6 -0
+    pub const fn enlarge<const NEW_NUM_BITS: u32>(self) -> BoundedInt<T, NEW_NUM_BITS>
+    where
+        T: Boundable<NEW_NUM_BITS>,
+        T: Copy,
+    {
+        build_assert!(NEW_NUM_BITS >= NUM_BITS);

This assertion can be evaluated in const context.

const {
    assert!(NEW_NUM_BITS >= NUM_BITS);
}

Alice

author maintainer
#14 lore raw

RFC PATCH v2 3/3 gpu: nova-core: use BoundedInt

In reply to Alexandre Courbot

Use BoundedInt with the register!() macro and adapt the nova-core code accordingly. This makes it impossible to trim values when setting a register field, because either the value of the field has been inferred at compile-time to fit within the bounds of the field, or the user has been forced to check at runtime that it does indeed fit.

The use of BoundedInt actually simplifies register fields definitions, as they don't need an intermediate storage type (the "as ..." part of fields definitions). Instead, the internal storage type for each field is now the bounded integer of its width in bits, which can optionally be converted to another type that implements `From`` or `TryFrom`` for that bounded integer type.

This means that something like

register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
3:3 status_valid as bool,
31:8 addr as u32,
});

Now becomes

  register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
      3:3     status_valid => bool,
      31:8    addr,
  });

(here status_valid is infallibly converted to a bool for convenience and to remain compatible with the previous semantics)

The field setter/getters are also simplified. If a field has no target type, then its setter expects any type that implements Into to the field's bounded integer type. Due to the many From implementations for primitive types, this means that most calls can be left unchanged. If the caller passes a value that is potentially larger than the field's capacity, it must use the try_ variant of the setter, which returns an error if the value cannot be converted at runtime.

For fields that use => to convert to another type, both setter and getter are always infallible.

For fields that use ?=> to fallibly convert to another type, only the getter needs to be fallible as the setter always provide valid values by design.

Outside of the register macro, the biggest changes occur in falcon.rs, which defines many enums for fields - their conversion implementations need to be changed from the original primitive type of the field to the new corresponding bounded int type. Hopefully the TryFrom/Into derive macros [1] can take care of implementing these, but it will need to be adapted to support bounded integers... :/

But overall, I am rather happy at how simple it was to convert the whole of nova-core to this.

Note: This RFC uses nova-core's register!() macro for practical purposes, but the hope is to move this patch on top of the bitfield macro after it is split out [2].

[1] https://lore.kernel.org/rust-for-linux/[email protected]/
[2] https://lore.kernel.org/rust-for-linux/[email protected]/

---
 drivers/gpu/nova-core/falcon.rs           | 134 ++++++++-------
 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 ++++++++--------
 drivers/gpu/nova-core/regs/macros.rs      | 264 +++++++++++++++---------------
 6 files changed, 283 insertions(+), 271 deletions(-)
drivers/gpu/nova-core/falcon.rs +72 -62
index 3f505b870601..71cb09cf7d67 100644
@@ -6,6 +6,7 @@
 use hal::FalconHal;
 use kernel::device;
 use kernel::dma::DmaAddress;
+use kernel::num::{Boundable, BoundedInt};
 use kernel::prelude::*;
 use kernel::sync::aref::ARef;
 use kernel::time::Delta;
@@ -22,11 +23,14 @@
 pub(crate) mod sec2;
 
 // TODO[FPRI]: Replace with `ToPrimitive`.
-macro_rules! impl_from_enum_to_u8 {
-    ($enum_type:ty) => {
-        impl From<$enum_type> for u8 {
+macro_rules! impl_from_enum_to_bounded {
+    ($enum_type:ty, $length:literal) => {
+        impl<T> From<$enum_type> for BoundedInt<T, $length>
+        where
+            T: From<u8> + Boundable<$length>,
+        {
             fn from(value: $enum_type) -> Self {
-                value as u8
+                BoundedInt::new(T::from(value as u8))
             }
         }
     };
@@ -46,16 +50,19 @@ pub(crate) enum FalconCoreRev {
     Rev6 = 6,
     Rev7 = 7,
 }
-impl_from_enum_to_u8!(FalconCoreRev);
+impl_from_enum_to_bounded!(FalconCoreRev, 4);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
-impl TryFrom<u8> for FalconCoreRev {
+impl<T> TryFrom<BoundedInt<T, 4>> for FalconCoreRev
+where
+    T: Boundable<4>,
+{
     type Error = Error;
 
-    fn try_from(value: u8) -> Result<Self> {
+    fn try_from(value: BoundedInt<T, 4>) -> Result<Self> {
         use FalconCoreRev::*;
 
-        let rev = match value {
+        let rev = match u8::from(value) {
             1 => Rev1,
             2 => Rev2,
             3 => Rev3,
@@ -81,24 +88,25 @@ pub(crate) enum FalconCoreRevSubversion {
     Subversion2 = 2,
     Subversion3 = 3,
 }
-impl_from_enum_to_u8!(FalconCoreRevSubversion);
+impl_from_enum_to_bounded!(FalconCoreRevSubversion, 2);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
-impl TryFrom<u8> for FalconCoreRevSubversion {
-    type Error = Error;
-
-    fn try_from(value: u8) -> Result<Self> {
+impl<T> From<BoundedInt<T, 2>> for FalconCoreRevSubversion
+where
+    T: Boundable<2>,
+{
+    fn from(value: BoundedInt<T, 2>) -> Self {
         use FalconCoreRevSubversion::*;
 
-        let sub_version = match value & 0b11 {
+        match u8::from(value) {
             0 => Subversion0,
             1 => Subversion1,
             2 => Subversion2,
             3 => Subversion3,
-            _ => return Err(EINVAL),
-        };
-
-        Ok(sub_version)
+            // TODO: somehow the compiler cannot infer that `value` cannot be > 3. Find a way to
+            // handle this gracefully, or switch back to fallible ops.
+            _ => panic!(),
+        }
     }
 }
 
@@ -125,16 +133,19 @@ pub(crate) enum FalconSecurityModel {
     /// Also known as High-Secure, Privilege Level 3 or PL3.
     Heavy = 3,
 }
-impl_from_enum_to_u8!(FalconSecurityModel);
+impl_from_enum_to_bounded!(FalconSecurityModel, 2);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
-impl TryFrom<u8> for FalconSecurityModel {
+impl<T> TryFrom<BoundedInt<T, 2>> for FalconSecurityModel
+where
+    T: Boundable<2>,
+{
     type Error = Error;
 
-    fn try_from(value: u8) -> Result<Self> {
+    fn try_from(value: BoundedInt<T, 2>) -> Result<Self> {
         use FalconSecurityModel::*;
 
-        let sec_model = match value {
+        let sec_model = match u8::from(value) {
             0 => None,
             2 => Light,
             3 => Heavy,
@@ -157,14 +168,17 @@ pub(crate) enum FalconModSelAlgo {
     #[default]
     Rsa3k = 1,
 }
-impl_from_enum_to_u8!(FalconModSelAlgo);
+impl_from_enum_to_bounded!(FalconModSelAlgo, 8);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
-impl TryFrom<u8> for FalconModSelAlgo {
+impl<T> TryFrom<BoundedInt<T, 8>> for FalconModSelAlgo
+where
+    T: Boundable<8>,
+{
     type Error = Error;
 
-    fn try_from(value: u8) -> Result<Self> {
-        match value {
+    fn try_from(value: BoundedInt<T, 8>) -> Result<Self> {
+        match u8::from(value) {
             1 => Ok(FalconModSelAlgo::Rsa3k),
             _ => Err(EINVAL),
         }
@@ -179,14 +193,17 @@ pub(crate) enum DmaTrfCmdSize {
     #[default]
     Size256B = 0x6,
 }
-impl_from_enum_to_u8!(DmaTrfCmdSize);
+impl_from_enum_to_bounded!(DmaTrfCmdSize, 3);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
-impl TryFrom<u8> for DmaTrfCmdSize {
+impl<T> TryFrom<BoundedInt<T, 3>> for DmaTrfCmdSize
+where
+    T: Boundable<3>,
+{
     type Error = Error;
 
-    fn try_from(value: u8) -> Result<Self> {
-        match value {
+    fn try_from(value: BoundedInt<T, 3>) -> Result<Self> {
+        match u8::from(value) {
             0x6 => Ok(Self::Size256B),
             _ => Err(EINVAL),
         }
@@ -202,25 +219,20 @@ pub(crate) enum PeregrineCoreSelect {
     /// RISC-V core is active.
     Riscv = 1,
 }
+impl_from_enum_to_bounded!(PeregrineCoreSelect, 1);
 
-impl From<bool> for PeregrineCoreSelect {
-    fn from(value: bool) -> Self {
-        match value {
+impl<T> From<BoundedInt<T, 1>> for PeregrineCoreSelect
+where
+    T: Boundable<1> + Zeroable,
+{
+    fn from(value: BoundedInt<T, 1>) -> Self {
+        match bool::from(value) {
             false => PeregrineCoreSelect::Falcon,
             true => PeregrineCoreSelect::Riscv,
         }
     }
 }
 
-impl From<PeregrineCoreSelect> for bool {
-    fn from(value: PeregrineCoreSelect) -> Self {
-        match value {
-            PeregrineCoreSelect::Falcon => false,
-            PeregrineCoreSelect::Riscv => true,
-        }
-    }
-}
-
 /// Different types of memory present in a falcon core.
 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum FalconMem {
@@ -244,14 +256,17 @@ pub(crate) enum FalconFbifTarget {
     /// Non-coherent system memory (System DRAM).
     NoncoherentSysmem = 2,
 }
-impl_from_enum_to_u8!(FalconFbifTarget);
+impl_from_enum_to_bounded!(FalconFbifTarget, 2);
 
 // TODO[FPRI]: replace with `FromPrimitive`.
-impl TryFrom<u8> for FalconFbifTarget {
+impl<T> TryFrom<BoundedInt<T, 2>> for FalconFbifTarget
+where
+    T: Boundable<2>,
+{
     type Error = Error;
 
-    fn try_from(value: u8) -> Result<Self> {
-        let res = match value {
+    fn try_from(value: BoundedInt<T, 2>) -> Result<Self> {
+        let res = match u8::from(value) {
             0 => Self::LocalFb,
             1 => Self::CoherentSysmem,
             2 => Self::NoncoherentSysmem,
@@ -271,26 +286,21 @@ pub(crate) enum FalconFbifMemType {
     /// Physical memory addresses.
     Physical = 1,
 }
+impl_from_enum_to_bounded!(FalconFbifMemType, 1);
 
 /// Conversion from a single-bit register field.
-impl From<bool> for FalconFbifMemType {
-    fn from(value: bool) -> Self {
-        match value {
+impl<T> From<BoundedInt<T, 1>> for FalconFbifMemType
+where
+    T: Boundable<1> + Zeroable,
+{
+    fn from(value: BoundedInt<T, 1>) -> Self {
+        match bool::from(value) {
             false => Self::Virtual,
             true => Self::Physical,
         }
     }
 }
 
-impl From<FalconFbifMemType> for bool {
-    fn from(value: FalconFbifMemType) -> Self {
-        match value {
-            FalconFbifMemType::Virtual => false,
-            FalconFbifMemType::Physical => true,
-        }
-    }
-}
-
 /// Type used to represent the `PFALCON` registers address base for a given falcon engine.
 pub(crate) struct PFalconBase(());
 
@@ -440,7 +450,7 @@ pub(crate) fn reset(&self, bar: &Bar0) -> Result {
         self.reset_wait_mem_scrubbing(bar)?;
 
         regs::NV_PFALCON_FALCON_RM::default()
-            .set_value(regs::NV_PMC_BOOT_0::read(bar).into())
+            .set_value(u32::from(regs::NV_PMC_BOOT_0::read(bar)))
             .write(bar, &E::ID);
 
         Ok(())
@@ -507,18 +517,18 @@ fn dma_wr<F: FalconFirmware<Target = E>>(
             .set_base((dma_start >> 8) as u32)
             .write(bar, &E::ID);
         regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
-            .set_base((dma_start >> 40) as u16)
+            .try_set_base(dma_start >> 40)?
             .write(bar, &E::ID);
 
         let cmd = regs::NV_PFALCON_FALCON_DMATRFCMD::default()
             .set_size(DmaTrfCmdSize::Size256B)
             .set_imem(target_mem == FalconMem::Imem)
-            .set_sec(if sec { 1 } else { 0 });
+            .set_sec(BoundedInt::new(if sec { 1 } else { 0 }));
 
         for pos in (0..num_transfers).map(|i| i * DMA_LEN) {
             // Perform a transfer of size `DMA_LEN`.
             regs::NV_PFALCON_FALCON_DMATRFMOFFS::default()
-                .set_offs(load_offsets.dst_start + pos)
+                .try_set_offs(load_offsets.dst_start + pos)?
                 .write(bar, &E::ID);
             regs::NV_PFALCON_FALCON_DMATRFFBOFFS::default()
                 .set_offs(src_start + pos)
drivers/gpu/nova-core/falcon/hal/ga102.rs +3 -2
index 0b1cbe7853b3..08c8b4123ce8 100644
@@ -55,7 +55,7 @@ fn signature_reg_fuse_version_ga102(
 
     // `ucode_idx` is guaranteed to be in the range [0..15], making the `read` calls provable valid
     // at build-time.
-    let reg_fuse_version = if engine_id_mask & 0x0001 != 0 {
+    let reg_fuse_version: u16 = if engine_id_mask & 0x0001 != 0 {
         regs::NV_FUSE_OPT_FPF_SEC2_UCODE1_VERSION::read(bar, ucode_idx).data()
     } else if engine_id_mask & 0x0004 != 0 {
         regs::NV_FUSE_OPT_FPF_NVDEC_UCODE1_VERSION::read(bar, ucode_idx).data()
@@ -64,7 +64,8 @@ fn signature_reg_fuse_version_ga102(
     } else {
         dev_err!(dev, "unexpected engine_id_mask {:#x}", engine_id_mask);
         return Err(EINVAL);
-    };
+    }
+    .into();
 
     // TODO[NUMM]: replace with `last_set_bit` once it lands.
     Ok(u16::BITS - reg_fuse_version.leading_zeros())
drivers/gpu/nova-core/fb/hal/ga100.rs +2 -1
index 871c42bf033a..5449902f2489 100644
@@ -2,6 +2,7 @@
 
 struct Ga100;
 
+use kernel::num::BoundedInt;
 use kernel::prelude::*;
 
 use crate::driver::Bar0;
@@ -18,7 +19,7 @@ pub(super) fn read_sysmem_flush_page_ga100(bar: &Bar0) -> u64 {
 
 pub(super) fn write_sysmem_flush_page_ga100(bar: &Bar0, addr: u64) {
     regs::NV_PFB_NISO_FLUSH_SYSMEM_ADDR_HI::default()
-        .set_adr_63_40((addr >> FLUSH_SYSMEM_ADDR_SHIFT_HI) as u32)
+        .set_adr_63_40(BoundedInt::new(addr >> FLUSH_SYSMEM_ADDR_SHIFT_HI).cast())
         .write(bar);
     regs::NV_PFB_NISO_FLUSH_SYSMEM_ADDR::default()
         .set_adr_39_08((addr >> FLUSH_SYSMEM_ADDR_SHIFT) as u32)
drivers/gpu/nova-core/gpu.rs +5 -4
index 5da9ad726483..7ed382d82fc7 100644
@@ -1,5 +1,6 @@
 // SPDX-License-Identifier: GPL-2.0
 
+use kernel::num::BoundedInt;
 use kernel::{device, devres::Devres, error::code::*, pci, prelude::*, sync::Arc};
 
 use crate::driver::Bar0;
@@ -131,15 +132,15 @@ fn try_from(value: u8) -> Result<Self> {
 }
 
 pub(crate) struct Revision {
-    major: u8,
-    minor: u8,
+    major: BoundedInt<u8, 4>,
+    minor: BoundedInt<u8, 4>,
 }
 
 impl Revision {
     fn from_boot0(boot0: regs::NV_PMC_BOOT_0) -> Self {
         Self {
-            major: boot0.major_revision(),
-            minor: boot0.minor_revision(),
+            major: boot0.major_revision().cast(),
+            minor: boot0.minor_revision().cast(),
         }
     }
 }
drivers/gpu/nova-core/regs.rs +70 -69

315 lines not on this page · raw message

drivers/gpu/nova-core/regs/macros.rs +131 -133

317 lines not on this page · raw message

Signature · 1 line
2.51.0
reviewer
#15 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

Hi Alexandre,

Quoted 5 lines · Alexandre Courbot

Use BoundedInt with the register!() macro and adapt the nova-core code accordingly. This makes it impossible to trim values when setting a register field, because either the value of the field has been inferred at compile-time to fit within the bounds of the field, or the user has been forced to check at runtime that it does indeed fit.

In C23 we've got _BitInt(), which works like:

unsigned _BitInt(2) a = 5; // compile-time error

Can you consider a similar name and syntax in rust?

Quoted 14 lines

The use of BoundedInt actually simplifies register fields definitions, as they don't need an intermediate storage type (the "as ..." part of fields definitions). Instead, the internal storage type for each field is now the bounded integer of its width in bits, which can optionally be converted to another type that implements `From`` or `TryFrom`` for that bounded integer type.

This means that something like

register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
3:3 status_valid as bool,
31:8 addr as u32,
});

Quoted 6 lines

Now becomes

  register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
      3:3     status_valid => bool,
      31:8    addr,
  });

That looks nicer, really. But now that you don't make user to provide a representation type, how would one distinguish signed and unsigned fields? Assuming that BoundedInt is intended to become a generic type, people may want to use it as a storage for counters and other non-bitfield type of things. Maybe:

   register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
       s 3:0     cnt,
         7:4     flags, // implies unsigned - ?
       u 31:8    addr,
   });
Quoted 11 lines

(here status_valid is infallibly converted to a bool for convenience and to remain compatible with the previous semantics)

The field setter/getters are also simplified. If a field has no target type, then its setter expects any type that implements Into to the field's bounded integer type. Due to the many From implementations for primitive types, this means that most calls can be left unchanged. If the caller passes a value that is potentially larger than the field's capacity, it must use the try_ variant of the setter, which returns an error if the value cannot be converted at runtime.

Quoted 6 lines

For fields that use => to convert to another type, both setter and getter are always infallible.

For fields that use ?=> to fallibly convert to another type, only the getter needs to be fallible as the setter always provide valid values by design.

Can you share a couple examples? Not sure I understand this part, especially how setters may not be fallible, and getters may fail.

Quoted 19 lines

Outside of the register macro, the biggest changes occur in falcon.rs, which defines many enums for fields - their conversion implementations need to be changed from the original primitive type of the field to the new corresponding bounded int type. Hopefully the TryFrom/Into derive macros [1] can take care of implementing these, but it will need to be adapted to support bounded integers... :/

But overall, I am rather happy at how simple it was to convert the whole of nova-core to this.

Note: This RFC uses nova-core's register!() macro for practical purposes, but the hope is to move this patch on top of the bitfield macro after it is split out [2].

[1] https://lore.kernel.org/rust-for-linux/[email protected]/
[2] https://lore.kernel.org/rust-for-linux/[email protected]/

---

...

drivers/gpu/nova-core/falcon.rs fn dma_wr<F: FalconFirmware<Target = E>>( · line 521

Quoted 4 lines

regs::NV_PFALCON_FALCON_DMATRFBASE1::default()

drivers/gpu/nova-core/falcon.rs +1 -1
-            .set_base((dma_start >> 40) as u16)
+            .try_set_base(dma_start >> 40)?
             .write(bar, &E::ID);

Does it mean that something like the following syntax is possible?

        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set_base1(base1 >> 40)?        // fail here
            .try_set_base2(base2 >> 40)?        // skip
            .write(bar, &E::ID) else { pr_err!(); return -EINVAL };

This is my main concern: Rust is advertised a as runtime-safe language (at lease safer than C), but current design isn't safe against one of the most common errors: type overflow.

If your syntax above allows to handle errors in .try_set() path this way or another, I think the rest is manageable.

As a side note: it's a huge pain in C to grep for functions that defined by using a macro. Here you do a similar thing. One can't easily grep the 'try_set_base' implementation, and would have to make a not so pleasant detour to the low-level internals. Maybe switch it to:

        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set(base, dma_start >> 40)?
            .write(bar, &E::ID);

Thanks,
Yury

maintainer
#16 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

Quoted 7 lines · Yury Norov
Quoted 5 lines · Alexandre Courbot

Use BoundedInt with the register!() macro and adapt the nova-core code accordingly. This makes it impossible to trim values when setting a register field, because either the value of the field has been inferred at compile-time to fit within the bounds of the field, or the user has been forced to check at runtime that it does indeed fit.

Quoted 5 lines

In C23 we've got _BitInt(), which works like:

unsigned _BitInt(2) a = 5; // compile-time error

Can you consider a similar name and syntax in rust?

Rust is a different language and has its own syntax, I think we should not try to use C syntax instead.

Quoted 9 lines

drivers/gpu/nova-core/falcon.rs fn dma_wr<F: FalconFirmware<Target = E>>( · line 521

Quoted 4 lines

regs::NV_PFALCON_FALCON_DMATRFBASE1::default()

drivers/gpu/nova-core/falcon.rs +1 -1
-            .set_base((dma_start >> 40) as u16)
+            .try_set_base(dma_start >> 40)?
             .write(bar, &E::ID);

Does it mean that something like the following syntax is possible?

        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set_base1(base1 >> 40)?        // fail here

Note that try_set_base1() returns a Result [1], which is handled immediately by the question mark operator [2]. I.e. if try_set_base1() returns an error it is propagated to the caller right away without executing any of the code below.

Quoted 6 lines
            .try_set_base2(base2 >> 40)?        // skip
            .write(bar, &E::ID) else { pr_err!(); return -EINVAL };

This is my main concern: Rust is advertised a as runtime-safe language (at lease safer than C), but current design isn't safe against one of the most common errors: type overflow.

Where do you see a potential runtime overflows in the register!() code?

[1] https://rust.docs.kernel.org/kernel/error/type.Result.html
[2] https://doc.rust-lang.org/reference/expressions/operator-expr.html?highlight=question%20mark#the-question-mark-operator

reviewer
#17 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

Quoted 8 lines · Danilo Krummrich
Quoted 7 lines · Yury Norov
Quoted 5 lines · Alexandre Courbot

Use BoundedInt with the register!() macro and adapt the nova-core code accordingly. This makes it impossible to trim values when setting a register field, because either the value of the field has been inferred at compile-time to fit within the bounds of the field, or the user has been forced to check at runtime that it does indeed fit.

Quoted 8 lines
Quoted 5 lines

In C23 we've got _BitInt(), which works like:

unsigned _BitInt(2) a = 5; // compile-time error

Can you consider a similar name and syntax in rust?

Rust is a different language and has its own syntax, I think we should not try to use C syntax instead.

Up to you guys. But having in mind that C is the only language that really works for system engineering, I would rather consider to stay in line with it on semantic level.

If your goal is to make rust adopted by system engineers, you may want to make your language somewhat familiar to what people already know.

Quoted 5 lines
Quoted 5 lines
Quoted 4 lines

regs::NV_PFALCON_FALCON_DMATRFBASE1::default()

drivers/gpu/nova-core/falcon.rs +1 -1
-            .set_base((dma_start >> 40) as u16)
+            .try_set_base(dma_start >> 40)?
             .write(bar, &E::ID);
Quoted 8 lines
Quoted 4 lines

Does it mean that something like the following syntax is possible?

        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set_base1(base1 >> 40)?        // fail here

Note that try_set_base1() returns a Result [1], which is handled immediately by the question mark operator [2]. I.e. if try_set_base1() returns an error it is propagated to the caller right away without executing any of the code below.

Thanks for the links. I am definitely the very beginning on the learning curve for this.

Quoted 8 lines
Quoted 6 lines
            .try_set_base2(base2 >> 40)?        // skip
            .write(bar, &E::ID) else { pr_err!(); return -EINVAL };

This is my main concern: Rust is advertised a as runtime-safe language (at lease safer than C), but current design isn't safe against one of the most common errors: type overflow.

Where do you see a potential runtime overflows in the register!() code?

Assuming base is 10-bit,

        let ret = some_c_wrapper()      // 0..1024 or -EINVAL
        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
             .try_set_base1(ret)

Or maybe I misunderstood the question, because if there's no possibility to overflow a field, what for the .try_set_xxx() is needed at all?

Quoted 2 lines

[1] https://rust.docs.kernel.org/kernel/error/type.Result.html
[2] https://doc.rust-lang.org/reference/expressions/operator-expr.html?highlight=question%20mark#the-question-mark-operator

#18 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

On 10/9/2025 2:28 PM, Yury Norov wrote:
[..]

Quoted 26 lines
Quoted 5 lines
Quoted 5 lines
Quoted 4 lines

regs::NV_PFALCON_FALCON_DMATRFBASE1::default()

drivers/gpu/nova-core/falcon.rs +1 -1
-            .set_base((dma_start >> 40) as u16)
+            .try_set_base(dma_start >> 40)?
             .write(bar, &E::ID);
Quoted 8 lines
Quoted 4 lines

Does it mean that something like the following syntax is possible?

        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set_base1(base1 >> 40)?        // fail here

Note that try_set_base1() returns a Result [1], which is handled immediately by the question mark operator [2]. I.e. if try_set_base1() returns an error it is propagated to the caller right away without executing any of the code below.

Thanks for the links. I am definitely the very beginning on the learning curve for this.

Quoted 8 lines
Quoted 6 lines
            .try_set_base2(base2 >> 40)?        // skip
            .write(bar, &E::ID) else { pr_err!(); return -EINVAL };

This is my main concern: Rust is advertised a as runtime-safe language (at lease safer than C), but current design isn't safe against one of the most common errors: type overflow.

Where do you see a potential runtime overflows in the register!() code?

Quoted 8 lines

Assuming base is 10-bit,

        let ret = some_c_wrapper()      // 0..1024 or -EINVAL
        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
             .try_set_base1(ret)

Or maybe I misunderstood the question, because if there's no possibility to overflow a field, what for the .try_set_xxx() is needed at all?

Because 'ret' is a value determined at runtime in this example, there is no way for the compiler to know that ret will fit into the bounded int, at compile time. So the "try_" means it is runtime checked and validated (via return of Result). Sure it may well not fail, but the compiler doesn't know that.

Thanks.

#19 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

In reply to Yury Norov
Quoted 8 lines · Yury Norov

Up to you guys. But having in mind that C is the only language that really works for system engineering, I would rather consider to stay in line with it on semantic level.

If your goal is to make rust adopted by system engineers, you may want to make your language somewhat familiar to what people already know.

I am not sure what you mean here, but just to clarify: our goal is to improve Linux with Rust, not to increase its adoption (even if obviously many of us would like that). And just in case, it is not "our" language either -- most of us do not come from upstream Rust.

In general, we do try to make things as familiar as possible, but sometimes it doesn't make much sense, so we don't follow C blindly.

For instance, C23 also got checked integer arithmetic macros, but that doesn't mean we should start using names like ckd_add, returning booleans and, worse, using macros for those. C23 also got nullptr_t -- similar story.

Cheers,
Miguel

maintainer
#20 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

In reply to Yury Norov
Quoted 13 lines · Yury Norov
Quoted 12 lines · Danilo Krummrich
Quoted 11 lines · Yury Norov
Quoted 5 lines · Alexandre Courbot

Use BoundedInt with the register!() macro and adapt the nova-core code accordingly. This makes it impossible to trim values when setting a register field, because either the value of the field has been inferred at compile-time to fit within the bounds of the field, or the user has been forced to check at runtime that it does indeed fit.

In C23 we've got _BitInt(), which works like:

unsigned _BitInt(2) a = 5; // compile-time error

Quoted 8 lines
Quoted 4 lines
Quoted 1 line

Can you consider a similar name and syntax in rust?

Rust is a different language and has its own syntax, I think we should not try to use C syntax instead.

Up to you guys. But having in mind that C is the only language that really works for system engineering, I would rather consider to stay in line with it on semantic level.

I think you asked about syntax above; semantically it is (and should be) exactly the same.

Quoted 3 lines

If your goal is to make rust adopted by system engineers, you may want to make your language somewhat familiar to what people already know.

The goal is to add support for Rust in the Linux kernel; to adapt its advanced type system features offering compile time checked lifetime and ownership semantics leading to better memory safety and more compile time validation overall.

In general I think we should stay as close to existing patterns as possible, i.e. consistency does matter.

However, sometimes it is necessary to break with existing patterns and design things slightly different to take full advantage of the capabilities we get from the language (BoundedInt / BitInt is not one of those).

In other words, introducing a new language with capabilities that solve real problems is pointless if we subsequently limit ourselfs to "what people already know" for people who haven't been in touch with the language before.

#21 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

In reply to Yury Norov

On 10/9/2025 12:40 PM, Yury Norov wrote:
[..]

Quoted 11 lines
Quoted 11 lines

The field setter/getters are also simplified. If a field has no target type, then its setter expects any type that implements Into to the field's bounded integer type. Due to the many From implementations for primitive types, this means that most calls can be left unchanged. If the caller passes a value that is potentially larger than the field's capacity, it must use the try_ variant of the setter, which returns an error if the value cannot be converted at runtime.

For fields that use => to convert to another type, both setter and getter are always infallible.

Quoted 6 lines
Quoted 3 lines

For fields that use ?=> to fallibly convert to another type, only the getter needs to be fallible as the setter always provide valid values by design.

Can you share a couple examples? Not sure I understand this part, especially how setters may not be fallible, and getters may fail.

Because a getter has to convert the raw bitfield value from memory into an enum, there is no guarantee that the memory in concern does not overflow the enum, say if register bit meanings change, or something. ?=> was before fallible in both directions hence the "?". Now with Alex's patch it is fallible only in one direction.

Quoted 27 lines
Quoted 19 lines

Outside of the register macro, the biggest changes occur in falcon.rs, which defines many enums for fields - their conversion implementations need to be changed from the original primitive type of the field to the new corresponding bounded int type. Hopefully the TryFrom/Into derive macros [1] can take care of implementing these, but it will need to be adapted to support bounded integers... :/

But overall, I am rather happy at how simple it was to convert the whole of nova-core to this.

Note: This RFC uses nova-core's register!() macro for practical purposes, but the hope is to move this patch on top of the bitfield macro after it is split out [2].

[1] https://lore.kernel.org/rust-for-linux/[email protected]/
[2] https://lore.kernel.org/rust-for-linux/[email protected]/

---

...

drivers/gpu/nova-core/falcon.rs fn dma_wr<F: FalconFirmware<Target = E>>( · line 521

Quoted 4 lines

regs::NV_PFALCON_FALCON_DMATRFBASE1::default()

drivers/gpu/nova-core/falcon.rs +1 -1
-            .set_base((dma_start >> 40) as u16)
+            .try_set_base(dma_start >> 40)?
             .write(bar, &E::ID);
Quoted 4 lines

Does it mean that something like the following syntax is possible?

        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set_base1(base1 >> 40)?        // fail here

Danilo already replied here, but this code is fine as we early return due to the try operator (?).

Quoted 2 lines
            .try_set_base2(base2 >> 40)?        // skip
            .write(bar, &E::ID) else { pr_err!(); return -EINVAL };

Here I am guessing (based on your concern from an earlier thread) but is your concern was that -EINVAL will get written to the register accidentally? That wont happen, the above code is fine. Or do you mean something else?

Quoted 4 lines

This is my main concern: Rust is advertised a as runtime-safe language (at lease safer than C), but current design isn't safe against one of the most common errors: type overflow.

I'd be a bit careful when using "isn't safe" in the context of Rust. Rust's notion of "safety" is about preventing undefined behavior (UB), not preventing every possible runtime mistake. In rust, integer overflows for example are not undefined so overflows are not "unsafe" (it might be a logical bug but that's not what unsafety is about). In fact an overflow might be exactly what some algorithm needs (wrap counters in RCU are example of harmless overflow). Another example is a deadlock is not undefined behavior in Rust, it is defined, even if bad :).

Thanks.

author maintainer
#22 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

In reply to Yury Norov
Quoted 9 lines · Yury Norov

Hi Alexandre,

Quoted 5 lines · Alexandre Courbot

Use BoundedInt with the register!() macro and adapt the nova-core code accordingly. This makes it impossible to trim values when setting a register field, because either the value of the field has been inferred at compile-time to fit within the bounds of the field, or the user has been forced to check at runtime that it does indeed fit.

Quoted 5 lines

In C23 we've got _BitInt(), which works like:

unsigned _BitInt(2) a = 5; // compile-time error

Can you consider a similar name and syntax in rust?

I like the shorter BitInt! For the syntax, we will have to conform to what is idiomatic Rust. And I don't think we can make something similar to = 5 work here - that would require overloading the = operator, which cannot be done AFAICT. A constructor is a requirement.

Quoted 28 lines
Quoted 15 lines

The use of BoundedInt actually simplifies register fields definitions, as they don't need an intermediate storage type (the "as ..." part of fields definitions). Instead, the internal storage type for each field is now the bounded integer of its width in bits, which can optionally be converted to another type that implements `From`` or `TryFrom`` for that bounded integer type.

This means that something like

register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
3:3 status_valid as bool,
31:8 addr as u32,
});

Quoted 6 lines

Now becomes

  register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
      3:3     status_valid => bool,
      31:8    addr,
  });

That looks nicer, really. But now that you don't make user to provide a representation type, how would one distinguish signed and unsigned fields? Assuming that BoundedInt is intended to become a generic type, people may want to use it as a storage for counters and other non-bitfield type of things. Maybe:

Quoted 5 lines
   register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
       s 3:0     cnt,
         7:4     flags, // implies unsigned - ?
       u 31:8    addr,
   });

The expectation would be to use the => syntax to convert the field to a signed type (similarly to how status_valid is turned into a bool in my example).

Quoted 15 lines
Quoted 15 lines

(here status_valid is infallibly converted to a bool for convenience and to remain compatible with the previous semantics)

The field setter/getters are also simplified. If a field has no target type, then its setter expects any type that implements Into to the field's bounded integer type. Due to the many From implementations for primitive types, this means that most calls can be left unchanged. If the caller passes a value that is potentially larger than the field's capacity, it must use the try_ variant of the setter, which returns an error if the value cannot be converted at runtime.

For fields that use => to convert to another type, both setter and getter are always infallible.

Quoted 6 lines
Quoted 3 lines

For fields that use ?=> to fallibly convert to another type, only the getter needs to be fallible as the setter always provide valid values by design.

Can you share a couple examples? Not sure I understand this part, especially how setters may not be fallible, and getters may fail.

Imagine you have this enum:

  enum GpioState {
    Low = 0,
    High = 1,
    Floating = 2,
  }

and this field:

2:0 gpio_state ?=> GpioState,

When you set it, you must pass an instance of GpioState as argument, which means that the value will always be valid. However, when you try to access the field, you have no guarantee at all that the value of the field won't be 3 - the IO space might be inaccessible, or the register value be forged arbitrarily. Thus the getter needs to return a Result<GpioState>.

Quoted 30 lines
Quoted 20 lines

Outside of the register macro, the biggest changes occur in falcon.rs, which defines many enums for fields - their conversion implementations need to be changed from the original primitive type of the field to the new corresponding bounded int type. Hopefully the TryFrom/Into derive macros [1] can take care of implementing these, but it will need to be adapted to support bounded integers... :/

But overall, I am rather happy at how simple it was to convert the whole of nova-core to this.

Note: This RFC uses nova-core's register!() macro for practical purposes, but the hope is to move this patch on top of the bitfield macro after it is split out [2].

[1] https://lore.kernel.org/rust-for-linux/[email protected]/
[2] https://lore.kernel.org/rust-for-linux/[email protected]/

---

...

drivers/gpu/nova-core/falcon.rs fn dma_wr<F: FalconFirmware<Target = E>>( · line 521

Quoted 4 lines

regs::NV_PFALCON_FALCON_DMATRFBASE1::default()

drivers/gpu/nova-core/falcon.rs +1 -1
-            .set_base((dma_start >> 40) as u16)
+            .try_set_base(dma_start >> 40)?
             .write(bar, &E::ID);

Does it mean that something like the following syntax is possible?

Quoted 8 lines
        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set_base1(base1 >> 40)?        // fail here
            .try_set_base2(base2 >> 40)?        // skip
            .write(bar, &E::ID) else { pr_err!(); return -EINVAL };

This is my main concern: Rust is advertised a as runtime-safe language (at lease safer than C), but current design isn't safe against one of the most common errors: type overflow.

Not sure I understand what you mean, but if you are talking about fields overflow, this cannot happen with the current design. The non-fallible setter can only be invoked if the compiler can prove that the argument does fit withing the field. Otherwise, one has to use the fallible setter (as this chunk does, because dma_start >> 40 can still spill over the capacity of base), which performs a runtime check and returns EOVERFLOW if the value didn't fit.

Quoted 10 lines

If your syntax above allows to handle errors in .try_set() path this way or another, I think the rest is manageable.

As a side note: it's a huge pain in C to grep for functions that defined by using a macro. Here you do a similar thing. One can't easily grep the 'try_set_base' implementation, and would have to make a not so pleasant detour to the low-level internals. Maybe switch it to:

Quoted 3 lines
        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set(base, dma_start >> 40)?
            .write(bar, &E::ID);

base here is passed by value, what type would it be? I don't think it is easily doable without jumping through many hoops.

Using LSP with Rust actually makes it very easy to jump to either the definition of the register, or of the try_set block in the macro - I've done this many times. LSP is pretty much a requirement to code efficiently in Rust, so I think it is reasonable to rely on it here.

reviewer
#23 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

Quoted 12 lines · Alexandre Courbot
Quoted 11 lines · Yury Norov

Hi Alexandre,

Quoted 5 lines · Alexandre Courbot

Use BoundedInt with the register!() macro and adapt the nova-core code accordingly. This makes it impossible to trim values when setting a register field, because either the value of the field has been inferred at compile-time to fit within the bounds of the field, or the user has been forced to check at runtime that it does indeed fit.

In C23 we've got _BitInt(), which works like:

Quoted 8 lines
Quoted 3 lines

unsigned _BitInt(2) a = 5; // compile-time error

Can you consider a similar name and syntax in rust?

I like the shorter BitInt! For the syntax, we will have to conform to what is idiomatic Rust. And I don't think we can make something similar to = 5 work here - that would require overloading the = operator, which cannot be done AFAICT. A constructor is a requirement.

Sure, BitInt + constructor is nice.

Quoted 33 lines
Quoted 27 lines
Quoted 14 lines

The use of BoundedInt actually simplifies register fields definitions, as they don't need an intermediate storage type (the "as ..." part of fields definitions). Instead, the internal storage type for each field is now the bounded integer of its width in bits, which can optionally be converted to another type that implements `From`` or `TryFrom`` for that bounded integer type.

This means that something like

register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
3:3 status_valid as bool,
31:8 addr as u32,
});

Quoted 6 lines

Now becomes

  register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
      3:3     status_valid => bool,
      31:8    addr,
  });

That looks nicer, really. But now that you don't make user to provide a representation type, how would one distinguish signed and unsigned fields? Assuming that BoundedInt is intended to become a generic type, people may want to use it as a storage for counters and other non-bitfield type of things. Maybe:

Quoted 5 lines
   register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
       s 3:0     cnt,
         7:4     flags, // implies unsigned - ?
       u 31:8    addr,
   });
Quoted 3 lines

The expectation would be to use the => syntax to convert the field to a signed type (similarly to how status_valid is turned into a bool in my example).

So, you suggest like this?

    register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
        3:0     cnt => i8,
        7:4     flags, // implied unsigned
        31:8    addr,  // implied unsigned
    });

That answers my question. Can you please highlight this use case in commit message?

And just to wrap up:

- all fields by default are unsigned integers;
- one may use '=>' to switch to signed integers, enums or booleans;
- all other types are not allowed.

Is that correct?

Quoted 31 lines
Quoted 14 lines
Quoted 14 lines

(here status_valid is infallibly converted to a bool for convenience and to remain compatible with the previous semantics)

The field setter/getters are also simplified. If a field has no target type, then its setter expects any type that implements Into to the field's bounded integer type. Due to the many From implementations for primitive types, this means that most calls can be left unchanged. If the caller passes a value that is potentially larger than the field's capacity, it must use the try_ variant of the setter, which returns an error if the value cannot be converted at runtime.

For fields that use => to convert to another type, both setter and getter are always infallible.

Quoted 6 lines
Quoted 3 lines

For fields that use ?=> to fallibly convert to another type, only the getter needs to be fallible as the setter always provide valid values by design.

Can you share a couple examples? Not sure I understand this part, especially how setters may not be fallible, and getters may fail.

Imagine you have this enum:

  enum GpioState {
    Low = 0,
    High = 1,
    Floating = 2,
  }

and this field:

Quoted 8 lines

2:0 gpio_state ?=> GpioState,

When you set it, you must pass an instance of GpioState as argument, which means that the value will always be valid. However, when you try to access the field, you have no guarantee at all that the value of the field won't be 3 - the IO space might be inaccessible, or the register value be forged arbitrarily. Thus the getter needs to return a Result<GpioState>.

Ack, thanks.

Quoted 38 lines
Quoted 29 lines
Quoted 19 lines

Outside of the register macro, the biggest changes occur in falcon.rs, which defines many enums for fields - their conversion implementations need to be changed from the original primitive type of the field to the new corresponding bounded int type. Hopefully the TryFrom/Into derive macros [1] can take care of implementing these, but it will need to be adapted to support bounded integers... :/

But overall, I am rather happy at how simple it was to convert the whole of nova-core to this.

Note: This RFC uses nova-core's register!() macro for practical purposes, but the hope is to move this patch on top of the bitfield macro after it is split out [2].

[1] https://lore.kernel.org/rust-for-linux/[email protected]/
[2] https://lore.kernel.org/rust-for-linux/[email protected]/

---

...

drivers/gpu/nova-core/falcon.rs fn dma_wr<F: FalconFirmware<Target = E>>( · line 521

Quoted 4 lines

regs::NV_PFALCON_FALCON_DMATRFBASE1::default()

drivers/gpu/nova-core/falcon.rs +1 -1
-            .set_base((dma_start >> 40) as u16)
+            .try_set_base(dma_start >> 40)?
             .write(bar, &E::ID);

Does it mean that something like the following syntax is possible?

Quoted 8 lines
        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set_base1(base1 >> 40)?        // fail here
            .try_set_base2(base2 >> 40)?        // skip
            .write(bar, &E::ID) else { pr_err!(); return -EINVAL };

This is my main concern: Rust is advertised a as runtime-safe language (at lease safer than C), but current design isn't safe against one of the most common errors: type overflow.

Quoted 7 lines

Not sure I understand what you mean, but if you are talking about fields overflow, this cannot happen with the current design. The non-fallible setter can only be invoked if the compiler can prove that the argument does fit withing the field. Otherwise, one has to use the fallible setter (as this chunk does, because dma_start >> 40 can still spill over the capacity of base), which performs a runtime check and returns EOVERFLOW if the value didn't fit.

Yeah, this design addresses my major question to the bitfields series from Joel: setters must be fallible. I played with this approach, and it does exactly what I have in mind.

I still have a question regarding compile-time flavor of the setter. In C we've got a builtin_constant_p, and use it like:

   static inline int set_base(unsigned int base)
   {
        BUILD_BUG_ON_ZERO(const_true(base > MAX_BASE));
        // Eliminated for compile-time 'base'
        if (base > MAX_BASE)
                return -EOVERFLOW;

        __set_base(base);

        return 0;

}

Can we do the same trick in rust? Would be nice to have a single setter for both compile and runtime cases.

Quoted 13 lines
Quoted 9 lines

If your syntax above allows to handle errors in .try_set() path this way or another, I think the rest is manageable.

As a side note: it's a huge pain in C to grep for functions that defined by using a macro. Here you do a similar thing. One can't easily grep the 'try_set_base' implementation, and would have to make a not so pleasant detour to the low-level internals. Maybe switch it to:

Quoted 3 lines
        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set(base, dma_start >> 40)?
            .write(bar, &E::ID);
Quoted 7 lines

base here is passed by value, what type would it be? I don't think it is easily doable without jumping through many hoops.

Using LSP with Rust actually makes it very easy to jump to either the definition of the register, or of the try_set block in the macro - I've done this many times. LSP is pretty much a requirement to code efficiently in Rust, so I think it is reasonable to rely on it here.

OK, then this one is also addressed. If LSP is a requirement, maybe it's worth to mention it in Documentation?

maintainer
#24 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

Quoted 8 lines · Yury Norov
Quoted 1 line · Alexandre Courbot

On Fri Oct 10, 2025 at 1:40 AM JST, Yury Norov wrote:

    register!(NV_PDISP_VGA_WORKSPACE_BASE @ 0x00625f04 {
        3:0     cnt => i8,
        7:4     flags, // implied unsigned
        31:8    addr,  // implied unsigned
    });
Quoted 8 lines

That answers my question. Can you please highlight this use case in commit message?

And just to wrap up:

- all fields by default are unsigned integers;
- one may use '=>' to switch to signed integers, enums or booleans;
- all other types are not allowed.

We do allow other types.

In Rust we have the From [1] and TryFrom [2] traits (analogously Into and TryInto).

This way, if some type T implements, for instance, From<u8> it means that we can always derive an instance of T from any u8.

Similarly, if T implements TryFrom<u8> we can always derive a Result<T>, which either contains a valid instance of T or some error that we can handle instead.

Hence, the following is valid is well:

	register!(NV_PFALCON_FALCON_HWCFG1 @ PFalconBase[0x0000012c] {
	    3:0     core_rev ?=> FalconCoreRev, "Core revision";
	    5:4     security_model ?=> FalconSecurityModel, "Security model";
	    7:6     core_rev_subversion as ?=> FalconCoreRevSubversion, "Core revision subversion";
	});

The '?=>' notation means TryFrom, hence the generated accessor method - e.g. security_model() - returns a Result<FalconCoreRevSubversion>.

In this exaple all three types are actually enums, but it would be the exact same for structs.

In fact, enums in Rust are very different than enums in C anyways and can be complex types, such as:

	enum Message {
	    Quit,
	    Move { x: i32, y: i32 },
	    Write(String),
	    ChangeColor(i32, i32, i32),
	}

[1] https://rust.docs.kernel.org/core/convert/trait.From.html
[2] https://rust.docs.kernel.org/core/convert/trait.TryFrom.html

Quoted 14 lines

I still have a question regarding compile-time flavor of the setter. In C we've got a builtin_constant_p, and use it like:

   static inline int set_base(unsigned int base)
   {
        BUILD_BUG_ON_ZERO(const_true(base > MAX_BASE));
        // Eliminated for compile-time 'base'
        if (base > MAX_BASE)
                return -EOVERFLOW;

        __set_base(base);

        return 0;
Quoted 4 lines

}

Can we do the same trick in rust? Would be nice to have a single setter for both compile and runtime cases.

Technically, we could, but it would be very inefficient: Even if the function / method is called in an infallible way it would still return a Result<T> instead of just T, which the caller would need to handle.

Analogously, for a setter the function / method would still return a Result, which must be handled.

Ignoring a returned Result causes a compiler warning:

	warning: unused `core::result::Result` that must be used
	  --> drivers/gpu/nova-core/driver.rs:64:9
	   |
	64 |         foo();
	   |         ^^^^^
	   |
	   = note: this `Result` may be an `Err` variant, which should be handled
	   = note: `#[warn(unused_must_use)]` on by default
	help: use `let _ = ...` to ignore the resulting value
	   |
	64 |         let _ = foo();
	   |         +++++++
	
	warning: 1 warning emitted

This is intentional, users should not be able to ignore error conditions willy-nilly:

It is a potential source for bugs if errors are ignored. For instance, a caller might not check the returned Result initially because a compile time check is expected. However, when changed later on to derive the value at runtime it is easy to forget handling the Result instead.

#25 lore raw

Re: [PATCH RFC v2 3/3] gpu: nova-core: use BoundedInt

In reply to Yury Norov

Hi Yury,

On 10/10/2025 1:20 PM, Yury Norov wrote:
[...]

Quoted 42 lines
Quoted 16 lines
Quoted 7 lines

drivers/gpu/nova-core/falcon.rs fn dma_wr<F: FalconFirmware<Target = E>>( · line 521

Quoted 4 lines

regs::NV_PFALCON_FALCON_DMATRFBASE1::default()

drivers/gpu/nova-core/falcon.rs +1 -1
-            .set_base((dma_start >> 40) as u16)
+            .try_set_base(dma_start >> 40)?
             .write(bar, &E::ID);

Does it mean that something like the following syntax is possible?

Quoted 8 lines
        regs::NV_PFALCON_FALCON_DMATRFBASE1::default()
            .try_set_base1(base1 >> 40)?        // fail here
            .try_set_base2(base2 >> 40)?        // skip
            .write(bar, &E::ID) else { pr_err!(); return -EINVAL };

This is my main concern: Rust is advertised a as runtime-safe language (at lease safer than C), but current design isn't safe against one of the most common errors: type overflow.

Quoted 7 lines

Not sure I understand what you mean, but if you are talking about fields overflow, this cannot happen with the current design. The non-fallible setter can only be invoked if the compiler can prove that the argument does fit withing the field. Otherwise, one has to use the fallible setter (as this chunk does, because dma_start >> 40 can still spill over the capacity of base), which performs a runtime check and returns EOVERFLOW if the value didn't fit.

Yeah, this design addresses my major question to the bitfields series from Joel: setters must be fallible. I played with this approach, and it does exactly what I have in mind.

I still have a question regarding compile-time flavor of the setter. In C we've got a builtin_constant_p, and use it like:

   static inline int set_base(unsigned int base)
   {
        BUILD_BUG_ON_ZERO(const_true(base > MAX_BASE));
        // Eliminated for compile-time 'base'
        if (base > MAX_BASE)
                return -EOVERFLOW;

        __set_base(base);

        return 0;
Quoted 4 lines

}

Can we do the same trick in rust? Would be nice to have a single setter for both compile and runtime cases.

I don't think we could combine the setter and try setter variants on the rust side, because the former returns Self and the latter returns Result. Also, both the variants already have compile time asserts which may cover what you're referring to.

The try setter variants in fact are not strictly needed, because the user can provide a bounded integer (after performing any fallible conversions on the caller side). Alex and me discussed adding that for a better user/caller experience [1].

[1] https://lore.kernel.org/all/[email protected]/

Or did you mean something else?

thanks,

- Joel