Re: [PATCH v12 1/1] rust: interop: Add list module for C linked list interface

Miguel Ojeda
2026-03-13T12:58:45Z

On Fri, Mar 6, 2026 at 9:37 PM Joel Fernandes <joelagnelf@nvidia.com> wrote:
>
> Acked-by: Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>

Acked-by: Miguel Ojeda <ojeda@kernel.org>

> +//! # // SAFETY: head and all the items are test objects allocated in this scope.

`head`

> +//! // Rust wrapper for the C struct.

Empty newline comment between these:

//! //

Actually, should this be `//! ///`?

> +//! // The list item struct in this example is defined in C code as:
> +//! // struct SampleItemC {
> +//! // int value;
> +//! // struct list_head link;
> +//! // };
> +//! //

Let's try to use the usual style, i.e. no empty newline at the end of
docs for an item.

And the example should be in a proper code block with a C tag, so all
together something like:

//! /// Rust wrapper for the C struct.
//! ///
//! /// The list item struct in this example is defined in C code as:
//! ///
//! /// ```c
//! /// struct SampleItemC {
//! /// int value;
//! /// struct list_head link;
//! /// };
//! /// ```

> +//! // SAFETY: [`Item`] has same layout as [`SampleItemC`].

No need for intra-doc links in comments (for now at least).

> +//! // Create typed [`CList`] from sentinel head.

Empty newline comment.

> +//! // SAFETY: head is valid and initialized, items are `SampleItemC` with

`head`

However, this is giving me a Clippy issue (please see the other email).

> +/// `next`/`prev` pointers are valid and non-NULL.

We started using `NULL` recently as a convention for the null pointer.

> + // - [`CListHead`] has same layout as `list_head`.

Intra-doc link not needed.

> + // - `ptr` is valid and unmodified for 'a per caller guarantees.

`'a`

> + // SAFETY: self.as_raw() is valid per type invariants.

`self.as_raw()`

> +/// perform conversion of returned [`CListHead`] to an item (using `container_of` macro or similar).

Intra-doc link to `container_of`?

> + // - [`CList`] has same layout as [`CListHead`] due to repr(transparent).

Intra-doc link not needed.

> + // Convert to item using OFFSET.

`OFFSET`

Newline comment after this one.

> +/// Create a C doubly-circular linked list interface `CList` from a raw `list_head` pointer.

[`CList`]

> +/// pointing to a list that is not concurrently modified for the lifetime of the `CList`.

[`CList`]

> +/// Refer to the examples in this module's documentation.

Perhaps we could have an intra-doc link here to the module.

> + // Compile-time check that field path is a list_head.

`list_head`

Cheers,
Miguel