rust/kernel/init.rs

1 // SPDX-License-Identifier: GPL-2.0
3 //! Extensions to the [`pin-init`] crate.
5 //! Most `struct`s from the [`sync`] module need to be pinned, because they contain self-referential
8 //! The [`pin-init`] crate is the way such structs are initialized on the Rust side. Please refer
14 //! [pinning]: https://doc.rust-lang.org/std/pin/index.html
15 //! [`pin-init`]: https://rust.docs.kernel.org/pin_init/
19 //! For the special case where initializing a field is a single FFI-function call that cannot fail,
20 //! there exist the helper function [`Opaque::ffi_init`]. This function initialize a single
57 //!     raw <- unsafe {
78 //! #     pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 }
82 //! #     fn from_errno(errno: core::ffi::c_int) -> Error {
100 //!     pub fn new(flags: u32) -> impl PinInit<Self, Error> {
102 //!         // - when the closure returns `Ok(())`, then it has successfully initialized and
104 //!         // - when it returns `Err(e)`, then it has cleaned up before
143 /// Smart pointer that can initialize memory in-place.
151     /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this
155     fn try_pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Self::PinnedSelf, E>  in try_pin_init()
159     /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this
163     fn pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> error::Result<Self::PinnedSelf>  in pin_init()
174     /// Use the given initializer to in-place initialize a `T`.
175     fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>  in try_init()
179     /// Use the given initializer to in-place initialize a `T`.
180     fn init<E>(init: impl Init<T, E>, flags: Flags) -> error::Result<Self>  in init()
192 /// Construct an in-place fallible initializer for `struct`s.
200 /// - `unsafe` code must guarantee either full initialization or return an error and allow
202 /// - the fields are initialized in the order given in the initializer.
203 /// - no references to fields are allowed to be created inside of the initializer.
216 ///     fn new() -> impl Init<Self, Error> {
232         $($fields:tt)*
239         $($fields:tt)*
247 /// Construct an in-place, fallible pinned initializer for `struct`s.
276 ///     fn new() -> impl PinInit<Self, Error> {
292         $($fields:tt)*
299         $($fields:tt)*