Add a new trait `Ownable` and type `Owned` for types that specify their
own way of performing allocation and destruction. This is useful for
types from the C side.

At most one `Owned<T>` exists for an object at any time. The type `T`
decides whether other references to the object, such as an `ARef<T>`,
may exist together with the `Owned<T>`.

Implement `ForeignOwnable` for `Owned`.

Split the `RefCounted` trait out of `AlwaysRefCounted`, so that a type
can be used with `ARef` without allowing the `&T` -> `ARef<T>`
conversion.

Add the traits `OwnableIntoShared` and `OwnableTryFromShared` that allow
conversion between `Owned` and `ARef`. This is analogous to conversion
between `UniqueArc` and `Arc`. The two conversions are provided by
separate traits, as some types cannot become unique again after having
been shared.

Patches 1-3 implement `Ownable` and can be merged on their own.

Patch 4 splits the `RefCounted` trait out of `AlwaysRefCounted`.

Patch 5 adds `Owned` <-> `ARef` interop via `OwnableIntoShared` and
`OwnableTryFromShared`.

Signed-off-by: Andreas Hindborg <[email protected]>
---
Changes in v22:
- Rebase on v7.4-rc2.
- Split `OwnableRefCounted` into `OwnableIntoShared` and
  `OwnableTryFromShared`, so that a type can provide one conversion
  without the other (Alice).
- Rework the safety requirements of `Ownable` and `Owned`. An `Owned<T>`
  is now unique among `Owned<T>` handles, and `T` decides whether other
  references may exist together with it. Document this in a new "Access
  model" section on `Ownable` (Alice).
- Allow `AlwaysRefCounted` to be implemented together with `Ownable` for
  types that allow an `ARef<T>` to exist together with an `Owned<T>`
  (Alice).
- Justify `AlwaysRefCounted` implementations by all instances of the type
  being reference counted, rather than by the type not implementing
  `Ownable` (Alice, Gary).
- Update the safety comments of the `ForeignOwnable` implementation for
  `Owned` and the conversion trait documentation for the reworked
  invariants.
- Split `RefCounted` out of `AlwaysRefCounted` for the fwctl and serdev
  `Device` types (Sashiko).
- Split `RefCounted` out of `AlwaysRefCounted` for `Fence`, which is new
  in v7.4-rc1.
- Relax the `ForeignOwnable` implementation for `ARef<T>` to require
  `T: RefCounted` rather than `T: AlwaysRefCounted` (Sashiko).
- Move the documentation updates for `Ownable` and `Owned` from the
  `OwnableRefCounted` patch to the patch that adds the types (Alice).
- Remove the empty line after the hidden imports in the examples (Alice).
- Document the type invariant of `Foo` in the `Ownable` example.
- Drop Reviewed-by tags from the patches adding `Ownable`/`Owned` and
  `ForeignOwnable` for `Owned`, and from the `RefCounted` rename patch,
  as their safety requirements changed.
- Move `Page` changes to their own series to be submitted separately.
- Drop the patch adding SAFETY documentation for the `ARef` example, it
  will be submitted separately.
- Link to v21: 
https://msgid.link/[email protected]

Changes in v21:
- Require callers of `Owned::from_raw()` to treat the pointee as
  pinned (Sashiko).
- Import `Page` directly in `allocator.rs` instead of using the
  `page::Page` path (Danilo).
- Update DRM GPUVM for the `RefCounted`/`AlwaysRefCounted` split
  (Sashiko).
- Rework the SAFETY comments in the `ARef::into_raw` doctest to
  justify the correct obligations (Sashiko).
- Use `sync::Refcount` in the `OwnableRefCounted` example (Gary,
  Danilo).
- Add a link to the SAFETY TODO tracking issue to the `ARef` example
  patch (Miguel).
- Convert `Page` to `AlwaysRefCounted` backed by `get_page()` and
  `put_page()` instead of `Ownable`, and return `ARef<Page>` from
  `Page::alloc_page()` (Alice).
- Update Rust Binder to store `ARef<Page>` instead of `Owned<Page>`
  (Alice).
- Add `ExclusivePage` as the in-tree `Owned` user, without
  `Deref<Target = Page>` as that would break its aliasing invariant.
  The type was previously posted as `SafePage` and is renamed here
  (Alice).
- Reorder the series to keep the `Page` patches together at the end.
- Link to v20: 
https://msgid.link/[email protected]

Changes in v20:
- Fix a few copy/paste errors in safety comments (Sashiko).
- Use `self.page.get()` rather than `Opaque::cast_into` (Alice).
- Add a space between generics in a comment (Sashiko).
- Change a safety comment to reference Box rather than KBox (Sashiko).
- Link to v19: 
https://msgid.link/[email protected]

Changes in v19:
- Update `workqueue.rs` and the `aref` module docs to use `RefCounted` instead 
of `AlwaysRefCounted` (Sashiko).
- Remove the default `OwnableRefCounted::into_shared` implementation to keep 
the trait safe (Sashiko).
- Fix the `ARef<Self>` rustdoc link (Sashiko).
- Reuse `Owned::into_raw`/`from_raw` in the `ForeignOwnable` implementation 
(Gary).
- Link to v18: 
https://msgid.link/[email protected]

Changes in v18:
- Rebase on `rust-next` (2026-06-24).
- Drop the `'static` bound on `ForeignOwnable for Owned` (Gary).
- Make `Ownable::release` take a raw pointer instead of `&mut self` (Alice, 
Sashiko).
- Drop `types::ARef` re-export (Alice).
- Drop unneeded `#[repr(transparent)]` on `Owned` (Gary).
- Fix `FOREIGN_ALIGN` for `Owned` to report the pointee alignment (Sashiko).
- Remove `BorrowedPage`; use `&Page` directly (Alice).
- Update Rust Binder for the `Owned<Page>` conversion (Alice).
- Update `pwm.rs` for the `RefCounted`/`AlwaysRefCounted` split (Sashiko).
- Fix documentation nits: missing `// INVARIANT:` comments, stale `Page` docs, 
and a stray `mut` (Sashiko).
- Expand the `use` statements touched by the rename patch to the multi-line 
style (Onur).
- Link to v17: 
https://msgid.link/[email protected]

Changes in v17:
- Rebase on v7.1-rc2.
- Reorder patches so that `Ownable` can merge without `OwnableRefCounted` 
(Alice).
- Add `#[inline]` directives to short functions added by the series (Gary).
- Link to v16: 
https://msgid.link/[email protected]

Changes in v16:
- Simplify pointer to reference cast in `Page::from_raw`.
- Use `NonNull<Page>` rather than `Owned<Page>` for `BorrowedPage` internals.
- Use "convertible to reference" wording when converting pointers to references.
- Fix formatting for `Page::from_raw` docs.
- Leave imports alone when adding safety comment to aref example.
- Use `KBox::into_nonnull` for examples.
- Add patch for `KBox::into_nonnull`.
- Change invariants and safety comments of `Ownable` and make the trait safe.
- Make `Ownable::release` take a mutable reference.
- Fix error handling in example for `Ownable`
- Link to v15: 
https://msgid.link/[email protected]

Changes in v15:
- Update series with original SoB's.
- Rename `AlwaysRefCounted` in `kernel::usb`.
- Rename `Owned::get_pin_mut` to `Owned::as_pin_mut`.
- Link to v14: 
https://msgid.link/[email protected]

Changes in v14:
- Rebase on v6.19-rc7.
- Rewrite cover letter.
- Update documentation and safety comments based on v13 feedback.
- Update commit messages.
- Reorder implementation blocks in owned.rs.
- Update example in owned.rs to use try operator rather than `expect`.
- Reformat use statements.
- Add patch: rust: page: convert to `Ownable`.
- Add patch: rust: implement `ForeignOwnable` for `Owned`.
- Add patch: rust: page: add `from_raw()`.
- Link to v13: 
https://lore.kernel.org/r/[email protected]

Changes in v13:
- Rebase onto v6.18-rc1 (Andreas's work).
- Documentation and style fixes contributed by Andreas
- Link to v12: 
https://lore.kernel.org/r/[email protected]

Changes in v12:
-
- Rebase onto v6.17-rc1 (Andreas's work).
- moved kernel/types/ownable.rs to kernel/owned.rs
- Drop OwnableMut, make DerefMut depend on Unpin instead. I understood
  ML discussion as that being okay, but probably needs further scrunity.
- Lots of more documentation changes suggested by reviewers.
- Usage example for Ownable/Owned.
- Link to v11: 
https://lore.kernel.org/r/[email protected]

Changes in v11:
- Rework of documentation. I tried to honor all requests for changes "in
  spirit" plus some clearifications and corrections of my own.
- Dropping `SimpleOwnedRefCounted` by request from Alice, as it creates a
  potentially problematic blanket implementation (which a derive macro that
  could be created later would not have).
- Dropping Miguel's "kbuild: provide `RUSTC_HAS_DO_NOT_RECOMMEND` symbol"
  patch, as it is not needed anymore after dropping `SimpleOwnedRefCounted`.
  (I can add it again, if it is considered useful anyway).
- Link to v10: 
https://lore.kernel.org/r/[email protected]

Changes in v10:
- Moved kernel/ownable.rs to kernel/types/ownable.rs
- Fixes in documentation / comments as suggested by Andreas Hindborg
- Added Reviewed-by comment for Andreas Hindborg
- Fix rustfmt of pid_namespace.rs
- Link to v9: 
https://lore.kernel.org/r/[email protected]

Changes in v9:
- Rebase onto v6.14-rc7
- Move Ownable/OwnedRefCounted/Ownable, etc., into separate module
- Documentation fixes to Ownable/OwnableMut/OwnableRefCounted
- Add missing SAFETY documentation to ARef example
- Link to v8: 
https://lore.kernel.org/r/[email protected]

Changes in v8:
- Fix Co-developed-by and Suggested-by tags as suggested by Miguel and Boqun
- Some small documentation fixes in Owned/Ownable patch
- removing redundant trait constraint on DerefMut for Owned as suggested by 
Boqun Feng
- make SimpleOwnedRefCounted no longer implement RefCounted as suggested by 
Boqun Feng
- documentation for RefCounted as suggested by Boqun Feng
- Link to v7: 
https://lore.kernel.org/r/[email protected]

Changes in v7:
- Squash patch to make Owned::from_raw/into_raw public into parent
- Added Signed-off-by to other people's commits
- Link to v6: 
https://lore.kernel.org/r/[email protected]

Changes in v6:
- Changed comments/formatting as suggested by Miguel Ojeda
- Included and used new config flag RUSTC_HAS_DO_NOT_RECOMMEND,
  thus no changes to types.rs will be needed when the attribute
  becomes available.
- Fixed commit message for Owned patch.
- Link to v5: 
https://lore.kernel.org/r/[email protected]

Changes in v5:
- Rebase the whole thing on top of the Ownable/Owned traits by Asahi Lina.
- Rename AlwaysRefCounted to RefCounted and make AlwaysRefCounted a
  marker trait instead to allow to obtain an ARef<T> from an &T,
  which (as Alice pointed out) is unsound when combined with UniqueRef/Owned.
- Change the Trait design and naming to implement this feature,
  UniqueRef/UniqueRefCounted is dropped in favor of Ownable/Owned and
  OwnableRefCounted is used to provide the functions to convert
  between Owned and ARef.
- Link to v4: 
https://lore.kernel.org/r/[email protected]

Changes in v4:
- Just a minor change in naming by request from Andreas Hindborg,
  try_shared_to_unique() -> try_from_shared(),
  unique_to_shared() -> into_shared(),
  which is more in line with standard Rust naming conventions.
- Link to v3: https://lore.kernel.org/r/Z8Wuud2UQX6Yukyr@mango

To: Danilo Krummrich <[email protected]>
To: Lorenzo Stoakes <[email protected]>
To: Vlastimil Babka <[email protected]>
To: "Liam R. Howlett" <[email protected]>
To: Uladzislau Rezki <[email protected]>
To: Miguel Ojeda <[email protected]>
To: Boqun Feng <[email protected]>
To: Gary Guo <[email protected]>
To: Björn Roy Baron <[email protected]>
To: Benno Lossin <[email protected]>
To: Andreas Hindborg <[email protected]>
To: Alice Ryhl <[email protected]>
To: Trevor Gross <[email protected]>
To: Daniel Almeida <[email protected]>
To: Tamir Duberstein <[email protected]>
To: Alexandre Courbot <[email protected]>
To: Onur Özkan <[email protected]>
To: Lyude Paul <[email protected]>
To: Greg Kroah-Hartman <[email protected]>
To: Christian Brauner <[email protected]>
To: "Rafael J. Wysocki" <[email protected]>
To: Dave Ertman <[email protected]>
To: Ira Weiny <[email protected]>
To: Leon Romanovsky <[email protected]>
To: Paul Moore <[email protected]>
To: Serge Hallyn <[email protected]>
To: David Airlie <[email protected]>
To: Simona Vetter <[email protected]>
To: Alexander Viro <[email protected]>
To: Jan Kara <[email protected]>
To: Igor Korotin <[email protected]>
To: Viresh Kumar <[email protected]>
To: Nishanth Menon <[email protected]>
To: Stephen Boyd <[email protected]>
To: Bjorn Helgaas <[email protected]>
To: Krzysztof Wilczyński <[email protected]>
To: Pavel Tikhomirov <[email protected]>
To: Michal Wilczynski <[email protected]>
To: Ira Weiny <[email protected]>
To: Matthew Brost <[email protected]>
To: Thomas Hellström <[email protected]>
To: Johan Hovold <[email protected]>
To: Sumit Semwal <[email protected]>
To: Christian König <[email protected]>
To: Dave Jiang <[email protected]>
To: Jason Gunthorpe <[email protected]>
To: Saeed Mahameed <[email protected]>
To: Zhi Wang <[email protected]>
To: Jonathan Cameron <[email protected]>
To: Markus Probst <[email protected]>
Cc: Philipp Stanner <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]

---
Andreas Hindborg (2):
      rust: alloc: add `KBox::into_non_null`
      rust: implement `ForeignOwnable` for `Owned`

Asahi Lina (1):
      rust: types: Add Ownable/Owned types

Oliver Mangold (2):
      rust: rename `AlwaysRefCounted` to `RefCounted`
      rust: Add `OwnableIntoShared` and `OwnableTryFromShared`

 rust/kernel/alloc/kbox.rs        |   9 +
 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/lib.rs               |   1 +
 rust/kernel/mm.rs                |  23 +-
 rust/kernel/mm/mmput_async.rs    |  12 +-
 rust/kernel/opp.rs               |  16 +-
 rust/kernel/owned.rs             | 494 +++++++++++++++++++++++++++++++++++++++
 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         |  82 +++++--
 rust/kernel/task.rs              |  13 +-
 rust/kernel/types.rs             |  13 ++
 rust/kernel/usb.rs               |  17 +-
 rust/kernel/workqueue.rs         |   8 +-
 29 files changed, 823 insertions(+), 83 deletions(-)
---
base-commit: 7475ea8b58616b33c04afb976cf0fbaad9dd63fb
change-id: 20250305-unique-ref-29fcd675f9e9

Best regards,
--  
Andreas Hindborg <[email protected]>


Reply via email to