[v6,13/15] rust: types: add common init-helper functions for `Opaque`
Commit Message
Add helper functions to more easily initialize `Opaque<T>` via FFI and
rust raw initializer functions.
These functions take a function pointer to the FFI/raw initialization
function and take between 0-4 other arguments. It then returns an
initializer that uses the FFI/raw initialization function along with the
given arguments to initialize an `Opaque<T>`.
Signed-off-by: Benno Lossin <y86-dev@protonmail.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com>
Cc: Gary Guo <gary@garyguo.net>
---
rust/kernel/init.rs | 9 +++++++++
rust/kernel/types.rs | 47 ++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 56 insertions(+)
--
2.39.2
Comments
On Wed, 05 Apr 2023 19:36:46 +0000
Benno Lossin <y86-dev@protonmail.com> wrote:
> Add helper functions to more easily initialize `Opaque<T>` via FFI and
> rust raw initializer functions.
> These functions take a function pointer to the FFI/raw initialization
> function and take between 0-4 other arguments. It then returns an
> initializer that uses the FFI/raw initialization function along with the
> given arguments to initialize an `Opaque<T>`.
>
> Signed-off-by: Benno Lossin <y86-dev@protonmail.com>
> Reviewed-by: Alice Ryhl <aliceryhl@google.com>
> Reviewed-by: Andreas Hindborg <a.hindborg@samsung.com>
> Cc: Gary Guo <gary@garyguo.net>
> ---
> rust/kernel/init.rs | 9 +++++++++
> rust/kernel/types.rs | 47 ++++++++++++++++++++++++++++++++++++++++++++
> 2 files changed, 56 insertions(+)
>
> diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
> index ffd539e2f5ef..a501fb823ae9 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 helper functions [`Opaque::ffi_init`]. These functions initialize a single
> +//! [`Opaque`] field by just delegating to the FFI-function. 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..dbfae9bb97ce 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,
> @@ -248,6 +249,52 @@ impl<T> Opaque<T> {
> }
> }
>
> +macro_rules! opaque_init_funcs {
> + ($($abi:literal $name:ident($($arg_name:ident: $arg_typ:ident),*);)*) => {
> + impl<T> Opaque<T> {
> + $(
> + /// Create an initializer using the given initializer function.
> + ///
> + /// # Safety
> + ///
> + /// The given function **must** under all circumstances initialize the memory
> + /// location to a valid `T`. If it fails to do so it results in UB.
> + ///
> + /// If any parameters are given, those need to be valid for the function. Valid
> + /// means that calling the function with those parameters complies with the above
> + /// requirement **and** every other requirement on the function itself.
> + pub unsafe fn $name<$($arg_typ),*>(
> + init_func: unsafe extern $abi fn(*mut T $(, $arg_typ)*),
> + $($arg_name: $arg_typ,)*
> + ) -> impl PinInit<Self> {
> + // SAFETY: The safety contract of this function ensures that `init_func` fully
> + // initializes `slot`.
> + unsafe {
> + init::pin_init_from_closure(move |slot| {
> + init_func(Self::raw_get(slot) $(, $arg_name)*);
> + Ok(())
> + })
> + }
> + }
> + )*
> + }
> + }
> +}
I personally don't like the fact that this is using function pointers,
as that generally causes a difficulty for static analysis tools.
How useful would this helper be?
unsafe {
Opaque::ffi_init2(
bindings::__init_waitqueue_head,
name.as_char_ptr(),
key.as_ptr(),
)
}
doesn't save much from
unsafe {
init::pin_init_from_closure(move |slot| {
bindings::__init_waitqueue_head(
Opaque::raw_get(slot),
name.as_char_ptr(),
key.as_ptr(),
)
)
}
> +
> +opaque_init_funcs! {
> + "C" ffi_init();
> + "C" ffi_init1(arg1: A1);
> + "C" ffi_init2(arg1: A1, arg2: A2);
> + "C" ffi_init3(arg1: A1, arg2: A2, arg3: A3);
> + "C" ffi_init4(arg1: A1, arg2: A2, arg3: A3, arg4: A4);
> +
> + "Rust" manual_init();
> + "Rust" manual_init1(arg1: A1);
> + "Rust" manual_init2(arg1: A1, arg2: A2);
> + "Rust" manual_init3(arg1: A1, arg2: A2, arg3: A3);
> + "Rust" manual_init4(arg1: A1, arg2: A2, arg3: A3, arg4: A4);
> +}
> +
> /// A sum type that always holds either a value of type `L` or `R`.
> pub enum Either<L, R> {
> /// Constructs an instance of [`Either`] containing a value of type `L`.
> --
> 2.39.2
>
>
@@ -177,6 +177,14 @@
//! }
//! ```
//!
+//! For the special case where initializing a field is a single FFI-function call that cannot fail,
+//! there exist helper functions [`Opaque::ffi_init`]. These functions initialize a single
+//! [`Opaque`] field by just delegating to the FFI-function. 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::{
@@ -2,6 +2,7 @@
//! Kernel types.
+use crate::init::{self, PinInit};
use alloc::boxed::Box;
use core::{
cell::UnsafeCell,
@@ -248,6 +249,52 @@ impl<T> Opaque<T> {
}
}
+macro_rules! opaque_init_funcs {
+ ($($abi:literal $name:ident($($arg_name:ident: $arg_typ:ident),*);)*) => {
+ impl<T> Opaque<T> {
+ $(
+ /// Create an initializer using the given initializer function.
+ ///
+ /// # Safety
+ ///
+ /// The given function **must** under all circumstances initialize the memory
+ /// location to a valid `T`. If it fails to do so it results in UB.
+ ///
+ /// If any parameters are given, those need to be valid for the function. Valid
+ /// means that calling the function with those parameters complies with the above
+ /// requirement **and** every other requirement on the function itself.
+ pub unsafe fn $name<$($arg_typ),*>(
+ init_func: unsafe extern $abi fn(*mut T $(, $arg_typ)*),
+ $($arg_name: $arg_typ,)*
+ ) -> impl PinInit<Self> {
+ // SAFETY: The safety contract of this function ensures that `init_func` fully
+ // initializes `slot`.
+ unsafe {
+ init::pin_init_from_closure(move |slot| {
+ init_func(Self::raw_get(slot) $(, $arg_name)*);
+ Ok(())
+ })
+ }
+ }
+ )*
+ }
+ }
+}
+
+opaque_init_funcs! {
+ "C" ffi_init();
+ "C" ffi_init1(arg1: A1);
+ "C" ffi_init2(arg1: A1, arg2: A2);
+ "C" ffi_init3(arg1: A1, arg2: A2, arg3: A3);
+ "C" ffi_init4(arg1: A1, arg2: A2, arg3: A3, arg4: A4);
+
+ "Rust" manual_init();
+ "Rust" manual_init1(arg1: A1);
+ "Rust" manual_init2(arg1: A1, arg2: A2);
+ "Rust" manual_init3(arg1: A1, arg2: A2, arg3: A3);
+ "Rust" manual_init4(arg1: A1, arg2: A2, arg3: A3, arg4: A4);
+}
+
/// A sum type that always holds either a value of type `L` or `R`.
pub enum Either<L, R> {
/// Constructs an instance of [`Either`] containing a value of type `L`.