rust: init: add `PinnedDrop` trait and macros
Subsystems (2)
PATCH v4 9/15 rust: init: add `PinnedDrop` trait and macros
From: Benno Lossin <[email protected]>
The PinnedDrop trait that facilitates destruction of pinned types. It has to be implemented via the #[pinned_drop] macro, since the drop function should not be called by normal code, only by other destructors. It also only works on structs that are annotated with #[pin_data(PinnedDrop)].
Co-developed-by Gary Guo <[email protected]>
Signed-off-by Gary Guo <[email protected]>
Signed-off-by Benno Lossin <[email protected]>
Cc Alice Ryhl <[email protected]>
Cc Andreas Hindborg <[email protected]>
--- rust/kernel/init.rs | 111 ++++++++++++++ rust/kernel/init/__internal.rs | 15 ++ rust/kernel/init/macros.rs | 264 +++++++++++++++++++++++++++++++++ rust/macros/lib.rs | 49 ++++++ rust/macros/pinned_drop.rs | 49 ++++++ 5 files changed, 488 insertions(+) create mode 100644 rust/macros/pinned_drop.rs
rust/kernel/init.rs +111 -0
@@ -104,6 +104,78 @@//! } //! ``` //! +//! ## Manual creation of an initializer +//! +//! Often when working with primitives the previous approaches are not sufficient. That is where +//! [`pin_init_from_closure()`] comes in. This `unsafe` function allows you to create a +//! [`impl PinInit<T, E>`] directly from a closure. Of course you have to ensure that the closure +//! actually does the initialization in the correct way. Here are the things to look out for +//! (we are calling the parameter to the closure `slot`): +//! - when the closure returns `Ok(())`, then it has completed the initialization successfully, so +//! `slot` now contains a valid bit pattern for the type `T`, +//! - when the closure returns `Err(e)`, then the caller may deallocate the memory at `slot`, so +//! you need to take care to clean up anything if your initialization fails mid-way, +//! - you may assume that `slot` will stay pinned even after the closure returns until `drop` of +//! `slot` gets called. +//! +//! ```rust +//! use kernel::{prelude::*, init}; +//! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin}; +//! # mod bindings { +//! # pub struct foo; +//! # pub unsafe fn init_foo(_ptr: *mut foo) {} +//! # pub unsafe fn destroy_foo(_ptr: *mut foo) {} +//! # pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 } +//! # } +//! /// # Invariants +//! /// +//! /// `foo` is always initialized +//! #[pin_data(PinnedDrop)] +//! pub struct RawFoo { +//! #[pin] +//! foo: Opaque<bindings::foo>, +//! #[pin] +//! _p: PhantomPinned, +//! } +//! +//! impl RawFoo { +//! pub fn new(flags: u32) -> impl PinInit<Self, Error> { +//! // SAFETY: +//! // - when the closure returns `Ok(())`, then it has successfully initialized and +//! // enabled `foo`, +//! // - when it returns `Err(e)`, then it has cleaned up before +//! unsafe { +//! init::pin_init_from_closure(move |slot: *mut Self| { +//! // `slot` contains uninit memory, avoid creating a reference. +//! let foo = addr_of_mut!((*slot).foo); +//! +//! // Initialize the `foo` +//! bindings::init_foo(Opaque::raw_get(foo)); +//! +//! // Try to enable it. +//! let err = bindings::enable_foo(Opaque::raw_get(foo), flags); +//! if err != 0 { +//! // Enabling has failed, first clean up the foo and then return the error. +//! bindings::destroy_foo(Opaque::raw_get(foo)); +//! return Err(Error::from_kernel_errno(err)); +//! } +//! +//! // All fields of `RawFoo` have been initialized, since `_p` is a ZST. +//! Ok(()) +//! }) +//! } +//! } +//! } +//! +//! #[pinned_drop] +//! impl PinnedDrop for RawFoo { +//! fn drop(self: Pin<&mut Self>) { +//! // SAFETY: Since `foo` is initialized, destroying is safe. +//! unsafe { bindings::destroy_foo(self.foo.get()) }; +//! } +//! } +//! ``` +//! //! [`sync`]: kernel::sync //! [pinning]: https://doc.rust-lang.org/std/pin/index.html //! [structurally pinned fields]:
@@ -1083,3 +1155,42 @@ impl<T> InPlaceInit<T> for UniqueArc<T> {Ok (unsafe { this.assume_init () }) } } + +/// Trait facilitating pinned destruction. +/// +/// Use [`pinned_drop`] to implement this trait safely: +/// +/// ```rust +/// # use kernel::sync::Mutex; +/// use kernel::macros::pinned_drop; +/// use core::pin::Pin; +/// #[pin_data(PinnedDrop)] +/// struct Foo { +/// #[pin] +/// mtx: Mutex<usize>, +/// } +/// +/// #[pinned_drop] +/// impl PinnedDrop for Foo { +/// fn drop(self: Pin<&mut Self>) { +/// pr_info!("Foo is being dropped!"); +/// } +/// } +/// ``` +/// +/// # Safety +/// +/// This trait must be implemented via the [`pinned_drop`] proc-macro attribute on the impl. +/// +/// [`pinned_drop`]: kernel::macros::pinned_drop +pub unsafe trait PinnedDrop : __internal::HasPinData { +/// Executes the pinned destructor of this type. +/// +/// While this function is marked safe, it is actually unsafe to call it manually. For this +/// reason it takes an additional parameter. This type can only be constructed by `unsafe` code +/// and thus prevents this function from being called where it should not. +/// +/// This extra parameter will be generated by the `#[pinned_drop]` proc-macro attribute +/// automatically. +fn drop (self:Pin <&mut Self >, only_call_from_drop: __internal::OnlyCallFromDrop ); +}
rust/kernel/init/__internal.rs +15 -0
@@ -167,3 +167,18 @@ impl<T: ?Sized> Drop for DropGuard<T> { } } } + +/// Token used by `PinnedDrop` to prevent calling the function without creating this unsafely +/// created struct. This is needed, because the `drop` function is safe, but should not be called +/// manually. +pub struct OnlyCallFromDrop (()); + +impl OnlyCallFromDrop { +/// # Safety +/// +/// This function should only be called from the [`Drop::drop`] function and only be used to +/// delegate the destruction to the pinned destructor [`PinnedDrop::drop`] of the same type. +pub unsafe fn new () ->Self { +Self (()) + } +}
rust/kernel/init/macros.rs +264 -0
288 lines not on this page · raw message
rust/macros/lib.rs +49 -0
70 lines not on this page · raw message
rust/macros/pinned_drop.rs new file +49 -0
49 lines not on this page · raw message
--
2.39.2