pm24.git, branch rust-6.8

docs: rust: Clarify that 'rustup override' applies to build directory

2023-12-21T21:47:40Z

'rustup override' is required to be set for the build directory and not necessarily the kernel source tree (unless the build directory is its subdir). Clarify the same in the Quick Start guide. Signed-off-by: Viresh Kumar Reviewed-by: Benno Lossin Reviewed-by: Alice Ryhl Originally-pointed-out-by: Masahiro Yamada Link: https://github.com/Rust-for-Linux/linux/commit/f2238e7 Link: https://lore.kernel.org/r/e2b943eca92abebbf035447b3569f09a7176c770.1702366951.git.viresh.kumar@linaro.org [ Reworded and fixed quotes for `--path` and `set`. ] Signed-off-by: Miguel Ojeda

docs: rust: Add rusttest info

2023-12-21T21:47:40Z

Searching the Rust kernel documentation all existing Rust Make targets (rustavailable, rustfmt, rustfmtcheck, rustdoc and rust-analyzer) are explicitly documented with their Make commands. While the Make target rusttest is mentioned two times in the existing documentation, it's Make command is not explicitly documented, yet. Add a test section to document this. While at it, add some info about the more important KUnit testing too. Reviewed-by: David Gow Signed-off-by: Dirk Behme Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20231212081313.226120-1-dirk.behme@de.bosch.com [ Added "the", newline and quotes for `.config`. Expanded "repos". ] Signed-off-by: Miguel Ojeda

docs: rust: remove `CC=clang` mentions

2023-12-21T21:47:09Z

Nowadays all architectures except s390 recommend using `LLVM=1` instead of `CC=clang`, and since commit a3c6bfba4429 ("Documentation/llvm: refresh docs") the Kbuild LLVM documentation makes `LLVM=1` the way to go: We want to encourage the use of ``LLVM=1`` rather than just ``CC=clang``. Make that suggestion "above the fold" and "front and center" in our docs. In particular, that commit removes the examples with `CC=clang`. Thus do the same in the Rust Quick Start guide, i.e. remove the `CC=clang` mentions, especially since the architectures that have had their Rust support upstreamed (or soon to be upstreamed) are all `LLVM=1` ones. And perhaps by the time Rust is supported for s390 (or new architectures), it may have moved to `LLVM=1` anyway. Otherwise, this can be added back if needed (or perhaps an extra link to Documentation/kbuild/llvm.rst). This should also help avoiding potential confusion around `CC=clang` [1]. Link: https://lore.kernel.org/rust-for-linux/6df6e8e5-8d5b-4d3d-91b5-bc0e90c424ea@nvidia.com/ [1] Reviewed-by: Ariel Miculas Reviewed-by: Nathan Chancellor Reviewed-by: Alice Ryhl Reviewed-by: Benno Lossin Reviewed-by: Justin Stitt Reviewed-by: John Hubbard Reviewed-by: Martin Rodriguez Reboredo Link: https://lore.kernel.org/r/20231215124751.175191-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda

rust: support `srctree`-relative links

2023-12-21T19:54:17Z

Some of our links use relative paths in order to point to files in the source tree, e.g.: //! C header: [`include/linux/printk.h`](../../../../include/linux/printk.h) /// [`struct mutex`]: ../../../../include/linux/mutex.h These are problematic because they are hard to maintain and do not support `O=` builds. Instead, provide support for `srctree`-relative links, e.g.: //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h) /// [`struct mutex`]: srctree/include/linux/mutex.h The links are fixed after `rustdoc` generation to be based on the absolute path to the source tree. Essentially, this is the automatic version of Tomonori's fix [1], suggested by Gary [2]. Suggested-by: Gary Guo Reported-by: FUJITA Tomonori Closes: https://lore.kernel.org/r/20231026.204058.2167744626131849993.fujita.tomonori@gmail.com [1] Fixes: 48fadf440075 ("docs: Move rustdoc output, cross-reference it") Link: https://lore.kernel.org/rust-for-linux/20231026154525.6d14b495@eugeo/ [2] Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Benno Lossin Link: https://lore.kernel.org/r/20231215235428.243211-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda

rust: sync: Makes `CondVar::wait()` an uninterruptible wait

2023-12-21T19:54:17Z

Currently, `CondVar::wait()` is an interruptible wait, and this is different than `wait_event()` in include/linux/wait.h (which is an uninterruptible wait). To avoid confusion between different APIs on the interruptible/uninterruptible, make `CondVar::wait()` an uninterruptible wait same as `wait_event()`, also rename the old `wait()` to `CondVar::wait_interruptible()`. Spotted-by: Tiago Lam Signed-off-by: Boqun Feng Reviewed-by: Benno Lossin Reviewed-by: Alice Ryhl Reviewed-by: Tiago Lam Link: https://lore.kernel.org/r/20231214200421.690629-1-boqun.feng@gmail.com Signed-off-by: Miguel Ojeda

rust: upgrade to Rust 1.74.1

2023-12-21T18:40:26Z

This is the next upgrade to the Rust toolchain, from 1.73.0 to 1.74.1 (i.e. the latest) [1]. See the upgrade policy [2] and the comments on the first upgrade in commit 3ed03f4da06e ("rust: upgrade to Rust 1.68.2"). # Unstable features No unstable features (that we use) were stabilized. Therefore, the only unstable features allowed to be used outside the `kernel` crate are still `new_uninit,offset_of`, though other code to be upstreamed may increase the list (e.g. `offset_of` was added recently). Please see [3] for details. # Other improvements Rust 1.74.0 allows to use `#[repr(Rust)]` explicitly [4], which can be useful to be explicit about particular cases that would normally use e.g. the C representation, such as silencing lints like the upcoming additions we requested [5] to the `no_mangle_with_rust_abi` Clippy lint (which in turn triggered the `#[repr(Rust)]` addition). Rust 1.74.0 includes a fix for one of the false negative cases we reported in Clippy's `disallowed_macros` lint [6] that we would like to use in the future. Rust 1.74.1 fixes an ICE that the Apple AGX GPU driver was hitting [7]. # Required changes For this upgrade, no changes were required (i.e. on our side). # `alloc` upgrade and reviewing The vast majority of changes are due to our `alloc` fork being upgraded at once. There are two kinds of changes to be aware of: the ones coming from upstream, which we should follow as closely as possible, and the updates needed in our added fallible APIs to keep them matching the newer infallible APIs coming from upstream. Instead of taking a look at the diff of this patch, an alternative approach is reviewing a diff of the changes between upstream `alloc` and the kernel's. This allows to easily inspect the kernel additions only, especially to check if the fallible methods we already have still match the infallible ones in the new version coming from upstream. Another approach is reviewing the changes introduced in the additions in the kernel fork between the two versions. This is useful to spot potentially unintended changes to our additions. To apply these approaches, one may follow steps similar to the following to generate a pair of patches that show the differences between upstream Rust and the kernel (for the subset of `alloc` we use) before and after applying this patch: # Get the difference with respect to the old version. git -C rust checkout $(linux/scripts/min-tool-version.sh rustc) git -C linux ls-tree -r --name-only HEAD -- rust/alloc | cut -d/ -f3- | grep -Fv README.md | xargs -IPATH cp rust/library/alloc/src/PATH linux/rust/alloc/PATH git -C linux diff --patch-with-stat --summary -R > old.patch git -C linux restore rust/alloc # Apply this patch. git -C linux am rust-upgrade.patch # Get the difference with respect to the new version. git -C rust checkout $(linux/scripts/min-tool-version.sh rustc) git -C linux ls-tree -r --name-only HEAD -- rust/alloc | cut -d/ -f3- | grep -Fv README.md | xargs -IPATH cp rust/library/alloc/src/PATH linux/rust/alloc/PATH git -C linux diff --patch-with-stat --summary -R > new.patch git -C linux restore rust/alloc Now one may check the `new.patch` to take a look at the additions (first approach) or at the difference between those two patches (second approach). For the latter, a side-by-side tool is recommended. Link: https://github.com/rust-lang/rust/blob/stable/RELEASES.md#version-1741-2023-12-07 [1] Link: https://rust-for-linux.com/rust-version-policy [2] Link: https://github.com/Rust-for-Linux/linux/issues/2 [3] Link: https://github.com/rust-lang/rust/pull/114201 [4] Link: https://github.com/rust-lang/rust-clippy/issues/11219 [5] Link: https://github.com/rust-lang/rust-clippy/issues/11431 [6] Link: https://github.com/rust-lang/rust/issues/117976#issuecomment-1822225691 [7] Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Alice Ryhl Reviewed-by: Benno Lossin Tested-by: David Gow Link: https://lore.kernel.org/r/20231214092958.377061-1-ojeda@kernel.org Signed-off-by: Miguel Ojeda

rust: Suppress searching builtin sysroot

2023-12-14T19:14:01Z

By default, if Rust is passed `--target=foo` rather than a target.json file, it will infer a default sysroot if that component is installed. As the proposed aarch64 support [1] uses `aarch64-unknown-none` rather than a target.json file, this is needed [2] to prevent rustc from being confused between the custom kernel sysroot and the pre-installed one. [ Miguel: Applied Boqun's extra case (for `rusttest`) and reworded to add links to the arm64 patch series discussion. In addition, fixed the `rustdoc` target too (which requires a conditional since `cmd_rustdoc` is also used for host crates like `macros`). ] Signed-off-by: Matthew Maurer Tested-by: Boqun Feng Reviewed-by: Alice Ryhl Link: https://lore.kernel.org/rust-for-linux/20231020155056.3495121-1-Jamie.Cunliffe@arm.com/ [1] Link: https://lore.kernel.org/rust-for-linux/CAGSQo01pOixiPXkW867h4vPUaAjtKtHGKhkV-rpifJvKxAf4Ww@mail.gmail.com/ [2] Link: https://lore.kernel.org/r/20231031201752.1189213-1-mmaurer@google.com Signed-off-by: Miguel Ojeda

rust: macros: improve `#[vtable]` documentation

2023-12-14T19:14:01Z

Traits marked with `#[vtable]` need to provide default implementations for optional functions. The C side represents these with `NULL` in the vtable, so the default functions are never actually called. We do not want to replicate the default behavior from C in Rust, because that is not maintainable. Therefore we should use `build_error` in those default implementations. The error message for that is provided at `kernel::error::VTABLE_DEFAULT_ERROR`. Signed-off-by: Benno Lossin Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Andreas Hindborg Reviewed-by: Alice Ryhl Reviewed-by: Finn Behrens Link: https://lore.kernel.org/r/20231026201855.1497680-1-benno.lossin@proton.me [ Wrapped paragraph to 80 as requested and capitalized sentence. ] Signed-off-by: Miguel Ojeda

rust: macros: update 'paste!' macro to accept string literals

2023-12-14T19:14:01Z

Enable combining identifiers with literals in the 'paste!' macro. This allows combining user-specified strings with affixes to create namespaced identifiers. This sample code: macro_rules! m { ($name:lit) => { paste!(struct [<_some_ $name _struct_>] {}) } } m!("foo_bar"); Would previously cause a compilation error. It will now generate: struct _some_foo_bar_struct_ {} Signed-off-by: Trevor Gross Reviewed-by: Martin Rodriguez Reboredo Reviewed-by: Vincenzo Palazzo Reviewed-by: Alice Ryhl Reviewed-by: Benno Lossin Reviewed-by: Gary Guo Link: https://lore.kernel.org/r/20231118013959.37384-1-tmgross@umich.edu [ Added `:` before example block. ] Signed-off-by: Miguel Ojeda

rust: bindings: rename const binding using sed

2023-12-14T19:14:01Z

Currently, for `const`s that bindgen doesn't recognise, we define a helper constant with const BINDINGS_ = ; in `bindings_helper.h` and then we put pub const : = BINDINGS_; in `bindings/lib.rs`. This is fine since we currently only have 3 constants that are defined this way, but is going to be more annoying when more constants are added since every new constant needs to be defined in two places. This patch changes the way we define constant helpers to const RUST_CONST_HELPER_ = ; and then use `sed` to postprocess Rust code generated by bindgen to remove the distinct prefix, so users of the `bindings` crate can refer to the name directly. Reviewed-by: Benno Lossin Reviewed-by: Andreas Hindborg Reviewed-by: Martin Rodriguez Reboredo Signed-off-by: Gary Guo Reviewed-by: Alice Ryhl Link: https://lore.kernel.org/r/20231104145700.2495176-1-gary@garyguo.net [ Reworded for typos. ] Signed-off-by: Miguel Ojeda