[RFC PATCH 4/5] doc: rust: safety standard: add safety requirements

[Benno Lossin <benno.lossin@proton.me>]

Add standardized safety requirements.

Signed-off-by: Benno Lossin <benno.lossin@proton.me>
---
 Documentation/rust/safety-standard/index.rst  |  5 ++
 .../rust/safety-standard/requirements.rst     | 80 +++++++++++++++++++
 2 files changed, 85 insertions(+)
 create mode 100644 Documentation/rust/safety-standard/requirements.rst

diff --git a/Documentation/rust/safety-standard/index.rst b/Documentation/rust/safety-standard/index.rst
index 40b17f59709c..2ef82d7dfbd8 100644
--- a/Documentation/rust/safety-standard/index.rst
+++ b/Documentation/rust/safety-standard/index.rst
@@ -157,6 +157,8 @@ The safety requirements have to be documented in the so called safety section::
         // ...
     }
 
+See requirements.rst for a full list of standardized safety requirements.
+
 .. _unsafe-Blocks:
 
 ``unsafe`` Blocks
@@ -208,6 +210,8 @@ are called safety requirements and need to be documented in the same way::
     /// <safety requirements>
     unsafe trait Foo {}
 
+See requirements.rst for a full list of standardized safety requirements.
+
 ``unsafe`` Impls
 ----------------
 
@@ -262,6 +266,7 @@ Further Pages
    examples
    guarantee
    type-invariants
+   requirements
 
 .. only::  subproject and html
 
diff --git a/Documentation/rust/safety-standard/requirements.rst b/Documentation/rust/safety-standard/requirements.rst
new file mode 100644
index 000000000000..b86bfb98179e
--- /dev/null
+++ b/Documentation/rust/safety-standard/requirements.rst
@@ -0,0 +1,80 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. highlight:: rust
+
+===================
+Safety Requirements
+===================
+
+There are many different kinds of safety requirements. The simplest example is the validity of raw
+pointers. But there is no limit to what they may require.
+
+Safety requirements are listed in an unordered markdown list in the ``# Safety`` section on
+``unsafe fn`` and ``unsafe trait`` items. Each list item should only contain a single requirement.
+The items should not specify the same requirement multiple times, especially not by expressing it in
+different terms.  The ``# Safety`` section should only consist of the list of safety requirements,
+if there is additional information, it should be documented in a different section.
+
+Common Safety Requirements
+==========================
+
++------------------------+---------------------+---------------------------------------------------+
+| Syntax                 | Meta Variables      | Meaning                                           |
+|                        |                     |                                                   |
++========================+=====================+===================================================+
+| ``ptr`` is valid for   |                     | Abbreviation for:                                 |
+| reads and writes.      |                     |                                                   |
+|                        | * ``ptr: *mut T``   | * ``ptr`` is valid for reads.                     |
+|                        |                     | * ``ptr`` is valid for writes.                    |
++------------------------+---------------------+---------------------------------------------------+
+| ``ptr`` is valid for   |                     | Abbreviation for:                                 |
+| reads.                 |                     |                                                   |
+|                        | * ``ptr: *const T`` | * ``ptr`` is valid for reads up to                |
+|                        |                     |   ``size_of::<T>()`` bytes for the duration of    |
+|                        |                     |   this function call.                             |
++------------------------+---------------------+---------------------------------------------------+
+| ``ptr`` is valid for   |                     | Abbreviation for:                                 |
+| writes.                |                     |                                                   |
+|                        | * ``ptr: *mut T``   | * ``ptr`` is valid for writes up to               |
+|                        |                     |   ``size_of::<T>()`` bytes for the duration of    |
+|                        |                     |   this function call.                             |
++------------------------+---------------------+---------------------------------------------------+
+| ``ptr`` is valid for   |                     | For the duration of ``'a``:                       |
+| reads up to ``size``   |                     |                                                   |
+| bytes for the duration | * ``ptr: *const T`` | * The pointer ``ptr`` is dereferenceable for      |
+| of ``'a``.             | * ``size: usize``   |   ``size`` bytes: all bytes with offset           |
+|                        |                     |   ``0..size`` have to be part of the same         |
+|                        |                     |   allocated object and it has to be alive.        |
+|                        |                     | * No concurrent write operation may occur to      |
+|                        |                     |   ``ptr`` at any offset between ``0..size``.      |
+|                        |                     | * The value at ``ptr`` is a valid instance of     |
+|                        |                     |   the type ``T``.                                 |
+|                        |                     |                                                   |
+|                        |                     | Additionally ``ptr`` must be:                     |
+|                        |                     |                                                   |
+|                        |                     | * non-null,                                       |
+|                        |                     | * aligned to ``align_of::<T>()`` i.e.             |
+|                        |                     |   ``ptr.addr() % align_of::<T>() == 0``.          |
++------------------------+---------------------+---------------------------------------------------+
+| ``ptr`` is valid for   |                     | For the duration of ``'a``:                       |
+| writes up to ``size``  |                     |                                                   |
+| bytes for the duration | * ``ptr: *mut T``   | * The pointer ``ptr`` is dereferenceable for      |
+| of ``'a``.             | * ``size: usize``   |   ``size`` bytes: all bytes with offset           |
+|                        |                     |   ``0..size`` have to be part of the same         |
+|                        |                     |   allocated object and it has to be alive.        |
+|                        |                     | * No concurrent read or write operation may occur |
+|                        |                     |   to ``ptr`` at any offset between ``0..size``.   |
+|                        |                     |                                                   |
+|                        |                     | Additionally ``ptr`` must be:                     |
+|                        |                     |                                                   |
+|                        |                     | * non-null,                                       |
+|                        |                     | * aligned to ``align_of::<T>()`` i.e.             |
+|                        |                     |   ``ptr.addr() % align_of::<T>() == 0``.          |
++------------------------+---------------------+---------------------------------------------------+
+
+
+Custom Safety Requirements
+==========================
+
+There are of course situations where the safety requirements listed above are insufficient. In that
+case the author can try to come up with their own safety requirement wording and ask the reviewers
+what they think. If the requirement is common enough, it should be added to the list above.
-- 
2.45.1