MIRRORS/linux-imx
1
0
Fork 0
mirror of https://github.com/nxp-imx/linux-imx.git synced 2025-07-06 09:25:22 +02:00
Code Issues Actions Packages Projects Releases Wiki Activity

ANDROID: rust: add linked list implementation

Browse Source 
This adds a linked list that can be used with reference counted
pointers.

This patch is an improved version of a patch included in the list of
dependencies of the Rust Binder RFC [1]. It is marked ANDROID: because
it has not yet been sent to the mailing list.

Link: https://lore.kernel.org/rust-for-linux/20231101-rust-binder-v1-0-08ba9197f637@google.com/ [1]
Bug: 324206405
Change-Id: Ibc1c20997ec20f64eabd2799cb3d6b01a949512e
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
This commit is contained in:
Alice Ryhl 2023-10-12 11:37:55 +02:00 committed by Treehugger Robot
parent f41a47170f
commit b1661c9e45
5 changed files with 1261 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
rust/kernel/lib.rs
View File

@ -41,6 +41,7 @@ pub mod init;
pub mod ioctl;
#[cfg(CONFIG_KUNIT)]
pub mod kunit;
pub mod list;
pub mod mm;
pub mod page;
pub mod prelude;

684
rust/kernel/list.rs Normal file
View File

@ -0,0 +1,684 @@
// SPDX-License-Identifier: GPL-2.0
// Copyright (C) 2024 Google LLC.
//! A linked list implementation.
use crate::init::PinInit;
use crate::sync::ArcBorrow;
use crate::types::Opaque;
use core::cell::UnsafeCell;
use core::iter::{DoubleEndedIterator, FusedIterator};
use core::marker::{PhantomData, PhantomPinned};
use core::mem::MaybeUninit;
use core::ptr;
use core::sync::atomic::{AtomicBool, Ordering};
mod impl_list_item_mod;
pub use self::impl_list_item_mod::{HasListLinks, HasSelfPtr};
pub use crate::{
impl_has_list_links, impl_has_list_links_self_ptr, impl_list_arc_safe, impl_list_item,
};
mod arc;
pub use self::arc::{ListArc, ListArcSafe, TryNewListArc};
mod arc_field;
pub use self::arc_field::{define_list_arc_field_getter, ListArcField};
/// A linked list.
///
/// All elements in this linked list will be [`ListArc`] references to the value. Since a value can
/// only have one `ListArc` (for each pair of prev/next pointers), this ensures that the same
/// prev/next pointers are not used for several linked lists.
///
/// # Invariants
///
/// If the list is empty, then `first` is null. Otherwise, it points at the links field of the
/// first element of this list. The prev/next pointers of items in the list will always form a
/// cycle. This means that prev/next pointers for an item in a list are never null and never
/// dangling.
pub struct List<T: ?Sized + ListItem<ID>, const ID: u64 = 0> {
first: *mut ListLinksFields,
_ty: PhantomData<ListArc<T, ID>>,
}
// SAFETY: This is a container of `ListArc<T, ID>`, and access to the container allows the same
// type of access to the `ListArc<T, ID>` elements.
unsafe impl<T, const ID: u64> Send for List<T, ID>
where
ListArc<T, ID>: Send,
T: ?Sized + ListItem<ID>,
{
}
// SAFETY: This is a container of `ListArc<T, ID>`, and access to the container allows the same
// type of access to the `ListArc<T, ID>` elements.
unsafe impl<T, const ID: u64> Sync for List<T, ID>
where
ListArc<T, ID>: Sync,
T: ?Sized + ListItem<ID>,
{
}
/// Implemented by types where a [`ListArc<Self>`] can be inserted into a [`List`].
///
/// # Safety
///
/// Implementers must ensure that they provide the guarantees documented on the three methods
/// below.
///
/// [`ListArc<Self>`]: ListArc
pub unsafe trait ListItem<const ID: u64 = 0>: ListArcSafe<ID> {
/// Views the [`ListLinks`] for this value.
///
/// # Guarantees
///
/// * If there is a currently active call to `prepare_to_insert`, then this returns the same
/// pointer as the one returned by the currently active call to `prepare_to_insert`.
/// * If there is no currently active call to `prepare_to_insert`, then the returned pointer
/// points at a read-only [`ListLinks`] with two null pointers.
///
/// # Safety
///
/// The provided pointer must point at a valid value. (It need not be in an `Arc`.)
unsafe fn view_links(me: *const Self) -> *mut ListLinks<ID>;
/// View the full value given its [`ListLinks`] field.
///
/// Can only be used when the value is in a list.
///
/// # Guarantees
///
/// * Returns the same pointer as the one passed to the previous call to `prepare_to_insert`.
/// * The returned pointer is valid until the next call to `post_remove`.
///
/// # Safety
///
/// * The provided pointer must originate from the previous call to `prepare_to_insert`, or
/// from a call to `view_links` that happened after the previous call to `prepare_to_insert`.
/// * Since the previous call to `prepare_to_insert`, the `post_remove` method must not have
/// been called.
unsafe fn view_value(me: *mut ListLinks<ID>) -> *const Self;
/// This is called when an item is inserted into a [`List`].
///
/// # Guarantees
///
/// The caller is granted exclusive access to the returned [`ListLinks`] until `post_remove` is
/// called.
///
/// # Safety
///
/// * The provided pointer must point at a valid value in an [`Arc`].
/// * Calls to `prepare_to_insert` and `post_remove` on the same value must alternate.
/// * The caller must own the [`ListArc`] for this value.
/// * The caller must not give up ownership of the [`ListArc`] unless `post_remove` has been
/// called after this call to `prepare_to_insert`.
///
/// [`Arc`]: crate::sync::Arc
unsafe fn prepare_to_insert(me: *const Self) -> *mut ListLinks<ID>;
/// This undoes a previous call to `prepare_to_insert`.
///
/// # Guarantees
///
/// The returned pointer is the pointer that was originally passed to `prepare_to_insert`.
///
/// The caller is free to recreate the `ListArc` after this call.
///
/// # Safety
///
/// The provided pointer must be the pointer returned by the previous call to
/// `prepare_to_insert`.
unsafe fn post_remove(me: *mut ListLinks<ID>) -> *const Self;
}
#[repr(C)]
struct ListLinksFields {
next: *mut ListLinksFields,
prev: *mut ListLinksFields,
}
/// The prev/next pointers for an item in a linked list.
///
/// # Invariants
///
/// The fields are null if and only if this item is not in a list.
#[repr(transparent)]
pub struct ListLinks<const ID: u64 = 0> {
inner: Opaque<ListLinksFields>,
}
unsafe impl<const ID: u64> Send for ListLinks<ID> {}
unsafe impl<const ID: u64> Sync for ListLinks<ID> {}
impl<const ID: u64> ListLinks<ID> {
/// Creates a new initializer for this type.
pub fn new() -> impl PinInit<Self> {
// INVARIANT: Pin-init initializers can't be used on an existing `Arc`, so this value will
// not be constructed in an `Arc` that already has a `ListArc`.
ListLinks {
inner: Opaque::new(ListLinksFields {
prev: ptr::null_mut(),
next: ptr::null_mut(),
}),
}
}
/// # Safety
///
/// The pointer must be dereferencable.
#[inline]
unsafe fn fields(me: *mut Self) -> *mut ListLinksFields {
// SAFETY: The caller promises that the pointer is valid.
unsafe { Opaque::raw_get(ptr::addr_of!((*me).inner)) }
}
/// # Safety
///
/// The pointer must be dereferencable.
#[inline]
unsafe fn from_fields(me: *mut ListLinksFields) -> *mut Self {
me.cast()
}
}
/// Similar to [`ListLinks`], but also contains a pointer to the full value.
///
/// This type can be used instead of [`ListLinks`] to support lists with trait objects.
#[repr(C)]
pub struct ListLinksSelfPtr<T: ?Sized, const ID: u64 = 0> {
/// The `ListLinks` field inside this value.
///
/// This is public so that it can be used with `impl_has_list_links!`.
pub inner: ListLinks<ID>,
self_ptr: UnsafeCell<MaybeUninit<*const T>>,
}
unsafe impl<T: ?Sized + Send, const ID: u64> Send for ListLinksSelfPtr<T, ID> {}
unsafe impl<T: ?Sized + Sync, const ID: u64> Sync for ListLinksSelfPtr<T, ID> {}
impl<T: ?Sized, const ID: u64> ListLinksSelfPtr<T, ID> {
/// The offset from the [`ListLinks`] to the self pointer field.
pub const LIST_LINKS_SELF_PTR_OFFSET: usize = core::mem::offset_of!(Self, self_ptr);
/// Creates a new initializer for this type.
pub fn new() -> impl PinInit<Self> {
// INVARIANT: Pin-init initializers can't be used on an existing `Arc`, so this value will
// not be constructed in an `Arc` that already has a `ListArc`.
Self {
inner: ListLinks {
inner: Opaque::new(ListLinksFields {
prev: ptr::null_mut(),
next: ptr::null_mut(),
}),
},
self_ptr: UnsafeCell::new(MaybeUninit::zeroed()),
}
}
}
/// A utility for tracking whether a [`ListArc`] exists using an atomic.
///
/// # Invariant
///
/// If the boolean is `false`, then there is no [`ListArc`] for this value.
#[repr(transparent)]
pub struct AtomicListArcTracker<const ID: u64 = 0> {
inner: AtomicBool,
_pin: PhantomPinned,
}
impl<const ID: u64> AtomicListArcTracker<ID> {
/// Creates a new initializer for this type.
pub fn new() -> impl PinInit<Self> {
// INVARIANT: Pin-init initializers can't be used on an existing `Arc`, so this value will
// not be constructed in an `Arc` that already has a `ListArc`.
Self {
inner: AtomicBool::new(false),
_pin: PhantomPinned,
}
}
}
impl<const ID: u64> ListArcSafe<ID> for AtomicListArcTracker<ID> {
unsafe fn on_create_list_arc_from_unique(&mut self) {
// INVARIANT: We just created a ListArc, so the boolean should be true.
*self.inner.get_mut() = true;
}
unsafe fn on_drop_list_arc(&self) {
// INVARIANT: We just dropped a ListArc, so the boolean should be false.
self.inner.store(false, Ordering::Release);
}
}
// SAFETY: If this method returns `true`, then by the type invariant there is no `ListArc` before
// this call, so it is okay to create a new `ListArc`.
//
// The acquire ordering will synchronize with the release store from the destruction of any
// previous `ListArc`, so any such destructions happens-before the creation of the new `ListArc`.
unsafe impl<const ID: u64> TryNewListArc<ID> for AtomicListArcTracker<ID> {
fn try_new_list_arc(&self) -> bool {
// INVARIANT: If this method returns true, then the boolean used to be false, and is no
// longer false, so it is okay for the caller to create a new [`ListArc`].
self.inner
.compare_exchange(false, true, Ordering::Acquire, Ordering::Relaxed)
.is_ok()
}
}
impl<T: ?Sized + ListItem<ID>, const ID: u64> List<T, ID> {
/// Creates a new empty list.
pub const fn new() -> Self {
Self {
first: ptr::null_mut(),
_ty: PhantomData,
}
}
/// Returns whether this list is empty.
pub fn is_empty(&self) -> bool {
self.first.is_null()
}
/// Add the provided item to the back of the list.
pub fn push_back(&mut self, item: ListArc<T, ID>) {
let item = unsafe { ListLinks::fields(T::prepare_to_insert(ListArc::into_raw(item))) };
if self.first.is_null() {
self.first = item;
// SAFETY: The caller just gave us ownership of these fields.
// INVARIANT: A linked list with one item should be cyclic.
unsafe {
(*item).next = item;
(*item).prev = item;
}
} else {
let next = self.first;
// SAFETY: We just checked that `next` is non-null.
let prev = unsafe { (*next).prev };
// SAFETY: Pointers in a linked list are never dangling, and the caller just gave us
// ownership of the fields on `item`.
// INVARIANT: This correctly inserts `item` between `prev` and `next`.
unsafe {
(*item).next = next;
(*item).prev = prev;
(*prev).next = item;
(*next).prev = item;
}
}
}
/// Add the provided item to the front of the list.
pub fn push_front(&mut self, item: ListArc<T, ID>) {
let item = unsafe { ListLinks::fields(T::prepare_to_insert(ListArc::into_raw(item))) };
if self.first.is_null() {
// SAFETY: The caller just gave us ownership of these fields.
// INVARIANT: A linked list with one item should be cyclic.
unsafe {
(*item).next = item;
(*item).prev = item;
}
} else {
let next = self.first;
// SAFETY: We just checked that `next` is non-null.
let prev = unsafe { (*next).prev };
// SAFETY: Pointers in a linked list are never dangling, and the caller just gave us
// ownership of the fields on `item`.
// INVARIANT: This correctly inserts `item` between `prev` and `next`.
unsafe {
(*item).next = next;
(*item).prev = prev;
(*prev).next = item;
(*next).prev = item;
}
}
self.first = item;
}
/// Removes the last item from this list.
pub fn pop_back(&mut self) -> Option<ListArc<T, ID>> {
if self.first.is_null() {
return None;
}
// SAFETY: We just checked that the list is not empty.
let last = unsafe { (*self.first).prev };
// SAFETY: The last item of this list is in this list.
Some(unsafe { self.remove_internal(last) })
}
/// Removes the first item from this list.
pub fn pop_front(&mut self) -> Option<ListArc<T, ID>> {
if self.first.is_null() {
return None;
}
// SAFETY: The first item of this list is in this list.
Some(unsafe { self.remove_internal(self.first) })
}
/// Removes the provided item from this list and returns it.
///
/// This returns `None` if the item is not in the list.
///
/// # Safety
///
/// The provided item must not be in a different linked list.
pub unsafe fn remove(&mut self, item: &T) -> Option<ListArc<T, ID>> {
let mut item = unsafe { ListLinks::fields(T::view_links(item)) };
// SAFETY: The user provided a reference, and reference are never dangling.
//
// As for why this is not a data race, there are two cases:
//
// * If `item` is not in any list, then these fields are read-only and null.
// * If `item` is in this list, then we have exclusive access to these fields since we
// have a mutable reference to the list.
//
// In either case, there's no race.
let next = unsafe { (*item).next };
// SAFETY: See above.
let prev = unsafe { (*item).prev };
debug_assert_eq!(next.is_null(), prev.is_null());
if !next.is_null() {
// This is really a no-op, but this ensures that `item` is a raw pointer that was
// obtained straight from the allocator without going through a reference anywhere.
// This ensures that the list is valid under the more restrictive strict provenance
// ruleset.
//
// SAFETY: We just checked that `next` is not null, and its not dangling by the
// list invariants.
unsafe {
debug_assert_eq!(item, (*next).prev);
item = (*next).prev;
}
// SAFETY: We just checked that `item` is in a list, so the caller guarantees that it
// is in this list. The pointers are in the right order.
Some(unsafe { self.remove_internal_inner(item, next, prev) })
} else {
None
}
}
/// Removes the provided item from the list.
///
/// # Safety
///
/// The pointer must point at an item in this list.
unsafe fn remove_internal(&mut self, item: *mut ListLinksFields) -> ListArc<T, ID> {
// SAFETY: The caller promises that this pointer is not dangling, and there's no data race
// since we have a mutable reference to the list containing `item`.
let next = unsafe { (*item).next };
// SAFETY: See above.
let prev = unsafe { (*item).prev };
// SAFETY: The pointers are ok and in the right order.
unsafe { self.remove_internal_inner(item, next, prev) }
}
/// Removes the provided item from the list.
///
/// # Safety
///
/// The pointer must point at an item in this list, and we must have `(*item).next == next` and
/// `(*item).prev == prev`.
unsafe fn remove_internal_inner(
&mut self,
item: *mut ListLinksFields,
next: *mut ListLinksFields,
prev: *mut ListLinksFields,
) -> ListArc<T, ID> {
// SAFETY: We have exclusive access to items in the list, and prev/next pointers are
// never null for items in a list.
//
// INVARIANT: There are three cases:
// * If the list has at least three items, then after removing the item, `prev` and `next`
// will be next to each other.
// * If the list has two items, then the remaining item will point at itself.
// * If this is the only item, then these writes have no effect since we immediately
// override them with null.
unsafe {
(*next).prev = prev;
(*prev).next = next;
}
// SAFETY: We have exclusive access to items in the list.
// INVARIANT: The item is no longer in a list, so the pointers should be null.
unsafe {
(*item).prev = ptr::null_mut();
(*item).next = ptr::null_mut();
}
// INVARIANT: There are three cases:
// * If `item` was not the first item, then `self.first` should remain unchanged.
// * If `item` was the first item and there is another item, then we just updated
// `prev->next` to `next`, which is the new first item, and setting `item->next` to null
// did not modify `prev->next`.
// * If `item` was the only item in the list, then `prev == item`, and we just set
// `item->next` to null, so this correctly sets `first` to null now that the list is
// empty.
if self.first == item {
// SAFETY: The `prev` field of an item in a list is never dangling.
self.first = unsafe { (*prev).next };
}
// SAFETY: We just removed a `ListArc` from the list, so we can turn it back into a
// `ListArc`.
unsafe { ListArc::from_raw(T::post_remove(ListLinks::from_fields(item))) }
}
/// Moves all items from `other` into `self`.
///
/// The items of `other` are added to the back of `self`, so the last item of `other` becomes
/// the last item of `self`.
pub fn push_all_back(&mut self, other: &mut List<T, ID>) {
// First, we insert the elements into `self`. At the end, we make `other` empty.
if self.is_empty() {
// INVARIANT: All of the elements in `other` become elements of `self`.
self.first = other.first;
} else if !other.is_empty() {
let other_first = other.first;
let other_last = unsafe { (*other_first).prev };
let self_first = self.first;
let self_last = unsafe { (*self_first).prev };
// SAFETY: We have exclusive access to both lists, so we can update the pointers.
// INVARIANT: This correctly sets the pointers to merge both lists.
unsafe {
(*self_first).prev = other_last;
(*other_last).next = self_first;
(*self_last).next = other_first;
(*other_first).prev = self_last;
}
}
// INVARIANT: The other list is now empty, so update its pointer.
other.first = ptr::null_mut();
}
/// Returns a cursor to the first element of the list.
///
/// If the list is empty, this returns `None`.
pub fn cursor_front(&mut self) -> Option<Cursor<'_, T, ID>> {
if self.first.is_null() {
None
} else {
Some(Cursor {
current: self.first,
list: self,
})
}
}
/// Creates an iterator over the list.
pub fn iter(&self) -> Iter<'_, T, ID> {
// INVARIANT: If the list is empty, both pointers are null. Otherwise, both pointers point
// at the first element of the same list.
Iter {
current: self.first,
stop: self.first,
_ty: PhantomData,
}
}
}
impl<T: ?Sized + ListItem<ID>, const ID: u64> Drop for List<T, ID> {
fn drop(&mut self) {
while let Some(item) = self.pop_front() {
drop(item);
}
}
}
/// A cursor into a [`List`].
///
/// # Invariants
///
/// The `current` pointer points a value in `list`.
pub struct Cursor<'a, T: ?Sized + ListItem<ID>, const ID: u64 = 0> {
current: *mut ListLinksFields,
list: &'a mut List<T, ID>,
}
impl<'a, T: ?Sized + ListItem<ID>, const ID: u64> Cursor<'a, T, ID> {
/// Access the current element of this cursor.
pub fn current(&self) -> ArcBorrow<'_, T> {
// SAFETY: The `current` pointer points a value in the list.
let me = unsafe { T::view_value(ListLinks::from_fields(self.current)) };
// SAFETY:
// * All values in a list are stored in an `Arc`.
// * The value cannot be removed from the list for the duration of the lifetime annotated
// on the returned `ArcBorrow`, because removing it from the list would require mutable
// access to the cursor or the list. However, the `ArcBorrow` holds an immutable borrow
// on the cursor, which in turn holds an immutable borrow on the list, so any such
// mutable access requires first releasing the immutable borrow on the cursor.
// * Values in a list never have a `UniqueArc` reference.
unsafe { ArcBorrow::from_raw(me) }
}
/// Move the cursor to the next element.
pub fn next(self) -> Option<Cursor<'a, T, ID>> {
// SAFETY: The `current` field is always in a list.
let next = unsafe { (*self.current).next };
if next == self.list.first {
None
} else {
Some(Cursor {
current: next,
list: self.list,
})
}
}
/// Move the cursor to the previous element.
pub fn prev(self) -> Option<Cursor<'a, T, ID>> {
// SAFETY: The `current` field is always in a list.
let prev = unsafe { (*self.current).prev };
if self.current == self.list.first {
None
} else {
Some(Cursor {
current: prev,
list: self.list,
})
}
}
/// Remove the current element from the list.
pub fn remove(self) -> ListArc<T, ID> {
// SAFETY: The `current` pointer always points at a member of the list.
unsafe { self.list.remove_internal(self.current) }
}
}
/// An iterator into a [`List`].
///
/// # Invariants
///
/// The `current` pointer points at a value in a list, or it is null if the iterator has reached
/// the end of the list. The `stop` pointer points at the first value in the same list, or it is
/// null if the list is empty.
#[derive(Clone)]
pub struct Iter<'a, T: ?Sized + ListItem<ID>, const ID: u64 = 0> {
current: *mut ListLinksFields,
stop: *mut ListLinksFields,
_ty: PhantomData<&'a ListArc<T, ID>>,
}
impl<'a, T: ?Sized + ListItem<ID>, const ID: u64> Iterator for Iter<'a, T, ID> {
type Item = ArcBorrow<'a, T>;
fn next(&mut self) -> Option<ArcBorrow<'a, T>> {
if self.current.is_null() {
return None;
}
let current = self.current;
// SAFETY: We just checked that `current` is not null, so it is in a list, and hence not
// dangling. There's no race because the iterator holds an immutable borrow to the list.
let next = unsafe { (*current).next };
// INVARIANT: If `current` was the last element of the list, then this updates it to null.
// Otherwise, we update it to the next element.
self.current = if next != self.stop {
next
} else {
ptr::null_mut()
};
// SAFETY: The `current` pointer points a value in the list.
let item = unsafe { T::view_value(ListLinks::from_fields(current)) };
// SAFETY:
// * All values in a list are stored in an `Arc`.
// * The value cannot be removed from the list for the duration of the lifetime annotated
// on the returned `ArcBorrow`, because removing it from the list would require mutable
// access to the list. However, the `ArcBorrow` is annotated with the iterator's
// lifetime, and the list is immutably borrowed for that lifetime.
// * Values in a list never have a `UniqueArc` reference.
Some(unsafe { ArcBorrow::from_raw(item) })
}
}
impl<'a, T: ?Sized + ListItem<ID>, const ID: u64> FusedIterator for Iter<'a, T, ID> {}
impl<'a, T: ?Sized + ListItem<ID>, const ID: u64> IntoIterator for &'a List<T, ID> {
type IntoIter = Iter<'a, T, ID>;
type Item = ArcBorrow<'a, T>;
fn into_iter(self) -> Iter<'a, T, ID> {
self.iter()
}
}
/// An owning iterator into a [`List`].
pub struct IntoIter<T: ?Sized + ListItem<ID>, const ID: u64 = 0> {
list: List<T, ID>,
}
impl<T: ?Sized + ListItem<ID>, const ID: u64> Iterator for IntoIter<T, ID> {
type Item = ListArc<T, ID>;
fn next(&mut self) -> Option<ListArc<T, ID>> {
self.list.pop_front()
}
}
impl<T: ?Sized + ListItem<ID>, const ID: u64> FusedIterator for IntoIter<T, ID> {}
impl<T: ?Sized + ListItem<ID>, const ID: u64> DoubleEndedIterator for IntoIter<T, ID> {
fn next_back(&mut self) -> Option<ListArc<T, ID>> {
self.list.pop_back()
}
}
impl<T: ?Sized + ListItem<ID>, const ID: u64> IntoIterator for List<T, ID> {
type IntoIter = IntoIter<T, ID>;
type Item = ListArc<T, ID>;
fn into_iter(self) -> IntoIter<T, ID> {
IntoIter { list: self }
}
}

264
rust/kernel/list/arc.rs Normal file
View File

@ -0,0 +1,264 @@
// SPDX-License-Identifier: GPL-2.0
// Copyright (C) 2024 Google LLC.
//! A wrapper around `Arc` for linked lists.
use crate::error;
use crate::prelude::*;
use crate::sync::{Arc, ArcBorrow, UniqueArc};
use core::alloc::AllocError;
use core::marker::Unsize;
use core::ops::Deref;
use core::pin::Pin;
/// Declares that this type has some way to ensure that there is exactly one `ListArc` instance for
/// this id.
pub trait ListArcSafe<const ID: u64 = 0> {
/// Informs the tracking inside this type that a new [`ListArc`] has just been created.
///
/// # Safety
///
/// Must not be called if a [`ListArc`] already exist for this value.
unsafe fn on_create_list_arc_from_unique(&mut self);
/// Informs the tracking inside this type that a [`ListArc`] no longer exists.
///
/// # Safety
///
/// Must only be called if there previously was a [`ListArc`], but there no longer is one.
unsafe fn on_drop_list_arc(&self);
}
/// Declares that this type is able to safely attempt to create `ListArc`s at arbitrary times.
///
/// # Safety
///
/// Implementers must ensure that `try_new_list_arc` never allows the creation of multiple
/// `ListArc` references to the same value.
pub unsafe trait TryNewListArc<const ID: u64 = 0>: ListArcSafe<ID> {
/// Attempts to convert an `Arc<Self>` into an `ListArc<Self>`. Returns `true` if the
/// conversion was successful.
fn try_new_list_arc(&self) -> bool;
}
/// A wrapper around `Arc` that's guaranteed unique for the given id.
#[repr(transparent)]
pub struct ListArc<T, const ID: u64 = 0>
where
T: ListArcSafe<ID> + ?Sized,
{
arc: Arc<T>,
}
impl<T: ListArcSafe<ID>, const ID: u64> ListArc<T, ID> {
/// Constructs a new reference counted instance of `T`.
pub fn try_new(contents: T) -> Result<Self, AllocError> {
Ok(Self::from_unique(UniqueArc::try_new(contents)?))
}
/// Use the given initializer to in-place initialize a `T`.
///
/// If `T: !Unpin` it will not be able to move afterwards.
pub fn pin_init<E>(init: impl PinInit<T, E>) -> error::Result<Self>
where
Error: From<E>,
{
Ok(Self::from_pin_unique(UniqueArc::pin_init(init)?))
}
}
impl<T, const ID: u64> ListArc<T, ID>
where
T: ListArcSafe<ID> + ?Sized,
{
/// Convert a [`UniqueArc`] into a [`ListArc`].
pub fn from_unique(mut unique: UniqueArc<T>) -> Self {
// SAFETY: We have a `UniqueArc`, so we can call this method.
unsafe { T::on_create_list_arc_from_unique(&mut unique) };
let arc = Arc::from(unique);
// SAFETY: We just called `on_create_list_arc_from_unique` on an arc without a `ListArc`,
// so we can create a `ListArc`.
unsafe { Self::transmute_from_arc(arc) }
}
/// Convert a pinned [`UniqueArc`] into a [`ListArc`].
pub fn from_pin_unique(unique: Pin<UniqueArc<T>>) -> Self {
// SAFETY: A `ListArc` is pinned, so we're not actually throwing away the pinning.
Self::from_unique(unsafe { Pin::into_inner_unchecked(unique) })
}
/// Like [`from_unique`], but creates two `ListArcs`.
pub fn pair_from_unique<const ID2: u64>(mut unique: UniqueArc<T>) -> (Self, ListArc<T, ID2>)
where
T: ListArcSafe<ID2>,
{
assert_ne!(ID, ID2);
// SAFETY: We have a `UniqueArc`, so we can call this method.
unsafe { <T as ListArcSafe<ID>>::on_create_list_arc_from_unique(&mut unique) };
// SAFETY: We have a `UniqueArc`, so we can call this method. The two ids are not equal.
unsafe { <T as ListArcSafe<ID2>>::on_create_list_arc_from_unique(&mut unique) };
let arc1 = Arc::from(unique);
let arc2 = Arc::clone(&arc1);
// SAFETY: We just called `on_create_list_arc_from_unique` on an arc without a `ListArc`,
// so we can create a `ListArc`.
unsafe {
(
Self::transmute_from_arc(arc1),
ListArc::transmute_from_arc(arc2),
)
}
}
/// Like [`pair_from_unique`], but uses a pinned arc.
pub fn pair_from_pin_unique<const ID2: u64>(
unique: Pin<UniqueArc<T>>,
) -> (Self, ListArc<T, ID2>)
where
T: ListArcSafe<ID2>,
{
// SAFETY: A `ListArc` is pinned, so we're not actually throwing away the pinning.
Self::pair_from_unique(unsafe { Pin::into_inner_unchecked(unique) })
}
/// Try to create a new `ListArc`.
///
/// This fails if this value already has a `ListArc`.
pub fn try_from_arc(arc: Arc<T>) -> Result<Self, Arc<T>>
where
T: TryNewListArc<ID>,
{
if arc.try_new_list_arc() {
// SAFETY: The `try_new_list_arc` method just told us that its okay to create a new
// `ListArc`.
Ok(unsafe { Self::transmute_from_arc(arc) })
} else {
Err(arc)
}
}
/// Try to create a new `ListArc`.
///
/// If it's not possible to create a new `ListArc`, then the `Arc` is dropped. This will never
/// run the destructor of the value.
pub fn try_from_arc_or_drop(arc: Arc<T>) -> Option<Self>
where
T: TryNewListArc<ID>,
{
match Self::try_from_arc(arc) {
Ok(list_arc) => Some(list_arc),
Err(arc) => Arc::into_unique_or_drop(arc).map(Self::from_pin_unique),
}
}
unsafe fn transmute_from_arc(me: Arc<T>) -> Self {
// SAFETY: ListArc is repr(transparent).
unsafe { core::mem::transmute(me) }
}
fn transmute_to_arc(self) -> Arc<T> {
// SAFETY: ListArc is repr(transparent).
unsafe { core::mem::transmute(self) }
}
/// Like `Arc::into_raw`.
pub fn into_raw(self) -> *const T {
Arc::into_raw(Self::transmute_to_arc(self))
}
/// Like `Arc::from_raw`.
///
/// # Safety
///
/// Beyond the safety requirements from `Arc::from_raw`, this must originate from a previous
/// call to `ListArc::into_raw`.
///
/// Note that this may not be used to convert an `Arc` into a `ListArc` because that would not
/// update the tracking for whether a `ListArc` exists.
pub unsafe fn from_raw(ptr: *const T) -> Self {
unsafe { Self::transmute_from_arc(Arc::from_raw(ptr)) }
}
/// Converts the `ListArc` into an [`Arc`].
pub fn into_arc(self) -> Arc<T> {
let arc = Self::transmute_to_arc(self);
// SAFETY: There is no longer a `ListArc`, so we can call this method.
unsafe { T::on_drop_list_arc(&arc) };
arc
}
/// Clone a `ListArc` into an [`Arc`].
pub fn clone_arc(&self) -> Arc<T> {
self.arc.clone()
}
/// Returns a reference to an [`Arc`] from the given [`ListArc`].
///
/// This is useful when the argument of a function call is an [`&Arc`] (e.g., in a method
/// receiver), but we have a [`ListArc`] instead.
///
/// [`&Arc`]: Arc
#[inline]
pub fn as_arc(&self) -> &Arc<T> {
&self.arc
}
/// Returns an [`ArcBorrow`] from the given [`ListArc`].
///
/// This is useful when the argument of a function call is an [`ArcBorrow`] (e.g., in a method
/// receiver), but we have an [`Arc`] instead. Getting an [`ArcBorrow`] is free when optimised.
#[inline]
pub fn as_arc_borrow(&self) -> ArcBorrow<'_, T> {
self.arc.as_arc_borrow()
}
/// Compare whether two [`ListArc`] pointers reference the same underlying object.
pub fn ptr_eq(this: &Self, other: &Self) -> bool {
Arc::ptr_eq(&this.arc, &other.arc)
}
}
impl<T, const ID: u64> Deref for ListArc<T, ID>
where
T: ListArcSafe<ID> + ?Sized,
{
type Target = T;
fn deref(&self) -> &Self::Target {
self.arc.deref()
}
}
impl<T, const ID: u64> Drop for ListArc<T, ID>
where
T: ListArcSafe<ID> + ?Sized,
{
fn drop(&mut self) {
// SAFETY: We're destroying the `ListArc`.
unsafe {
T::on_drop_list_arc(&self.arc);
}
}
}
// This is to allow [`ListArc`] (and variants) to be used as the type of `self`.
impl<T, const ID: u64> core::ops::Receiver for ListArc<T, ID> where T: ListArcSafe<ID> + ?Sized {}
// This is to allow coercion from `ListArc<T>` to `ListArc<U>` if `T` can be converted to the
// dynamically-sized type (DST) `U`.
impl<T, U, const ID: u64> core::ops::CoerceUnsized<ListArc<U, ID>> for ListArc<T, ID>
where
T: ListArcSafe<ID> + Unsize<U> + ?Sized,
U: ListArcSafe<ID> + ?Sized,
{
}
// This is to allow `ListArc<U>` to be dispatched on when `ListArc<T>` can be coerced into
// `ListArc<U>`.
impl<T, U, const ID: u64> core::ops::DispatchFromDyn<ListArc<U, ID>> for ListArc<T, ID>
where
T: ListArcSafe<ID> + Unsize<U> + ?Sized,
U: ListArcSafe<ID> + ?Sized,
{
}

87
rust/kernel/list/arc_field.rs Normal file
View File

@ -0,0 +1,87 @@
// SPDX-License-Identifier: GPL-2.0
// Copyright (C) 2024 Google LLC.
//! A field that is exclusively owned by a [`ListArc`].
//!
//! This can be used to have reference counted struct where one of the reference counted pointers
//! has exclusive access to a field of the struct.
//!
//! [`ListArc`]: crate::list::ListArc
use core::cell::UnsafeCell;
/// A field owned by a specific `ListArc`.
pub struct ListArcField<T, const ID: u64 = 0> {
value: UnsafeCell<T>,
}
unsafe impl<T: Send, const ID: u64> Send for ListArcField<T, ID> {}
unsafe impl<T: Sync, const ID: u64> Sync for ListArcField<T, ID> {}
impl<T, const ID: u64> ListArcField<T, ID> {
/// Creates a new `ListArcField`.
pub fn new(value: T) -> Self {
Self {
value: UnsafeCell::new(value),
}
}
/// Access the value when we have exclusive access to the `ListArcField`.
///
/// This allows access to the field using an `UniqueArc` instead of a `ListArc`.
pub fn get_mut(&mut self) -> &mut T {
self.value.get_mut()
}
/// Unsafely assert that you have shared access to the `ListArc` for this field.
///
/// # Safety
///
/// The caller must have shared access to the `ListArc<ID>` containing the struct with this
/// field for the duration of the returned reference.
pub unsafe fn assert_ref(&self) -> &T {
unsafe { &*self.value.get() }
}
/// Unsafely assert that you have mutable access to the `ListArc` for this field.
///
/// # Safety
///
/// The caller must have mutable access to the `ListArc<ID>` containing the struct with this
/// field for the duration of the returned reference.
pub unsafe fn assert_mut(&self) -> &mut T {
unsafe { &mut *self.value.get() }
}
}
/// Defines.
#[macro_export]
macro_rules! define_list_arc_field_getter {
($pub:vis fn $name:ident(&self $(<$id:tt>)?) -> &$typ:ty { $field:ident }
$($rest:tt)*
) => {
$pub fn $name<'a>(self: &'a $crate::list::ListArc<Self $(, $id)?>) -> &'a $typ {
let field = &(&**self).$field;
// SAFETY: We have a shared reference to the `ListArc`.
unsafe { $crate::list::ListArcField::<$typ $(, $id)?>::assert_ref(field) }
}
$crate::list::define_list_arc_field_getter!($($rest)*);
};
($pub:vis fn $name:ident(&mut self $(<$id:tt>)?) -> &mut $typ:ty { $field:ident }
$($rest:tt)*
) => {
$pub fn $name<'a>(self: &'a mut $crate::list::ListArc<Self $(, $id)?>) -> &'a mut $typ {
let field = &(&**self).$field;
// SAFETY: We have a mutable reference to the `ListArc`.
unsafe { $crate::list::ListArcField::<$typ $(, $id)?>::assert_mut(field) }
}
$crate::list::define_list_arc_field_getter!($($rest)*);
};
() => {};
}
pub use define_list_arc_field_getter;

225
rust/kernel/list/impl_list_item_mod.rs Normal file
View File

@ -0,0 +1,225 @@
// SPDX-License-Identifier: GPL-2.0
// Copyright (C) 2024 Google LLC.
//! Helpers for implementing [`ListItem`] safely.
//!
//! [`ListItem`]: crate::list::ListItem
use crate::list::ListLinks;
/// Declares that this type has a `ListLinks<ID>` field at a fixed offset.
///
/// This trait is only used to help implement `ListItem` safely. If `ListItem` is implemented
/// manually, then this trait is not needed.
///
/// # Safety
///
/// All values of this type must have a `ListLinks<ID>` field at the given offset.
pub unsafe trait HasListLinks<const ID: u64 = 0> {
/// The offset of the `ListLinks` field.
const OFFSET: usize;
/// Returns a pointer to the [`ListLinks<T, ID>`] field.
///
/// # Safety
///
/// The provided pointer must point at a valid struct of type `Self`.
///
/// [`ListLinks<T, ID>`]: ListLinks
// We don't really need this method, but it's necessary for the implementation of
// `impl_has_work!` to be correct.
#[inline]
unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut ListLinks<ID> {
// SAFETY: The caller promises that the pointer is valid.
unsafe { (ptr as *mut u8).add(Self::OFFSET) as *mut ListLinks<ID> }
}
}
/// Implements the [`HasListLinks`] trait for the given type.
#[macro_export]
macro_rules! impl_has_list_links {
($(impl$(<$($implarg:ident),*>)?
HasListLinks$(<$id:tt>)?
for $self:ident $(<$($selfarg:ty),*>)?
{ self$(.$field:ident)* }
)*) => {$(
// SAFETY: The implementation of `raw_get_list_links` only compiles if the field has the
// right type.
unsafe impl$(<$($implarg),*>)? $crate::list::HasListLinks$(<$id>)? for
$self $(<$($selfarg),*>)?
{
const OFFSET: usize = ::core::mem::offset_of!(Self, $($field).*) as usize;
#[inline]
unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut $crate::list::ListLinks$(<$id>)? {
// SAFETY: The caller promises that the pointer is not dangling.
unsafe {
::core::ptr::addr_of_mut!((*ptr)$(.$field)*)
}
}
}
)*};
}
/// Declares that the `ListLinks<ID>` field in this struct is inside a `ListLinksSelfPtr<T, ID>`.
///
/// # Safety
///
/// The `ListLinks<ID>` field of this struct at the offset `HasListLinks<ID>::OFFSET` must be
/// inside a `ListLinksSelfPtr<T, ID>`.
pub unsafe trait HasSelfPtr<T: ?Sized, const ID: u64 = 0>
where
Self: HasListLinks<ID>,
{
}
/// Implements the [`HasListLinks`] and [`HasSelfPtr`] traits for the given type.
#[macro_export]
macro_rules! impl_has_list_links_self_ptr {
($(impl$({$($implarg:tt)*})?
HasSelfPtr<$item_type:ty $(, $id:tt)?>
for $self:ident $(<$($selfarg:ty),*>)?
{ self.$field:ident }
)*) => {$(
// SAFETY: The implementation of `raw_get_list_links` only compiles if the field has the
// right type.
unsafe impl$(<$($implarg)*>)? $crate::list::HasSelfPtr<$item_type $(, $id)?> for
$self $(<$($selfarg),*>)?
{}
unsafe impl$(<$($implarg)*>)? $crate::list::HasListLinks$(<$id>)? for
$self $(<$($selfarg),*>)?
{
const OFFSET: usize = ::core::mem::offset_of!(Self, $field) as usize;
#[inline]
unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut $crate::list::ListLinks$(<$id>)? {
// SAFETY: The caller promises that the pointer is not dangling.
let ptr: *mut $crate::list::ListLinksSelfPtr<$item_type $(, $id)?> =
unsafe { ::core::ptr::addr_of_mut!((*ptr).$field) };
ptr.cast()
}
}
)*};
}
/// Declares that this type supports `ListArc`.
#[macro_export]
macro_rules! impl_list_arc_safe {
(impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty { untracked; } $($rest:tt)*) => {
impl$(<$($generics)*>)? ListArcSafe<$num> for $t {
unsafe fn on_create_list_arc_from_unique(&mut self) {}
unsafe fn on_drop_list_arc(&self) {}
}
$crate::list::impl_list_arc_safe! { $($rest)* }
};
(impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty {
tracked_by $field:ident : $fty:ty;
} $($rest:tt)*) => {
impl$(<$($generics)*>)? ListArcSafe<$num> for $t {
unsafe fn on_create_list_arc_from_unique(&mut self) {
let me = self as *mut Self;
let field: *mut $fty = unsafe { ::core::ptr::addr_of_mut!((*me).$field) };
unsafe { <$fty as $crate::list::ListArcSafe<$num>>::on_create_list_arc_from_unique(
&mut *field
) };
}
unsafe fn on_drop_list_arc(&self) {
let me = self as *const Self;
let field: *const $fty = unsafe { ::core::ptr::addr_of!((*me).$field) };
unsafe { <$fty as $crate::list::ListArcSafe<$num>>::on_drop_list_arc(&*field) };
}
}
unsafe impl$(<$($generics)*>)? TryNewListArc<$num> for $t
where
$fty: TryNewListArc<$num>,
{
fn try_new_list_arc(&self) -> bool {
let me = self as *const Self;
let field: *const $fty = unsafe { ::core::ptr::addr_of!((*me).$field) };
unsafe { <$fty as $crate::list::TryNewListArc<$num>>::try_new_list_arc(&*field) }
}
}
$crate::list::impl_list_arc_safe! { $($rest)* }
};
() => {};
}
/// Implements the [`ListItem`] trait for the given type.
///
/// Assumes that the type implements [`HasListLinks`]. If using the `ListLinksSelfPtr` strategy,
/// then it also assumes that the type implements the [`HasSelfPtr`] trait.
///
/// [`ListItem`]: crate::list::ListItem
#[macro_export]
macro_rules! impl_list_item {
(
impl$({$($generics:tt)*})? ListItem<$num:tt> for $t:ty {
using ListLinks;
} $($rest:tt)*
) => {
unsafe impl$(<$($generics)*>)? ListItem<$num> for $t {
unsafe fn view_links(me: *const Self) -> *mut ListLinks<$num> {
unsafe {
<Self as HasListLinks<$num>>::raw_get_list_links(me.cast_mut())
}
}
unsafe fn view_value(me: *mut ListLinks<$num>) -> *const Self {
let offset = <Self as HasListLinks<$num>>::OFFSET;
unsafe { (me as *const u8).sub(offset) as *const Self }
}
unsafe fn prepare_to_insert(me: *const Self) -> *mut ListLinks<$num> {
unsafe { Self::view_links(me) }
}
unsafe fn post_remove(me: *mut ListLinks<$num>) -> *const Self {
unsafe { Self::view_value(me) }
}
}
};
(
impl$({$($generics:tt)*})? ListItem<$num:tt> for $t:ty {
using ListLinksSelfPtr;
} $($rest:tt)*
) => {
unsafe impl$(<$($generics)*>)? ListItem<$num> for $t {
unsafe fn prepare_to_insert(me: *const Self) -> *mut ListLinks<$num> {
let links_field = unsafe { Self::view_links(me) };
let spoff = ListLinksSelfPtr::<Self, $num>::LIST_LINKS_SELF_PTR_OFFSET;
let self_ptr = unsafe { (links_field as *const u8).add(spoff)
as *const ::core::cell::UnsafeCell<*const Self> };
let cell_inner = ::core::cell::UnsafeCell::raw_get(self_ptr);
unsafe { ::core::ptr::write(cell_inner, me) };
links_field
}
unsafe fn view_links(me: *const Self) -> *mut ListLinks<$num> {
unsafe {
<Self as HasListLinks<$num>>::raw_get_list_links(me.cast_mut())
}
}
unsafe fn view_value(links_field: *mut ListLinks<$num>) -> *const Self {
let spoff = ListLinksSelfPtr::<Self, $num>::LIST_LINKS_SELF_PTR_OFFSET;
let self_ptr = unsafe { (links_field as *const u8).add(spoff)
as *const ::core::cell::UnsafeCell<*const Self> };
let cell_inner = ::core::cell::UnsafeCell::raw_get(self_ptr);
unsafe {
::core::ptr::read(cell_inner)
}
}
unsafe fn post_remove(me: *mut ListLinks<$num>) -> *const Self {
unsafe { Self::view_value(me) }
}
}
};
}