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