Claude review: rust: clist: Add support to interface with C linked lists

[Claude Code Review Bot <claude-review@example.com>]

Patch Review

This is the main patch. Several observations:

**1. `is_linked()` semantic mismatch with C `list_empty()`**

```rust
pub fn is_linked(&self) -> bool {
    let raw = self.as_raw();
    // SAFETY: self.as_raw() is valid per type invariants.
    unsafe { (*raw).next != raw && (*raw).prev != raw }
}
```

The C `list_empty()` only checks `head->next == head`. This implementation checks *both* `next` and `prev`, which is closer to `list_empty_careful()` but without any memory ordering guarantees. After `list_del()` (not `list_del_init()`), a node's pointers are set to `LIST_POISON1`/`LIST_POISON2` -- neither points to self, so `is_linked()` would return `true` for a deleted (poisoned) node. This may be intentional since the safety requirements demand proper initialization, but it's worth noting that this differs from C's `list_empty()` semantics. Consider whether checking only `next != self` (matching `list_empty()`) would be more appropriate, or document the behavioral difference.

The `is_linked()` method is only used by `CList::is_empty()`:
```rust
pub fn is_empty(&self) -> bool {
    !self.0.is_linked()
}
```

For the sentinel head, after `INIT_LIST_HEAD()`, both `next` and `prev` point to self, so both checks are equivalent there. The `&&` vs `||` vs single-check distinction only matters for edge cases (e.g., partially modified nodes), which shouldn't arise if the safety invariants hold.

**2. `list_add_tail` helper is unused**

```c
__rust_helper void rust_helper_list_add_tail(struct list_head *new, struct list_head *head)
{
	list_add_tail(new, head);
}
```

This helper is added in `rust/helpers/list.c` but never used by any Rust code in this patch. The doctest only calls `bindings::list_add_tail` and `bindings::INIT_LIST_HEAD` -- the `INIT_LIST_HEAD` helper is also defined here but the `list_add_tail` helper appears to be dead code added for future use. Kernel convention generally avoids adding unused helpers; consider dropping `rust_helper_list_add_tail` from this patch and adding it when it's actually needed.

**3. `Send`/`Sync` safety justification could be stronger**

```rust
// SAFETY: `list_head` contains no thread-bound state; it only holds
// `next`/`prev` pointers.
unsafe impl Send for CListHead {}

// SAFETY: `CListHead` can be shared among threads as modifications are
// not allowed at the moment.
unsafe impl Sync for CListHead {}
```

The `Sync` justification "modifications are not allowed at the moment" is a bit weak -- it relies on the current API surface being read-only rather than any inherent property. If mutation APIs are added later, this `Sync` impl would become unsound. The safety comment should note that `Sync` is valid because the type invariants require exclusive access (no concurrent modification) for the lifetime of any `&CListHead`, as documented in `from_raw()`.

**4. `FusedIterator` for `CListHeadIter` needs justification**

```rust
impl<'a> FusedIterator for CListHeadIter<'a> {}
```

`FusedIterator` guarantees that after `next()` returns `None`, it will always return `None`. This is correct here because once `current == sentinel`, subsequent calls still see `current == sentinel` (the field isn't modified after returning `None`). However, the impl is missing a `// SAFETY:` comment explaining why this contract holds, which is customary for unsafe-adjacent guarantees.

**5. The `clist_create!` macro field type check**

```rust
let _: fn(*const $c_type) -> *const $crate::bindings::list_head =
    |p| unsafe { &raw const (*p).$($field).+ };
```

This is a clever compile-time check that the field is a `list_head`. Good practice.

**6. `#![feature(offset_of_nested)]` addition**

```rust
#![feature(offset_of_nested)]
```

This is placed in the "Stable since Rust 1.82.0" section block, but `offset_of_nested` was stabilized in Rust 1.87.0, not 1.82.0. It should be in its own section with the correct stabilization version, or under a "To be determined" / "Expected to become stable" section if the kernel's minimum Rust version hasn't reached 1.87 yet. Looking at the patch context, it's inserted between the `#![feature(lint_reasons)]` (1.81.0) and `#![feature(raw_ref_op)]` (1.82.0) comments, so it's in the wrong location regardless.

**7. Minor: Trailing `//` comment markers on imports**

```rust
use core::{
    iter::FusedIterator,
    marker::PhantomData, //
};
```

The trailing `//` comments on the last items in use groups appear to be rustfmt workarounds to force multi-line formatting. This is a known pattern but looks a bit unusual. The cover letter mentions "Removed unnecessary trailing comment markers from example imports" -- these remain in the non-example code.

**8. The doctest is thorough but heavy**

The module-level doctest is comprehensive, showing the full lifecycle from creating a C list to iterating over it from Rust. The hidden boilerplate is necessarily long since it must simulate C-side list setup. This is fine.

**9. Safety documentation for `CList::from_raw` is good**

The safety requirements are well-documented:
```rust
/// - `ptr` must be a valid pointer to an initialized sentinel `list_head`
/// - `ptr` must remain valid for the lifetime `'a`.
/// - The list and all linked nodes must not be concurrently modified 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.
```

This is clear and complete.

**Summary of actionable items:**

- **Drop `rust_helper_list_add_tail`** if it has no in-tree user (minor, but follows kernel convention).
- **Fix `#![feature(offset_of_nested)]` placement** -- it's in the wrong stabilization version comment block.
- **Consider strengthening the `Sync` safety comment** to reference the lifetime-bound immutability invariant rather than "at the moment."

---
Generated by Claude Code Patch Reviewer