Claude review: rust: interop: Add list module for C linked list interface

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

Patch Review

**Positive aspects:**
- Clean separation of concerns between untyped (`CListHead`/`CListHeadIter`) and typed (`CList`/`CListIter`) layers.
- The `clist_create!` macro's compile-time type check (lines 329-331) that verifies the field path resolves to a `list_head` is a nice safety net.
- Good doctest that exercises the full workflow end-to-end.
- Appropriate documentation directing users to `kernel::list::List` for pure-Rust use cases.

**Observations and minor issues:**

1. **`is_linked()` semantics** (list.rs:156-159): The method uses `&&` to check both pointers:
   ```rust
   unsafe { (*raw).next != raw && (*raw).prev != raw }
   ```
   This means a node is considered "not linked" if *either* pointer is self-referential. For the primary use-case (`is_empty` on the sentinel), this is correct. However, the method name `is_linked` on the public `CListHead` type could be misleading if someone tries to use it on a node removed via `list_del()` (which sets pointers to `LIST_POISON1`/`LIST_POISON2`, not self) — such a poisoned node would appear "linked". This is covered by the type invariants (which require valid pointers), but a brief doc comment on `is_linked` noting it's intended for initialized nodes (not poisoned ones) would improve clarity.

2. **`Sync` safety justification** (list.rs:175-177):
   ```rust
   // SAFETY: `CListHead` can be shared among threads as modifications are
   // not allowed at the moment.
   unsafe impl Sync for CListHead {}
   ```
   The safety argument "modifications are not allowed at the moment" is somewhat fragile — it relies on the *current* absence of mutation APIs rather than a structural guarantee. If mutation methods are added later, this `Sync` impl would need revisiting. Consider strengthening the comment to note this dependency explicitly, e.g., "Safe because `CListHead` exposes no mutation APIs; this must be revisited if mutation is added."

3. **`CListHead::next()` returns `&Self` unconditionally** (list.rs:145-152): This method is public and always succeeds, even when called on the sentinel of an empty list (where it returns the sentinel itself). While this is fine for internal use by the iterator, external callers could be surprised. Since `CListHeadIter` is private and the typed `CListIter` handles sentinel detection properly, this is not a bug, but documenting that `next()` may return the sentinel would be helpful.

4. **`#[macro_export]` namespace** (list.rs:326): The `clist_create!` macro is exported at the crate root as `kernel::clist_create`, not under `kernel::interop::list`. This is standard Rust macro behavior but creates a namespace mismatch. The doctest correctly imports it as `kernel::clist_create` so usage is clear.

5. **`list_add_tail` helper** (list.c:14-17): The C helper `rust_helper_list_add_tail` is defined but only used in the doctest (via `bindings::list_add_tail`). It's not used by the production Rust code since the module is read-only. This is fine — it's needed to set up the test, and future callers (e.g., GPU buddy bindings) will likely need it.

6. **`CList` with `PhantomData`** (list.rs:239): `CList<T, const OFFSET: usize>(CListHead, PhantomData<T>)` is `#[repr(transparent)]`, which is correct since `PhantomData<T>` is a ZST and doesn't affect layout. The cast in `from_raw` (line 257) from `*mut list_head` to `*const CList` is sound because of this.

7. **Feature gate `offset_of_nested`** (lib.rs:31): This was added for the `$($field:tt).+` pattern in the macro allowing nested field paths like `a.b`. The feature is stable since Rust 1.82.0 as noted in the comment block. The kernel's minimum Rust version should be checked to ensure this is available, but since it's grouped with other "Stable since 1.82.0" features, this is presumably fine.

**No blocking issues found.** The patch is clean, well-documented, has good safety invariants, and the API is appropriately minimal for its read-only interop purpose.

---
Generated by Claude Code Patch Reviewer