mirror of
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
synced 2024-08-25 10:19:47 +00:00
![Miguel Ojeda](/assets/img/avatar_default.png)
Most of the documentation for Rust is written within the source code itself, as it is idiomatic for Rust projects. This applies to both the shared infrastructure at `rust/` as well as any other Rust module (e.g. drivers) written across the kernel. However, these documents contain general information that does not fit particularly well in the source code, like the Quick Start guide. It also contains a few other small changes elsewhere in the documentation folder. Reviewed-by: Kees Cook <keescook@chromium.org> Co-developed-by: Alex Gaynor <alex.gaynor@gmail.com> Signed-off-by: Alex Gaynor <alex.gaynor@gmail.com> Co-developed-by: Finn Behrens <me@kloenk.de> Signed-off-by: Finn Behrens <me@kloenk.de> Co-developed-by: Adam Bratschi-Kaye <ark.email@gmail.com> Signed-off-by: Adam Bratschi-Kaye <ark.email@gmail.com> Co-developed-by: Wedson Almeida Filho <wedsonaf@google.com> Signed-off-by: Wedson Almeida Filho <wedsonaf@google.com> Co-developed-by: Michael Ellerman <mpe@ellerman.id.au> Signed-off-by: Michael Ellerman <mpe@ellerman.id.au> Co-developed-by: Sven Van Asbroeck <thesven73@gmail.com> Signed-off-by: Sven Van Asbroeck <thesven73@gmail.com> Co-developed-by: Wu XiangCheng <bobwxc@email.cn> Signed-off-by: Wu XiangCheng <bobwxc@email.cn> Co-developed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Gary Guo <gary@garyguo.net> Co-developed-by: Boris-Chengbiao Zhou <bobo1239@web.de> Signed-off-by: Boris-Chengbiao Zhou <bobo1239@web.de> Co-developed-by: Yuki Okushi <jtitor@2k36.org> Signed-off-by: Yuki Okushi <jtitor@2k36.org> Co-developed-by: Wei Liu <wei.liu@kernel.org> Signed-off-by: Wei Liu <wei.liu@kernel.org> Co-developed-by: Daniel Xu <dxu@dxuuu.xyz> Signed-off-by: Daniel Xu <dxu@dxuuu.xyz> Co-developed-by: Julian Merkle <me@jvmerkle.de> Signed-off-by: Julian Merkle <me@jvmerkle.de> Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
216 lines
7.4 KiB
ReStructuredText
216 lines
7.4 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
Coding Guidelines
|
|
=================
|
|
|
|
This document describes how to write Rust code in the kernel.
|
|
|
|
|
|
Style & formatting
|
|
------------------
|
|
|
|
The code should be formatted using ``rustfmt``. In this way, a person
|
|
contributing from time to time to the kernel does not need to learn and
|
|
remember one more style guide. More importantly, reviewers and maintainers
|
|
do not need to spend time pointing out style issues anymore, and thus
|
|
less patch roundtrips may be needed to land a change.
|
|
|
|
.. note:: Conventions on comments and documentation are not checked by
|
|
``rustfmt``. Thus those are still needed to be taken care of.
|
|
|
|
The default settings of ``rustfmt`` are used. This means the idiomatic Rust
|
|
style is followed. For instance, 4 spaces are used for indentation rather
|
|
than tabs.
|
|
|
|
It is convenient to instruct editors/IDEs to format while typing,
|
|
when saving or at commit time. However, if for some reason reformatting
|
|
the entire kernel Rust sources is needed at some point, the following can be
|
|
run::
|
|
|
|
make LLVM=1 rustfmt
|
|
|
|
It is also possible to check if everything is formatted (printing a diff
|
|
otherwise), for instance for a CI, with::
|
|
|
|
make LLVM=1 rustfmtcheck
|
|
|
|
Like ``clang-format`` for the rest of the kernel, ``rustfmt`` works on
|
|
individual files, and does not require a kernel configuration. Sometimes it may
|
|
even work with broken code.
|
|
|
|
|
|
Comments
|
|
--------
|
|
|
|
"Normal" comments (i.e. ``//``, rather than code documentation which starts
|
|
with ``///`` or ``//!``) are written in Markdown the same way as documentation
|
|
comments are, even though they will not be rendered. This improves consistency,
|
|
simplifies the rules and allows to move content between the two kinds of
|
|
comments more easily. For instance:
|
|
|
|
.. code-block:: rust
|
|
|
|
// `object` is ready to be handled now.
|
|
f(object);
|
|
|
|
Furthermore, just like documentation, comments are capitalized at the beginning
|
|
of a sentence and ended with a period (even if it is a single sentence). This
|
|
includes ``// SAFETY:``, ``// TODO:`` and other "tagged" comments, e.g.:
|
|
|
|
.. code-block:: rust
|
|
|
|
// FIXME: The error should be handled properly.
|
|
|
|
Comments should not be used for documentation purposes: comments are intended
|
|
for implementation details, not users. This distinction is useful even if the
|
|
reader of the source file is both an implementor and a user of an API. In fact,
|
|
sometimes it is useful to use both comments and documentation at the same time.
|
|
For instance, for a ``TODO`` list or to comment on the documentation itself.
|
|
For the latter case, comments can be inserted in the middle; that is, closer to
|
|
the line of documentation to be commented. For any other case, comments are
|
|
written after the documentation, e.g.:
|
|
|
|
.. code-block:: rust
|
|
|
|
/// Returns a new [`Foo`].
|
|
///
|
|
/// # Examples
|
|
///
|
|
// TODO: Find a better example.
|
|
/// ```
|
|
/// let foo = f(42);
|
|
/// ```
|
|
// FIXME: Use fallible approach.
|
|
pub fn f(x: i32) -> Foo {
|
|
// ...
|
|
}
|
|
|
|
One special kind of comments are the ``// SAFETY:`` comments. These must appear
|
|
before every ``unsafe`` block, and they explain why the code inside the block is
|
|
correct/sound, i.e. why it cannot trigger undefined behavior in any case, e.g.:
|
|
|
|
.. code-block:: rust
|
|
|
|
// SAFETY: `p` is valid by the safety requirements.
|
|
unsafe { *p = 0; }
|
|
|
|
``// SAFETY:`` comments are not to be confused with the ``# Safety`` sections
|
|
in code documentation. ``# Safety`` sections specify the contract that callers
|
|
(for functions) or implementors (for traits) need to abide by. ``// SAFETY:``
|
|
comments show why a call (for functions) or implementation (for traits) actually
|
|
respects the preconditions stated in a ``# Safety`` section or the language
|
|
reference.
|
|
|
|
|
|
Code documentation
|
|
------------------
|
|
|
|
Rust kernel code is not documented like C kernel code (i.e. via kernel-doc).
|
|
Instead, the usual system for documenting Rust code is used: the ``rustdoc``
|
|
tool, which uses Markdown (a lightweight markup language).
|
|
|
|
To learn Markdown, there are many guides available out there. For instance,
|
|
the one at:
|
|
|
|
https://commonmark.org/help/
|
|
|
|
This is how a well-documented Rust function may look like:
|
|
|
|
.. code-block:: rust
|
|
|
|
/// Returns the contained [`Some`] value, consuming the `self` value,
|
|
/// without checking that the value is not [`None`].
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// Calling this method on [`None`] is *[undefined behavior]*.
|
|
///
|
|
/// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// let x = Some("air");
|
|
/// assert_eq!(unsafe { x.unwrap_unchecked() }, "air");
|
|
/// ```
|
|
pub unsafe fn unwrap_unchecked(self) -> T {
|
|
match self {
|
|
Some(val) => val,
|
|
|
|
// SAFETY: The safety contract must be upheld by the caller.
|
|
None => unsafe { hint::unreachable_unchecked() },
|
|
}
|
|
}
|
|
|
|
This example showcases a few ``rustdoc`` features and some conventions followed
|
|
in the kernel:
|
|
|
|
- The first paragraph must be a single sentence briefly describing what
|
|
the documented item does. Further explanations must go in extra paragraphs.
|
|
|
|
- Unsafe functions must document their safety preconditions under
|
|
a ``# Safety`` section.
|
|
|
|
- While not shown here, if a function may panic, the conditions under which
|
|
that happens must be described under a ``# Panics`` section.
|
|
|
|
Please note that panicking should be very rare and used only with a good
|
|
reason. In almost all cases, a fallible approach should be used, typically
|
|
returning a ``Result``.
|
|
|
|
- If providing examples of usage would help readers, they must be written in
|
|
a section called ``# Examples``.
|
|
|
|
- Rust items (functions, types, constants...) must be linked appropriately
|
|
(``rustdoc`` will create a link automatically).
|
|
|
|
- Any ``unsafe`` block must be preceded by a ``// SAFETY:`` comment
|
|
describing why the code inside is sound.
|
|
|
|
While sometimes the reason might look trivial and therefore unneeded,
|
|
writing these comments is not just a good way of documenting what has been
|
|
taken into account, but most importantly, it provides a way to know that
|
|
there are no *extra* implicit constraints.
|
|
|
|
To learn more about how to write documentation for Rust and extra features,
|
|
please take a look at the ``rustdoc`` book at:
|
|
|
|
https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html
|
|
|
|
|
|
Naming
|
|
------
|
|
|
|
Rust kernel code follows the usual Rust naming conventions:
|
|
|
|
https://rust-lang.github.io/api-guidelines/naming.html
|
|
|
|
When existing C concepts (e.g. macros, functions, objects...) are wrapped into
|
|
a Rust abstraction, a name as close as reasonably possible to the C side should
|
|
be used in order to avoid confusion and to improve readability when switching
|
|
back and forth between the C and Rust sides. For instance, macros such as
|
|
``pr_info`` from C are named the same in the Rust side.
|
|
|
|
Having said that, casing should be adjusted to follow the Rust naming
|
|
conventions, and namespacing introduced by modules and types should not be
|
|
repeated in the item names. For instance, when wrapping constants like:
|
|
|
|
.. code-block:: c
|
|
|
|
#define GPIO_LINE_DIRECTION_IN 0
|
|
#define GPIO_LINE_DIRECTION_OUT 1
|
|
|
|
The equivalent in Rust may look like (ignoring documentation):
|
|
|
|
.. code-block:: rust
|
|
|
|
pub mod gpio {
|
|
pub enum LineDirection {
|
|
In = bindings::GPIO_LINE_DIRECTION_IN as _,
|
|
Out = bindings::GPIO_LINE_DIRECTION_OUT as _,
|
|
}
|
|
}
|
|
|
|
That is, the equivalent of ``GPIO_LINE_DIRECTION_IN`` would be referred to as
|
|
``gpio::LineDirection::In``. In particular, it should not be named
|
|
``gpio::gpio_line_direction::GPIO_LINE_DIRECTION_IN``.
|