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?
[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
