Documentation/rust/general-information.rst

1 .. SPDX-License-Identifier: GPL-2.0
11 ----------
13 The Rust support in the kernel can link only `core <https://doc.rust-lang.org/core/>`_,
14 but not `std <https://doc.rust-lang.org/std/>`_. Crates for use in the
21 ------------------
23 Rust kernel code is documented using ``rustdoc``, its built-in documentation
26 The generated HTML docs include integrated search, linked items (e.g. types,
29 	https://rust.docs.kernel.org
31 For linux-next, please see:
33 	https://rust.docs.kernel.org/next/
37 	https://rust.docs.kernel.org/6.10/
39 The docs can also be easily generated and read locally. This is quite fast
47 To read the docs locally in your web browser, run e.g.::
49 	xdg-open Documentation/output/rust/rustdoc/kernel/index.html
51 To learn about how to write the documentation, please see coding-guidelines.rst.
55 -----------
58 available via ``clippy``, a Rust linter. To enable it, pass ``CLIPPY=1`` to
68 -------------------------
82 should provide as-safe-as-possible abstractions as needed.
84 .. code-block::
89 	                                                   include/ -----+ <-+
91 	  drivers/              rust/kernel/              +----------+ <-+   |
93 	   .../            +-------------------+          +----------+ --+   |
95 	+---------+        | +------+ +------+ |          +----------+   |   |
96 	| my_foo  | -----> | | foo  | | bar  | | -------> | Bindings | <-+   |
97 	| driver  |  Safe  | | sub- | | sub- | |  Unsafe  |          |       |
98 	+---------+        | |system| |system| |          | bindings | <-----+
99 	     |             | +------+ +------+ |          |  crate   |       |
100 	     |             |   kernel crate    |          +----------+       |
101 	     |             +-------------------+                             |
103 	     +------------------# FORBIDDEN #--------------------------------+
118 ``rust/bindings/bindings_helper.h``, the ``bindgen`` tool will auto-generate the
123 ``inline`` functions or non-trivial macros, it is acceptable to add a small
130 Abstractions are the layer between the bindings and the in-kernel users. They
132 access to the bindings into an as-safe-as-possible API that they expose to their
143 -----------------------
148 .. code-block:: rust
151 	#[cfg(CONFIG_X="y")]   // Enabled as a built-in (`y`)
158 .. code-block:: kconfig