Re: [PATCH v2] rust: num: document why Integer is sealed

["Alexandre Courbot" <acourbot@nvidia.com>]

On Tue Sep 8, 2026 at 1:39 PM JST, Younes Akhouayri via B4 Relay wrote:
> From: Younes Akhouayri <git@younes.io>
>
> Bounded relies on Integer implementations to provide primitive integer
> semantics. Unsafe blocks use those semantics to justify unchecked
> construction and conversion, but their safety comments do not say why a
> safe trait may be trusted.
>
> Document the seal at those safety comments and next to the private
> supertrait.
>
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>
> Suggested-by: Gary Guo <gary@garyguo.net>
> Link: https://lore.kernel.org/all/CANiq72m8kycbfQ1teyne-OtB5d5TsUcX_WW0FCkWB3Ayyg-qWw@mail.gmail.com/
> Link: https://lore.kernel.org/all/DL88SQWYU15W.2CVZB5NVSSJGK@garyguo.net/
> Link: https://lore.kernel.org/all/CANiq72kx-YPPEruOFdu-Dp7GX+8=Et6svG+sQtqEmmF7kpnVyQ@mail.gmail.com/
> Signed-off-by: Younes Akhouayri <git@younes.io>
> ---
> Changes in v2:
> - Shorten the comment explaining why `Integer` is sealed.
> - Mention the seal in the `SAFETY` comments that rely on it.
> - Link to v1: https://patch.msgid.link/20260906-docs-rust-num-integer-sealing-safety-v1-1-78057391302c@younes.io
>
> To: Alexandre Courbot <acourbot@nvidia.com>
> To: Yury Norov <yury.norov@gmail.com>
> To: Miguel Ojeda <ojeda@kernel.org>
> To: Boqun Feng <boqun@kernel.org>
> To: Gary Guo <gary@garyguo.net>
> To: Björn Roy Baron <bjorn3_gh@protonmail.com>
> To: Benno Lossin <lossin@kernel.org>
> To: Andreas Hindborg <a.hindborg@kernel.org>
> To: Alice Ryhl <aliceryhl@google.com>
> To: Trevor Gross <tmgross@umich.edu>
> To: Danilo Krummrich <dakr@kernel.org>
> To: Daniel Almeida <daniel.almeida@collabora.com>
> To: Tamir Duberstein <tamird@kernel.org>
> To: Onur Özkan <work@onurozkan.dev>
> Cc: rust-for-linux@vger.kernel.org
> Cc: linux-kernel@vger.kernel.org
> ---
>  rust/kernel/num.rs         |  1 +
>  rust/kernel/num/bounded.rs | 48 ++++++++++++++++++++++++++--------------------
>  2 files changed, 28 insertions(+), 21 deletions(-)
>
> diff --git a/rust/kernel/num.rs b/rust/kernel/num.rs
> index de589792a77a..0449e84a384a 100644
> --- a/rust/kernel/num.rs
> +++ b/rust/kernel/num.rs
> @@ -21,6 +21,7 @@ pub trait Sealed {}
>  
>  /// Describes core properties of integer types.
>  pub trait Integer:
> +    // Sealed so that unsafe code can rely on the correctness of its implementations.
>      private::Sealed
>      + Sized
>      + Copy
> diff --git a/rust/kernel/num/bounded.rs b/rust/kernel/num/bounded.rs
> index 2a2b0a4bca5e..1a3f369cd886 100644
> --- a/rust/kernel/num/bounded.rs
> +++ b/rust/kernel/num/bounded.rs
> @@ -336,7 +336,8 @@ impl<T, const N: u32> Bounded<T, N>
>      /// ```
>      pub fn try_new(value: T) -> Option<Self> {
>          fits_within(value, N).then(|| {
> -            // SAFETY: `fits_within` confirmed that `value` can be represented within `N` bits.
> +            // SAFETY: `Integer` is sealed, so `fits_within` has primitive integer semantics and
> +            // confirmed that `value` can be represented within `N` bits.

I know this was suggested on v1, but do these comments need to be
updated? The seal on `Integer` guarantees that all implementors have
proper integer semantics. `fits_within` relies on that to guarantee that
a given value can be represented in some number of bits. So wouldn't
relying on the guarantee provided by `fits_within` here be sufficient?

I'm nitpicking a bit here because SAFETY comments are simpler to
understand and maintain if they are simple - as long as they are
correct, of course.