kernel/types.rs
1// SPDX-License-Identifier: GPL-2.0
2
3//! Kernel types.
4
5use crate::ffi::c_void;
6use core::{
7 cell::UnsafeCell,
8 marker::{PhantomData, PhantomPinned},
9 mem::MaybeUninit,
10 ops::{Deref, DerefMut},
11};
12use pin_init::{PinInit, Wrapper, Zeroable};
13
14pub 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`].
27pub 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
53 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
63 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
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
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
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 `()`.
131unsafe impl ForeignOwnable for () {
132 const FOREIGN_ALIGN: usize = core::mem::align_of::<()>();
133 type Borrowed<'a> = ();
134 type BorrowedMut<'a> = ();
135
136 fn into_foreign(self) -> *mut c_void {
137 core::ptr::NonNull::dangling().as_ptr()
138 }
139
140 unsafe fn from_foreign(_: *mut c_void) -> Self {}
141
142 unsafe fn borrow<'a>(_: *mut c_void) -> Self::Borrowed<'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.
220pub struct ScopeGuard<T, F: FnOnce(T)>(Option<(T, F)>);
221
222impl<T, F: FnOnce(T)> ScopeGuard<T, F> {
223 /// Creates a new guarded object wrapping the given data and with the given cleanup function.
224 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.
230 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
237impl ScopeGuard<(), fn(())> {
238 /// Creates a new guarded object with the given cleanup function.
239 pub fn new(cleanup: impl FnOnce()) -> ScopeGuard<(), impl FnOnce(())> {
240 ScopeGuard::new_with_data((), move |()| cleanup())
241 }
242}
243
244impl<T, F: FnOnce(T)> Deref for ScopeGuard<T, F> {
245 type Target = T;
246
247 fn deref(&self) -> &T {
248 // The type invariants guarantee that `unwrap` will succeed.
249 &self.0.as_ref().unwrap().0
250 }
251}
252
253impl<T, F: FnOnce(T)> DerefMut for ScopeGuard<T, F> {
254 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
260impl<T, F: FnOnce(T)> Drop for ScopeGuard<T, F> {
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/// # #![expect(unreachable_pub, clippy::disallowed_names)]
293/// use kernel::types::Opaque;
294/// # // Emulate a C struct binding which is from C, maybe uninitialized or not, only the C side
295/// # // knows.
296/// # mod bindings {
297/// # pub struct Foo {
298/// # pub val: u8,
299/// # }
300/// # }
301///
302/// // `foo.val` is assumed to be handled on the C side, so we use `Opaque` to wrap it.
303/// pub struct Foo {
304/// foo: Opaque<bindings::Foo>,
305/// }
306///
307/// impl Foo {
308/// pub fn get_val(&self) -> u8 {
309/// let ptr = Opaque::get(&self.foo);
310///
311/// // SAFETY: `Self` is valid from C side.
312/// unsafe { (*ptr).val }
313/// }
314/// }
315///
316/// // Create an instance of `Foo` with the `Opaque` wrapper.
317/// let foo = Foo {
318/// foo: Opaque::new(bindings::Foo { val: 0xdb }),
319/// };
320///
321/// assert_eq!(foo.get_val(), 0xdb);
322/// ```
323#[repr(transparent)]
324pub struct Opaque<T> {
325 value: UnsafeCell<MaybeUninit<T>>,
326 _pin: PhantomPinned,
327}
328
329// SAFETY: `Opaque<T>` allows the inner value to be any bit pattern, including all zeros.
330unsafe impl<T> Zeroable for Opaque<T> {}
331
332impl<T> Opaque<T> {
333 /// Creates a new opaque value.
334 pub const fn new(value: T) -> Self {
335 Self {
336 value: UnsafeCell::new(MaybeUninit::new(value)),
337 _pin: PhantomPinned,
338 }
339 }
340
341 /// Creates an uninitialised value.
342 pub const fn uninit() -> Self {
343 Self {
344 value: UnsafeCell::new(MaybeUninit::uninit()),
345 _pin: PhantomPinned,
346 }
347 }
348
349 /// Creates a new zeroed opaque value.
350 pub const fn zeroed() -> Self {
351 Self {
352 value: UnsafeCell::new(MaybeUninit::zeroed()),
353 _pin: PhantomPinned,
354 }
355 }
356
357 /// Creates a pin-initializer from the given initializer closure.
358 ///
359 /// The returned initializer calls the given closure with the pointer to the inner `T` of this
360 /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it.
361 ///
362 /// This function is safe, because the `T` inside of an `Opaque` is allowed to be
363 /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs
364 /// to verify at that point that the inner value is valid.
365 pub fn ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self> {
366 // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully
367 // initialize the `T`.
368 unsafe {
369 pin_init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| {
370 init_func(Self::cast_into(slot));
371 Ok(())
372 })
373 }
374 }
375
376 /// Creates a fallible pin-initializer from the given initializer closure.
377 ///
378 /// The returned initializer calls the given closure with the pointer to the inner `T` of this
379 /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it.
380 ///
381 /// This function is safe, because the `T` inside of an `Opaque` is allowed to be
382 /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs
383 /// to verify at that point that the inner value is valid.
384 pub fn try_ffi_init<E>(
385 init_func: impl FnOnce(*mut T) -> Result<(), E>,
386 ) -> impl PinInit<Self, E> {
387 // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully
388 // initialize the `T`.
389 unsafe {
390 pin_init::pin_init_from_closure::<_, E>(move |slot| init_func(Self::cast_into(slot)))
391 }
392 }
393
394 /// Returns a raw pointer to the opaque data.
395 pub const fn get(&self) -> *mut T {
396 UnsafeCell::get(&self.value).cast::<T>()
397 }
398
399 /// Gets the value behind `this`.
400 ///
401 /// This function is useful to get access to the value without creating intermediate
402 /// references.
403 pub const fn cast_into(this: *const Self) -> *mut T {
404 UnsafeCell::raw_get(this.cast::<UnsafeCell<MaybeUninit<T>>>()).cast::<T>()
405 }
406
407 /// The opposite operation of [`Opaque::cast_into`].
408 pub const fn cast_from(this: *const T) -> *const Self {
409 this.cast()
410 }
411}
412
413impl<T> Wrapper<T> for Opaque<T> {
414 /// Create an opaque pin-initializer from the given pin-initializer.
415 fn pin_init<E>(slot: impl PinInit<T, E>) -> impl PinInit<Self, E> {
416 Self::try_ffi_init(|ptr: *mut T| {
417 // SAFETY:
418 // - `ptr` is a valid pointer to uninitialized memory,
419 // - `slot` is not accessed on error,
420 // - `slot` is pinned in memory.
421 unsafe { PinInit::<T, E>::__pinned_init(slot, ptr) }
422 })
423 }
424}
425
426/// Zero-sized type to mark types not [`Send`].
427///
428/// Add this type as a field to your struct if your type should not be sent to a different task.
429/// Since [`Send`] is an auto trait, adding a single field that is `!Send` will ensure that the
430/// whole type is `!Send`.
431///
432/// If a type is `!Send` it is impossible to give control over an instance of the type to another
433/// task. This is useful to include in types that store or reference task-local information. A file
434/// descriptor is an example of such task-local information.
435///
436/// This type also makes the type `!Sync`, which prevents immutable access to the value from
437/// several threads in parallel.
438pub type NotThreadSafe = PhantomData<*mut ()>;
439
440/// Used to construct instances of type [`NotThreadSafe`] similar to how `PhantomData` is
441/// constructed.
442///
443/// [`NotThreadSafe`]: type@NotThreadSafe
444#[allow(non_upper_case_globals)]
445pub const NotThreadSafe: NotThreadSafe = PhantomData;