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

====================== ===============  ========================================

GNU C                  5.1              gcc --version

Clang/LLVM (optional)  13.0.1           clang --version

Rust (optional)        1.76.0           rustc --version

Rust (optional)        1.78.0           rustc --version

bindgen (optional)     0.65.1           bindgen --version

GNU make               3.82             make --version

bash                   4.2              bash --version

(e.g. drivers) should not use the C bindings directly. Instead, subsystems

should provide as-safe-as-possible abstractions as needed.

.. code-block::

	                                                rust/bindings/

	                                               (rust/helpers.c)

	                                                   include/ -----+ <-+

	                                                                 |   |

	  drivers/              rust/kernel/              +----------+ <-+   |

	    fs/                                           | bindgen  |       |

	   .../            +-------------------+          +----------+ --+   |

	                   |    Abstractions   |                         |   |

	+---------+        | +------+ +------+ |          +----------+   |   |

	| my_foo  | -----> | | foo  | | bar  | | -------> | Bindings | <-+   |

	| driver  |  Safe  | | sub- | | sub- | |  Unsafe  |          |       |

	+---------+        | |system| |system| |          | bindings | <-----+

	     |             | +------+ +------+ |          |  crate   |       |

	     |             |   kernel crate    |          +----------+       |

	     |             +-------------------+                             |

	     |                                                               |

	     +------------------# FORBIDDEN #--------------------------------+

The main idea is to encapsulate all direct interaction with the kernel's C APIs

into carefully reviewed and documented abstractions. Then users of these

abstractions cannot introduce undefined behavior (UB) as long as:

#. The abstractions are correct ("sound").

#. Any ``unsafe`` blocks respect the safety contract necessary to call the

   operations inside the block. Similarly, any ``unsafe impl``\ s respect the

   safety contract necessary to implement the trait.

Bindings

~~~~~~~~

By including a C header from ``include/`` into

``rust/bindings/bindings_helper.h``, the ``bindgen`` tool will auto-generate the

bindings for the included subsystem. After building, see the ``*_generated.rs``

output files in the ``rust/bindings/`` directory.

For parts of the C header that ``bindgen`` does not auto generate, e.g. C

``inline`` functions or non-trivial macros, it is acceptable to add a small

wrapper function to ``rust/helpers.c`` to make it available for the Rust side as

well.

Abstractions

~~~~~~~~~~~~

Abstractions are the layer between the bindings and the in-kernel users. They

are located in ``rust/kernel/`` and their role is to encapsulate the unsafe

access to the bindings into an as-safe-as-possible API that they expose to their

users. Users of the abstractions include things like drivers or file systems

written in Rust.

Besides the safety aspect, the abstractions are supposed to be "ergonomic", in

the sense that they turn the C interfaces into "idiomatic" Rust code. Basic

examples are to turn the C resource acquisition and release into Rust

constructors and destructors or C integer error codes into Rust's ``Result``\ s.

Conditional compilation

-----------------------

This document contains useful information how to test the Rust code in the

kernel.

There are two sorts of tests:

There are three sorts of tests:

- The KUnit tests.

- The ``#[test]`` tests.

- The Kselftests.

The KUnit tests

---------------

This requires the kernel ``.config`` and downloads external repositories. It

runs the ``#[test]`` tests on the host (currently) and thus is fairly limited in

what these tests can test.

The Kselftests

--------------

Kselftests are also available in the ``tools/testing/selftests/rust`` folder.

The kernel config options required for the tests are listed in the

``tools/testing/selftests/rust/config`` file and can be included with the aid

of the ``merge_config.sh`` script::

	./scripts/kconfig/merge_config.sh .config tools/testing/selftests/rust/config

The kselftests are built within the kernel source tree and are intended to

be executed on a system that is running the same kernel.

Once a kernel matching the source tree has been installed and booted, the

tests can be compiled and executed using the following command::

	make TARGETS="rust" kselftest

Refer to Documentation/dev-tools/kselftest.rst for the general Kselftest

documentation.

    --cfg no_fp_fmt_parse

alloc-cfgs = \

    --cfg no_borrow \

    --cfg no_fmt \

    --cfg no_global_oom_handling \

    --cfg no_macros \

    --cfg no_rc \

    --cfg no_str \

    --cfg no_string \

    --cfg no_sync \

    --cfg no_thin

    --cfg no_sync

quiet_cmd_rustdoc = RUSTDOC $(if $(rustdoc_host),H, ) $<

      cmd_rustdoc = \

# due to things that are "configured out" vs. entirely non-existing ones.

rustdoc-alloc: private rustc_target_flags = $(alloc-cfgs) \

    -Arustdoc::broken_intra_doc_links

rustdoc-alloc: $(src)/alloc/lib.rs rustdoc-core rustdoc-compiler_builtins FORCE

rustdoc-alloc: $(RUST_LIB_SRC)/alloc/src/lib.rs rustdoc-core rustdoc-compiler_builtins FORCE

	+$(call if_changed,rustdoc)

rustdoc-kernel: private rustc_target_flags = --extern alloc \

#   - `cargo` only considers the use case of building the standard library

#     to use it in a given package. Thus we need to create a dummy package

#     and pick the generated libraries from there.

#   - Since we only keep a subset of upstream `alloc` in-tree, we need

#     to recreate it on the fly by putting our sources on top.

#   - The usual ways of modifying the dependency graph in `cargo` do not seem

#     to apply for the `-Zbuild-std` steps, thus we have to mislead it

#     by modifying the sources in the sysroot.

	rm -rf $(objtree)/$(obj)/test; \

	mkdir -p $(objtree)/$(obj)/test; \

	cp -a $(rustc_sysroot) $(objtree)/$(obj)/test/sysroot; \

	cp -r $(srctree)/$(src)/alloc/* \

		$(objtree)/$(obj)/test/sysroot/lib/rustlib/src/rust/library/alloc/src; \

	echo '\#!/bin/sh' > $(objtree)/$(obj)/test/rustc_sysroot; \

	echo "$(RUSTC) --sysroot=$(abspath $(objtree)/$(obj)/test/sysroot) \"\$$@\"" \

		>> $(objtree)/$(obj)/test/rustc_sysroot; \

$(obj)/alloc.o: private skip_clippy = 1

$(obj)/alloc.o: private skip_flags = -Dunreachable_pub

$(obj)/alloc.o: private rustc_target_flags = $(alloc-cfgs)

$(obj)/alloc.o: $(src)/alloc/lib.rs $(obj)/compiler_builtins.o FORCE

$(obj)/alloc.o: $(RUST_LIB_SRC)/alloc/src/lib.rs $(obj)/compiler_builtins.o FORCE

	+$(call if_changed_dep,rustc_library)

$(obj)/build_error.o: $(src)/build_error.rs $(obj)/compiler_builtins.o FORCE

# `alloc`

These source files come from the Rust standard library, hosted in

the <https://github.com/rust-lang/rust> repository, licensed under

"Apache-2.0 OR MIT" and adapted for kernel use. For copyright details,

see <https://github.com/rust-lang/rust/blob/master/COPYRIGHT>.

Please note that these files should be kept as close as possible to

upstream. In general, only additions should be performed (e.g. new

methods). Eventually, changes should make it into upstream so that,

at some point, this fork can be dropped from the kernel tree.

The Rust upstream version on top of which these files are based matches

the output of `scripts/min-tool-version.sh rustc`.

## Rationale

On one hand, kernel folks wanted to keep `alloc` in-tree to have more

freedom in both workflow and actual features if actually needed

(e.g. receiver types if we ended up using them), which is reasonable.

On the other hand, Rust folks wanted to keep `alloc` as close as

upstream as possible and avoid as much divergence as possible, which

is also reasonable.

We agreed on a middle-ground: we would keep a subset of `alloc`

in-tree that would be as small and as close as possible to upstream.

Then, upstream can start adding the functions that we add to `alloc`

etc., until we reach a point where the kernel already knows exactly

what it needs in `alloc` and all the new methods are merged into

upstream, so that we can drop `alloc` from the kernel tree and go back

to using the upstream one.

By doing this, the kernel can go a bit faster now, and Rust can

slowly incorporate and discuss the changes as needed.