Message-ID: <20240717221133.459589-1-benno.lossin@proton.me>
Date: Wed, 17 Jul 2024 22:12:24 +0000
From: Benno Lossin <benno.lossin@...ton.me>
To: Jonathan Corbet <corbet@....net>, Miguel Ojeda <ojeda@...nel.org>, Alex Gaynor <alex.gaynor@...il.com>, Wedson Almeida Filho <wedsonaf@...il.com>, Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>, Björn Roy Baron <bjorn3_gh@...tonmail.com>, Benno Lossin <benno.lossin@...ton.me>, Andreas Hindborg <a.hindborg@...sung.com>, Alice Ryhl <aliceryhl@...gle.com>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org, rust-for-linux@...r.kernel.org
Subject: [RFC PATCH 0/5] Introduce the Rust Safety Standard

`unsafe` Rust code in the kernel is required to have safety
documentation. This is to ensure the correctness of `unsafe` code and is
thus very important.
However, at this point in time there does not exist a standard way of
writing safety documentation. This leads to confusion, as authors
struggle to find the right way to convey their desired intentions.
Readers similarly struggle with correctly interpreting the 
documentation; it's the wild west.

To alleviate this issue and to raise the quality of safety
documentation, this patch series introduces a standard way of writing
safety documentation.

Because creating a standard for every possible requirement is a tall
task, this series starts off very small. I hope to start more
discussion, in order to find the best form of safety documentation for
the kernel.
Please do not hesitate to give any kind of comment. I could benefit
especially from improvements to the visual look of the documentation, as
this is my first time writing Sphinx documentation. For example, I am
not satisfied with how the tables renders in HTML.

Benno Lossin (5):
  doc: rust: create safety standard
  doc: rust: safety standard: add examples
  doc: rust: safety standard: add guarantees and type invariants
  doc: rust: safety standard: add safety requirements
  doc: rust: safety standard: add justifications

 Documentation/rust/general-information.rst    |   1 +
 Documentation/rust/index.rst                  |   1 +
 .../rust/safety-standard/examples.rst         |  70 +++++
 .../rust/safety-standard/guarantee.rst        |   7 +
 Documentation/rust/safety-standard/index.rst  | 281 ++++++++++++++++++
 .../rust/safety-standard/justifications.rst   |  40 +++
 .../rust/safety-standard/requirements.rst     |  80 +++++
 .../rust/safety-standard/type-invariants.rst  |  18 ++
 8 files changed, 498 insertions(+)
 create mode 100644 Documentation/rust/safety-standard/examples.rst
 create mode 100644 Documentation/rust/safety-standard/guarantee.rst
 create mode 100644 Documentation/rust/safety-standard/index.rst
 create mode 100644 Documentation/rust/safety-standard/justifications.rst
 create mode 100644 Documentation/rust/safety-standard/requirements.rst
 create mode 100644 Documentation/rust/safety-standard/type-invariants.rst

-- 
2.45.1

Powered by blists - more mailing lists