Added:
- 'impl<T, E> [Pin]Init<T, E> for Result<T, E>', so results are now
(pin-)initializers.
- 'Zeroable::init_zeroed()' delegating to 'init_zeroed()'.
- New 'zeroed()', a safe version of 'mem::zeroed()' and also provide
it via 'Zeroable::zeroed()'.
- Implement 'Zeroable' for 'Option<&T>' and 'Option<&mut T>'.
- Implement 'Zeroable' for 'Option<[unsafe] [extern "abi"]
fn(...args...) -> ret>' for '"Rust"' and '"C"' ABIs and up to 20
arguments.
Changed:
- Blanket impls of 'Init' and 'PinInit' from 'impl<T, E> [Pin]Init<T, E>
for T' to 'impl<T> [Pin]Init<T> for T'.
- Renamed 'zeroed()' to 'init_zeroed()'.
Upstream dev news:
- More CI improvements to deny warnings, use '--all-targets'. Also check
the synchronization status of the two '-next' branches in upstream and
the kernel.
-----BEGIN PGP SIGNATURE-----
iIgEABYKADAWIQQjEG/HT3UeYLJybLTomd21rZaLygUCaGqd4RIcbG9zc2luQGtl
cm5lbC5vcmcACgkQ6Jndta2Wi8qKagD/aBH4iwbal0DHbYx36TMfkvunp6pkKAo1
uu7qbmNwMMwBAKuRb41xA2AvllcYy/aMsb5H00o3iVLOzpMUHNnOFdIJ
=0DbP
-----END PGP SIGNATURE-----
Merge tag 'pin-init-v6.17' of https://github.com/Rust-for-Linux/linux into rust-next
Pull pin-init updates from Benno Lossin:
"Added:
- 'impl<T, E> [Pin]Init<T, E> for Result<T, E>', so results are now
(pin-)initializers.
- 'Zeroable::init_zeroed()' delegating to 'init_zeroed()'.
- New 'zeroed()', a safe version of 'mem::zeroed()' and also provide
it via 'Zeroable::zeroed()'.
- Implement 'Zeroable' for 'Option<&T>' and 'Option<&mut T>'.
- Implement 'Zeroable' for 'Option<[unsafe] [extern "abi"]
fn(...args...) -> ret>' for '"Rust"' and '"C"' ABIs and up to 20
arguments.
Changed:
- Blanket impls of 'Init' and 'PinInit' from 'impl<T, E>
[Pin]Init<T, E> for T' to 'impl<T> [Pin]Init<T> for T'.
- Renamed 'zeroed()' to 'init_zeroed()'.
Upstream dev news:
- More CI improvements to deny warnings, use '--all-targets'. Also
check the synchronization status of the two '-next' branches in
upstream and the kernel."
Acked-by: Andreas Hindborg <a.hindborg@kernel.org>
* tag 'pin-init-v6.17' of https://github.com/Rust-for-Linux/linux:
rust: pin-init: examples, tests: use `ignore` instead of conditionally compiling tests
rust: init: remove doctest's `Error::from_errno` workaround
rust: init: re-enable doctests
rust: pin-init: implement `ZeroableOption` for function pointers with up to 20 arguments
rust: pin-init: change `impl Zeroable for Option<NonNull<T>>` to `ZeroableOption for NonNull<T>`
rust: pin-init: implement `ZeroableOption` for `&T` and `&mut T`
rust: pin-init: add `zeroed()` & `Zeroable::zeroed()` functions
rust: pin-init: add `Zeroable::init_zeroed`
rust: pin-init: rename `zeroed` to `init_zeroed`
rust: pin-init: feature-gate the `stack_init_reuse` test on the `std` feature
rust: pin-init: examples: pthread_mutex: disable the main test for miri
rust: pin-init: examples, tests: add conditional compilation in order to compile under any feature combination
rust: pin-init: change blanket impls for `[Pin]Init` and add one for `Result<T, E>`
rust: pin-init: improve safety documentation for `impl<T> [Pin]Init<T> for T`
Use a consistent `# Examples` heading in rustdoc across the codebase.
Some modules previously used `## Examples` (even when they should be
available as top-level headers), while others used `# Example`, which
deviates from the preferred `# Examples` style.
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
Acked-by: Benno Lossin <lossin@kernel.org>
Link: https://lore.kernel.org/r/ddd5ce0ac20c99a72a4f1e4322d3de3911056922.1749545815.git.viresh.kumar@linaro.org
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Change `#[cfg(cond)]` to `#[cfg_attr(not(cond), ignore)]` on tests.
Ignoring tests instead of disabling them still makes them appear in the
test list, but with `ignored`. It also still compiles the code in those
cases.
Some tests still need to be ignore, because they use types that are not
present when the condition is false. For example the condition is
`feature = std` and then it uses `std:🧵:Thread`.
Suggested-by: Alice Ryhl <aliceryhl@google.com>
Link: https://lore.kernel.org/all/aDC9y829vZZBzZ2p@google.com
Link: b004dd8e64
Reviewed-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Link: https://lore.kernel.org/all/20250605155258.573391-1-lossin@kernel.org
Signed-off-by: Benno Lossin <lossin@kernel.org>
`zeroed()` returns a zeroed out value of a sized type implementing
`Zeroable`.
The function is added as a free standing function, in addition to an
associated function on `Zeroable`, because then it can be marked `const`
(functions in traits can't be const at the moment).
Link: 809e4ec160
Link: https://lore.kernel.org/all/20250523145125.523275-4-lossin@kernel.org
Signed-off-by: Benno Lossin <lossin@kernel.org>
The trait function delegates to the already existing `init_zeroed`
function that returns a zeroing initializer for `Self`.
The syntax `..Zeroable::init_zeroed()` is already used by the
initialization macros to initialize all fields that are not mentioned in
the initializer with zero. Therefore it is expected that the function
also exists on the trait.
Link: a424a6c9af
Link: https://lore.kernel.org/all/20250523145125.523275-3-lossin@kernel.org
Signed-off-by: Benno Lossin <lossin@kernel.org>
The name `zeroed` is a much better fit for a function that returns the
type by-value.
Link: 7dbe38682c
[ also rename uses in `rust/kernel/init.rs` - Benno]
Link: https://lore.kernel.org/all/20250523145125.523275-2-lossin@kernel.org
[ Fix wrong replacement of `mem::zeroed` in the definition of `trait
Zeroable`. - Benno ]
[ Also change occurrences of `zeroed` in `configfs.rs` - Benno ]
Acked-by: Andreas Hindborg <a.hindborg@kernel.org>
Signed-off-by: Benno Lossin <lossin@kernel.org>
When trying to run `cargo check --all-targets --no-default-features`, an
error is reported by the test, as it cannot find the `std` crate. This
is to be expected, since the `--no-default-features` flag enables the
`no-std` behavior of the crate. Thus exclude the test in that scenario.
Link: 2813729cca
Link: https://lore.kernel.org/all/20250523125424.192843-4-lossin@kernel.org
[ Changed my author email address to @kernel.org. - Benno ]
Signed-off-by: Benno Lossin <lossin@kernel.org>
In the CI, all examples & tests should be run under all feature
combinations. Currently several examples & tests use `std` without
conditionally enabling it. Thus make them all compile under any feature
combination by conditionally disabling the code that uses e.g. `std`.
Link: fdfb70efdd
Link: https://lore.kernel.org/all/20250523125424.192843-2-lossin@kernel.org
Signed-off-by: Benno Lossin <lossin@kernel.org>
Remove the error from the blanket implementations `impl<T, E> Init<T, E>
for T` (and also for `PinInit`). Add implementations for `Result<T, E>`.
This allows one to easily construct (un)conditional failing
initializers. It also improves the compatibility with APIs that do not
use pin-init, because users can supply a `Result<T, E>` to a function
taking an `impl PinInit<T, E>`.
Suggested-by: Alice Ryhl <aliceryhl@google.com>
Link: 58612514b2
[ Also fix a compile error in block. - Benno ]
Reviewed-by: Boqun Feng <boqun.feng@gmail.com>
Link: https://lore.kernel.org/all/20250529081027.297648-2-lossin@kernel.org
[ Add title prefix `rust: pin-init`. - Benno ]
Signed-off-by: Benno Lossin <lossin@kernel.org>
The inner SAFETY comments were missing since commit 5cfe7bef6751 ("rust:
enable `clippy::undocumented_unsafe_blocks` lint").
Also rework the implementation of `__pinned_init` to better justify the
SAFETY comment.
Link: df925b2e27
Reviewed-by: Boqun Feng <boqun.feng@gmail.com>
Link: https://lore.kernel.org/all/20250529081027.297648-1-lossin@kernel.org
Signed-off-by: Benno Lossin <lossin@kernel.org>
Added:
- 'Wrapper<T>' trait for creating pin-initializers for wrapper structs
with a structurally pinned value such as 'UnsafeCell<T>' or
'MaybeUninit<T>'.
- 'MaybeZeroable' derive macro to try to derive 'Zeroable', but not
error if not all fields implement it. This is needed to derive
'Zeroable' for all bindgen-generated structs.
- 'unsafe fn cast_[pin_]init()' functions to unsafely change the
initialized type of an initializer. These are utilized by the
'Wrapper<T>' implementations.
Changed:
- Added support for visibility in 'Zeroable' derive macro.
- Added support for 'union's in 'Zeroable' derive macro.
Upstream dev news:
- The CI has been streamlined & some bugs with it have been fixed. I
also added new workflows to check if the user-space version and the
one in the kernel tree have diverged.
- I also started to use the issues [1] tab to keep track of any problems
or unexpected/unwanted things. This should help folks report and
diagnose issues w.r.t. 'pin-init' better.
[1]: https://github.com/rust-for-linux/pin-init/issues
-----BEGIN PGP SIGNATURE-----
iIgEABYKADAWIQQjEG/HT3UeYLJybLTomd21rZaLygUCaBkpnxIcbG9zc2luQGtl
cm5lbC5vcmcACgkQ6Jndta2Wi8rvGAEAlmQercahKos8nEIvsP53vckky2OI7NWi
/1IjnFqIx0ABAJ4Wm08BDTU3tVOI7hNWIlZbWm0U81+Alk5fgR+Ou30F
=ZfOJ
-----END PGP SIGNATURE-----
Merge tag 'pin-init-v6.16' of https://github.com/Rust-for-Linux/linux into rust-next
Pull pin-init updates from Benno Lossin:
"Added:
- 'Wrapper<T>' trait for creating pin-initializers for wrapper
structs with a structurally pinned value such as 'UnsafeCell<T>' or
'MaybeUninit<T>'.
- 'MaybeZeroable' derive macro to try to derive 'Zeroable', but not
error if not all fields implement it. This is needed to derive
'Zeroable' for all bindgen-generated structs.
- 'unsafe fn cast_[pin_]init()' functions to unsafely change the
initialized type of an initializer. These are utilized by the
'Wrapper<T>' implementations.
Changed:
- Added support for visibility in 'Zeroable' derive macro.
- Added support for 'union's in 'Zeroable' derive macro.
Upstream dev news:
- The CI has been streamlined & some bugs with it have been fixed. I
also added new workflows to check if the user-space version and the
one in the kernel tree have diverged.
- I also started to use the issues [1] tab to keep track of any
problems or unexpected/unwanted things. This should help folks
report and diagnose issues w.r.t. 'pin-init' better.
[1] https://github.com/rust-for-linux/pin-init/issues"
* tag 'pin-init-v6.16' of https://github.com/Rust-for-Linux/linux:
rust: pin-init: improve documentation for `Zeroable` derive macros
rust: pin-init: fix typos
rust: pin-init: add `MaybeZeroable` derive macro
rust: pin-init: allow `Zeroable` derive macro to also be applied to unions
rust: pin-init: allow `pub` fields in `derive(Zeroable)`
rust: pin-init: Update the structural pinning link in readme.
rust: pin-init: Update Changelog and Readme
rust: pin-init: Implement `Wrapper` for `UnsafePinned` behind feature flag.
rust: pin-init: Add the `Wrapper` trait.
rust: pin-init: add `cast_[pin_]init` functions to change the initialized type
rust: pin-init: examples: use `allow` instead of `expect`
rust: pin-init: examples: conditionally enable `feature(lint_reasons)`
rust: pin-init: internal: skip rustfmt formatting of kernel-only module
rust: pin-init: synchronize README.md
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>
Specify that both `MaybeZeroable` and `Zeroable` work on `union`s. Add a
doc example for a union. Also include an example with visibility on the
field.
Link: ab0985a0e0
Reviewed-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Correct two typos in the `Wrapper::pin_init` documentation.
Link: fd0bf5e244
Reviewed-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
This derive macro implements `Zeroable` for structs & unions precisely
if all fields also implement `Zeroable` and does nothing otherwise. The
plain `Zeroable` derive macro instead errors when it cannot derive
`Zeroable` safely. The `MaybeZeroable` derive macro is useful in cases
where manual checking is infeasible such as with the bindings crate.
Move the zeroable generics parsing into a standalone function in order
to avoid code duplication between the two derive macros.
Link: 1165cdad1a
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Enabling the same behavior for unions as for structs is correct, but
could be relaxed: the valid bit patterns for unions are the union of all
valid bit patterns of their fields. So for a union to implement
`Zeroable`, only a single field needs to implement `Zeroable`. This can
be a future improvement, as it is currently only needed for unions where
all fields implement `Zeroable`.
There is no danger for mis-parsing with the two optional tokens (ie
neither one or both tokens are parsed), as the compiler will already
have rejected that before giving it as the input to the derive macro.
Link: 5927b497ce
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Add support for parsing `pub`, `pub(crate)` and `pub(super)` to the
derive macro `Zeroable`.
Link: e8311e52ca
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
The previous link anchor was broken in rust 1.77, because the
documentation was refactored in upstream rust.
Change the link to refer to the new section in the rust documentation.
Signed-off-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Link: a146142fe1
[ Fixed commit authorship. - Benno ]
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Add Changelog entry for the `Wrapper` trait and document the
`unsafe-pinned` feature in the Readme.
Signed-off-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Link: 986555f564
[ Fixed commit authorship. - Benno ]
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Add the `unsafe-pinned` feature which gates the `Wrapper`
implementation of the `core::pin::UnsafePinned` struct.
For now this is just a cargo feature, but once `core::pin::UnsafePinned`
is stable a config flag can be added to allow the usage of this
implementation in the linux kernel.
Signed-off-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Link: 99cb193442
[ Fixed commit authorship. - Benno ]
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
This trait allows creating `PinInitializers` for wrapper or new-type
structs with the inner value structurally pinned, when given the
initializer for the inner value.
Implement this trait for `UnsafeCell` and `MaybeUninit`.
Signed-off-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Link: 3ab4db083b
[ Reworded commit message into imperative mode, fixed typo and fixed
commit authorship. - Benno ]
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
These functions cast the given pointer from one type to another. They
are particularly useful when initializing transparent wrapper types.
Link: 80c03ddee4
Reviewed-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Rust 1.78 doesn't emit a `dead_code` error on the annotated element,
resulting in the `unfulfilled_lint_expectations` error. Rust 1.85 does
emit the `dead_code` error, so we still need an `allow`.
Link: 0e28cbb895
Link: https://lore.kernel.org/all/20250414195928.129040-4-benno.lossin@proton.me
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
The `quote` module only is available in the kernel and thus running
`cargo fmt` or `rustfmt internal/src/lib.rs` in the user-space
repository [1] results in:
error: couldn't read `~/pin-init/internal/src/../../../macros/quote.rs`: No such file or directory (os error 2)
--> ~/pin-init/internal/src/lib.rs:25:1
|
25 | mod quote;
| ^^^^^^^^^^
Error writing files: failed to resolve mod `quote`: ~/pin-init/internal/src/../../../macros/quote.rs does not exist
Thus mark it with `rustfmt::skip` when compiling without kernel support.
Link: https://github.com/Rust-for-Linux/pin-init [1]
Link: a6caf1945e
Link: https://lore.kernel.org/all/20250414195928.129040-2-benno.lossin@proton.me
Reviewed-by: Christian Schrefl <chrisi.schrefl@gmail.com>
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
The upstream version of the `README.md` differs by this change, so
synchronize it.
The reason that this wasn't in the original sync patch is that this was
a late change that I didn't port back to the kernel repo, since it was
generated by `cargo rdme`.
Link: https://lore.kernel.org/all/20250416225002.25253-1-benno.lossin@proton.me
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
"Normal" comments in Rust (`//`) are also formatted in Markdown, like
the documentation (`///` and `//!`), see
Documentation/rust/coding-guidelines.rst
Thus use Markdown autolinks for a couple links that were missing it.
It also helps to get proper linking in some software like kitty [1].
Suggested-by: Benno Lossin <benno.lossin@proton.me>
Link: https://github.com/Rust-for-Linux/pin-init/pull/32#discussion_r2023103712 [1]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Link: dd230d61bf
Fixes: 84837cf6fa ("rust: pin-init: change examples to the user-space version")
Cc: stable@vger.kernel.org
[ Change case in title. Reworded commit message. - Benno ]
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Link: https://lore.kernel.org/r/20250407201755.649153-3-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Similar to what was done for `Zeroable<NonNull<T>>` in commit
df27cef153 ("rust: init: fix `Zeroable` implementation for
`Option<NonNull<T>>` and `Option<KBox<T>>`"), the latest Rust
documentation [1] says it guarantees that `transmute::<_,
Option<T>>([0u8; size_of::<T>()])` is sound and produces
`Option::<T>::None` only in some cases. In particular, it says:
`Box<U>` (specifically, only `Box<U, Global>`) when `U: Sized`
Thus restrict the `impl` to `Sized`, and use similar wording as in that
commit too.
Link: https://doc.rust-lang.org/stable/std/option/index.html#representation [1]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Link: a6007cf555
Fixes: 9b2299af3b ("rust: pin-init: add `std` and `alloc` support from the user-space version")
Cc: stable@vger.kernel.org
[ Adjust mentioned commit to the one from the kernel. - Benno ]
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Link: https://lore.kernel.org/r/20250407201755.649153-2-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Toolchain and infrastructure:
- Extract the 'pin-init' API from the 'kernel' crate and make it into
a standalone crate.
In order to do this, the contents are rearranged so that they can
easily be kept in sync with the version maintained out-of-tree that
other projects have started to use too (or plan to, like QEMU).
This will reduce the maintenance burden for Benno, who will now have
his own sub-tree, and will simplify future expected changes like the
move to use 'syn' to simplify the implementation.
- Add '#[test]'-like support based on KUnit.
We already had doctests support based on KUnit, which takes the
examples in our Rust documentation and runs them under KUnit.
Now, we are adding the beginning of the support for "normal" tests,
similar to those the '#[test]' tests in userspace Rust. For instance:
#[kunit_tests(my_suite)]
mod tests {
#[test]
fn my_test() {
assert_eq!(1 + 1, 2);
}
}
Unlike with doctests, the 'assert*!'s do not map to the KUnit
assertion APIs yet.
- Check Rust signatures at compile time for functions called from C by
name.
In particular, introduce a new '#[export]' macro that can be placed
in the Rust function definition. It will ensure that the function
declaration on the C side matches the signature on the Rust function:
#[export]
pub unsafe extern "C" fn my_function(a: u8, b: i32) -> usize {
// ...
}
The macro essentially forces the compiler to compare the types of
the actual Rust function and the 'bindgen'-processed C signature.
These cases are rare so far. In the future, we may consider
introducing another tool, 'cbindgen', to generate C headers
automatically. Even then, having these functions explicitly marked
may be a good idea anyway.
- Enable the 'raw_ref_op' Rust feature: it is already stable, and
allows us to use the new '&raw' syntax, avoiding a couple macros.
After everyone has migrated, we will disallow the macros.
- Pass the correct target to 'bindgen' on Usermode Linux.
- Fix 'rusttest' build in macOS.
'kernel' crate:
- New 'hrtimer' module: add support for setting up intrusive timers
without allocating when starting the timer. Add support for
'Pin<Box<_>>', 'Arc<_>', 'Pin<&_>' and 'Pin<&mut _>' as pointer types
for use with timer callbacks. Add support for setting clock source
and timer mode.
- New 'dma' module: add a simple DMA coherent allocator abstraction and
a test sample driver.
- 'list' module: make the linked list 'Cursor' point between elements,
rather than at an element, which is more convenient to us and allows
for cursors to empty lists; and document it with examples of how to
perform common operations with the provided methods.
- 'str' module: implement a few traits for 'BStr' as well as the
'strip_prefix()' method.
- 'sync' module: add 'Arc::as_ptr'.
- 'alloc' module: add 'Box::into_pin'.
- 'error' module: extend the 'Result' documentation, including a few
examples on different ways of handling errors, a warning about using
methods that may panic, and links to external documentation.
'macros' crate:
- 'module' macro: add the 'authors' key to support multiple authors.
The original key will be kept until everyone has migrated.
Documentation:
- Add error handling sections.
MAINTAINERS:
- Add Danilo Krummrich as reviewer of the Rust "subsystem".
- Add 'RUST [PIN-INIT]' entry with Benno Lossin as maintainer. It has
its own sub-tree.
- Add sub-tree for 'RUST [ALLOC]'.
- Add 'DMA MAPPING HELPERS DEVICE DRIVER API [RUST]' entry with Abdiel
Janulgue as primary maintainer. It will go through the sub-tree of
the 'RUST [ALLOC]' entry.
- Add 'HIGH-RESOLUTION TIMERS [RUST]' entry with Andreas Hindborg as
maintainer. It has its own sub-tree.
And a few other cleanups and improvements.
-----BEGIN PGP SIGNATURE-----
iQIzBAABCgAdFiEEPjU5OPd5QIZ9jqqOGXyLc2htIW0FAmfpQgAACgkQGXyLc2ht
IW35CQ//VOIFKtG6qgHVMIxrmpT7YFsrAU41h+cHT2lzy5KiTqSYlCgd18SJ+Iyy
vi1ylfdyqOpH5EoO+opPN2H4E+VUlRJg7BkZrT4p1lgGDEKg1mtR/825TxquLNFM
A653f3FvK/scMb6X43kWNKGK/jnxlfxBGmUwIY4/p7+adIuZzXnNbPkV9XYGLx3r
8KIBKJ9gM52eXoCoF8XJpg6Vg/0rYWIet32OzYF0PvzSAOqUlH4keu15jeUo+59V
tgCzAkc2yV3oSo721KYlpPeCPKI5iVCzIcwT0n8fqraXtgGnaFPe5XF16U9Qvrjv
vRp5/dePAHwsOcj5ErzOgLMqGa1sqY76lxDI05PNcBJ8fBAhNEV/rpCTXs/wRagQ
xUZOdsQyEn0V/BOtV+dnwu410dElEeJdOAeojSYFm1gUay43a0e6yIboxn3Ylnfx
8jONSokZ/UFHX3wOFNqHeXsY+REB8Qq8OZXjNBZVFpKHNsICWA0G3BcCRnB1815k
0v7seSdrST78EJ/A5nM0a9gghuLzYgAN04SDx0FzKjb2mHs3PiVfXDvrNMCJ0pBW
zbF9RlvszKZStY5tpxdZ5Zh+f7rfYcnJHYhNpoP7DJr136iWP+NnHbk1lK6+o4WY
lPVdMMgUSUlEXIHgK2ebcb/I1KBrDYiPktmvKAFLrH3qVzhkLAU=
=PCxf
-----END PGP SIGNATURE-----
Merge tag 'rust-6.15' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux
Pull Rust updates from Miguel Ojeda:
"Toolchain and infrastructure:
- Extract the 'pin-init' API from the 'kernel' crate and make it into
a standalone crate.
In order to do this, the contents are rearranged so that they can
easily be kept in sync with the version maintained out-of-tree that
other projects have started to use too (or plan to, like QEMU).
This will reduce the maintenance burden for Benno, who will now
have his own sub-tree, and will simplify future expected changes
like the move to use 'syn' to simplify the implementation.
- Add '#[test]'-like support based on KUnit.
We already had doctests support based on KUnit, which takes the
examples in our Rust documentation and runs them under KUnit.
Now, we are adding the beginning of the support for "normal" tests,
similar to those the '#[test]' tests in userspace Rust. For
instance:
#[kunit_tests(my_suite)]
mod tests {
#[test]
fn my_test() {
assert_eq!(1 + 1, 2);
}
}
Unlike with doctests, the 'assert*!'s do not map to the KUnit
assertion APIs yet.
- Check Rust signatures at compile time for functions called from C
by name.
In particular, introduce a new '#[export]' macro that can be placed
in the Rust function definition. It will ensure that the function
declaration on the C side matches the signature on the Rust
function:
#[export]
pub unsafe extern "C" fn my_function(a: u8, b: i32) -> usize {
// ...
}
The macro essentially forces the compiler to compare the types of
the actual Rust function and the 'bindgen'-processed C signature.
These cases are rare so far. In the future, we may consider
introducing another tool, 'cbindgen', to generate C headers
automatically. Even then, having these functions explicitly marked
may be a good idea anyway.
- Enable the 'raw_ref_op' Rust feature: it is already stable, and
allows us to use the new '&raw' syntax, avoiding a couple macros.
After everyone has migrated, we will disallow the macros.
- Pass the correct target to 'bindgen' on Usermode Linux.
- Fix 'rusttest' build in macOS.
'kernel' crate:
- New 'hrtimer' module: add support for setting up intrusive timers
without allocating when starting the timer. Add support for
'Pin<Box<_>>', 'Arc<_>', 'Pin<&_>' and 'Pin<&mut _>' as pointer
types for use with timer callbacks. Add support for setting clock
source and timer mode.
- New 'dma' module: add a simple DMA coherent allocator abstraction
and a test sample driver.
- 'list' module: make the linked list 'Cursor' point between
elements, rather than at an element, which is more convenient to us
and allows for cursors to empty lists; and document it with
examples of how to perform common operations with the provided
methods.
- 'str' module: implement a few traits for 'BStr' as well as the
'strip_prefix()' method.
- 'sync' module: add 'Arc::as_ptr'.
- 'alloc' module: add 'Box::into_pin'.
- 'error' module: extend the 'Result' documentation, including a few
examples on different ways of handling errors, a warning about
using methods that may panic, and links to external documentation.
'macros' crate:
- 'module' macro: add the 'authors' key to support multiple authors.
The original key will be kept until everyone has migrated.
Documentation:
- Add error handling sections.
MAINTAINERS:
- Add Danilo Krummrich as reviewer of the Rust "subsystem".
- Add 'RUST [PIN-INIT]' entry with Benno Lossin as maintainer. It has
its own sub-tree.
- Add sub-tree for 'RUST [ALLOC]'.
- Add 'DMA MAPPING HELPERS DEVICE DRIVER API [RUST]' entry with
Abdiel Janulgue as primary maintainer. It will go through the
sub-tree of the 'RUST [ALLOC]' entry.
- Add 'HIGH-RESOLUTION TIMERS [RUST]' entry with Andreas Hindborg as
maintainer. It has its own sub-tree.
And a few other cleanups and improvements"
* tag 'rust-6.15' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux: (71 commits)
rust: dma: add `Send` implementation for `CoherentAllocation`
rust: macros: fix `make rusttest` build on macOS
rust: block: refactor to use `&raw mut`
rust: enable `raw_ref_op` feature
rust: uaccess: name the correct function
rust: rbtree: fix comments referring to Box instead of KBox
rust: hrtimer: add maintainer entry
rust: hrtimer: add clocksource selection through `ClockId`
rust: hrtimer: add `HrTimerMode`
rust: hrtimer: implement `HrTimerPointer` for `Pin<Box<T>>`
rust: alloc: add `Box::into_pin`
rust: hrtimer: implement `UnsafeHrTimerPointer` for `Pin<&mut T>`
rust: hrtimer: implement `UnsafeHrTimerPointer` for `Pin<&T>`
rust: hrtimer: add `hrtimer::ScopedHrTimerPointer`
rust: hrtimer: add `UnsafeHrTimerPointer`
rust: hrtimer: allow timer restart from timer handler
rust: str: implement `strip_prefix` for `BStr`
rust: str: implement `AsRef<BStr>` for `[u8]` and `BStr`
rust: str: implement `Index` for `BStr`
rust: str: implement `PartialEq` for `BStr`
...
The pin-init crate is now compiled in a standalone fashion, so revert
the earlier commit that disabled the doctests in pin-init in order to
avoid build errors while transitioning the crate into a standalone
version.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-22-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Add readme and contribution guidelines of the user-space version of
pin-init.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-21-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Remove the last differences between the kernel version and the
user-space version.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Link: https://lore.kernel.org/r/20250308110339.2997091-20-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Synchronize the internal macros crate with the user-space version that
uses the quote crate [1] instead of a custom `quote!` macro. The imports
in the different version are achieved using `cfg` on the kernel config
value. This cfg is always set in the kernel and never set in the
user-space version.
Since the quote crate requires the proc_macro2 crate, imports also need
to be adjusted and `.into()` calls have to be inserted.
Link: https://crates.io/crates/quote [1]
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Reviewed-by: Fiona Behrens <me@Kloenk.dev>
Link: https://lore.kernel.org/r/20250308110339.2997091-19-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Synchronize documentation and examples with the user-space version.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-18-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
To synchronize the kernel's version of pin-init with the user-space
version, introduce support for `std` and `alloc`. While the kernel uses
neither, the user-space version has to support both. Thus include the
required `#[cfg]`s and additional code.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-17-benno.lossin@proton.me
[ Undo the temporary `--extern force:alloc` since now we have contents
for `alloc` here. - Miguel ]
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
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 <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-16-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Add infrastructure for moving the initialization API to its own crate.
Covers all make targets such as `rust-analyzer` and `rustdoc`. The tests
of pin-init are not added to `rusttest`, as they are already tested in
the user-space repository [1].
Link: https://github.com/Rust-for-Linux/pin-init [1]
Co-developed-by: Benno Lossin <benno.lossin@proton.me>
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-15-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Change the paste macro path from `::kernel::macros::paste!` to use
`$crate::init::macros::paste!` instead, which links to
`::macros::paste!`. This is because the pin-init crate will be a
dependency of the kernel, so it itself cannot have the kernel as a
dependency.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-14-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
In order to make pin-init a standalone crate, remove dependencies on
kernel-specific code such as `ScopeGuard` and `KBox`.
`ScopeGuard` is only used in the `[pin_]init_array_from_fn` functions
and can easily be replaced by a primitive construct.
`KBox` is only used for type variance of unsized types and can also
easily be replaced.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-13-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Before switching to compile the `pin-init` crate directly, change
any links that would be invalid to links that are valid both before and
after the switch.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-12-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
When making pin-init its own crate, `Zeroable` will no longer be defined
by the kernel crate and thus implementing it for `Option<Box<T, A>>` is
no longer possible due to the orphan rule.
For this reason introduce a new `ZeroableOption` trait that circumvents
this problem.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-11-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
In order to make pin-init a standalone crate, move kernel-specific code
directly into the kernel crate. Since `Opaque<T>` and `KBox<T>` are part
of the kernel, move their `Zeroable` implementation into the kernel
crate.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Link: https://lore.kernel.org/r/20250308110339.2997091-10-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
In order to make pin-init a standalone crate, move kernel-specific code
directly into the kernel crate. This includes the `InPlaceInit<T>`
trait, its implementations and the implementations of `InPlaceWrite` for
`Arc` and `UniqueArc`. All of these use the kernel's error type which
will become unavailable in pin-init.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-9-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Move the ability to just write `try_pin_init!(Foo { a <- a_init })`
(note the missing `? Error` at the end) into the kernel crate.
Remove this notation from the pin-init crate, since the default when no
error is specified is the kernel-internal `Error` type. Instead add two
macros in the kernel crate that serve this default and are used instead
of the ones from `pin-init`.
This is done, because the `Error` type that is used as the default is
from the kernel crate and it thus prevents making the pin-init crate
standalone.
In order to not cause a build error due to a name overlap, the macros in
the pin-init crate are renamed, but this change is reverted in a future
commit when it is a standalone crate.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-8-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
The `[pin_]init!` macros have the same behavior as the `try_[pin_]init!`
macros, except that they set the error type to `Infallible`.
Instead of calling the primitive `__init_internal!` with the correct
parameters, the same can thus be achieved by calling `try_[pin_]init!`.
Since this makes it more clear what their behavior is, simplify the
implementations of `[pin_]init!`.
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Reviewed-by: Andreas Hindborg <a.hindborg@kernel.org>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-7-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
Replace the examples in the documentation by the ones from the
user-space version and introduce the standalone examples from the
user-space version such as the `CMutex<T>` type.
The `CMutex<T>` example from the pinned-init repository [1] is used in
several documentation examples in the user-space version instead of the
kernel `Mutex<T>` type (as it's not available). In order to split off
the pin-init crate, all examples need to be free of kernel-specific
types.
Link: https://github.com/rust-for-Linux/pinned-init [1]
Signed-off-by: Benno Lossin <benno.lossin@proton.me>
Reviewed-by: Fiona Behrens <me@kloenk.dev>
Tested-by: Andreas Hindborg <a.hindborg@kernel.org>
Link: https://lore.kernel.org/r/20250308110339.2997091-6-benno.lossin@proton.me
Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
