From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from smtp.kernel.org (aws-us-west-2-korg-mail-alma10-1.taild15c8.ts.net [100.103.45.18]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id A14F03E0724; Thu, 10 Sep 2026 09:01:49 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=100.103.45.18 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789030918; cv=none; b=AdnCUG70zoNb59dmSk+5NLPUnemyVu8b/gkKeaKpsIyWZeNhZrOu8UWirL2vp0dFQr8AAmplrrPILNgOnmTfartaqxf15o7MFXLXYwgOl9PKM5vOZ1mB3PeN6n/TnYBpqsgZHSQZaMATtOplVzts7BaoQ8WfdctLGo6meaNaR+o= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1789030918; c=relaxed/simple; bh=fY1ZeofKGZP0R0vybxeg1uDiO6Ilyw3mZ+JLjl5dn54=; h=From:Date:Subject:MIME-Version:Content-Type:Message-Id:References: In-Reply-To:To:Cc; b=hMkeQdKnKm7IoXV1/jvdJyCp/wUr0usc9moye+CnMWxRdWlMK2C6+OW4BNOzsKpYpVQowLi1EO4HknbGd7F4t/UgWCA46Odh3L9+YX+IuHfP0urOz7gktww2aYDSCTksAs8hb1EEYCkdtV37pzAVqo9QxiruziQPGPgzYrEY8/k= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b=QZWIIJTB; arc=none smtp.client-ip=100.103.45.18 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=kernel.org header.i=@kernel.org header.b="QZWIIJTB" Received: by smtp.kernel.org (Postfix) with ESMTPSA id ECBD01F00898; Thu, 10 Sep 2026 09:01:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=kernel.org; s=k20260515; t=1789030907; bh=oG+KGaYcq/LrlTcZix6QO2VK530O5ka3Rs0mLGMUdtQ=; h=From:Date:Subject:References:In-Reply-To:To:Cc; b=QZWIIJTBzOkomxOJZk4c4zQ6MbJ0v3zPVJsPyIuRa5nV8nkbTJBgQpOwM6+eKWDwW NIWYg6lV2Rf5Pcf6Pwsk5vA7Bnybe4Z/p1arxTLXuDwSTp7ObNfBVWkf25B42ubZce JrYPgyGaiekosD4Cy4w3kQ+Ejq2uGfF+t5K5fY4jehr1pcWgw01Bo7i5DKJ89VCQBq 1U5UvB+GTawRXP7F4cSCrCWgzFN4cUfTBj1zVNVzwWOWYbhjvwp1D0bX4ipRzQg2fy Cb1rf4aYJxmh5rD4NiKaw1gkePmSaDBPnQ1+iuziDYde8t8lE4IiJk4cFdmmF0wDZW P7A4dDPt+2HAA== From: Andreas Hindborg Date: Thu, 10 Sep 2026 11:00:06 +0200 Subject: [PATCH v21 2/9] rust: types: Add Ownable/Owned types Precedence: bulk X-Mailing-List: linux-fsdevel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit Message-Id: <20260910-unique-ref-v21-2-e83257373062@kernel.org> References: <20260910-unique-ref-v21-0-e83257373062@kernel.org> In-Reply-To: <20260910-unique-ref-v21-0-e83257373062@kernel.org> To: Danilo Krummrich , Lorenzo Stoakes , Vlastimil Babka , "Liam R. Howlett" , Uladzislau Rezki , Miguel Ojeda , Boqun Feng , Gary Guo , =?utf-8?q?Bj=C3=B6rn_Roy_Baron?= , Benno Lossin , Alice Ryhl , Trevor Gross , Daniel Almeida , Tamir Duberstein , Alexandre Courbot , =?utf-8?q?Onur_=C3=96zkan?= , Lyude Paul , Greg Kroah-Hartman , =?utf-8?q?Arve_Hj=C3=B8nnev=C3=A5g?= , Todd Kjos , Christian Brauner , Carlos Llamas , "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 , =?utf-8?q?Krzysztof_Wilczy=C5=84ski?= , Pavel Tikhomirov , Michal Wilczynski , Ira Weiny , Matthew Brost , =?utf-8?q?Thomas_Hellstr=C3=B6m?= , Ira Weiny Cc: Andreas Hindborg , Philipp Stanner , rust-for-linux@vger.kernel.org, linux-kernel@vger.kernel.org, linux-mm@kvack.org, driver-core@lists.linux.dev, linux-block@vger.kernel.org, linux-security-module@vger.kernel.org, dri-devel@lists.freedesktop.org, linux-fsdevel@vger.kernel.org, linux-pm@vger.kernel.org, linux-pci@vger.kernel.org, linux-pwm@vger.kernel.org, linux-usb@vger.kernel.org, Asahi Lina , Oliver Mangold , Boqun Feng X-Mailer: b4 0.16.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=10889; i=a.hindborg@kernel.org; h=from:subject:message-id; bh=qRWbwqK7TEegrbGW6xNA+C4LOYo7zhHcjmaxGwUnwrg=; b=owEBbQKS/ZANAwAKAfpQKQiqxb3QAcsmYgBqonGiPIkyRWHCPutOl1uLHFVvk9aNknONcu/+h iyukNOXlNSJAjMEAAEKAB0WIQRXitnI2WZ2JirAaob6UCkIqsW90AUCaqJxogAKCRD6UCkIqsW9 0H2iD/94uZ+/2TTsjRDkp3mW4k6lM7pFW3XrwqmAvOnTUTZu/fd9IR+QhzSO8P2RZPMZqzu8cx4 D3OG/kExKrOKXYWb47NgduXUNtewyvIqQXlilx3UEhqXJ5+xwCqUlVVCsP7Od++epay7sGzPEgn RxcDpya/PX6yICJqUwI6DsvXvELp1E+2v8nknLgxh3Y0VZ1h/NE9FiEiV/2FggB4h61WOLJBeOY SKuAuBoyNmbBcGZaisPKZJUx0BW2OE22xQk4bcdv2oZA3VLB9g0/oIyGPtMCzTWzjZHTjQ9eYYs 3j+VB8hdgVG65zWngPJg2B5Ul7vEimDMz6T+FH517CAa79TxRWznfwe1F2L6wZMEYQEO7otFeOj 2O54Q2K6QyMj8fS/7KS/28tShfTswvS0a5PJnlcCm8vn3lHACVaRzDvutvcRAONo8XGwQXigoLv freczsK+iGeY3gRKwCvDOI2a6IfsQ/RsGxLxu92NY25A7R2V+iq/27kN1cSgdt9vtMlEf4dHhvH 0tQQmqrPVS5arR6l1vNiHgS7zxs6Jj3NMgks8mDrpeC9BWMASWH8ITGec0I1lVE8BohTBTKKTO2 CbXcw0QSI72C1tEGpi1JeTVLI45hI+Tp1POlcHXChhpsycUTtb0Vuy/zMUXfdjDDjpr33ehawQ7 h3SAu2vbn0U7HRg== X-Developer-Key: i=a.hindborg@kernel.org; a=openpgp; fpr=3108C10F46872E248D1FB221376EB100563EF7A7 From: Asahi Lina 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 `AlwaysRefCounted`, this mechanism expects the reference to be unique within Rust, and does not allow cloning. Conceptually, this is similar to a `KBox`, 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 Co-developed-by: Oliver Mangold Signed-off-by: Oliver Mangold Reviewed-by: Boqun Feng Reviewed-by: Daniel Almeida Reviewed-by: Gary Guo Reviewed-by: Alice Ryhl [ Andreas: Updated documentation, examples, and formatting. Change safety requirements, safety comments. ] Assisted-by: LLM Co-developed-by: Andreas Hindborg Signed-off-by: Andreas Hindborg --- rust/kernel/lib.rs | 1 + rust/kernel/owned.rs | 191 +++++++++++++++++++++++++++++++++++++++++++++++ rust/kernel/sync/aref.rs | 5 ++ rust/kernel/types.rs | 5 ++ 4 files changed, 202 insertions(+) diff --git a/rust/kernel/lib.rs b/rust/kernel/lib.rs index 4d5c96ddc49c..bcacd03c67a6 100644 --- a/rust/kernel/lib.rs +++ b/rust/kernel/lib.rs @@ -108,6 +108,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..b76edd7c4151 --- /dev/null +++ b/rust/kernel/owned.rs @@ -0,0 +1,191 @@ +// 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`] pointer type. This +/// is useful when it is desirable to tie the lifetime of the 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 [`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. +/// +/// # 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 = 0; +/// } +/// // SAFETY: We call `init()` only once, here. +/// unsafe { FOO_ALLOC_COUNT.init() }; +/// +/// struct Foo; +/// +/// impl Foo { +/// fn new() -> Result> { +/// // 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 and we own it. +/// // - We can transfer this ownership to the `from_raw` method. +/// Ok(unsafe { Owned::from_raw(result) }) +/// } +/// } +/// +/// impl Ownable for Foo { +/// unsafe fn release(this: NonNull) { +/// // SAFETY: The [`KBox`] 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. + /// + /// # Safety + /// + /// Callers must ensure that they have exclusive ownership of the `Self` pointed to by `this`, + /// and that this ownership is transferred to the `release` method. `this` must not be used + /// after calling this method, as the underlying object may have been freed. + unsafe fn release(this: NonNull); +} + +/// A mutable reference to an owned `T`. +/// +/// The [`Ownable`] is automatically freed or released when an instance of [`Owned`] is +/// dropped. +/// +/// # Invariants +/// +/// - Until `T::release` is called, this `Owned` exclusively owns the underlying `T`. +/// - The `T` value is pinned. +pub struct Owned { + ptr: NonNull, +} + +impl Owned { + /// Creates a new instance of [`Owned`]. + /// + /// This function takes over ownership of the underlying object. + /// + /// # Safety + /// + /// Callers must ensure that: + /// - `ptr` points to a valid instance of `T`. + /// - Until `T::release` is called, the returned `Owned` exclusively owns 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`]. + #[inline] + pub unsafe fn from_raw(ptr: NonNull) -> Self { + // INVARIANT: By the function safety requirements, we have exclusive ownership of the `T` + // and the `T` is treated as pinned, satisfying both 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. + #[inline] + pub fn into_raw(me: Self) -> NonNull { + ManuallyDrop::new(me).ptr + } + + /// Get a pinned mutable reference to the data owned by this `Owned`. + #[inline] + pub fn as_pin_mut(&mut self) -> Pin<&mut T> { + // SAFETY: The type invariants guarantee that the object is valid, and that we can safely + // return a mutable reference to it. + let unpinned = unsafe { self.ptr.as_mut() }; + + // SAFETY: By type invariant `T` is pinned. + unsafe { Pin::new_unchecked(unpinned) } + } +} + +// SAFETY: It is safe to send an [`Owned`] to another thread when the underlying `T` is [`Send`], +// because of the ownership invariant. Sending an [`Owned`] is equivalent to sending the `T`. +unsafe impl Send for Owned {} + +// SAFETY: It is safe to send [`&Owned`] to another thread when the underlying `T` is [`Sync`], +// because of the ownership invariant. Sending an [`&Owned`] is equivalent to sending the `&T`. +unsafe impl Sync for Owned {} + +impl Deref for Owned { + type Target = T; + + #[inline] + fn deref(&self) -> &Self::Target { + // SAFETY: The type invariants guarantee that the object is valid. + unsafe { self.ptr.as_ref() } + } +} + +impl DerefMut for Owned { + #[inline] + fn deref_mut(&mut self) -> &mut Self::Target { + // SAFETY: The type invariants guarantee that the object is valid, and that we can safely + // return a mutable reference to it. + unsafe { self.ptr.as_mut() } + } +} + +impl Drop for Owned { + #[inline] + fn drop(&mut self) { + // SAFETY: By existence of `&mut self` we exclusively own `self` and the underlying `T`. As + // we are dropping `self`, we can transfer ownership of the `T` to the `release` method. + 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`]. 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`](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.51.2