Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
rust: list: support heterogeneous lists
Support linked lists that can hold many different structs at once. This
is generally done using trait objects. The main challenge is figuring
what the struct is given only a pointer to the ListLinks.
We do this by storing a pointer to the struct next to the ListLinks
field. The container_of operation will then just read that pointer. When
the type is a trait object, that pointer will be a fat pointer whose
metadata is a vtable that tells you what kind of struct it is.
Heterogeneous lists are heavily used by Rust Binder. There are a lot of
so-called todo lists containing various events that need to be delivered
to userspace next time userspace calls into the driver. And there are
quite a few different todo item types: incoming transaction, changes to
refcounts, death notifications, and more.
Reviewed-by: Benno Lossin <benno.lossin@proton.me>
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20240814-linked-list-v5-9-f5f5e8075da0@google.com
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
authored by
Alice Ryhl
and committed by
Miguel Ojeda
2003c04b
9078a4f9
+177
-1
+46
-1
rust/kernel/list.rs
+46
-1
rust/kernel/list.rs
···
12
12
use core::ptr;
13
13
14
14
mod impl_list_item_mod;
15
-
pub use self::impl_list_item_mod::{impl_has_list_links, impl_list_item, HasListLinks};
15
+
pub use self::impl_list_item_mod::{
16
+
impl_has_list_links, impl_has_list_links_self_ptr, impl_list_item, HasListLinks, HasSelfPtr,
17
+
};
16
18
17
19
mod arc;
18
20
pub use self::arc::{impl_list_arc_safe, AtomicTracker, ListArc, ListArcSafe, TryNewListArc};
···
182
180
#[inline]
183
181
unsafe fn from_fields(me: *mut ListLinksFields) -> *mut Self {
184
182
me.cast()
183
+
}
184
+
}
185
+
186
+
/// Similar to [`ListLinks`], but also contains a pointer to the full value.
187
+
///
188
+
/// This type can be used instead of [`ListLinks`] to support lists with trait objects.
189
+
#[repr(C)]
190
+
pub struct ListLinksSelfPtr<T: ?Sized, const ID: u64 = 0> {
191
+
/// The `ListLinks` field inside this value.
192
+
///
193
+
/// This is public so that it can be used with `impl_has_list_links!`.
194
+
pub inner: ListLinks<ID>,
195
+
// UnsafeCell is not enough here because we use `Opaque::uninit` as a dummy value, and
196
+
// `ptr::null()` doesn't work for `T: ?Sized`.
197
+
self_ptr: Opaque<*const T>,
198
+
}
199
+
200
+
// SAFETY: The fields of a ListLinksSelfPtr can be moved across thread boundaries.
201
+
unsafe impl<T: ?Sized + Send, const ID: u64> Send for ListLinksSelfPtr<T, ID> {}
202
+
// SAFETY: The type is opaque so immutable references to a ListLinksSelfPtr are useless. Therefore,
203
+
// it's okay to have immutable access to a ListLinks from several threads at once.
204
+
//
205
+
// Note that `inner` being a public field does not prevent this type from being opaque, since
206
+
// `inner` is a opaque type.
207
+
unsafe impl<T: ?Sized + Sync, const ID: u64> Sync for ListLinksSelfPtr<T, ID> {}
208
+
209
+
impl<T: ?Sized, const ID: u64> ListLinksSelfPtr<T, ID> {
210
+
/// The offset from the [`ListLinks`] to the self pointer field.
211
+
pub const LIST_LINKS_SELF_PTR_OFFSET: usize = core::mem::offset_of!(Self, self_ptr);
212
+
213
+
/// Creates a new initializer for this type.
214
+
pub fn new() -> impl PinInit<Self> {
215
+
// INVARIANT: Pin-init initializers can't be used on an existing `Arc`, so this value will
216
+
// not be constructed in an `Arc` that already has a `ListArc`.
217
+
Self {
218
+
inner: ListLinks {
219
+
inner: Opaque::new(ListLinksFields {
220
+
prev: ptr::null_mut(),
221
+
next: ptr::null_mut(),
222
+
}),
223
+
},
224
+
self_ptr: Opaque::uninit(),
225
+
}
185
226
}
186
227
}
187
228
+131
rust/kernel/list/impl_list_item_mod.rs
+131
rust/kernel/list/impl_list_item_mod.rs
···
68
68
}
69
69
pub use impl_has_list_links;
70
70
71
+
/// Declares that the `ListLinks<ID>` field in this struct is inside a `ListLinksSelfPtr<T, ID>`.
72
+
///
73
+
/// # Safety
74
+
///
75
+
/// The `ListLinks<ID>` field of this struct at the offset `HasListLinks<ID>::OFFSET` must be
76
+
/// inside a `ListLinksSelfPtr<T, ID>`.
77
+
pub unsafe trait HasSelfPtr<T: ?Sized, const ID: u64 = 0>
78
+
where
79
+
Self: HasListLinks<ID>,
80
+
{
81
+
}
82
+
83
+
/// Implements the [`HasListLinks`] and [`HasSelfPtr`] traits for the given type.
84
+
#[macro_export]
85
+
macro_rules! impl_has_list_links_self_ptr {
86
+
($(impl$({$($implarg:tt)*})?
87
+
HasSelfPtr<$item_type:ty $(, $id:tt)?>
88
+
for $self:ident $(<$($selfarg:ty),*>)?
89
+
{ self.$field:ident }
90
+
)*) => {$(
91
+
// SAFETY: The implementation of `raw_get_list_links` only compiles if the field has the
92
+
// right type.
93
+
unsafe impl$(<$($implarg)*>)? $crate::list::HasSelfPtr<$item_type $(, $id)?> for
94
+
$self $(<$($selfarg),*>)?
95
+
{}
96
+
97
+
unsafe impl$(<$($implarg)*>)? $crate::list::HasListLinks$(<$id>)? for
98
+
$self $(<$($selfarg),*>)?
99
+
{
100
+
const OFFSET: usize = ::core::mem::offset_of!(Self, $field) as usize;
101
+
102
+
#[inline]
103
+
unsafe fn raw_get_list_links(ptr: *mut Self) -> *mut $crate::list::ListLinks$(<$id>)? {
104
+
// SAFETY: The caller promises that the pointer is not dangling.
105
+
let ptr: *mut $crate::list::ListLinksSelfPtr<$item_type $(, $id)?> =
106
+
unsafe { ::core::ptr::addr_of_mut!((*ptr).$field) };
107
+
ptr.cast()
108
+
}
109
+
}
110
+
)*};
111
+
}
112
+
pub use impl_has_list_links_self_ptr;
113
+
71
114
/// Implements the [`ListItem`] trait for the given type.
72
115
///
73
116
/// Requires that the type implements [`HasListLinks`]. Use the [`impl_has_list_links!`] macro to
···
179
136
// points at the field at offset `offset` in a value of type `Self`. Thus,
180
137
// subtracting `offset` from `me` is still in-bounds of the allocation.
181
138
unsafe { (me as *const u8).sub(offset) as *const Self }
139
+
}
140
+
}
141
+
)*};
142
+
143
+
(
144
+
$(impl$({$($generics:tt)*})? ListItem<$num:tt> for $t:ty {
145
+
using ListLinksSelfPtr;
146
+
})*
147
+
) => {$(
148
+
// SAFETY: See GUARANTEES comment on each method.
149
+
unsafe impl$(<$($generics)*>)? $crate::list::ListItem<$num> for $t {
150
+
// GUARANTEES:
151
+
// This implementation of `ListItem` will not give out exclusive access to the same
152
+
// `ListLinks` several times because calls to `prepare_to_insert` and `post_remove`
153
+
// must alternate and exclusive access is given up when `post_remove` is called.
154
+
//
155
+
// Other invocations of `impl_list_item!` also cannot give out exclusive access to the
156
+
// same `ListLinks` because you can only implement `ListItem` once for each value of
157
+
// `ID`, and the `ListLinks` fields only work with the specified `ID`.
158
+
unsafe fn prepare_to_insert(me: *const Self) -> *mut $crate::list::ListLinks<$num> {
159
+
// SAFETY: The caller promises that `me` points at a valid value of type `Self`.
160
+
let links_field = unsafe { <Self as $crate::list::ListItem<$num>>::view_links(me) };
161
+
162
+
let spoff = $crate::list::ListLinksSelfPtr::<Self, $num>::LIST_LINKS_SELF_PTR_OFFSET;
163
+
// Goes via the offset as the field is private.
164
+
//
165
+
// SAFETY: The constant is equal to `offset_of!(ListLinksSelfPtr, self_ptr)`, so
166
+
// the pointer stays in bounds of the allocation.
167
+
let self_ptr = unsafe { (links_field as *const u8).add(spoff) }
168
+
as *const $crate::types::Opaque<*const Self>;
169
+
let cell_inner = $crate::types::Opaque::raw_get(self_ptr);
170
+
171
+
// SAFETY: This value is not accessed in any other places than `prepare_to_insert`,
172
+
// `post_remove`, or `view_value`. By the safety requirements of those methods,
173
+
// none of these three methods may be called in parallel with this call to
174
+
// `prepare_to_insert`, so this write will not race with any other access to the
175
+
// value.
176
+
unsafe { ::core::ptr::write(cell_inner, me) };
177
+
178
+
links_field
179
+
}
180
+
181
+
// GUARANTEES:
182
+
// * This returns the same pointer as `prepare_to_insert` because `prepare_to_insert`
183
+
// returns the return value of `view_links`.
184
+
// * By the type invariants of `ListLinks`, the `ListLinks` has two null pointers when
185
+
// this value is not in a list.
186
+
unsafe fn view_links(me: *const Self) -> *mut $crate::list::ListLinks<$num> {
187
+
// SAFETY: The caller promises that `me` points at a valid value of type `Self`.
188
+
unsafe { <Self as HasListLinks<$num>>::raw_get_list_links(me.cast_mut()) }
189
+
}
190
+
191
+
// This function is also used as the implementation of `post_remove`, so the caller
192
+
// may choose to satisfy the safety requirements of `post_remove` instead of the safety
193
+
// requirements for `view_value`.
194
+
//
195
+
// GUARANTEES: (always)
196
+
// * This returns the same pointer as the one passed to the most recent call to
197
+
// `prepare_to_insert` since that call wrote that pointer to this location. The value
198
+
// is only modified in `prepare_to_insert`, so it has not been modified since the
199
+
// most recent call.
200
+
//
201
+
// GUARANTEES: (only when using the `view_value` safety requirements)
202
+
// * The pointer remains valid until the next call to `post_remove` because the caller
203
+
// of the most recent call to `prepare_to_insert` promised to retain ownership of the
204
+
// `ListArc` containing `Self` until the next call to `post_remove`. The value cannot
205
+
// be destroyed while a `ListArc` reference exists.
206
+
unsafe fn view_value(links_field: *mut $crate::list::ListLinks<$num>) -> *const Self {
207
+
let spoff = $crate::list::ListLinksSelfPtr::<Self, $num>::LIST_LINKS_SELF_PTR_OFFSET;
208
+
// SAFETY: The constant is equal to `offset_of!(ListLinksSelfPtr, self_ptr)`, so
209
+
// the pointer stays in bounds of the allocation.
210
+
let self_ptr = unsafe { (links_field as *const u8).add(spoff) }
211
+
as *const ::core::cell::UnsafeCell<*const Self>;
212
+
let cell_inner = ::core::cell::UnsafeCell::raw_get(self_ptr);
213
+
// SAFETY: This is not a data race, because the only function that writes to this
214
+
// value is `prepare_to_insert`, but by the safety requirements the
215
+
// `prepare_to_insert` method may not be called in parallel with `view_value` or
216
+
// `post_remove`.
217
+
unsafe { ::core::ptr::read(cell_inner) }
218
+
}
219
+
220
+
// GUARANTEES:
221
+
// The first guarantee of `view_value` is exactly what `post_remove` guarantees.
222
+
unsafe fn post_remove(me: *mut $crate::list::ListLinks<$num>) -> *const Self {
223
+
// SAFETY: This specific implementation of `view_value` allows the caller to
224
+
// promise the safety requirements of `post_remove` instead of the safety
225
+
// requirements for `view_value`.
226
+
unsafe { <Self as $crate::list::ListItem<$num>>::view_value(me) }
182
227
}
183
228
}
184
229
)*};