Since now we have support for returning `-> Result`s, we can convert some
of these tests to use the feature, and serve as a first user for it too.
Thus convert them, which allows us to remove some `unwrap()`s.
We keep the actual assertions we want to make as explicit ones with
`assert*!`s.
Reviewed-by: David Gow <davidgow@google.com>
Acked-by: Danilo Krummrich <dakr@kernel.org>
Link: https://lore.kernel.org/r/20250502215133.1923676-6-ojeda@kernel.org
[ Split the `CString` simplification into a new commit. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Simplify the `format!` macro used in the tests by using
`CString::try_from_fmt` and directly `unwrap()`ing.
This will allow us to change both `unwrap()`s here in order to showcase
the `?` operator support now that the tests are KUnit ones.
Reviewed-by: David Gow <davidgow@google.com>
Acked-by: Danilo Krummrich <dakr@kernel.org>
[ Split from the next commit as suggested by Tamir. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Currently, return values of KUnit `#[test]` functions are ignored.
Thus introduce support for `-> Result` functions by checking their
returned values.
At the same time, require that test functions return `()` or `Result<T,
E>`, which should avoid mistakes, especially with non-`#[must_use]`
types. Other types can be supported in the future if needed.
With this, a failing test like:
#[test]
fn my_test() -> Result {
f()?;
Ok(())
}
will output:
[ 3.744214] KTAP version 1
[ 3.744287] # Subtest: my_test_suite
[ 3.744378] # speed: normal
[ 3.744399] 1..1
[ 3.745817] # my_test: ASSERTION FAILED at rust/kernel/lib.rs:321
[ 3.745817] Expected is_test_result_ok(my_test()) to be true, but is false
[ 3.747152] # my_test.speed: normal
[ 3.747199] not ok 1 my_test
[ 3.747345] not ok 4 my_test_suite
Reviewed-by: David Gow <davidgow@google.com>
Acked-by: Danilo Krummrich <dakr@kernel.org>
Link: https://lore.kernel.org/r/20250502215133.1923676-3-ojeda@kernel.org
[ Used `::kernel` for paths. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
The KUnit `#[test]` support that landed recently is very basic and does
not map the `assert*!` macros into KUnit like the doctests do, so they
panic at the moment.
Thus implement the custom mapping in a similar way to doctests, reusing
the infrastructure there.
In Rust 1.88.0, the `file()` method in `Span` may be stable [1]. However,
it was changed recently (from `SourceFile`), so we need to do something
different in previous versions. Thus create a helper for it and use it
to get the path.
With this, a failing test suite like:
#[kunit_tests(my_test_suite)]
mod tests {
use super::*;
#[test]
fn my_first_test() {
assert_eq!(42, 43);
}
#[test]
fn my_second_test() {
assert!(42 >= 43);
}
}
will properly map back to KUnit, printing something like:
[ 1.924325] KTAP version 1
[ 1.924421] # Subtest: my_test_suite
[ 1.924506] # speed: normal
[ 1.924525] 1..2
[ 1.926385] # my_first_test: ASSERTION FAILED at rust/kernel/lib.rs:251
[ 1.926385] Expected 42 == 43 to be true, but is false
[ 1.928026] # my_first_test.speed: normal
[ 1.928075] not ok 1 my_first_test
[ 1.928723] # my_second_test: ASSERTION FAILED at rust/kernel/lib.rs:256
[ 1.928723] Expected 42 >= 43 to be true, but is false
[ 1.929834] # my_second_test.speed: normal
[ 1.929868] not ok 2 my_second_test
[ 1.930032] # my_test_suite: pass:0 fail:2 skip:0 total:2
[ 1.930153] # Totals: pass:0 fail:2 skip:0 total
Link: https://github.com/rust-lang/rust/pull/140514 [1]
Reviewed-by: David Gow <davidgow@google.com>
Acked-by: Danilo Krummrich <dakr@kernel.org>
Link: https://lore.kernel.org/r/20250502215133.1923676-2-ojeda@kernel.org
[ Required `KUNIT=y` like for doctests. Used the `cfg_attr` from the
TODO comment and clarified its comment now that the stabilization is
in beta and thus quite likely stable in Rust 1.88.0. Simplified the
`new_body` code by introducing a new variable. Added
`#[allow(clippy::incompatible_msrv)]`. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Commit dbd5058ba6 ("rust: make pin-init its own crate") moved all
items from pin-init into the pin-init crate, including the
`assert_pinned!` macro.
Thus fix the path of the sole user of the `assert_pinned!` macro.
This occurrence was missed in the commit above, since it is in a macro
rule that has no current users (although binder is a future user).
Cc: stable@kernel.org
Fixes: dbd5058ba6 ("rust: make pin-init its own crate")
Signed-off-by: Benno Lossin <lossin@kernel.org>
Link: https://lore.kernel.org/r/20250525173450.853413-1-lossin@kernel.org
[ Reworded slightly as discussed in the list. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
In particular:
- Add missing Markdown code spans.
- Improve title for `DeviceId`, adding a link to the struct in the
C side, rather than referring to `bindings::`.
- Convert `TODO` from documentation to a normal comment, and put code
in block.
This was found using the Clippy `doc_markdown` lint, which we may want
to enable.
Fixes: 1bd8b6b2c5 ("rust: pci: add basic PCI device / driver abstractions")
Reviewed-by: Benno Lossin <benno.lossin@proton.me>
Acked-by: Danilo Krummrich <dakr@kernel.org>
Link: https://lore.kernel.org/r/20250324210359.1199574-8-ojeda@kernel.org
[ Prefixed link text with `struct`. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Rust kernel code is supposed to use the custom mapping of C FFI types,
i.e. those from the `ffi` crate, rather than the ones coming from `core`.
Thus, to minimize mistakes and to simplify the code everywhere, just
provide them in the `kernel` prelude and ask in the Coding Guidelines
to use them directly, i.e. as a single segment path.
After this lands, we can start cleaning up the existing users.
Ideally, we would use something like Clippy's `disallowed-types` to
prevent the use of the `core` ones, but that one sees through aliases.
Link: https://lore.kernel.org/rust-for-linux/CANiq72kc4gzfieD-FjuWfELRDXXD2vLgPv4wqk3nt4pjdPQ=qg@mail.gmail.com/
Reviewed-by: Danilo Krummrich <dakr@kernel.org>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20250413005650.1745894-1-ojeda@kernel.org
[ Reworded content of the documentation to focus on how to use the
aliases first. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
`bindgen` currently generates the wrong type for an `enum` when there
is a forward reference to it. For instance:
enum E;
enum E { A };
generates:
pub const E_A: E = 0;
pub type E = i32;
instead of the expected:
pub const E_A: E = 0;
pub type E = ffi::c_uint;
The issue was reported to upstream `bindgen` [1].
Now, both GCC and Clang support silently these forward references to
`enum` types, unless `-Wpedantic` is passed, and it turns out that some
headers in the kernel depend on them.
Thus, depending on how the headers are included, which in turn may depend
on the kernel configuration or the architecture, we may get a different
type on the Rust side for a given C `enum`.
That can be quite confusing, to say the least, especially since
developers may only notice issues when building for other architectures
like in [2]. In particular, they may end up forcing a cast and adding
an `#[allow(clippy::unnecessary_cast)]` like it was done in commit
94e05a66ea ("rust: hrtimer: allow timer restart from timer handler"),
which isn't great.
Instead, let's have a section at the top of our `bindings_helper.h` that
`#include`s the headers with the affected types -- hopefully there are
not many cases and there is a single ordering that covers all cases.
This allows us to remove the cast and the `#[allow]`, thus keeping the
correct code in the source files. When the issue gets resolved in upstream
`bindgen` (and we update our minimum `bindgen` version), we can easily
remove this section at the top.
Link: https://github.com/rust-lang/rust-bindgen/issues/3179 [1]
Link: https://lore.kernel.org/rust-for-linux/87tt7md1s6.fsf@kernel.org/ [2]
Acked-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250325184309.97170-1-ojeda@kernel.org
[ Added extra paragraph on the comment to clarify that the workaround may
not be possible in some cases. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
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 52ae96f518 ("rust: list: make the
cursor point between elements").
Link: https://github.com/Rust-for-Linux/linux/issues/1121
Signed-off-by: I Hsin Cheng <richard120310@gmail.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Benno Lossin <lossin@kernel.org>
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 <ojeda@kernel.org>
"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 <richard120310@gmail.com>
Link: https://lore.kernel.org/r/20250310073853.427954-1-richard120310@gmail.com
Reviewed-by: Benno Lossin <lossin@kernel.org>
[ Rebased dropping the cases that do not apply anymore. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
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 a39f308709 ("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 <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20250520182125.806758-1-ojeda@kernel.org
[ Reworded for clarity. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Pull XArray updates from Andreas Hindborg:
"Introduce Rust support for the 'xarray' data structure:
- Add a Rust abstraction for the 'xarray' data structure. This
abstraction allows Rust code to leverage the 'xarray' to store
types that implement 'ForeignOwnable'. This support is a dependency
for memory backing feature of the Rust null block driver, which is
waiting to be merged.
- Set up an entry in MAINTAINERS for the XArray Rust support. Patches
will go to the new Rust XArray tree and then via the Rust subsystem
tree for now.
'kernel' crate:
- Allow 'ForeignOwnable' to carry information about the pointed-to
type. This helps asserting alignment requirements for the pointer
passed to the foreign language."
* tag 'rust-xarray-for-v6.16' of https://github.com/Rust-for-Linux/linux:
MAINTAINERS: add entry for Rust XArray API
rust: xarray: Add an abstraction for XArray
rust: types: add `ForeignOwnable::PointedTo`
Pull timekeeping updates from Andreas Hindborg:
- Morph the Rust hrtimer subsystem into the Rust timekeeping subsystem,
covering delay, sleep, timekeeping, timers. This new subsystem has
all the relevant timekeeping C maintainers listed in the entry.
- Replace 'Ktime' with 'Delta' and 'Instant' types to represent a
duration of time and a point in time.
- Temporarily add 'Ktime' to 'hrtimer' module to allow 'hrtimer' to
delay converting to 'Instant' and 'Delta'.
* tag 'rust-timekeeping-for-v6.16-v2' of https://github.com/Rust-for-Linux/linux:
MAINTAINERS: rust: Add a new section for all of the time stuff
rust: time: Introduce Instant type
rust: time: Introduce Delta type
rust: time: Add PartialEq/Eq/PartialOrd/Ord trait to Ktime
rust: hrtimer: Add Ktime temporarily
We track the details of which Rust features we use at our usual "live
list" [1] (and its sub-lists), but in light of a discussion in the LWN
article [2], it would help to clarify it in the source code.
In particular, we are very close to rely only on stable Rust language-wise
-- essentially only two language features remain (including the `kernel`
crate).
Thus add some details in both the feature list of the `kernel` crate as
well as the list of allowed features.
This does not over every single feature, and there are quite a few
non-language features that we use too. To have the full picture, please
refer to [1].
Link: https://github.com/Rust-for-Linux/linux/issues/2 [1]
Link: https://lwn.net/Articles/1015409/ [2]
Suggested-by: Andreas Hindborg <a.hindborg@kernel.org>
Reviewed-by: Benno Lossin <benno.lossin@proton.me>
Link: https://lore.kernel.org/r/20250327211302.286313-1-ojeda@kernel.org
[ Improved comments with suggestions from the list. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
When build the kernel using the llvm-18.1.3-rust-1.85.0-x86_64
with ARCH=arm64, the following symbols are generated:
$nm vmlinux | grep ' _R'.*Page | rustfilt
ffff8000805b6f98 T <kernel::page::Page>::alloc_page
ffff8000805b715c T <kernel::page::Page>::fill_zero_raw
ffff8000805b720c T <kernel::page::Page>::copy_from_user_slice_raw
ffff8000805b6fb4 T <kernel::page::Page>::read_raw
ffff8000805b7088 T <kernel::page::Page>::write_raw
ffff8000805b72fc T <kernel::page::Page as core::ops::drop::Drop>::drop
These Rust symbols(alloc_page and drop) are trivial wrappers around the C
functions alloc_pages and __free_pages. It doesn't make sense to go
through a trivial wrapper for these functions, so mark them inline.
Link: https://github.com/Rust-for-Linux/linux/issues/1145
Suggested-by: Alice Ryhl <aliceryhl@google.com>
Co-developed-by: Grace Deng <Grace.Deng006@Gmail.com>
Signed-off-by: Grace Deng <Grace.Deng006@Gmail.com>
Signed-off-by: Kunwu Chan <kunwu.chan@hotmail.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20250321080124.484647-1-kunwu.chan@linux.dev
[ Removed spurious colon in title. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
This is needed by Rust Binder in the range allocator, and by upcoming
GPU drivers during firmware initialization.
Panics in the kernel are best avoided when possible, so an error is
returned if the index is out of bounds. An error type is used rather
than just returning Option<T> to let callers handle errors with ?.
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Benno Lossin <lossin@kernel.org>
Link: https://lore.kernel.org/r/20250502-vec-methods-v5-6-06d20ad9366f@google.com
[ Remove `# Panics` section; `Vec::remove() handles the error properly.`
- Danilo ]
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
This adds a common Vec method called `retain` that removes all elements
that don't match a certain condition. Rust Binder uses it to find all
processes that match a given pid.
The stdlib retain method takes &T rather than &mut T and has a separate
retain_mut for the &mut T case. However, this is considered an API
mistake that can't be fixed now due to backwards compatibility. There's
no reason for us to repeat that mistake.
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Benno Lossin <lossin@kernel.org>
Link: https://lore.kernel.org/r/20250502-vec-methods-v5-5-06d20ad9366f@google.com
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
This is like the stdlib method drain, except that it's hard-coded to use
the entire vector's range. Rust Binder uses it in the range allocator to
take ownership of everything in a vector in a case where reusing the
vector is desirable.
Implementing `DrainAll` in terms of `slice::IterMut` lets us reuse some
nice optimizations in core for the case where T is a ZST.
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Benno Lossin <lossin@kernel.org>
Link: https://lore.kernel.org/r/20250502-vec-methods-v5-4-06d20ad9366f@google.com
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
This introduces a new method called `push_within_capacity` for appending
to a vector without attempting to allocate if the capacity is full. Rust
Binder will use this in various places to safely push to a vector while
holding a spinlock.
The implementation is moved to a push_within_capacity_unchecked method.
This is preferred over having push() call push_within_capacity()
followed by an unwrap_unchecked() for simpler unsafe.
Panics in the kernel are best avoided when possible, so an error is
returned if the vector does not have sufficient capacity. An error type
is used rather than just returning Result<(),T> to make it more
convenient for callers (i.e. they can use ? or unwrap).
Signed-off-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Reviewed-by: Benno Lossin <lossin@kernel.org>
Link: https://lore.kernel.org/r/20250502-vec-methods-v5-3-06d20ad9366f@google.com
[ Remove public visibility from `Vec::push_within_capacity_unchecked()`.
- Danilo ]
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
Starting with Rust 1.88.0 (expected 2025-06-26) [1], `rustc` may move
back the `uninlined_format_args` to `style` from `pedantic` (it was
there waiting for rust-analyzer suppotr), and thus we will start to see
lints like:
warning: variables can be used directly in the `format!` string
--> rust/macros/kunit.rs:105:37
|
105 | let kunit_wrapper_fn_name = format!("kunit_rust_wrapper_{}", test);
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#uninlined_format_args
help: change this to
|
105 - let kunit_wrapper_fn_name = format!("kunit_rust_wrapper_{}", test);
105 + let kunit_wrapper_fn_name = format!("kunit_rust_wrapper_{test}");
There is even a case that is a pure removal:
warning: variables can be used directly in the `format!` string
--> rust/macros/module.rs:51:13
|
51 | format!("{field}={content}\0", field = field, content = content)
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#uninlined_format_args
help: change this to
|
51 - format!("{field}={content}\0", field = field, content = content)
51 + format!("{field}={content}\0")
The lints all seem like nice cleanups, thus just apply them.
We may want to disable `allow-mixed-uninlined-format-args` in the future.
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/14160 [1]
Acked-by: Benno Lossin <lossin@kernel.org>
Reviewed-by: Tamir Duberstein <tamird@gmail.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20250502140237.1659624-6-ojeda@kernel.org
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Allow implementors to specify the foreign pointer type; this exposes
information about the pointed-to type such as its alignment.
This requires the trait to be `unsafe` since it is now possible for
implementors to break soundness by returning a misaligned pointer.
Encoding the pointer type in the trait (and avoiding pointer casts)
allows the compiler to check that implementors return the correct
pointer type. This is preferable to directly encoding the alignment in
the trait using a constant as the compiler would be unable to check it.
Acked-by: Danilo Krummrich <dakr@kernel.org>
Signed-off-by: Tamir Duberstein <tamird@gmail.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20250423-rust-xarray-bindings-v19-1-83cdcf11c114@gmail.com
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
Introduce a type representing a span of time. Define our own type
because `core::time::Duration` is large and could panic during
creation.
time::Ktime could be also used for time duration but timestamp and
timedelta are different so better to use a new type.
i64 is used instead of u64 to represent a span of time; some C drivers
uses negative Deltas and i64 is more compatible with Ktime using i64
too (e.g., ktime_[us|ms]_delta() APIs return i64 so we create Delta
object without type conversion.
i64 is used instead of bindings::ktime_t because when the ktime_t
type is used as timestamp, it represents values from 0 to
KTIME_MAX, which is different from Delta.
as_millis() method isn't used in this patchset. It's planned to be
used in Binder driver.
Reviewed-by: Andrew Lunn <andrew@lunn.ch>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Tested-by: Daniel Almeida <daniel.almeida@collabora.com>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Signed-off-by: FUJITA Tomonori <fujita.tomonori@gmail.com>
Link: https://lore.kernel.org/r/20250423192857.199712-4-fujita.tomonori@gmail.com
Signed-off-by: Andreas Hindborg <a.hindborg@kernel.org>
Add `Vec::dec_len` that reduces the length of the receiver. This method
is intended to be used from methods that remove elements from `Vec` such
as `truncate`, `pop`, `remove`, and others. This method is intentionally
not `pub`.
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Signed-off-by: Tamir Duberstein <tamird@gmail.com>
Link: https://lore.kernel.org/r/20250416-vec-set-len-v4-2-112b222604cd@gmail.com
[ Add #[expect(unused)] to dec_len(). - Danilo ]
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
