From: "Paul E. McKenney" <paulmck@kernel.org>
To: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Joel Fernandes <joel@joelfernandes.org>,
Peter Zijlstra <peterz@infradead.org>,
Alan Stern <stern@rowland.harvard.edu>,
Marco Elver <elver@google.com>,
Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
Ignacio Encinas Rubio <ignacio@iencinas.com>,
lkmm@lists.linux.dev
Subject: Re: [PATCH v2] docs: Pull LKMM documentation into dev-tools book
Date: Thu, 11 Sep 2025 06:25:03 -0700 [thread overview]
Message-ID: <5e2b5f4c-9655-4ece-b0a1-df43b5f578db@paulmck-laptop> (raw)
In-Reply-To: <7ce84a93-5cbc-420e-894a-06a0372c52ab@gmail.com>
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@gmail.com>
> Cc: Paul E. McKenney <paulmck@kernel.org>
> ---
> 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@kernel.org>
> [v1]: https://lore.kernel.org/015198be-1f23-4fc9-ba58-be7c48550f36@gmail.com/
>
> 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
>
next prev parent reply other threads:[~2025-09-11 13:25 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-09-11 8:29 [PATCH v2] docs: Pull LKMM documentation into dev-tools book Akira Yokosawa
2025-09-11 13:25 ` Paul E. McKenney [this message]
2025-09-16 16:34 ` Jonathan Corbet
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=5e2b5f4c-9655-4ece-b0a1-df43b5f578db@paulmck-laptop \
--to=paulmck@kernel.org \
--cc=akiyks@gmail.com \
--cc=corbet@lwn.net \
--cc=elver@google.com \
--cc=ignacio@iencinas.com \
--cc=joel@joelfernandes.org \
--cc=linux-doc@vger.kernel.org \
--cc=lkmm@lists.linux.dev \
--cc=mchehab+huawei@kernel.org \
--cc=peterz@infradead.org \
--cc=stern@rowland.harvard.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).