mirror of
https://github.com/armbian/linux-cix.git
synced 2026-01-06 12:30:45 -08:00
Merge tag 'rust-v6.1-rc1' of https://github.com/Rust-for-Linux/linux
Pull Rust introductory support from Kees Cook: "The tree has a recent base, but has fundamentally been in linux-next for a year and a half[1]. It's been updated based on feedback from the Kernel Maintainer's Summit, and to gain recent Reviewed-by: tags. Miguel is the primary maintainer, with me helping where needed/wanted. Our plan is for the tree to switch to the standard non-rebasing practice once this initial infrastructure series lands. The contents are the absolute minimum to get Rust code building in the kernel, with many more interfaces[2] (and drivers - NVMe[3], 9p[4], M1 GPU[5]) on the way. The initial support of Rust-for-Linux comes in roughly 4 areas: - Kernel internals (kallsyms expansion for Rust symbols, %pA format) - Kbuild infrastructure (Rust build rules and support scripts) - Rust crates and bindings for initial minimum viable build - Rust kernel documentation and samples Rust support has been in linux-next for a year and a half now, and the short log doesn't do justice to the number of people who have contributed both to the Linux kernel side but also to the upstream Rust side to support the kernel's needs. Thanks to these 173 people, and many more, who have been involved in all kinds of ways: Miguel Ojeda, Wedson Almeida Filho, Alex Gaynor, Boqun Feng, Gary Guo, Björn Roy Baron, Andreas Hindborg, Adam Bratschi-Kaye, Benno Lossin, Maciej Falkowski, Finn Behrens, Sven Van Asbroeck, Asahi Lina, FUJITA Tomonori, John Baublitz, Wei Liu, Geoffrey Thomas, Philip Herron, Arthur Cohen, David Faust, Antoni Boucher, Philip Li, Yujie Liu, Jonathan Corbet, Greg Kroah-Hartman, Paul E. McKenney, Josh Triplett, Kent Overstreet, David Gow, Alice Ryhl, Robin Randhawa, Kees Cook, Nick Desaulniers, Matthew Wilcox, Linus Walleij, Joe Perches, Michael Ellerman, Petr Mladek, Masahiro Yamada, Arnaldo Carvalho de Melo, Andrii Nakryiko, Konstantin Shelekhin, Rasmus Villemoes, Konstantin Ryabitsev, Stephen Rothwell, Andy Shevchenko, Sergey Senozhatsky, John Paul Adrian Glaubitz, David Laight, Nathan Chancellor, Jonathan Cameron, Daniel Latypov, Shuah Khan, Brendan Higgins, Julia Lawall, Laurent Pinchart, Geert Uytterhoeven, Akira Yokosawa, Pavel Machek, David S. Miller, John Hawley, James Bottomley, Arnd Bergmann, Christian Brauner, Dan Robertson, Nicholas Piggin, Zhouyi Zhou, Elena Zannoni, Jose E. Marchesi, Leon Romanovsky, Will Deacon, Richard Weinberger, Randy Dunlap, Paolo Bonzini, Roland Dreier, Mark Brown, Sasha Levin, Ted Ts'o, Steven Rostedt, Jarkko Sakkinen, Michal Kubecek, Marco Elver, Al Viro, Keith Busch, Johannes Berg, Jan Kara, David Sterba, Connor Kuehl, Andy Lutomirski, Andrew Lunn, Alexandre Belloni, Peter Zijlstra, Russell King, Eric W. Biederman, Willy Tarreau, Christoph Hellwig, Emilio Cobos Álvarez, Christian Poveda, Mark Rousskov, John Ericson, TennyZhuang, Xuanwo, Daniel Paoliello, Manish Goregaokar, comex, Josh Stone, Stephan Sokolow, Philipp Krones, Guillaume Gomez, Joshua Nelson, Mats Larsen, Marc Poulhiès, Samantha Miller, Esteban Blanc, Martin Schmidt, Martin Rodriguez Reboredo, Daniel Xu, Viresh Kumar, Bartosz Golaszewski, Vegard Nossum, Milan Landaverde, Dariusz Sosnowski, Yuki Okushi, Matthew Bakhtiari, Wu XiangCheng, Tiago Lam, Boris-Chengbiao Zhou, Sumera Priyadarsini, Viktor Garske, Niklas Mohrin, Nándor István Krácser, Morgan Bartlett, Miguel Cano, Léo Lanteri Thauvin, Julian Merkle, Andreas Reindl, Jiapeng Chong, Fox Chen, Douglas Su, Antonio Terceiro, SeongJae Park, Sergio González Collado, Ngo Iok Ui (Wu Yu Wei), Joshua Abraham, Milan, Daniel Kolsoi, ahomescu, Manas, Luis Gerhorst, Li Hongyu, Philipp Gesang, Russell Currey, Jalil David Salamé Messina, Jon Olson, Raghvender, Angelos, Kaviraj Kanagaraj, Paul Römer, Sladyn Nunes, Mauro Baladés, Hsiang-Cheng Yang, Abhik Jain, Hongyu Li, Sean Nash, Yuheng Su, Peng Hao, Anhad Singh, Roel Kluin, Sara Saa, Geert Stappers, Garrett LeSage, IFo Hancroft, and Linus Torvalds" Link: https://lwn.net/Articles/849849/ [1] Link: https://github.com/Rust-for-Linux/linux/commits/rust [2] Link:d88c3744d6[3] Link:9367032607[4] Link: https://github.com/AsahiLinux/linux/commits/gpu/rust-wip [5] * tag 'rust-v6.1-rc1' of https://github.com/Rust-for-Linux/linux: (27 commits) MAINTAINERS: Rust samples: add first Rust examples x86: enable initial Rust support docs: add Rust documentation Kbuild: add Rust support rust: add `.rustfmt.toml` scripts: add `is_rust_module.sh` scripts: add `rust_is_available.sh` scripts: add `generate_rust_target.rs` scripts: add `generate_rust_analyzer.py` scripts: decode_stacktrace: demangle Rust symbols scripts: checkpatch: enable language-independent checks for Rust scripts: checkpatch: diagnose uses of `%pA` in the C side as errors vsprintf: add new `%pA` format specifier rust: export generated symbols rust: add `kernel` crate rust: add `bindings` crate rust: add `macros` crate rust: add `compiler_builtins` crate rust: adapt `alloc` crate to the kernel ...
This commit is contained in:
Linus Torvalds
6
.gitignore
vendored
6
.gitignore
vendored
@@ -37,6 +37,8 @@
|
||||
*.o
|
||||
*.o.*
|
||||
*.patch
|
||||
*.rmeta
|
||||
*.rsi
|
||||
*.s
|
||||
*.so
|
||||
*.so.dbg
|
||||
@@ -97,6 +99,7 @@ modules.order
|
||||
!.gitattributes
|
||||
!.gitignore
|
||||
!.mailmap
|
||||
!.rustfmt.toml
|
||||
|
||||
#
|
||||
# Generated include files
|
||||
@@ -162,3 +165,6 @@ x509.genkey
|
||||
|
||||
# Documentation toolchain
|
||||
sphinx_*/
|
||||
|
||||
# Rust analyzer configuration
|
||||
/rust-project.json
|
||||
|
||||
12
.rustfmt.toml
Normal file
12
.rustfmt.toml
Normal file
@@ -0,0 +1,12 @@
|
||||
edition = "2021"
|
||||
newline_style = "Unix"
|
||||
|
||||
# Unstable options that help catching some mistakes in formatting and that we may want to enable
|
||||
# when they become stable.
|
||||
#
|
||||
# They are kept here since they are useful to run from time to time.
|
||||
#format_code_in_doc_comments = true
|
||||
#reorder_impl_items = true
|
||||
#comment_width = 100
|
||||
#wrap_comments = true
|
||||
#normalize_comments = true
|
||||
@@ -625,6 +625,16 @@ Examples::
|
||||
%p4cc Y10 little-endian (0x20303159)
|
||||
%p4cc NV12 big-endian (0xb231564e)
|
||||
|
||||
Rust
|
||||
----
|
||||
|
||||
::
|
||||
|
||||
%pA
|
||||
|
||||
Only intended to be used from Rust code to format ``core::fmt::Arguments``.
|
||||
Do *not* use it from C.
|
||||
|
||||
Thanks
|
||||
======
|
||||
|
||||
|
||||
@@ -14,6 +14,9 @@ when it is embedded in source files.
|
||||
reasons. The kernel source contains tens of thousands of kernel-doc
|
||||
comments. Please stick to the style described here.
|
||||
|
||||
.. note:: kernel-doc does not cover Rust code: please see
|
||||
Documentation/rust/general-information.rst instead.
|
||||
|
||||
The kernel-doc structure is extracted from the comments, and proper
|
||||
`Sphinx C Domain`_ function and type descriptions with anchors are
|
||||
generated from them. The descriptions are filtered for special kernel-doc
|
||||
|
||||
@@ -58,6 +58,7 @@ Various other manuals with useful information for all kernel developers.
|
||||
trace/index
|
||||
fault-injection/index
|
||||
livepatch/index
|
||||
rust/index
|
||||
|
||||
|
||||
User-oriented documentation
|
||||
|
||||
@@ -48,6 +48,10 @@ KCFLAGS
|
||||
-------
|
||||
Additional options to the C compiler (for built-in and modules).
|
||||
|
||||
KRUSTFLAGS
|
||||
----------
|
||||
Additional options to the Rust compiler (for built-in and modules).
|
||||
|
||||
CFLAGS_KERNEL
|
||||
-------------
|
||||
Additional options for $(CC) when used to compile
|
||||
@@ -57,6 +61,15 @@ CFLAGS_MODULE
|
||||
-------------
|
||||
Additional module specific options to use for $(CC).
|
||||
|
||||
RUSTFLAGS_KERNEL
|
||||
----------------
|
||||
Additional options for $(RUSTC) when used to compile
|
||||
code that is compiled as built-in.
|
||||
|
||||
RUSTFLAGS_MODULE
|
||||
----------------
|
||||
Additional module specific options to use for $(RUSTC).
|
||||
|
||||
LDFLAGS_MODULE
|
||||
--------------
|
||||
Additional options used for $(LD) when linking modules.
|
||||
@@ -69,6 +82,10 @@ HOSTCXXFLAGS
|
||||
------------
|
||||
Additional flags to be passed to $(HOSTCXX) when building host programs.
|
||||
|
||||
HOSTRUSTFLAGS
|
||||
-------------
|
||||
Additional flags to be passed to $(HOSTRUSTC) when building host programs.
|
||||
|
||||
HOSTLDFLAGS
|
||||
-----------
|
||||
Additional flags to be passed when linking host programs.
|
||||
|
||||
@@ -29,8 +29,9 @@ This document describes the Linux kernel Makefiles.
|
||||
--- 4.1 Simple Host Program
|
||||
--- 4.2 Composite Host Programs
|
||||
--- 4.3 Using C++ for host programs
|
||||
--- 4.4 Controlling compiler options for host programs
|
||||
--- 4.5 When host programs are actually built
|
||||
--- 4.4 Using Rust for host programs
|
||||
--- 4.5 Controlling compiler options for host programs
|
||||
--- 4.6 When host programs are actually built
|
||||
|
||||
=== 5 Userspace Program support
|
||||
--- 5.1 Simple Userspace Program
|
||||
@@ -835,7 +836,24 @@ Both possibilities are described in the following.
|
||||
qconf-cxxobjs := qconf.o
|
||||
qconf-objs := check.o
|
||||
|
||||
4.4 Controlling compiler options for host programs
|
||||
4.4 Using Rust for host programs
|
||||
--------------------------------
|
||||
|
||||
Kbuild offers support for host programs written in Rust. However,
|
||||
since a Rust toolchain is not mandatory for kernel compilation,
|
||||
it may only be used in scenarios where Rust is required to be
|
||||
available (e.g. when ``CONFIG_RUST`` is enabled).
|
||||
|
||||
Example::
|
||||
|
||||
hostprogs := target
|
||||
target-rust := y
|
||||
|
||||
Kbuild will compile ``target`` using ``target.rs`` as the crate root,
|
||||
located in the same directory as the ``Makefile``. The crate may
|
||||
consist of several source files (see ``samples/rust/hostprogs``).
|
||||
|
||||
4.5 Controlling compiler options for host programs
|
||||
--------------------------------------------------
|
||||
|
||||
When compiling host programs, it is possible to set specific flags.
|
||||
@@ -867,7 +885,7 @@ Both possibilities are described in the following.
|
||||
When linking qconf, it will be passed the extra option
|
||||
"-L$(QTDIR)/lib".
|
||||
|
||||
4.5 When host programs are actually built
|
||||
4.6 When host programs are actually built
|
||||
-----------------------------------------
|
||||
|
||||
Kbuild will only build host-programs when they are referenced
|
||||
@@ -1181,6 +1199,17 @@ When kbuild executes, the following steps are followed (roughly):
|
||||
The first example utilises the trick that a config option expands
|
||||
to 'y' when selected.
|
||||
|
||||
KBUILD_RUSTFLAGS
|
||||
$(RUSTC) compiler flags
|
||||
|
||||
Default value - see top level Makefile
|
||||
Append or modify as required per architecture.
|
||||
|
||||
Often, the KBUILD_RUSTFLAGS variable depends on the configuration.
|
||||
|
||||
Note that target specification file generation (for ``--target``)
|
||||
is handled in ``scripts/generate_rust_target.rs``.
|
||||
|
||||
KBUILD_AFLAGS_KERNEL
|
||||
Assembler options specific for built-in
|
||||
|
||||
@@ -1208,6 +1237,19 @@ When kbuild executes, the following steps are followed (roughly):
|
||||
are used for $(CC).
|
||||
From commandline CFLAGS_MODULE shall be used (see kbuild.rst).
|
||||
|
||||
KBUILD_RUSTFLAGS_KERNEL
|
||||
$(RUSTC) options specific for built-in
|
||||
|
||||
$(KBUILD_RUSTFLAGS_KERNEL) contains extra Rust compiler flags used to
|
||||
compile resident kernel code.
|
||||
|
||||
KBUILD_RUSTFLAGS_MODULE
|
||||
Options for $(RUSTC) when building modules
|
||||
|
||||
$(KBUILD_RUSTFLAGS_MODULE) is used to add arch-specific options that
|
||||
are used for $(RUSTC).
|
||||
From commandline RUSTFLAGS_MODULE shall be used (see kbuild.rst).
|
||||
|
||||
KBUILD_LDFLAGS_MODULE
|
||||
Options for $(LD) when linking modules
|
||||
|
||||
|
||||
@@ -31,6 +31,8 @@ you probably needn't concern yourself with pcmciautils.
|
||||
====================== =============== ========================================
|
||||
GNU C 5.1 gcc --version
|
||||
Clang/LLVM (optional) 11.0.0 clang --version
|
||||
Rust (optional) 1.62.0 rustc --version
|
||||
bindgen (optional) 0.56.0 bindgen --version
|
||||
GNU make 3.81 make --version
|
||||
bash 4.2 bash --version
|
||||
binutils 2.23 ld -v
|
||||
@@ -80,6 +82,29 @@ kernels. Older releases aren't guaranteed to work, and we may drop workarounds
|
||||
from the kernel that were used to support older versions. Please see additional
|
||||
docs on :ref:`Building Linux with Clang/LLVM <kbuild_llvm>`.
|
||||
|
||||
Rust (optional)
|
||||
---------------
|
||||
|
||||
A particular version of the Rust toolchain is required. Newer versions may or
|
||||
may not work because the kernel depends on some unstable Rust features, for
|
||||
the moment.
|
||||
|
||||
Each Rust toolchain comes with several "components", some of which are required
|
||||
(like ``rustc``) and some that are optional. The ``rust-src`` component (which
|
||||
is optional) needs to be installed to build the kernel. Other components are
|
||||
useful for developing.
|
||||
|
||||
Please see Documentation/rust/quick-start.rst for instructions on how to
|
||||
satisfy the build requirements of Rust support. In particular, the ``Makefile``
|
||||
target ``rustavailable`` is useful to check why the Rust toolchain may not
|
||||
be detected.
|
||||
|
||||
bindgen (optional)
|
||||
------------------
|
||||
|
||||
``bindgen`` is used to generate the Rust bindings to the C side of the kernel.
|
||||
It depends on ``libclang``.
|
||||
|
||||
Make
|
||||
----
|
||||
|
||||
@@ -348,6 +373,12 @@ Sphinx
|
||||
Please see :ref:`sphinx_install` in :ref:`Documentation/doc-guide/sphinx.rst <sphinxdoc>`
|
||||
for details about Sphinx requirements.
|
||||
|
||||
rustdoc
|
||||
-------
|
||||
|
||||
``rustdoc`` is used to generate the documentation for Rust code. Please see
|
||||
Documentation/rust/general-information.rst for more information.
|
||||
|
||||
Getting updated software
|
||||
========================
|
||||
|
||||
@@ -364,6 +395,16 @@ Clang/LLVM
|
||||
|
||||
- :ref:`Getting LLVM <getting_llvm>`.
|
||||
|
||||
Rust
|
||||
----
|
||||
|
||||
- Documentation/rust/quick-start.rst.
|
||||
|
||||
bindgen
|
||||
-------
|
||||
|
||||
- Documentation/rust/quick-start.rst.
|
||||
|
||||
Make
|
||||
----
|
||||
|
||||
|
||||
19
Documentation/rust/arch-support.rst
Normal file
19
Documentation/rust/arch-support.rst
Normal file
@@ -0,0 +1,19 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
Arch Support
|
||||
============
|
||||
|
||||
Currently, the Rust compiler (``rustc``) uses LLVM for code generation,
|
||||
which limits the supported architectures that can be targeted. In addition,
|
||||
support for building the kernel with LLVM/Clang varies (please see
|
||||
Documentation/kbuild/llvm.rst). This support is needed for ``bindgen``
|
||||
which uses ``libclang``.
|
||||
|
||||
Below is a general summary of architectures that currently work. Level of
|
||||
support corresponds to ``S`` values in the ``MAINTAINERS`` file.
|
||||
|
||||
============ ================ ==============================================
|
||||
Architecture Level of support Constraints
|
||||
============ ================ ==============================================
|
||||
``x86`` Maintained ``x86_64`` only.
|
||||
============ ================ ==============================================
|
||||
216
Documentation/rust/coding-guidelines.rst
Normal file
216
Documentation/rust/coding-guidelines.rst
Normal file
@@ -0,0 +1,216 @@
|
||||
.. 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``.
|
||||
79
Documentation/rust/general-information.rst
Normal file
79
Documentation/rust/general-information.rst
Normal file
@@ -0,0 +1,79 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
General Information
|
||||
===================
|
||||
|
||||
This document contains useful information to know when working with
|
||||
the Rust support in the kernel.
|
||||
|
||||
|
||||
Code documentation
|
||||
------------------
|
||||
|
||||
Rust kernel code is documented using ``rustdoc``, its built-in documentation
|
||||
generator.
|
||||
|
||||
The generated HTML docs include integrated search, linked items (e.g. types,
|
||||
functions, constants), source code, etc. They may be read at (TODO: link when
|
||||
in mainline and generated alongside the rest of the documentation):
|
||||
|
||||
http://kernel.org/
|
||||
|
||||
The docs can also be easily generated and read locally. This is quite fast
|
||||
(same order as compiling the code itself) and no special tools or environment
|
||||
are needed. This has the added advantage that they will be tailored to
|
||||
the particular kernel configuration used. To generate them, use the ``rustdoc``
|
||||
target with the same invocation used for compilation, e.g.::
|
||||
|
||||
make LLVM=1 rustdoc
|
||||
|
||||
To read the docs locally in your web browser, run e.g.::
|
||||
|
||||
xdg-open rust/doc/kernel/index.html
|
||||
|
||||
To learn about how to write the documentation, please see coding-guidelines.rst.
|
||||
|
||||
|
||||
Extra lints
|
||||
-----------
|
||||
|
||||
While ``rustc`` is a very helpful compiler, some extra lints and analyses are
|
||||
available via ``clippy``, a Rust linter. To enable it, pass ``CLIPPY=1`` to
|
||||
the same invocation used for compilation, e.g.::
|
||||
|
||||
make LLVM=1 CLIPPY=1
|
||||
|
||||
Please note that Clippy may change code generation, thus it should not be
|
||||
enabled while building a production kernel.
|
||||
|
||||
|
||||
Abstractions vs. bindings
|
||||
-------------------------
|
||||
|
||||
Abstractions are Rust code wrapping kernel functionality from the C side.
|
||||
|
||||
In order to use functions and types from the C side, bindings are created.
|
||||
Bindings are the declarations for Rust of those functions and types from
|
||||
the C side.
|
||||
|
||||
For instance, one may write a ``Mutex`` abstraction in Rust which wraps
|
||||
a ``struct mutex`` from the C side and calls its functions through the bindings.
|
||||
|
||||
Abstractions are not available for all the kernel internal APIs and concepts,
|
||||
but it is intended that coverage is expanded as time goes on. "Leaf" modules
|
||||
(e.g. drivers) should not use the C bindings directly. Instead, subsystems
|
||||
should provide as-safe-as-possible abstractions as needed.
|
||||
|
||||
|
||||
Conditional compilation
|
||||
-----------------------
|
||||
|
||||
Rust code has access to conditional compilation based on the kernel
|
||||
configuration:
|
||||
|
||||
.. code-block:: rust
|
||||
|
||||
#[cfg(CONFIG_X)] // Enabled (`y` or `m`)
|
||||
#[cfg(CONFIG_X="y")] // Enabled as a built-in (`y`)
|
||||
#[cfg(CONFIG_X="m")] // Enabled as a module (`m`)
|
||||
#[cfg(not(CONFIG_X))] // Disabled
|
||||
22
Documentation/rust/index.rst
Normal file
22
Documentation/rust/index.rst
Normal file
@@ -0,0 +1,22 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
Rust
|
||||
====
|
||||
|
||||
Documentation related to Rust within the kernel. To start using Rust
|
||||
in the kernel, please read the quick-start.rst guide.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
quick-start
|
||||
general-information
|
||||
coding-guidelines
|
||||
arch-support
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
Indices
|
||||
=======
|
||||
|
||||
* :ref:`genindex`
|
||||
232
Documentation/rust/quick-start.rst
Normal file
232
Documentation/rust/quick-start.rst
Normal file
@@ -0,0 +1,232 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
Quick Start
|
||||
===========
|
||||
|
||||
This document describes how to get started with kernel development in Rust.
|
||||
|
||||
|
||||
Requirements: Building
|
||||
----------------------
|
||||
|
||||
This section explains how to fetch the tools needed for building.
|
||||
|
||||
Some of these requirements might be available from Linux distributions
|
||||
under names like ``rustc``, ``rust-src``, ``rust-bindgen``, etc. However,
|
||||
at the time of writing, they are likely not to be recent enough unless
|
||||
the distribution tracks the latest releases.
|
||||
|
||||
To easily check whether the requirements are met, the following target
|
||||
can be used::
|
||||
|
||||
make LLVM=1 rustavailable
|
||||
|
||||
This triggers the same logic used by Kconfig to determine whether
|
||||
``RUST_IS_AVAILABLE`` should be enabled; but it also explains why not
|
||||
if that is the case.
|
||||
|
||||
|
||||
rustc
|
||||
*****
|
||||
|
||||
A particular version of the Rust compiler is required. Newer versions may or
|
||||
may not work because, for the moment, the kernel depends on some unstable
|
||||
Rust features.
|
||||
|
||||
If ``rustup`` is being used, enter the checked out source code directory
|
||||
and run::
|
||||
|
||||
rustup override set $(scripts/min-tool-version.sh rustc)
|
||||
|
||||
Otherwise, fetch a standalone installer or install ``rustup`` from:
|
||||
|
||||
https://www.rust-lang.org
|
||||
|
||||
|
||||
Rust standard library source
|
||||
****************************
|
||||
|
||||
The Rust standard library source is required because the build system will
|
||||
cross-compile ``core`` and ``alloc``.
|
||||
|
||||
If ``rustup`` is being used, run::
|
||||
|
||||
rustup component add rust-src
|
||||
|
||||
The components are installed per toolchain, thus upgrading the Rust compiler
|
||||
version later on requires re-adding the component.
|
||||
|
||||
Otherwise, if a standalone installer is used, the Rust repository may be cloned
|
||||
into the installation folder of the toolchain::
|
||||
|
||||
git clone --recurse-submodules \
|
||||
--branch $(scripts/min-tool-version.sh rustc) \
|
||||
https://github.com/rust-lang/rust \
|
||||
$(rustc --print sysroot)/lib/rustlib/src/rust
|
||||
|
||||
In this case, upgrading the Rust compiler version later on requires manually
|
||||
updating this clone.
|
||||
|
||||
|
||||
libclang
|
||||
********
|
||||
|
||||
``libclang`` (part of LLVM) is used by ``bindgen`` to understand the C code
|
||||
in the kernel, which means LLVM needs to be installed; like when the kernel
|
||||
is compiled with ``CC=clang`` or ``LLVM=1``.
|
||||
|
||||
Linux distributions are likely to have a suitable one available, so it is
|
||||
best to check that first.
|
||||
|
||||
There are also some binaries for several systems and architectures uploaded at:
|
||||
|
||||
https://releases.llvm.org/download.html
|
||||
|
||||
Otherwise, building LLVM takes quite a while, but it is not a complex process:
|
||||
|
||||
https://llvm.org/docs/GettingStarted.html#getting-the-source-code-and-building-llvm
|
||||
|
||||
Please see Documentation/kbuild/llvm.rst for more information and further ways
|
||||
to fetch pre-built releases and distribution packages.
|
||||
|
||||
|
||||
bindgen
|
||||
*******
|
||||
|
||||
The bindings to the C side of the kernel are generated at build time using
|
||||
the ``bindgen`` tool. A particular version is required.
|
||||
|
||||
Install it via (note that this will download and build the tool from source)::
|
||||
|
||||
cargo install --locked --version $(scripts/min-tool-version.sh bindgen) bindgen
|
||||
|
||||
|
||||
Requirements: Developing
|
||||
------------------------
|
||||
|
||||
This section explains how to fetch the tools needed for developing. That is,
|
||||
they are not needed when just building the kernel.
|
||||
|
||||
|
||||
rustfmt
|
||||
*******
|
||||
|
||||
The ``rustfmt`` tool is used to automatically format all the Rust kernel code,
|
||||
including the generated C bindings (for details, please see
|
||||
coding-guidelines.rst).
|
||||
|
||||
If ``rustup`` is being used, its ``default`` profile already installs the tool,
|
||||
thus nothing needs to be done. If another profile is being used, the component
|
||||
can be installed manually::
|
||||
|
||||
rustup component add rustfmt
|
||||
|
||||
The standalone installers also come with ``rustfmt``.
|
||||
|
||||
|
||||
clippy
|
||||
******
|
||||
|
||||
``clippy`` is a Rust linter. Running it provides extra warnings for Rust code.
|
||||
It can be run by passing ``CLIPPY=1`` to ``make`` (for details, please see
|
||||
general-information.rst).
|
||||
|
||||
If ``rustup`` is being used, its ``default`` profile already installs the tool,
|
||||
thus nothing needs to be done. If another profile is being used, the component
|
||||
can be installed manually::
|
||||
|
||||
rustup component add clippy
|
||||
|
||||
The standalone installers also come with ``clippy``.
|
||||
|
||||
|
||||
cargo
|
||||
*****
|
||||
|
||||
``cargo`` is the Rust native build system. It is currently required to run
|
||||
the tests since it is used to build a custom standard library that contains
|
||||
the facilities provided by the custom ``alloc`` in the kernel. The tests can
|
||||
be run using the ``rusttest`` Make target.
|
||||
|
||||
If ``rustup`` is being used, all the profiles already install the tool,
|
||||
thus nothing needs to be done.
|
||||
|
||||
The standalone installers also come with ``cargo``.
|
||||
|
||||
|
||||
rustdoc
|
||||
*******
|
||||
|
||||
``rustdoc`` is the documentation tool for Rust. It generates pretty HTML
|
||||
documentation for Rust code (for details, please see
|
||||
general-information.rst).
|
||||
|
||||
``rustdoc`` is also used to test the examples provided in documented Rust code
|
||||
(called doctests or documentation tests). The ``rusttest`` Make target uses
|
||||
this feature.
|
||||
|
||||
If ``rustup`` is being used, all the profiles already install the tool,
|
||||
thus nothing needs to be done.
|
||||
|
||||
The standalone installers also come with ``rustdoc``.
|
||||
|
||||
|
||||
rust-analyzer
|
||||
*************
|
||||
|
||||
The `rust-analyzer <https://rust-analyzer.github.io/>`_ language server can
|
||||
be used with many editors to enable syntax highlighting, completion, go to
|
||||
definition, and other features.
|
||||
|
||||
``rust-analyzer`` needs a configuration file, ``rust-project.json``, which
|
||||
can be generated by the ``rust-analyzer`` Make target.
|
||||
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
``Rust support`` (``CONFIG_RUST``) needs to be enabled in the ``General setup``
|
||||
menu. The option is only shown if a suitable Rust toolchain is found (see
|
||||
above), as long as the other requirements are met. In turn, this will make
|
||||
visible the rest of options that depend on Rust.
|
||||
|
||||
Afterwards, go to::
|
||||
|
||||
Kernel hacking
|
||||
-> Sample kernel code
|
||||
-> Rust samples
|
||||
|
||||
And enable some sample modules either as built-in or as loadable.
|
||||
|
||||
|
||||
Building
|
||||
--------
|
||||
|
||||
Building a kernel with a complete LLVM toolchain is the best supported setup
|
||||
at the moment. That is::
|
||||
|
||||
make LLVM=1
|
||||
|
||||
For architectures that do not support a full LLVM toolchain, use::
|
||||
|
||||
make CC=clang
|
||||
|
||||
Using GCC also works for some configurations, but it is very experimental at
|
||||
the moment.
|
||||
|
||||
|
||||
Hacking
|
||||
-------
|
||||
|
||||
To dive deeper, take a look at the source code of the samples
|
||||
at ``samples/rust/``, the Rust support code under ``rust/`` and
|
||||
the ``Rust hacking`` menu under ``Kernel hacking``.
|
||||
|
||||
If GDB/Binutils is used and Rust symbols are not getting demangled, the reason
|
||||
is the toolchain does not support Rust's new v0 mangling scheme yet.
|
||||
There are a few ways out:
|
||||
|
||||
- Install a newer release (GDB >= 10.2, Binutils >= 2.36).
|
||||
|
||||
- Some versions of GDB (e.g. vanilla GDB 10.1) are able to use
|
||||
the pre-demangled names embedded in the debug info (``CONFIG_DEBUG_INFO``).
|
||||
18
MAINTAINERS
18
MAINTAINERS
@@ -17755,6 +17755,24 @@ F: include/rv/
|
||||
F: kernel/trace/rv/
|
||||
F: tools/verification/
|
||||
|
||||
RUST
|
||||
M: Miguel Ojeda <ojeda@kernel.org>
|
||||
M: Alex Gaynor <alex.gaynor@gmail.com>
|
||||
M: Wedson Almeida Filho <wedsonaf@gmail.com>
|
||||
R: Boqun Feng <boqun.feng@gmail.com>
|
||||
R: Gary Guo <gary@garyguo.net>
|
||||
R: Björn Roy Baron <bjorn3_gh@protonmail.com>
|
||||
L: rust-for-linux@vger.kernel.org
|
||||
S: Supported
|
||||
W: https://github.com/Rust-for-Linux/linux
|
||||
B: https://github.com/Rust-for-Linux/linux/issues
|
||||
T: git https://github.com/Rust-for-Linux/linux.git rust-next
|
||||
F: Documentation/rust/
|
||||
F: rust/
|
||||
F: samples/rust/
|
||||
F: scripts/*rust*
|
||||
K: \b(?i:rust)\b
|
||||
|
||||
RXRPC SOCKETS (AF_RXRPC)
|
||||
M: David Howells <dhowells@redhat.com>
|
||||
M: Marc Dionne <marc.dionne@auristor.com>
|
||||
|
||||
172
Makefile
172
Makefile
@@ -120,6 +120,15 @@ endif
|
||||
|
||||
export KBUILD_CHECKSRC
|
||||
|
||||
# Enable "clippy" (a linter) as part of the Rust compilation.
|
||||
#
|
||||
# Use 'make CLIPPY=1' to enable it.
|
||||
ifeq ("$(origin CLIPPY)", "command line")
|
||||
KBUILD_CLIPPY := $(CLIPPY)
|
||||
endif
|
||||
|
||||
export KBUILD_CLIPPY
|
||||
|
||||
# Use make M=dir or set the environment variable KBUILD_EXTMOD to specify the
|
||||
# directory of external module to build. Setting M= takes precedence.
|
||||
ifeq ("$(origin M)", "command line")
|
||||
@@ -270,14 +279,14 @@ no-dot-config-targets := $(clean-targets) \
|
||||
cscope gtags TAGS tags help% %docs check% coccicheck \
|
||||
$(version_h) headers headers_% archheaders archscripts \
|
||||
%asm-generic kernelversion %src-pkg dt_binding_check \
|
||||
outputmakefile
|
||||
outputmakefile rustavailable rustfmt rustfmtcheck
|
||||
# Installation targets should not require compiler. Unfortunately, vdso_install
|
||||
# is an exception where build artifacts may be updated. This must be fixed.
|
||||
no-compiler-targets := $(no-dot-config-targets) install dtbs_install \
|
||||
headers_install modules_install kernelrelease image_name
|
||||
no-sync-config-targets := $(no-dot-config-targets) %install kernelrelease \
|
||||
image_name
|
||||
single-targets := %.a %.i %.ko %.lds %.ll %.lst %.mod %.o %.s %.symtypes %/
|
||||
single-targets := %.a %.i %.rsi %.ko %.lds %.ll %.lst %.mod %.o %.s %.symtypes %/
|
||||
|
||||
config-build :=
|
||||
mixed-build :=
|
||||
@@ -439,6 +448,7 @@ else
|
||||
HOSTCC = gcc
|
||||
HOSTCXX = g++
|
||||
endif
|
||||
HOSTRUSTC = rustc
|
||||
HOSTPKG_CONFIG = pkg-config
|
||||
|
||||
KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
|
||||
@@ -447,8 +457,26 @@ KBUILD_USERHOSTCFLAGS := -Wall -Wmissing-prototypes -Wstrict-prototypes \
|
||||
KBUILD_USERCFLAGS := $(KBUILD_USERHOSTCFLAGS) $(USERCFLAGS)
|
||||
KBUILD_USERLDFLAGS := $(USERLDFLAGS)
|
||||
|
||||
# These flags apply to all Rust code in the tree, including the kernel and
|
||||
# host programs.
|
||||
export rust_common_flags := --edition=2021 \
|
||||
-Zbinary_dep_depinfo=y \
|
||||
-Dunsafe_op_in_unsafe_fn -Drust_2018_idioms \
|
||||
-Dunreachable_pub -Dnon_ascii_idents \
|
||||
-Wmissing_docs \
|
||||
-Drustdoc::missing_crate_level_docs \
|
||||
-Dclippy::correctness -Dclippy::style \
|
||||
-Dclippy::suspicious -Dclippy::complexity \
|
||||
-Dclippy::perf \
|
||||
-Dclippy::let_unit_value -Dclippy::mut_mut \
|
||||
-Dclippy::needless_bitwise_bool \
|
||||
-Dclippy::needless_continue \
|
||||
-Wclippy::dbg_macro
|
||||
|
||||
KBUILD_HOSTCFLAGS := $(KBUILD_USERHOSTCFLAGS) $(HOST_LFS_CFLAGS) $(HOSTCFLAGS)
|
||||
KBUILD_HOSTCXXFLAGS := -Wall -O2 $(HOST_LFS_CFLAGS) $(HOSTCXXFLAGS)
|
||||
KBUILD_HOSTRUSTFLAGS := $(rust_common_flags) -O -Cstrip=debuginfo \
|
||||
-Zallow-features= $(HOSTRUSTFLAGS)
|
||||
KBUILD_HOSTLDFLAGS := $(HOST_LFS_LDFLAGS) $(HOSTLDFLAGS)
|
||||
KBUILD_HOSTLDLIBS := $(HOST_LFS_LIBS) $(HOSTLDLIBS)
|
||||
|
||||
@@ -473,6 +501,12 @@ OBJDUMP = $(CROSS_COMPILE)objdump
|
||||
READELF = $(CROSS_COMPILE)readelf
|
||||
STRIP = $(CROSS_COMPILE)strip
|
||||
endif
|
||||
RUSTC = rustc
|
||||
RUSTDOC = rustdoc
|
||||
RUSTFMT = rustfmt
|
||||
CLIPPY_DRIVER = clippy-driver
|
||||
BINDGEN = bindgen
|
||||
CARGO = cargo
|
||||
PAHOLE = pahole
|
||||
RESOLVE_BTFIDS = $(objtree)/tools/bpf/resolve_btfids/resolve_btfids
|
||||
LEX = flex
|
||||
@@ -498,9 +532,11 @@ CHECKFLAGS := -D__linux__ -Dlinux -D__STDC__ -Dunix -D__unix__ \
|
||||
-Wbitwise -Wno-return-void -Wno-unknown-attribute $(CF)
|
||||
NOSTDINC_FLAGS :=
|
||||
CFLAGS_MODULE =
|
||||
RUSTFLAGS_MODULE =
|
||||
AFLAGS_MODULE =
|
||||
LDFLAGS_MODULE =
|
||||
CFLAGS_KERNEL =
|
||||
RUSTFLAGS_KERNEL =
|
||||
AFLAGS_KERNEL =
|
||||
LDFLAGS_vmlinux =
|
||||
|
||||
@@ -529,15 +565,43 @@ KBUILD_CFLAGS := -Wall -Wundef -Werror=strict-prototypes -Wno-trigraphs \
|
||||
-Werror=return-type -Wno-format-security \
|
||||
-std=gnu11
|
||||
KBUILD_CPPFLAGS := -D__KERNEL__
|
||||
KBUILD_RUSTFLAGS := $(rust_common_flags) \
|
||||
--target=$(objtree)/rust/target.json \
|
||||
-Cpanic=abort -Cembed-bitcode=n -Clto=n \
|
||||
-Cforce-unwind-tables=n -Ccodegen-units=1 \
|
||||
-Csymbol-mangling-version=v0 \
|
||||
-Crelocation-model=static \
|
||||
-Zfunction-sections=n \
|
||||
-Dclippy::float_arithmetic
|
||||
|
||||
KBUILD_AFLAGS_KERNEL :=
|
||||
KBUILD_CFLAGS_KERNEL :=
|
||||
KBUILD_RUSTFLAGS_KERNEL :=
|
||||
KBUILD_AFLAGS_MODULE := -DMODULE
|
||||
KBUILD_CFLAGS_MODULE := -DMODULE
|
||||
KBUILD_RUSTFLAGS_MODULE := --cfg MODULE
|
||||
KBUILD_LDFLAGS_MODULE :=
|
||||
KBUILD_LDFLAGS :=
|
||||
CLANG_FLAGS :=
|
||||
|
||||
ifeq ($(KBUILD_CLIPPY),1)
|
||||
RUSTC_OR_CLIPPY_QUIET := CLIPPY
|
||||
RUSTC_OR_CLIPPY = $(CLIPPY_DRIVER)
|
||||
else
|
||||
RUSTC_OR_CLIPPY_QUIET := RUSTC
|
||||
RUSTC_OR_CLIPPY = $(RUSTC)
|
||||
endif
|
||||
|
||||
ifdef RUST_LIB_SRC
|
||||
export RUST_LIB_SRC
|
||||
endif
|
||||
|
||||
# Allows the usage of unstable features in stable compilers.
|
||||
export RUSTC_BOOTSTRAP := 1
|
||||
|
||||
export ARCH SRCARCH CONFIG_SHELL BASH HOSTCC KBUILD_HOSTCFLAGS CROSS_COMPILE LD CC HOSTPKG_CONFIG
|
||||
export RUSTC RUSTDOC RUSTFMT RUSTC_OR_CLIPPY_QUIET RUSTC_OR_CLIPPY BINDGEN CARGO
|
||||
export HOSTRUSTC KBUILD_HOSTRUSTFLAGS
|
||||
export CPP AR NM STRIP OBJCOPY OBJDUMP READELF PAHOLE RESOLVE_BTFIDS LEX YACC AWK INSTALLKERNEL
|
||||
export PERL PYTHON3 CHECK CHECKFLAGS MAKE UTS_MACHINE HOSTCXX
|
||||
export KGZIP KBZIP2 KLZOP LZMA LZ4 XZ ZSTD
|
||||
@@ -546,9 +610,10 @@ export KBUILD_USERCFLAGS KBUILD_USERLDFLAGS
|
||||
|
||||
export KBUILD_CPPFLAGS NOSTDINC_FLAGS LINUXINCLUDE OBJCOPYFLAGS KBUILD_LDFLAGS
|
||||
export KBUILD_CFLAGS CFLAGS_KERNEL CFLAGS_MODULE
|
||||
export KBUILD_RUSTFLAGS RUSTFLAGS_KERNEL RUSTFLAGS_MODULE
|
||||
export KBUILD_AFLAGS AFLAGS_KERNEL AFLAGS_MODULE
|
||||
export KBUILD_AFLAGS_MODULE KBUILD_CFLAGS_MODULE KBUILD_LDFLAGS_MODULE
|
||||
export KBUILD_AFLAGS_KERNEL KBUILD_CFLAGS_KERNEL
|
||||
export KBUILD_AFLAGS_MODULE KBUILD_CFLAGS_MODULE KBUILD_RUSTFLAGS_MODULE KBUILD_LDFLAGS_MODULE
|
||||
export KBUILD_AFLAGS_KERNEL KBUILD_CFLAGS_KERNEL KBUILD_RUSTFLAGS_KERNEL
|
||||
export PAHOLE_FLAGS
|
||||
|
||||
# Files to ignore in find ... statements
|
||||
@@ -729,7 +794,7 @@ $(KCONFIG_CONFIG):
|
||||
#
|
||||
# Do not use $(call cmd,...) here. That would suppress prompts from syncconfig,
|
||||
# so you cannot notice that Kconfig is waiting for the user input.
|
||||
%/config/auto.conf %/config/auto.conf.cmd %/generated/autoconf.h: $(KCONFIG_CONFIG)
|
||||
%/config/auto.conf %/config/auto.conf.cmd %/generated/autoconf.h %/generated/rustc_cfg: $(KCONFIG_CONFIG)
|
||||
$(Q)$(kecho) " SYNC $@"
|
||||
$(Q)$(MAKE) -f $(srctree)/Makefile syncconfig
|
||||
else # !may-sync-config
|
||||
@@ -758,10 +823,17 @@ KBUILD_CFLAGS += $(call cc-disable-warning, address-of-packed-member)
|
||||
|
||||
ifdef CONFIG_CC_OPTIMIZE_FOR_PERFORMANCE
|
||||
KBUILD_CFLAGS += -O2
|
||||
KBUILD_RUSTFLAGS += -Copt-level=2
|
||||
else ifdef CONFIG_CC_OPTIMIZE_FOR_SIZE
|
||||
KBUILD_CFLAGS += -Os
|
||||
KBUILD_RUSTFLAGS += -Copt-level=s
|
||||
endif
|
||||
|
||||
# Always set `debug-assertions` and `overflow-checks` because their default
|
||||
# depends on `opt-level` and `debug-assertions`, respectively.
|
||||
KBUILD_RUSTFLAGS += -Cdebug-assertions=$(if $(CONFIG_RUST_DEBUG_ASSERTIONS),y,n)
|
||||
KBUILD_RUSTFLAGS += -Coverflow-checks=$(if $(CONFIG_RUST_OVERFLOW_CHECKS),y,n)
|
||||
|
||||
# Tell gcc to never replace conditional load with a non-conditional one
|
||||
ifdef CONFIG_CC_IS_GCC
|
||||
# gcc-10 renamed --param=allow-store-data-races=0 to
|
||||
@@ -792,6 +864,9 @@ KBUILD_CFLAGS-$(CONFIG_WERROR) += -Werror
|
||||
KBUILD_CFLAGS-$(CONFIG_CC_NO_ARRAY_BOUNDS) += -Wno-array-bounds
|
||||
KBUILD_CFLAGS += $(KBUILD_CFLAGS-y) $(CONFIG_CC_IMPLICIT_FALLTHROUGH)
|
||||
|
||||
KBUILD_RUSTFLAGS-$(CONFIG_WERROR) += -Dwarnings
|
||||
KBUILD_RUSTFLAGS += $(KBUILD_RUSTFLAGS-y)
|
||||
|
||||
ifdef CONFIG_CC_IS_CLANG
|
||||
KBUILD_CPPFLAGS += -Qunused-arguments
|
||||
# The kernel builds with '-std=gnu11' so use of GNU extensions is acceptable.
|
||||
@@ -812,12 +887,15 @@ KBUILD_CFLAGS += $(call cc-disable-warning, dangling-pointer)
|
||||
|
||||
ifdef CONFIG_FRAME_POINTER
|
||||
KBUILD_CFLAGS += -fno-omit-frame-pointer -fno-optimize-sibling-calls
|
||||
KBUILD_RUSTFLAGS += -Cforce-frame-pointers=y
|
||||
else
|
||||
# Some targets (ARM with Thumb2, for example), can't be built with frame
|
||||
# pointers. For those, we don't have FUNCTION_TRACER automatically
|
||||
# select FRAME_POINTER. However, FUNCTION_TRACER adds -pg, and this is
|
||||
# incompatible with -fomit-frame-pointer with current GCC, so we don't use
|
||||
# -fomit-frame-pointer with FUNCTION_TRACER.
|
||||
# In the Rust target specification, "frame-pointer" is set explicitly
|
||||
# to "may-omit".
|
||||
ifndef CONFIG_FUNCTION_TRACER
|
||||
KBUILD_CFLAGS += -fomit-frame-pointer
|
||||
endif
|
||||
@@ -882,8 +960,10 @@ ifdef CONFIG_DEBUG_SECTION_MISMATCH
|
||||
KBUILD_CFLAGS += -fno-inline-functions-called-once
|
||||
endif
|
||||
|
||||
# `rustc`'s `-Zfunction-sections` applies to data too (as of 1.59.0).
|
||||
ifdef CONFIG_LD_DEAD_CODE_DATA_ELIMINATION
|
||||
KBUILD_CFLAGS_KERNEL += -ffunction-sections -fdata-sections
|
||||
KBUILD_RUSTFLAGS_KERNEL += -Zfunction-sections=y
|
||||
LDFLAGS_vmlinux += --gc-sections
|
||||
endif
|
||||
|
||||
@@ -1026,10 +1106,11 @@ include $(addprefix $(srctree)/, $(include-y))
|
||||
# Do not add $(call cc-option,...) below this line. When you build the kernel
|
||||
# from the clean source tree, the GCC plugins do not exist at this point.
|
||||
|
||||
# Add user supplied CPPFLAGS, AFLAGS and CFLAGS as the last assignments
|
||||
# Add user supplied CPPFLAGS, AFLAGS, CFLAGS and RUSTFLAGS as the last assignments
|
||||
KBUILD_CPPFLAGS += $(KCPPFLAGS)
|
||||
KBUILD_AFLAGS += $(KAFLAGS)
|
||||
KBUILD_CFLAGS += $(KCFLAGS)
|
||||
KBUILD_RUSTFLAGS += $(KRUSTFLAGS)
|
||||
|
||||
KBUILD_LDFLAGS_MODULE += --build-id=sha1
|
||||
LDFLAGS_vmlinux += --build-id=sha1
|
||||
@@ -1104,6 +1185,7 @@ ifeq ($(KBUILD_EXTMOD),)
|
||||
core-y += kernel/ certs/ mm/ fs/ ipc/ security/ crypto/
|
||||
core-$(CONFIG_BLOCK) += block/
|
||||
core-$(CONFIG_IO_URING) += io_uring/
|
||||
core-$(CONFIG_RUST) += rust/
|
||||
|
||||
vmlinux-dirs := $(patsubst %/,%,$(filter %/, \
|
||||
$(core-y) $(core-m) $(drivers-y) $(drivers-m) \
|
||||
@@ -1206,6 +1288,10 @@ prepare0: archprepare
|
||||
|
||||
# All the preparing..
|
||||
prepare: prepare0
|
||||
ifdef CONFIG_RUST
|
||||
$(Q)$(CONFIG_SHELL) $(srctree)/scripts/rust_is_available.sh -v
|
||||
$(Q)$(MAKE) $(build)=rust
|
||||
endif
|
||||
|
||||
PHONY += remove-stale-files
|
||||
remove-stale-files:
|
||||
@@ -1499,7 +1585,7 @@ endif # CONFIG_MODULES
|
||||
# Directories & files removed with 'make clean'
|
||||
CLEAN_FILES += include/ksym vmlinux.symvers modules-only.symvers \
|
||||
modules.builtin modules.builtin.modinfo modules.nsdeps \
|
||||
compile_commands.json .thinlto-cache
|
||||
compile_commands.json .thinlto-cache rust/test rust/doc
|
||||
|
||||
# Directories & files removed with 'make mrproper'
|
||||
MRPROPER_FILES += include/config include/generated \
|
||||
@@ -1510,7 +1596,8 @@ MRPROPER_FILES += include/config include/generated \
|
||||
certs/signing_key.pem \
|
||||
certs/x509.genkey \
|
||||
vmlinux-gdb.py \
|
||||
*.spec
|
||||
*.spec \
|
||||
rust/target.json rust/libmacros.so
|
||||
|
||||
# clean - Delete most, but leave enough to build external modules
|
||||
#
|
||||
@@ -1535,6 +1622,9 @@ $(mrproper-dirs):
|
||||
|
||||
mrproper: clean $(mrproper-dirs)
|
||||
$(call cmd,rmfiles)
|
||||
@find . $(RCS_FIND_IGNORE) \
|
||||
\( -name '*.rmeta' \) \
|
||||
-type f -print | xargs rm -f
|
||||
|
||||
# distclean
|
||||
#
|
||||
@@ -1622,6 +1712,24 @@ help:
|
||||
@echo ' kselftest-merge - Merge all the config dependencies of'
|
||||
@echo ' kselftest to existing .config.'
|
||||
@echo ''
|
||||
@echo 'Rust targets:'
|
||||
@echo ' rustavailable - Checks whether the Rust toolchain is'
|
||||
@echo ' available and, if not, explains why.'
|
||||
@echo ' rustfmt - Reformat all the Rust code in the kernel'
|
||||
@echo ' rustfmtcheck - Checks if all the Rust code in the kernel'
|
||||
@echo ' is formatted, printing a diff otherwise.'
|
||||
@echo ' rustdoc - Generate Rust documentation'
|
||||
@echo ' (requires kernel .config)'
|
||||
@echo ' rusttest - Runs the Rust tests'
|
||||
@echo ' (requires kernel .config; downloads external repos)'
|
||||
@echo ' rust-analyzer - Generate rust-project.json rust-analyzer support file'
|
||||
@echo ' (requires kernel .config)'
|
||||
@echo ' dir/file.[os] - Build specified target only'
|
||||
@echo ' dir/file.rsi - Build macro expanded source, similar to C preprocessing.'
|
||||
@echo ' Run with RUSTFMT=n to skip reformatting if needed.'
|
||||
@echo ' The output is not intended to be compilable.'
|
||||
@echo ' dir/file.ll - Build the LLVM assembly file'
|
||||
@echo ''
|
||||
@$(if $(dtstree), \
|
||||
echo 'Devicetree:'; \
|
||||
echo '* dtbs - Build device tree blobs for enabled boards'; \
|
||||
@@ -1694,6 +1802,52 @@ PHONY += $(DOC_TARGETS)
|
||||
$(DOC_TARGETS):
|
||||
$(Q)$(MAKE) $(build)=Documentation $@
|
||||
|
||||
|
||||
# Rust targets
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
# "Is Rust available?" target
|
||||
PHONY += rustavailable
|
||||
rustavailable:
|
||||
$(Q)$(CONFIG_SHELL) $(srctree)/scripts/rust_is_available.sh -v && echo "Rust is available!"
|
||||
|
||||
# Documentation target
|
||||
#
|
||||
# Using the singular to avoid running afoul of `no-dot-config-targets`.
|
||||
PHONY += rustdoc
|
||||
rustdoc: prepare
|
||||
$(Q)$(MAKE) $(build)=rust $@
|
||||
|
||||
# Testing target
|
||||
PHONY += rusttest
|
||||
rusttest: prepare
|
||||
$(Q)$(MAKE) $(build)=rust $@
|
||||
|
||||
# Formatting targets
|
||||
PHONY += rustfmt rustfmtcheck
|
||||
|
||||
# We skip `rust/alloc` since we want to minimize the diff w.r.t. upstream.
|
||||
#
|
||||
# We match using absolute paths since `find` does not resolve them
|
||||
# when matching, which is a problem when e.g. `srctree` is `..`.
|
||||
# We `grep` afterwards in order to remove the directory entry itself.
|
||||
rustfmt:
|
||||
$(Q)find $(abs_srctree) -type f -name '*.rs' \
|
||||
-o -path $(abs_srctree)/rust/alloc -prune \
|
||||
-o -path $(abs_objtree)/rust/test -prune \
|
||||
| grep -Fv $(abs_srctree)/rust/alloc \
|
||||
| grep -Fv $(abs_objtree)/rust/test \
|
||||
| grep -Fv generated \
|
||||
| xargs $(RUSTFMT) $(rustfmt_flags)
|
||||
|
||||
rustfmtcheck: rustfmt_flags = --check
|
||||
rustfmtcheck: rustfmt
|
||||
|
||||
# IDE support targets
|
||||
PHONY += rust-analyzer
|
||||
rust-analyzer:
|
||||
$(Q)$(MAKE) $(build)=rust $@
|
||||
|
||||
# Misc
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
@@ -1861,7 +2015,7 @@ $(clean-dirs):
|
||||
clean: $(clean-dirs)
|
||||
$(call cmd,rmfiles)
|
||||
@find $(or $(KBUILD_EXTMOD), .) $(RCS_FIND_IGNORE) \
|
||||
\( -name '*.[aios]' -o -name '*.ko' -o -name '.*.cmd' \
|
||||
\( -name '*.[aios]' -o -name '*.rsi' -o -name '*.ko' -o -name '.*.cmd' \
|
||||
-o -name '*.ko.*' \
|
||||
-o -name '*.dtb' -o -name '*.dtbo' -o -name '*.dtb.S' -o -name '*.dt.yaml' \
|
||||
-o -name '*.dwo' -o -name '*.lst' \
|
||||
|
||||
@@ -355,6 +355,12 @@ config HAVE_RSEQ
|
||||
This symbol should be selected by an architecture if it
|
||||
supports an implementation of restartable sequences.
|
||||
|
||||
config HAVE_RUST
|
||||
bool
|
||||
help
|
||||
This symbol should be selected by an architecture if it
|
||||
supports Rust.
|
||||
|
||||
config HAVE_FUNCTION_ARG_ACCESS_API
|
||||
bool
|
||||
help
|
||||
|
||||
@@ -257,6 +257,7 @@ config X86
|
||||
select HAVE_STATIC_CALL_INLINE if HAVE_OBJTOOL
|
||||
select HAVE_PREEMPT_DYNAMIC_CALL
|
||||
select HAVE_RSEQ
|
||||
select HAVE_RUST if X86_64
|
||||
select HAVE_SYSCALL_TRACEPOINTS
|
||||
select HAVE_UACCESS_VALIDATION if HAVE_OBJTOOL
|
||||
select HAVE_UNSTABLE_SCHED_CLOCK
|
||||
|
||||
@@ -68,6 +68,7 @@ export BITS
|
||||
# https://gcc.gnu.org/bugzilla/show_bug.cgi?id=53383
|
||||
#
|
||||
KBUILD_CFLAGS += -mno-sse -mno-mmx -mno-sse2 -mno-3dnow -mno-avx
|
||||
KBUILD_RUSTFLAGS += -Ctarget-feature=-sse,-sse2,-sse3,-ssse3,-sse4.1,-sse4.2,-avx,-avx2
|
||||
|
||||
ifeq ($(CONFIG_X86_KERNEL_IBT),y)
|
||||
#
|
||||
@@ -155,8 +156,17 @@ else
|
||||
cflags-$(CONFIG_GENERIC_CPU) += -mtune=generic
|
||||
KBUILD_CFLAGS += $(cflags-y)
|
||||
|
||||
rustflags-$(CONFIG_MK8) += -Ctarget-cpu=k8
|
||||
rustflags-$(CONFIG_MPSC) += -Ctarget-cpu=nocona
|
||||
rustflags-$(CONFIG_MCORE2) += -Ctarget-cpu=core2
|
||||
rustflags-$(CONFIG_MATOM) += -Ctarget-cpu=atom
|
||||
rustflags-$(CONFIG_GENERIC_CPU) += -Ztune-cpu=generic
|
||||
KBUILD_RUSTFLAGS += $(rustflags-y)
|
||||
|
||||
KBUILD_CFLAGS += -mno-red-zone
|
||||
KBUILD_CFLAGS += -mcmodel=kernel
|
||||
KBUILD_RUSTFLAGS += -Cno-redzone=y
|
||||
KBUILD_RUSTFLAGS += -Ccode-model=kernel
|
||||
endif
|
||||
|
||||
#
|
||||
|
||||
@@ -4,8 +4,12 @@
|
||||
|
||||
#ifndef __ASSEMBLY__
|
||||
|
||||
/*
|
||||
* Skipped when running bindgen due to a libclang issue;
|
||||
* see https://github.com/rust-lang/rust-bindgen/issues/2244.
|
||||
*/
|
||||
#if defined(CONFIG_DEBUG_INFO_BTF) && defined(CONFIG_PAHOLE_HAS_BTF_TAG) && \
|
||||
__has_attribute(btf_type_tag)
|
||||
__has_attribute(btf_type_tag) && !defined(__BINDGEN__)
|
||||
# define BTF_TYPE_TAG(value) __attribute__((btf_type_tag(#value)))
|
||||
#else
|
||||
# define BTF_TYPE_TAG(value) /* nothing */
|
||||
|
||||
@@ -15,7 +15,7 @@
|
||||
|
||||
#include <asm/sections.h>
|
||||
|
||||
#define KSYM_NAME_LEN 128
|
||||
#define KSYM_NAME_LEN 512
|
||||
#define KSYM_SYMBOL_LEN (sizeof("%s+%#lx/%#lx [%s %s]") + \
|
||||
(KSYM_NAME_LEN - 1) + \
|
||||
2*(BITS_PER_LONG*3/10) + (MODULE_NAME_LEN - 1) + \
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user