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 66
75 .. code-block:: 67 .. code-block::
76 68
77 69 rust/bindings/
78 !! 70 (rust/helpers.c)
79 71
80 72 include/ -----+ <-+
81 73 | |
82 drivers/ rust/kernel/ 74 drivers/ rust/kernel/ +----------+ <-+ |
83 fs/ 75 fs/ | bindgen | |
84 .../ +------------------ 76 .../ +-------------------+ +----------+ --+ |
85 | Abstractions 77 | Abstractions | | |
86 +---------+ | +------+ +------+ 78 +---------+ | +------+ +------+ | +----------+ | |
87 | my_foo | -----> | | foo | | bar | 79 | my_foo | -----> | | foo | | bar | | -------> | Bindings | <-+ |
88 | driver | Safe | | sub- | | sub- | 80 | driver | Safe | | sub- | | sub- | | Unsafe | | |
89 +---------+ | |system| |system| 81 +---------+ | |system| |system| | | bindings | <-----+
90 | | +------+ +------+ 82 | | +------+ +------+ | | crate | |
91 | | kernel crate 83 | | kernel crate | +----------+ |
92 | +------------------ 84 | +-------------------+ |
93 | 85 | |
94 +------------------# FORBIDDEN #- 86 +------------------# FORBIDDEN #--------------------------------+
95 87
96 The main idea is to encapsulate all direct int 88 The main idea is to encapsulate all direct interaction with the kernel's C APIs
97 into carefully reviewed and documented abstrac 89 into carefully reviewed and documented abstractions. Then users of these
98 abstractions cannot introduce undefined behavi 90 abstractions cannot introduce undefined behavior (UB) as long as:
99 91
100 #. The abstractions are correct ("sound"). 92 #. The abstractions are correct ("sound").
101 #. Any ``unsafe`` blocks respect the safety co 93 #. Any ``unsafe`` blocks respect the safety contract necessary to call the
102 operations inside the block. Similarly, any 94 operations inside the block. Similarly, any ``unsafe impl``\ s respect the
103 safety contract necessary to implement the 95 safety contract necessary to implement the trait.
104 96
105 Bindings 97 Bindings
106 ~~~~~~~~ 98 ~~~~~~~~
107 99
108 By including a C header from ``include/`` into 100 By including a C header from ``include/`` into
109 ``rust/bindings/bindings_helper.h``, the ``bin 101 ``rust/bindings/bindings_helper.h``, the ``bindgen`` tool will auto-generate the
110 bindings for the included subsystem. After bui 102 bindings for the included subsystem. After building, see the ``*_generated.rs``
111 output files in the ``rust/bindings/`` directo 103 output files in the ``rust/bindings/`` directory.
112 104
113 For parts of the C header that ``bindgen`` doe 105 For parts of the C header that ``bindgen`` does not auto generate, e.g. C
114 ``inline`` functions or non-trivial macros, it 106 ``inline`` functions or non-trivial macros, it is acceptable to add a small
115 wrapper function to ``rust/helpers/`` to make !! 107 wrapper function to ``rust/helpers.c`` to make it available for the Rust side as
116 well. 108 well.
117 109
118 Abstractions 110 Abstractions
119 ~~~~~~~~~~~~ 111 ~~~~~~~~~~~~
120 112
121 Abstractions are the layer between the binding 113 Abstractions are the layer between the bindings and the in-kernel users. They
122 are located in ``rust/kernel/`` and their role 114 are located in ``rust/kernel/`` and their role is to encapsulate the unsafe
123 access to the bindings into an as-safe-as-poss 115 access to the bindings into an as-safe-as-possible API that they expose to their
124 users. Users of the abstractions include thing 116 users. Users of the abstractions include things like drivers or file systems
125 written in Rust. 117 written in Rust.
126 118
127 Besides the safety aspect, the abstractions ar 119 Besides the safety aspect, the abstractions are supposed to be "ergonomic", in
128 the sense that they turn the C interfaces into 120 the sense that they turn the C interfaces into "idiomatic" Rust code. Basic
129 examples are to turn the C resource acquisitio 121 examples are to turn the C resource acquisition and release into Rust
130 constructors and destructors or C integer erro 122 constructors and destructors or C integer error codes into Rust's ``Result``\ s.
131 123
132 124
133 Conditional compilation 125 Conditional compilation
134 ----------------------- 126 -----------------------
135 127
136 Rust code has access to conditional compilatio 128 Rust code has access to conditional compilation based on the kernel
137 configuration: 129 configuration:
138 130
139 .. code-block:: rust 131 .. code-block:: rust
140 132
141 #[cfg(CONFIG_X)] // Enabled 133 #[cfg(CONFIG_X)] // Enabled (`y` or `m`)
142 #[cfg(CONFIG_X="y")] // Enabled as a 134 #[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`)
143 #[cfg(CONFIG_X="m")] // Enabled as a 135 #[cfg(CONFIG_X="m")] // Enabled as a module (`m`)
144 #[cfg(not(CONFIG_X))] // Disabled 136 #[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.