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