From nobody Fri Sep 25 04:44:23 2026 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-1.web.codeaurora.org [10.30.226.201]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 33DC536A374; Wed, 16 Sep 2026 15:10:54 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=10.30.226.201 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789571455; cv=none; b=kYYhkqZFZReM795NjEjHnhmtRCKCcfThI8HlaRgsLZuIHSFKWVNbMHd72PrtBUFqP2XQCGOZgbqIGG6RsQoux2xOJJi1k5A3h9rIkXxFeGlCPLWRMBJS6rGU8maEUqgtLztbcJgMfUf9989Op+KUhECuWZqr9Yw/k+oVdLcujNQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789571455; c=relaxed/simple; bh=tiBtNi4UdtCY7BBoK8CcuFpjleEy3QUbwC6npWMDmqU=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:To:Cc; b=aL+OWaGKT3PfMzq37PusYu/Kn83oembGIwWoRgoPPqYwsQZENrTJM/uEVCV2zTvPcms/VsvN6jTX/UdVVepaQR63dUlGvaPnzPIyolKY7AzKK3X79e99tjLTeKYEwkyZyFTpV/T17n3GMJkXSAuUYjRcvrkDh7TAvk8BLupED0E= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=Zcw1ZVzv; arc=none smtp.client-ip=10.30.226.201 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="Zcw1ZVzv" Received: by smtp.kernel.org (Postfix) with ESMTPS id B512FC2BCB3; Wed, 16 Sep 2026 15:10:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1789571454; bh=tiBtNi4UdtCY7BBoK8CcuFpjleEy3QUbwC6npWMDmqU=; h=From:Date:Subject:To:Cc:Reply-To:From; b=Zcw1ZVzvAzHPOrxAo0xlgwRmSWfXR6gUwh4SUHYuEiiOnujuUxfvSNUNeff0rsIMw XgyeG4f2naTKadjATFQc45fQvpVH5aea2w4DaS7sKqBG+x8+R6TIDXde5b18nwArUy GthBJrnOAhAJ9jIxSda1B0G6DcPPKKq7h8mlXaw8uRsYxv+ZRtsbL0yTFyZRCido7o jzld+yh0gTEwhuX7ZbP4xx3R1+8MgeZxre6SbD5roLkfWe+e4YFhU7ha5keL5jjufG gQNLCfBUj/X4QFlU58KDE00WB7eaqkge4gVeh0QAfY1aKwHtaaZsKXNUu6G7iwylDI AyR34TXThvPrg== Received: from aws-us-west-2-korg-lkml-1.web.codeaurora.org (localhost.localdomain [127.0.0.1]) by smtp.lore.kernel.org (Postfix) with ESMTP id A075EC982CA; Wed, 16 Sep 2026 15:10:54 +0000 (UTC) From: Younes Akhouayri via B4 Relay Date: Wed, 16 Sep 2026 17:10:38 +0200 Subject: [PATCH v3] rust: num: document why Integer is sealed Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Message-Id: <20260916-docs-rust-num-integer-sealing-safety-v3-1-00f950426c85@younes.io> X-B4-Tracking: v=1; b=H4sIAAAAAAAC/5WOQW7CMBBFr4K87lDHhsRh1XtULBxnSKYqNvI4E RHK3bHDhmW7fKM/7/+HYIyELE67h4g4E1PwGfTHTrjR+gGB+sxCSVXLVtbQB8cQJ07gpyuQTzh gBEb7S34AthdMC2grUbV1Y9uDEVl1i3ih+1bzfX4xT90PulTcJdFZRuii9W4spxBpIP+59bw+c 2YkTiEu29a5Kq5/zporqKAx8tjottJSua8lTB55T0GUWbN6l5o/SlWWonH1UelD3xn1Ll3X9Qn nTQh2YwEAAA== X-Change-ID: 20260906-docs-rust-num-integer-sealing-safety-3a0e2967a948 To: Alexandre Courbot , Yury Norov , Miguel Ojeda , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= , Benno Lossin , Andreas Hindborg , Alice Ryhl , Trevor Gross , Danilo Krummrich , Daniel Almeida , Tamir Duberstein , =?utf-8?q?Onur_=C3=96zkan?= Cc: rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, Younes Akhouayri X-Mailer: b4 0.15.2 X-Developer-Signature: v=1; a=ed25519-sha256; t=1789571453; l=7870; i=git@younes.io; s=20260712; h=from:subject:message-id; bh=6EBGJ4a6/ShfQ/6ynR/rskrjn3ZQAYYZNFuSE3dWtm8=; b=6TmRtiwtGmVkccHklAtYYJopUGxnctI2PmWwSUaGmimoD5HX1Ikr+iTGieknagyKCoG9/LlAA KjGvj31yH77AFdLRUSbVVBZU/hKdmzILPOrn1aVcyxX2Ad22nFSNd2G X-Developer-Key: i=git@younes.io; a=ed25519; pk=1DRfzPrQ04RQHHgGK28t+vjIAPv5oISPiAdLMU6J5dE= X-Endpoint-Received: by B4 Relay for git@younes.io/20260712 with auth_id=866 X-Original-From: Younes Akhouayri Reply-To: git@younes.io From: Younes Akhouayri Bounded relies on Integer implementations to provide primitive integer semantics when justifying unchecked operations. Explain why Integer is sealed next to its private supertrait. Document the dependency inside fits_within, so callers can rely on its result without repeating that explanation. Mention sealing in safety comments that directly rely on integer metadata, shifts or conversions. Suggested-by: Miguel Ojeda Suggested-by: Gary Guo Suggested-by: Alexandre Courbot Link: https://lore.kernel.org/all/CANiq72m8kycbfQ1teyne-OtB5d5TsUcX_WW0FCkW= B3Ayyg-qWw@mail.gmail.com/ Link: https://lore.kernel.org/all/DL88SQWYU15W.2CVZB5NVSSJGK@garyguo.net/ Link: https://lore.kernel.org/all/CANiq72kx-YPPEruOFdu-Dp7GX+8=3DEt6svG+sQt= qEmmF7kpnVyQ@mail.gmail.com/ Link: https://lore.kernel.org/all/DLDSZ09SM8HI.3PHPYGLV2YZBX@nvidia.com/ Signed-off-by: Younes Akhouayri --- Changes in v3: - Document the sealing dependency inside fits_within and restore its callers' original safety comments, following Alexandre's feedback. - Restore extend's invariant-based comment and remove the repeated sealing explanation from the second cast safety comment. - Link to v2: https://patch.msgid.link/20260908-docs-rust-num-integer-seali= ng-safety-v2-1-e8c65234db82@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-seali= ng-safety-v1-1-78057391302c@younes.io To: Alexandre Courbot To: Yury Norov To: Miguel Ojeda To: Boqun Feng To: Gary Guo To: Bj=C3=B6rn Roy Baron To: Benno Lossin To: Andreas Hindborg To: Alice Ryhl To: Trevor Gross To: Danilo Krummrich To: Daniel Almeida To: Tamir Duberstein To: Onur =C3=96zkan Cc: rust-for-linux@vger.kernel.org Cc: linux-kernel@vger.kernel.org --- rust/kernel/num.rs | 1 + rust/kernel/num/bounded.rs | 32 +++++++++++++++++++------------- 2 files changed, 20 insertions(+), 13 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 {} =20 /// Describes core properties of integer types. pub trait Integer: + // Sealed so that unsafe code can rely on the correctness of its imple= mentations. private::Sealed + Sized + Copy diff --git a/rust/kernel/num/bounded.rs b/rust/kernel/num/bounded.rs index 2a2b0a4bca5e..aff35e2eb616 100644 --- a/rust/kernel/num/bounded.rs +++ b/rust/kernel/num/bounded.rs @@ -40,6 +40,8 @@ macro_rules! fits_within { /// Returns `true` if `value` can be represented with at most `N` bits in = a `T`. #[inline(always)] fn fits_within(value: T, num_bits: u32) -> bool { + // `Integer` is sealed, so the bit width, shifts and equality have pri= mitive integer semantics. + // Unsafe code relies on this function correctly checking whether `val= ue` fits. fits_within!(value, T, num_bits) } =20 @@ -472,8 +474,9 @@ pub fn cast(self) -> Bounded T: Integer, U: Integer, { - // SAFETY: The converted value is represented using `N` bits, `U` = can contain `N` bits, and - // `U` and `T` have the same sign, hence this conversion cannot fa= il. + // SAFETY: `Integer` is sealed, so the bit widths and signedness a= re correct. The converted + // value is represented using `N` bits, `U` can contain `N` bits, = and `U` and `T` have the + // same sign, hence this conversion cannot fail. let value =3D unsafe { U::try_from(self.get()).unwrap_unchecked() = }; =20 // SAFETY: Although the backing type has changed, the value is sti= ll represented within @@ -498,8 +501,9 @@ pub fn shr(self) -> B= ounded { const_assert!(SHIFT < T::BITS); const_assert!(RES + SHIFT >=3D N); =20 - // SAFETY: We shift the value right by `SHIFT`, reducing the numbe= r of bits needed to - // represent the shifted value by as much, and just asserted that = `RES >=3D N - SHIFT`. + // SAFETY: `Integer` is sealed, so the shift has primitive integer= semantics. We reduce the + // number of bits needed to represent the shifted value by `SHIFT`= , and just asserted that + // `RES >=3D N - SHIFT`. unsafe { Bounded::__new(self.0 >> SHIFT) } } =20 @@ -550,8 +554,9 @@ pub fn shr_exact(self= ) -> Option(self) -> Bounded { const_assert!(RES >=3D N + SHIFT); =20 - // SAFETY: We shift the value left by `SHIFT`, augmenting the numb= er of bits needed to - // represent the shifted value by as much, and just asserted that = `RES >=3D N + SHIFT`. + // SAFETY: `Integer` is sealed, so the shift has primitive integer= semantics. We augment + // the number of bits needed to represent the shifted value by `SH= IFT`, and just asserted + // that `RES >=3D N + SHIFT`. unsafe { Bounded::__new(self.0 << SHIFT) } } } @@ -1028,8 +1033,9 @@ impl From<$type> for Bounded Self: AtLeastXBits<{ <$type as Integer>::BITS as usize }>, { fn from(value: $type) -> Self { - // SAFETY: The trait bound on `Self` guarantees that `N` b= its is - // enough to hold any value of the source type. + // SAFETY: `Integer` is sealed, so the bit widths and sign= edness are correct. The + // trait bound on `Self` guarantees that `N` bits is enoug= h to hold any value of + // the source type. unsafe { Self::__new(T::from(value)) } } } @@ -1104,9 +1110,9 @@ impl From> for $type Bounded: FitsInXBits<{ <$type as Integer>::BITS as usize= }>, { fn from(value: Bounded) -> $type { - // SAFETY: The trait bound on `Bounded` ensures that any v= alue it holds (which - // is constrained to `N` bits) can fit into the destinatio= n type, so this - // conversion cannot fail. + // SAFETY: `Integer` is sealed, so the bit widths and sign= edness are correct. The + // trait bound on `Bounded` ensures that any value it hold= s (which is constrained + // to `N` bits) can fit into the destination type, so this= conversion cannot fail. unsafe { <$type>::try_from(value.get()).unwrap_unchecked()= } } } @@ -1137,8 +1143,8 @@ impl From for Bounded T: Integer + From, { fn from(value: bool) -> Self { - // SAFETY: A boolean is represented by `0` or `1`, so it fits with= in any valid unsigned - // `Bounded` width. + // SAFETY: `Integer` is sealed, so `T` is a primitive unsigned int= eger. A boolean is + // represented by `0` or `1`, so it fits within any valid unsigned= `Bounded` width. unsafe { Self::__new(T::from(value)) } } } --- base-commit: c6709d5e14072d0e3d02f291daee46a199e5dad3 change-id: 20260906-docs-rust-num-integer-sealing-safety-3a0e2967a948 Best regards, -- =20 Younes Akhouayri