[PATCH v3] docs: rust: extend abstraction and binding documentation
From: Dirk Behme <hidden>
Date: 2024-02-13 08:38:36
Subsystem:
documentation, rust, the rest · Maintainers:
Jonathan Corbet, Miguel Ojeda, Linus Torvalds
Add some basics explained by Miguel in [1] to the documentation. And connect it with some hints where this is implemented in the kernel. [1] https://www.linuxfoundation.org/webinars/rust-for-linux-writing-abstractions-and-drivers Cc: Miguel Ojeda <ojeda@kernel.org> Signed-off-by: Dirk Behme <redacted> --- Documentation/rust/general-information.rst | 56 ++++++++++++++++++++++ 1 file changed, 56 insertions(+) Changes in v3: Try to incorporate the v2 review comments from Trevor and Valentin.
diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst
index 081397827a7e..6c6fb3a5e318 100644
--- a/Documentation/rust/general-information.rst
+++ b/Documentation/rust/general-information.rst@@ -64,6 +64,62 @@ 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. +.. code-block:: + + rust/bindings/ + (rust/helpers.c) + + include/ -----+ <-+ + | | + drivers/ rust/kernel/ +----------+ <-+ | + fs/ | bindgen | | + .../ +-------------------+ +----------+ --+ | + | Abstractions | | | + +---------+ | +------+ +------+ | +----------+ | | + | my_foo | -----> | | foo | | bar | | -------> | Bindings | <-+ | + | driver | Safe | | sub- | | sub- | | Unsafe | | | + +---------+ | |system| |system| | | bindings | <-----+ + | | +------+ +------+ | | crate | | + | | kernel crate | +----------+ | + | +-------------------+ | + | | + +------------------# FORBIDDEN #--------------------------------+ + +The main idea is to encapsulate all direct interaction with the kernel's C APIs +into carefully reviewed and documented abstractions. These are then considered to +be sound. The goal is that users of these abstractions ("my_foo driver") cannot +introduce undefined behavior (UB) as long as: + +#. the abstractions are correct. +#. they don't use ``unsafe{..}``. Or they uphold the preconditions of all unsafe + operations that they perform if they use ``unsafe{..}`` for performance optimizations + or to call unsafe abstractions. + +Bindings +~~~~~~~~ + +By including a C header from ``include/`` into ``rust/bindings/bindings_helper.h`` +the ``bindgen`` tool will auto-generate the bindings for the included subsystem. +After building, see the ``*_generated.rs`` output files in the ``rust/bindings/`` +directory. + +For parts of the C header that ``bindgen`` doesn't auto generate, e.g. C ``inline`` +functions or macros, it is acceptable to add a small wrapper function +to ``rust/helpers.c`` to make it available for the Rust side as well. + +Abstractions +~~~~~~~~~~~~ + +Abstractions are the layer between the bindings and the in-kernel users. They are +located in ``rust/kernel/`` and their role is to encapsulate the unsafe access +to the bindings into an as-safe-as-possible API that they expose to their users. +Users of the abstractions include things like drivers or file systems written in Rust. + +Besides the safety aspect, the abstractions are supposed to be "ergonomic", in the +sense that they turn the C interfaces into "idiomatic" Rust code. Basic examples are +to turn the C resource acquisition and release into Rust constructors and destructors +or C integer error codes into Rust's ``Result``. + Conditional compilation -----------------------
--
2.28.0