Re: [PATCH v3] rust: clist: Add support to interface with C linked lists

[Joel Fernandes <joelagnelf@nvidia.com>]

Hi Daniel,

On 12/1/2025 11:51 AM, Daniel Almeida wrote:
> 
[...]
>> +/// Create a C doubly-circular linked list interface `Clist` from a raw `list_head` pointer.
>> +///
>> +/// This macro creates a `Clist<T>` 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
>> +///
>> +/// The caller must ensure:
>> +/// - `$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.
>> +/// - The macro is called from an unsafe block.
>> +///
>> +/// # Examples
>> +///
>> +/// Refer to the examples in the [crate::clist] module documentation.
> 
> Missing backticks?
> 

will fix, thanks.

>> +#[macro_export]
>> +macro_rules! clist_create {
>> +    ($head:expr, $rust_type:ty, $c_type:ty, $field:ident) => {
> 
> I think this needs a SAFETY comment, or otherwise the linter will complain.
> 
This is intentional, the SAFETY comes from the caller. This is exactly the
container_of! macro pattern too.

Instead, like container_of, we have a safety header above:

/// # Safety

thanks,

 - Joel