On Thu, Sep 11, 2025 at 05:29:31PM +0900, Akira Yokosawa wrote:
> Currently, LKMM docs are not included in any of kernel documentation
> books.
>
> Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt
> into the core-api book") covered plain-text docs under Documentation/
> by using the "include::" directive along with the ":literal:" option.
>
> As LKMM docs are not under Documentation/, the same approach would not
> work due to the directive's restriction.
>
> As a matter of fact, kernel documentation has an extended directive
> by the name of "kernel-include::", which loosens such restriction and
> accepts any files under the kernel source tree.
>
> Rather than moving LKMM docs around, use the latter and pull them into
> the dev-tools book next to KCSAN.
>
> Signed-off-by: Akira Yokosawa <akiyks@xxxxxxxxx>
> Cc: Paul E. McKenney <paulmck@xxxxxxxxxx>
> ---
> v2:
> - Rebased on top of docs-next.
> - v1 was intended to be upstreamed through Paul's lkmm tree.
> Given the changes queued in Jon's tree where docs build scripts have
> seen rather radical changes, upstreaming this through Jon's tree
> sounds reasonable to me.
> - Removed "$SOURCEDIR/" from path to the "kernel-include::" directives.
> "kernel-include::" now treats them as relative to kernel source dir.
> - Amended summary phrase.
>
> Paul, could you ack on this change going through Jon's tree?
Thank you, Akira!
Acked-by: Paul E. McKenney <paulmck@xxxxxxxxxx>
> [v1]: https://lore.kernel.org/015198be-1f23-4fc9-ba58-be7c48550f36@xxxxxxxxx/
>
> Thanks, Akira
> --
> Documentation/dev-tools/index.rst | 1 +
> .../dev-tools/lkmm/docs/access-marking.rst | 11 ++++++++++
> .../dev-tools/lkmm/docs/cheatsheet.rst | 11 ++++++++++
> .../lkmm/docs/control-dependencies.rst | 11 ++++++++++
> .../dev-tools/lkmm/docs/explanation.rst | 11 ++++++++++
> .../dev-tools/lkmm/docs/glossary.rst | 11 ++++++++++
> .../lkmm/docs/herd-representation.rst | 11 ++++++++++
> Documentation/dev-tools/lkmm/docs/index.rst | 21 +++++++++++++++++++
> .../dev-tools/lkmm/docs/litmus-tests.rst | 11 ++++++++++
> Documentation/dev-tools/lkmm/docs/locking.rst | 11 ++++++++++
> .../dev-tools/lkmm/docs/ordering.rst | 11 ++++++++++
> Documentation/dev-tools/lkmm/docs/readme.rst | 11 ++++++++++
> Documentation/dev-tools/lkmm/docs/recipes.rst | 11 ++++++++++
> .../dev-tools/lkmm/docs/references.rst | 11 ++++++++++
> Documentation/dev-tools/lkmm/docs/simple.rst | 11 ++++++++++
> Documentation/dev-tools/lkmm/index.rst | 15 +++++++++++++
> Documentation/dev-tools/lkmm/readme.rst | 11 ++++++++++
> MAINTAINERS | 1 +
> 18 files changed, 192 insertions(+)
> create mode 100644 Documentation/dev-tools/lkmm/docs/access-marking.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/cheatsheet.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/control-dependencies.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/explanation.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/glossary.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/herd-representation.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/index.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/litmus-tests.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/locking.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/ordering.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/readme.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/recipes.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/references.rst
> create mode 100644 Documentation/dev-tools/lkmm/docs/simple.rst
> create mode 100644 Documentation/dev-tools/lkmm/index.rst
> create mode 100644 Documentation/dev-tools/lkmm/readme.rst
>
> diff --git a/Documentation/dev-tools/index.rst b/Documentation/dev-tools/index.rst
> index 65c54b27a60b..4b8425e348ab 100644
> --- a/Documentation/dev-tools/index.rst
> +++ b/Documentation/dev-tools/index.rst
> @@ -29,6 +29,7 @@ Documentation/process/debugging/index.rst
> ubsan
> kmemleak
> kcsan
> + lkmm/index
> kfence
> kselftest
> kunit/index
> diff --git a/Documentation/dev-tools/lkmm/docs/access-marking.rst b/Documentation/dev-tools/lkmm/docs/access-marking.rst
> new file mode 100644
> index 000000000000..80058a4da980
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/access-marking.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Access Marking
> +--------------
> +
> +Literal include of ``tools/memory-model/Documentation/access-marking.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/access-marking.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/cheatsheet.rst b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst
> new file mode 100644
> index 000000000000..37681f6a6a8c
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/cheatsheet.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Cheatsheet
> +----------
> +
> +Literal include of ``tools/memory-model/Documentation/cheatsheet.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/cheatsheet.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/control-dependencies.rst b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst
> new file mode 100644
> index 000000000000..5ae97e8861eb
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/control-dependencies.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Control Dependencies
> +--------------------
> +
> +Literal include of ``tools/memory-model/Documentation/control-dependencies.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/control-dependencies.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/explanation.rst b/Documentation/dev-tools/lkmm/docs/explanation.rst
> new file mode 100644
> index 000000000000..0bcba9a5ddf7
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/explanation.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Explanation
> +-----------
> +
> +Literal include of ``tools/memory-model/Documentation/explanation.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/explanation.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/glossary.rst b/Documentation/dev-tools/lkmm/docs/glossary.rst
> new file mode 100644
> index 000000000000..849aefdf3d6e
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/glossary.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Glossary
> +--------
> +
> +Literal include of ``tools/memory-model/Documentation/glossary.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/glossary.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/herd-representation.rst b/Documentation/dev-tools/lkmm/docs/herd-representation.rst
> new file mode 100644
> index 000000000000..ebf4a2181cd7
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/herd-representation.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +herd-representation
> +-------------------
> +
> +Literal include of ``tools/memory-model/Documentation/herd-representation``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/herd-representation.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/index.rst b/Documentation/dev-tools/lkmm/docs/index.rst
> new file mode 100644
> index 000000000000..abbddcc009de
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/index.rst
> @@ -0,0 +1,21 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Documentation
> +=============
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + readme
> + simple
> + ordering
> + litmus-tests
> + locking
> + recipes
> + control-dependencies
> + access-marking
> + cheatsheet
> + explanation
> + herd-representation
> + glossary
> + references
> diff --git a/Documentation/dev-tools/lkmm/docs/litmus-tests.rst b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst
> new file mode 100644
> index 000000000000..3293f4540156
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/litmus-tests.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Litmus Tests
> +------------
> +
> +Literal include of ``tools/memory-model/Documentation/litmus-tests.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/litmus-tests.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/locking.rst b/Documentation/dev-tools/lkmm/docs/locking.rst
> new file mode 100644
> index 000000000000..b5eae4c0acb7
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/locking.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Locking
> +-------
> +
> +Literal include of ``tools/memory-model/Documentation/locking.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/locking.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/ordering.rst b/Documentation/dev-tools/lkmm/docs/ordering.rst
> new file mode 100644
> index 000000000000..a2343c12462d
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/ordering.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Ordering
> +--------
> +
> +Literal include of ``tools/memory-model/Documentation/ordering.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/ordering.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/readme.rst b/Documentation/dev-tools/lkmm/docs/readme.rst
> new file mode 100644
> index 000000000000..51e7a64e4435
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/readme.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +README (for LKMM Documentation)
> +-------------------------------
> +
> +Literal include of ``tools/memory-model/Documentation/README``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/README
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/recipes.rst b/Documentation/dev-tools/lkmm/docs/recipes.rst
> new file mode 100644
> index 000000000000..e55952640047
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/recipes.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Recipes
> +-------
> +
> +Literal include of ``tools/memory-model/Documentation/recipes.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/recipes.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/references.rst b/Documentation/dev-tools/lkmm/docs/references.rst
> new file mode 100644
> index 000000000000..c6831b3c9c02
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/references.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +References
> +----------
> +
> +Literal include of ``tools/memory-model/Documentation/references.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/references.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/docs/simple.rst b/Documentation/dev-tools/lkmm/docs/simple.rst
> new file mode 100644
> index 000000000000..5c1094c95f45
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/docs/simple.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +Simple
> +------
> +
> +Literal include of ``tools/memory-model/Documentation/simple.txt``.
> +
> +------------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/Documentation/simple.txt
> + :literal:
> diff --git a/Documentation/dev-tools/lkmm/index.rst b/Documentation/dev-tools/lkmm/index.rst
> new file mode 100644
> index 000000000000..e52782449ca3
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/index.rst
> @@ -0,0 +1,15 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +============================================
> +Linux Kernel Memory Consistency Model (LKMM)
> +============================================
> +
> +This section literally renders documents under ``tools/memory-model/``
> +and ``tools/memory-model/Documentation/``, which are maintained in
> +the *pure* plain text form.
> +
> +.. toctree::
> + :maxdepth: 2
> +
> + readme
> + docs/index
> diff --git a/Documentation/dev-tools/lkmm/readme.rst b/Documentation/dev-tools/lkmm/readme.rst
> new file mode 100644
> index 000000000000..a7f847109584
> --- /dev/null
> +++ b/Documentation/dev-tools/lkmm/readme.rst
> @@ -0,0 +1,11 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +README (for LKMM)
> +=================
> +
> +Literal include of ``tools/memory-model/README``.
> +
> +------------------------------------------------------------
> +
> +.. kernel-include:: tools/memory-model/README
> + :literal:
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ef87548b8f88..ac47a5d0d8e8 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -14151,6 +14151,7 @@ T: git git://git.kernel.org/pub/scm/linux/kernel/git/rcu/linux.git rcu/dev
> F: Documentation/atomic_bitops.txt
> F: Documentation/atomic_t.txt
> F: Documentation/core-api/refcount-vs-atomic.rst
> +F: Documentation/dev-tools/lkmm/
> F: Documentation/litmus-tests/
> F: Documentation/memory-barriers.txt
> F: tools/memory-model/
>
> base-commit: f44a29784f685804d9970cfb0d3439c9e30981d7
> --
> 2.43.0
>
