diff --git a/Documentation/rust/coding.rst b/Documentation/rust/coding.rst new file mode 100644 index 00000000000000..d0d73bfa66436b --- /dev/null +++ b/Documentation/rust/coding.rst @@ -0,0 +1,41 @@ +.. _rust_coding: + +Coding +====== + +This document describes how to write Rust code in the kernel. + + +Coding style +------------ + +For the moment, we are following the idiomatic Rust style. For instance, +we use 4 spaces for indentation rather than tabs. + + +Abstractions vs. bindings +------------------------- + +We don't have abstractions for all the kernel internal APIs and concepts, +but we would like to expand coverage as time goes on. Unless there is +a good reason not to, always use the abstractions instead of calling +the C bindings directly. + +If you are writing some code that requires a call to an internal kernel API +or concept that isn't abstracted yet, consider providing an (ideally safe) +abstraction for everyone to use. + + +Conditional compilation +----------------------- + +Rust code has access to conditional compilation based on the kernel +configuration: + +.. code-block:: rust + + #[cfg(CONFIG_X)] // `CONFIG_X` is enabled (`y` or `m`) + #[cfg(CONFIG_X="y")] // `CONFIG_X` is enabled as a built-in (`y`) + #[cfg(CONFIG_X="m")] // `CONFIG_X` is enabled as a module (`m`) + #[cfg(not(CONFIG_X))] // `CONFIG_X` is disabled + diff --git a/Documentation/rust/index.rst b/Documentation/rust/index.rst index bcb4de39f3f17b..3dd98fe6d759e3 100644 --- a/Documentation/rust/index.rst +++ b/Documentation/rust/index.rst @@ -1,12 +1,14 @@ Rust ==== -Documentation related to Rust within the kernel. If you are starting out, read the :ref:`Documentation/rust/quick-start.rst ` guide. +Documentation related to Rust within the kernel. If you are starting out, +read the :ref:`Documentation/rust/quick-start.rst ` guide. .. toctree:: :maxdepth: 1 quick-start + coding .. only:: subproject and html diff --git a/Documentation/rust/quick-start.rst b/Documentation/rust/quick-start.rst index 925848b82c2fa3..d012869fcd71f6 100644 --- a/Documentation/rust/quick-start.rst +++ b/Documentation/rust/quick-start.rst @@ -5,10 +5,13 @@ Quick Start This document describes how to get started with Rust kernel development. + Requirements ------------ -A recent nightly Rust toolchain (at least ``rustc``, ``cargo`` and ``rustfmt``) is required, e.g. `nightly-2020-08-27`. In the future, this restriction will be lifted. If you are using ``rustup``, run:: +A recent nightly Rust toolchain (at least ``rustc``, ``cargo`` and ``rustfmt``) +is required, e.g. ``nightly-2020-08-27``. In the future, this restriction +will be lifted. If you are using ``rustup``, run:: rustup toolchain install nightly @@ -16,26 +19,35 @@ Otherwise, fetch a standalone installer from: https://www.rust-lang.org -The sources for the compiler are required to be available. If you are using ``rustup``, run:: +The sources for the compiler are required to be available. If you are using +``rustup``, run:: rustup component add rust-src -Otherwise, if you used a standalone installer, you can clone the Rust compiler sources and create a symlink to them in the installation folder of your nightly toolchain:: +Otherwise, if you used a standalone installer, you can clone the Rust compiler +sources and create a symlink to them in the installation folder of +your nightly toolchain:: git clone https://github.com/rust-lang/rust ln -s rust .../rust-nightly/lib/rustlib/src + Testing a simple driver ----------------------- -If the kernel configuration system is able to find ``rustc`` and ``cargo``, it will enable Rust support (``CONFIG_HAS_RUST``). In turn, this will make visible the rest of options that depend on Rust. +If the kernel configuration system is able to find ``rustc`` and ``cargo``, +it will enable Rust support (``CONFIG_HAS_RUST``). In turn, this will make +visible the rest of options that depend on Rust. -A simple driver you can compile to test things out is at ``drivers/char/rust_example`` (``CONFIG_RUST_EXAMPLE``). Enable it and compile the kernel with: +A simple driver you can compile to test things out is at +``drivers/char/rust_example`` (``CONFIG_RUST_EXAMPLE``). Enable it and compile +the kernel with: make LLVM=1 TODO: drop LLVM=1, allowing to mix GCC with LLVM + Avoiding the network -------------------- @@ -43,5 +55,6 @@ You can prefetch the dependencies that ``cargo`` will download by running:: cargo fetch -in the kernel sources root. After this step, a network connection is not needed anymore. +in the kernel sources root. After this step, a network connection is +not needed anymore.