rust/kernel/types.rs

   1 // SPDX-License-Identifier: GPL-2.0
   2
   3 //! Kernel types.
   4
   5 use crate::init::{self, PinInit};
   6 use alloc::boxed::Box;
   7 use core::{
   8     cell::UnsafeCell,
   9     marker::PhantomData,
  10     mem::MaybeUninit,
  11     ops::{Deref, DerefMut},
  12     ptr::NonNull,
  13 };
  14
  15 /// Used to transfer ownership to and from foreign (non-Rust) languages.
  16 ///
  17 /// Ownership is transferred from Rust to a foreign language by calling [`Self::into_foreign`] and
  18 /// later may be transferred back to Rust by calling [`Self::from_foreign`].
  19 ///
  20 /// This trait is meant to be used in cases when Rust objects are stored in C objects and
  21 /// eventually "freed" back to Rust.
  22 pub trait ForeignOwnable: Sized {
  23     /// Type of values borrowed between calls to [`ForeignOwnable::into_foreign`] and
  24     /// [`ForeignOwnable::from_foreign`].
  25     type Borrowed<'a>;
  26
  27     /// Converts a Rust-owned object to a foreign-owned one.
  28     ///
  29     /// The foreign representation is a pointer to void.
  30     fn into_foreign(self) -> *const core::ffi::c_void;
  31
  32     /// Borrows a foreign-owned object.
  33     ///
  34     /// # Safety
  35     ///
  36     /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
  37     /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
  38     unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>;
  39
  40     /// Converts a foreign-owned object back to a Rust-owned one.
  41     ///
  42     /// # Safety
  43     ///
  44     /// `ptr` must have been returned by a previous call to [`ForeignOwnable::into_foreign`] for
  45     /// which a previous matching [`ForeignOwnable::from_foreign`] hasn't been called yet.
  46     /// Additionally, all instances (if any) of values returned by [`ForeignOwnable::borrow`] for
  47     /// this object must have been dropped.
  48     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self;
  49 }
  50
  51 impl<T: 'static> ForeignOwnable for Box<T> {
  52     type Borrowed<'a> = &'a T;
  53
  54     fn into_foreign(self) -> *const core::ffi::c_void {
  55         Box::into_raw(self) as _
  56     }
  57
  58     unsafe fn borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T {
  59         // SAFETY: The safety requirements for this function ensure that the object is still alive,
  60         // so it is safe to dereference the raw pointer.
  61         // The safety requirements of `from_foreign` also ensure that the object remains alive for
  62         // the lifetime of the returned value.
  63         unsafe { &*ptr.cast() }
  64     }
  65
  66     unsafe fn from_foreign(ptr: *const core::ffi::c_void) -> Self {
  67         // SAFETY: The safety requirements of this function ensure that `ptr` comes from a previous
  68         // call to `Self::into_foreign`.
  69         unsafe { Box::from_raw(ptr as _) }
  70     }
  71 }
  72
  73 impl ForeignOwnable for () {
  74     type Borrowed<'a> = ();
  75
  76     fn into_foreign(self) -> *const core::ffi::c_void {
  77         core::ptr::NonNull::dangling().as_ptr()
  78     }
  79
  80     unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
  81
  82     unsafe fn from_foreign(_: *const core::ffi::c_void) -> Self {}
  83 }
  84
  85 /// Runs a cleanup function/closure when dropped.
  86 ///
  87 /// The [`ScopeGuard::dismiss`] function prevents the cleanup function from running.
  88 ///
  89 /// # Examples
  90 ///
  91 /// In the example below, we have multiple exit paths and we want to log regardless of which one is
  92 /// taken:
  93 /// ```
  94 /// # use kernel::types::ScopeGuard;
  95 /// fn example1(arg: bool) {
  96 ///     let _log = ScopeGuard::new(|| pr_info!("example1 completed\n"));
  97 ///
  98 ///     if arg {
  99 ///         return;
 100 ///     }
 101 ///
 102 ///     pr_info!("Do something...\n");
 103 /// }
 104 ///
 105 /// # example1(false);
 106 /// # example1(true);
 107 /// ```
 108 ///
 109 /// In the example below, we want to log the same message on all early exits but a different one on
 110 /// the main exit path:
 111 /// ```
 112 /// # use kernel::types::ScopeGuard;
 113 /// fn example2(arg: bool) {
 114 ///     let log = ScopeGuard::new(|| pr_info!("example2 returned early\n"));
 115 ///
 116 ///     if arg {
 117 ///         return;
 118 ///     }
 119 ///
 120 ///     // (Other early returns...)
 121 ///
 122 ///     log.dismiss();
 123 ///     pr_info!("example2 no early return\n");
 124 /// }
 125 ///
 126 /// # example2(false);
 127 /// # example2(true);
 128 /// ```
 129 ///
 130 /// In the example below, we need a mutable object (the vector) to be accessible within the log
 131 /// function, so we wrap it in the [`ScopeGuard`]:
 132 /// ```
 133 /// # use kernel::types::ScopeGuard;
 134 /// fn example3(arg: bool) -> Result {
 135 ///     let mut vec =
 136 ///         ScopeGuard::new_with_data(Vec::new(), |v| pr_info!("vec had {} elements\n", v.len()));
 137 ///
 138 ///     vec.try_push(10u8)?;
 139 ///     if arg {
 140 ///         return Ok(());
 141 ///     }
 142 ///     vec.try_push(20u8)?;
 143 ///     Ok(())
 144 /// }
 145 ///
 146 /// # assert_eq!(example3(false), Ok(()));
 147 /// # assert_eq!(example3(true), Ok(()));
 148 /// ```
 149 ///
 150 /// # Invariants
 151 ///
 152 /// The value stored in the struct is nearly always `Some(_)`, except between
 153 /// [`ScopeGuard::dismiss`] and [`ScopeGuard::drop`]: in this case, it will be `None` as the value
 154 /// will have been returned to the caller. Since  [`ScopeGuard::dismiss`] consumes the guard,
 155 /// callers won't be able to use it anymore.
 156 pub struct ScopeGuard<T, F: FnOnce(T)>(Option<(T, F)>);
 157
 158 impl<T, F: FnOnce(T)> ScopeGuard<T, F> {
 159     /// Creates a new guarded object wrapping the given data and with the given cleanup function.
 160     pub fn new_with_data(data: T, cleanup_func: F) -> Self {
 161         // INVARIANT: The struct is being initialised with `Some(_)`.
 162         Self(Some((data, cleanup_func)))
 163     }
 164
 165     /// Prevents the cleanup function from running and returns the guarded data.
 166     pub fn dismiss(mut self) -> T {
 167         // INVARIANT: This is the exception case in the invariant; it is not visible to callers
 168         // because this function consumes `self`.
 169         self.0.take().unwrap().0
 170     }
 171 }
 172
 173 impl ScopeGuard<(), fn(())> {
 174     /// Creates a new guarded object with the given cleanup function.
 175     pub fn new(cleanup: impl FnOnce()) -> ScopeGuard<(), impl FnOnce(())> {
 176         ScopeGuard::new_with_data((), move |_| cleanup())
 177     }
 178 }
 179
 180 impl<T, F: FnOnce(T)> Deref for ScopeGuard<T, F> {
 181     type Target = T;
 182
 183     fn deref(&self) -> &T {
 184         // The type invariants guarantee that `unwrap` will succeed.
 185         &self.0.as_ref().unwrap().0
 186     }
 187 }
 188
 189 impl<T, F: FnOnce(T)> DerefMut for ScopeGuard<T, F> {
 190     fn deref_mut(&mut self) -> &mut T {
 191         // The type invariants guarantee that `unwrap` will succeed.
 192         &mut self.0.as_mut().unwrap().0
 193     }
 194 }
 195
 196 impl<T, F: FnOnce(T)> Drop for ScopeGuard<T, F> {
 197     fn drop(&mut self) {
 198         // Run the cleanup function if one is still present.
 199         if let Some((data, cleanup)) = self.0.take() {
 200             cleanup(data)
 201         }
 202     }
 203 }
 204
 205 /// Stores an opaque value.
 206 ///
 207 /// This is meant to be used with FFI objects that are never interpreted by Rust code.
 208 #[repr(transparent)]
 209 pub struct Opaque<T>(MaybeUninit<UnsafeCell<T>>);
 210
 211 impl<T> Opaque<T> {
 212     /// Creates a new opaque value.
 213     pub const fn new(value: T) -> Self {
 214         Self(MaybeUninit::new(UnsafeCell::new(value)))
 215     }
 216
 217     /// Creates an uninitialised value.
 218     pub const fn uninit() -> Self {
 219         Self(MaybeUninit::uninit())
 220     }
 221
 222     /// Creates a pin-initializer from the given initializer closure.
 223     ///
 224     /// The returned initializer calls the given closure with the pointer to the inner `T` of this
 225     /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it.
 226     ///
 227     /// This function is safe, because the `T` inside of an `Opaque` is allowed to be
 228     /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs
 229     /// to verify at that point that the inner value is valid.
 230     pub fn ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self> {
 231         // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully
 232         // initialize the `T`.
 233         unsafe {
 234             init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| {
 235                 init_func(Self::raw_get(slot));
 236                 Ok(())
 237             })
 238         }
 239     }
 240
 241     /// Returns a raw pointer to the opaque data.
 242     pub fn get(&self) -> *mut T {
 243         UnsafeCell::raw_get(self.0.as_ptr())
 244     }
 245
 246     /// Gets the value behind `this`.
 247     ///
 248     /// This function is useful to get access to the value without creating intermediate
 249     /// references.
 250     pub const fn raw_get(this: *const Self) -> *mut T {
 251         UnsafeCell::raw_get(this.cast::<UnsafeCell<T>>())
 252     }
 253 }
 254
 255 /// Types that are _always_ reference counted.
 256 ///
 257 /// It allows such types to define their own custom ref increment and decrement functions.
 258 /// Additionally, it allows users to convert from a shared reference `&T` to an owned reference
 259 /// [`ARef<T>`].
 260 ///
 261 /// This is usually implemented by wrappers to existing structures on the C side of the code. For
 262 /// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
 263 /// instances of a type.
 264 ///
 265 /// # Safety
 266 ///
 267 /// Implementers must ensure that increments to the reference count keep the object alive in memory
 268 /// at least until matching decrements are performed.
 269 ///
 270 /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
 271 /// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
 272 /// alive.)
 273 pub unsafe trait AlwaysRefCounted {
 274     /// Increments the reference count on the object.
 275     fn inc_ref(&self);
 276
 277     /// Decrements the reference count on the object.
 278     ///
 279     /// Frees the object when the count reaches zero.
 280     ///
 281     /// # Safety
 282     ///
 283     /// Callers must ensure that there was a previous matching increment to the reference count,
 284     /// and that the object is no longer used after its reference count is decremented (as it may
 285     /// result in the object being freed), unless the caller owns another increment on the refcount
 286     /// (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls
 287     /// [`AlwaysRefCounted::dec_ref`] once).
 288     unsafe fn dec_ref(obj: NonNull<Self>);
 289 }
 290
 291 /// An owned reference to an always-reference-counted object.
 292 ///
 293 /// The object's reference count is automatically decremented when an instance of [`ARef`] is
 294 /// dropped. It is also automatically incremented when a new instance is created via
 295 /// [`ARef::clone`].
 296 ///
 297 /// # Invariants
 298 ///
 299 /// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
 300 /// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
 301 pub struct ARef<T: AlwaysRefCounted> {
 302     ptr: NonNull<T>,
 303     _p: PhantomData<T>,
 304 }
 305
 306 // SAFETY: It is safe to send `ARef<T>` to another thread when the underlying `T` is `Sync` because
 307 // it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally, it needs
 308 // `T` to be `Send` because any thread that has an `ARef<T>` may ultimately access `T` using a
 309 // mutable reference, for example, when the reference count reaches zero and `T` is dropped.
 310 unsafe impl<T: AlwaysRefCounted + Sync + Send> Send for ARef<T> {}
 311
 312 // SAFETY: It is safe to send `&ARef<T>` to another thread when the underlying `T` is `Sync`
 313 // because it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally,
 314 // it needs `T` to be `Send` because any thread that has a `&ARef<T>` may clone it and get an
 315 // `ARef<T>` on that thread, so the thread may ultimately access `T` using a mutable reference, for
 316 // example, when the reference count reaches zero and `T` is dropped.
 317 unsafe impl<T: AlwaysRefCounted + Sync + Send> Sync for ARef<T> {}
 318
 319 impl<T: AlwaysRefCounted> ARef<T> {
 320     /// Creates a new instance of [`ARef`].
 321     ///
 322     /// It takes over an increment of the reference count on the underlying object.
 323     ///
 324     /// # Safety
 325     ///
 326     /// Callers must ensure that the reference count was incremented at least once, and that they
 327     /// are properly relinquishing one increment. That is, if there is only one increment, callers
 328     /// must not use the underlying object anymore -- it is only safe to do so via the newly
 329     /// created [`ARef`].
 330     pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
 331         // INVARIANT: The safety requirements guarantee that the new instance now owns the
 332         // increment on the refcount.
 333         Self {
 334             ptr,
 335             _p: PhantomData,
 336         }
 337     }
 338 }
 339
 340 impl<T: AlwaysRefCounted> Clone for ARef<T> {
 341     fn clone(&self) -> Self {
 342         self.inc_ref();
 343         // SAFETY: We just incremented the refcount above.
 344         unsafe { Self::from_raw(self.ptr) }
 345     }
 346 }
 347
 348 impl<T: AlwaysRefCounted> Deref for ARef<T> {
 349     type Target = T;
 350
 351     fn deref(&self) -> &Self::Target {
 352         // SAFETY: The type invariants guarantee that the object is valid.
 353         unsafe { self.ptr.as_ref() }
 354     }
 355 }
 356
 357 impl<T: AlwaysRefCounted> From<&T> for ARef<T> {
 358     fn from(b: &T) -> Self {
 359         b.inc_ref();
 360         // SAFETY: We just incremented the refcount above.
 361         unsafe { Self::from_raw(NonNull::from(b)) }
 362     }
 363 }
 364
 365 impl<T: AlwaysRefCounted> Drop for ARef<T> {
 366     fn drop(&mut self) {
 367         // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
 368         // decrement.
 369         unsafe { T::dec_ref(self.ptr) };
 370     }
 371 }
 372
 373 /// A sum type that always holds either a value of type `L` or `R`.
 374 pub enum Either<L, R> {
 375     /// Constructs an instance of [`Either`] containing a value of type `L`.
 376     Left(L),
 377
 378     /// Constructs an instance of [`Either`] containing a value of type `R`.
 379     Right(R),
 380 }