docs: add Rust documentation

   reasons. The kernel source contains tens of thousands of kernel-doc

   comments. Please stick to the style described here.

.. note:: kernel-doc does not cover Rust code: please see

   Documentation/rust/general-information.rst instead.

The kernel-doc structure is extracted from the comments, and proper

`Sphinx C Domain`_ function and type descriptions with anchors are

generated from them. The descriptions are filtered for special kernel-doc

   maintainer/index

   fault-injection/index

   livepatch/index

   rust/index

Kernel API documentation

-------

Additional options to the C compiler (for built-in and modules).

KRUSTFLAGS

----------

Additional options to the Rust compiler (for built-in and modules).

CFLAGS_KERNEL

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

Additional options for $(CC) when used to compile

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

Additional module specific options to use for $(CC).

RUSTFLAGS_KERNEL

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

Additional options for $(RUSTC) when used to compile

code that is compiled as built-in.

RUSTFLAGS_MODULE

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

Additional module specific options to use for $(RUSTC).

LDFLAGS_MODULE

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

Additional options used for $(LD) when linking modules.

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

Additional flags to be passed to $(HOSTCXX) when building host programs.

HOSTRUSTFLAGS

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

Additional flags to be passed to $(HOSTRUSTC) when building host programs.

HOSTLDFLAGS

-----------

Additional flags to be passed when linking host programs.

	   --- 4.1 Simple Host Program

	   --- 4.2 Composite Host Programs

	   --- 4.3 Using C++ for host programs

	   --- 4.4 Controlling compiler options for host programs

	   --- 4.5 When host programs are actually built

	   --- 4.4 Using Rust for host programs

	   --- 4.5 Controlling compiler options for host programs

	   --- 4.6 When host programs are actually built

	=== 5 Userspace Program support

	   --- 5.1 Simple Userspace Program

		qconf-cxxobjs := qconf.o

		qconf-objs    := check.o

4.4 Controlling compiler options for host programs

4.4 Using Rust for host programs

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

	Kbuild offers support for host programs written in Rust. However,

	since a Rust toolchain is not mandatory for kernel compilation,

	it may only be used in scenarios where Rust is required to be

	available (e.g. when  ``CONFIG_RUST`` is enabled).

	Example::

		hostprogs     := target

		target-rust   := y

	Kbuild will compile ``target`` using ``target.rs`` as the crate root,

	located in the same directory as the ``Makefile``. The crate may

	consist of several source files (see ``samples/rust/hostprogs``).

4.5 Controlling compiler options for host programs

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

	When compiling host programs, it is possible to set specific flags.

	When linking qconf, it will be passed the extra option

	"-L$(QTDIR)/lib".

4.5 When host programs are actually built

4.6 When host programs are actually built

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

	Kbuild will only build host-programs when they are referenced

	The first example utilises the trick that a config option expands

	to 'y' when selected.

    KBUILD_RUSTFLAGS

	$(RUSTC) compiler flags

	Default value - see top level Makefile

	Append or modify as required per architecture.

	Often, the KBUILD_RUSTFLAGS variable depends on the configuration.

	Note that target specification file generation (for ``--target``)

	is handled in ``scripts/generate_rust_target.rs``.

    KBUILD_AFLAGS_KERNEL

	Assembler options specific for built-in

	are used for $(CC).

	From commandline CFLAGS_MODULE shall be used (see kbuild.rst).

    KBUILD_RUSTFLAGS_KERNEL

	$(RUSTC) options specific for built-in

	$(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to

	compile resident kernel code.

    KBUILD_RUSTFLAGS_MODULE

	Options for $(RUSTC) when building modules

	$(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that

	are used for $(RUSTC).

	From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst).

    KBUILD_LDFLAGS_MODULE

	Options for $(LD) when linking modules

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

GNU C                  5.1              gcc --version

Clang/LLVM (optional)  11.0.0           clang --version

Rust (optional)        1.62.0           rustc --version

bindgen (optional)     0.56.0           bindgen --version

GNU make               3.81             make --version

bash                   4.2              bash --version

binutils               2.23             ld -v

from the kernel that were used to support older versions. Please see additional

docs on :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.

Rust (optional)

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

A particular version of the Rust toolchain is required. Newer versions may or

may not work because the kernel depends on some unstable Rust features, for

the moment.

Each Rust toolchain comes with several "components", some of which are required

(like ``rustc``) and some that are optional. The ``rust-src`` component (which

is optional) needs to be installed to build the kernel. Other components are

useful for developing.

Please see Documentation/rust/quick-start.rst for instructions on how to

satisfy the build requirements of Rust support. In particular, the ``Makefile``

target ``rustavailable`` is useful to check why the Rust toolchain may not

be detected.

bindgen (optional)

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

``bindgen`` is used to generate the Rust bindings to the C side of the kernel.

It depends on ``libclang``.

Make

----

Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>`

for details about Sphinx requirements.

rustdoc

-------

``rustdoc`` is used to generate the documentation for Rust code. Please see

Documentation/rust/general-information.rst for more information.

Getting updated software

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

- :ref:`Getting LLVM <getting_llvm>`.

Rust

----

- Documentation/rust/quick-start.rst.

bindgen

-------

- Documentation/rust/quick-start.rst.

Make

----