xref: /openbmc/linux/rust/kernel/types.rs (revision d6344cc8)
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, PhantomPinned},
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.
into_foreign(self) -> *const core::ffi::c_void30     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.
borrow<'a>(ptr: *const core::ffi::c_void) -> Self::Borrowed<'a>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.
from_foreign(ptr: *const core::ffi::c_void) -> Self48     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 
into_foreign(self) -> *const core::ffi::c_void54     fn into_foreign(self) -> *const core::ffi::c_void {
55         Box::into_raw(self) as _
56     }
57 
borrow<'a>(ptr: *const core::ffi::c_void) -> &'a T58     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 
from_foreign(ptr: *const core::ffi::c_void) -> Self66     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 
into_foreign(self) -> *const core::ffi::c_void76     fn into_foreign(self) -> *const core::ffi::c_void {
77         core::ptr::NonNull::dangling().as_ptr()
78     }
79 
borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a>80     unsafe fn borrow<'a>(_: *const core::ffi::c_void) -> Self::Borrowed<'a> {}
81 
from_foreign(_: *const core::ffi::c_void) -> Self82     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.
new_with_data(data: T, cleanup_func: F) -> Self160     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.
dismiss(mut self) -> T166     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.
new(cleanup: impl FnOnce()) -> ScopeGuard<(), impl FnOnce(())>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 
deref(&self) -> &T183     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> {
deref_mut(&mut self) -> &mut T190     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> {
drop(&mut self)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> {
210     value: UnsafeCell<MaybeUninit<T>>,
211     _pin: PhantomPinned,
212 }
213 
214 impl<T> Opaque<T> {
215     /// Creates a new opaque value.
new(value: T) -> Self216     pub const fn new(value: T) -> Self {
217         Self {
218             value: UnsafeCell::new(MaybeUninit::new(value)),
219             _pin: PhantomPinned,
220         }
221     }
222 
223     /// Creates an uninitialised value.
uninit() -> Self224     pub const fn uninit() -> Self {
225         Self {
226             value: UnsafeCell::new(MaybeUninit::uninit()),
227             _pin: PhantomPinned,
228         }
229     }
230 
231     /// Creates a pin-initializer from the given initializer closure.
232     ///
233     /// The returned initializer calls the given closure with the pointer to the inner `T` of this
234     /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it.
235     ///
236     /// This function is safe, because the `T` inside of an `Opaque` is allowed to be
237     /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs
238     /// to verify at that point that the inner value is valid.
ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self>239     pub fn ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self> {
240         // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully
241         // initialize the `T`.
242         unsafe {
243             init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| {
244                 init_func(Self::raw_get(slot));
245                 Ok(())
246             })
247         }
248     }
249 
250     /// Returns a raw pointer to the opaque data.
get(&self) -> *mut T251     pub const fn get(&self) -> *mut T {
252         UnsafeCell::get(&self.value).cast::<T>()
253     }
254 
255     /// Gets the value behind `this`.
256     ///
257     /// This function is useful to get access to the value without creating intermediate
258     /// references.
raw_get(this: *const Self) -> *mut T259     pub const fn raw_get(this: *const Self) -> *mut T {
260         UnsafeCell::raw_get(this.cast::<UnsafeCell<MaybeUninit<T>>>()).cast::<T>()
261     }
262 }
263 
264 /// Types that are _always_ reference counted.
265 ///
266 /// It allows such types to define their own custom ref increment and decrement functions.
267 /// Additionally, it allows users to convert from a shared reference `&T` to an owned reference
268 /// [`ARef<T>`].
269 ///
270 /// This is usually implemented by wrappers to existing structures on the C side of the code. For
271 /// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
272 /// instances of a type.
273 ///
274 /// # Safety
275 ///
276 /// Implementers must ensure that increments to the reference count keep the object alive in memory
277 /// at least until matching decrements are performed.
278 ///
279 /// Implementers must also ensure that all instances are reference-counted. (Otherwise they
280 /// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object
281 /// alive.)
282 pub unsafe trait AlwaysRefCounted {
283     /// Increments the reference count on the object.
inc_ref(&self)284     fn inc_ref(&self);
285 
286     /// Decrements the reference count on the object.
287     ///
288     /// Frees the object when the count reaches zero.
289     ///
290     /// # Safety
291     ///
292     /// Callers must ensure that there was a previous matching increment to the reference count,
293     /// and that the object is no longer used after its reference count is decremented (as it may
294     /// result in the object being freed), unless the caller owns another increment on the refcount
295     /// (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls
296     /// [`AlwaysRefCounted::dec_ref`] once).
dec_ref(obj: NonNull<Self>)297     unsafe fn dec_ref(obj: NonNull<Self>);
298 }
299 
300 /// An owned reference to an always-reference-counted object.
301 ///
302 /// The object's reference count is automatically decremented when an instance of [`ARef`] is
303 /// dropped. It is also automatically incremented when a new instance is created via
304 /// [`ARef::clone`].
305 ///
306 /// # Invariants
307 ///
308 /// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In
309 /// particular, the [`ARef`] instance owns an increment on the underlying object's reference count.
310 pub struct ARef<T: AlwaysRefCounted> {
311     ptr: NonNull<T>,
312     _p: PhantomData<T>,
313 }
314 
315 // SAFETY: It is safe to send `ARef<T>` to another thread when the underlying `T` is `Sync` because
316 // it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally, it needs
317 // `T` to be `Send` because any thread that has an `ARef<T>` may ultimately access `T` using a
318 // mutable reference, for example, when the reference count reaches zero and `T` is dropped.
319 unsafe impl<T: AlwaysRefCounted + Sync + Send> Send for ARef<T> {}
320 
321 // SAFETY: It is safe to send `&ARef<T>` to another thread when the underlying `T` is `Sync`
322 // because it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally,
323 // it needs `T` to be `Send` because any thread that has a `&ARef<T>` may clone it and get an
324 // `ARef<T>` on that thread, so the thread may ultimately access `T` using a mutable reference, for
325 // example, when the reference count reaches zero and `T` is dropped.
326 unsafe impl<T: AlwaysRefCounted + Sync + Send> Sync for ARef<T> {}
327 
328 impl<T: AlwaysRefCounted> ARef<T> {
329     /// Creates a new instance of [`ARef`].
330     ///
331     /// It takes over an increment of the reference count on the underlying object.
332     ///
333     /// # Safety
334     ///
335     /// Callers must ensure that the reference count was incremented at least once, and that they
336     /// are properly relinquishing one increment. That is, if there is only one increment, callers
337     /// must not use the underlying object anymore -- it is only safe to do so via the newly
338     /// created [`ARef`].
from_raw(ptr: NonNull<T>) -> Self339     pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
340         // INVARIANT: The safety requirements guarantee that the new instance now owns the
341         // increment on the refcount.
342         Self {
343             ptr,
344             _p: PhantomData,
345         }
346     }
347 }
348 
349 impl<T: AlwaysRefCounted> Clone for ARef<T> {
clone(&self) -> Self350     fn clone(&self) -> Self {
351         self.inc_ref();
352         // SAFETY: We just incremented the refcount above.
353         unsafe { Self::from_raw(self.ptr) }
354     }
355 }
356 
357 impl<T: AlwaysRefCounted> Deref for ARef<T> {
358     type Target = T;
359 
deref(&self) -> &Self::Target360     fn deref(&self) -> &Self::Target {
361         // SAFETY: The type invariants guarantee that the object is valid.
362         unsafe { self.ptr.as_ref() }
363     }
364 }
365 
366 impl<T: AlwaysRefCounted> From<&T> for ARef<T> {
from(b: &T) -> Self367     fn from(b: &T) -> Self {
368         b.inc_ref();
369         // SAFETY: We just incremented the refcount above.
370         unsafe { Self::from_raw(NonNull::from(b)) }
371     }
372 }
373 
374 impl<T: AlwaysRefCounted> Drop for ARef<T> {
drop(&mut self)375     fn drop(&mut self) {
376         // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
377         // decrement.
378         unsafe { T::dec_ref(self.ptr) };
379     }
380 }
381 
382 /// A sum type that always holds either a value of type `L` or `R`.
383 pub enum Either<L, R> {
384     /// Constructs an instance of [`Either`] containing a value of type `L`.
385     Left(L),
386 
387     /// Constructs an instance of [`Either`] containing a value of type `R`.
388     Right(R),
389 }
390