Re: [PATCH v2] 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 carefully reviewed
> +and documented abstractions. These are then considered to be sound. With this model
> +it is ensured that users of the abstractions ("my_foo driver") can't do anything
> +unsound if
> +
> +#. the abstractions are sound
> +#. they don't use ``unsafe()``

I'd like to follow up on some of the things that Miguel mentioned in his
earlier message:

- To make it clearer what is meant by "unsafe handling": One could say
  "... encapsulate all direct interaction with the kernel's C APIs ...".
  This requires using unsafe Rust, but also leaves the door open for
  drivers to use unsafe Rust, e.g., for performance optimizations or to
  call unsafe abstractions.
- To avoid saying that "... [abstractions] are considered to be sound
  [after review] ...": One could say "The goal must be that users of
  these abstractions cannot introduce undefined behavior as long as:
  1. The abstractions are correct, & 2. they uphold the preconditions
  of all unsafe operations that they perform."

> +
> +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 or macros, 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 layer between the bindings and the in-kernel users. For example
> +the drivers or file systems written in Rust. They are located in ``rust/kernel/``
> +and their role is to encapsulate the unsafe access to the bindings into a safe API
> +that they expose to their users.

I'd think one should keep the "as-safe-as-possible" aspect here, as
there will always be cases where it is not possible to provide safe
abstractions.

Another aspect about these APIs that I don't see mentioned here is that
they should be "ergonomic", in the sense that they turn "C-ish"
interfaces into something that allows you to write "idiomatic" Rust
code. Basic examples would be to turn resource acquisition and release
into constructors and destructors or integer error codes into Results,
and so on. I'm not entirely sure to which extend this is covered by the
safety aspect (they have a non-zero overlap), but perhaps it is
something that could be mentioned here.

	- Best Valentin

> +