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

rust: remove leftover mentions of the `alloc` crate

2025-03-22T19:54:23+00:00

commit 374908a15af4cd60862ebc51a6e012ace2212c76 upstream. In commit 392e34b6bc22 ("kbuild: rust: remove the `alloc` crate and `GlobalAlloc`") we stopped using the upstream `alloc` crate. Thus remove a few leftover mentions treewide. Cc: stable@vger.kernel.org # Also to 6.12.y after the `alloc` backport lands Fixes: 392e34b6bc22 ("kbuild: rust: remove the `alloc` crate and `GlobalAlloc`") Reviewed-by: Danilo Krummrich Reviewed-by: Andreas Hindborg Link: https://lore.kernel.org/r/20250303171030.1081134-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda Signed-off-by: Greg Kroah-Hartman

docs: rust: remove spurious item in `expect` list

2025-03-13T12:02:18+00:00

commit b160dc46dd9af4001c802cc9c7d68b6ba58d27c4 upstream. This list started as a "when to prefer `expect`" list, but at some point during writing I changed it to a "prefer `expect` unless..." one. However, the first bullet remained, which does not make sense anymore. Thus remove it. In addition, fix nearby typo. Fixes: 04866494e936 ("Documentation: rust: discuss `#[expect(...)]` in the guidelines") Reviewed-by: Alice Ryhl Reviewed-by: Andreas Hindborg Link: https://lore.kernel.org/r/20241117133127.473937-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda Signed-off-by: Greg Kroah-Hartman

Documentation: rust: discuss `#[expect(...)]` in the guidelines

2025-03-13T12:01:42+00:00

commit 04866494e936d041fd196d3a36aecd979e4ef078 upstream. Discuss `#[expect(...)]` in the Lints sections of the coding guidelines document, which is an upcoming feature in Rust 1.81.0, and explain that it is generally to be preferred over `allow` unless there is a reason not to use it (e.g. conditional compilation being involved). Tested-by: Gary Guo Reviewed-by: Gary Guo Link: https://lore.kernel.org/r/20240904204347.168520-19-ojeda@kernel.org Signed-off-by: Miguel Ojeda Signed-off-by: Greg Kroah-Hartman

Documentation: rust: add coding guidelines on lints

2025-03-13T12:01:42+00:00

commit 139d396572ec4ba6e8cc5c02f5c8d5d1139be4b7 upstream. In the C side, disabling diagnostics locally, i.e. within the source code, is rare (at least in the kernel). Sometimes warnings are manipulated via the flags at the translation unit level, but that is about it. In Rust, it is easier to change locally the "level" of lints (e.g. allowing them locally). In turn, this means it is easier to globally enable more lints that may trigger a few false positives here and there that need to be allowed locally, but that generally can spot issues or bugs. Thus document this. Reviewed-by: Trevor Gross Reviewed-by: Alice Ryhl Tested-by: Gary Guo Reviewed-by: Gary Guo Link: https://lore.kernel.org/r/20240904204347.168520-17-ojeda@kernel.org Signed-off-by: Miguel Ojeda Signed-off-by: Greg Kroah-Hartman

RISC-V: disallow gcc + rust builds

2024-10-25T13:18:37+00:00

During the discussion before supporting rust on riscv, it was decided not to support gcc yet, due to differences in extension handling compared to llvm (only the version of libclang matching the c compiler is supported). Recently Jason Montleon reported [1] that building with gcc caused build issues, due to unsupported arguments being passed to libclang. After some discussion between myself and Miguel, it is better to disable gcc + rust builds to match the original intent, and subsequently support it when an appropriate set of extensions can be deduced from the version of libclang. Closes: https://lore.kernel.org/all/20240917000848.720765-2-jmontleo@redhat.com/ [1] Link: https://lore.kernel.org/all/20240926-battering-revolt-6c6a7827413e@spud/ [2] Fixes: 70a57b247251a ("RISC-V: enable building 64-bit kernels with rust support") Cc: stable@vger.kernel.org Reported-by: Jason Montleon Signed-off-by: Conor Dooley Acked-by: Miguel Ojeda Reviewed-by: Nathan Chancellor Link: https://lore.kernel.org/r/20241001-playlist-deceiving-16ece2f440f5@spud Signed-off-by: Palmer Dabbelt

Merge tag 'rust-6.12' of https://github.com/Rust-for-Linux/linux

2024-09-25T17:25:40+00:00

Pull Rust updates from Miguel Ojeda: "Toolchain and infrastructure: - Support 'MITIGATION_{RETHUNK,RETPOLINE,SLS}' (which cleans up objtool warnings), teach objtool about 'noreturn' Rust symbols and mimic '___ADDRESSABLE()' for 'module_{init,exit}'. With that, we should be objtool-warning-free, so enable it to run for all Rust object files. - KASAN (no 'SW_TAGS'), KCFI and shadow call sanitizer support. - Support 'RUSTC_VERSION', including re-config and re-build on change. - Split helpers file into several files in a folder, to avoid conflicts in it. Eventually those files will be moved to the right places with the new build system. In addition, remove the need to manually export the symbols defined there, reusing existing machinery for that. - Relax restriction on configurations with Rust + GCC plugins to just the RANDSTRUCT plugin. 'kernel' crate: - New 'list' module: doubly-linked linked list for use with reference counted values, which is heavily used by the upcoming Rust Binder. This includes 'ListArc' (a wrapper around 'Arc' that is guaranteed unique for the given ID), 'AtomicTracker' (tracks whether a 'ListArc' exists using an atomic), 'ListLinks' (the prev/next pointers for an item in a linked list), 'List' (the linked list itself), 'Iter' (an iterator over a 'List'), 'Cursor' (a cursor into a 'List' that allows to remove elements), 'ListArcField' (a field exclusively owned by a 'ListArc'), as well as support for heterogeneous lists. - New 'rbtree' module: red-black tree abstractions used by the upcoming Rust Binder. This includes 'RBTree' (the red-black tree itself), 'RBTreeNode' (a node), 'RBTreeNodeReservation' (a memory reservation for a node), 'Iter' and 'IterMut' (immutable and mutable iterators), 'Cursor' (bidirectional cursor that allows to remove elements), as well as an entry API similar to the Rust standard library one. - 'init' module: add 'write_[pin_]init' methods and the 'InPlaceWrite' trait. Add the 'assert_pinned!' macro. - 'sync' module: implement the 'InPlaceInit' trait for 'Arc' by introducing an associated type in the trait. - 'alloc' module: add 'drop_contents' method to 'BoxExt'. - 'types' module: implement the 'ForeignOwnable' trait for 'Pin>' and improve the trait's documentation. In addition, add the 'into_raw' method to the 'ARef' type. - 'error' module: in preparation for the upcoming Rust support for 32-bit architectures, like arm, locally allow Clippy lint for those. Documentation: - https://rust.docs.kernel.org has been announced, so link to it. - Enable rustdoc's "jump to definition" feature, making its output a bit closer to the experience in a cross-referencer. - Debian Testing now also provides recent Rust releases (outside of the freeze period), so add it to the list. MAINTAINERS: - Trevor is joining as reviewer of the "RUST" entry. And a few other small bits" * tag 'rust-6.12' of https://github.com/Rust-for-Linux/linux: (54 commits) kasan: rust: Add KASAN smoke test via UAF kbuild: rust: Enable KASAN support rust: kasan: Rust does not support KHWASAN kbuild: rust: Define probing macros for rustc kasan: simplify and clarify Makefile rust: cfi: add support for CFI_CLANG with Rust cfi: add CONFIG_CFI_ICALL_NORMALIZE_INTEGERS rust: support for shadow call stack sanitizer docs: rust: include other expressions in conditional compilation section kbuild: rust: replace proc macros dependency on `core.o` with the version text kbuild: rust: rebuild if the version text changes kbuild: rust: re-run Kconfig if the version text changes kbuild: rust: add `CONFIG_RUSTC_VERSION` rust: avoid `box_uninit_write` feature MAINTAINERS: add Trevor Gross as Rust reviewer rust: rbtree: add `RBTree::entry` rust: rbtree: add cursor rust: rbtree: add mutable iterator rust: rbtree: add iterator rust: rbtree: add red-black tree implementation backed by the C version ...

docs: rust: include other expressions in conditional compilation section

2024-09-05T20:45:01+00:00

Expand the conditional compilation section to explain how to support other expressions, such as testing whether `RUSTC_VERSION` is at least a given version, which requires a numerical comparison that Rust's `cfg` predicates do not support (yet?). Reviewed-by: Nicolas Schier Tested-by: Alice Ryhl Acked-by: Masahiro Yamada Link: https://lore.kernel.org/r/20240902165535.1101978-7-ojeda@kernel.org Signed-off-by: Miguel Ojeda

docs: rust: remove unintended blockquote in Quick Start

2024-08-27T20:44:29+00:00

Remove indentation within the "Hacking" section of the Rust Quick Start guide, i.e. remove a `

` HTML element from the rendered documentation. Reported-by: Miguel Ojeda Closes: https://github.com/Rust-for-Linux/linux/issues/1103 Fixes: d07479b211b7 ("docs: add Rust documentation") Signed-off-by: Jon Mulder Link: https://lore.kernel.org/r/20240826-pr-docs-rust-remove-quickstart-blockquote-v1-1-c51317d8d71a@gmail.com [ Added Fixes tag, reworded slightly and matched title to a previous, similar commit. - Miguel ] Signed-off-by: Miguel Ojeda

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