[PATCH v4] docs: rust: extend abstraction and binding documentation

* [PATCH v4] docs: rust: extend abstraction and binding documentation
@ 2024-04-18  7:06 Dirk Behme
  2024-04-18 11:55 ` Benno Lossin
  2024-05-05 22:32 ` Miguel Ojeda
  0 siblings, 2 replies; 3+ messages in thread
From: Dirk Behme @ 2024-04-18  7:06 UTC (permalink / raw)
  To: rust-for-linux; +Cc: Dirk Behme, Valentin Obst, Trevor Gross, Miguel Ojeda

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 <dirk.behme@de.bosch.com>
---
 Documentation/rust/general-information.rst | 56 ++++++++++++++++++++++
 1 file changed, 56 insertions(+)

Changes in v4: Rebase against rust-dev v6.9-rc1 to re-start this topic. If
               the reviewers are too busy and its not a good time for it
               just let me know :)

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


^ permalink raw reply related	[flat|nested] 3+ messages in thread