projects/linux·blob uaccess-cleanups · refs

487 lines · 15.0 KiB

1.. SPDX-License-Identifier: GPL-2.0
2
3Coding Guidelines
4=================
5
6This document describes how to write Rust code in the kernel.
7
8
9Style & formatting
10------------------
11
12The code should be formatted using ``rustfmt``. In this way, a person
13contributing from time to time to the kernel does not need to learn and
14remember one more style guide. More importantly, reviewers and maintainers
15do not need to spend time pointing out style issues anymore, and thus
16less patch roundtrips may be needed to land a change.
17
18.. note:: Conventions on comments and documentation are not checked by
19 ``rustfmt``. Thus those are still needed to be taken care of.
20
21The default settings of ``rustfmt`` are used. This means the idiomatic Rust
22style is followed. For instance, 4 spaces are used for indentation rather
23than tabs.
24
25It is convenient to instruct editors/IDEs to format while typing,
26when saving or at commit time. However, if for some reason reformatting
27the entire kernel Rust sources is needed at some point, the following can be
28run::
29
30 make LLVM=1 rustfmt
31
32It is also possible to check if everything is formatted (printing a diff
33otherwise), for instance for a CI, with::
34
35 make LLVM=1 rustfmtcheck
36
37Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
38individual files, and does not require a kernel configuration. Sometimes it may
39even work with broken code.
40
41Imports
42~~~~~~~
43
44``rustfmt``, by default, formats imports in a way that is prone to conflicts
45while merging and rebasing, since in some cases it condenses several items into
46the same line. For instance:
47
48.. code-block:: rust
49
50 // Do not use this style.
51 use crate::{
52 example1,
53 example2::{example3, example4, example5},
54 example6, example7,
55 example8::example9,
56 };
57
58Instead, the kernel uses a vertical layout that looks like this:
59
60.. code-block:: rust
61
62 use crate::{
63 example1,
64 example2::{
65 example3,
66 example4,
67 example5, //
68 },
69 example6,
70 example7,
71 example8::example9, //
72 };
73
74That is, each item goes into its own line, and braces are used as soon as there
75is more than one item in a list.
76
77The trailing empty comment allows to preserve this formatting. Not only that,
78``rustfmt`` will actually reformat imports vertically when the empty comment is
79added. That is, it is possible to easily reformat the original example into the
80expected style by running ``rustfmt`` on an input like:
81
82.. code-block:: rust
83
84 // Do not use this style.
85 use crate::{
86 example1,
87 example2::{example3, example4, example5, //
88 },
89 example6, example7,
90 example8::example9, //
91 };
92
93The trailing empty comment works for nested imports, as shown above, as well as
94for single item imports -- this can be useful to minimize diffs within patch
95series:
96
97.. code-block:: rust
98
99 use crate::{
100 example1, //
101 };
102
103The trailing empty comment works in any of the lines within the braces, but it
104is preferred to keep it in the last item, since it is reminiscent of the
105trailing comma in other formatters. Sometimes it may be simpler to avoid moving
106the comment several times within a patch series due to changes in the list.
107
108There may be cases where exceptions may need to be made, i.e. none of this is
109a hard rule. There is also code that is not migrated to this style yet, but
110please do not introduce code in other styles.
111
112Eventually, the goal is to get ``rustfmt`` to support this formatting style (or
113a similar one) automatically in a stable release without requiring the trailing
114empty comment. Thus, at some point, the goal is to remove those comments.
115
116
117Comments
118--------
119
120"Normal" comments (i.e. ``//``, rather than code documentation which starts
121with ``///`` or ``//!``) are written in Markdown the same way as documentation
122comments are, even though they will not be rendered. This improves consistency,
123simplifies the rules and allows to move content between the two kinds of
124comments more easily. For instance:
125
126.. code-block:: rust
127
128 // `object` is ready to be handled now.
129 f(object);
130
131Furthermore, just like documentation, comments are capitalized at the beginning
132of a sentence and ended with a period (even if it is a single sentence). This
133includes ``// SAFETY:``, ``// TODO:`` and other "tagged" comments, e.g.:
134
135.. code-block:: rust
136
137 // FIXME: The error should be handled properly.
138
139Comments should not be used for documentation purposes: comments are intended
140for implementation details, not users. This distinction is useful even if the
141reader of the source file is both an implementor and a user of an API. In fact,
142sometimes it is useful to use both comments and documentation at the same time.
143For instance, for a ``TODO`` list or to comment on the documentation itself.
144For the latter case, comments can be inserted in the middle; that is, closer to
145the line of documentation to be commented. For any other case, comments are
146written after the documentation, e.g.:
147
148.. code-block:: rust
149
150 /// Returns a new [`Foo`].
151 ///
152 /// # Examples
153 ///
154 // TODO: Find a better example.
155 /// ```
156 /// let foo = f(42);
157 /// ```
158 // FIXME: Use fallible approach.
159 pub fn f(x: i32) -> Foo {
160 // ...
161 }
162
163This applies to both public and private items. This increases consistency with
164public items, allows changes to visibility with less changes involved and will
165allow us to potentially generate the documentation for private items as well.
166In other words, if documentation is written for a private item, then ``///``
167should still be used. For instance:
168
169.. code-block:: rust
170
171 /// My private function.
172 // TODO: ...
173 fn f() {}
174
175One special kind of comments are the ``// SAFETY:`` comments. These must appear
176before every ``unsafe`` block, and they explain why the code inside the block is
177correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.:
178
179.. code-block:: rust
180
181 // SAFETY: `p` is valid by the safety requirements.
182 unsafe { *p = 0; }
183
184``// SAFETY:`` comments are not to be confused with the ``# Safety`` sections
185in code documentation. ``# Safety`` sections specify the contract that callers
186(for functions) or implementors (for traits) need to abide by. ``// SAFETY:``
187comments show why a call (for functions) or implementation (for traits) actually
188respects the preconditions stated in a ``# Safety`` section or the language
189reference.
190
191
192Code documentation
193------------------
194
195Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
196Instead, the usual system for documenting Rust code is used: the ``rustdoc``
197tool, which uses Markdown (a lightweight markup language).
198
199To learn Markdown, there are many guides available out there. For instance,
200the one at:
201
202 https://commonmark.org/help/
203
204This is how a well-documented Rust function may look like:
205
206.. code-block:: rust
207
208 /// Returns the contained [`Some`] value, consuming the `self` value,
209 /// without checking that the value is not [`None`].
210 ///
211 /// # Safety
212 ///
213 /// Calling this method on [`None`] is *[undefined behavior]*.
214 ///
215 /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
216 ///
217 /// # Examples
218 ///
219 /// ```
220 /// let x = Some("air");
221 /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air");
222 /// ```
223 pub unsafe fn unwrap_unchecked(self) -> T {
224 match self {
225 Some(val) => val,
226
227 // SAFETY: The safety contract must be upheld by the caller.
228 None => unsafe { hint::unreachable_unchecked() },
229 }
230 }
231
232This example showcases a few ``rustdoc`` features and some conventions followed
233in the kernel:
234
235- The first paragraph must be a single sentence briefly describing what
236 the documented item does. Further explanations must go in extra paragraphs.
237
238- Unsafe functions must document their safety preconditions under
239 a ``# Safety`` section.
240
241- While not shown here, if a function may panic, the conditions under which
242 that happens must be described under a ``# Panics`` section.
243
244 Please note that panicking should be very rare and used only with a good
245 reason. In almost all cases, a fallible approach should be used, typically
246 returning a ``Result``.
247
248- If providing examples of usage would help readers, they must be written in
249 a section called ``# Examples``.
250
251- Rust items (functions, types, constants...) must be linked appropriately
252 (``rustdoc`` will create a link automatically).
253
254- Any ``unsafe`` block must be preceded by a ``// SAFETY:`` comment
255 describing why the code inside is sound.
256
257 While sometimes the reason might look trivial and therefore unneeded,
258 writing these comments is not just a good way of documenting what has been
259 taken into account, but most importantly, it provides a way to know that
260 there are no *extra* implicit constraints.
261
262To learn more about how to write documentation for Rust and extra features,
263please take a look at the ``rustdoc`` book at:
264
265 https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
266
267In addition, the kernel supports creating links relative to the source tree by
268prefixing the link destination with ``srctree/``. For instance:
269
270.. code-block:: rust
271
272 //! C header: [`include/linux/printk.h`](srctree/include/linux/printk.h)
273
274or:
275
276.. code-block:: rust
277
278 /// [`struct mutex`]: srctree/include/linux/mutex.h
279
280
281C FFI types
282-----------
283
284Rust kernel code refers to C types, such as ``int``, using type aliases such as
285``c_int``, which are readily available from the ``kernel`` prelude. Please do
286not use the aliases from ``core::ffi`` -- they may not map to the correct types.
287
288These aliases should generally be referred directly by their identifier, i.e.
289as a single segment path. For instance:
290
291.. code-block:: rust
292
293 fn f(p: *const c_char) -> c_int {
294 // ...
295 }
296
297
298Naming
299------
300
301Rust kernel code follows the usual Rust naming conventions:
302
303 https://rust-lang.github.io/api-guidelines/naming.html
304
305When existing C concepts (e.g. macros, functions, objects...) are wrapped into
306a Rust abstraction, a name as close as reasonably possible to the C side should
307be used in order to avoid confusion and to improve readability when switching
308back and forth between the C and Rust sides. For instance, macros such as
309``pr_info`` from C are named the same in the Rust side.
310
311Having said that, casing should be adjusted to follow the Rust naming
312conventions, and namespacing introduced by modules and types should not be
313repeated in the item names. For instance, when wrapping constants like:
314
315.. code-block:: c
316
317 #define GPIO_LINE_DIRECTION_IN 0
318 #define GPIO_LINE_DIRECTION_OUT 1
319
320The equivalent in Rust may look like (ignoring documentation):
321
322.. code-block:: rust
323
324 pub mod gpio {
325 pub enum LineDirection {
326 In = bindings::GPIO_LINE_DIRECTION_IN as _,
327 Out = bindings::GPIO_LINE_DIRECTION_OUT as _,
328 }
329 }
330
331That is, the equivalent of ``GPIO_LINE_DIRECTION_IN`` would be referred to as
332``gpio::LineDirection::In``. In particular, it should not be named
333``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN``.
334
335
336Lints
337-----
338
339In Rust, it is possible to ``allow`` particular warnings (diagnostics, lints)
340locally, making the compiler ignore instances of a given warning within a given
341function, module, block, etc.
342
343It is similar to ``#pragma GCC diagnostic push`` + ``ignored`` + ``pop`` in C
344[#]_:
345
346.. code-block:: c
347
348 #pragma GCC diagnostic push
349 #pragma GCC diagnostic ignored "-Wunused-function"
350 static void f(void) {}
351 #pragma GCC diagnostic pop
352
353.. [#] In this particular case, the kernel's ``__{always,maybe}_unused``
354 attributes (C23's ``[[maybe_unused]]``) may be used; however, the example
355 is meant to reflect the equivalent lint in Rust discussed afterwards.
356
357But way less verbose:
358
359.. code-block:: rust
360
361 #[allow(dead_code)]
362 fn f() {}
363
364By that virtue, it makes it possible to comfortably enable more diagnostics by
365default (i.e. outside ``W=`` levels). In particular, those that may have some
366false positives but that are otherwise quite useful to keep enabled to catch
367potential mistakes.
368
369On top of that, Rust provides the ``expect`` attribute which takes this further.
370It makes the compiler warn if the warning was not produced. For instance, the
371following will ensure that, when ``f()`` is called somewhere, we will have to
372remove the attribute:
373
374.. code-block:: rust
375
376 #[expect(dead_code)]
377 fn f() {}
378
379If we do not, we get a warning from the compiler::
380
381 warning: this lint expectation is unfulfilled
382 --> x.rs:3:10
383 |
384 3 | #[expect(dead_code)]
385 | ^^^^^^^^^
386 |
387 = note: `#[warn(unfulfilled_lint_expectations)]` on by default
388
389This means that ``expect``\ s do not get forgotten when they are not needed, which
390may happen in several situations, e.g.:
391
392- Temporary attributes added while developing.
393
394- Improvements in lints in the compiler, Clippy or custom tools which may
395 remove a false positive.
396
397- When the lint is not needed anymore because it was expected that it would be
398 removed at some point, such as the ``dead_code`` example above.
399
400It also increases the visibility of the remaining ``allow``\ s and reduces the
401chance of misapplying one.
402
403Thus prefer ``expect`` over ``allow`` unless:
404
405- Conditional compilation triggers the warning in some cases but not others.
406
407 If there are only a few cases where the warning triggers (or does not
408 trigger) compared to the total number of cases, then one may consider using
409 a conditional ``expect`` (i.e. ``cfg_attr(..., expect(...))``). Otherwise,
410 it is likely simpler to just use ``allow``.
411
412- Inside macros, when the different invocations may create expanded code that
413 triggers the warning in some cases but not in others.
414
415- When code may trigger a warning for some architectures but not others, such
416 as an ``as`` cast to a C FFI type.
417
418As a more developed example, consider for instance this program:
419
420.. code-block:: rust
421
422 fn g() {}
423
424 fn main() {
425 #[cfg(CONFIG_X)]
426 g();
427 }
428
429Here, function ``g()`` is dead code if ``CONFIG_X`` is not set. Can we use
430``expect`` here?
431
432.. code-block:: rust
433
434 #[expect(dead_code)]
435 fn g() {}
436
437 fn main() {
438 #[cfg(CONFIG_X)]
439 g();
440 }
441
442This would emit a lint if ``CONFIG_X`` is set, since it is not dead code in that
443configuration. Therefore, in cases like this, we cannot use ``expect`` as-is.
444
445A simple possibility is using ``allow``:
446
447.. code-block:: rust
448
449 #[allow(dead_code)]
450 fn g() {}
451
452 fn main() {
453 #[cfg(CONFIG_X)]
454 g();
455 }
456
457An alternative would be using a conditional ``expect``:
458
459.. code-block:: rust
460
461 #[cfg_attr(not(CONFIG_X), expect(dead_code))]
462 fn g() {}
463
464 fn main() {
465 #[cfg(CONFIG_X)]
466 g();
467 }
468
469This would ensure that, if someone introduces another call to ``g()`` somewhere
470(e.g. unconditionally), then it would be spotted that it is not dead code
471anymore. However, the ``cfg_attr`` is more complex than a simple ``allow``.
472
473Therefore, it is likely that it is not worth using conditional ``expect``\ s when
474more than one or two configurations are involved or when the lint may be
475triggered due to non-local changes (such as ``dead_code``).
476
477For more information about diagnostics in Rust, please see:
478
479 https://doc.rust-lang.org/stable/reference/attributes/diagnostics.html
480
481Error handling
482--------------
483
484For some background and guidelines about Rust for Linux specific error handling,
485please see:
486
487 https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust