* [PATCH v22 2/5] rust: types: Add Ownable/Owned types
2026-11-16 14:20 [PATCH v22 0/5] rust: add `Ownable` trait and `Owned` type Andreas Hindborg
2026-11-16 14:20 ` [PATCH v22 1/5] rust: alloc: add `KBox::into_non_null` Andreas Hindborg
@ 2026-11-16 14:20 ` Andreas Hindborg
2026-11-16 14:21 ` [PATCH v22 3/5] rust: implement `ForeignOwnable` for `Owned` Andreas Hindborg
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Andreas Hindborg @ 2026-11-16 14:20 UTC (permalink / raw)
To: Danilo Krummrich, Lorenzo Stoakes, Vlastimil Babka,
Liam R. Howlett, Uladzislau Rezki, Miguel Ojeda, Boqun Feng,
Gary Guo, Björn Roy Baron, Benno Lossin, Alice Ryhl,
Trevor Gross, Daniel Almeida, Tamir Duberstein,
Alexandre Courbot, Onur Özkan, Lyude Paul,
Greg Kroah-Hartman, Christian Brauner, Rafael J. Wysocki,
Dave Ertman, Leon Romanovsky, Paul Moore, Serge Hallyn,
David Airlie, Simona Vetter, Alexander Viro, Jan Kara,
Igor Korotin, Viresh Kumar, Nishanth Menon, Stephen Boyd,
Bjorn Helgaas, Krzysztof Wilczyński, Pavel Tikhomirov,
Michal Wilczynski, Ira Weiny, Matthew Brost,
Thomas Hellström, Johan Hovold, Sumit Semwal,
Christian König, Dave Jiang, Jason Gunthorpe,
Saeed Mahameed, Zhi Wang, Jonathan Cameron, Markus Probst,
Ira Weiny
Cc: Andreas Hindborg, Philipp Stanner, rust-for-linux, linux-kernel,
linux-mm, driver-core, linux-block, linux-security-module,
dri-devel, linux-fsdevel, linux-pm, linux-pci, linux-pwm,
linux-usb, linux-media, linaro-mm-sig, linux-serial, Asahi Lina,
Oliver Mangold
From: Asahi Lina <lina+kernel@asahilina.net>
By analogy to `AlwaysRefCounted` and `ARef`, an `Ownable` type is a
(typically C FFI) type that *may* be owned by Rust, but need not be. Unlike
an `ARef<T>`, an `Owned<T>` cannot be cloned. At most one `Owned<T>` exists
for an object at any time, and the type `T` decides whether other
references to the object may exist together with it.
Conceptually, this is similar to a `KBox<T>`, except that it delegates
resource management to the `T` instead of using a generic allocator.
[ om:
- Split code into separate file and `pub use` it from types.rs.
- Make from_raw() and into_raw() public.
- Remove OwnableMut, and make DerefMut dependent on Unpin instead.
- Usage example/doctest for Ownable/Owned.
- Fixes to documentation and commit message.
]
Link: https://lore.kernel.org/all/20250202-rust-page-v1-1-e3170d7fe55e@asahilina.net/
Signed-off-by: Asahi Lina <lina+kernel@asahilina.net>
Co-developed-by: Oliver Mangold <oliver.mangold@pm.me>
Signed-off-by: Oliver Mangold <oliver.mangold@pm.me>
[ Andreas: Updated documentation, examples, and formatting. Change safety
requirements, safety comments. Let `T` decide whether other references
may exist together with an `Owned<T>`. ]
Co-developed-by: Andreas Hindborg <a.hindborg@kernel.org>
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
rust/kernel/lib.rs | 1 +
rust/kernel/owned.rs | 274 +++++++++++++++++++++++++++++++++++++++++++++++
rust/kernel/sync/aref.rs | 5 +
rust/kernel/types.rs | 5 +
4 files changed, 285 insertions(+)
diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs
index 1ab41129d557..fd0f9bf484e4 100644
--- a/rust/kernel/lib.rs
+++ b/rust/kernel/lib.rs
@@ -111,6 +111,7 @@
pub mod of;
#[cfg(CONFIG_PM_OPP)]
pub mod opp;
+pub mod owned;
pub mod page;
#[cfg(CONFIG_PCI)]
pub mod pci;
diff --git a/rust/kernel/owned.rs b/rust/kernel/owned.rs
new file mode 100644
index 000000000000..51da9bc7e1f4
--- /dev/null
+++ b/rust/kernel/owned.rs
@@ -0,0 +1,274 @@
+// SPDX-License-Identifier: GPL-2.0
+
+//! Unique owned pointer types for objects with custom drop logic.
+//!
+//! These pointer types are useful for C-allocated objects which by API-contract
+//! are owned by Rust, but need to be freed through the C API.
+
+use core::{
+ mem::ManuallyDrop,
+ ops::{
+ Deref,
+ DerefMut, //
+ },
+ pin::Pin,
+ ptr::NonNull, //
+};
+
+/// Types that specify their own way of performing allocation and destruction. Typically, this trait
+/// is implemented on types from the C side.
+///
+/// Implementing this trait allows types to be referenced via the [`Owned<Self>`] pointer type.
+/// - This is useful when it is desirable to tie the lifetime of an object reference to an owned
+/// object, rather than pass around a bare reference.
+/// - [`Ownable`] types can define custom drop logic that is executed when the owned reference
+/// of type [`Owned<_>`] pointing to the object is dropped.
+///
+/// Note: The underlying object is not required to provide internal reference counting, because it
+/// represents a unique, owned reference. If reference counting (on the Rust side) is required,
+/// [`AlwaysRefCounted`](crate::sync::aref::AlwaysRefCounted) should be implemented.
+///
+/// # Access model
+///
+/// An [`Owned<Self>`] is a unique handle: at most one [`Owned<Self>`] exists for an object at any
+/// time. There are two kinds of references to the object to consider, and they are governed by
+/// different rules:
+///
+/// - References that borrow the [`Owned<Self>`]. An [`Owned<Self>`] hands out `&Self` and
+/// `Pin<&mut Self>` to safe code, and also `&mut Self` if `Self` is [`Unpin`]. These references
+/// borrow the [`Owned<Self>`], so the borrow checker ensures that they do not outlive it and
+/// that they follow the usual aliasing rules with respect to each other.
+/// - Other references. These are references to the object that do not borrow the
+/// [`Owned<Self>`], such as an `ARef<Self>`, or a `&Self` obtained from one. The borrow checker
+/// does not relate these to the [`Owned<Self>`].
+///
+/// Whether other references to an object may exist together with the [`Owned<Self>`] is decided by
+/// the implementer of this trait:
+///
+/// - A type may forbid all other references to an object for as long as an [`Owned<Self>`] to
+/// the object exists. For such a type, an [`Owned<Self>`] is the exclusive owner of the object.
+/// - A type may allow other references, such as `ARef<Self>`, to exist together with an
+/// [`Owned<Self>`]. For such a type, an [`Owned<Self>`] has exclusive access only to the parts
+/// of the object that the type reserves for it.
+///
+/// The borrow checker cannot ensure that references that borrow the [`Owned<Self>`] are sound in
+/// the presence of other references. This is the responsibility of the code that creates an
+/// [`Owned<Self>`], see [`Owned::from_raw`]. Note that a `&mut Self` must never alias another
+/// reference, so a type that is [`Unpin`] cannot allow other references to exist together with an
+/// [`Owned<Self>`].
+///
+/// A type that allows other references to exist together with an [`Owned<Self>`] must place all
+/// state that is accessible through those references inside [`Opaque`](crate::types::Opaque) or
+/// [`UnsafeCell`](core::cell::UnsafeCell). A `&Self` asserts that state outside of these wrappers
+/// is not mutated while the reference is live, so such state must not be mutated through the
+/// [`Owned<Self>`]. In addition, a `Pin<&mut Self>` handed out by an [`Owned<Self>`] may only
+/// alias other references because the compiler does not treat a mutable reference to a type that
+/// is not [`Unpin`] as unique. The intent is to express this with `UnsafePinned` instead, once it
+/// is stable.
+///
+/// Implementers should document, as a type invariant of `Self`, which other references may exist
+/// together with an [`Owned<Self>`], and why access through the [`Owned<Self>`] is sound.
+///
+/// # Examples
+///
+/// A minimal example implementation of [`Ownable`] and its usage with [`Owned`] looks like
+/// this:
+///
+/// ```
+/// # #![expect(clippy::disallowed_names)]
+/// # use core::cell::Cell;
+/// # use core::ptr::NonNull;
+/// # use kernel::sync::global_lock;
+/// # use kernel::alloc::{flags, kbox::KBox, AllocError};
+/// # use kernel::types::{Owned, Ownable};
+/// // Let's count the allocations to see if freeing works.
+/// kernel::sync::global_lock! {
+/// // SAFETY: we call `init()` right below, before doing anything else.
+/// unsafe(uninit) static FOO_ALLOC_COUNT: Mutex<usize> = 0;
+/// }
+/// // SAFETY: We call `init()` only once, here.
+/// unsafe { FOO_ALLOC_COUNT.init() };
+///
+/// // An exclusively owned struct for demonstration purposes.
+/// //
+/// // # Invariants
+/// //
+/// // `Foo` does not allow other references to exist together with an `Owned<Foo>`: while an
+/// // `Owned<Foo>` exists, it is the only reference to the object.
+/// struct Foo;
+///
+/// impl Foo {
+/// fn new() -> Result<Owned<Self>> {
+/// // We are just using a `KBox` here to handle the actual allocation, as our `Foo` is
+/// // not actually a C-allocated object.
+/// let result = KBox::new(
+/// Foo {},
+/// flags::GFP_KERNEL,
+/// )?;
+/// let result = KBox::into_non_null(result);
+/// // Count new allocation
+/// *FOO_ALLOC_COUNT.lock() += 1;
+/// // SAFETY:
+/// // - We just allocated the `Self`, thus it is valid until we free it in `release`.
+/// // - No other pointer to the allocation exists, so this is the only `Owned<Foo>` and
+/// // no other reference to the `Foo` exists. Thus access through the `Owned<Foo>` is
+/// // sound, and it can be used from any thread that `Foo` can be used from.
+/// // - The `Foo` is not moved until it is freed in `release`.
+/// Ok(unsafe { Owned::from_raw(result) })
+/// }
+/// }
+///
+/// impl Ownable for Foo {
+/// unsafe fn release(this: NonNull<Self>) {
+/// // SAFETY: The [`KBox<Self>`] is still alive. We can pass ownership to the [`KBox`], as
+/// // by requirement on calling this function.
+/// drop(unsafe { KBox::from_raw(this.as_ptr()) });
+/// // Count released allocation
+/// *FOO_ALLOC_COUNT.lock() -= 1;
+/// }
+/// }
+///
+/// {
+/// let foo = Foo::new()?;
+/// assert!(*FOO_ALLOC_COUNT.lock() == 1);
+/// }
+/// // `foo` is out of scope now, so we expect no live allocations.
+/// assert!(*FOO_ALLOC_COUNT.lock() == 0);
+/// # Ok::<(), Error>(())
+/// ```
+pub trait Ownable {
+ /// Tear down this `Ownable`.
+ ///
+ /// Implementers of `Ownable` can use this function to clean up the use of `Self`. This can
+ /// include freeing the underlying object, handing it back to the subsystem that allocated it,
+ /// or dropping a reference count.
+ ///
+ /// # Safety
+ ///
+ /// Callers must ensure that:
+ /// - `this` points to a valid `Self`.
+ /// - They hold the ownership of the `Self` pointed to by `this` that is represented by the
+ /// unique [`Owned<Self>`], and that this ownership is transferred to the `release` method.
+ /// - `this` is not used after calling this method, as the underlying object may have been
+ /// freed.
+ ///
+ /// `this` is pinned and implementers of this method must observe this constraint.
+ unsafe fn release(this: NonNull<Self>);
+}
+
+/// A unique owning handle to a `T`.
+///
+/// The [`Ownable`] is automatically freed or released when an instance of [`Owned`] is
+/// dropped.
+///
+/// Whether other references to the underlying `T` may exist together with an [`Owned<T>`] is
+/// decided by `T`, see the *Access model* section of [`Ownable`].
+///
+/// # Invariants
+///
+/// Until `T::release` is called:
+/// - `ptr` points to a valid `T`.
+/// - This is the only `Owned<T>` for the underlying `T`.
+/// - The `T` value is pinned.
+/// - It is sound to create a `&T` or a `Pin<&mut T>` to the underlying `T` and to hand it to safe
+/// code, for the duration of a shared or mutable borrow of this `Owned<T>` respectively. If `T`
+/// is [`Unpin`], the same applies to a `&mut T`. This holds in the presence of all the references
+/// that `T` allows to exist together with an `Owned<T>`.
+/// - If `T` is [`Send`], it is sound to use this `Owned<T>` from, and to drop it on, another thread
+/// than the one it was created on. If `T` is [`Sync`], it is sound to use shared references to
+/// this `Owned<T>` from multiple threads concurrently.
+pub struct Owned<T: Ownable> {
+ ptr: NonNull<T>,
+}
+
+impl<T: Ownable> Owned<T> {
+ /// Creates a new instance of [`Owned`].
+ ///
+ /// This function takes over ownership of the underlying object.
+ ///
+ /// # Safety
+ ///
+ /// Callers must ensure that, until `T::release` is called:
+ /// - `ptr` points to a valid instance of `T`.
+ /// - The returned `Owned<T>` is the only `Owned<T>` for the underlying `T`.
+ /// - The `T` pointed to by `ptr` is treated as pinned from this call on: unless `T: Unpin`, it
+ /// must not be moved for the rest of its lifetime, including after the pointer is recovered
+ /// with [`Owned::into_raw`].
+ /// - No reference to the underlying `T` exists, or is created, other than the references that
+ /// `T` allows to exist together with an `Owned<T>`. In the presence of those references, it
+ /// must be sound to create a `&T` or a `Pin<&mut T>` to the underlying `T` and to hand it to
+ /// safe code, for the duration of a shared or mutable borrow of the returned `Owned<T>`
+ /// respectively. If `T` is [`Unpin`], the same applies to a `&mut T`.
+ /// - If `T` is [`Send`], it is sound to use the returned `Owned<T>` from, and to drop it on,
+ /// another thread than the current one. If `T` is [`Sync`], it is sound to use shared
+ /// references to the returned `Owned<T>` from multiple threads concurrently.
+ #[inline]
+ pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
+ // INVARIANT: The function safety requirements match the invariants of `Self`.
+ Self { ptr }
+ }
+
+ /// Consumes the [`Owned`], returning a raw pointer.
+ ///
+ /// This function does not drop the underlying `T`. When this function returns, ownership of the
+ /// underlying `T` is with the caller.
+ ///
+ /// Note that the returned pointer is pinned.
+ #[inline]
+ pub fn into_raw(me: Self) -> NonNull<T> {
+ ManuallyDrop::new(me).ptr
+ }
+
+ /// Get a pinned mutable reference to the data owned by this `Owned<T>`.
+ #[inline]
+ pub fn as_pin_mut(&mut self) -> Pin<&mut T> {
+ // SAFETY: By the type invariants, `ptr` points to a valid `T` and it is sound to create a
+ // mutable reference to the `T` for the duration of the mutable borrow of `self`, given that
+ // we only hand it out as a `Pin<&mut T>` below.
+ let unpinned = unsafe { self.ptr.as_mut() };
+
+ // SAFETY: By type invariant `T` is pinned.
+ unsafe { Pin::new_unchecked(unpinned) }
+ }
+}
+
+// SAFETY: By the type invariants, it is sound to use and drop an [`Owned<T>`] on another thread
+// when the underlying `T` is [`Send`]. For a `T` that does not allow other references to exist
+// together with an [`Owned<T>`], sending an [`Owned<T>`] is equivalent to sending the `T`.
+unsafe impl<T: Ownable + Send> Send for Owned<T> {}
+
+// SAFETY: By the type invariants, it is sound to use shared references to an [`Owned<T>`] from
+// multiple threads when the underlying `T` is [`Sync`]. A [`&Owned<T>`] only gives access to a
+// `&T`, so sending a [`&Owned<T>`] is equivalent to sending the `&T`.
+unsafe impl<T: Ownable + Sync> Sync for Owned<T> {}
+
+impl<T: Ownable> Deref for Owned<T> {
+ type Target = T;
+
+ #[inline]
+ fn deref(&self) -> &Self::Target {
+ // SAFETY: By the type invariants, `ptr` points to a valid `T` and it is sound to create a
+ // shared reference to the `T` for the duration of the borrow of `self`.
+ unsafe { self.ptr.as_ref() }
+ }
+}
+
+impl<T: Ownable + Unpin> DerefMut for Owned<T> {
+ #[inline]
+ fn deref_mut(&mut self) -> &mut Self::Target {
+ // SAFETY: By the type invariants, `ptr` points to a valid `T` and, as `T` is `Unpin`, it is
+ // sound to create a mutable reference to the `T` for the duration of the mutable borrow of
+ // `self`.
+ unsafe { self.ptr.as_mut() }
+ }
+}
+
+impl<T: Ownable> Drop for Owned<T> {
+ #[inline]
+ fn drop(&mut self) {
+ // SAFETY: By the type invariants, `ptr` points to a valid `T` and `self` is the only
+ // `Owned<T>` for it. As we are dropping `self`, we can transfer the ownership it represents
+ // to the `release` method, and we do not use `ptr` afterwards.
+ unsafe { T::release(self.ptr) };
+ }
+}
diff --git a/rust/kernel/sync/aref.rs b/rust/kernel/sync/aref.rs
index 9983ee085248..1876e40c76df 100644
--- a/rust/kernel/sync/aref.rs
+++ b/rust/kernel/sync/aref.rs
@@ -39,6 +39,11 @@
/// Rust code, the recommendation is to use [`Arc`](crate::sync::Arc) to create reference-counted
/// instances of a type.
///
+/// Note: Implementing this trait allows types to be wrapped in an [`ARef<Self>`]. It requires an
+/// internal reference count and provides only shared references. If unique references are required
+/// [`Ownable`](crate::types::Ownable) should be implemented which allows types to be wrapped in an
+/// [`Owned<Self>`](crate::types::Owned).
+///
/// # Safety
///
/// Implementers must ensure that increments to the reference count keep the object alive in memory
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index 132dd428c1f6..b23e1d60cdd6 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -18,6 +18,11 @@
ForLt, //
};
+pub use crate::owned::{
+ Ownable,
+ Owned, //
+};
+
/// Used to transfer ownership to and from foreign (non-Rust) languages.
///
/// Ownership is transferred from Rust to a foreign language by calling [`Self::into_foreign`] and
--
2.54.0
^ permalink raw reply [flat|nested] 6+ messages in thread* [PATCH v22 4/5] rust: rename `AlwaysRefCounted` to `RefCounted`
2026-11-16 14:20 [PATCH v22 0/5] rust: add `Ownable` trait and `Owned` type Andreas Hindborg
` (2 preceding siblings ...)
2026-11-16 14:21 ` [PATCH v22 3/5] rust: implement `ForeignOwnable` for `Owned` Andreas Hindborg
@ 2026-11-16 14:21 ` Andreas Hindborg
2026-11-16 14:21 ` [PATCH v22 5/5] rust: Add `OwnableIntoShared` and `OwnableTryFromShared` Andreas Hindborg
4 siblings, 0 replies; 6+ messages in thread
From: Andreas Hindborg @ 2026-11-16 14:21 UTC (permalink / raw)
To: Danilo Krummrich, Lorenzo Stoakes, Vlastimil Babka,
Liam R. Howlett, Uladzislau Rezki, Miguel Ojeda, Boqun Feng,
Gary Guo, Björn Roy Baron, Benno Lossin, Alice Ryhl,
Trevor Gross, Daniel Almeida, Tamir Duberstein,
Alexandre Courbot, Onur Özkan, Lyude Paul,
Greg Kroah-Hartman, Christian Brauner, Rafael J. Wysocki,
Dave Ertman, Leon Romanovsky, Paul Moore, Serge Hallyn,
David Airlie, Simona Vetter, Alexander Viro, Jan Kara,
Igor Korotin, Viresh Kumar, Nishanth Menon, Stephen Boyd,
Bjorn Helgaas, Krzysztof Wilczyński, Pavel Tikhomirov,
Michal Wilczynski, Ira Weiny, Matthew Brost,
Thomas Hellström, Johan Hovold, Sumit Semwal,
Christian König, Dave Jiang, Jason Gunthorpe,
Saeed Mahameed, Zhi Wang, Jonathan Cameron, Markus Probst,
Ira Weiny
Cc: Andreas Hindborg, Philipp Stanner, rust-for-linux, linux-kernel,
linux-mm, driver-core, linux-block, linux-security-module,
dri-devel, linux-fsdevel, linux-pm, linux-pci, linux-pwm,
linux-usb, linux-media, linaro-mm-sig, linux-serial,
Oliver Mangold, Viresh Kumar, Uwe Kleine-König,
Igor Korotin
From: Oliver Mangold <oliver.mangold@pm.me>
There are types where it may both be reference counted in some cases and
owned in others. For such types, obtaining an `ARef<T>` from a `&T` may be
unsound, as it allows creation of an `ARef<T>` from a `&Owned<T>`.
Therefore, we split `AlwaysRefCounted` into `RefCounted` (which `ARef<T>`
would require) and a marker trait to indicate that the `&T` -> `ARef<T>`
conversion is sound for the type. A type that implements `Ownable` may
only implement the marker trait if it allows an `ARef<T>` to exist
together with an `Owned<T>`.
- Rename `AlwaysRefCounted` to `RefCounted`.
- Add a new unsafe trait `AlwaysRefCounted`.
- Implement the new trait `AlwaysRefCounted` for the newly renamed
`RefCounted` implementations. This leaves functionality of existing
implementers of `AlwaysRefCounted` intact.
Suggested-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Oliver Mangold <oliver.mangold@pm.me>
[ Andreas: Updated commit message, rebased on v7.4-rc2, converted new
implementers, relaxed the `ForeignOwnable` bound for `ARef<T>`, updated
safety comments. ]
Acked-by: Igor Korotin <igor.korotin.linux@gmail.com>
Acked-by: Danilo Krummrich <dakr@kernel.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Co-developed-by: Andreas Hindborg <a.hindborg@kernel.org>
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
Acked-by: Uwe Kleine-König <ukleinek@kernel.org> # for pwm.rs
---
rust/kernel/auxiliary.rs | 10 ++++++-
rust/kernel/block/mq/request.rs | 17 +++++++----
rust/kernel/cred.rs | 16 ++++++++--
rust/kernel/device.rs | 12 ++++++--
rust/kernel/device/property.rs | 11 +++++--
rust/kernel/dma_buf/dma_fence.rs | 9 ++++--
rust/kernel/drm/device.rs | 9 ++++--
rust/kernel/drm/gem/mod.rs | 16 +++++++---
rust/kernel/drm/gpuvm/mod.rs | 9 ++++--
rust/kernel/drm/gpuvm/vm_bo.rs | 6 +++-
rust/kernel/fs/file.rs | 23 ++++++++++++---
rust/kernel/fwctl.rs | 9 ++++--
rust/kernel/i2c.rs | 13 +++++++--
rust/kernel/mm.rs | 23 ++++++++++++---
rust/kernel/mm/mmput_async.rs | 12 ++++++--
rust/kernel/opp.rs | 16 ++++++++--
rust/kernel/owned.rs | 2 +-
rust/kernel/pci.rs | 10 ++++++-
rust/kernel/pid_namespace.rs | 15 ++++++++--
rust/kernel/platform.rs | 10 ++++++-
rust/kernel/pwm.rs | 12 ++++++--
rust/kernel/serdev.rs | 11 +++++--
rust/kernel/sync/aref.rs | 63 +++++++++++++++++++++++++---------------
rust/kernel/task.rs | 13 +++++++--
rust/kernel/types.rs | 12 ++++++--
rust/kernel/usb.rs | 17 +++++++++--
rust/kernel/workqueue.rs | 8 ++---
27 files changed, 297 insertions(+), 87 deletions(-)
diff --git a/rust/kernel/auxiliary.rs b/rust/kernel/auxiliary.rs
index 9d3de109b381..4e7b21815a5d 100644
--- a/rust/kernel/auxiliary.rs
+++ b/rust/kernel/auxiliary.rs
@@ -19,6 +19,10 @@
to_result, //
},
prelude::*,
+ sync::aref::{
+ AlwaysRefCounted,
+ RefCounted, //
+ },
types::{
CovariantForLt,
ForLt,
@@ -389,7 +393,7 @@ unsafe impl<Ctx: device::DeviceContext> device::AsBusDevice<Ctx> for Device<Ctx>
kernel::impl_device_context_into_aref!(Device);
// SAFETY: Instances of `Device` are always reference-counted.
-unsafe impl crate::sync::aref::AlwaysRefCounted for Device {
+unsafe impl RefCounted for Device {
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
unsafe { bindings::get_device(self.as_ref().as_raw()) };
@@ -408,6 +412,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount
+// is non-zero and it is okay to obtain an `ARef<Device>` from it.
+unsafe impl AlwaysRefCounted for Device {}
+
impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
fn as_ref(&self) -> &device::Device<Ctx> {
// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
diff --git a/rust/kernel/block/mq/request.rs b/rust/kernel/block/mq/request.rs
index 6115f9aec228..12df305ade3e 100644
--- a/rust/kernel/block/mq/request.rs
+++ b/rust/kernel/block/mq/request.rs
@@ -11,7 +11,8 @@
sync::{
aref::{
ARef,
- AlwaysRefCounted, //
+ AlwaysRefCounted,
+ RefCounted, //
},
atomic::Relaxed,
Refcount, //
@@ -235,11 +236,10 @@ unsafe impl<T: Operations> Send for Request<T> {}
// mutate `self` are internally synchronized`
unsafe impl<T: Operations> Sync for Request<T> {}
-// SAFETY: All instances of `Request<T>` are reference counted. This
-// implementation of `AlwaysRefCounted` ensure that increments to the ref count
-// keeps the object alive in memory at least until a matching reference count
-// decrement is executed.
-unsafe impl<T: Operations> AlwaysRefCounted for Request<T> {
+// SAFETY: All instances of `Request<T>` are reference counted. This implementation of `RefCounted`
+// ensure that increments to the ref count keeps the object alive in memory at least until a
+// matching reference count decrement is executed.
+unsafe impl<T: Operations> RefCounted for Request<T> {
fn inc_ref(&self) {
self.wrapper_ref().refcount().inc();
}
@@ -261,3 +261,8 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Self>) {
}
}
}
+
+// SAFETY: All instances of `Request<T>` are currently reference counted, so a `&Request<T>` proves
+// that the refcount is non-zero and it is okay to obtain an `ARef<Request<T>>` from it (but this
+// will change in the future).
+unsafe impl<T: Operations> AlwaysRefCounted for Request<T> {}
diff --git a/rust/kernel/cred.rs b/rust/kernel/cred.rs
index ffa156b9df37..8b7517c908e5 100644
--- a/rust/kernel/cred.rs
+++ b/rust/kernel/cred.rs
@@ -8,7 +8,15 @@
//!
//! Reference: <https://www.kernel.org/doc/html/latest/security/credentials.html>
-use crate::{bindings, sync::aref::AlwaysRefCounted, task::Kuid, types::Opaque};
+use crate::{
+ bindings,
+ sync::aref::RefCounted,
+ task::Kuid,
+ types::{
+ AlwaysRefCounted,
+ Opaque, //
+ }, //
+};
/// Wraps the kernel's `struct cred`.
///
@@ -76,7 +84,7 @@ pub fn euid(&self) -> Kuid {
}
// SAFETY: The type invariants guarantee that `Credential` is always ref-counted.
-unsafe impl AlwaysRefCounted for Credential {
+unsafe impl RefCounted for Credential {
#[inline]
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -90,3 +98,7 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Credential>) {
unsafe { bindings::put_cred(obj.cast().as_ptr()) };
}
}
+
+// SAFETY: All instances of `Credential` are reference counted, so a `&Credential` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<Credential>` from it.
+unsafe impl AlwaysRefCounted for Credential {}
diff --git a/rust/kernel/device.rs b/rust/kernel/device.rs
index 2291d85b6849..c17436358940 100644
--- a/rust/kernel/device.rs
+++ b/rust/kernel/device.rs
@@ -8,8 +8,12 @@
bindings,
fmt,
prelude::*,
- sync::aref::ARef,
+ sync::aref::{
+ ARef,
+ RefCounted, //
+ },
types::{
+ AlwaysRefCounted,
ForeignOwnable,
Opaque, //
}, //
@@ -435,7 +439,7 @@ pub fn name(&self) -> &CStr {
kernel::impl_device_context_into_aref!(Device);
// SAFETY: Instances of `Device` are always reference-counted.
-unsafe impl crate::sync::aref::AlwaysRefCounted for Device {
+unsafe impl RefCounted for Device {
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
unsafe { bindings::get_device(self.as_raw()) };
@@ -447,6 +451,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
}
}
+// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount
+// is non-zero and it is okay to obtain an `ARef<Device>` from it.
+unsafe impl AlwaysRefCounted for Device {}
+
// SAFETY: As by the type invariant `Device` can be sent to any thread.
unsafe impl Send for Device {}
diff --git a/rust/kernel/device/property.rs b/rust/kernel/device/property.rs
index 5aead835fbbc..2dedcfb028f2 100644
--- a/rust/kernel/device/property.rs
+++ b/rust/kernel/device/property.rs
@@ -14,7 +14,10 @@
fmt,
prelude::*,
str::{CStr, CString},
- sync::aref::ARef,
+ sync::aref::{
+ ARef,
+ AlwaysRefCounted, //
+ },
types::Opaque,
};
@@ -360,7 +363,7 @@ fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
}
// SAFETY: Instances of `FwNode` are always reference-counted.
-unsafe impl crate::sync::aref::AlwaysRefCounted for FwNode {
+unsafe impl crate::sync::aref::RefCounted for FwNode {
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference guarantees that the
// refcount is non-zero.
@@ -374,6 +377,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
}
}
+// SAFETY: All instances of `FwNode` are reference counted, so a `&FwNode` proves that the refcount
+// is non-zero and it is okay to obtain an `ARef<FwNode>` from it.
+unsafe impl AlwaysRefCounted for FwNode {}
+
enum Node<'a> {
Borrowed(&'a FwNode),
Owned(ARef<FwNode>),
diff --git a/rust/kernel/dma_buf/dma_fence.rs b/rust/kernel/dma_buf/dma_fence.rs
index 18a43e1bb442..7519a9bd3355 100644
--- a/rust/kernel/dma_buf/dma_fence.rs
+++ b/rust/kernel/dma_buf/dma_fence.rs
@@ -36,7 +36,8 @@
sync::{
aref::{
ARef,
- AlwaysRefCounted, //
+ AlwaysRefCounted,
+ RefCounted, //
},
atomic::{
Atomic,
@@ -565,7 +566,7 @@ pub unsafe fn from_raw<'a>(ptr: *mut bindings::dma_fence) -> &'a Self {
// SAFETY: These implement the C backends refcounting methods which are proven
// to work correctly.
-unsafe impl AlwaysRefCounted for Fence {
+unsafe impl RefCounted for Fence {
fn inc_ref(&self) {
// SAFETY: `self.as_raw()` is a pointer to a valid `struct dma_fence`.
unsafe { bindings::dma_fence_get(self.as_raw()) }
@@ -582,6 +583,10 @@ unsafe fn dec_ref(ptr: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Fence` are reference counted, so a `&Fence` proves that the refcount is
+// non-zero and it is okay to obtain an `ARef<Fence>` from it.
+unsafe impl AlwaysRefCounted for Fence {}
+
// Necessary to guarantee that `inner` always comes first and can be freed by C.
// Also useful for using casts instead of container_of().
#[repr(C)]
diff --git a/rust/kernel/drm/device.rs b/rust/kernel/drm/device.rs
index 6b88ade28e24..186d2cafb065 100644
--- a/rust/kernel/drm/device.rs
+++ b/rust/kernel/drm/device.rs
@@ -17,7 +17,8 @@
prelude::*,
sync::aref::{
ARef,
- AlwaysRefCounted, //
+ AlwaysRefCounted,
+ RefCounted, //
},
types::{
NotThreadSafe,
@@ -480,7 +481,7 @@ fn deref(&self) -> &Self::Target {
// SAFETY: DRM device objects are always reference counted and the get/put functions
// satisfy the requirements.
-unsafe impl<T: drm::Driver> AlwaysRefCounted for Device<T> {
+unsafe impl<T: drm::Driver> RefCounted for Device<T> {
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
unsafe { bindings::drm_dev_get(self.as_raw()) };
@@ -495,6 +496,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount
+// is non-zero and it is okay to obtain an `ARef<Device>` from it.
+unsafe impl<T: drm::Driver> AlwaysRefCounted for Device<T> {}
+
impl<T: drm::Driver> AsRef<T::ParentDevice<device::Normal>> for Device<T> {
fn as_ref(&self) -> &T::ParentDevice<device::Normal> {
// SAFETY: `bindings::drm_device::dev` is valid as long as the DRM device itself is valid,
diff --git a/rust/kernel/drm/gem/mod.rs b/rust/kernel/drm/gem/mod.rs
index 85657a39e146..31c50db479ce 100644
--- a/rust/kernel/drm/gem/mod.rs
+++ b/rust/kernel/drm/gem/mod.rs
@@ -21,7 +21,7 @@
prelude::*,
sync::aref::{
ARef,
- AlwaysRefCounted, //
+ RefCounted, //
},
types::Opaque,
};
@@ -34,7 +34,7 @@
#[cfg(CONFIG_RUST_DRM_GEM_SHMEM_HELPER)]
pub mod shmem;
-/// A macro for implementing [`AlwaysRefCounted`] for any GEM object type.
+/// A macro for implementing [`RefCounted`] for any GEM object type.
///
/// Since all GEM objects use the same refcounting scheme.
#[macro_export]
@@ -47,7 +47,7 @@ impl $( <$( $tparam_id:ident ),+> )? for $type:ty
)?
) => {
// SAFETY: All GEM objects are refcounted.
- unsafe impl $( <$( $tparam_id ),+> )? $crate::sync::aref::AlwaysRefCounted for $type
+ unsafe impl $( <$( $tparam_id ),+> )? $crate::sync::aref::RefCounted for $type
where
Self: IntoGEMObject,
$( $( $bind_param : $bind_trait ),+ )?
@@ -66,6 +66,14 @@ unsafe fn dec_ref(obj: core::ptr::NonNull<Self>) {
unsafe { bindings::drm_gem_object_put(obj) };
}
}
+
+ // SAFETY: All instances of `$type` are reference counted, so a `&$type` proves that the
+ // refcount is non-zero and it is okay to obtain an `ARef<$type>` from it.
+ unsafe impl $( <$( $tparam_id ),+> )? $crate::sync::aref::AlwaysRefCounted for $type
+ where
+ Self: IntoGEMObject,
+ $( $( $bind_param : $bind_trait ),+ )?
+ {}
};
}
#[cfg_attr(not(CONFIG_RUST_DRM_GEM_SHMEM_HELPER), allow(unused))]
@@ -197,7 +205,7 @@ fn create_handle<D, F>(&self, file: &drm::File<F>) -> Result<u32>
/// Looks up an object by its handle for a given `File`.
fn lookup_handle<D, F>(file: &drm::File<F>, handle: u32) -> Result<ARef<Self>>
where
- Self: AllocImpl<Driver = D> + AlwaysRefCounted,
+ Self: AllocImpl<Driver = D> + RefCounted,
D: drm::Driver<Object = Self, File = F>,
F: drm::file::DriverFile<Driver = D>,
{
diff --git a/rust/kernel/drm/gpuvm/mod.rs b/rust/kernel/drm/gpuvm/mod.rs
index d9d43d719761..84590e673349 100644
--- a/rust/kernel/drm/gpuvm/mod.rs
+++ b/rust/kernel/drm/gpuvm/mod.rs
@@ -22,7 +22,8 @@
prelude::*,
sync::aref::{
ARef,
- AlwaysRefCounted, //
+ AlwaysRefCounted,
+ RefCounted, //
},
types::Opaque, //
};
@@ -81,7 +82,7 @@ unsafe impl<T: DriverGpuVm> Send for GpuVm<T> {}
unsafe impl<T: DriverGpuVm> Sync for GpuVm<T> {}
// SAFETY: By type invariants, the allocation is managed by the refcount in `self.vm`.
-unsafe impl<T: DriverGpuVm> AlwaysRefCounted for GpuVm<T> {
+unsafe impl<T: DriverGpuVm> RefCounted for GpuVm<T> {
fn inc_ref(&self) {
// SAFETY: By type invariants, the allocation is managed by the refcount in `self.vm`.
unsafe { bindings::drm_gpuvm_get(self.vm.get()) };
@@ -93,6 +94,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `GpuVm<T>` are reference counted, so a `&GpuVm<T>` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<GpuVm<T>>` from it.
+unsafe impl<T: DriverGpuVm> AlwaysRefCounted for GpuVm<T> {}
+
impl<T: DriverGpuVm> PartialEq for GpuVm<T> {
#[inline]
fn eq(&self, other: &Self) -> bool {
diff --git a/rust/kernel/drm/gpuvm/vm_bo.rs b/rust/kernel/drm/gpuvm/vm_bo.rs
index 5989972da829..7f311ea7a128 100644
--- a/rust/kernel/drm/gpuvm/vm_bo.rs
+++ b/rust/kernel/drm/gpuvm/vm_bo.rs
@@ -29,7 +29,7 @@ unsafe impl<T: DriverGpuVm> Send for GpuVmBo<T> {}
unsafe impl<T: DriverGpuVm> Sync for GpuVmBo<T> {}
// SAFETY: By type invariants, the allocation is managed by the refcount in `self.inner`.
-unsafe impl<T: DriverGpuVm> AlwaysRefCounted for GpuVmBo<T> {
+unsafe impl<T: DriverGpuVm> RefCounted for GpuVmBo<T> {
fn inc_ref(&self) {
// SAFETY: By type invariants, the allocation is managed by the refcount in `self.inner`.
unsafe { bindings::drm_gpuvm_bo_get(self.inner.get()) };
@@ -44,6 +44,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `GpuVmBo<T>` are reference counted, so a `&GpuVmBo<T>` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<GpuVmBo<T>>` from it.
+unsafe impl<T: DriverGpuVm> AlwaysRefCounted for GpuVmBo<T> {}
+
impl<T: DriverGpuVm> PartialEq for GpuVmBo<T> {
#[inline]
fn eq(&self, other: &Self) -> bool {
diff --git a/rust/kernel/fs/file.rs b/rust/kernel/fs/file.rs
index 23ee689bd240..f78c92df054c 100644
--- a/rust/kernel/fs/file.rs
+++ b/rust/kernel/fs/file.rs
@@ -12,8 +12,15 @@
cred::Credential,
error::{code::*, to_result, Error, Result},
fmt,
- sync::aref::{ARef, AlwaysRefCounted},
- types::{NotThreadSafe, Opaque},
+ sync::aref::{
+ ARef,
+ RefCounted, //
+ },
+ types::{
+ AlwaysRefCounted,
+ NotThreadSafe,
+ Opaque, //
+ }, //
};
use core::ptr;
@@ -197,7 +204,7 @@ unsafe impl Sync for File {}
// SAFETY: The type invariants guarantee that `File` is always ref-counted. This implementation
// makes `ARef<File>` own a normal refcount.
-unsafe impl AlwaysRefCounted for File {
+unsafe impl RefCounted for File {
#[inline]
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -212,6 +219,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<File>) {
}
}
+// SAFETY: All instances of `File` are reference counted, so a `&File` proves that the refcount is
+// non-zero and it is okay to obtain an `ARef<File>` from it.
+unsafe impl AlwaysRefCounted for File {}
+
/// Wraps the kernel's `struct file`. Not thread safe.
///
/// This type represents a file that is not known to be safe to transfer across thread boundaries.
@@ -233,7 +244,7 @@ pub struct LocalFile {
// SAFETY: The type invariants guarantee that `LocalFile` is always ref-counted. This implementation
// makes `ARef<LocalFile>` own a normal refcount.
-unsafe impl AlwaysRefCounted for LocalFile {
+unsafe impl RefCounted for LocalFile {
#[inline]
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -249,6 +260,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<LocalFile>) {
}
}
+// SAFETY: All instances of `LocalFile` are reference counted, so a `&LocalFile` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<LocalFile>` from it.
+unsafe impl AlwaysRefCounted for LocalFile {}
+
impl LocalFile {
/// Constructs a new `struct file` wrapper from a file descriptor.
///
diff --git a/rust/kernel/fwctl.rs b/rust/kernel/fwctl.rs
index b7778e4d5ee0..e68a1963f758 100644
--- a/rust/kernel/fwctl.rs
+++ b/rust/kernel/fwctl.rs
@@ -11,7 +11,8 @@
prelude::*,
sync::aref::{
ARef,
- AlwaysRefCounted, //
+ AlwaysRefCounted,
+ RefCounted, //
},
types::Opaque, //
};
@@ -259,7 +260,7 @@ fn as_ref(&self) -> &device::Device {
// SAFETY: `fwctl_get` increments the refcount of a valid fwctl_device.
// `fwctl_put` decrements it and frees the device when it reaches zero.
-unsafe impl<T: Operations> AlwaysRefCounted for Device<T> {
+unsafe impl<T: Operations> RefCounted for Device<T> {
#[inline]
fn inc_ref(&self) {
// SAFETY: `self` holds a live reference.
@@ -273,6 +274,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Device<T>` are reference counted, so a `&Device<T>` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<Device<T>>` from it.
+unsafe impl<T: Operations> AlwaysRefCounted for Device<T> {}
+
// SAFETY: `Device<T>` is refcounted by the fwctl core and may be released from any thread.
unsafe impl<T: Operations> Send for Device<T> {}
diff --git a/rust/kernel/i2c.rs b/rust/kernel/i2c.rs
index b4ff25c830fc..2dd18a0b8e68 100644
--- a/rust/kernel/i2c.rs
+++ b/rust/kernel/i2c.rs
@@ -17,7 +17,8 @@
prelude::*,
sync::aref::{
ARef,
- AlwaysRefCounted, //
+ AlwaysRefCounted,
+ RefCounted, //
},
types::Opaque, //
};
@@ -414,7 +415,7 @@ pub fn get(index: i32) -> Result<ARef<Self>> {
kernel::impl_device_context_into_aref!(I2cAdapter);
// SAFETY: Instances of `I2cAdapter` are always reference-counted.
-unsafe impl AlwaysRefCounted for I2cAdapter {
+unsafe impl RefCounted for I2cAdapter {
#[inline]
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
@@ -427,6 +428,9 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
unsafe { bindings::i2c_put_adapter(obj.as_ref().as_raw()) }
}
}
+// SAFETY: All instances of `I2cAdapter` are reference counted, so a `&I2cAdapter` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<I2cAdapter>` from it.
+unsafe impl AlwaysRefCounted for I2cAdapter {}
/// The i2c board info representation
///
@@ -492,7 +496,7 @@ unsafe impl<Ctx: device::DeviceContext> device::AsBusDevice<Ctx> for I2cClient<C
kernel::impl_device_context_into_aref!(I2cClient);
// SAFETY: Instances of `I2cClient` are always reference-counted.
-unsafe impl AlwaysRefCounted for I2cClient {
+unsafe impl RefCounted for I2cClient {
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
unsafe { bindings::get_device(self.as_ref().as_raw()) };
@@ -503,6 +507,9 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
unsafe { bindings::put_device(&raw mut (*obj.as_ref().as_raw()).dev) }
}
}
+// SAFETY: All instances of `I2cClient` are reference counted, so a `&I2cClient` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<I2cClient>` from it.
+unsafe impl AlwaysRefCounted for I2cClient {}
impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for I2cClient<Ctx> {
fn as_ref(&self) -> &device::Device<Ctx> {
diff --git a/rust/kernel/mm.rs b/rust/kernel/mm.rs
index 58bc1793fdaf..2d52a91990e4 100644
--- a/rust/kernel/mm.rs
+++ b/rust/kernel/mm.rs
@@ -13,8 +13,15 @@
use crate::{
bindings,
- sync::aref::{ARef, AlwaysRefCounted},
- types::{NotThreadSafe, Opaque},
+ sync::aref::{
+ ARef,
+ RefCounted, //
+ },
+ types::{
+ AlwaysRefCounted,
+ NotThreadSafe,
+ Opaque, //
+ }, //
};
use core::{ops::Deref, ptr::NonNull};
@@ -55,7 +62,7 @@ unsafe impl Send for Mm {}
unsafe impl Sync for Mm {}
// SAFETY: By the type invariants, this type is always refcounted.
-unsafe impl AlwaysRefCounted for Mm {
+unsafe impl RefCounted for Mm {
#[inline]
fn inc_ref(&self) {
// SAFETY: The pointer is valid since self is a reference.
@@ -69,6 +76,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Mm` are reference counted, so a `&Mm` proves that the refcount is
+// non-zero and it is okay to obtain an `ARef<Mm>` from it.
+unsafe impl AlwaysRefCounted for Mm {}
+
/// A wrapper for the kernel's `struct mm_struct`.
///
/// This type is like [`Mm`], but with non-zero `mm_users`. It can only be used when `mm_users` can
@@ -91,7 +102,7 @@ unsafe impl Send for MmWithUser {}
unsafe impl Sync for MmWithUser {}
// SAFETY: By the type invariants, this type is always refcounted.
-unsafe impl AlwaysRefCounted for MmWithUser {
+unsafe impl RefCounted for MmWithUser {
#[inline]
fn inc_ref(&self) {
// SAFETY: The pointer is valid since self is a reference.
@@ -105,6 +116,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `MmWithUser` are reference counted, so a `&MmWithUser` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<MmWithUser>` from it.
+unsafe impl AlwaysRefCounted for MmWithUser {}
+
// Make all `Mm` methods available on `MmWithUser`.
impl Deref for MmWithUser {
type Target = Mm;
diff --git a/rust/kernel/mm/mmput_async.rs b/rust/kernel/mm/mmput_async.rs
index b8d2f051225c..77e0aa1e6dc1 100644
--- a/rust/kernel/mm/mmput_async.rs
+++ b/rust/kernel/mm/mmput_async.rs
@@ -10,7 +10,11 @@
use crate::{
bindings,
mm::MmWithUser,
- sync::aref::{ARef, AlwaysRefCounted},
+ sync::aref::{
+ ARef,
+ RefCounted, //
+ },
+ types::AlwaysRefCounted,
};
use core::{ops::Deref, ptr::NonNull};
@@ -34,7 +38,7 @@ unsafe impl Send for MmWithUserAsync {}
unsafe impl Sync for MmWithUserAsync {}
// SAFETY: By the type invariants, this type is always refcounted.
-unsafe impl AlwaysRefCounted for MmWithUserAsync {
+unsafe impl RefCounted for MmWithUserAsync {
#[inline]
fn inc_ref(&self) {
// SAFETY: The pointer is valid since self is a reference.
@@ -48,6 +52,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `MmWithUserAsync` are reference counted, so a `&MmWithUserAsync` proves
+// that the refcount is non-zero and it is okay to obtain an `ARef<MmWithUserAsync>` from it.
+unsafe impl AlwaysRefCounted for MmWithUserAsync {}
+
// Make all `MmWithUser` methods available on `MmWithUserAsync`.
impl Deref for MmWithUserAsync {
type Target = MmWithUser;
diff --git a/rust/kernel/opp.rs b/rust/kernel/opp.rs
index 62e44676125d..949811d6b82e 100644
--- a/rust/kernel/opp.rs
+++ b/rust/kernel/opp.rs
@@ -16,8 +16,14 @@
ffi::{c_char, c_ulong},
prelude::*,
str::CString,
- sync::aref::{ARef, AlwaysRefCounted},
- types::Opaque,
+ sync::aref::{
+ ARef,
+ RefCounted, //
+ },
+ types::{
+ AlwaysRefCounted,
+ Opaque, //
+ }, //
};
#[cfg(CONFIG_CPU_FREQ)]
@@ -1041,7 +1047,7 @@ unsafe impl Send for OPP {}
unsafe impl Sync for OPP {}
/// SAFETY: The type invariants guarantee that [`OPP`] is always refcounted.
-unsafe impl AlwaysRefCounted for OPP {
+unsafe impl RefCounted for OPP {
#[inline]
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -1055,6 +1061,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
}
}
+// SAFETY: All instances of `OPP` are reference counted, so a `&OPP` proves that the refcount is
+// non-zero and it is okay to obtain an `ARef<OPP>` from it.
+unsafe impl AlwaysRefCounted for OPP {}
+
impl OPP {
/// Creates an owned reference to a [`OPP`] from a valid pointer.
///
diff --git a/rust/kernel/owned.rs b/rust/kernel/owned.rs
index c255420f8383..bfc52bc7f645 100644
--- a/rust/kernel/owned.rs
+++ b/rust/kernel/owned.rs
@@ -28,7 +28,7 @@
///
/// Note: The underlying object is not required to provide internal reference counting, because it
/// represents a unique, owned reference. If reference counting (on the Rust side) is required,
-/// [`AlwaysRefCounted`](crate::sync::aref::AlwaysRefCounted) should be implemented.
+/// [`RefCounted`](crate::types::RefCounted) should be implemented.
///
/// # Access model
///
diff --git a/rust/kernel/pci.rs b/rust/kernel/pci.rs
index 769d01d23429..b3266c2d3e26 100644
--- a/rust/kernel/pci.rs
+++ b/rust/kernel/pci.rs
@@ -20,6 +20,10 @@
io::resource,
prelude::*,
str::CStr,
+ sync::aref::{
+ AlwaysRefCounted,
+ RefCounted, //
+ },
types::Opaque,
ThisModule, //
};
@@ -510,7 +514,7 @@ unsafe impl<Ctx: device::DeviceContext> device::AsBusDevice<Ctx> for Device<Ctx>
impl<'a> crate::dma::Device<'a> for Device<device::Core<'a>> {}
// SAFETY: Instances of `Device` are always reference-counted.
-unsafe impl crate::sync::aref::AlwaysRefCounted for Device {
+unsafe impl RefCounted for Device {
#[inline]
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
@@ -524,6 +528,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount
+// is non-zero and it is okay to obtain an `ARef<Device>` from it.
+unsafe impl AlwaysRefCounted for Device {}
+
impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
fn as_ref(&self) -> &device::Device<Ctx> {
// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
diff --git a/rust/kernel/pid_namespace.rs b/rust/kernel/pid_namespace.rs
index 979a9718f153..e67e098582e5 100644
--- a/rust/kernel/pid_namespace.rs
+++ b/rust/kernel/pid_namespace.rs
@@ -7,7 +7,14 @@
//! C header: [`include/linux/pid_namespace.h`](srctree/include/linux/pid_namespace.h) and
//! [`include/linux/pid.h`](srctree/include/linux/pid.h)
-use crate::{bindings, sync::aref::AlwaysRefCounted, types::Opaque};
+use crate::{
+ bindings,
+ sync::aref::RefCounted,
+ types::{
+ AlwaysRefCounted,
+ Opaque, //
+ }, //
+};
use core::ptr;
/// Wraps the kernel's `struct pid_namespace`. Thread safe.
@@ -41,7 +48,7 @@ pub unsafe fn from_ptr<'a>(ptr: *const bindings::pid_namespace) -> &'a Self {
}
// SAFETY: Instances of `PidNamespace` are always reference-counted.
-unsafe impl AlwaysRefCounted for PidNamespace {
+unsafe impl RefCounted for PidNamespace {
#[inline]
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -55,6 +62,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<PidNamespace>) {
}
}
+// SAFETY: All instances of `PidNamespace` are reference counted, so a `&PidNamespace` proves that
+// the refcount is non-zero and it is okay to obtain an `ARef<PidNamespace>` from it.
+unsafe impl AlwaysRefCounted for PidNamespace {}
+
// SAFETY:
// - `PidNamespace::dec_ref` can be called from any thread.
// - It is okay to send ownership of `PidNamespace` across thread boundaries.
diff --git a/rust/kernel/platform.rs b/rust/kernel/platform.rs
index ac0a012ae1bb..5225916897a8 100644
--- a/rust/kernel/platform.rs
+++ b/rust/kernel/platform.rs
@@ -24,6 +24,10 @@
},
of,
prelude::*,
+ sync::aref::{
+ AlwaysRefCounted,
+ RefCounted, //
+ },
types::Opaque,
ThisModule, //
};
@@ -534,7 +538,7 @@ pub fn optional_irq_by_name(&self, name: &CStr) -> Result<IrqRequest<'_>> {
impl<'a> crate::dma::Device<'a> for Device<device::Core<'a>> {}
// SAFETY: Instances of `Device` are always reference-counted.
-unsafe impl crate::sync::aref::AlwaysRefCounted for Device {
+unsafe impl RefCounted for Device {
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference guarantees that the refcount is non-zero.
unsafe { bindings::get_device(self.as_ref().as_raw()) };
@@ -546,6 +550,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount
+// is non-zero and it is okay to obtain an `ARef<Device>` from it.
+unsafe impl AlwaysRefCounted for Device {}
+
impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
fn as_ref(&self) -> &device::Device<Ctx> {
// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
diff --git a/rust/kernel/pwm.rs b/rust/kernel/pwm.rs
index 8aa47304bec3..9e3af0f8d807 100644
--- a/rust/kernel/pwm.rs
+++ b/rust/kernel/pwm.rs
@@ -13,7 +13,11 @@
devres,
error::{self, to_result},
prelude::*,
- sync::aref::{ARef, AlwaysRefCounted},
+ sync::aref::{
+ ARef,
+ AlwaysRefCounted,
+ RefCounted, //
+ },
types::Opaque, //
};
use core::{
@@ -627,7 +631,7 @@ pub fn new<'a>(
}
// SAFETY: Implements refcounting for `Chip` using the embedded `struct device`.
-unsafe impl<T: PwmOps> AlwaysRefCounted for Chip<T> {
+unsafe impl<T: PwmOps> RefCounted for Chip<T> {
#[inline]
fn inc_ref(&self) {
// SAFETY: `self.0.get()` points to a valid `pwm_chip` because `self` exists.
@@ -645,6 +649,10 @@ unsafe fn dec_ref(obj: NonNull<Chip<T>>) {
}
}
+// SAFETY: All instances of `Chip<T>` are reference counted, so a `&Chip<T>` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<Chip<T>>` from it.
+unsafe impl<T: PwmOps> AlwaysRefCounted for Chip<T> {}
+
// SAFETY: `Chip` is a wrapper around `*mut bindings::pwm_chip`. The underlying C
// structure's state is managed and synchronized by the kernel's device model
// and PWM core locking mechanisms. Therefore, it is safe to move the `Chip`
diff --git a/rust/kernel/serdev.rs b/rust/kernel/serdev.rs
index 17ca504b7f8d..18f34b9959fd 100644
--- a/rust/kernel/serdev.rs
+++ b/rust/kernel/serdev.rs
@@ -17,7 +17,10 @@
of,
prelude::*,
sync::{
- aref::AlwaysRefCounted,
+ aref::{
+ AlwaysRefCounted,
+ RefCounted, //
+ },
Mutex, //
},
time::Jiffies,
@@ -570,7 +573,7 @@ unsafe impl<Ctx: device::DeviceContext> device::AsBusDevice<Ctx> for Device<Ctx>
kernel::impl_device_context_into_aref!(Device);
// SAFETY: Instances of `Device` are always reference-counted.
-unsafe impl AlwaysRefCounted for Device {
+unsafe impl RefCounted for Device {
fn inc_ref(&self) {
self.as_ref().inc_ref();
}
@@ -581,6 +584,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount
+// is non-zero and it is okay to obtain an `ARef<Device>` from it.
+unsafe impl AlwaysRefCounted for Device {}
+
impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
fn as_ref(&self) -> &device::Device<Ctx> {
// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
diff --git a/rust/kernel/sync/aref.rs b/rust/kernel/sync/aref.rs
index 1876e40c76df..6bc58aae38ed 100644
--- a/rust/kernel/sync/aref.rs
+++ b/rust/kernel/sync/aref.rs
@@ -11,7 +11,7 @@
//! underlying object, but this refcount is internal to the object. It essentially is a Rust
//! implementation of the `get_` and `put_` pattern used in C for reference counting.
//!
-//! To make use of [`ARef<MyType>`], `MyType` needs to implement [`AlwaysRefCounted`]. It is a trait
+//! To make use of [`ARef<MyType>`], `MyType` needs to implement [`RefCounted`]. It is a trait
//! for accessing the internal reference count of an object of the `MyType` type.
//!
//! [`Arc`]: crate::sync::Arc
@@ -29,11 +29,9 @@
types::ForeignOwnable, //
};
-/// Types that are _always_ reference counted.
+/// Types that are internally 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
@@ -50,9 +48,8 @@
/// 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 {
+/// won't be able to honour the requirement that [`RefCounted::inc_ref`] keep the object alive.)
+pub unsafe trait RefCounted {
/// Increments the reference count on the object.
fn inc_ref(&self);
@@ -65,11 +62,29 @@ pub unsafe trait AlwaysRefCounted {
/// 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).
+ /// (e.g., it calls [`RefCounted::inc_ref`] twice, then calls [`RefCounted::dec_ref`] once).
unsafe fn dec_ref(obj: NonNull<Self>);
}
+/// Always reference-counted type.
+///
+/// It allows deriving a counted reference [`ARef<T>`] from a `&T`.
+///
+/// This provides some convenience, but it allows "escaping" borrow checks on `&T`. As it
+/// complicates attempts to ensure that a reference to T is unique, it is optional to provide for
+/// [`RefCounted`] types. See *Safety* below.
+///
+/// # Safety
+///
+/// Implementers must ensure that no safety invariants are violated by upgrading an `&T` to an
+/// [`ARef<T>`]. In particular, an [`Owned<T>`] can be dereferenced into an `&T`, and an [`ARef<T>`]
+/// can be obtained from that. Thus, a type that implements [`Ownable`](crate::types::Ownable) must
+/// only implement [`AlwaysRefCounted`] if it allows an [`ARef<T>`] to exist together with an
+/// [`Owned<T>`]. See the *Access model* section of [`Ownable`](crate::types::Ownable).
+///
+/// [`Owned<T>`]: crate::types::Owned
+pub unsafe trait AlwaysRefCounted: RefCounted {}
+
/// An owned reference to an always-reference-counted object.
///
/// The object's reference count is automatically decremented when an instance of [`ARef`] is
@@ -80,7 +95,7 @@ pub unsafe trait AlwaysRefCounted {
///
/// 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> {
+pub struct ARef<T: RefCounted> {
ptr: NonNull<T>,
_p: PhantomData<T>,
}
@@ -89,19 +104,19 @@ pub struct ARef<T: AlwaysRefCounted> {
// it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally, it needs
// `T` to be `Send` because any thread that has an `ARef<T>` may ultimately access `T` using a
// mutable reference, for example, when the reference count reaches zero and `T` is dropped.
-unsafe impl<T: AlwaysRefCounted + Sync + Send> Send for ARef<T> {}
+unsafe impl<T: RefCounted + Sync + Send> Send for ARef<T> {}
// SAFETY: It is safe to send `&ARef<T>` to another thread when the underlying `T` is `Sync`
// because it effectively means sharing `&T` (which is safe because `T` is `Sync`); additionally,
// it needs `T` to be `Send` because any thread that has a `&ARef<T>` may clone it and get an
// `ARef<T>` on that thread, so the thread may ultimately access `T` using a mutable reference, for
// example, when the reference count reaches zero and `T` is dropped.
-unsafe impl<T: AlwaysRefCounted + Sync + Send> Sync for ARef<T> {}
+unsafe impl<T: RefCounted + Sync + Send> Sync for ARef<T> {}
// Even if `T` is pinned, pointers to `T` can still move.
-impl<T: AlwaysRefCounted> Unpin for ARef<T> {}
+impl<T: RefCounted> Unpin for ARef<T> {}
-impl<T: AlwaysRefCounted> ARef<T> {
+impl<T: RefCounted> ARef<T> {
/// Creates a new instance of [`ARef`].
///
/// It takes over an increment of the reference count on the underlying object.
@@ -130,12 +145,12 @@ pub unsafe fn from_raw(ptr: NonNull<T>) -> Self {
///
/// ```
/// use core::ptr::NonNull;
- /// use kernel::sync::aref::{ARef, AlwaysRefCounted};
+ /// use kernel::sync::aref::{ARef, RefCounted};
///
/// struct Empty {}
///
/// # // SAFETY: TODO.
- /// unsafe impl AlwaysRefCounted for Empty {
+ /// unsafe impl RefCounted for Empty {
/// fn inc_ref(&self) {}
/// unsafe fn dec_ref(_obj: NonNull<Self>) {}
/// }
@@ -153,7 +168,7 @@ pub fn into_raw(me: Self) -> NonNull<T> {
}
}
-impl<T: AlwaysRefCounted> Clone for ARef<T> {
+impl<T: RefCounted> Clone for ARef<T> {
fn clone(&self) -> Self {
self.inc_ref();
// SAFETY: We just incremented the refcount above.
@@ -161,7 +176,7 @@ fn clone(&self) -> Self {
}
}
-impl<T: AlwaysRefCounted> Deref for ARef<T> {
+impl<T: RefCounted> Deref for ARef<T> {
type Target = T;
fn deref(&self) -> &Self::Target {
@@ -178,7 +193,7 @@ fn from(b: &T) -> Self {
}
}
-impl<T: AlwaysRefCounted> Drop for ARef<T> {
+impl<T: RefCounted> Drop for ARef<T> {
fn drop(&mut self) {
// SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
// decrement.
@@ -188,19 +203,19 @@ fn drop(&mut self) {
impl<T, U> PartialEq<ARef<U>> for ARef<T>
where
- T: AlwaysRefCounted + PartialEq<U>,
- U: AlwaysRefCounted,
+ T: RefCounted + PartialEq<U>,
+ U: RefCounted,
{
#[inline]
fn eq(&self, other: &ARef<U>) -> bool {
T::eq(&**self, &**other)
}
}
-impl<T: AlwaysRefCounted + Eq> Eq for ARef<T> {}
+impl<T: RefCounted + Eq> Eq for ARef<T> {}
// SAFETY: `into_foreign` returns a pointer from `NonNull::as_ptr`, so it's non-null. The
// `ARef` invariant guarantees that `ptr` points to a valid `T`, so it's aligned to `T`.
-unsafe impl<T: AlwaysRefCounted> ForeignOwnable for ARef<T> {
+unsafe impl<T: RefCounted> ForeignOwnable for ARef<T> {
const FOREIGN_ALIGN: usize = core::mem::align_of::<T>();
type Borrowed<'a>
@@ -245,7 +260,7 @@ unsafe fn borrow_mut<'a>(ptr: *mut c_void) -> &'a T {
impl<T, U> PartialEq<&'_ U> for ARef<T>
where
- T: AlwaysRefCounted + PartialEq<U>,
+ T: RefCounted + PartialEq<U>,
{
#[inline]
fn eq(&self, other: &&U) -> bool {
diff --git a/rust/kernel/task.rs b/rust/kernel/task.rs
index 3336df493dec..bd106bb61d7c 100644
--- a/rust/kernel/task.rs
+++ b/rust/kernel/task.rs
@@ -10,7 +10,12 @@
pid_namespace::PidNamespace,
prelude::*,
sync::aref::ARef,
- types::{NotThreadSafe, Opaque},
+ types::{
+ AlwaysRefCounted,
+ NotThreadSafe,
+ Opaque,
+ RefCounted, //
+ },
};
use core::{
ops::Deref,
@@ -347,7 +352,7 @@ pub fn group_leader(&self) -> &Task {
}
// SAFETY: The type invariants guarantee that `Task` is always refcounted.
-unsafe impl crate::sync::aref::AlwaysRefCounted for Task {
+unsafe impl RefCounted for Task {
#[inline]
fn inc_ref(&self) {
// SAFETY: The existence of a shared reference means that the refcount is nonzero.
@@ -361,6 +366,10 @@ unsafe fn dec_ref(obj: ptr::NonNull<Self>) {
}
}
+// SAFETY: All instances of `Task` are reference counted, so a `&Task` proves that the refcount is
+// non-zero and it is okay to obtain an `ARef<Task>` from it.
+unsafe impl AlwaysRefCounted for Task {}
+
impl PartialEq for Task {
#[inline]
fn eq(&self, other: &Self) -> bool {
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index b23e1d60cdd6..f97b8ab6dad5 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -18,9 +18,15 @@
ForLt, //
};
-pub use crate::owned::{
- Ownable,
- Owned, //
+pub use crate::{
+ owned::{
+ Ownable,
+ Owned, //
+ },
+ sync::aref::{
+ AlwaysRefCounted,
+ RefCounted, //
+ }, //
};
/// Used to transfer ownership to and from foreign (non-Rust) languages.
diff --git a/rust/kernel/usb.rs b/rust/kernel/usb.rs
index 993760ff332b..89028041bca9 100644
--- a/rust/kernel/usb.rs
+++ b/rust/kernel/usb.rs
@@ -18,7 +18,10 @@
to_result, //
},
prelude::*,
- sync::aref::AlwaysRefCounted,
+ sync::aref::{
+ AlwaysRefCounted,
+ RefCounted, //
+ },
types::Opaque,
ThisModule, //
};
@@ -373,7 +376,7 @@ fn as_ref(&self) -> &Device {
}
// SAFETY: Instances of `Interface` are always reference-counted.
-unsafe impl AlwaysRefCounted for Interface {
+unsafe impl RefCounted for Interface {
#[inline]
fn inc_ref(&self) {
// SAFETY: The invariants of `Interface` guarantee that `self.as_raw()`
@@ -389,6 +392,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Interface` are reference counted, so a `&Interface` proves that the
+// refcount is non-zero and it is okay to obtain an `ARef<Interface>` from it.
+unsafe impl AlwaysRefCounted for Interface {}
+
// SAFETY: A `Interface` is always reference-counted and can be released from any thread.
unsafe impl Send for Interface {}
@@ -426,7 +433,7 @@ fn as_raw(&self) -> *mut bindings::usb_device {
kernel::impl_device_context_into_aref!(Device);
// SAFETY: Instances of `Device` are always reference-counted.
-unsafe impl AlwaysRefCounted for Device {
+unsafe impl RefCounted for Device {
#[inline]
fn inc_ref(&self) {
// SAFETY: The invariants of `Device` guarantee that `self.as_raw()`
@@ -442,6 +449,10 @@ unsafe fn dec_ref(obj: NonNull<Self>) {
}
}
+// SAFETY: All instances of `Device` are reference counted, so a `&Device` proves that the refcount
+// is non-zero and it is okay to obtain an `ARef<Device>` from it.
+unsafe impl AlwaysRefCounted for Device {}
+
impl<Ctx: device::DeviceContext> AsRef<device::Device<Ctx>> for Device<Ctx> {
fn as_ref(&self) -> &device::Device<Ctx> {
// SAFETY: By the type invariant of `Self`, `self.as_raw()` is a pointer to a valid
diff --git a/rust/kernel/workqueue.rs b/rust/kernel/workqueue.rs
index a872f9fffb90..528564b1f4f2 100644
--- a/rust/kernel/workqueue.rs
+++ b/rust/kernel/workqueue.rs
@@ -192,7 +192,7 @@
sync::{
aref::{
ARef,
- AlwaysRefCounted, //
+ RefCounted, //
},
Arc,
LockClassKey, //
@@ -954,7 +954,7 @@ unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for Pin<KBox<T>>
// implementation of `WorkItemPointer` for `ARef<T>`.
unsafe impl<T, const ID: u64> WorkItemPointer<ID> for ARef<T>
where
- T: AlwaysRefCounted,
+ T: RefCounted,
T: WorkItem<ID, Pointer = Self>,
T: HasWork<T, ID>,
{
@@ -987,7 +987,7 @@ unsafe impl<T, const ID: u64> WorkItemPointer<ID> for ARef<T>
// requirements of `WorkItemPointer`.
unsafe impl<T, const ID: u64> RawWorkItem<ID> for ARef<T>
where
- T: AlwaysRefCounted,
+ T: RefCounted,
T: WorkItem<ID, Pointer = Self>,
T: HasWork<T, ID>,
{
@@ -1020,7 +1020,7 @@ unsafe impl<T, const ID: u64> RawDelayedWorkItem<ID> for ARef<T>
where
T: WorkItem<ID, Pointer = Self>,
T: HasDelayedWork<T, ID>,
- T: AlwaysRefCounted,
+ T: RefCounted,
{
}
--
2.54.0
^ permalink raw reply [flat|nested] 6+ messages in thread* [PATCH v22 5/5] rust: Add `OwnableIntoShared` and `OwnableTryFromShared`
2026-11-16 14:20 [PATCH v22 0/5] rust: add `Ownable` trait and `Owned` type Andreas Hindborg
` (3 preceding siblings ...)
2026-11-16 14:21 ` [PATCH v22 4/5] rust: rename `AlwaysRefCounted` to `RefCounted` Andreas Hindborg
@ 2026-11-16 14:21 ` Andreas Hindborg
4 siblings, 0 replies; 6+ messages in thread
From: Andreas Hindborg @ 2026-11-16 14:21 UTC (permalink / raw)
To: Danilo Krummrich, Lorenzo Stoakes, Vlastimil Babka,
Liam R. Howlett, Uladzislau Rezki, Miguel Ojeda, Boqun Feng,
Gary Guo, Björn Roy Baron, Benno Lossin, Alice Ryhl,
Trevor Gross, Daniel Almeida, Tamir Duberstein,
Alexandre Courbot, Onur Özkan, Lyude Paul,
Greg Kroah-Hartman, Christian Brauner, Rafael J. Wysocki,
Dave Ertman, Leon Romanovsky, Paul Moore, Serge Hallyn,
David Airlie, Simona Vetter, Alexander Viro, Jan Kara,
Igor Korotin, Viresh Kumar, Nishanth Menon, Stephen Boyd,
Bjorn Helgaas, Krzysztof Wilczyński, Pavel Tikhomirov,
Michal Wilczynski, Ira Weiny, Matthew Brost,
Thomas Hellström, Johan Hovold, Sumit Semwal,
Christian König, Dave Jiang, Jason Gunthorpe,
Saeed Mahameed, Zhi Wang, Jonathan Cameron, Markus Probst,
Ira Weiny
Cc: Andreas Hindborg, Philipp Stanner, rust-for-linux, linux-kernel,
linux-mm, driver-core, linux-block, linux-security-module,
dri-devel, linux-fsdevel, linux-pm, linux-pci, linux-pwm,
linux-usb, linux-media, linaro-mm-sig, linux-serial,
Oliver Mangold
From: Oliver Mangold <oliver.mangold@pm.me>
Types implementing these traits can safely convert between an `ARef<T>`
and an `Owned<T>`.
`OwnableIntoShared` provides the infallible conversion from `Owned<T>`
to `ARef<T>`. `OwnableTryFromShared` provides the fallible conversion
from `ARef<T>` back to `Owned<T>`, which succeeds only when no `Owned<T>`
exists for the object and the requirements for creating one are
satisfied. For a type that does not allow other references to exist
together with an `Owned<T>`, this means that the `ARef<T>` must be the
only reference to the object.
The two conversions are provided by separate traits because they have
different conditions for existing. Some types can never become unique
again after having been shared, and such types can implement
`OwnableIntoShared` only.
This is useful for types which generally are accessed through an `ARef`
but have methods which can only safely be called when the reference is
unique, like e.g. `block::mq::Request::end_ok()`.
Signed-off-by: Oliver Mangold <oliver.mangold@pm.me>
[ Andreas: Fix formatting, update documentation, fix error handling in
examples. Split `OwnableRefCounted` into two traits. ]
Co-developed-by: Andreas Hindborg <a.hindborg@kernel.org>
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
---
rust/kernel/owned.rs | 165 ++++++++++++++++++++++++++++++++++++++++++++++-
rust/kernel/sync/aref.rs | 16 ++++-
rust/kernel/types.rs | 2 +
3 files changed, 181 insertions(+), 2 deletions(-)
diff --git a/rust/kernel/owned.rs b/rust/kernel/owned.rs
index bfc52bc7f645..5b71d264477e 100644
--- a/rust/kernel/owned.rs
+++ b/rust/kernel/owned.rs
@@ -14,6 +14,10 @@
pin::Pin,
ptr::NonNull, //
};
+use kernel::{
+ sync::aref::ARef,
+ types::RefCounted, //
+};
use kernel::types::ForeignOwnable;
@@ -28,7 +32,9 @@
///
/// Note: The underlying object is not required to provide internal reference counting, because it
/// represents a unique, owned reference. If reference counting (on the Rust side) is required,
-/// [`RefCounted`](crate::types::RefCounted) should be implemented.
+/// [`RefCounted`] should be implemented. [`OwnableIntoShared`] should be implemented if conversion
+/// from unique to shared (reference counted) ownership is needed, and [`OwnableTryFromShared`] if
+/// conversion from shared back to unique ownership is needed.
///
/// # Access model
///
@@ -329,3 +335,160 @@ unsafe fn borrow_mut<'a>(ptr: *mut kernel::ffi::c_void) -> Self::BorrowedMut<'a>
unsafe { Pin::new_unchecked(inner) }
}
}
+
+/// A trait for types that support converting a unique reference [`Owned<Self>`] into a shared
+/// reference [`ARef<Self>`].
+///
+/// The conversion consumes the [`Owned`], so it cannot fail. Implementing this trait does not make
+/// the opposite conversion available. Types that can become unique again after having been shared
+/// can implement [`OwnableTryFromShared`] in addition.
+///
+/// # Examples
+///
+/// A minimal example implementation of [`OwnableIntoShared`], [`OwnableTryFromShared`],
+/// [`Ownable`] and its usage with [`ARef`] and [`Owned`] looks like this:
+///
+/// ```
+/// # #![expect(clippy::disallowed_names)]
+/// # use core::ptr::NonNull;
+/// # use kernel::alloc::{flags, kbox::KBox, AllocError};
+/// # use kernel::sync::aref::{ARef, RefCounted};
+/// # use kernel::sync::atomic::Acquire;
+/// # use kernel::sync::Refcount;
+/// # use kernel::types::{Owned, Ownable, OwnableIntoShared, OwnableTryFromShared};
+/// // An internally refcounted struct for demonstration purposes.
+/// //
+/// // # Invariants
+/// //
+/// // - `refcount` counts the live references to the object, so the object is valid while
+/// // `refcount` is non-zero.
+/// // - `Foo` does not allow other references to exist together with an `Owned<Foo>`: while an
+/// // `Owned<Foo>` exists, `refcount` is 1 and no `ARef<Foo>` exists.
+/// struct Foo {
+/// refcount: Refcount,
+/// }
+///
+/// impl Foo {
+/// fn new() -> Result<Owned<Self>> {
+/// // We are just using a `KBox` here to handle the actual allocation, as our `Foo` is
+/// // not actually a C-allocated object.
+/// // INVARIANT: We initialize `refcount` to 1, counting the reference held by the
+/// // returned `Owned<Foo>`. No `ARef<Foo>` exists for the new object.
+/// let result = KBox::new(
+/// Foo {
+/// refcount: Refcount::new(1),
+/// },
+/// flags::GFP_KERNEL,
+/// )?;
+/// let result = KBox::into_non_null(result);
+/// // SAFETY:
+/// // - We just allocated the `Self`, thus it is valid until the refcount drops to zero.
+/// // - No other pointer to the allocation exists, so this is the only `Owned<Foo>` and
+/// // no other reference to the `Foo` exists. Thus access through the `Owned<Foo>` is
+/// // sound, and it can be used from any thread that `Foo` can be used from.
+/// // - The `Foo` is not moved until it is freed in `dec_ref`.
+/// Ok(unsafe { Owned::from_raw(result) })
+/// }
+/// }
+///
+/// // SAFETY: We increment and decrement the refcount each time the respective function is
+/// // called, and only free the `Foo` when the refcount reaches zero.
+/// unsafe impl RefCounted for Foo {
+/// fn inc_ref(&self) {
+/// self.refcount.inc();
+/// }
+///
+/// unsafe fn dec_ref(this: NonNull<Self>) {
+/// // SAFETY: By requirement on calling this function, the refcount is non-zero,
+/// // implying the underlying object is valid.
+/// let refcount = unsafe { &this.as_ref().refcount };
+/// if refcount.dec_and_test() {
+/// // SAFETY: The refcount reached zero, so by requirement on calling this function
+/// // no reference to the object remains and it will no longer be used. We can
+/// // reclaim the allocation by passing ownership back to the [`KBox`], which frees
+/// // the `Foo` when dropped.
+/// drop(unsafe { KBox::from_raw(this.as_ptr()) });
+/// }
+/// }
+/// }
+///
+/// impl OwnableIntoShared for Foo {
+/// fn into_shared(this: Owned<Self>) -> ARef<Self> {
+/// // SAFETY: By the type invariants of `Foo`, an `Owned<Foo>` holds the only reference
+/// // (refcount 1). We consume the `Owned<Foo>` and transfer the reference to the new
+/// // `ARef`.
+/// unsafe { ARef::from_raw(Owned::into_raw(this)) }
+/// }
+/// }
+///
+/// impl OwnableTryFromShared for Foo {
+/// fn try_from_shared(this: ARef<Self>) -> Result<Owned<Self>, ARef<Self>> {
+/// // `this` is a live reference, so the refcount cannot drop below 1, and it can only
+/// // grow through an existing reference. Thus observing 1 means that `this` is the only
+/// // reference to the object. The `Acquire` ordering synchronizes with the release
+/// // decrements of references dropped on other threads.
+/// if this.refcount.as_atomic().load(Acquire) == 1 {
+/// // SAFETY: The `Foo` is valid and `this` holds the only reference to it, so we
+/// // can transfer this last reference to the returned `Owned<Foo>`. No other
+/// // reference to the `Foo` exists, so this is the only `Owned<Foo>` and access
+/// // through it is sound. The `Foo` is not moved until it is freed in `dec_ref`.
+/// // INVARIANT: `refcount` is 1 and we consumed the only `ARef<Foo>`.
+/// Ok(unsafe { Owned::from_raw(ARef::into_raw(this)) })
+/// } else {
+/// Err(this)
+/// }
+/// }
+/// }
+///
+/// impl Ownable for Foo {
+/// unsafe fn release(this: NonNull<Self>) {
+/// // SAFETY: Using `dec_ref()` from [`RefCounted`] to release is okay, as the refcount is
+/// // always 1 for an [`Owned<Foo>`].
+/// unsafe { Foo::dec_ref(this) };
+/// }
+/// }
+///
+/// let foo = Foo::new()?;
+/// let foo = ARef::from(foo);
+/// {
+/// let bar = foo.clone();
+/// assert!(Owned::try_from(bar).is_err());
+/// }
+/// assert!(Owned::try_from(foo).is_ok());
+/// # Ok::<(), Error>(())
+/// ```
+pub trait OwnableIntoShared: RefCounted + Ownable + Sized {
+ /// Converts the [`Owned`] into an [`ARef`].
+ fn into_shared(this: Owned<Self>) -> ARef<Self>;
+}
+
+/// A trait for types that support converting a shared reference [`ARef<Self>`] back into a unique
+/// reference [`Owned<Self>`].
+///
+/// The conversion can only succeed when no [`Owned`] exists for the object, and when the
+/// requirements for creating one are satisfied, so it is fallible. For a type that does not allow
+/// other references to exist together with an [`Owned`], this means that the [`ARef`] must be the
+/// only reference to the object. See the *Access model* section of [`Ownable`].
+///
+/// Not all types that implement [`OwnableIntoShared`] are able to become unique again after having
+/// been shared, so this capability is provided by a separate trait.
+///
+/// # Examples
+///
+/// See the example for [`OwnableIntoShared`].
+pub trait OwnableTryFromShared: RefCounted + Ownable + Sized {
+ /// Checks if the [`ARef`] can be converted to an [`Owned`] and converts it if that is the case.
+ /// Otherwise it returns again an [`ARef`] to the same underlying object.
+ fn try_from_shared(this: ARef<Self>) -> Result<Owned<Self>, ARef<Self>>;
+}
+
+impl<T: OwnableTryFromShared> TryFrom<ARef<T>> for Owned<T> {
+ type Error = ARef<T>;
+ /// Tries to convert the [`ARef`] to an [`Owned`] by calling
+ /// [`try_from_shared()`](OwnableTryFromShared::try_from_shared). In case the conversion is not
+ /// possible, it returns again an [`ARef`] to the same underlying object.
+ #[inline]
+ fn try_from(b: ARef<T>) -> Result<Owned<T>, Self::Error> {
+ T::try_from_shared(b)
+ }
+}
diff --git a/rust/kernel/sync/aref.rs b/rust/kernel/sync/aref.rs
index 6bc58aae38ed..8a029d124fa3 100644
--- a/rust/kernel/sync/aref.rs
+++ b/rust/kernel/sync/aref.rs
@@ -23,6 +23,10 @@
ops::Deref,
ptr::NonNull, //
};
+use kernel::types::{
+ OwnableIntoShared,
+ Owned, //
+};
use crate::{
prelude::*,
@@ -40,7 +44,10 @@
/// Note: Implementing this trait allows types to be wrapped in an [`ARef<Self>`]. It requires an
/// internal reference count and provides only shared references. If unique references are required
/// [`Ownable`](crate::types::Ownable) should be implemented which allows types to be wrapped in an
-/// [`Owned<Self>`](crate::types::Owned).
+/// [`Owned<Self>`](crate::types::Owned). Implementing the trait [`OwnableIntoShared`] allows to
+/// convert a unique reference into a shared one (i.e. [`Owned<Self>`](crate::types::Owned) into
+/// [`ARef<Self>`]), and implementing
+/// [`OwnableTryFromShared`](crate::types::OwnableTryFromShared) allows to convert back.
///
/// # Safety
///
@@ -193,6 +200,13 @@ fn from(b: &T) -> Self {
}
}
+impl<T: OwnableIntoShared> From<Owned<T>> for ARef<T> {
+ #[inline]
+ fn from(b: Owned<T>) -> Self {
+ T::into_shared(b)
+ }
+}
+
impl<T: RefCounted> Drop for ARef<T> {
fn drop(&mut self) {
// SAFETY: The type invariants guarantee that the `ARef` owns the reference we're about to
diff --git a/rust/kernel/types.rs b/rust/kernel/types.rs
index f97b8ab6dad5..8905dd1c6c4e 100644
--- a/rust/kernel/types.rs
+++ b/rust/kernel/types.rs
@@ -21,6 +21,8 @@
pub use crate::{
owned::{
Ownable,
+ OwnableIntoShared,
+ OwnableTryFromShared,
Owned, //
},
sync::aref::{
--
2.54.0
^ permalink raw reply [flat|nested] 6+ messages in thread