diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2023-04-30 21:20:22 +0300 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2023-04-30 21:20:22 +0300 |
commit | 310897659cf056016e2c772a028f9b8abc934928 (patch) | |
tree | ca5f122d871a4e54026884bcc98a6309e3fd4069 /rust/kernel/types.rs | |
parent | 825a0714d2b3883d4f8ff64f6933fb73ee3f1834 (diff) | |
parent | ea76e08f4d901a450619831a255e9e0a4c0ed162 (diff) | |
download | linux-310897659cf056016e2c772a028f9b8abc934928.tar.xz |
Merge tag 'rust-6.4' of https://github.com/Rust-for-Linux/linux
Pull rust updates from Miguel Ojeda
"More additions to the Rust core. Importantly, this adds the pin-init
API, which will be used by other abstractions, such as the
synchronization ones added here too:
- pin-init API: a solution for the safe pinned initialization
problem.
This allows to reduce the need for 'unsafe' code in the kernel when
dealing with data structures that require a stable address. Commit
90e53c5e70a6 ("rust: add pin-init API core") contains a nice
introduction -- here is an example of how it looks like:
#[pin_data]
struct Example {
#[pin]
value: Mutex<u32>,
#[pin]
value_changed: CondVar,
}
impl Example {
fn new() -> impl PinInit<Self> {
pin_init!(Self {
value <- new_mutex!(0),
value_changed <- new_condvar!(),
})
}
}
// In a `Box`.
let b = Box::pin_init(Example::new())?;
// In the stack.
stack_pin_init!(let s = Example::new());
- 'sync' module:
New types 'LockClassKey' ('struct lock_class_key'), 'Lock',
'Guard', 'Mutex' ('struct mutex'), 'SpinLock' ('spinlock_t'),
'LockedBy' and 'CondVar' (uses 'wait_queue_head_t'), plus macros
such as 'static_lock_class!' and 'new_spinlock!'.
In particular, 'Lock' and 'Guard' are generic implementations that
contain code that is common to all locks. Then, different backends
(the new 'Backend' trait) are implemented and used to define types
like 'Mutex':
type Mutex<T> = Lock<T, MutexBackend>;
In addition, new methods 'assume_init()', 'init_with()' and
'pin_init_with()' for 'UniqueArc<MaybeUninit<T>>' and 'downcast()'
for 'Arc<dyn Any + Send + Sync>'; as well as 'Debug' and 'Display'
implementations for 'Arc' and 'UniqueArc'. Reduced stack usage of
'UniqueArc::try_new_uninit()', too.
- 'types' module:
New trait 'AlwaysRefCounted' and new type 'ARef' (an owned
reference to an always-reference-counted object, meant to be used
in wrappers for C types that have their own ref counting
functions).
Moreover, new associated functions 'raw_get()' and 'ffi_init()' for
'Opaque'.
- New 'task' module with a new type 'Task' ('struct task_struct'),
and a new macro 'current!' to safely get a reference to the current
one.
- New 'ioctl' module with new '_IOC*' const functions (equivalent to
the C macros).
- New 'uapi' crate, intended to be accessible by drivers directly.
- 'macros' crate: new 'quote!' macro (similar to the one provided in
userspace by the 'quote' crate); and the 'module!' macro now allows
specifying multiple module aliases.
- 'error' module:
New associated functions for the 'Error' type, such as
'from_errno()' and new functions such as 'to_result()'.
- 'alloc' crate:
More fallible 'Vec' methods: 'try_resize` and
'try_extend_from_slice' and the infrastructure (imported from the
Rust standard library) they need"
* tag 'rust-6.4' of https://github.com/Rust-for-Linux/linux: (44 commits)
rust: ioctl: Add ioctl number manipulation functions
rust: uapi: Add UAPI crate
rust: sync: introduce `CondVar`
rust: lock: add `Guard::do_unlocked`
rust: sync: introduce `LockedBy`
rust: introduce `current`
rust: add basic `Task`
rust: introduce `ARef`
rust: lock: introduce `SpinLock`
rust: lock: introduce `Mutex`
rust: sync: introduce `Lock` and `Guard`
rust: sync: introduce `LockClassKey`
MAINTAINERS: add Benno Lossin as Rust reviewer
rust: init: broaden the blanket impl of `Init`
rust: sync: add functions for initializing `UniqueArc<MaybeUninit<T>>`
rust: sync: reduce stack usage of `UniqueArc::try_new_uninit`
rust: types: add `Opaque::ffi_init`
rust: prelude: add `pin-init` API items to prelude
rust: init: add `Zeroable` trait and `init::zeroed` function
rust: init: add `stack_pin_init!` macro
...
Diffstat (limited to 'rust/kernel/types.rs')
-rw-r--r-- | rust/kernel/types.rs | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs index 9d0fdbc55843..29db59d6119a 100644 --- a/rust/kernel/types.rs +++ b/rust/kernel/types.rs @@ -2,11 +2,14 @@ //! Kernel types. +use crate::init::{self, PinInit}; use alloc::boxed::Box; use core::{ cell::UnsafeCell, + marker::PhantomData, mem::MaybeUninit, ops::{Deref, DerefMut}, + ptr::NonNull, }; /// Used to transfer ownership to and from foreign (non-Rust) languages. @@ -234,10 +237,142 @@ impl<T> Opaque<T> { Self(MaybeUninit::uninit()) } + /// Creates a pin-initializer from the given initializer closure. + /// + /// The returned initializer calls the given closure with the pointer to the inner `T` of this + /// `Opaque`. Since this memory is uninitialized, the closure is not allowed to read from it. + /// + /// This function is safe, because the `T` inside of an `Opaque` is allowed to be + /// uninitialized. Additionally, access to the inner `T` requires `unsafe`, so the caller needs + /// to verify at that point that the inner value is valid. + pub fn ffi_init(init_func: impl FnOnce(*mut T)) -> impl PinInit<Self> { + // SAFETY: We contain a `MaybeUninit`, so it is OK for the `init_func` to not fully + // initialize the `T`. + unsafe { + init::pin_init_from_closure::<_, ::core::convert::Infallible>(move |slot| { + init_func(Self::raw_get(slot)); + Ok(()) + }) + } + } + /// Returns a raw pointer to the opaque data. pub fn get(&self) -> *mut T { UnsafeCell::raw_get(self.0.as_ptr()) } + + /// Gets the value behind `this`. + /// + /// This function is useful to get access to the value without creating intermediate + /// references. + pub const fn raw_get(this: *const Self) -> *mut T { + UnsafeCell::raw_get(this.cast::<UnsafeCell<T>>()) + } +} + +/// Types that are _always_ reference counted. +/// +/// It allows such types to define their own custom ref increment and decrement functions. +/// Additionally, it allows users to convert from a shared reference `&T` to an owned reference +/// [`ARef<T>`]. +/// +/// This is usually implemented by wrappers to existing structures on the C side of the code. For +/// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted +/// instances of a type. +/// +/// # Safety +/// +/// Implementers must ensure that increments to the reference count keep the object alive in memory +/// at least until matching decrements are performed. +/// +/// Implementers must also ensure that all instances are reference-counted. (Otherwise they +/// won't be able to honour the requirement that [`AlwaysRefCounted::inc_ref`] keep the object +/// alive.) +pub unsafe trait AlwaysRefCounted { + /// Increments the reference count on the object. + fn inc_ref(&self); + + /// Decrements the reference count on the object. + /// + /// Frees the object when the count reaches zero. + /// + /// # Safety + /// + /// Callers must ensure that there was a previous matching increment to the reference count, + /// and that the object is no longer used after its reference count is decremented (as it may + /// result in the object being freed), unless the caller owns another increment on the refcount + /// (e.g., it calls [`AlwaysRefCounted::inc_ref`] twice, then calls + /// [`AlwaysRefCounted::dec_ref`] once). + unsafe fn dec_ref(obj: NonNull<Self>); +} + +/// An owned reference to an always-reference-counted object. +/// +/// The object's reference count is automatically decremented when an instance of [`ARef`] is +/// dropped. It is also automatically incremented when a new instance is created via +/// [`ARef::clone`]. +/// +/// # Invariants +/// +/// The pointer stored in `ptr` is non-null and valid for the lifetime of the [`ARef`] instance. In +/// particular, the [`ARef`] instance owns an increment on the underlying object's reference count. +pub struct ARef<T: AlwaysRefCounted> { + ptr: NonNull<T>, + _p: PhantomData<T>, +} + +impl<T: AlwaysRefCounted> ARef<T> { + /// Creates a new instance of [`ARef`]. + /// + /// It takes over an increment of the reference count on the underlying object. + /// + /// # Safety + /// + /// Callers must ensure that the reference count was incremented at least once, and that they + /// are properly relinquishing one increment. That is, if there is only one increment, callers + /// must not use the underlying object anymore -- it is only safe to do so via the newly + /// created [`ARef`]. + pub unsafe fn from_raw(ptr: NonNull<T>) -> Self { + // INVARIANT: The safety requirements guarantee that the new instance now owns the + // increment on the refcount. + Self { + ptr, + _p: PhantomData, + } + } +} + +impl<T: AlwaysRefCounted> Clone for ARef<T> { + fn clone(&self) -> Self { + self.inc_ref(); + // SAFETY: We just incremented the refcount above. + unsafe { Self::from_raw(self.ptr) } + } +} + +impl<T: AlwaysRefCounted> Deref for ARef<T> { + type Target = T; + + fn deref(&self) -> &Self::Target { + // SAFETY: The type invariants guarantee that the object is valid. + unsafe { self.ptr.as_ref() } + } +} + +impl<T: AlwaysRefCounted> From<&T> for ARef<T> { + fn from(b: &T) -> Self { + b.inc_ref(); + // SAFETY: We just incremented the refcount above. + unsafe { Self::from_raw(NonNull::from(b)) } + } +} + +impl<T: AlwaysRefCounted> Drop for ARef<T> { + fn drop(&mut self) { + // SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to + // decrement. + unsafe { T::dec_ref(self.ptr) }; + } } /// A sum type that always holds either a value of type `L` or `R`. |