1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Extensions to the [`pin-init`] crate. 4 //! 5 //! Most `struct`s from the [`sync`] module need to be pinned, because they contain self-referential 6 //! `struct`s from C. [Pinning][pinning] is Rust's way of ensuring data does not move. 7 //! 8 //! The [`pin-init`] crate is the way such structs are initialized on the Rust side. Please refer 9 //! to its documentation to better understand how to use it. Additionally, there are many examples 10 //! throughout the kernel, such as the types from the [`sync`] module. And the ones presented 11 //! below. 12 //! 13 //! [`sync`]: crate::sync 14 //! [pinning]: https://doc.rust-lang.org/std/pin/index.html 15 //! [`pin-init`]: https://rust.docs.kernel.org/pin_init/ 16 //! 17 //! # [`Opaque<T>`] 18 //! 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 21 //! [`Opaque<T>`] field by just delegating to the supplied closure. You can use these in 22 //! combination with [`pin_init!`]. 23 //! 24 //! [`Opaque<T>`]: crate::types::Opaque 25 //! [`Opaque::ffi_init`]: crate::types::Opaque::ffi_init 26 //! [`pin_init!`]: pin_init::pin_init 27 //! 28 //! # Examples 29 //! 30 //! ## General Examples 31 //! 32 //! ```rust 33 //! # #![expect(clippy::undocumented_unsafe_blocks)] 34 //! use kernel::types::Opaque; 35 //! use pin_init::pin_init_from_closure; 36 //! 37 //! // assume we have some `raw_foo` type in C: 38 //! #[repr(C)] 39 //! struct RawFoo([u8; 16]); 40 //! extern "C" { 41 //! fn init_foo(_: *mut RawFoo); 42 //! } 43 //! 44 //! #[pin_data] 45 //! struct Foo { 46 //! #[pin] 47 //! raw: Opaque<RawFoo>, 48 //! } 49 //! 50 //! impl Foo { 51 //! fn setup(self: Pin<&mut Self>) { 52 //! pr_info!("Setting up foo\n"); 53 //! } 54 //! } 55 //! 56 //! let foo = pin_init!(Foo { 57 //! raw <- unsafe { 58 //! Opaque::ffi_init(|s| { 59 //! // note that this cannot fail. 60 //! init_foo(s); 61 //! }) 62 //! }, 63 //! }).pin_chain(|foo| { 64 //! foo.setup(); 65 //! Ok(()) 66 //! }); 67 //! ``` 68 //! 69 //! ```rust 70 //! use kernel::{prelude::*, types::Opaque}; 71 //! use core::{ptr::addr_of_mut, marker::PhantomPinned, pin::Pin}; 72 //! # mod bindings { 73 //! # #![expect(non_camel_case_types, clippy::missing_safety_doc)] 74 //! # pub struct foo; 75 //! # pub unsafe fn init_foo(_ptr: *mut foo) {} 76 //! # pub unsafe fn destroy_foo(_ptr: *mut foo) {} 77 //! # pub unsafe fn enable_foo(_ptr: *mut foo, _flags: u32) -> i32 { 0 } 78 //! # } 79 //! /// # Invariants 80 //! /// 81 //! /// `foo` is always initialized 82 //! #[pin_data(PinnedDrop)] 83 //! pub struct RawFoo { 84 //! #[pin] 85 //! foo: Opaque<bindings::foo>, 86 //! #[pin] 87 //! _p: PhantomPinned, 88 //! } 89 //! 90 //! impl RawFoo { 91 //! pub fn new(flags: u32) -> impl PinInit<Self, Error> { 92 //! // SAFETY: 93 //! // - when the closure returns `Ok(())`, then it has successfully initialized and 94 //! // enabled `foo`, 95 //! // - when it returns `Err(e)`, then it has cleaned up before 96 //! unsafe { 97 //! pin_init::pin_init_from_closure(move |slot: *mut Self| { 98 //! // `slot` contains uninit memory, avoid creating a reference. 99 //! let foo = addr_of_mut!((*slot).foo); 100 //! 101 //! // Initialize the `foo` 102 //! bindings::init_foo(Opaque::cast_into(foo)); 103 //! 104 //! // Try to enable it. 105 //! let err = bindings::enable_foo(Opaque::cast_into(foo), flags); 106 //! if err != 0 { 107 //! // Enabling has failed, first clean up the foo and then return the error. 108 //! bindings::destroy_foo(Opaque::cast_into(foo)); 109 //! return Err(Error::from_errno(err)); 110 //! } 111 //! 112 //! // All fields of `RawFoo` have been initialized, since `_p` is a ZST. 113 //! Ok(()) 114 //! }) 115 //! } 116 //! } 117 //! } 118 //! 119 //! #[pinned_drop] 120 //! impl PinnedDrop for RawFoo { 121 //! fn drop(self: Pin<&mut Self>) { 122 //! // SAFETY: Since `foo` is initialized, destroying is safe. 123 //! unsafe { bindings::destroy_foo(self.foo.get()) }; 124 //! } 125 //! } 126 //! ``` 127 128 use crate::{ 129 alloc::{AllocError, Flags}, 130 error::{self, Error}, 131 }; 132 use pin_init::{init_from_closure, pin_init_from_closure, Init, PinInit}; 133 134 /// Smart pointer that can initialize memory in-place. 135 pub trait InPlaceInit<T>: Sized { 136 /// Pinned version of `Self`. 137 /// 138 /// If a type already implicitly pins its pointee, `Pin<Self>` is unnecessary. In this case use 139 /// `Self`, otherwise just use `Pin<Self>`. 140 type PinnedSelf; 141 142 /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this 143 /// type. 144 /// 145 /// If `T: !Unpin` it will not be able to move afterwards. 146 fn try_pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Self::PinnedSelf, E> 147 where 148 E: From<AllocError>; 149 150 /// Use the given pin-initializer to pin-initialize a `T` inside of a new smart pointer of this 151 /// type. 152 /// 153 /// If `T: !Unpin` it will not be able to move afterwards. 154 #[inline] 155 fn pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> error::Result<Self::PinnedSelf> 156 where 157 Error: From<E>, 158 { 159 // SAFETY: We delegate to `init` and only change the error type. 160 let init = unsafe { 161 pin_init_from_closure(|slot| init.__pinned_init(slot).map_err(|e| Error::from(e))) 162 }; 163 Self::try_pin_init(init, flags) 164 } 165 166 /// Use the given initializer to in-place initialize a `T`. 167 fn try_init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E> 168 where 169 E: From<AllocError>; 170 171 /// Use the given initializer to in-place initialize a `T`. 172 #[inline] 173 fn init<E>(init: impl Init<T, E>, flags: Flags) -> error::Result<Self> 174 where 175 Error: From<E>, 176 { 177 // SAFETY: We delegate to `init` and only change the error type. 178 let init = unsafe { 179 init_from_closure(|slot| init.__pinned_init(slot).map_err(|e| Error::from(e))) 180 }; 181 Self::try_init(init, flags) 182 } 183 } 184 185 /// Construct an in-place fallible initializer for `struct`s. 186 /// 187 /// This macro defaults the error to [`Error`]. If you need [`Infallible`], then use 188 /// [`init!`]. 189 /// 190 /// The syntax is identical to [`try_pin_init!`]. If you want to specify a custom error, 191 /// append `? $type` after the `struct` initializer. 192 /// The safety caveats from [`try_pin_init!`] also apply: 193 /// - `unsafe` code must guarantee either full initialization or return an error and allow 194 /// deallocation of the memory. 195 /// - the fields are initialized in the order given in the initializer. 196 /// - no references to fields are allowed to be created inside of the initializer. 197 /// 198 /// # Examples 199 /// 200 /// ```rust 201 /// use kernel::error::Error; 202 /// use pin_init::init_zeroed; 203 /// struct BigBuf { 204 /// big: KBox<[u8; 1024 * 1024 * 1024]>, 205 /// small: [u8; 1024 * 1024], 206 /// } 207 /// 208 /// impl BigBuf { 209 /// fn new() -> impl Init<Self, Error> { 210 /// try_init!(Self { 211 /// big: KBox::init(init_zeroed(), GFP_KERNEL)?, 212 /// small: [0; 1024 * 1024], 213 /// }? Error) 214 /// } 215 /// } 216 /// ``` 217 /// 218 /// [`Infallible`]: core::convert::Infallible 219 /// [`init!`]: pin_init::init 220 /// [`try_pin_init!`]: crate::try_pin_init! 221 /// [`Error`]: crate::error::Error 222 #[macro_export] 223 macro_rules! try_init { 224 ($($args:tt)*) => { 225 ::pin_init::init!( 226 #[default_error($crate::error::Error)] 227 $($args)* 228 ) 229 } 230 } 231 232 /// Construct an in-place, fallible pinned initializer for `struct`s. 233 /// 234 /// If the initialization can complete without error (or [`Infallible`]), then use [`pin_init!`]. 235 /// 236 /// You can use the `?` operator or use `return Err(err)` inside the initializer to stop 237 /// initialization and return the error. 238 /// 239 /// IMPORTANT: if you have `unsafe` code inside of the initializer you have to ensure that when 240 /// initialization fails, the memory can be safely deallocated without any further modifications. 241 /// 242 /// This macro defaults the error to [`Error`]. 243 /// 244 /// The syntax is identical to [`pin_init!`] with the following exception: you can append `? $type` 245 /// after the `struct` initializer to specify the error type you want to use. 246 /// 247 /// # Examples 248 /// 249 /// ```rust 250 /// # #![feature(new_uninit)] 251 /// use kernel::error::Error; 252 /// use pin_init::init_zeroed; 253 /// #[pin_data] 254 /// struct BigBuf { 255 /// big: KBox<[u8; 1024 * 1024 * 1024]>, 256 /// small: [u8; 1024 * 1024], 257 /// ptr: *mut u8, 258 /// } 259 /// 260 /// impl BigBuf { 261 /// fn new() -> impl PinInit<Self, Error> { 262 /// try_pin_init!(Self { 263 /// big: KBox::init(init_zeroed(), GFP_KERNEL)?, 264 /// small: [0; 1024 * 1024], 265 /// ptr: core::ptr::null_mut(), 266 /// }? Error) 267 /// } 268 /// } 269 /// ``` 270 /// 271 /// [`Infallible`]: core::convert::Infallible 272 /// [`pin_init!`]: pin_init::pin_init 273 /// [`Error`]: crate::error::Error 274 #[macro_export] 275 macro_rules! try_pin_init { 276 ($($args:tt)*) => { 277 ::pin_init::pin_init!( 278 #[default_error($crate::error::Error)] 279 $($args)* 280 ) 281 } 282 } 283