1 // SPDX-License-Identifier: GPL-2.0 2 3 //! Kernel types. 4 5 use crate::ffi::c_void; 6 use core::{ 7 cell::UnsafeCell, 8 marker::{PhantomData, PhantomPinned}, 9 mem::MaybeUninit, 10 ops::{Deref, DerefMut}, 11 }; 12 use pin_init::{PinInit, Wrapper, Zeroable}; 13 14 pub use crate::sync::aref::{ARef, AlwaysRefCounted}; 15 16 /// Used to transfer ownership to and from foreign (non-Rust) languages. 17 /// 18 /// Ownership is transferred from Rust to a foreign language by calling [`Self::into_foreign`] and 19 /// later may be transferred back to Rust by calling [`Self::from_foreign`]. 20 /// 21 /// This trait is meant to be used in cases when Rust objects are stored in C objects and 22 /// eventually "freed" back to Rust. 23 /// 24 /// # Safety 25 /// 26 /// - Implementations must satisfy the guarantees of [`Self::into_foreign`]. 27 pub unsafe trait ForeignOwnable: Sized { 28 /// The alignment of pointers returned by `into_foreign`. 29 const FOREIGN_ALIGN: usize; 30 31 /// Type used to immutably borrow a value that is currently foreign-owned. 32 type Borrowed<'a>; 33 34 /// Type used to mutably borrow a value that is currently foreign-owned. 35 type BorrowedMut<'a>; 36 37 /// Converts a Rust-owned object to a foreign-owned one. 38 /// 39 /// The foreign representation is a pointer to void. Aside from the guarantees listed below, 40 /// there are no other guarantees for this pointer. For example, it might be invalid, dangling 41 /// or pointing to uninitialized memory. Using it in any way except for [`from_foreign`], 42 /// [`try_from_foreign`], [`borrow`], or [`borrow_mut`] can result in undefined behavior. 43 /// 44 /// # Guarantees 45 /// 46 /// - Minimum alignment of returned pointer is [`Self::FOREIGN_ALIGN`]. 47 /// - The returned pointer is not null. 48 /// 49 /// [`from_foreign`]: Self::from_foreign 50 /// [`try_from_foreign`]: Self::try_from_foreign 51 /// [`borrow`]: Self::borrow 52 /// [`borrow_mut`]: Self::borrow_mut into_foreign(self) -> *mut c_void53 fn into_foreign(self) -> *mut c_void; 54 55 /// Converts a foreign-owned object back to a Rust-owned one. 56 /// 57 /// # Safety 58 /// 59 /// The provided pointer must have been returned by a previous call to [`into_foreign`], and it 60 /// must not be passed to `from_foreign` more than once. 61 /// 62 /// [`into_foreign`]: Self::into_foreign from_foreign(ptr: *mut c_void) -> Self63 unsafe fn from_foreign(ptr: *mut c_void) -> Self; 64 65 /// Tries to convert a foreign-owned object back to a Rust-owned one. 66 /// 67 /// A convenience wrapper over [`ForeignOwnable::from_foreign`] that returns [`None`] if `ptr` 68 /// is null. 69 /// 70 /// # Safety 71 /// 72 /// `ptr` must either be null or satisfy the safety requirements for [`from_foreign`]. 73 /// 74 /// [`from_foreign`]: Self::from_foreign try_from_foreign(ptr: *mut c_void) -> Option<Self>75 unsafe fn try_from_foreign(ptr: *mut c_void) -> Option<Self> { 76 if ptr.is_null() { 77 None 78 } else { 79 // SAFETY: Since `ptr` is not null here, then `ptr` satisfies the safety requirements 80 // of `from_foreign` given the safety requirements of this function. 81 unsafe { Some(Self::from_foreign(ptr)) } 82 } 83 } 84 85 /// Borrows a foreign-owned object immutably. 86 /// 87 /// This method provides a way to access a foreign-owned value from Rust immutably. It provides 88 /// you with exactly the same abilities as an `&Self` when the value is Rust-owned. 89 /// 90 /// # Safety 91 /// 92 /// The provided pointer must have been returned by a previous call to [`into_foreign`], and if 93 /// the pointer is ever passed to [`from_foreign`], then that call must happen after the end of 94 /// the lifetime `'a`. 95 /// 96 /// [`into_foreign`]: Self::into_foreign 97 /// [`from_foreign`]: Self::from_foreign borrow<'a>(ptr: *mut c_void) -> Self::Borrowed<'a>98 unsafe fn borrow<'a>(ptr: *mut c_void) -> Self::Borrowed<'a>; 99 100 /// Borrows a foreign-owned object mutably. 101 /// 102 /// This method provides a way to access a foreign-owned value from Rust mutably. It provides 103 /// you with exactly the same abilities as an `&mut Self` when the value is Rust-owned, except 104 /// that the address of the object must not be changed. 105 /// 106 /// Note that for types like [`Arc`], an `&mut Arc<T>` only gives you immutable access to the 107 /// inner value, so this method also only provides immutable access in that case. 108 /// 109 /// In the case of `Box<T>`, this method gives you the ability to modify the inner `T`, but it 110 /// does not let you change the box itself. That is, you cannot change which allocation the box 111 /// points at. 112 /// 113 /// # Safety 114 /// 115 /// The provided pointer must have been returned by a previous call to [`into_foreign`], and if 116 /// the pointer is ever passed to [`from_foreign`], then that call must happen after the end of 117 /// the lifetime `'a`. 118 /// 119 /// The lifetime `'a` must not overlap with the lifetime of any other call to [`borrow`] or 120 /// `borrow_mut` on the same object. 121 /// 122 /// [`into_foreign`]: Self::into_foreign 123 /// [`from_foreign`]: Self::from_foreign 124 /// [`borrow`]: Self::borrow 125 /// [`Arc`]: crate::sync::Arc borrow_mut<'a>(ptr: *mut c_void) -> Self::BorrowedMut<'a>126 unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> Self::BorrowedMut<'a>; 127 } 128 129 // SAFETY: The pointer returned by `into_foreign` comes from a well aligned 130 // pointer to `()`. 131 unsafe impl ForeignOwnable for () { 132 const FOREIGN_ALIGN: usize = core::mem::align_of::<()>(); 133 type Borrowed<'a> = (); 134 type BorrowedMut<'a> = (); 135 into_foreign(self) -> *mut c_void136 fn into_foreign(self) -> *mut c_void { 137 core::ptr::NonNull::dangling().as_ptr() 138 } 139 from_foreign(_: *mut c_void) -> Self140 unsafe fn from_foreign(_: *mut c_void) -> Self {} 141 borrow<'a>(_: *mut c_void) -> Self::Borrowed<'a>142 unsafe fn borrow<'a>(_: *mut c_void) -> Self::Borrowed<'a> {} borrow_mut<'a>(_: *mut c_void) -> Self::BorrowedMut<'a>143 unsafe fn borrow_mut<'a>(_: *mut c_void) -> Self::BorrowedMut<'a> {} 144 } 145 146 /// Runs a cleanup function/closure when dropped. 147 /// 148 /// The [`ScopeGuard::dismiss`] function prevents the cleanup function from running. 149 /// 150 /// # Examples 151 /// 152 /// In the example below, we have multiple exit paths and we want to log regardless of which one is 153 /// taken: 154 /// 155 /// ``` 156 /// # use kernel::types::ScopeGuard; 157 /// fn example1(arg: bool) { 158 /// let _log = ScopeGuard::new(|| pr_info!("example1 completed\n")); 159 /// 160 /// if arg { 161 /// return; 162 /// } 163 /// 164 /// pr_info!("Do something...\n"); 165 /// } 166 /// 167 /// # example1(false); 168 /// # example1(true); 169 /// ``` 170 /// 171 /// In the example below, we want to log the same message on all early exits but a different one on 172 /// the main exit path: 173 /// 174 /// ``` 175 /// # use kernel::types::ScopeGuard; 176 /// fn example2(arg: bool) { 177 /// let log = ScopeGuard::new(|| pr_info!("example2 returned early\n")); 178 /// 179 /// if arg { 180 /// return; 181 /// } 182 /// 183 /// // (Other early returns...) 184 /// 185 /// log.dismiss(); 186 /// pr_info!("example2 no early return\n"); 187 /// } 188 /// 189 /// # example2(false); 190 /// # example2(true); 191 /// ``` 192 /// 193 /// In the example below, we need a mutable object (the vector) to be accessible within the log 194 /// function, so we wrap it in the [`ScopeGuard`]: 195 /// 196 /// ``` 197 /// # use kernel::types::ScopeGuard; 198 /// fn example3(arg: bool) -> Result { 199 /// let mut vec = 200 /// ScopeGuard::new_with_data(KVec::new(), |v| pr_info!("vec had {} elements\n", v.len())); 201 /// 202 /// vec.push(10u8, GFP_KERNEL)?; 203 /// if arg { 204 /// return Ok(()); 205 /// } 206 /// vec.push(20u8, GFP_KERNEL)?; 207 /// Ok(()) 208 /// } 209 /// 210 /// # assert_eq!(example3(false), Ok(())); 211 /// # assert_eq!(example3(true), Ok(())); 212 /// ``` 213 /// 214 /// # Invariants 215 /// 216 /// The value stored in the struct is nearly always `Some(_)`, except between 217 /// [`ScopeGuard::dismiss`] and [`ScopeGuard::drop`]: in this case, it will be `None` as the value 218 /// will have been returned to the caller. Since [`ScopeGuard::dismiss`] consumes the guard, 219 /// callers won't be able to use it anymore. 220 pub struct ScopeGuard<T, F: FnOnce(T)>(Option<(T, F)>); 221 222 impl<T, F: FnOnce(T)> ScopeGuard<T, F> { 223 /// Creates a new guarded object wrapping the given data and with the given cleanup function. new_with_data(data: T, cleanup_func: F) -> Self224 pub fn new_with_data(data: T, cleanup_func: F) -> Self { 225 // INVARIANT: The struct is being initialised with `Some(_)`. 226 Self(Some((data, cleanup_func))) 227 } 228 229 /// Prevents the cleanup function from running and returns the guarded data. dismiss(mut self) -> T230 pub fn dismiss(mut self) -> T { 231 // INVARIANT: This is the exception case in the invariant; it is not visible to callers 232 // because this function consumes `self`. 233 self.0.take().unwrap().0 234 } 235 } 236 237 impl ScopeGuard<(), fn(())> { 238 /// Creates a new guarded object with the given cleanup function. new(cleanup: impl FnOnce()) -> ScopeGuard<(), impl FnOnce(())>239 pub fn new(cleanup: impl FnOnce()) -> ScopeGuard<(), impl FnOnce(())> { 240 ScopeGuard::new_with_data((), move |()| cleanup()) 241 } 242 } 243 244 impl<T, F: FnOnce(T)> Deref for ScopeGuard<T, F> { 245 type Target = T; 246 deref(&self) -> &T247 fn deref(&self) -> &T { 248 // The type invariants guarantee that `unwrap` will succeed. 249 &self.0.as_ref().unwrap().0 250 } 251 } 252 253 impl<T, F: FnOnce(T)> DerefMut for ScopeGuard<T, F> { deref_mut(&mut self) -> &mut T254 fn deref_mut(&mut self) -> &mut T { 255 // The type invariants guarantee that `unwrap` will succeed. 256 &mut self.0.as_mut().unwrap().0 257 } 258 } 259 260 impl<T, F: FnOnce(T)> Drop for ScopeGuard<T, F> { drop(&mut self)261 fn drop(&mut self) { 262 // Run the cleanup function if one is still present. 263 if let Some((data, cleanup)) = self.0.take() { 264 cleanup(data) 265 } 266 } 267 } 268 269 /// Stores an opaque value. 270 /// 271 /// [`Opaque<T>`] is meant to be used with FFI objects that are never interpreted by Rust code. 272 /// 273 /// It is used to wrap structs from the C side, like for example `Opaque<bindings::mutex>`. 274 /// It gets rid of all the usual assumptions that Rust has for a value: 275 /// 276 /// * The value is allowed to be uninitialized (for example have invalid bit patterns: `3` for a 277 /// [`bool`]). 278 /// * The value is allowed to be mutated, when a `&Opaque<T>` exists on the Rust side. 279 /// * No uniqueness for mutable references: it is fine to have multiple `&mut Opaque<T>` point to 280 /// the same value. 281 /// * The value is not allowed to be shared with other threads (i.e. it is `!Sync`). 282 /// 283 /// This has to be used for all values that the C side has access to, because it can't be ensured 284 /// that the C side is adhering to the usual constraints that Rust needs. 285 /// 286 /// Using [`Opaque<T>`] allows to continue to use references on the Rust side even for values shared 287 /// with C. 288 /// 289 /// # Examples 290 /// 291 /// ``` 292 /// use kernel::types::Opaque; 293 /// # // Emulate a C struct binding which is from C, maybe uninitialized or not, only the C side 294 /// # // knows. 295 /// # mod bindings { 296 /// # pub struct Foo { 297 /// # pub val: u8, 298 /// # } 299 /// # } 300 /// 301 /// // `foo.val` is assumed to be handled on the C side, so we use `Opaque` to wrap it. 302 /// pub struct Foo { 303 /// foo: Opaque<bindings::Foo>, 304 /// } 305 /// 306 /// impl Foo { 307 /// pub fn get_val(&self) -> u8 { 308 /// let ptr = Opaque::get(&self.foo); 309 /// 310 /// // SAFETY: `Self` is valid from C side. 311 /// unsafe { (*ptr).val } 312 /// } 313 /// } 314 /// 315 /// // Create an instance of `Foo` with the `Opaque` wrapper. 316 /// let foo = Foo { 317 /// foo: Opaque::new(bindings::Foo { val: 0xdb }), 318 /// }; 319 /// 320 /// assert_eq!(foo.get_val(), 0xdb); 321 /// ``` 322 #[repr(transparent)] 323 pub struct Opaque<T> { 324 value: UnsafeCell<MaybeUninit<T>>, 325 _pin: PhantomPinned, 326 } 327 328 // SAFETY: `Opaque<T>` allows the inner value to be any bit pattern, including all zeros. 329 unsafe impl<T> Zeroable for Opaque<T> {} 330 331 impl<T> Opaque<T> { 332 /// Creates a new opaque value. new(value: T) -> Self333 pub const fn new(value: T) -> Self { 334 Self { 335 value: UnsafeCell::new(MaybeUninit::new(value)), 336 _pin: PhantomPinned, 337 } 338 } 339 340 /// Creates an uninitialised value. uninit() -> Self341 pub const fn uninit() -> Self { 342 Self { 343 value: UnsafeCell::new(MaybeUninit::uninit()), 344 _pin: PhantomPinned, 345 } 346 } 347 348 /// Creates a new zeroed opaque value. zeroed() -> Self349 pub const fn zeroed() -> Self { 350 Self { 351 value: UnsafeCell::new(MaybeUninit::zeroed()), 352 _pin: PhantomPinned, 353 } 354 } 355 356 /// Creates a pin-initializer from the given initializer closure. 357 /// 358 /// The returned initializer calls the given closure with the pointer to the inner `T` of this 359 /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it. 360 /// 361 /// This function is safe, because the `T` inside of an `Opaque` is allowed to be 362 /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs 363 /// to verify at that point that the inner value is valid. ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self>364 pub fn ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self> { 365 // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully 366 // initialize the `T`. 367 unsafe { 368 pin_init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| { 369 init_func(Self::cast_into(slot)); 370 Ok(()) 371 }) 372 } 373 } 374 375 /// Creates a fallible pin-initializer from the given initializer closure. 376 /// 377 /// The returned initializer calls the given closure with the pointer to the inner `T` of this 378 /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it. 379 /// 380 /// This function is safe, because the `T` inside of an `Opaque` is allowed to be 381 /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs 382 /// to verify at that point that the inner value is valid. try_ffi_init<E>( init_func: impl FnOnce(*mut T) -> Result<(), E>, ) -> impl PinInit<Self, E>383 pub fn try_ffi_init<E>( 384 init_func: impl FnOnce(*mut T) -> Result<(), E>, 385 ) -> impl PinInit<Self, E> { 386 // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully 387 // initialize the `T`. 388 unsafe { 389 pin_init::pin_init_from_closure::<_, E>(move |slot| init_func(Self::cast_into(slot))) 390 } 391 } 392 393 /// Returns a raw pointer to the opaque data. get(&self) -> *mut T394 pub const fn get(&self) -> *mut T { 395 UnsafeCell::get(&self.value).cast::<T>() 396 } 397 398 /// Gets the value behind `this`. 399 /// 400 /// This function is useful to get access to the value without creating intermediate 401 /// references. cast_into(this: *const Self) -> *mut T402 pub const fn cast_into(this: *const Self) -> *mut T { 403 UnsafeCell::raw_get(this.cast::<UnsafeCell<MaybeUninit<T>>>()).cast::<T>() 404 } 405 406 /// The opposite operation of [`Opaque::cast_into`]. cast_from(this: *const T) -> *const Self407 pub const fn cast_from(this: *const T) -> *const Self { 408 this.cast() 409 } 410 } 411 412 impl<T> Wrapper<T> for Opaque<T> { 413 /// Create an opaque pin-initializer from the given pin-initializer. pin_init<E>(slot: impl PinInit<T, E>) -> impl PinInit<Self, E>414 fn pin_init<E>(slot: impl PinInit<T, E>) -> impl PinInit<Self, E> { 415 Self::try_ffi_init(|ptr: *mut T| { 416 // SAFETY: 417 // - `ptr` is a valid pointer to uninitialized memory, 418 // - `slot` is not accessed on error, 419 // - `slot` is pinned in memory. 420 unsafe { PinInit::<T, E>::__pinned_init(slot, ptr) } 421 }) 422 } 423 } 424 425 /// Zero-sized type to mark types not [`Send`]. 426 /// 427 /// Add this type as a field to your struct if your type should not be sent to a different task. 428 /// Since [`Send`] is an auto trait, adding a single field that is `!Send` will ensure that the 429 /// whole type is `!Send`. 430 /// 431 /// If a type is `!Send` it is impossible to give control over an instance of the type to another 432 /// task. This is useful to include in types that store or reference task-local information. A file 433 /// descriptor is an example of such task-local information. 434 /// 435 /// This type also makes the type `!Sync`, which prevents immutable access to the value from 436 /// several threads in parallel. 437 pub type NotThreadSafe = PhantomData<*mut ()>; 438 439 /// Used to construct instances of type [`NotThreadSafe`] similar to how `PhantomData` is 440 /// constructed. 441 /// 442 /// [`NotThreadSafe`]: type@NotThreadSafe 443 #[allow(non_upper_case_globals)] 444 pub const NotThreadSafe: NotThreadSafe = PhantomData; 445