lastdragon/linux-kernel
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Resguardo inicial

Browse Source
This commit is contained in:
lastdragon
2026-09-06 12:53:21 -06:00
parent 662efe3c2a
commit ad2088d178
94853 changed files with 43200404 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
linux-7.2.3/rust/kernel/list/arc.rs
+500
View File
@@ -0,0 +1,500 @@
// SPDX-License-Identifier: GPL-2.0
// Copyright (C) 2024 Google LLC.
//! A wrapper around `Arc` for linked lists.
use crate::alloc::{AllocError, Flags};
use crate::prelude::*;
use crate::sync::atomic::{ordering, AtomicFlag};
use crate::sync::{Arc, ArcBorrow, UniqueArc};
use core::marker::PhantomPinned;
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.
///
/// Types that implement this trait should include some kind of logic for keeping track of whether
/// a [`ListArc`] exists or not. We refer to this logic as "the tracking inside `T`".
///
/// We allow the case where the tracking inside `T` thinks that a [`ListArc`] exists, but actually,
/// there isn't a [`ListArc`]. However, we do not allow the opposite situation where a [`ListArc`]
/// exists, but the tracking thinks it doesn't. This is because the former can at most result in us
/// failing to create a [`ListArc`] when the operation could succeed, whereas the latter can result
/// in the creation of two [`ListArc`] references. Only the latter situation can lead to memory
/// safety issues.
///
/// A consequence of the above is that you may implement the tracking inside `T` by not actually
/// keeping track of anything. To do this, you always claim that a [`ListArc`] exists, even if
/// there isn't one. This implementation is allowed by the above rule, but it means that
/// [`ListArc`] references can only be created if you have ownership of *all* references to the
/// refcounted object, as you otherwise have no way of knowing whether a [`ListArc`] exists.
pub trait ListArcSafe<const ID: u64 = 0> {
/// Informs the tracking inside this type that it now has a [`ListArc`] reference.
///
/// This method may be called even if the tracking inside this type thinks that a `ListArc`
/// reference exists. (But only if that's not actually the case.)
///
/// # Safety
///
/// Must not be called if a [`ListArc`] already exist for this value.
unsafe fn on_create_list_arc_from_unique(self: Pin<&mut Self>);
/// Informs the tracking inside this type that there is no [`ListArc`] reference anymore.
///
/// # Safety
///
/// Must only be called if there is no [`ListArc`] reference, but the tracking thinks there is.
unsafe fn on_drop_list_arc(&self);
}
/// Declares that this type is able to safely attempt to create `ListArc`s at any time.
///
/// # Safety
///
/// The guarantees of `try_new_list_arc` must be upheld.
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.
///
/// This method should not be called directly. Use [`ListArc::try_from_arc`] instead.
///
/// # Guarantees
///
/// If this call returns `true`, then there is no [`ListArc`] pointing to this value.
/// Additionally, this call will have transitioned the tracking inside `Self` from not thinking
/// that a [`ListArc`] exists, to thinking that a [`ListArc`] exists.
fn try_new_list_arc(&self) -> bool;
}
/// Declares that this type supports [`ListArc`].
///
/// This macro supports a few different strategies for implementing the tracking inside the type:
///
/// * The `untracked` strategy does not actually keep track of whether a [`ListArc`] exists. When
/// using this strategy, the only way to create a [`ListArc`] is using a [`UniqueArc`].
/// * The `tracked_by` strategy defers the tracking to a field of the struct. The user must specify
/// which field to defer the tracking to. The field must implement [`ListArcSafe`]. If the field
/// implements [`TryNewListArc`], then the type will also implement [`TryNewListArc`].
///
/// The `tracked_by` strategy is usually used by deferring to a field of type
/// [`AtomicTracker`]. However, it is also possible to defer the tracking to another struct
/// using also using this macro.
#[macro_export]
#[doc(hidden)]
macro_rules! impl_list_arc_safe {
(impl$({$($generics:tt)*})? ListArcSafe<$num:tt> for $t:ty { untracked; } $($rest:tt)*) => {
impl$(<$($generics)*>)? $crate::list::ListArcSafe<$num> for $t {
unsafe fn on_create_list_arc_from_unique(self: ::core::pin::Pin<&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)*>)? $crate::list::ListArcSafe<$num> for $t {
unsafe fn on_create_list_arc_from_unique(self: ::core::pin::Pin<&mut Self>) {
::pin_init::assert_pinned!($t, $field, $fty, inline);
// SAFETY: This field is structurally pinned as per the above assertion.
let field = unsafe {
::core::pin::Pin::map_unchecked_mut(self, |me| &mut me.$field)
};
// SAFETY: The caller promises that there is no `ListArc`.
unsafe {
<$fty as $crate::list::ListArcSafe<$num>>::on_create_list_arc_from_unique(field)
};
}
unsafe fn on_drop_list_arc(&self) {
// SAFETY: The caller promises that there is no `ListArc` reference, and also
// promises that the tracking thinks there is a `ListArc` reference.
unsafe { <$fty as $crate::list::ListArcSafe<$num>>::on_drop_list_arc(&self.$field) };
}
}
unsafe impl$(<$($generics)*>)? $crate::list::TryNewListArc<$num> for $t
where
$fty: TryNewListArc<$num>,
{
fn try_new_list_arc(&self) -> bool {
<$fty as $crate::list::TryNewListArc<$num>>::try_new_list_arc(&self.$field)
}
}
$crate::list::impl_list_arc_safe! { $($rest)* }
};
() => {};
}
pub use impl_list_arc_safe;
/// A wrapper around [`Arc`] that's guaranteed unique for the given id.
///
/// The `ListArc` type can be thought of as a special reference to a refcounted object that owns the
/// permission to manipulate the `next`/`prev` pointers stored in the refcounted object. By ensuring
/// that each object has only one `ListArc` reference, the owner of that reference is assured
/// exclusive access to the `next`/`prev` pointers. When a `ListArc` is inserted into a [`List`],
/// the [`List`] takes ownership of the `ListArc` reference.
///
/// There are various strategies to ensuring that a value has only one `ListArc` reference. The
/// simplest is to convert a [`UniqueArc`] into a `ListArc`. However, the refcounted object could
/// also keep track of whether a `ListArc` exists using a boolean, which could allow for the
/// creation of new `ListArc` references from an [`Arc`] reference. Whatever strategy is used, the
/// relevant tracking is referred to as "the tracking inside `T`", and the [`ListArcSafe`] trait
/// (and its subtraits) are used to update the tracking when a `ListArc` is created or destroyed.
///
/// Note that we allow the case where the tracking inside `T` thinks that a `ListArc` exists, but
/// actually, there isn't a `ListArc`. However, we do not allow the opposite situation where a
/// `ListArc` exists, but the tracking thinks it doesn't. This is because the former can at most
/// result in us failing to create a `ListArc` when the operation could succeed, whereas the latter
/// can result in the creation of two `ListArc` references.
///
/// While this `ListArc` is unique for the given id, there still might exist normal `Arc`
/// references to the object.
///
/// # Invariants
///
/// * Each reference counted object has at most one `ListArc` for each value of `ID`.
/// * The tracking inside `T` is aware that a `ListArc` reference exists.
///
/// [`List`]: crate::list::List
#[repr(transparent)]
#[derive(core::marker::CoercePointee)]
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`.
#[inline]
pub fn new(contents: T, flags: Flags) -> Result<Self, AllocError> {
Ok(Self::from(UniqueArc::new(contents, flags)?))
}
/// Use the given initializer to in-place initialize a `T`.
///
/// If `T: !Unpin` it will not be able to move afterwards.
// We don't implement `InPlaceInit` because `ListArc` is implicitly pinned. This is similar to
// what we do for `Arc`.
#[inline]
pub fn pin_init<E>(init: impl PinInit<T, E>, flags: Flags) -> Result<Self, E>
where
E: From<AllocError>,
{
Ok(Self::from(UniqueArc::try_pin_init(init, flags)?))
}
/// Use the given initializer to in-place initialize a `T`.
///
/// This is equivalent to [`ListArc<T>::pin_init`], since a [`ListArc`] is always pinned.
#[inline]
pub fn init<E>(init: impl Init<T, E>, flags: Flags) -> Result<Self, E>
where
E: From<AllocError>,
{
Ok(Self::from(UniqueArc::try_init(init, flags)?))
}
}
impl<T, const ID: u64> From<UniqueArc<T>> for ListArc<T, ID>
where
T: ListArcSafe<ID> + ?Sized,
{
/// Convert a [`UniqueArc`] into a [`ListArc`].
#[inline]
fn from(unique: UniqueArc<T>) -> Self {
Self::from(Pin::from(unique))
}
}
impl<T, const ID: u64> From<Pin<UniqueArc<T>>> for ListArc<T, ID>
where
T: ListArcSafe<ID> + ?Sized,
{
/// Convert a pinned [`UniqueArc`] into a [`ListArc`].
#[inline]
fn from(mut unique: Pin<UniqueArc<T>>) -> Self {
// SAFETY: We have a `UniqueArc`, so there is no `ListArc`.
unsafe { T::on_create_list_arc_from_unique(unique.as_mut()) };
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) }
}
}
impl<T, const ID: u64> ListArc<T, ID>
where
T: ListArcSafe<ID> + ?Sized,
{
/// Creates two `ListArc`s from a [`UniqueArc`].
///
/// The two ids must be different.
#[inline]
pub fn pair_from_unique<const ID2: u64>(unique: UniqueArc<T>) -> (Self, ListArc<T, ID2>)
where
T: ListArcSafe<ID2>,
{
Self::pair_from_pin_unique(Pin::from(unique))
}
/// Creates two `ListArc`s from a pinned [`UniqueArc`].
///
/// The two ids must be different.
#[inline]
pub fn pair_from_pin_unique<const ID2: u64>(
mut unique: Pin<UniqueArc<T>>,
) -> (Self, ListArc<T, ID2>)
where
T: ListArcSafe<ID2>,
{
build_assert!(ID != ID2);
// SAFETY: We have a `UniqueArc`, so there is no `ListArc`.
unsafe { <T as ListArcSafe<ID>>::on_create_list_arc_from_unique(unique.as_mut()) };
// SAFETY: We have a `UniqueArc`, so there is no `ListArc`.
unsafe { <T as ListArcSafe<ID2>>::on_create_list_arc_from_unique(unique.as_mut()) };
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`
// for both IDs (which are different), so we can create two `ListArc`s.
unsafe {
(
Self::transmute_from_arc(arc1),
ListArc::transmute_from_arc(arc2),
)
}
}
/// 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 returned true, so we made the tracking think
// that a `ListArc` exists. This lets us create a `ListArc`.
Ok(unsafe { Self::transmute_from_arc(arc) })
} else {
Err(arc)
}
}
/// Try to create a new `ListArc`.
///
/// This fails if this value already has a `ListArc`.
pub fn try_from_arc_borrow(arc: ArcBorrow<'_, T>) -> Option<Self>
where
T: TryNewListArc<ID>,
{
if arc.try_new_list_arc() {
// SAFETY: The `try_new_list_arc` method returned true, so we made the tracking think
// that a `ListArc` exists. This lets us create a `ListArc`.
Some(unsafe { Self::transmute_from_arc(Arc::from(arc)) })
} else {
None
}
}
/// 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),
}
}
/// Transmutes an [`Arc`] into a `ListArc` without updating the tracking inside `T`.
///
/// # Safety
///
/// * The value must not already have a `ListArc` reference.
/// * The tracking inside `T` must think that there is a `ListArc` reference.
#[inline]
unsafe fn transmute_from_arc(arc: Arc<T>) -> Self {
// INVARIANT: By the safety requirements, the invariants on `ListArc` are satisfied.
Self { arc }
}
/// Transmutes a `ListArc` into an [`Arc`] without updating the tracking inside `T`.
///
/// After this call, the tracking inside `T` will still think that there is a `ListArc`
/// reference.
#[inline]
fn transmute_to_arc(self) -> Arc<T> {
// Use a transmute to skip destructor.
//
// SAFETY: ListArc is repr(transparent).
unsafe { core::mem::transmute(self) }
}
/// Convert ownership of this `ListArc` into a raw pointer.
///
/// The returned pointer is indistinguishable from pointers returned by [`Arc::into_raw`]. The
/// tracking inside `T` will still think that a `ListArc` exists after this call.
#[inline]
pub fn into_raw(self) -> *const T {
Arc::into_raw(Self::transmute_to_arc(self))
}
/// Take ownership of the `ListArc` from a raw pointer.
///
/// # Safety
///
/// * `ptr` must satisfy the safety requirements of [`Arc::from_raw`].
/// * The value must not already have a `ListArc` reference.
/// * The tracking inside `T` must think that there is a `ListArc` reference.
#[inline]
pub unsafe fn from_raw(ptr: *const T) -> Self {
// SAFETY: The pointer satisfies the safety requirements for `Arc::from_raw`.
let arc = unsafe { Arc::from_raw(ptr) };
// SAFETY: The value doesn't already have a `ListArc` reference, but the tracking thinks it
// does.
unsafe { Self::transmute_from_arc(arc) }
}
/// Converts the `ListArc` into an [`Arc`].
#[inline]
pub fn into_arc(self) -> Arc<T> {
let arc = Self::transmute_to_arc(self);
// SAFETY: There is no longer a `ListArc`, but the tracking thinks there is.
unsafe { T::on_drop_list_arc(&arc) };
arc
}
/// Clone a `ListArc` into an [`Arc`].
#[inline]
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.
#[inline]
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;
#[inline]
fn deref(&self) -> &Self::Target {
self.arc.deref()
}
}
impl<T, const ID: u64> Drop for ListArc<T, ID>
where
T: ListArcSafe<ID> + ?Sized,
{
#[inline]
fn drop(&mut self) {
// SAFETY: There is no longer a `ListArc`, but the tracking thinks there is by the type
// invariants on `Self`.
unsafe { T::on_drop_list_arc(&self.arc) };
}
}
impl<T, const ID: u64> AsRef<Arc<T>> for ListArc<T, ID>
where
T: ListArcSafe<ID> + ?Sized,
{
#[inline]
fn as_ref(&self) -> &Arc<T> {
self.as_arc()
}
}
/// A utility for tracking whether a [`ListArc`] exists using an atomic.
///
/// # Invariants
///
/// If the boolean is `false`, then there is no [`ListArc`] for this value.
#[repr(transparent)]
pub struct AtomicTracker<const ID: u64 = 0> {
inner: AtomicFlag,
// This value needs to be pinned to justify the INVARIANT: comment in `AtomicTracker::new`.
_pin: PhantomPinned,
}
impl<const ID: u64> AtomicTracker<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: AtomicFlag::new(false),
_pin: PhantomPinned,
}
}
fn project_inner(self: Pin<&mut Self>) -> &mut AtomicFlag {
// SAFETY: The `inner` field is not structurally pinned, so we may obtain a mutable
// reference to it even if we only have a pinned reference to `self`.
unsafe { &mut Pin::into_inner_unchecked(self).inner }
}
}
impl<const ID: u64> ListArcSafe<ID> for AtomicTracker<ID> {
unsafe fn on_create_list_arc_from_unique(self: Pin<&mut Self>) {
// INVARIANT: We just created a ListArc, so the boolean should be true.
*self.project_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 if there was a previous `ListArc`, then the destruction of the previous
// `ListArc` happens-before the creation of the new `ListArc`.
unsafe impl<const ID: u64> TryNewListArc<ID> for AtomicTracker<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.cmpxchg(false, true, ordering::Acquire).is_ok()
}
}
linux-7.2.3/rust/kernel/list/arc_field.rs
+97
View File
@@ -0,0 +1,97 @@
// 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`].
///
/// [`ListArc`]: crate::list::ListArc
pub struct ListArcField<T, const ID: u64 = 0> {
value: UnsafeCell<T>,
}
// SAFETY: If the inner type is thread-safe, then it's also okay for `ListArc` to be thread-safe.
unsafe impl<T: Send + Sync, const ID: u64> Send for ListArcField<T, ID> {}
// SAFETY: If the inner type is thread-safe, then it's also okay for `ListArc` to be thread-safe.
unsafe impl<T: Send + 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 {
// SAFETY: The caller has shared access to the `ListArc`, so they also have shared access
// to this field.
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.
#[expect(clippy::mut_from_ref)]
pub unsafe fn assert_mut(&self) -> &mut T {
// SAFETY: The caller has exclusive access to the `ListArc`, so they also have exclusive
// access to this field.
unsafe { &mut *self.value.get() }
}
}
/// Defines getters for a [`ListArcField`].
#[macro_export]
#[doc(hidden)]
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;
linux-7.2.3/rust/kernel/list/impl_list_item_mod.rs
+361
View File
@@ -0,0 +1,361 @@
// SPDX-License-Identifier: GPL-2.0
// Copyright (C) 2024 Google LLC.
//! Helpers for implementing list traits safely.
/// Declares that this type has a [`ListLinks<ID>`] field.
///
/// This trait is only used to help implement [`ListItem`] safely. If [`ListItem`] is implemented
/// manually, then this trait is not needed. Use the [`impl_has_list_links!`] macro to implement
/// this trait.
///
/// # Safety
///
/// The methods on this trait must have exactly the behavior that the definitions given below have.
///
/// [`ListLinks<ID>`]: crate::list::ListLinks
/// [`ListItem`]: crate::list::ListItem
pub unsafe trait HasListLinks<const ID: u64 = 0> {
/// Returns a pointer to the [`ListLinks<ID>`] field.
///
/// # Safety
///
/// The provided pointer must point at a valid struct of type `Self`.
///
/// [`ListLinks<ID>`]: crate::list::ListLinks
unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut crate::list::ListLinks<ID>;
}
/// Implements the [`HasListLinks`] trait for the given type.
#[macro_export]
#[doc(hidden)]
macro_rules! impl_has_list_links {
($(impl$({$($generics:tt)*})?
HasListLinks$(<$id:tt>)?
for $self:ty
{ self$(.$field:ident)* }
)*) => {$(
// SAFETY: The implementation of `raw_get_list_links` only compiles if the field has the
// right type.
unsafe impl$(<$($generics)*>)? $crate::list::HasListLinks$(<$id>)? for $self {
#[inline]
unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut $crate::list::ListLinks$(<$id>)? {
// Statically ensure that `$(.field)*` doesn't follow any pointers.
//
// Cannot be `const` because `$self` may contain generics and E0401 says constants
// "can't use {`Self`,generic parameters} from outer item".
if false { let _: usize = ::core::mem::offset_of!(Self, $($field).*); }
// SAFETY: The caller promises that the pointer is not dangling. We know that this
// expression doesn't follow any pointers, as the `offset_of!` invocation above
// would otherwise not compile.
unsafe { ::core::ptr::addr_of_mut!((*ptr)$(.$field)*) }
}
}
)*};
}
pub use impl_has_list_links;
/// Declares that the [`ListLinks<ID>`] field in this struct is inside a
/// [`ListLinksSelfPtr<T, ID>`].
///
/// # Safety
///
/// The [`ListLinks<ID>`] field of this struct at [`HasListLinks<ID>::raw_get_list_links`] must be
/// inside a [`ListLinksSelfPtr<T, ID>`].
///
/// [`ListLinks<ID>`]: crate::list::ListLinks
/// [`ListLinksSelfPtr<T, ID>`]: crate::list::ListLinksSelfPtr
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]
#[doc(hidden)]
macro_rules! impl_has_list_links_self_ptr {
($(impl$({$($generics:tt)*})?
HasSelfPtr<$item_type:ty $(, $id:tt)?>
for $self:ty
{ self$(.$field:ident)* }
)*) => {$(
// SAFETY: The implementation of `raw_get_list_links` only compiles if the field has the
// right type.
unsafe impl$(<$($generics)*>)? $crate::list::HasSelfPtr<$item_type $(, $id)?> for $self {}
// SAFETY: TODO.
unsafe impl$(<$($generics)*>)? $crate::list::HasListLinks$(<$id>)? for $self {
#[inline]
unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut $crate::list::ListLinks$(<$id>)? {
let ptr: *mut $crate::list::ListLinksSelfPtr<$item_type $(, $id)?> =
// SAFETY: The caller promises that the pointer is not dangling.
unsafe { ::core::ptr::addr_of_mut!((*ptr)$(.$field)*) };
ptr.cast()
}
}
)*};
}
pub use impl_has_list_links_self_ptr;
/// Implements the [`ListItem`] trait for the given type.
///
/// Requires that the type implements [`HasListLinks`]. Use the [`impl_has_list_links!`] macro to
/// implement that trait.
///
/// [`ListItem`]: crate::list::ListItem
///
/// # Examples
///
/// ```
/// #[pin_data]
/// struct SimpleListItem {
/// value: u32,
/// #[pin]
/// links: kernel::list::ListLinks,
/// }
///
/// kernel::list::impl_list_arc_safe! {
/// impl ListArcSafe<0> for SimpleListItem { untracked; }
/// }
///
/// kernel::list::impl_list_item! {
/// impl ListItem<0> for SimpleListItem { using ListLinks { self.links }; }
/// }
///
/// struct ListLinksHolder {
/// inner: kernel::list::ListLinks,
/// }
///
/// #[pin_data]
/// struct ComplexListItem<T, U> {
/// value: Result<T, U>,
/// #[pin]
/// links: ListLinksHolder,
/// }
///
/// kernel::list::impl_list_arc_safe! {
/// impl{T, U} ListArcSafe<0> for ComplexListItem<T, U> { untracked; }
/// }
///
/// kernel::list::impl_list_item! {
/// impl{T, U} ListItem<0> for ComplexListItem<T, U> { using ListLinks { self.links.inner }; }
/// }
/// ```
///
/// ```
/// #[pin_data]
/// struct SimpleListItem {
/// value: u32,
/// #[pin]
/// links: kernel::list::ListLinksSelfPtr<SimpleListItem>,
/// }
///
/// kernel::list::impl_list_arc_safe! {
/// impl ListArcSafe<0> for SimpleListItem { untracked; }
/// }
///
/// kernel::list::impl_list_item! {
/// impl ListItem<0> for SimpleListItem { using ListLinksSelfPtr { self.links }; }
/// }
///
/// struct ListLinksSelfPtrHolder<T, U> {
/// inner: kernel::list::ListLinksSelfPtr<ComplexListItem<T, U>>,
/// }
///
/// #[pin_data]
/// struct ComplexListItem<T, U> {
/// value: Result<T, U>,
/// #[pin]
/// links: ListLinksSelfPtrHolder<T, U>,
/// }
///
/// kernel::list::impl_list_arc_safe! {
/// impl{T, U} ListArcSafe<0> for ComplexListItem<T, U> { untracked; }
/// }
///
/// kernel::list::impl_list_item! {
/// impl{T, U} ListItem<0> for ComplexListItem<T, U> {
/// using ListLinksSelfPtr { self.links.inner };
/// }
/// }
/// ```
#[macro_export]
#[doc(hidden)]
macro_rules! impl_list_item {
(
$(impl$({$($generics:tt)*})? ListItem<$num:tt> for $self:ty {
using ListLinks { self$(.$field:ident)* };
})*
) => {$(
$crate::list::impl_has_list_links! {
impl$({$($generics)*})? HasListLinks<$num> for $self { self$(.$field)* }
}
// SAFETY: See GUARANTEES comment on each method.
unsafe impl$(<$($generics)*>)? $crate::list::ListItem<$num> for $self {
// GUARANTEES:
// * This returns the same pointer as `prepare_to_insert` because `prepare_to_insert`
// is implemented in terms of `view_links`.
// * By the type invariants of `ListLinks`, the `ListLinks` has two null pointers when
// this value is not in a list.
unsafe fn view_links(me: *const Self) -> *mut $crate::list::ListLinks<$num> {
// SAFETY: The caller guarantees that `me` points at a valid value of type `Self`.
unsafe {
<Self as $crate::list::HasListLinks<$num>>::raw_get_list_links(me.cast_mut())
}
}
// GUARANTEES:
// * `me` originates from the most recent call to `prepare_to_insert`, which calls
// `raw_get_list_link`, which is implemented using `addr_of_mut!((*self)$(.$field)*)`.
// This method uses `container_of` to perform the inverse operation, so it returns the
// pointer originally passed to `prepare_to_insert`.
// * The pointer remains valid until the next call to `post_remove` because the caller
// of the most recent call to `prepare_to_insert` promised to retain ownership of the
// `ListArc` containing `Self` until the next call to `post_remove`. The value cannot
// be destroyed while a `ListArc` reference exists.
unsafe fn view_value(me: *mut $crate::list::ListLinks<$num>) -> *const Self {
// SAFETY: `me` originates from the most recent call to `prepare_to_insert`, so it
// points at the field `$field` in a value of type `Self`. Thus, reversing that
// operation is still in-bounds of the allocation.
unsafe { $crate::container_of!(me, Self, $($field).*) }
}
// GUARANTEES:
// This implementation of `ListItem` will not give out exclusive access to the same
// `ListLinks` several times because calls to `prepare_to_insert` and `post_remove`
// must alternate and exclusive access is given up when `post_remove` is called.
//
// Other invocations of `impl_list_item!` also cannot give out exclusive access to the
// same `ListLinks` because you can only implement `ListItem` once for each value of
// `ID`, and the `ListLinks` fields only work with the specified `ID`.
unsafe fn prepare_to_insert(me: *const Self) -> *mut $crate::list::ListLinks<$num> {
// SAFETY: The caller promises that `me` points at a valid value.
unsafe { <Self as $crate::list::ListItem<$num>>::view_links(me) }
}
// GUARANTEES:
// * `me` originates from the most recent call to `prepare_to_insert`, which calls
// `raw_get_list_link`, which is implemented using `addr_of_mut!((*self)$(.$field)*)`.
// This method uses `container_of` to perform the inverse operation, so it returns the
// pointer originally passed to `prepare_to_insert`.
unsafe fn post_remove(me: *mut $crate::list::ListLinks<$num>) -> *const Self {
// SAFETY: `me` originates from the most recent call to `prepare_to_insert`, so it
// points at the field `$field` in a value of type `Self`. Thus, reversing that
// operation is still in-bounds of the allocation.
unsafe { $crate::container_of!(me, Self, $($field).*) }
}
}
)*};
(
$(impl$({$($generics:tt)*})? ListItem<$num:tt> for $self:ty {
using ListLinksSelfPtr { self$(.$field:ident)* };
})*
) => {$(
$crate::list::impl_has_list_links_self_ptr! {
impl$({$($generics)*})? HasSelfPtr<$self> for $self { self$(.$field)* }
}
// SAFETY: See GUARANTEES comment on each method.
unsafe impl$(<$($generics)*>)? $crate::list::ListItem<$num> for $self {
// GUARANTEES:
// This implementation of `ListItem` will not give out exclusive access to the same
// `ListLinks` several times because calls to `prepare_to_insert` and `post_remove`
// must alternate and exclusive access is given up when `post_remove` is called.
//
// Other invocations of `impl_list_item!` also cannot give out exclusive access to the
// same `ListLinks` because you can only implement `ListItem` once for each value of
// `ID`, and the `ListLinks` fields only work with the specified `ID`.
unsafe fn prepare_to_insert(me: *const Self) -> *mut $crate::list::ListLinks<$num> {
// SAFETY: The caller promises that `me` points at a valid value of type `Self`.
let links_field = unsafe { <Self as $crate::list::ListItem<$num>>::view_links(me) };
// SAFETY: TODO.
let container = unsafe {
$crate::container_of!(
links_field, $crate::list::ListLinksSelfPtr<Self, $num>, inner
)
};
// SAFETY: By the same reasoning above, `links_field` is a valid pointer.
let self_ptr = unsafe {
$crate::list::ListLinksSelfPtr::raw_get_self_ptr(container)
};
let cell_inner = $crate::types::Opaque::cast_into(self_ptr);
// SAFETY: This value is not accessed in any other places than `prepare_to_insert`,
// `post_remove`, or `view_value`. By the safety requirements of those methods,
// none of these three methods may be called in parallel with this call to
// `prepare_to_insert`, so this write will not race with any other access to the
// value.
unsafe { ::core::ptr::write(cell_inner, me) };
links_field
}
// GUARANTEES:
// * This returns the same pointer as `prepare_to_insert` because `prepare_to_insert`
// returns the return value of `view_links`.
// * By the type invariants of `ListLinks`, the `ListLinks` has two null pointers when
// this value is not in a list.
unsafe fn view_links(me: *const Self) -> *mut $crate::list::ListLinks<$num> {
// SAFETY: The caller promises that `me` points at a valid value of type `Self`.
unsafe {
<Self as $crate::list::HasListLinks<$num>>::raw_get_list_links(me.cast_mut())
}
}
// This function is also used as the implementation of `post_remove`, so the caller
// may choose to satisfy the safety requirements of `post_remove` instead of the safety
// requirements for `view_value`.
//
// GUARANTEES: (always)
// * This returns the same pointer as the one passed to the most recent call to
// `prepare_to_insert` since that call wrote that pointer to this location. The value
// is only modified in `prepare_to_insert`, so it has not been modified since the
// most recent call.
//
// GUARANTEES: (only when using the `view_value` safety requirements)
// * The pointer remains valid until the next call to `post_remove` because the caller
// of the most recent call to `prepare_to_insert` promised to retain ownership of the
// `ListArc` containing `Self` until the next call to `post_remove`. The value cannot
// be destroyed while a `ListArc` reference exists.
unsafe fn view_value(links_field: *mut $crate::list::ListLinks<$num>) -> *const Self {
// SAFETY: TODO.
let container = unsafe {
$crate::container_of!(
links_field, $crate::list::ListLinksSelfPtr<Self, $num>, inner
)
};
// SAFETY: By the same reasoning above, `links_field` is a valid pointer.
let self_ptr = unsafe {
$crate::list::ListLinksSelfPtr::raw_get_self_ptr(container)
};
let cell_inner = $crate::types::Opaque::cast_into(self_ptr);
// SAFETY: This is not a data race, because the only function that writes to this
// value is `prepare_to_insert`, but by the safety requirements the
// `prepare_to_insert` method may not be called in parallel with `view_value` or
// `post_remove`.
unsafe { ::core::ptr::read(cell_inner) }
}
// GUARANTEES:
// The first guarantee of `view_value` is exactly what `post_remove` guarantees.
unsafe fn post_remove(me: *mut $crate::list::ListLinks<$num>) -> *const Self {
// SAFETY: This specific implementation of `view_value` allows the caller to
// promise the safety requirements of `post_remove` instead of the safety
// requirements for `view_value`.
unsafe { <Self as $crate::list::ListItem<$num>>::view_value(me) }
}
}
)*};
}
pub use impl_list_item;