1 .. SPDX-License-Identifier: GPL-2.0
2
3 Coding Guidelines
4 =================
5
6 This document describes how to write Rust code
7
8
9 Style & formatting
10 ------------------
11
12 The code should be formatted using ``rustfmt``
13 contributing from time to time to the kernel d
14 remember one more style guide. More importantl
15 do not need to spend time pointing out style i
16 less patch roundtrips may be needed to land a
17
18 .. note:: Conventions on comments and document
19 ``rustfmt``. Thus those are still needed to
20
21 The default settings of ``rustfmt`` are used.
22 style is followed. For instance, 4 spaces are
23 than tabs.
24
25 It is convenient to instruct editors/IDEs to f
26 when saving or at commit time. However, if for
27 the entire kernel Rust sources is needed at so
28 run::
29
30 make LLVM=1 rustfmt
31
32 It is also possible to check if everything is
33 otherwise), for instance for a CI, with::
34
35 make LLVM=1 rustfmtcheck
36
37 Like ``clang-format`` for the rest of the kern
38 individual files, and does not require a kerne
39 even work with broken code.
40
41
42 Comments
43 --------
44
45 "Normal" comments (i.e. ``//``, rather than co
46 with ``///`` or ``//!``) are written in Markdo
47 comments are, even though they will not be ren
48 simplifies the rules and allows to move conten
49 comments more easily. For instance:
50
51 .. code-block:: rust
52
53 // `object` is ready to be handled now
54 f(object);
55
56 Furthermore, just like documentation, comments
57 of a sentence and ended with a period (even if
58 includes ``// SAFETY:``, ``// TODO:`` and othe
59
60 .. code-block:: rust
61
62 // FIXME: The error should be handled
63
64 Comments should not be used for documentation
65 for implementation details, not users. This di
66 reader of the source file is both an implement
67 sometimes it is useful to use both comments an
68 For instance, for a ``TODO`` list or to commen
69 For the latter case, comments can be inserted
70 the line of documentation to be commented. For
71 written after the documentation, e.g.:
72
73 .. code-block:: rust
74
75 /// Returns a new [`Foo`].
76 ///
77 /// # Examples
78 ///
79 // TODO: Find a better example.
80 /// ```
81 /// let foo = f(42);
82 /// ```
83 // FIXME: Use fallible approach.
84 pub fn f(x: i32) -> Foo {
85 // ...
86 }
87
88 One special kind of comments are the ``// SAFE
89 before every ``unsafe`` block, and they explai
90 correct/sound, i.e. why it cannot trigger unde
91
92 .. code-block:: rust
93
94 // SAFETY: `p` is valid by the safety
95 unsafe { *p = 0; }
96
97 ``// SAFETY:`` comments are not to be confused
98 in code documentation. ``# Safety`` sections s
99 (for functions) or implementors (for traits) n
100 comments show why a call (for functions) or im
101 respects the preconditions stated in a ``# Saf
102 reference.
103
104
105 Code documentation
106 ------------------
107
108 Rust kernel code is not documented like C kern
109 Instead, the usual system for documenting Rust
110 tool, which uses Markdown (a lightweight marku
111
112 To learn Markdown, there are many guides avail
113 the one at:
114
115 https://commonmark.org/help/
116
117 This is how a well-documented Rust function ma
118
119 .. code-block:: rust
120
121 /// Returns the contained [`Some`] val
122 /// without checking that the value is
123 ///
124 /// # Safety
125 ///
126 /// Calling this method on [`None`] is
127 ///
128 /// [undefined behavior]: https://doc.
129 ///
130 /// # Examples
131 ///
132 /// ```
133 /// let x = Some("air");
134 /// assert_eq!(unsafe { x.unwrap_unche
135 /// ```
136 pub unsafe fn unwrap_unchecked(self) -
137 match self {
138 Some(val) => val,
139
140 // SAFETY: The safety contract
141 None => unsafe { hint::unreach
142 }
143 }
144
145 This example showcases a few ``rustdoc`` featu
146 in the kernel:
147
148 - The first paragraph must be a single sentenc
149 the documented item does. Further explanatio
150
151 - Unsafe functions must document their safety
152 a ``# Safety`` section.
153
154 - While not shown here, if a function may pani
155 that happens must be described under a ``# P
156
157 Please note that panicking should be very ra
158 reason. In almost all cases, a fallible appr
159 returning a ``Result``.
160
161 - If providing examples of usage would help re
162 a section called ``# Examples``.
163
164 - Rust items (functions, types, constants...)
165 (``rustdoc`` will create a link automaticall
166
167 - Any ``unsafe`` block must be preceded by a `
168 describing why the code inside is sound.
169
170 While sometimes the reason might look trivia
171 writing these comments is not just a good wa
172 taken into account, but most importantly, it
173 there are no *extra* implicit constraints.
174
175 To learn more about how to write documentation
176 please take a look at the ``rustdoc`` book at:
177
178 https://doc.rust-lang.org/rustdoc/how-
179
180 In addition, the kernel supports creating link
181 prefixing the link destination with ``srctree/
182
183 .. code-block:: rust
184
185 //! C header: [`include/linux/printk.h
186
187 or:
188
189 .. code-block:: rust
190
191 /// [`struct mutex`]: srctree/include/
192
193
194 Naming
195 ------
196
197 Rust kernel code follows the usual Rust naming
198
199 https://rust-lang.github.io/api-guidel
200
201 When existing C concepts (e.g. macros, functio
202 a Rust abstraction, a name as close as reasona
203 be used in order to avoid confusion and to imp
204 back and forth between the C and Rust sides. F
205 ``pr_info`` from C are named the same in the R
206
207 Having said that, casing should be adjusted to
208 conventions, and namespacing introduced by mod
209 repeated in the item names. For instance, when
210
211 .. code-block:: c
212
213 #define GPIO_LINE_DIRECTION_IN 0
214 #define GPIO_LINE_DIRECTION_OUT 1
215
216 The equivalent in Rust may look like (ignoring
217
218 .. code-block:: rust
219
220 pub mod gpio {
221 pub enum LineDirection {
222 In = bindings::GPIO_LINE_DIREC
223 Out = bindings::GPIO_LINE_DIRE
224 }
225 }
226
227 That is, the equivalent of ``GPIO_LINE_DIRECTI
228 ``gpio::LineDirection::In``. In particular, it
229 ``gpio::gpio_line_direction::GPIO_LINE_DIRECTI
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.