Merge pull request #35 from Rust-for-Linux/rust-doc

Doc improvements

Author: ojeda

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
+

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 <rust_quick_start>` guide.
+Documentation related to Rust within the kernel. If you are starting out,
+read the :ref:`Documentation/rust/quick-start.rst <rust_quick_start>` guide.
 
 .. toctree::
     :maxdepth: 1
 
     quick-start
+    coding
 
 .. only::  subproject and html
 

Documentation/rust/quick-start.rst

@@ -5,43 +5,56 @@ 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
 
 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
 --------------------
 
 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.