summaryrefslogtreecommitdiffstats
path: root/rust
diff options
context:
space:
mode:
authorBenno Lossin <benno.lossin@proton.me>2023-04-08 12:26:22 +0000
committerMiguel Ojeda <ojeda@kernel.org>2023-04-12 18:41:05 +0200
commit692e8935e23efab6c5d5fc4b003816b33c8082f7 (patch)
tree18fe62f03bfdc6475f4e0ab63eb952cc4d98aaa3 /rust
parent8586f1acd314a47d68d189331606ca235a05b972 (diff)
downloadlinux-stable-692e8935e23efab6c5d5fc4b003816b33c8082f7.tar.gz
linux-stable-692e8935e23efab6c5d5fc4b003816b33c8082f7.tar.bz2
linux-stable-692e8935e23efab6c5d5fc4b003816b33c8082f7.zip
rust: types: add `Opaque::ffi_init`
This function allows to easily initialize `Opaque` with the pin-init API. `Opaque::ffi_init` takes a closure and returns a pin-initializer. This pin-initiailizer calls the given closure with a pointer to the inner `T`. Co-developed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Gary Guo <gary@garyguo.net> Signed-off-by: Benno Lossin <benno.lossin@proton.me> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Link: https://lore.kernel.org/r/20230408122429.1103522-14-y86-dev@protonmail.com [ Fixed typo. ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Diffstat (limited to 'rust')
-rw-r--r--rust/kernel/init.rs9
-rw-r--r--rust/kernel/types.rs20
2 files changed, 29 insertions, 0 deletions
diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
index ffd539e2f5ef..a1298c8bbda0 100644
--- a/rust/kernel/init.rs
+++ b/rust/kernel/init.rs
@@ -177,6 +177,14 @@
//! }
//! ```
//!
+//! For the special case where initializing a field is a single FFI-function call that cannot fail,
+//! there exist the helper function [`Opaque::ffi_init`]. This function initialize a single
+//! [`Opaque`] field by just delegating to the supplied closure. You can use these in combination
+//! with [`pin_init!`].
+//!
+//! For more information on how to use [`pin_init_from_closure()`], take a look at the uses inside
+//! the `kernel` crate. The [`sync`] module is a good starting point.
+//!
//! [`sync`]: kernel::sync
//! [pinning]: https://doc.rust-lang.org/std/pin/index.html
//! [structurally pinned fields]:
@@ -187,6 +195,7 @@
//! [`impl PinInit<T, E>`]: PinInit
//! [`impl Init<T, E>`]: Init
//! [`Opaque`]: kernel::types::Opaque
+//! [`Opaque::ffi_init`]: kernel::types::Opaque::ffi_init
//! [`pin_data`]: ::macros::pin_data
use crate::{
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index ff2b2fac951d..a4b1e3778da7 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -2,6 +2,7 @@
//! Kernel types.
+use crate::init::{self, PinInit};
use alloc::boxed::Box;
use core::{
cell::UnsafeCell,
@@ -234,6 +235,25 @@ impl<T> Opaque<T> {
Self(MaybeUninit::uninit())
}
+ /// Creates a pin-initializer from the given initializer closure.
+ ///
+ /// The returned initializer calls the given closure with the pointer to the inner `T` of this
+ /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it.
+ ///
+ /// This function is safe, because the `T` inside of an `Opaque` is allowed to be
+ /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs
+ /// to verify at that point that the inner value is valid.
+ pub fn ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self> {
+ // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully
+ // initialize the `T`.
+ unsafe {
+ init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| {
+ init_func(Self::raw_get(slot));
+ Ok(())
+ })
+ }
+ }
+
/// Returns a raw pointer to the opaque data.
pub fn get(&self) -> *mut T {
UnsafeCell::raw_get(self.0.as_ptr())