[PATCH 1/2] rust: pin-init: improve safety documentation for `impl<T> [Pin]Init<T> for T`

[PATCH 1/2] rust: pin-init: improve safety documentation for `impl<T> [Pin]Init<T> for T`

[Benno Lossin]

The inner SAFETY comments were missing since commit 5cfe7bef6751 ("rust:
enable `clippy::undocumented_unsafe_blocks` lint").

Also rework the implementation of `__pinned_init` to better justify the
SAFETY comment.

Link: https://github.com/Rust-for-Linux/pin-init/pull/62/commits/df925b2e27d499b7144df7e62b01acb00d4b94b8
Signed-off-by: Benno Lossin <lossin@kernel.org>
---
 rust/pin-init/src/lib.rs | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs
index 9ab34036e6bc..d1c3ca5cfff4 100644
--- a/rust/pin-init/src/lib.rs
+++ b/rust/pin-init/src/lib.rs
@@ -1390,20 +1390,22 @@ pub fn pin_init_array_from_fn<I, const N: usize, T, E>(
     unsafe { pin_init_from_closure(init) }
 }
 
-// SAFETY: Every type can be initialized by-value.
+// SAFETY: the `__init` function always returns `Ok(())` and initializes every field of `slot`.
 unsafe impl<T, E> Init<T, E> for T {
     unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
-        // SAFETY: TODO.
+        // SAFETY: `slot` is valid for writes by the safety requirements of this function.
         unsafe { slot.write(self) };
         Ok(())
     }
 }
 
-// SAFETY: Every type can be initialized by-value. `__pinned_init` calls `__init`.
+// SAFETY: the `__pinned_init` function always returns `Ok(())` and initializes every field of
+// `slot`. Additionally, all pinning invariants of `T` are upheld.
 unsafe impl<T, E> PinInit<T, E> for T {
     unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {
-        // SAFETY: TODO.
-        unsafe { self.__init(slot) }
+        // SAFETY: `slot` is valid for writes by the safety requirements of this function.
+        unsafe { slot.write(self) };
+        Ok(())
     }
 }
 

base-commit: 1ce98bb2bb30713ec4374ef11ead0d7d3e856766
-- 
2.49.0

[PATCH 2/2] change blanket impls for `[Pin]Init` and add one for `Result<T, E>`

[Benno Lossin]

Remove the error from the blanket implementations `impl<T, E> Init<T, E>
for T` (and also for `PinInit`). Add implementations for `Result<T, E>`.

This allows one to easily construct (un)conditional failing
initializers. It also improves the compatibility with APIs that do not
use pin-init, because users can supply a `Result<T, E>` to a  function
taking an `impl PinInit<T, E>`.

Suggested-by: Alice Ryhl <aliceryhl@google.com>
Link: https://github.com/Rust-for-Linux/pin-init/pull/62/commits/58612514b256c6f4a4a0718be25298410e67387a
[ Also fix a compile error in block. - Benno ]
Signed-off-by: Benno Lossin <lossin@kernel.org>
---

This patch is also needed by Danilo for initializing `Devres`
ergonomically.

---
 rust/kernel/block/mq/tag_set.rs | 12 +++++++-----
 rust/pin-init/src/lib.rs        | 30 ++++++++++++++++++++++++++----
 2 files changed, 33 insertions(+), 9 deletions(-)

diff --git a/rust/kernel/block/mq/tag_set.rs b/rust/kernel/block/mq/tag_set.rs
index bcf4214ad149..c3cf56d52bee 100644
--- a/rust/kernel/block/mq/tag_set.rs
+++ b/rust/kernel/block/mq/tag_set.rs
@@ -9,7 +9,7 @@
 use crate::{
     bindings,
     block::mq::{operations::OperationsVTable, request::RequestDataWrapper, Operations},
-    error,
+    error::{self, Result},
     prelude::try_pin_init,
     types::Opaque,
 };
@@ -41,7 +41,7 @@ pub fn new(
         // SAFETY: `blk_mq_tag_set` only contains integers and pointers, which
         // all are allowed to be 0.
         let tag_set: bindings::blk_mq_tag_set = unsafe { core::mem::zeroed() };
-        let tag_set = core::mem::size_of::<RequestDataWrapper>()
+        let tag_set: Result<_> = core::mem::size_of::<RequestDataWrapper>()
             .try_into()
             .map(|cmd_size| {
                 bindings::blk_mq_tag_set {
@@ -56,12 +56,14 @@ pub fn new(
                     nr_maps: num_maps,
                     ..tag_set
                 }
-            });
+            })
+            .map(Opaque::new)
+            .map_err(|e| e.into());
 
         try_pin_init!(TagSet {
-            inner <- PinInit::<_, error::Error>::pin_chain(Opaque::new(tag_set?), |tag_set| {
+            inner <- tag_set.pin_chain(|tag_set| {
                 // SAFETY: we do not move out of `tag_set`.
-                let tag_set = unsafe { Pin::get_unchecked_mut(tag_set) };
+                let tag_set: &mut Opaque<_> = unsafe { Pin::get_unchecked_mut(tag_set) };
                 // SAFETY: `tag_set` is a reference to an initialized `blk_mq_tag_set`.
                 error::to_result( unsafe { bindings::blk_mq_alloc_tag_set(tag_set.get())})
             }),
diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs
index d1c3ca5cfff4..f4e034497cdd 100644
--- a/rust/pin-init/src/lib.rs
+++ b/rust/pin-init/src/lib.rs
@@ -1391,8 +1391,8 @@ pub fn pin_init_array_from_fn<I, const N: usize, T, E>(
 }
 
 // SAFETY: the `__init` function always returns `Ok(())` and initializes every field of `slot`.
-unsafe impl<T, E> Init<T, E> for T {
-    unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
+unsafe impl<T> Init<T> for T {
+    unsafe fn __init(self, slot: *mut T) -> Result<(), Infallible> {
         // SAFETY: `slot` is valid for writes by the safety requirements of this function.
         unsafe { slot.write(self) };
         Ok(())
@@ -1401,14 +1401,36 @@ unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
 
 // SAFETY: the `__pinned_init` function always returns `Ok(())` and initializes every field of
 // `slot`. Additionally, all pinning invariants of `T` are upheld.
-unsafe impl<T, E> PinInit<T, E> for T {
-    unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {
+unsafe impl<T> PinInit<T> for T {
+    unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), Infallible> {
         // SAFETY: `slot` is valid for writes by the safety requirements of this function.
         unsafe { slot.write(self) };
         Ok(())
     }
 }
 
+// SAFETY: when the `__init` function returns with
+// - `Ok(())`, `slot` was initialized and all pinned invariants of `T` are upheld.
+// - `Err(err)`, slot was not written to.
+unsafe impl<T, E> Init<T, E> for Result<T, E> {
+    unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
+        // SAFETY: `slot` is valid for writes by the safety requirements of this function.
+        unsafe { slot.write(self?) };
+        Ok(())
+    }
+}
+
+// SAFETY: when the `__pinned_init` function returns with
+// - `Ok(())`, `slot` was initialized and all pinned invariants of `T` are upheld.
+// - `Err(err)`, slot was not written to.
+unsafe impl<T, E> PinInit<T, E> for Result<T, E> {
+    unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {
+        // SAFETY: `slot` is valid for writes by the safety requirements of this function.
+        unsafe { slot.write(self?) };
+        Ok(())
+    }
+}
+
 /// Smart pointer containing uninitialized memory and that can write a value.
 pub trait InPlaceWrite<T> {
     /// The type `Self` turns into when the contents are initialized.
-- 
2.49.0

Re: [PATCH 1/2] rust: pin-init: improve safety documentation for `impl<T> [Pin]Init<T> for T`

[Boqun Feng]

On Thu, May 29, 2025 at 10:10:23AM +0200, Benno Lossin wrote:
> The inner SAFETY comments were missing since commit 5cfe7bef6751 ("rust:
> enable `clippy::undocumented_unsafe_blocks` lint").
> 
> Also rework the implementation of `__pinned_init` to better justify the
> SAFETY comment.
> 
> Link: https://github.com/Rust-for-Linux/pin-init/pull/62/commits/df925b2e27d499b7144df7e62b01acb00d4b94b8
> Signed-off-by: Benno Lossin <lossin@kernel.org>

Reviewed-by: Boqun Feng <boqun.feng@gmail.com>

Regards,
Boqun

> ---
>  rust/pin-init/src/lib.rs | 12 +++++++-----
>  1 file changed, 7 insertions(+), 5 deletions(-)
> 
> diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs
> index 9ab34036e6bc..d1c3ca5cfff4 100644
> --- a/rust/pin-init/src/lib.rs
> +++ b/rust/pin-init/src/lib.rs
> @@ -1390,20 +1390,22 @@ pub fn pin_init_array_from_fn<I, const N: usize, T, E>(
>      unsafe { pin_init_from_closure(init) }
>  }
>  
> -// SAFETY: Every type can be initialized by-value.
> +// SAFETY: the `__init` function always returns `Ok(())` and initializes every field of `slot`.
>  unsafe impl<T, E> Init<T, E> for T {
>      unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
> -        // SAFETY: TODO.
> +        // SAFETY: `slot` is valid for writes by the safety requirements of this function.
>          unsafe { slot.write(self) };
>          Ok(())
>      }
>  }
>  
> -// SAFETY: Every type can be initialized by-value. `__pinned_init` calls `__init`.
> +// SAFETY: the `__pinned_init` function always returns `Ok(())` and initializes every field of
> +// `slot`. Additionally, all pinning invariants of `T` are upheld.
>  unsafe impl<T, E> PinInit<T, E> for T {
>      unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {
> -        // SAFETY: TODO.
> -        unsafe { self.__init(slot) }
> +        // SAFETY: `slot` is valid for writes by the safety requirements of this function.
> +        unsafe { slot.write(self) };
> +        Ok(())
>      }
>  }
>  
> 
> base-commit: 1ce98bb2bb30713ec4374ef11ead0d7d3e856766
> -- 
> 2.49.0
> 

Re: [PATCH 2/2] change blanket impls for `[Pin]Init` and add one for `Result<T, E>`

[Boqun Feng]

On Thu, May 29, 2025 at 10:10:24AM +0200, Benno Lossin wrote:
> Remove the error from the blanket implementations `impl<T, E> Init<T, E>
> for T` (and also for `PinInit`). Add implementations for `Result<T, E>`.
> 
> This allows one to easily construct (un)conditional failing
> initializers. It also improves the compatibility with APIs that do not
> use pin-init, because users can supply a `Result<T, E>` to a  function
> taking an `impl PinInit<T, E>`.
> 
> Suggested-by: Alice Ryhl <aliceryhl@google.com>
> Link: https://github.com/Rust-for-Linux/pin-init/pull/62/commits/58612514b256c6f4a4a0718be25298410e67387a
> [ Also fix a compile error in block. - Benno ]
> Signed-off-by: Benno Lossin <lossin@kernel.org>

The patch title is missing a "rust:" tag... but you can fix that in PR.

Reviewed-by: Boqun Feng <boqun.feng@gmail.com>

Regards,
Boqun

> ---
> 
> This patch is also needed by Danilo for initializing `Devres`
> ergonomically.
> 
> ---
>  rust/kernel/block/mq/tag_set.rs | 12 +++++++-----
>  rust/pin-init/src/lib.rs        | 30 ++++++++++++++++++++++++++----
>  2 files changed, 33 insertions(+), 9 deletions(-)
> 
> diff --git a/rust/kernel/block/mq/tag_set.rs b/rust/kernel/block/mq/tag_set.rs
> index bcf4214ad149..c3cf56d52bee 100644
> --- a/rust/kernel/block/mq/tag_set.rs
> +++ b/rust/kernel/block/mq/tag_set.rs
> @@ -9,7 +9,7 @@
>  use crate::{
>      bindings,
>      block::mq::{operations::OperationsVTable, request::RequestDataWrapper, Operations},
> -    error,
> +    error::{self, Result},
>      prelude::try_pin_init,
>      types::Opaque,
>  };
> @@ -41,7 +41,7 @@ pub fn new(
>          // SAFETY: `blk_mq_tag_set` only contains integers and pointers, which
>          // all are allowed to be 0.
>          let tag_set: bindings::blk_mq_tag_set = unsafe { core::mem::zeroed() };
> -        let tag_set = core::mem::size_of::<RequestDataWrapper>()
> +        let tag_set: Result<_> = core::mem::size_of::<RequestDataWrapper>()
>              .try_into()
>              .map(|cmd_size| {
>                  bindings::blk_mq_tag_set {
> @@ -56,12 +56,14 @@ pub fn new(
>                      nr_maps: num_maps,
>                      ..tag_set
>                  }
> -            });
> +            })
> +            .map(Opaque::new)
> +            .map_err(|e| e.into());
>  
>          try_pin_init!(TagSet {
> -            inner <- PinInit::<_, error::Error>::pin_chain(Opaque::new(tag_set?), |tag_set| {
> +            inner <- tag_set.pin_chain(|tag_set| {
>                  // SAFETY: we do not move out of `tag_set`.
> -                let tag_set = unsafe { Pin::get_unchecked_mut(tag_set) };
> +                let tag_set: &mut Opaque<_> = unsafe { Pin::get_unchecked_mut(tag_set) };
>                  // SAFETY: `tag_set` is a reference to an initialized `blk_mq_tag_set`.
>                  error::to_result( unsafe { bindings::blk_mq_alloc_tag_set(tag_set.get())})
>              }),
> diff --git a/rust/pin-init/src/lib.rs b/rust/pin-init/src/lib.rs
> index d1c3ca5cfff4..f4e034497cdd 100644
> --- a/rust/pin-init/src/lib.rs
> +++ b/rust/pin-init/src/lib.rs
> @@ -1391,8 +1391,8 @@ pub fn pin_init_array_from_fn<I, const N: usize, T, E>(
>  }
>  
>  // SAFETY: the `__init` function always returns `Ok(())` and initializes every field of `slot`.
> -unsafe impl<T, E> Init<T, E> for T {
> -    unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
> +unsafe impl<T> Init<T> for T {
> +    unsafe fn __init(self, slot: *mut T) -> Result<(), Infallible> {
>          // SAFETY: `slot` is valid for writes by the safety requirements of this function.
>          unsafe { slot.write(self) };
>          Ok(())
> @@ -1401,14 +1401,36 @@ unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
>  
>  // SAFETY: the `__pinned_init` function always returns `Ok(())` and initializes every field of
>  // `slot`. Additionally, all pinning invariants of `T` are upheld.
> -unsafe impl<T, E> PinInit<T, E> for T {
> -    unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {
> +unsafe impl<T> PinInit<T> for T {
> +    unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), Infallible> {
>          // SAFETY: `slot` is valid for writes by the safety requirements of this function.
>          unsafe { slot.write(self) };
>          Ok(())
>      }
>  }
>  
> +// SAFETY: when the `__init` function returns with
> +// - `Ok(())`, `slot` was initialized and all pinned invariants of `T` are upheld.
> +// - `Err(err)`, slot was not written to.
> +unsafe impl<T, E> Init<T, E> for Result<T, E> {
> +    unsafe fn __init(self, slot: *mut T) -> Result<(), E> {
> +        // SAFETY: `slot` is valid for writes by the safety requirements of this function.
> +        unsafe { slot.write(self?) };
> +        Ok(())
> +    }
> +}
> +
> +// SAFETY: when the `__pinned_init` function returns with
> +// - `Ok(())`, `slot` was initialized and all pinned invariants of `T` are upheld.
> +// - `Err(err)`, slot was not written to.
> +unsafe impl<T, E> PinInit<T, E> for Result<T, E> {
> +    unsafe fn __pinned_init(self, slot: *mut T) -> Result<(), E> {
> +        // SAFETY: `slot` is valid for writes by the safety requirements of this function.
> +        unsafe { slot.write(self?) };
> +        Ok(())
> +    }
> +}
> +
>  /// Smart pointer containing uninitialized memory and that can write a value.
>  pub trait InPlaceWrite<T> {
>      /// The type `Self` turns into when the contents are initialized.
> -- 
> 2.49.0
> 

Re: [PATCH 2/2] change blanket impls for `[Pin]Init` and add one for `Result<T, E>`

[Benno Lossin]

On Thu May 29, 2025 at 9:11 PM CEST, Boqun Feng wrote:
> On Thu, May 29, 2025 at 10:10:24AM +0200, Benno Lossin wrote:
>> Remove the error from the blanket implementations `impl<T, E> Init<T, E>
>> for T` (and also for `PinInit`). Add implementations for `Result<T, E>`.
>> 
>> This allows one to easily construct (un)conditional failing
>> initializers. It also improves the compatibility with APIs that do not
>> use pin-init, because users can supply a `Result<T, E>` to a  function
>> taking an `impl PinInit<T, E>`.
>> 
>> Suggested-by: Alice Ryhl <aliceryhl@google.com>
>> Link: https://github.com/Rust-for-Linux/pin-init/pull/62/commits/58612514b256c6f4a4a0718be25298410e67387a
>> [ Also fix a compile error in block. - Benno ]
>> Signed-off-by: Benno Lossin <lossin@kernel.org>
>
> The patch title is missing a "rust:" tag... but you can fix that in PR.

Good catch, I originally ported this patch with my script, but then I
decided to squash upstream and then copied the commit message from
there, removing the prefix...


> Reviewed-by: Boqun Feng <boqun.feng@gmail.com>

Thanks!

---
Cheers,
Benno

Re: [PATCH 1/2] rust: pin-init: improve safety documentation for `impl<T> [Pin]Init<T> for T`

[Benno Lossin]

On Thu May 29, 2025 at 10:10 AM CEST, Benno Lossin wrote:
> The inner SAFETY comments were missing since commit 5cfe7bef6751 ("rust:
> enable `clippy::undocumented_unsafe_blocks` lint").
>
> Also rework the implementation of `__pinned_init` to better justify the
> SAFETY comment.
>
> Link: https://github.com/Rust-for-Linux/pin-init/pull/62/commits/df925b2e27d499b7144df7e62b01acb00d4b94b8
> Signed-off-by: Benno Lossin <lossin@kernel.org>
> ---
>  rust/pin-init/src/lib.rs | 12 +++++++-----
>  1 file changed, 7 insertions(+), 5 deletions(-)

Applied both to pin-init-next -- thanks everyone!

    [ add title prefix `rust: pin-init` - Benno ]

---
Cheers,
Benno

Re: [PATCH 2/2] change blanket impls for `[Pin]Init` and add one for `Result<T, E>`

[Danilo Krummrich]

On 5/29/25 10:10 AM, Benno Lossin wrote:
> Remove the error from the blanket implementations `impl<T, E> Init<T, E>
> for T` (and also for `PinInit`). Add implementations for `Result<T, E>`.
> 
> This allows one to easily construct (un)conditional failing
> initializers. It also improves the compatibility with APIs that do not
> use pin-init, because users can supply a `Result<T, E>` to a  function
> taking an `impl PinInit<T, E>`.
> 
> Suggested-by: Alice Ryhl <aliceryhl@google.com>
> Link: https://github.com/Rust-for-Linux/pin-init/pull/62/commits/58612514b256c6f4a4a0718be25298410e67387a
> [ Also fix a compile error in block. - Benno ]
> Signed-off-by: Benno Lossin <lossin@kernel.org>
> ---
> 
> This patch is also needed by Danilo for initializing `Devres`
> ergonomically.

For this purpose, can you please provide me with a signed tag for this one
please? Otherwise I can also add the explicit `Infallible` generics in a few
places until next cycle.

Re: [PATCH 2/2] change blanket impls for `[Pin]Init` and add one for `Result<T, E>`

[Benno Lossin]

On Tue Jun 10, 2025 at 3:44 PM CEST, Danilo Krummrich wrote:
> On 5/29/25 10:10 AM, Benno Lossin wrote:
>> Remove the error from the blanket implementations `impl<T, E> Init<T, E>
>> for T` (and also for `PinInit`). Add implementations for `Result<T, E>`.
>> 
>> This allows one to easily construct (un)conditional failing
>> initializers. It also improves the compatibility with APIs that do not
>> use pin-init, because users can supply a `Result<T, E>` to a  function
>> taking an `impl PinInit<T, E>`.
>> 
>> Suggested-by: Alice Ryhl <aliceryhl@google.com>
>> Link: https://github.com/Rust-for-Linux/pin-init/pull/62/commits/58612514b256c6f4a4a0718be25298410e67387a
>> [ Also fix a compile error in block. - Benno ]
>> Signed-off-by: Benno Lossin <lossin@kernel.org>
>> ---
>> 
>> This patch is also needed by Danilo for initializing `Devres`
>> ergonomically.
>
> For this purpose, can you please provide me with a signed tag for this one
> please? Otherwise I can also add the explicit `Infallible` generics in a few
> places until next cycle.

I rebased `pin-init-next` to have these two commits as the first two and
will create a tag a bit later in the cycle when I'm sure that they are
stable.

---
Cheers,
Benno