mirror of https://github.com/torvalds/linux.git
8 Commits
| Author | SHA1 | Message | Date |
|---|---|---|---|
Gary Guo
|
889c8c934d |
rust: rework `build_assert!` documentation
Add a detailed comparison and recommendation of the three types of build-time assertion macro as module documentation (and un-hide the module to render them). The documentation on the macro themselves are simplified to only cover the scenarios where they should be used; links to the module documentation is added instead. Reviewed-by: Yury Norov <ynorov@nvidia.com> Signed-off-by: Gary Guo <gary@garyguo.net> Reviewed-by: Alexandre Courbot <acourbot@nvidia.com> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Danilo Krummrich <dakr@kernel.org> Link: https://patch.msgid.link/20260319121653.2975748-4-gary@kernel.org [ Added periods on comments. - Miguel ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org> |
|
|
Gary Guo
|
560a7a9b92 |
rust: add `const_assert!` macro
The macro is a more powerful version of `static_assert!` for use inside
function contexts. This is powered by inline consts, so enable the feature
for old compiler versions that does not have it stably.
While it is possible already to write `const { assert!(...) }`, this
provides a short hand that is more uniform with other assertions. It also
formats nicer with rustfmt where it will not be formatted into multiple
lines.
Two users that would route via the Rust tree are converted.
Reviewed-by: Yury Norov <ynorov@nvidia.com>
Signed-off-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Alexandre Courbot <acourbot@nvidia.com>
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Reviewed-by: Danilo Krummrich <dakr@kernel.org>
Link: https://patch.msgid.link/20260319121653.2975748-3-gary@kernel.org
[ Rebased. Fixed period typo. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
|
|
|
Gary Guo
|
abfe5ee997 |
rust: move `static_assert` into `build_assert`
Conceptually, `static_assert` is also a build-time assertion that occurs earlier in the pipeline. Consolidate the implementation so that we can use this as the canonical place to add more useful build-time assertions. Reviewed-by: Yury Norov <ynorov@nvidia.com> Signed-off-by: Gary Guo <gary@garyguo.net> Reviewed-by: Alice Ryhl <aliceryhl@google.com> Reviewed-by: Danilo Krummrich <dakr@kernel.org> Link: https://patch.msgid.link/20260319121653.2975748-2-gary@kernel.org [ Used kernel vertical style. - Miguel ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org> |
|
Alexandre Courbot
|
1b18b37a2c |
rust: build_assert: add instructions for use with function arguments
`build_assert` relies on the compiler to optimize out its error path,
lest build fails with the dreaded error:
ERROR: modpost: "rust_build_error" [path/to/module.ko] undefined!
It has been observed that very trivial code performing I/O accesses
(sometimes even using an immediate value) would seemingly randomly fail
with this error whenever `CLIPPY=1` was set. The same behavior was also
observed until different, very similar conditions [1][2].
The cause appears to be that the failing function is eventually using
`build_assert` with its argument, but is only annotated with
`#[inline]`. This gives the compiler freedom to not inline the function,
which it notably did when Clippy was active, triggering the error.
The fix is to annotate functions passing their argument to
`build_assert` with `#[inline(always)]`, telling the compiler to be as
aggressive as possible with their inlining. This is also the correct
behavior as inlining is mandatory for correct behavior in these cases.
Add a paragraph instructing to annotate such functions with
`#[inline(always)]` in `build_assert`'s documentation, and split its
example to illustrate.
Reviewed-by: Daniel Almeida <daniel.almeida@collabora.com>
Signed-off-by: Alexandre Courbot <acourbot@nvidia.com>
Link: https://patch.msgid.link/20251208-io-build-assert-v3-1-98aded02c1ea@nvidia.com
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
|
|
Miguel Ojeda
|
4401565fe9 |
rust: add `build_error!` to the prelude
The sibling `build_assert!` is already in the prelude, it makes sense that a "core"/"language" facility like this is part of the prelude and users should not be defining their own one (thus there should be no risk of future name collisions and we would want to be aware of them anyway). Thus add `build_error!` into the prelude. Reviewed-by: Alice Ryhl <aliceryhl@google.com> Link: https://lore.kernel.org/r/20241123222849.350287-3-ojeda@kernel.org [ Applied the change to the new miscdevice cases. - Miguel ] Signed-off-by: Miguel Ojeda <ojeda@kernel.org> |
|
|
Miguel Ojeda
|
614724e780 |
rust: kernel: move `build_error` hidden function to prevent mistakes
Users were using the hidden exported `kernel::build_error` function
instead of the intended `kernel::build_error!` macro, e.g. see the
previous commit.
To force to use the macro, move it into the `build_assert` module,
thus making it a compilation error and avoiding a collision in the same
"namespace". Using the function now would require typing the module name
(which is hidden), not just a single character.
Now attempting to use the function will trigger this error with the
right suggestion by the compiler:
error[E0423]: expected function, found macro `kernel::build_error`
--> samples/rust/rust_minimal.rs:29:9
|
29 | kernel::build_error();
| ^^^^^^^^^^^^^^^^^^^ not a function
|
help: use `!` to invoke the macro
|
29 | kernel::build_error!();
| +
An alternative would be using an alias, but it would be more complex
and moving it into the module seems right since it belongs there and
reduces the amount of code at the crate root.
Keep the `#[doc(hidden)]` inside `build_assert` in case the module is
not hidden in the future.
Reviewed-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/r/20241123222849.350287-2-ojeda@kernel.org
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
|
|
|
Miguel Ojeda
|
3ed03f4da0 |
rust: upgrade to Rust 1.68.2
This is the first upgrade to the Rust toolchain since the initial Rust
merge, from 1.62.0 to 1.68.2 (i.e. the latest).
# Context
The kernel currently supports only a single Rust version [1] (rather
than a minimum) given our usage of some "unstable" Rust features [2]
which do not promise backwards compatibility.
The goal is to reach a point where we can declare a minimum version for
the toolchain. For instance, by waiting for some of the features to be
stabilized. Therefore, the first minimum Rust version that the kernel
will support is "in the future".
# Upgrade policy
Given we will eventually need to reach that minimum version, it would be
ideal to upgrade the compiler from time to time to be as close as
possible to that goal and find any issues sooner. In the extreme, we
could upgrade as soon as a new Rust release is out. Of course, upgrading
so often is in stark contrast to what one normally would need for GCC
and LLVM, especially given the release schedule: 6 weeks for Rust vs.
half a year for LLVM and a year for GCC.
Having said that, there is no particular advantage to updating slowly
either: kernel developers in "stable" distributions are unlikely to be
able to use their distribution-provided Rust toolchain for the kernel
anyway [3]. Instead, by routinely upgrading to the latest instead,
kernel developers using Linux distributions that track the latest Rust
release may be able to use those rather than Rust-provided ones,
especially if their package manager allows to pin / hold back /
downgrade the version for some days during windows where the version may
not match. For instance, Arch, Fedora, Gentoo and openSUSE all provide
and track the latest version of Rust as they get released every 6 weeks.
Then, when the minimum version is reached, we will stop upgrading and
decide how wide the window of support will be. For instance, a year of
Rust versions. We will probably want to start small, and then widen it
over time, just like the kernel did originally for LLVM, see commit
|
|
|
Gary Guo
|
0f595bab9d |
rust: build_assert: add `build_{error,assert}!` macros
Add the `build_error!` and `build_assert!` macros which leverage
the previously introduced `build_error` crate. Do so in a new
module, called `build_assert`.
The former fails the build if the code path calling it can possibly
be executed. The latter asserts that a boolean expression is `true`
at compile time.
In particular, `build_assert!` can be used in some contexts where
`static_assert!` cannot:
fn f1<const N: usize>() {
static_assert!(N > 1);` // Error.
build_assert!(N > 1); // Build-time check.
assert!(N > 1); // Run-time check.
}
#[inline]
fn f2(n: usize) {
static_assert!(n > 1); // Error.
build_assert!(n > 1); // Build-time check.
assert!(n > 1); // Run-time check.
}
Signed-off-by: Gary Guo <gary@garyguo.net>
Reviewed-by: Wei Liu <wei.liu@kernel.org>
[Reworded, adapted for upstream and applied latest changes]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
|