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

[Valentin Obst <kernel@valentinobst.de>]

+.. 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 ``unsafe()`` handling in the abstractions reviewed
+and documented carefully. These are considered to be sound then.

Maybe reword a bit to make it smoother:

The main idea is to encapsulate all ``unsafe()`` handling in carefully
reviewed and documented abstractions. These are then considered to be
sound.

> 								  With this model
> +it is assumed that users of the abstractions ("my_foo driver") can't do anything
> +unsound if

Not sure if 'assumed' is the best word here. Isn't the soundness
of safe code implied by the soundness of the safe abstractions it is
using? In that case one could use stronger words and say, e.g.,
"... ensured that ...".

> +
> +#. the abstractions are sound
> +#. they don't use ``unsafe()``
> +
> +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.
> +See the ``*_generated.rs`` output files in the ``rust/bindings/`` directory.
> +
> +For parts of the C header ``bindgen`` doesn't auto generate, e.g. C ``inline``
> +functions, there is the option to add a small wrapper function to ``rust/helpers.c``
> +to make it available for the Rust side as well.
> +
> +Abstractions
> +~~~~~~~~~~~~
> +
> +Abstractions are the glue layer between the bindings and the in-kernel users. E.g.
> +the drivers or file systems written in Rust.

Wouldn't start a sentence with 'e.g.'. I'd either write it out, i.e.,
"For example,", or not start a new sentence: "... users, e.g. ...".

> 						They are located in ``rust/kernel/``
> +and are supposed to make the ``unsafe()`` access to the bindings as-safe-as-possible
> +for their users.
> +

I think one could make it more clear that users are not expected to
access the bindings directly, e.g.:

... and their role is to encapsulate the ``unsafe()`` access to the
bindings into a safe API that they expose to their users.

Note: Looks like you only sent this to Miguel and RFL list (intentional?).

	- Best Valentin