1 .. SPDX-License-Identifier: GPL-2.0
2
3 General Information
4 ===================
5
6 This document contains useful information to k
7 the Rust support in the kernel.
8
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
19 ------------------
20
21 Rust kernel code is documented using ``rustdoc
22 generator.
23
24 The generated HTML docs include integrated sea
25 functions, constants), source code, etc. They
26 in mainline and generated alongside the rest o
27
28 http://kernel.org/
29
30 The docs can also be easily generated and read
31 (same order as compiling the code itself) and
32 are needed. This has the added advantage that
33 the particular kernel configuration used. To g
34 target with the same invocation used for compi
35
36 make LLVM=1 rustdoc
37
38 To read the docs locally in your web browser,
39
40 xdg-open Documentation/output/rust/rus
41
42 To learn about how to write the documentation,
43
44
45 Extra lints
46 -----------
47
48 While ``rustc`` is a very helpful compiler, so
49 available via ``clippy``, a Rust linter. To en
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 genera
55 enabled while building a production kernel.
56
57
58 Abstractions vs. bindings
59 -------------------------
60
61 Abstractions are Rust code wrapping kernel fun
62
63 In order to use functions and types from the C
64 Bindings are the declarations for Rust of thos
65 the C side.
66
67 For instance, one may write a ``Mutex`` abstra
68 a ``struct mutex`` from the C side and calls i
69
70 Abstractions are not available for all the ker
71 but it is intended that coverage is expanded a
72 (e.g. drivers) should not use the C bindings d
73 should provide as-safe-as-possible abstraction
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
132
133 Conditional compilation
134 -----------------------
135
136 Rust code has access to conditional compilatio
137 configuration:
138
139 .. code-block:: rust
140
141 #[cfg(CONFIG_X)] // Enabled
142 #[cfg(CONFIG_X="y")] // Enabled as a
143 #[cfg(CONFIG_X="m")] // Enabled as a
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.