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

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

[Younes Akhouayri via B4 Relay]

From: Younes Akhouayri <git@younes.io>

Bounded relies on Integer::BITS and Integer::Signedness accurately
describing the implementing type to justify unchecked operations.
The reason external implementations are prohibited is currently recorded
only in the commit history.

Document this safety requirement on Integer itself.

Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Link: https://lore.kernel.org/all/CANiq72m8kycbfQ1teyne-OtB5d5TsUcX_WW0FCkWB3Ayyg-qWw@mail.gmail.com/
Signed-off-by: Younes Akhouayri <git@younes.io>
---
 rust/kernel/num.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/rust/kernel/num.rs b/rust/kernel/num.rs
index de589792a77a..1d06395d3a63 100644
--- a/rust/kernel/num.rs
+++ b/rust/kernel/num.rs
@@ -20,6 +20,11 @@ pub trait Sealed {}
 }
 
 /// Describes core properties of integer types.
+///
+/// This trait is sealed because [`Bounded`] relies on [`Integer::BITS`] and
+/// [`Integer::Signedness`] accurately describing the implementing type to
+/// justify unchecked operations. An incorrect implementation could therefore
+/// make safe [`Bounded`] operations cause undefined behavior.
 pub trait Integer:
     private::Sealed
     + Sized

---
base-commit: c6709d5e14072d0e3d02f291daee46a199e5dad3
change-id: 20260906-docs-rust-num-integer-sealing-safety-3a0e2967a948

Best regards,
--  
Younes Akhouayri <git@younes.io>

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

[Younes Akhouayri]

Bounded relies on Integer::BITS and Integer::Signedness accurately
describing the implementing type to justify unchecked operations.
The reason external implementations are prohibited is currently recorded
only in the commit history.

Document this safety requirement on Integer itself.

Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Link: https://lore.kernel.org/all/CANiq72m8kycbfQ1teyne-OtB5d5TsUcX_WW0FCkWB3Ayyg-qWw@mail.gmail.com/
Signed-off-by: Younes Akhouayri <git@younes.io>
---
 rust/kernel/num.rs | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/rust/kernel/num.rs b/rust/kernel/num.rs
index de589792a77a..1d06395d3a63 100644
--- a/rust/kernel/num.rs
+++ b/rust/kernel/num.rs
@@ -20,6 +20,11 @@ pub trait Sealed {}
 }
 
 /// Describes core properties of integer types.
+///
+/// This trait is sealed because [`Bounded`] relies on [`Integer::BITS`] and
+/// [`Integer::Signedness`] accurately describing the implementing type to
+/// justify unchecked operations. An incorrect implementation could therefore
+/// make safe [`Bounded`] operations cause undefined behavior.
 pub trait Integer:
     private::Sealed
     + Sized

---
base-commit: c6709d5e14072d0e3d02f291daee46a199e5dad3
change-id: 20260906-docs-rust-num-integer-sealing-safety-3a0e2967a948

Best regards,
--  
Younes Akhouayri <git@younes.io>

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

[Gary Guo]

On Sun Sep 6, 2026 at 8:40 AM BST, Younes Akhouayri via B4 Relay wrote:
> From: Younes Akhouayri <git@younes.io>
>
> Bounded relies on Integer::BITS and Integer::Signedness accurately
> describing the implementing type to justify unchecked operations.
> The reason external implementations are prohibited is currently recorded
> only in the commit history.
>
> Document this safety requirement on Integer itself.
>
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>
> Link: https://lore.kernel.org/all/CANiq72m8kycbfQ1teyne-OtB5d5TsUcX_WW0FCkWB3Ayyg-qWw@mail.gmail.com/
> Signed-off-by: Younes Akhouayri <git@younes.io>
> ---
>  rust/kernel/num.rs | 5 +++++
>  1 file changed, 5 insertions(+)
>
> diff --git a/rust/kernel/num.rs b/rust/kernel/num.rs
> index de589792a77a..1d06395d3a63 100644
> --- a/rust/kernel/num.rs
> +++ b/rust/kernel/num.rs
> @@ -20,6 +20,11 @@ pub trait Sealed {}
>  }
>  
>  /// Describes core properties of integer types.
> +///
> +/// This trait is sealed because [`Bounded`] relies on [`Integer::BITS`] and
> +/// [`Integer::Signedness`] accurately describing the implementing type to
> +/// justify unchecked operations. An incorrect implementation could therefore
> +/// make safe [`Bounded`] operations cause undefined behavior.

I think this is a fairly typical case where correctness turns into safety --
i.e. unsafe code depends on correct impl of safe code. I think a

    // sealed so that unsafe code can rely on correctness

could be sufficient. I imagine with a future sealed attribute, they can also be
single line, so

    #[sealed] // so that unsafe code can rely on correctnes

would serve the purpose. Miguel, any thoughts?

Best,
Gary

>  pub trait Integer:
>      private::Sealed
>      + Sized
>
> ---
> base-commit: c6709d5e14072d0e3d02f291daee46a199e5dad3
> change-id: 20260906-docs-rust-num-integer-sealing-safety-3a0e2967a948
>
> Best regards,
> --  
> Younes Akhouayri <git@younes.io>

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

[Miguel Ojeda]

On Sun, Sep 6, 2026 at 2:46 PM Gary Guo <gary@garyguo.net> wrote:
>
>     #[sealed] // so that unsafe code can rely on correctnes
>
> would serve the purpose. Miguel, any thoughts?

Yeah, we could at least mention something about the seal in the `//
SAFETY` comments that actually rely on it, even if it is just adding
"The trait is sealed." or maybe a bit more.

Cheers,
Miguel

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

[Alexandre Courbot]

On Sun Sep 6, 2026 at 4:40 PM JST, Younes Akhouayri via B4 Relay wrote:
> From: Younes Akhouayri <git@younes.io>
>
> Bounded relies on Integer::BITS and Integer::Signedness accurately
> describing the implementing type to justify unchecked operations.
> The reason external implementations are prohibited is currently recorded
> only in the commit history.
>
> Document this safety requirement on Integer itself.
>
> Suggested-by: Miguel Ojeda <ojeda@kernel.org>
> Link: https://lore.kernel.org/all/CANiq72m8kycbfQ1teyne-OtB5d5TsUcX_WW0FCkWB3Ayyg-qWw@mail.gmail.com/
> Signed-off-by: Younes Akhouayri <git@younes.io>

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