linux/rust/kernel/list.rs, branch v6.16

rust: list: Add examples for linked list

2025-05-22T10:00:52Z

Add basic examples for the structure "List", which also serve as unit tests for basic list methods. It includes the following manipulations: * List creation * List emptiness check * List insertion through push_front(), push_back() * List item removal through pop_front(), pop_back() * Push one list to another through push_all_back() The method "remove()" doesn't have an example here because insertion with push_front() or push_back() will take the ownership of the item, which means we can't keep any valid reference to the node we want to remove, unless Cursor is used. The "remove" example through Cursor is already demonstrated with commit 52ae96f5187c ("rust: list: make the cursor point between elements"). Link: https://github.com/Rust-for-Linux/linux/issues/1121 Signed-off-by: I Hsin Cheng Reviewed-by: Alice Ryhl Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20250311133357.90322-1-richard120310@gmail.com [ Removed prelude import and spurious newlines. Formatted comments with the usual style. Reworded slightly. - Miguel ] Signed-off-by: Miguel Ojeda

rust: list: Use "List::is_empty()" to perform checking when possible

2025-05-22T10:00:37Z

"List::is_empty()" provides a straight forward convention to check whether a given "List" is empty or not. There're numerous places in the current implementation still use "self.first.is_null()" to perform the equivalent check, replace them with "List::is_empty()". Signed-off-by: I Hsin Cheng Link: https://lore.kernel.org/r/20250310073853.427954-1-richard120310@gmail.com Reviewed-by: Benno Lossin [ Rebased dropping the cases that do not apply anymore. - Miguel ] Signed-off-by: Miguel Ojeda

rust: remove unneeded Rust 1.87.0 `allow(clippy::ptr_eq)`

2025-05-22T09:46:50Z

For the Rust 1.87.0 release, Clippy was expected to warn with: error: use `core::ptr::eq` when comparing raw pointers --> rust/kernel/list.rs:438:12 | 438 | if self.first == item { | ^^^^^^^^^^^^^^^^^^ help: try: `core::ptr::eq(self.first, item)` | = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#ptr_eq = note: `-D clippy::ptr-eq` implied by `-D warnings` = help: to override `-D warnings` add `#[allow(clippy::ptr_eq)]` However, a backport to relax a bit the `clippy::ptr_eq` finally landed, and thus Clippy did not warn by the time the release happened. Thus remove the `allow`s added back then, which were added just in case the backport did not land in time. See commit a39f30870927 ("rust: allow Rust 1.87.0's `clippy::ptr_eq` lint") for details. Link: https://github.com/rust-lang/rust/pull/140859 [1] Reviewed-by: Alice Ryhl Link: https://lore.kernel.org/r/20250520182125.806758-1-ojeda@kernel.org [ Reworded for clarity. - Miguel ] Signed-off-by: Miguel Ojeda

rust: allow Rust 1.87.0's `clippy::ptr_eq` lint

2025-05-06T22:11:02Z

Starting with Rust 1.87.0 (expected 2025-05-15) [1], Clippy may expand the `ptr_eq` lint, e.g.: error: use `core::ptr::eq` when comparing raw pointers --> rust/kernel/list.rs:438:12 | 438 | if self.first == item { | ^^^^^^^^^^^^^^^^^^ help: try: `core::ptr::eq(self.first, item)` | = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#ptr_eq = note: `-D clippy::ptr-eq` implied by `-D warnings` = help: to override `-D warnings` add `#[allow(clippy::ptr_eq)]` It is expected that a PR to relax the lint will be backported [2] by the time Rust 1.87.0 releases, since the lint was considered too eager (at least by default) [3]. Thus allow the lint temporarily just in case. Cc: stable@vger.kernel.org # Needed in 6.12.y and later (Rust is pinned in older LTSs). Link: https://github.com/rust-lang/rust-clippy/pull/14339 [1] Link: https://github.com/rust-lang/rust-clippy/pull/14526 [2] Link: https://github.com/rust-lang/rust-clippy/issues/14525 [3] Link: https://lore.kernel.org/r/20250502140237.1659624-3-ojeda@kernel.org [ Converted to `allow`s since backport was confirmed. - Miguel ] Signed-off-by: Miguel Ojeda

rust: make pin-init its own crate

2025-03-16T20:59:19Z

Rename relative paths inside of the crate to still refer to the same items, also rename paths inside of the kernel crate and adjust the build system to build the crate. [ Remove the `expect` (and thus the `lint_reasons` feature) since the tree now uses `quote!` from `rust/macros/export.rs`. Remove the `TokenStream` import removal, since it is now used as well. In addition, temporarily (i.e. just for this commit) use an `--extern force:alloc` to prevent an unknown `new_uninit` error in the `rustdoc` target. For context, please see a similar case in: https://lore.kernel.org/lkml/20240422090644.525520-1-ojeda@kernel.org/ And adjusted the message above. - Miguel ] Signed-off-by: Benno Lossin Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-16-benno.lossin@proton.me Signed-off-by: Miguel Ojeda

rust: list: make the cursor point between elements

2025-03-08T21:35:34Z

I've been using the linked list cursor for a few different things, and I find it inconvenient to use because all of the functions have signatures along the lines of `Self -> Option`. The root cause of these signatures is that the cursor points *at* an element, rather than *between* two elements. Thus, change the cursor API to point between two elements. This is inspired by the stdlib linked list (well, really by this guy [1]), which also uses cursors that point between elements. The `peek_next` method returns a helper that lets you look at and optionally remove the element, as one common use-case of cursors is to iterate a list to look for an element, then remove that element. For many of the methods, this will reduce how many we need since they now just need a prev/next method, instead of the current state where you may end up needing all of curr/prev/next. Also, if we decide to add a function for splitting a list into two lists at the cursor, then a cursor that points between elements is exactly what makes the most sense. Another advantage is that this means you can now have a cursor into an empty list. Link: https://rust-unofficial.github.io/too-many-lists/sixth-cursors-intro.html [1] Reviewed-by: Andreas Hindborg Reviewed-by: Boqun Feng Signed-off-by: Alice Ryhl Link: https://lore.kernel.org/r/20250210-cursor-between-v7-2-36f0215181ed@google.com Signed-off-by: Miguel Ojeda

rust: list: extract common code for insertion

2025-03-08T21:35:34Z

To prepare for a new cursor API that has the ability to insert elements into the list, extract the common code needed for this operation into a new `insert_inner` method. Both `push_back` and `push_front` are updated to use the new function. Reviewed-by: Andreas Hindborg Reviewed-by: Boqun Feng Signed-off-by: Alice Ryhl Link: https://lore.kernel.org/r/20250210-cursor-between-v7-1-36f0215181ed@google.com Signed-off-by: Miguel Ojeda

rust: enable `clippy::undocumented_unsafe_blocks` lint

2024-10-07T19:39:05Z

Checking that we are not missing any `// SAFETY` comments in our `unsafe` blocks is something we have wanted to do for a long time, as well as cleaning up the remaining cases that were not documented [1]. Back when Rust for Linux started, this was something that could have been done via a script, like Rust's `tidy`. Soon after, in Rust 1.58.0, Clippy implemented the `undocumented_unsafe_blocks` lint [2]. Even though the lint has a few false positives, e.g. in some cases where attributes appear between the comment and the `unsafe` block [3], there are workarounds and the lint seems quite usable already. Thus enable the lint now. We still have a few cases to clean up, so just allow those for the moment by writing a `TODO` comment -- some of those may be good candidates for new contributors. Link: https://github.com/Rust-for-Linux/linux/issues/351 [1] Link: https://rust-lang.github.io/rust-clippy/master/#/undocumented_unsafe_blocks [2] Link: https://github.com/rust-lang/rust-clippy/issues/13189 [3] Reviewed-by: Alice Ryhl Reviewed-by: Trevor Gross Tested-by: Gary Guo Reviewed-by: Gary Guo Link: https://lore.kernel.org/r/20240904204347.168520-5-ojeda@kernel.org Signed-off-by: Miguel Ojeda

rust: list: add ListArcField

2024-08-23T04:26:57Z

One way to explain what `ListArc` does is that it controls exclusive access to the prev/next pointer field in a refcounted object. The feature of having a special reference to a refcounted object with exclusive access to specific fields is useful for other things, so provide a general utility for that. This is used by Rust Binder to keep track of which processes have a reference to a given node. This involves an object for each process/node pair, that is referenced by both the process and the node. For some fields in this object, only the process's reference needs to access them (and it needs mutable access), so Binder uses a ListArc to give the process's reference exclusive access. Reviewed-by: Benno Lossin Signed-off-by: Alice Ryhl Link: https://lore.kernel.org/r/20240814-linked-list-v5-10-f5f5e8075da0@google.com Signed-off-by: Miguel Ojeda

rust: list: support heterogeneous lists

2024-08-23T04:26:57Z

Support linked lists that can hold many different structs at once. This is generally done using trait objects. The main challenge is figuring what the struct is given only a pointer to the ListLinks. We do this by storing a pointer to the struct next to the ListLinks field. The container_of operation will then just read that pointer. When the type is a trait object, that pointer will be a fat pointer whose metadata is a vtable that tells you what kind of struct it is. Heterogeneous lists are heavily used by Rust Binder. There are a lot of so-called todo lists containing various events that need to be delivered to userspace next time userspace calls into the driver. And there are quite a few different todo item types: incoming transaction, changes to refcounts, death notifications, and more. Reviewed-by: Benno Lossin Signed-off-by: Alice Ryhl Link: https://lore.kernel.org/r/20240814-linked-list-v5-9-f5f5e8075da0@google.com Signed-off-by: Miguel Ojeda