Commit 692e8935 authored by Benno Lossin's avatar Benno Lossin Committed by Miguel Ojeda
Browse files

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: default avatarGary Guo <gary@garyguo.net>
Signed-off-by: default avatarGary Guo <gary@garyguo.net>
Signed-off-by: default avatarBenno Lossin <benno.lossin@proton.me>
Reviewed-by: default avatarAndreas Hindborg <a.hindborg@samsung.com>
Reviewed-by: default avatarAlice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20230408122429.1103522-14-y86-dev@protonmail.com


[ Fixed typo. ]
Signed-off-by: default avatarMiguel Ojeda <ojeda@kernel.org>
parent 8586f1ac

rust/kernel/init.rs

+9 −0
Original line number Diff line number Diff line
@@ -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::{

rust/kernel/types.rs

+20 −0
Original line number Diff line number Diff line
@@ -2,6 +2,7 @@ 


//! Kernel types.



use crate::init::{self, PinInit};

use alloc::boxed::Box;

use core::{

    cell::UnsafeCell,
@@ -234,6 +235,25 @@ pub const fn uninit() -> Self { 
        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())