kernel/linux.git/Documentation/rust, branch v6.18.21

docs: rust: add section on imports formatting

2025-10-16T22:56:20+00:00

`rustfmt`, by default, formats imports in a way that is prone to conflicts while merging and rebasing, since in some cases it condenses several items into the same line. For instance, Linus mentioned [1] that the following case: use crate::{ fmt, page::AsPageIter, }; is compressed by `rustfmt` into: use crate::{fmt, page::AsPageIter}; which is undesirable. Similarly, `rustfmt` may put several items in the same line even if the braces span already multiple lines, e.g.: use kernel::{ acpi, c_str, device::{property, Core}, of, platform, }; The options that control the formatting behavior around imports are generally unstable, and `rustfmt` releases do not allow to use nightly features, unlike the compiler and other Rust tooling [2]. For the moment, we can introduce a workaround to prevent `rustfmt` from compressing the example above -- the "trailing empty comment": use crate::{ fmt, page::AsPageIter, // }; which is reminiscent of the trailing comma behavior in other formatters. We already used empty comments for formatting purposes in the past, e.g. in commit b9b701fce49a ("rust: clarify the language unstable features in use"). In addition, `rustfmt` actually reformats with a vertical layout (i.e. it does not put two items in the same line) when seeing such a comment, i.e. it doesn't just preserve the formatting, which is good in the sense that we can use it to easily reformat some imports, since it matches the style we generally want to have. A Git merge driver would help (suggested by Gary and Wedson), though maintainers would need to set it up, the diffs would still be larger and the formatting rules for imports would remain hard to predict. Thus document the style that we will follow in the coding guidelines by introducing a new section and explain how the trailing empty comment works there too. We discussed the issue with upstream Rust in our usual Rust <-> Rust for Linux meeting [3], and there have also been a few other discussions in parallel in issues [4][5] and Zulip [6]. We will see what happens, but upstream Rust has already created a subteam of `rustfmt` to try to overcome the bandwidth issue [7], which is a good signal, and some organization work has already started (e.g. tracking issues). We will continue our discussions with them about it. Cc: Caleb Cartwright Cc: Yacin Tmimi Cc: Manish Goregaokar Cc: Deadbeef Cc: Cameron Steffen Cc: Jieyou Xu Link: https://lore.kernel.org/all/CAHk-=wgO7S_FZUSBbngG5vtejWOpzDfTTBkVvP3_yjJmFddbzA@mail.gmail.com/ [1] Link: https://github.com/rust-lang/rustfmt/issues/4884 [2] Link: https://hackmd.io/iSCyY3JTTz-g8YM-nnzTTA [3] Link: https://github.com/rust-lang/rustfmt/issues/4991 [4] Link: https://github.com/rust-lang/rustfmt/issues/3361 [5] Link: https://rust-lang.zulipchat.com/#narrow/channel/392734-council/topic/rustfmt.20maintenance/near/543815381 [6] Link: https://github.com/rust-lang/team/pull/2017 [7] Reviewed-by: Benno Lossin Signed-off-by: Miguel Ojeda

Documentation: rust: testing: add docs on the new KUnit `#[test]` tests

2025-05-27T18:09:59+00:00

There was no documentation yet on the KUnit-based `#[test]`s. Thus add it now. It includes an explanation about the `assert*!` macros being mapped to KUnit and the support for `-> Result` introduced in these series. Reviewed-by: David Gow Acked-by: Danilo Krummrich Link: https://lore.kernel.org/r/20250502215133.1923676-8-ojeda@kernel.org Signed-off-by: Miguel Ojeda

Documentation: rust: rename `#[test]`s to "`rusttest` host tests"

2025-05-27T18:09:59+00:00

Now that `rusttest`s are not really used much, clarify the section of the documentation that describes them. In addition, free the section name for the KUnit-based `#[test]`s that will be added afterwards. To do so, rename the section into `rusttest` host tests. Reviewed-by: David Gow Acked-by: Danilo Krummrich Link: https://lore.kernel.org/r/20250502215133.1923676-7-ojeda@kernel.org Signed-off-by: Miguel Ojeda

rust: add C FFI types to the prelude

2025-05-23T14:31:43+00:00

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 Reviewed-by: Alice Ryhl 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

docs: rust: quick-start: update Ubuntu instructions

2025-05-22T22:12:14+00:00

Split installation instructions for Ubuntu into 2 different sections: - For Ubuntu 25.04: this release provides easy-to-install Rust packages. - For Ubuntu 24.10 and below: these releases provide rust-1.80 and bindgen-0.65, which do not set their tools as defaults. The instructions for these versions have been updated to configure Rust tools properly. Signed-off-by: Igor Korotin Link: https://lore.kernel.org/r/20250402160047.1827500-1-igor.korotin@yahoo.com [ Dropped 24.10 -- it is soon out of support and their `bindgen` issue (reported as issue #2086639) was never patched anyway. Removed trailing spaces. Split into subheaders. Added `rustfmt` link. Removed spurious backquotes. Reworded contents slightly. - Miguel ] Signed-off-by: Miguel Ojeda

docs: rust: explain that `///` vs. `//` applies to private items too

2025-05-11T22:20:25+00:00

Sometimes kernel developers use `//` for documenting private items, since those do not get rendered at the moment. That is reasonable, but the intention behind `///` (and `//!`) vs. `//` is to convey the distinction between documentation and other kinds of comments, such as implementation details or TODOs. It also increases consistency with the public items and thus e.g. allows to change visibility of an item with less changes involved. It is not just useful for human readers, but also tooling. For instance, we may want to eventually generate documentation for private items (perhaps as a toggle in the HTML UI). On top of that, `rustdoc` lints as usual for those, too, so we may want to do it even if we do not use the result. Thus document this explicitly. Link: https://lore.kernel.org/rust-for-linux/CANiq72n_C7exSOMe5yf-7jKKnhSCv+a9QcD=OE2B_Q2UFBL3Xg@mail.gmail.com/ Link: https://github.com/Rust-for-Linux/linux/issues/1157 Reviewed-by: Alice Ryhl Reviewed-by: Christian Schrefl Reviewed-by: Viresh Kumar Link: https://lore.kernel.org/r/20250416112454.2503872-1-ojeda@kernel.org [ Fixed typo. - Miguel ] Signed-off-by: Miguel Ojeda

Merge tag 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/rmk/linux

2025-04-03T19:21:44+00:00

Pull ARM and clkdev updates from Russell King: - Simplify ARM_MMU_KEEP usage - Add Rust support for ARM architecture version 7 - Align IPIs reported in /proc/interrupts - require linker to support KEEP within OVERLAY - add KEEP() for ARM vectors - add __printf() attribute for clkdev functions * tag 'for-linus' of git://git.kernel.org/pub/scm/linux/kernel/git/rmk/linux: ARM: 9445/1: clkdev: Mark some functions with __printf() attribute ARM: 9444/1: add KEEP() keyword to ARM_VECTORS ARM: 9443/1: Require linker to support KEEP within OVERLAY for DCE ARM: 9442/1: smp: Fix IPI alignment in /proc/interrupts ARM: 9441/1: rust: Enable Rust support for ARMv7 ARM: 9439/1: arm32: simplify ARM_MMU_KEEP usage

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

2025-03-31T00:03:26+00:00

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

ARM: 9441/1: rust: Enable Rust support for ARMv7

2025-03-26T13:31:16+00:00

This commit allows building ARMv7 kernels with Rust support. The rust core library expects some __eabi_... functions that are not implemented in the kernel. Those functions are some float operations and __aeabi_uldivmod. For now those are implemented with define_panicking_intrinsics!. This is based on the code by Sven Van Asbroeck from the original rust branch and inspired by the AArch version by Jamie Cunliffe. I have tested the rust samples and a custom simple MMIO module on hardware (De1SoC FPGA + Arm A9 CPU). Tested-by: Rudraksha Gupta Reviewed-by: Alice Ryhl Acked-by: Miguel Ojeda Tested-by: Miguel Ojeda Acked-by: Ard Biesheuvel Signed-off-by: Christian Schrefl Signed-off-by: Russell King (Oracle)

docs: rust: Add error handling sections

2025-03-08T21:52:02+00:00

Add error handling sections to the documentation and use it to link to the existing code documentation. This will allow to extend that documentation, use intra-doc links and test the examples. Suggested-by: Miguel Ojeda Link: https://lore.kernel.org/rust-for-linux/CANiq72keOdXy0LFKk9SzYWwSjiD710v=hQO4xi+5E4xNALa6cA@mail.gmail.com/ Signed-off-by: Dirk Behme Link: https://lore.kernel.org/r/20250115062552.1970768-1-dirk.behme@de.bosch.com [ Slightly tweaked wording. - Miguel ] Signed-off-by: Miguel Ojeda