Documentation/rust/general-information.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 General Information
   4 ===================
   5
   6 This document contains useful information to know when working with
   7 the Rust support in the kernel.
   8
   9
  10 ``no_std``
  11 ----------
  12
  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
  15 kernel must opt into this behavior using the ``#![no_std]`` attribute.
  16
  17
  18 .. _rust_code_documentation:
  19
  20 Code documentation
  21 ------------------
  22
  23 Rust kernel code is documented using ``rustdoc``, its built-in documentation
  24 generator.
  25
  26 The generated HTML docs include integrated search, linked items (e.g. types,
  27 functions, constants), source code, etc. They may be read at:
  28
  29         https://rust.docs.kernel.org
  30
  31 For linux-next, please see:
  32
  33         https://rust.docs.kernel.org/next/
  34
  35 There are also tags for each main release, e.g.:
  36
  37         https://rust.docs.kernel.org/6.10/
  38
  39 The docs can also be easily generated and read locally. This is quite fast
  40 (same order as compiling the code itself) and no special tools or environment
  41 are needed. This has the added advantage that they will be tailored to
  42 the particular kernel configuration used. To generate them, use the ``rustdoc``
  43 target with the same invocation used for compilation, e.g.::
  44
  45         make LLVM=1 rustdoc
  46
  47 To read the docs locally in your web browser, run e.g.::
  48
  49         xdg-open Documentation/output/rust/rustdoc/kernel/index.html
  50
  51 To learn about how to write the documentation, please see coding-guidelines.rst.
  52
  53
  54 Extra lints
  55 -----------
  56
  57 While ``rustc`` is a very helpful compiler, some extra lints and analyses are
  58 available via ``clippy``, a Rust linter. To enable it, pass ``CLIPPY=1`` to
  59 the same invocation used for compilation, e.g.::
  60
  61         make LLVM=1 CLIPPY=1
  62
  63 Please note that Clippy may change code generation, thus it should not be
  64 enabled while building a production kernel.
  65
  66
  67 Abstractions vs. bindings
  68 -------------------------
  69
  70 Abstractions are Rust code wrapping kernel functionality from the C side.
  71
  72 In order to use functions and types from the C side, bindings are created.
  73 Bindings are the declarations for Rust of those functions and types from
  74 the C side.
  75
  76 For instance, one may write a ``Mutex`` abstraction in Rust which wraps
  77 a ``struct mutex`` from the C side and calls its functions through the bindings.
  78
  79 Abstractions are not available for all the kernel internal APIs and concepts,
  80 but it is intended that coverage is expanded as time goes on. "Leaf" modules
  81 (e.g. drivers) should not use the C bindings directly. Instead, subsystems
  82 should provide as-safe-as-possible abstractions as needed.
  83
  84 .. code-block::
  85
  86                                                         rust/bindings/
  87                                                        (rust/helpers/)
  88
  89                                                            include/ -----+ <-+
  90                                                                          |   |
  91           drivers/              rust/kernel/              +----------+ <-+   |
  92             fs/                                           | bindgen  |       |
  93            .../            +-------------------+          +----------+ --+   |
  94                            |    Abstractions   |                         |   |
  95         +---------+        | +------+ +------+ |          +----------+   |   |
  96         | my_foo  | -----> | | foo  | | bar  | | -------> | Bindings | <-+   |
  97         | driver  |  Safe  | | sub- | | sub- | |  Unsafe  |          |       |
  98         +---------+        | |system| |system| |          | bindings | <-----+
  99              |             | +------+ +------+ |          |  crate   |       |
 100              |             |   kernel crate    |          +----------+       |
 101              |             +-------------------+                             |
 102              |                                                               |
 103              +------------------# FORBIDDEN #--------------------------------+
 104
 105 The main idea is to encapsulate all direct interaction with the kernel's C APIs
 106 into carefully reviewed and documented abstractions. Then users of these
 107 abstractions cannot introduce undefined behavior (UB) as long as:
 108
 109 #. The abstractions are correct ("sound").
 110 #. Any ``unsafe`` blocks respect the safety contract necessary to call the
 111    operations inside the block. Similarly, any ``unsafe impl``\ s respect the
 112    safety contract necessary to implement the trait.
 113
 114 Bindings
 115 ~~~~~~~~
 116
 117 By including a C header from ``include/`` into
 118 ``rust/bindings/bindings_helper.h``, the ``bindgen`` tool will auto-generate the
 119 bindings for the included subsystem. After building, see the ``*_generated.rs``
 120 output files in the ``rust/bindings/`` directory.
 121
 122 For parts of the C header that ``bindgen`` does not auto generate, e.g. C
 123 ``inline`` functions or non-trivial macros, it is acceptable to add a small
 124 wrapper function to ``rust/helpers/`` to make it available for the Rust side as
 125 well.
 126
 127 Abstractions
 128 ~~~~~~~~~~~~
 129
 130 Abstractions are the layer between the bindings and the in-kernel users. They
 131 are located in ``rust/kernel/`` and their role is to encapsulate the unsafe
 132 access to the bindings into an as-safe-as-possible API that they expose to their
 133 users. Users of the abstractions include things like drivers or file systems
 134 written in Rust.
 135
 136 Besides the safety aspect, the abstractions are supposed to be "ergonomic", in
 137 the sense that they turn the C interfaces into "idiomatic" Rust code. Basic
 138 examples are to turn the C resource acquisition and release into Rust
 139 constructors and destructors or C integer error codes into Rust's ``Result``\ s.
 140
 141
 142 Conditional compilation
 143 -----------------------
 144
 145 Rust code has access to conditional compilation based on the kernel
 146 configuration:
 147
 148 .. code-block:: rust
 149
 150         #[cfg(CONFIG_X)]       // Enabled               (`y` or `m`)
 151         #[cfg(CONFIG_X="y")]   // Enabled as a built-in (`y`)
 152         #[cfg(CONFIG_X="m")]   // Enabled as a module   (`m`)
 153         #[cfg(not(CONFIG_X))]  // Disabled
 154
 155 For other predicates that Rust's ``cfg`` does not support, e.g. expressions with
 156 numerical comparisons, one may define a new Kconfig symbol:
 157
 158 .. code-block:: kconfig
 159
 160         config RUSTC_VERSION_MIN_107900
 161                 def_bool y if RUSTC_VERSION >= 107900