kernel/linux.git/Documentation/rust/index.rst, branch linux-7.0.y

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

2026-02-10T19:53:01+00:00

Pull rust updates from Miguel Ojeda: "Toolchain and infrastructure: - Add '__rust_helper' annotation to the C helpers This is needed to inline these helpers into Rust code - Remove imports available via the prelude, treewide This was possible thanks to a new lint in Klint that Gary has implemented -- more Klint-related changes, including initial upstream support, are coming - Deduplicate pin-init flags 'kernel' crate: - Add support for calling a function exactly once with the new 'do_once_lite!' macro (and 'OnceLite' type) Based on this, add 'pr_*_once!' macros to print only once - Add 'impl_flags!' macro for defining common bitflags operations: impl_flags!( /// Represents multiple permissions. #[derive(Debug, Clone, Default, Copy, PartialEq, Eq)] pub struct Permissions(u32); /// Represents a single permission. #[derive(Debug, Clone, Copy, PartialEq, Eq)] pub enum Permission { /// Read permission. Read = 1 << 0, /// Write permission. Write = 1 << 1, /// Execute permission. Execute = 1 << 2, } ); let mut f: Permissions = Permission::Read | Permission::Write; assert!(f.contains(Permission::Read)); assert!(!f.contains(Permission::Execute)); f |= Permission::Execute; assert!(f.contains(Permission::Execute)); let f2: Permissions = Permission::Write | Permission::Execute; assert!((f ^ f2).contains(Permission::Read)); assert!(!(f ^ f2).contains(Permission::Write)); - 'bug' module: support 'CONFIG_DEBUG_BUGVERBOSE_DETAILED' in the 'warn_on!' macro in order to show the evaluated condition alongside the file path: ------------[ cut here ]------------ WARNING: [val == 1] linux/samples/rust/rust_minimal.rs:27 at ... Modules linked in: rust_minimal(+) - Add safety module with 'unsafe_precondition_assert!' macro, currently a wrapper for 'debug_assert!', intended to mark the validation of safety preconditions where possible: /// # Safety /// /// The caller must ensure that `index` is less than `N`. unsafe fn set_unchecked(&mut self, index: usize, value: T) { unsafe_precondition_assert!( index < N, "set_unchecked() requires index ({index}) < N ({N})" ); ... } - Add instructions to 'build_assert!' documentation requesting to always inline functions when used with function arguments - 'ptr' module: replace 'build_assert!' with a 'const' one - 'rbtree' module: reduce unsafe blocks on pointer derefs - 'transmute' module: implement 'FromBytes' and 'AsBytes' for inhabited ZSTs, and use it in Nova - More treewide replacements of 'c_str!' with C string literals 'macros' crate: - Rewrite most procedural macros ('module!', 'concat_idents!', '#[export]', '#[vtable]', '#[kunit_tests]') to use the 'syn' parsing library which we introduced last cycle, with better diagnostics This also allows to support '#[cfg]' properly in the '#[vtable]' macro, to support arbitrary types in 'module!' macro (not just an identifier) and to remove several custom parsing helpers we had - Use 'quote!' from the recently vendored 'quote' library and remove our custom one The vendored one also allows us to avoid quoting '"' and '{}' inside the template anymore and editors can now highlight it. In addition, it improves robustness as it eliminates the need for string quoting and escaping - Use 'pin_init::zeroed()' to simplify KUnit code 'pin-init' crate: - Rewrite all procedural macros ('[pin_]init!', '#[pin_data]', '#[pinned_drop]', 'derive([Maybe]Zeroable)') to use the 'syn' parsing library which we introduced last cycle, with better diagnostics - Implement 'InPlaceWrite' for '&'static mut MaybeUninit'. This enables users to use external allocation mechanisms such as 'static_cell' - Support tuple structs in 'derive([Maybe]Zeroable)' - Support attributes on fields in '[pin_]init!' (such as '#[cfg(...)]') - Add a '#[default_error()]' attribute to '[pin_]init!' to override the default error (when no '? Error' is specified) - Support packed structs in '[pin_]init!' with '#[disable_initialized_field_access]' - Remove 'try_[pin_]init!' in favor of merging their feature with '[pin_]init!'. Update the kernel's own 'try_[pin_]init!' macros to use the 'default_error' attribute - Correct 'T: Sized' bounds to 'T: ?Sized' in the generated 'PinnedDrop' check by '#[pin_data]' Documentation: - Conclude the Rust experiment MAINTAINERS: - Add "RUST [RUST-ANALYZER]" entry for the rust-analyzer support. Tamir and Jesung will take care of it. They have both been active around it for a while. The new tree will flow through the Rust one - Add Gary as maintainer for "RUST [PIN-INIT]" - Update Boqun and Tamir emails to their kernel.org accounts And a few other cleanups and improvements" * tag 'rust-6.20-7.0' of git://git.kernel.org/pub/scm/linux/kernel/git/ojeda/linux: (59 commits) rust: safety: introduce `unsafe_precondition_assert!` macro rust: add `impl_flags!` macro for defining common bitflag operations rust: print: Add pr_*_once macros rust: bug: Support DEBUG_BUGVERBOSE_DETAILED option rust: print: Add support for calling a function exactly once rust: kbuild: deduplicate pin-init flags gpu: nova-core: remove imports available via prelude rust: clk: replace `kernel::c_str!` with C-Strings MAINTAINERS: Update my email address to @kernel.org rust: macros: support `#[cfg]` properly in `#[vtable]` macro. rust: kunit: use `pin_init::zeroed` instead of custom null value rust: macros: rearrange `#[doc(hidden)]` in `module!` macro rust: macros: allow arbitrary types to be used in `module!` macro rust: macros: convert `#[kunit_tests]` macro to use `syn` rust: macros: convert `concat_idents!` to use `syn` rust: macros: convert `#[export]` to use `syn` rust: macros: use `quote!` for `module!` macro rust: macros: use `syn` to parse `module!` macro rust: macros: convert `#[vtable]` macro to use `syn` rust: macros: use `quote!` from vendored crate ...

Documentation: use a source-read extension for the index link boilerplate

2026-01-23T18:59:34+00:00

The root document usually has a special :ref:`genindex` link to the generated index. This is also the case for Documentation/index.rst. The other index.rst files deeper in the directory hierarchy usually don't. For SPHINXDIRS builds, the root document isn't Documentation/index.rst, but some other index.rst in the hierarchy. Currently they have a ".. only::" block to add the index link when doing SPHINXDIRS html builds. This is obviously very tedious and repetitive. The link is also added to all index.rst files in the hierarchy for SPHINXDIRS builds, not just the root document. Put the boilerplate in a sphinx-includes/subproject-index.rst file, and include it at the end of the root document for subproject builds in an ad-hoc source-read extension defined in conf.py. For now, keep having the boilerplate in translations, because this approach currently doesn't cover translated index link headers. Cc: Jonathan Corbet Cc: Mauro Carvalho Chehab Cc: Randy Dunlap Signed-off-by: Jani Nikula Tested-by: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab [jc: did s/doctree/kern_doc_dir/ ] Signed-off-by: Jonathan Corbet Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>

rust: conclude the Rust experiment

2026-01-19T00:13:22+00:00

The Rust support was merged in v6.1 into mainline in order to help determine whether Rust as a language was suitable for the kernel, i.e. worth the tradeoffs, technically, procedurally and socially. At the 2025 Linux Kernel Maintainers Summit, the experiment has just been deemed concluded [1]. Thus remove the section -- it was not fully true already anyway, since there are already uses of Rust in production out there, some well-known Linux distributions enable it and it is already in millions of devices via Android. Obviously, this does not mean that everything works for every kernel configuration, architecture, toolchain etc., or that there won't be new issues. There is still a ton of work to do in all areas, from the kernel to upstream Rust, GCC and other projects. And, in fact, certain combinations (such as the mixed GCC+LLVM builds and the upcoming GCC support) are still quite experimental but getting there. But the experiment is done, i.e. Rust is here to stay. I hope this signals commitment from the kernel to companies and other entities to invest more into it, e.g. into giving time to their kernel developers to train themselves in Rust. Thanks to the many kernel maintainers that gave the project their support and patience throughout these years, and to the many other developers, whether in the kernel or in other projects, that have made this possible. I had a long list of 173 names in the credits of the original pull that merged the support into the kernel [2], and now such a list would be way longer, so I will not even try to compose one, but again, thanks a lot, everybody. Link: https://lwn.net/Articles/1050174/ [1] Link: https://git.kernel.org/linus/8aebac82933f [2] Reviewed-by: Gary Guo Acked-by: Greg Kroah-Hartman Acked-by: Benno Lossin Acked-by: Andreas Hindborg Acked-by: Danilo Krummrich Reviewed-by: Boqun Feng Link: https://patch.msgid.link/20251213000042.23072-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda

kernel-docs: Add new section for Rust learning materials

2024-10-14T15:50:29+00:00

Include a new section in the Index of Further Kernel Documentation with resources to learn Rust. Reference it in the Rust index. The resources are a product of a survey among assistants to the conference Kangrejos'24. Signed-off-by: Carlos Bilbao Reviewed-by: Dirk Behme Acked-by: Miguel Ojeda Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240922160411.274949-1-carlos.bilbao.osdev@gmail.com

docs: rust: improve main page introducing a "Code documentation" section

2024-08-25T16:37:40+00:00

Clean the "Rust" main page by introducing a 'Code documentation" section to separate it from the rest of the text above. In addition, introduce the "Rust code documentation" term, which may be clearer than referring to a potentially unknown tool. Furthermore, for the HTML case, homogenize both `rustdoc` and non-`rustdoc` cases and use the term introduced above instead. Then, always generate the pregenerated version part, since now there is a section that is always generated and thus makes sense to do so. Finally, finish the new section with a link to more details about the Rust code documentation. The intention is that: - The non-HTML case mentions the code documentation too, making it more prominent for readers of non-HTML docs. - Both HTML cases read more naturally. - The pregenerated version is always mentioned, since it is likely useful for readers of non-HTML docs. Link: https://lore.kernel.org/r/20240818141200.386899-2-ojeda@kernel.org Signed-off-by: Miguel Ojeda

docs: rust: link to https://rust.docs.kernel.org

2024-08-25T16:37:40+00:00

The Rust code documentation (i.e. `rustdoc`-generated docs) is now available at: https://rust.docs.kernel.org Thus document it and remove the `TODO` line. The generation uses a particular kernel configuration, based on x86_64, which may get tweaked over time. Older tags, and how they are generated, may also change in the future. We may consider freezing them at some point, but for the moment, the content should not be considered immutable. Thanks Konstantin for the support setting it up! Cc: Konstantin Ryabitsev Acked-by: Konstantin Ryabitsev Link: https://lore.kernel.org/r/20240818141200.386899-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda

docs: rust: Move testing to a separate page

2024-02-18T20:22:27+00:00

To be able to add more testing documentation move the testing section to it's own page. No change on the documentation itself. Suggested-by: Trevor Gross Suggested-by: Miguel Ojeda Reviewed-by: Trevor Gross Reviewed-by: David Gow Reviewed-by: Alice Ryhl Signed-off-by: Dirk Behme Link: https://lore.kernel.org/r/20240130075117.4137360-1-dirk.behme@de.bosch.com Signed-off-by: Miguel Ojeda

docs: rust: add "The Rust experiment" section

2023-10-25T01:14:00+00:00

Clarify that the Rust experiment is still going on to avoid confusion for both kernel maintainers and end users. Reviewed-by: Carlos Bilbao Link: https://lore.kernel.org/r/20231018160922.1018962-1-ojeda@kernel.org [ Changed last paragraph as discussed in the mailing list. ] Signed-off-by: Miguel Ojeda

docs: Move rustdoc output, cross-reference it

2023-07-21T21:08:46+00:00

Generate rustdoc documentation with the rest of subsystem's documentation in Documentation/output. Add a cross reference to the generated rustdoc in Documentation/rust/index.rst if Sphinx target rustdoc is set. Reviewed-by: Akira Yokosawa Signed-off-by: Carlos Bilbao Reviewed-by: Martin Rodriguez Reboredo Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20230718151534.4067460-2-carlos.bilbao@amd.com

docs: add Rust documentation

2022-09-28T07:02:45+00:00

Most of the documentation for Rust is written within the source code itself, as it is idiomatic for Rust projects. This applies to both the shared infrastructure at `rust/` as well as any other Rust module (e.g. drivers) written across the kernel. However, these documents contain general information that does not fit particularly well in the source code, like the Quick Start guide. It also contains a few other small changes elsewhere in the documentation folder. Reviewed-by: Kees Cook Co-developed-by: Alex Gaynor Signed-off-by: Alex Gaynor Co-developed-by: Finn Behrens Signed-off-by: Finn Behrens Co-developed-by: Adam Bratschi-Kaye Signed-off-by: Adam Bratschi-Kaye Co-developed-by: Wedson Almeida Filho Signed-off-by: Wedson Almeida Filho Co-developed-by: Michael Ellerman Signed-off-by: Michael Ellerman Co-developed-by: Sven Van Asbroeck Signed-off-by: Sven Van Asbroeck Co-developed-by: Wu XiangCheng Signed-off-by: Wu XiangCheng Co-developed-by: Gary Guo Signed-off-by: Gary Guo Co-developed-by: Boris-Chengbiao Zhou Signed-off-by: Boris-Chengbiao Zhou Co-developed-by: Yuki Okushi Signed-off-by: Yuki Okushi Co-developed-by: Wei Liu Signed-off-by: Wei Liu Co-developed-by: Daniel Xu Signed-off-by: Daniel Xu Co-developed-by: Julian Merkle Signed-off-by: Julian Merkle Signed-off-by: Miguel Ojeda