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