From: Dirk Behme <dirk.behme@de.bosch.com>
To: <rust-for-linux@vger.kernel.org>
Cc: Dirk Behme <dirk.behme@de.bosch.com>,
Valentin Obst <kernel@valentinobst.de>,
Trevor Gross <tmgross@umich.edu>, Miguel Ojeda <ojeda@kernel.org>
Subject: [PATCH v3] docs: rust: extend abstraction and binding documentation
Date: Tue, 13 Feb 2024 09:38:19 +0100 [thread overview]
Message-ID: <20240213083819.1292958-1-dirk.behme@de.bosch.com> (raw)
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 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
reply other threads:[~2024-02-13 8:38 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240213083819.1292958-1-dirk.behme@de.bosch.com \
--to=dirk.behme@de.bosch.com \
--cc=kernel@valentinobst.de \
--cc=ojeda@kernel.org \
--cc=rust-for-linux@vger.kernel.org \
--cc=tmgross@umich.edu \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).