linux/rust/pin-init/src/lib.rs, branch v6.15

rust: pin-init: use Markdown autolinks in Rust comments

2025-04-08T19:12:58Z

"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 Link: https://github.com/Rust-for-Linux/pin-init/pull/32#discussion_r2023103712 [1] Signed-off-by: Miguel Ojeda Link: https://github.com/Rust-for-Linux/pin-init/pull/32/commits/dd230d61bf0538281072fbff4bb71efc58f3420c Fixes: 84837cf6fa54 ("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 Link: https://lore.kernel.org/r/20250407201755.649153-3-benno.lossin@proton.me Signed-off-by: Miguel Ojeda

Merge tag 'rust-6.15' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux

2025-03-31T00:03:26Z

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>', '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>` 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` for `[u8]` and `BStr` rust: str: implement `Index` for `BStr` rust: str: implement `PartialEq` for `BStr` ...

rust: pin-init: re-enable doctests

2025-03-16T20:59:19Z

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 Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-22-benno.lossin@proton.me Signed-off-by: Miguel Ojeda

rust: pin-init: miscellaneous synchronization with the user-space version

2025-03-16T20:59:19Z

Remove the last differences between the kernel version and the user-space version. Signed-off-by: Benno Lossin Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Reviewed-by: Fiona Behrens Link: https://lore.kernel.org/r/20250308110339.2997091-20-benno.lossin@proton.me Signed-off-by: Miguel Ojeda

rust: pin-init: synchronize documentation with the user-space version

2025-03-16T20:59:19Z

Synchronize documentation and examples with the user-space version. 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-18-benno.lossin@proton.me Signed-off-by: Miguel Ojeda

rust: pin-init: add `std` and `alloc` support from the user-space version

2025-03-16T20:59:19Z

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 Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg 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

rust: make pin-init its own crate

2025-03-16T20:59:19Z

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: pin-init: remove kernel-crate dependency

2025-03-16T20:59:19Z

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 Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-13-benno.lossin@proton.me Signed-off-by: Miguel Ojeda

rust: pin-init: fix documentation links

2025-03-16T20:59:19Z

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 Reviewed-by: Fiona Behrens Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-12-benno.lossin@proton.me Signed-off-by: Miguel Ojeda

rust: add `ZeroableOption` and implement it instead of `Zeroable` for `Option>`

2025-03-16T20:59:18Z

When making pin-init its own crate, `Zeroable` will no longer be defined by the kernel crate and thus implementing it for `Option>` 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 Reviewed-by: Fiona Behrens Reviewed-by: Andreas Hindborg Tested-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250308110339.2997091-11-benno.lossin@proton.me Signed-off-by: Miguel Ojeda