linux-stable.git/rust/macros/lib.rs, branch v6.15

rust: macros: add macro to easily run KUnit tests

2025-03-20T11:26:54+00:00

Add a new procedural macro (`#[kunit_tests(kunit_test_suit_name)]`) to
run KUnit tests using a user-space like syntax.

The macro, that should be used on modules, transforms every `#[test]`
in a `kunit_case!` and adds a `kunit_unsafe_test_suite!` registering
all of them.

The only difference with user-space tests is that instead of using
`#[cfg(test)]`, `#[kunit_tests(kunit_test_suit_name)]` is used.

Note that `#[cfg(CONFIG_KUNIT)]` is added so the test module is not
compiled when `CONFIG_KUNIT` is set to `n`.

Reviewed-by: David Gow 
Signed-off-by: José Expósito 
Co-developed-by: Boqun Feng 
Signed-off-by: Boqun Feng 
Co-developed-by: Miguel Ojeda 
Signed-off-by: Miguel Ojeda 
Reviewed-by: Tamir Duberstein 
Signed-off-by: David Gow 
Link: https://lore.kernel.org/r/20250307090103.918788-3-davidgow@google.com
[ Removed spurious (in rendered form) newline in docs. - 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: move pin-init API into its own directory

2025-03-16T20:59:18+00:00

In preparation of splitting off the pin-init crate from the kernel
crate, move all pin-init API code (including proc-macros) into
`rust/pin-init`.

Moved modules have their import path adjusted via the `#[path = "..."]`
attribute. This allows the files to still be imported in the kernel
crate even though the files are in different directories.

Code that is moved out of files (but the file itself stays where it is)
is imported via the `include!` macro. This also allows the code to be
moved while still being part of the kernel crate.

Note that this commit moves the generics parsing code out of the GPL-2.0
file `rust/macros/helpers.rs` into the Apache-2.0 OR MIT file
`rust/pin_init/internal/src/helpers.rs`. I am the sole author of that
code and it already is available with that license at [1].
The same is true for the entry-points of the proc-macros `pin_data`,
`pinned_drop` and `derive_zeroable` in `rust/macros/lib.rs` that are
moved to `rust/pin_data/internal/src/lib.rs`. Although there are some
smaller patches that fix the doctests.

Link: https://github.com/Rust-for-Linux/pinned-init [1]
Signed-off-by: Benno Lossin 
Reviewed-by: Andreas Hindborg 
Reviewed-by: Fiona Behrens 
Tested-by: Andreas Hindborg 
Link: https://lore.kernel.org/r/20250308110339.2997091-3-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda

rust: init: disable doctests

2025-03-16T20:59:18+00:00

The build system cannot handle doctests in the kernel crate in files
outside of `rust/kernel/`. Subsequent commits will move files out of
that directory, but will still compile them as part of the kernel crate.
Thus ignore all doctests in the to-be-moved files.

Leave tests disabled until they are separated into their own crate and
they stop causing breakage.

Signed-off-by: Benno Lossin 
Reviewed-by: Fiona Behrens 
Reviewed-by: Andreas Hindborg 
Tested-by: Andreas Hindborg 
Link: https://lore.kernel.org/r/20250308110339.2997091-2-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda

rust: module: introduce `authors` key

2025-03-10T14:12:17+00:00

In the `module!` macro, the `author` field is currently of type `String`.

Since modules can have multiple authors, this limitation prevents
specifying more than one.

Add an `authors` field as `Option>` to allow creating
modules with multiple authors, and change the documentation and all
current users to use it. Eventually, the single `author` field may
be removed.

[ The `modinfo` key needs to still be `author`; otherwise, tooling
  may not work properly, e.g.:

      $ modinfo --author samples/rust/rust_print.ko
      Rust for Linux Contributors

  I have also kept the original `author` field (undocumented), so
  that we can drop it more easily in a kernel cycle or two.

    - Miguel ]

Suggested-by: Miguel Ojeda 
Link: https://github.com/Rust-for-Linux/linux/issues/244
Reviewed-by: Charalampos Mitrodimas 
Reviewed-by: Alice Ryhl 
Reviewed-by: Andreas Hindborg 
Signed-off-by: Guilherme Giacomo Simoes 
Link: https://lore.kernel.org/r/20250309175712.845622-2-trintaeoitogc@gmail.com
[ Fixed `modinfo` key. Kept `author` field. Reworded message
  accordingly. Updated my email. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: add #[export] macro

2025-03-09T19:52:46+00:00

Rust has two different tools for generating function declarations to
call across the FFI boundary:

* bindgen. Generates Rust declarations from a C header.
* cbindgen. Generates C headers from Rust declarations.

However, we only use bindgen in the kernel. This means that when C code
calls a Rust function by name, its signature must be duplicated in both
Rust code and a C header, and the signature needs to be kept in sync
manually.

Introducing cbindgen as a mandatory dependency to build the kernel would
be a rather complex and large change, so we do not consider that at this
time. Instead, to eliminate this manual checking, introduce a new macro
that verifies at compile time that the two function declarations use the
same signature. The idea is to run the C declaration through bindgen,
and then have rustc verify that the function pointers have the same
type.

The signature must still be written twice, but at least you can no
longer get it wrong. If the signatures don't match, you will get errors
that look like this:

error[E0308]: `if` and `else` have incompatible types
  --> /rust/kernel/print.rs:22:22
   |
21 | #[export]
   | --------- expected because of this
22 | unsafe extern "C" fn rust_fmt_argument(
   |                      ^^^^^^^^^^^^^^^^^ expected `u8`, found `i8`
   |
   = note: expected fn item `unsafe extern "C" fn(*mut u8, *mut u8, *mut c_void) -> *mut u8 {bindings::rust_fmt_argument}`
              found fn item `unsafe extern "C" fn(*mut i8, *mut i8, *const c_void) -> *mut i8 {print::rust_fmt_argument}`

It is unfortunate that the error message starts out by saying "`if` and
`else` have incompatible types", but I believe the rest of the error
message is reasonably clear and not too confusing.

Reviewed-by: Tamir Duberstein 
Reviewed-by: Andreas Hindborg 
Acked-by: Greg Kroah-Hartman 
Signed-off-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20250303-export-macro-v3-3-41fbad85a27f@google.com
Signed-off-by: Miguel Ojeda

rust: add `build_error!` to the prelude

2025-01-09T23:19:09+00:00

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 
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

rust: use the `build_error!` macro, not the hidden function

2025-01-09T23:19:05+00:00

Code and some examples were using the function, rather than the macro. The
macro is what is documented.

Thus move users to the macro.

Reviewed-by: Alice Ryhl 
Link: https://lore.kernel.org/r/20241123222849.350287-1-ojeda@kernel.org
[ Applied the change to the new miscdevice cases. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: macros: enable the rest of the tests

2024-11-01T21:02:53+00:00

Now that the rusttest target for the macros crate is compiled with the
kernel crate as a dependency, the rest of the rustdoc tests can be
enabled.

Signed-off-by: Ethan D. Twardy 
Reviewed-by: Alice Ryhl 
Link: https://github.com/Rust-for-Linux/linux/issues/1076
Link: https://lore.kernel.org/r/20240704145607.17732-5-ethan.twardy@gmail.com
[ Rebased (use `K{Box,Vec}` instead, enable `lint_reasons` feature).
  Remove unneeded `rust` as language in examples, as well as
  `#[macro_use]` `extern`s. - Miguel ]
Signed-off-by: Miguel Ojeda

rust: macros: enable paste! use from macro_rules!

2024-11-01T21:02:53+00:00

According to the rustdoc for the proc_macro crate[1], tokens captured
from a "macro variable" (e.g. from within macro_rules!) may be delimited
by invisible tokens and be contained within a proc_macro::Group.

Previously, this scenario was not handled by macros::paste, which caused
a proc-macro panic when the corresponding tests are enabled. Enable the
tests, and handle this case by making macros::paste::concat recursive.

Link: https://doc.rust-lang.org/stable/proc_macro/enum.Delimiter.html [1]
Signed-off-by: Ethan D. Twardy 
Reviewed-by: Alice Ryhl 
Link: https://github.com/Rust-for-Linux/linux/issues/1076
Link: https://lore.kernel.org/r/20240704145607.17732-4-ethan.twardy@gmail.com
[ Rebased (one fix was already applied) and reworded. Remove unneeded
  `rust` as language in examples. - Miguel ]
Signed-off-by: Miguel Ojeda