doc: rust: Add docs on bindings

Add documentation on the bindings between Rust and C, and the bindgen
tool used to generate them.

Signed-off-by: David Brown <[email protected]>

Author: d3zd3z

doc/develop/languages/rust/bindings.rst

@@ -0,0 +1,52 @@
+.. _rust_bindings:
+
+Bindings to Zephyr for Rust
+###########################
+
+Zephyr is written in C, and it's primary API is also made available to C.  It is written as a
+mixture of types, function prototypes, inline functions, and macros.
+
+Although Rust interfaces fairly easily with C at an ABI level, the compiler does not have any
+support for generating the code necessary for these bindings. In order to call C code, the types
+must be reproduced in Rust, function prototypes written in Rust, and often wrappers made for inline
+functions and macros (or this functionality replicated in Rust).
+
+This is a tedious, and error-prone process, and the end result would quickly get out of date with
+the development of Zephyr.
+
+The `bindgen`_ project seeks to address much of this issue by automatically generating bindings to C
+code for Rust.  It makes use of ``libclang`` to parse and interpret a given set of headers, and
+generate the Rust code needed to call this code.
+
+.. _bindgen: https://github.com/rust-lang/rust-bindgen
+
+Because the Zephyr headers use numerous conditional compilation macros, the bindings needed will be
+very specialized to a given board, and even a given configuration.  To do this, the file
+:file:`lib/rust/zephyr-sys/build.rs`, which ``cargo`` knows to run at build time will
+generate the bindings for the particular build of Zephyr being used by the current Rust application.
+
+These bindings will be made available in the ``zephyr-sys`` crate, as well as under ``zephyr::raw``.
+
+Using the Bindings
+******************
+
+In general, using direct bindings to C function from Rust is a bit more difficult than calling them
+from C.  Although all of these calls are considered "unsafe", and must be placed in an ``unsafe``
+block, the rust language has stricter constraints on what is allowed, even by unsafe code.  Although
+the intent of the Rust on Zephyr project is to allow full use of Zephyr, without needing to resort
+to unsafe code, it is understandable that this implementation will be incomplete, and some
+applications may require resorting to, what is sometimes referred to as "The Dark Arts".  The
+`Rustinomicon`_ is a good resource for those wishing to delve into this area.
+
+.. _Rustinomicon: https://doc.rust-lang.org/nomicon/
+
+In addition, the code in :file:`zephyr/lib/rust/zephyr` that provides the higher level abstractions
+will primarily be implemented using these auto-generated bindings.
+
+Generation
+**********
+
+The generation of the bindings is controlled by the ``build.rs`` program.  This attempts to capture
+the symbols that are needed for successful bindings, but there may be things missing.  Additional
+bindings can be included by adding their patterns to the list of patterns in ``build.rs``, and
+possibly adding additional ``#include`` directives to :file:`lib/rust/zephyr-sys/wrapper.h`.

doc/develop/languages/rust/index.rst

@@ -11,6 +11,11 @@ efficient low-level code.  Rust's expressive syntax and modern features make it
 for developers working on embedded systems, operating systems, and other performance-critical
 applications.
 
+.. toctree::
+   :maxdepth: 2
+
+   bindings.rst
+
 Enabling Rust Support
 *********************