linux.git/rust/kernel/list.rs, branch v6.18.21

rust: list: Add an example for `ListLinksSelfPtr` usage

2025-09-14T23:10:23+00:00

It appears that the support for `ListLinksSelfPtr` is dead code at the
moment [1]. Although some tests were added at [2] for impl `ListItem`
using `ListLinksSelfPtr` field, still we could use more examples
demonstrating and testing the usage of `ListLinksSelfPtr`. Hence add an
example similar to `ListLinks` usage.

The example is mostly based on Alice's usage in binder driver [3].

Link: https://lore.kernel.org/rust-for-linux/20250719183649.596051-1-ojeda@kernel.org/ [1]
Link: https://lore.kernel.org/rust-for-linux/20250709-list-no-offset-v4-5-a429e75840a9@gmail.com/ [2]
Link: https://lore.kernel.org/rust-for-linux/20231101-rust-binder-v1-4-08ba9197f637@google.com/ [3]
Signed-off-by: Boqun Feng 
Reviewed-by: Alice Ryhl 
[ Fixed typo. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: list: remove OFFSET constants

2025-07-19T21:18:18+00:00

Replace `ListLinksSelfPtr::LIST_LINKS_SELF_PTR_OFFSET` with `unsafe fn
raw_get_self_ptr` which returns a pointer to the field rather than
requiring the caller to do pointer arithmetic.

Implement `HasListLinks::raw_get_list_links` in `impl_has_list_links!`,
narrowing the interface of `HasListLinks` and replacing pointer
arithmetic with `container_of!`.

Modify `impl_list_item` to also invoke `impl_has_list_links!` or
`impl_has_list_links_self_ptr!`. This is necessary to allow
`impl_list_item` to see more of the tokens used by
`impl_has_list_links{,_self_ptr}!`.

A similar API change was discussed on the hrtimer series[1].

Link: https://lore.kernel.org/all/20250224-hrtimer-v3-v6-12-rc2-v9-1-5bd3bf0ce6cc@kernel.org/ [1]
Tested-by: Alice Ryhl 
Reviewed-by: Alice Ryhl 
Signed-off-by: Tamir Duberstein 
Link: https://lore.kernel.org/r/20250709-list-no-offset-v4-6-a429e75840a9@gmail.com
[ Fixed broken intra-doc links. Used the renamed
  `Opaque::cast_into`. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: types: rename Opaque::raw_get to cast_into

2025-07-15T20:26:11+00:00

In the previous patch we added Opaque::cast_from() that performs the
opposite operation to Opaque::raw_get(). For consistency with this
naming, rename raw_get() to cast_from().

There are a few other options such as calling cast_from() something
closer to raw_get() rather than renaming this method. However, I could
not find a great naming scheme that works with raw_get(). The previous
version of this patch used from_raw(), but functions of that name
typically have a different signature, so that's not a great option.

Suggested-by: Danilo Krummrich 
Signed-off-by: Alice Ryhl 
Acked-by: Benno Lossin 
Acked-by: Andreas Hindborg 
Acked-by: Boqun Feng 
Reviewed-by: Danilo Krummrich 
Acked-by: Danilo Krummrich 
Link: https://lore.kernel.org/r/20250624-opaque-from-raw-v2-2-e4da40bdc59c@google.com
[ Removed `HrTimer::raw_get` change. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: list: replace unwrap() with ? in doctest examples

2025-06-23T23:01:12+00:00

Using `unwrap()` in kernel doctests can cause panics on error and may
give newcomers the mistaken impression that panicking is acceptable
in kernel code.

Replace all `.unwrap()` calls in `kernel::list`
examples with `.ok_or(EINVAL)?` so that errors are properly propagated.

Suggested-by: Miguel Ojeda 
Link: https://github.com/Rust-for-Linux/linux/issues/1164
Reviewed-by: Benno Lossin 
Signed-off-by: Albin Babu Varghese 
Reviewed-by: Alice Ryhl 
Reviewed-by: Danilo Krummrich 
Link: https://lore.kernel.org/r/20250527204928.5117-1-albinbabuvarghese20@gmail.com
[ Reworded slightly. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: list: Add examples for linked list

2025-05-22T10:00:52+00:00

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:37+00:00

"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:50+00:00

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:02+00:00

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:19+00:00

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:34+00:00

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