On Wed Feb 18, 2026 at 9:55 PM CET, Joel Fernandes wrote: > +RUST TO C LIST INTERFACES
Maybe this should just be "RUST [FFI]" instead (in case Alex and you want to sign up for looking after FFI helper infrastructure in general)? > +M: Joel Fernandes <[email protected]> > +M: Alexandre Courbot <[email protected]> > +L: [email protected] > +S: Maintained > +F: rust/kernel/ffi/clist.rs <snip> > diff --git a/rust/kernel/ffi/clist.rs b/rust/kernel/ffi/clist.rs > new file mode 100644 > index 000000000000..a84f395875dc > --- /dev/null > +++ b/rust/kernel/ffi/clist.rs > @@ -0,0 +1,327 @@ > +// SPDX-License-Identifier: GPL-2.0 > + > +//! FFI interface for C doubly circular intrusive linked lists. > +//! > +//! This module provides Rust abstractions for iterating over C > `list_head`-based > +//! linked lists. It is intended for FFI use-cases where a C subsystem > manages a > +//! circular linked list that Rust code needs to read. This is generally > required > +//! only for special cases and should be avoided by drivers. Maybe generalize the statement a bit and say that this should only be used for cases where C and Rust code share direct access to the same linked list through an FFI interface. Additionally, add a separate note that this *must not* be used by Rust components that just aim for a linked list primitive and instead refer to the Rust linked list implementation with an intra-doc link. > +//! > +//! # Examples > +//! > +//! ``` > +//! use kernel::{ > +//! bindings, > +//! clist_create, > +//! types::Opaque, // Examples don't necessarily need '//' at the end, as they are not automatically formatted anyways. (I hope that we will have a solution for import formatting before rustfmt supports doc-comments. :) > +//! }; > +//! # // Create test list with values (0, 10, 20) - normally done by C code > but it is > +//! # // emulated here for doctests using the C bindings. > +//! # use core::mem::MaybeUninit; > +//! # > +//! # /// C struct with embedded `list_head` (typically will be allocated by > C code). > +//! # #[repr(C)] > +//! # pub struct SampleItemC { > +//! # pub value: i32, > +//! # pub link: bindings::list_head, > +//! # } > +//! # > +//! # let mut head = MaybeUninit::<bindings::list_head>::uninit(); > +//! # > +//! # let head = head.as_mut_ptr(); > +//! # // SAFETY: head and all the items are test objects allocated in this > scope. > +//! # unsafe { bindings::INIT_LIST_HEAD(head) }; > +//! # > +//! # let mut items = [ > +//! # MaybeUninit::<SampleItemC>::uninit(), > +//! # MaybeUninit::<SampleItemC>::uninit(), > +//! # MaybeUninit::<SampleItemC>::uninit(), > +//! # ]; > +//! # > +//! # for (i, item) in items.iter_mut().enumerate() { > +//! # let ptr = item.as_mut_ptr(); > +//! # // SAFETY: pointers are to allocated test objects with a list_head > field. > +//! # unsafe { I understand that this is just setup code for a doc-test, but I still think we should hold it to the same standards, i.e. let's separate the different unsafe calls into their own unsafe blocks and add proper safety comments. > +//! # (*ptr).value = i as i32 * 10; > +//! # // &raw mut computes address of link directly as link is > uninitialized. > +//! # bindings::INIT_LIST_HEAD(&raw mut (*ptr).link); > +//! # bindings::list_add_tail(&mut (*ptr).link, head); > +//! # } > +//! # } <snip> > +use pin_init::{ > + pin_data, > + pin_init, > + PinInit // Should be 'PinInit, //'. > +}; > + > +/// FFI wrapper for a C `list_head` object used in intrusive linked lists. > +/// > +/// # Invariants > +/// > +/// - [`CListHead`] represents an allocated and valid `list_head` structure. What does "allocated" mean in this context? (Dynamic allocations, stack, .data section of the binary, any of those?) In case of the latter, I'd just remove "allocated". > +#[pin_data] > +#[repr(transparent)] > +pub struct CListHead { > + #[pin] > + inner: Opaque<bindings::list_head>, > +} > + > +impl CListHead { > + /// Create a `&CListHead` reference from a raw `list_head` pointer. > + /// > + /// # Safety > + /// > + /// - `ptr` must be a valid pointer to an allocated and initialized > `list_head` structure. Same here, what exactly is meant by "allocated"? > + /// - `ptr` must remain valid and unmodified for the lifetime `'a`. > + /// - The list and all linked `list_head` nodes must not be modified by > non-Rust code > + /// for the lifetime `'a`. This is a bit vague I think, concurrent modifications of (other) Rust code are not OK either. > + #[inline] > + pub unsafe fn from_raw<'a>(ptr: *mut bindings::list_head) -> &'a Self { > + // SAFETY: > + // - [`CListHead`] has same layout as `list_head`. > + // - `ptr` is valid and unmodified for 'a per caller guarantees. > + unsafe { &*ptr.cast() } > + } > + > + /// Get the raw `list_head` pointer. > + #[inline] > + pub fn as_raw(&self) -> *mut bindings::list_head { > + self.inner.get() > + } > + > + /// Get the next [`CListHead`] in the list. > + #[inline] > + pub fn next(&self) -> &Self { > + let raw = self.as_raw(); > + // SAFETY: > + // - `self.as_raw()` is valid per type invariants. > + // - The `next` pointer is guaranteed to be non-NULL. I'm not sure whether "valid" in the type invariant implies that the struct list_head is initialized. From a language point of view it is also valid if the pointers are NULL. So, I think the invariant (and the safety requirements of from_raw()) have to ensure that the struct list_head is initialized in the sense of INIT_LIST_HEAD(). > + unsafe { Self::from_raw((*raw).next) } > + } <snip> > +/// A typed C linked list with a sentinel head intended for FFI use-cases > where > +/// C subsystem manages a linked list that Rust code needs to read. Generally > +/// required only for special cases. > +/// > +/// A sentinel head [`ClistHead`] represents the entire linked list and can > be used > +/// for iteration over items of type `T`, it is not associated with a > specific item. > +/// > +/// The const generic `OFFSET` specifies the byte offset of the `list_head` > field within > +/// the struct that `T` wraps. > +/// > +/// # Invariants > +/// > +/// - The [`CListHead`] is an allocated and valid sentinel C `list_head` > structure. > +/// - `OFFSET` is the byte offset of the `list_head` field within the struct > that `T` wraps. > +/// - All the list's `list_head` nodes are allocated and have valid > next/prev pointers. > +#[repr(transparent)] > +pub struct CList<T, const OFFSET: usize>(CListHead, PhantomData<T>); > + > +impl<T, const OFFSET: usize> CList<T, OFFSET> { > + /// Create a typed [`CList`] reference from a raw sentinel `list_head` > pointer. > + /// > + /// # Safety > + /// > + /// - `ptr` must be a valid pointer to an allocated and initialized > `list_head` structure > + /// representing a list sentinel. > + /// - `ptr` must remain valid and unmodified for the lifetime `'a`. > + /// - The list must contain items where the `list_head` field is at byte > offset `OFFSET`. > + /// - `T` must be `#[repr(transparent)]` over the C struct. > + #[inline] > + pub unsafe fn from_raw<'a>(ptr: *mut bindings::list_head) -> &'a Self { > + // SAFETY: > + // - [`CList`] has same layout as [`CListHead`] due to > repr(transparent). > + // - Caller guarantees `ptr` is a valid, sentinel `list_head` object. > + unsafe { &*ptr.cast() } > + } Comments from CListHead also apply here. > +/// Create a C doubly-circular linked list interface `CList` from a raw > `list_head` pointer. > +/// > +/// This macro creates a `CList<T, OFFSET>` that can iterate over items of > type `$rust_type` > +/// linked via the `$field` field in the underlying C struct `$c_type`. > +/// > +/// # Arguments > +/// > +/// - `$head`: Raw pointer to the sentinel `list_head` object (`*mut > bindings::list_head`). > +/// - `$rust_type`: Each item's rust wrapper type. > +/// - `$c_type`: Each item's C struct type that contains the embedded > `list_head`. > +/// - `$field`: The name of the `list_head` field within the C struct. > +/// > +/// # Safety > +/// > +/// This is an unsafe macro. The caller must ensure: Given that, we should probably use the same (or a similar) trick as in [1]. [1] https://rust.docs.kernel.org/src/kernel/device.rs.html#665-688 > +/// > +/// - `$head` is a valid, initialized sentinel `list_head` pointing to a > list that remains > +/// unmodified for the lifetime of the rust `CList`. > +/// - The list contains items of type `$c_type` linked via an embedded > `$field`. > +/// - `$rust_type` is `#[repr(transparent)]` over `$c_type` or has > compatible layout. > +/// > +/// # Examples > +/// > +/// Refer to the examples in this module's documentation. > +#[macro_export] > +macro_rules! clist_create { > + ($head:expr, $rust_type:ty, $c_type:ty, $($field:tt).+) => {{ > + // Compile-time check that field path is a list_head. > + let _: fn(*const $c_type) -> *const $crate::bindings::list_head = > + |p| &raw const (*p).$($field).+; > + > + // Calculate offset and create `CList`. > + const OFFSET: usize = ::core::mem::offset_of!($c_type, $($field).+); > + $crate::ffi::clist::CList::<$rust_type, OFFSET>::from_raw($head) > + }}; > +}
