linux-toradex.git/Documentation/rust, branch v7.0-rc7

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

docs: rust: quick-start: add Debian 13 (Trixie)

2025-11-04T19:21:15+00:00

Debian 13 (released 2025-08-09) packages Rust 1.85.0 [1], which is recent
enough to build Linux.

Thus document it.

In fact, we are planning to propose that the minimum supported Rust
version in Linux follows Debian Stable releases, with Debian 13 being
the first one we upgrade to, i.e. Rust 1.85.

Link: https://www.debian.org/News/2025/20250809 [1]
Link: https://patch.msgid.link/20251012224645.1148411-1-ojeda@kernel.org
Signed-off-by: Miguel Ojeda

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