projects/linux·blob master · refs

453 lines · 15.6 KiB

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