linux-kernel - [PATCH 2/2] rust: pin-init: improve documentation for `Zeroable` derive macros

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250426083901.13289-2-benno.lossin@proton.me>
Date: Sat, 26 Apr 2025 08:39:28 +0000
From: Benno Lossin <benno.lossin@...ton.me>
To: Benno Lossin <benno.lossin@...ton.me>, Miguel Ojeda <ojeda@...nel.org>, Alex Gaynor <alex.gaynor@...il.com>, Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>, Björn Roy Baron <bjorn3_gh@...tonmail.com>, Andreas Hindborg <a.hindborg@...nel.org>, Alice Ryhl <aliceryhl@...gle.com>, Trevor Gross <tmgross@...ch.edu>, Danilo Krummrich <dakr@...nel.org>, Fiona Behrens <me@...enk.dev>, Christian Schrefl <chrisi.schrefl@...il.com>
Cc: rust-for-linux@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: [PATCH 2/2] rust: pin-init: improve documentation for `Zeroable` derive macros

Specify that both `MaybeZeroable` and `Zeroable` work on `union`s. Add a
doc example for a union. Also include an example with visibility on the
field.

Link: https://github.com/Rust-for-Linux/pin-init/pull/48/commits/ab0985a0e08df06c60a32ca5888f74adcc2c1cf3
Signed-off-by: Benno Lossin <benno.lossin@...ton.me>
---
Also see the compile-fail & macro expansion tests added by this commit
(not included in the kernel, since the test files are only upstream):

    https://github.com/Rust-for-Linux/pin-init/pull/48/commits/278070d12b41f0fca1b0d6dff6c5f38f3cf46044
---
 rust/pin-init/src/lib.rs | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs
index b5a295effd9c..9ab34036e6bc 100644
--- a/rust/pin-init/src/lib.rs
+++ b/rust/pin-init/src/lib.rs
@@ -395,9 +395,10 @@
 /// ```
 pub use ::pin_init_internal::pinned_drop;
 
-/// Derives the [`Zeroable`] trait for the given struct.
+/// Derives the [`Zeroable`] trait for the given `struct` or `union`.
 ///
-/// This can only be used for structs where every field implements the [`Zeroable`] trait.
+/// This can only be used for `struct`s/`union`s where every field implements the [`Zeroable`]
+/// trait.
 ///
 /// # Examples
 ///
@@ -406,14 +407,25 @@
 ///
 /// #[derive(Zeroable)]
 /// pub struct DriverData {
-///     id: i64,
+///     pub(crate) id: i64,
 ///     buf_ptr: *mut u8,
 ///     len: usize,
 /// }
 /// ```
+///
+/// ```
+/// use pin_init::Zeroable;
+///
+/// #[derive(Zeroable)]
+/// pub union SignCast {
+///     signed: i64,
+///     unsigned: u64,
+/// }
+/// ```
 pub use ::pin_init_internal::Zeroable;
 
-/// Derives the [`Zeroable`] trait for the given struct if all fields implement [`Zeroable`].
+/// Derives the [`Zeroable`] trait for the given `struct` or `union` if all fields implement
+/// [`Zeroable`].
 ///
 /// Contrary to the derive macro named [`macro@...oable`], this one silently fails when a field
 /// doesn't implement [`Zeroable`].
@@ -426,7 +438,7 @@
 /// // implmements `Zeroable`
 /// #[derive(MaybeZeroable)]
 /// pub struct DriverData {
-///     id: i64,
+///     pub(crate) id: i64,
 ///     buf_ptr: *mut u8,
 ///     len: usize,
 /// }
@@ -434,7 +446,7 @@
 /// // does not implmement `Zeroable`
 /// #[derive(MaybeZeroable)]
 /// pub struct DriverData2 {
-///     id: i64,
+///     pub(crate) id: i64,
 ///     buf_ptr: *mut u8,
 ///     len: usize,
 ///     // this field doesn't implement `Zeroable`
-- 
2.48.1