Skip to contentSkip to conversation

Convert atomic_*.txt and memory-barriers.txt to reST

PATCH NAK Bagas Sanjaya 6 participants 13 messages Jul 17, 2025 – Jul 19, 2025

Subsystems (7)
lore
Share & tools
lore
#0 lore raw

cover Convert atomic_*.txt and memory-barriers.txt to reST

Atomic types, atomic bitops, and memory barriers docs are included in kernel docs build since commit e40573a43d163a ("docs: put atomic*.txt and memory-barriers.txt into the core-api book") as a wrapper stub for corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs.

Bagas Sanjaya (4):
Documentation: memory-barriers: Convert to reST format
Documentation: atomic_bitops: Convert to reST format
Documentation: atomic_t: Convert to reST format
Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
newly-converted docs

 Documentation/RCU/rcu_dereference.rst         |    2 +-
 .../atomic_bitops.rst}                        |   43 +-
 .../{atomic_t.txt => core-api/atomic_t.rst}   |  211 ++-
 Documentation/core-api/circular-buffers.rst   |    4 +-
 Documentation/core-api/index.rst              |    6 +-
 .../memory-barriers.rst}                      | 1594 +++++++++--------
 Documentation/core-api/refcount-vs-atomic.rst |    5 +-
 .../core-api/wrappers/atomic_bitops.rst       |   18 -
 Documentation/core-api/wrappers/atomic_t.rst  |   19 -
 .../core-api/wrappers/memory-barriers.rst     |   18 -
 Documentation/driver-api/device-io.rst        |    4 +-
 Documentation/locking/spinlocks.rst           |    5 +-
 Documentation/virt/kvm/vcpu-requests.rst      |    4 +-
 13 files changed, 1000 insertions(+), 933 deletions(-)
 rename Documentation/{atomic_bitops.txt => core-api/atomic_bitops.rst} (54%)
 rename Documentation/{atomic_t.txt => core-api/atomic_t.rst} (67%)
 rename Documentation/{memory-barriers.txt => core-api/memory-barriers.rst} (67%)
 delete mode 100644 Documentation/core-api/wrappers/atomic_bitops.rst
 delete mode 100644 Documentation/core-api/wrappers/atomic_t.rst
 delete mode 100644 Documentation/core-api/wrappers/memory-barriers.rst

base-commit: cae58415830f326822593ec01deebe5fdaeb33a2

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#1 lore raw

PATCH 1/4 Documentation: memory-barriers: Convert to reST format

Convert memory barriers documentation to reST syntax:

* Fix up title and section headings (and sentence-case headings)
* Generate in-doc table of contents with contents:: directive
* Use proper bullet list syntax
* Mark-up admonitions, code blocks, and footnotes

---
 Documentation/core-api/index.rst              |    2 +-
 .../memory-barriers.rst}                      | 1580 +++++++++--------
 .../core-api/wrappers/memory-barriers.rst     |   18 -
 3 files changed, 840 insertions(+), 760 deletions(-)
 rename Documentation/{memory-barriers.txt => core-api/memory-barriers.rst} (67%)
 delete mode 100644 Documentation/core-api/wrappers/memory-barriers.rst
Documentation/core-api/index.rst +1 -1
index 7a4ca18ca6e2d3..a0c3749c655b05 100644
@@ -77,7 +77,7 @@ Documentation/locking/index.rst for more related documentation.
    local_ops
    padata
    ../RCU/index
-   wrappers/memory-barriers.rst
+   memory-barriers
 
 Low-level hardware management
 =============================
Documentation/core-api/memory-barriers.rst renamed from Documentation/memory-barriers.txt +839 -741

2,752 lines not on this page · raw message

Documentation/core-api/wrappers/memory-barriers.rst deleted +0 -18
deleted file mode 100644
index 532460b5e3eb88..00000000000000
@@ -1,18 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-   This is a simple wrapper to bring memory-barriers.txt into the RST world
-   until such a time as that file can be converted directly.
-
-============================
-Linux kernel memory barriers
-============================
-
-.. raw:: latex
-
-    \footnotesize
-
-.. include:: ../../memory-barriers.txt
-   :literal:
-
-.. raw:: latex
-
-    \normalsize
Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer
#2 lore raw

Re: [PATCH 1/4] Documentation: memory-barriers: Convert to reST format

I believe memory-barriers.txt is often referred to outside of the kernel and should retain that name. Maybe that's no longer the case.

David

#3 lore raw

PATCH 2/4 Documentation: atomic_bitops: Convert to reST format

In reply to Bagas Sanjaya

Convert atomic bitops documentation to reST syntax:

* Sentence-case headings
* List API functions and their semantics in bullet list

---
 .../atomic_bitops.rst}                        | 39 +++++++++----------
 Documentation/core-api/index.rst              |  2 +-
 .../core-api/wrappers/atomic_bitops.rst       | 18 ---------
 3 files changed, 20 insertions(+), 39 deletions(-)
 rename Documentation/{atomic_bitops.txt => core-api/atomic_bitops.rst} (60%)
 delete mode 100644 Documentation/core-api/wrappers/atomic_bitops.rst
Documentation/core-api/atomic_bitops.rst renamed from Documentation/atomic_bitops.txt +19 -20
similarity index 60%
rename from Documentation/atomic_bitops.txt
rename to Documentation/core-api/atomic_bitops.rst
index edea4656c5c05f..b93c388fd9bdc4 100644
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
 =============
 Atomic bitops
 =============
@@ -11,53 +13,50 @@ API
 
 The single bit operations are:
 
-Non-RMW ops:
+* Non-RMW ops:
 
-  test_bit()
+  * test_bit()
 
-RMW atomic operations without return value:
+* RMW atomic operations without return value:
 
-  {set,clear,change}_bit()
-  clear_bit_unlock()
+  * {set,clear,change}_bit()
+  * clear_bit_unlock()
 
-RMW atomic operations with return value:
+* RMW atomic operations with return value:
 
-  test_and_{set,clear,change}_bit()
-  test_and_set_bit_lock()
+  * test_and_{set,clear,change}_bit()
+  * test_and_set_bit_lock()
 
-Barriers:
+* Barriers:
 
-  smp_mb__{before,after}_atomic()
+  * smp_mb__{before,after}_atomic()
 
 
 All RMW atomic operations have a '__' prefixed variant which is non-atomic.
 
 
-SEMANTICS
+Semantics
 ---------
 
-Non-atomic ops:
+* Non-atomic ops:
 
-In particular __clear_bit_unlock() suffers the same issue as atomic_set(),
-which is why the generic version maps to clear_bit_unlock(), see atomic_t.txt.
+  In particular __clear_bit_unlock() suffers the same issue as atomic_set(),
+  which is why the generic version maps to clear_bit_unlock(), see atomic_t.txt.
 
 
-RMW ops:
+* RMW ops:
 
-The test_and_{}_bit() operations return the original value of the bit.
+  The test_and_{}_bit() operations return the original value of the bit.
 
 
-ORDERING
+Ordering
 --------
 
 Like with atomic_t, the rule of thumb is:
 
  - non-RMW operations are unordered;
-
  - RMW operations that have no return value are unordered;
-
  - RMW operations that have a return value are fully ordered.
-
  - RMW operations that are conditional are fully ordered.
 
 Except for a successful test_and_set_bit_lock() which has ACQUIRE semantics,
Documentation/core-api/index.rst +1 -1
index a0c3749c655b05..4bc132fefaab7f 100644
@@ -49,7 +49,7 @@ Library functionality that is used throughout the kernel.
    timekeeping
    errseq
    wrappers/atomic_t
-   wrappers/atomic_bitops
+   atomic_bitops
    floating-point
    union_find
    min_heap
Documentation/core-api/wrappers/atomic_bitops.rst deleted +0 -18
deleted file mode 100644
index bf24e4081a8f4c..00000000000000
@@ -1,18 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-   This is a simple wrapper to bring atomic_bitops.txt into the RST world
-   until such a time as that file can be converted directly.
-
-=============
-Atomic bitops
-=============
-
-.. raw:: latex
-
-    \footnotesize
-
-.. include:: ../../atomic_bitops.txt
-   :literal:
-
-.. raw:: latex
-
-    \normalsize
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#4 lore raw

PATCH 3/4 Documentation: atomic_t: Convert to reST format

In reply to Bagas Sanjaya

Convert atomic types documentation to reST syntax:

* Add docs title
* Sentence-case headings
* List API functions in bullet list
* Mark-up notes and code blocks as appropriate

---
 .../{atomic_t.txt => core-api/atomic_t.rst}   | 211 ++++++++++--------
 Documentation/core-api/index.rst              |   2 +-
 Documentation/core-api/wrappers/atomic_t.rst  |  19 --
 3 files changed, 117 insertions(+), 115 deletions(-)
 rename Documentation/{atomic_t.txt => core-api/atomic_t.rst} (67%)
 delete mode 100644 Documentation/core-api/wrappers/atomic_t.rst
Documentation/core-api/atomic_t.rst renamed from Documentation/atomic_t.txt +116 -95
similarity index 67%
rename from Documentation/atomic_t.txt
rename to Documentation/core-api/atomic_t.rst
index bee3b1bca9a7b4..1f088eb2179c6c 100644
@@ -1,63 +1,66 @@
+.. SPDX-License-Identifier: GPL-2.0
 
-On atomic types (atomic_t atomic64_t and atomic_long_t).
+============
+Atomic types
+============
 
 The atomic type provides an interface to the architecture's means of atomic
 RMW operations between CPUs (atomic operations on MMIO are not supported and
 can lead to fatal traps on some platforms).
 
 API
----
+===
 
-The 'full' API consists of (atomic64_ and atomic_long_ prefixes omitted for
+The 'full' API consists of (atomic64\_ and atomic_long\_ prefixes omitted for
 brevity):
 
-Non-RMW ops:
+* Non-RMW ops:
 
-  atomic_read(), atomic_set()
-  atomic_read_acquire(), atomic_set_release()
+  * atomic_read(), atomic_set()
+  * atomic_read_acquire(), atomic_set_release()
 
 
-RMW atomic operations:
+* RMW atomic operations:
 
-Arithmetic:
+  * Arithmetic:
 
-  atomic_{add,sub,inc,dec}()
-  atomic_{add,sub,inc,dec}_return{,_relaxed,_acquire,_release}()
-  atomic_fetch_{add,sub,inc,dec}{,_relaxed,_acquire,_release}()
+    * atomic_{add,sub,inc,dec}()
+    * atomic_{add,sub,inc,dec}_return{,_relaxed,_acquire,_release}()
+    * atomic_fetch_{add,sub,inc,dec}{,_relaxed,_acquire,_release}()
 
 
-Bitwise:
+  * Bitwise:
 
-  atomic_{and,or,xor,andnot}()
-  atomic_fetch_{and,or,xor,andnot}{,_relaxed,_acquire,_release}()
+    * atomic_{and,or,xor,andnot}()
+    * atomic_fetch_{and,or,xor,andnot}{,_relaxed,_acquire,_release}()
 
 
-Swap:
+  * Swap:
 
-  atomic_xchg{,_relaxed,_acquire,_release}()
-  atomic_cmpxchg{,_relaxed,_acquire,_release}()
-  atomic_try_cmpxchg{,_relaxed,_acquire,_release}()
+    * atomic_xchg{,_relaxed,_acquire,_release}()
+    * atomic_cmpxchg{,_relaxed,_acquire,_release}()
+    * atomic_try_cmpxchg{,_relaxed,_acquire,_release}()
 
 
-Reference count (but please see refcount_t):
+  * Reference count (but please see refcount_t):
 
-  atomic_add_unless(), atomic_inc_not_zero()
-  atomic_sub_and_test(), atomic_dec_and_test()
+    * atomic_add_unless(), atomic_inc_not_zero()
+    * atomic_sub_and_test(), atomic_dec_and_test()
 
 
-Misc:
+  * Misc:
 
-  atomic_inc_and_test(), atomic_add_negative()
-  atomic_dec_unless_positive(), atomic_inc_unless_negative()
+    * atomic_inc_and_test(), atomic_add_negative()
+    * atomic_dec_unless_positive(), atomic_inc_unless_negative()
 
 
-Barriers:
+* Barriers:
 
-  smp_mb__{before,after}_atomic()
+  * smp_mb__{before,after}_atomic()
 
 
-TYPES (signed vs unsigned)
------
+Types (signed vs unsigned)
+==========================
 
 While atomic_t, atomic_long_t and atomic64_t use int, long and s64
 respectively (for hysterical raisins), the kernel uses -fno-strict-overflow
@@ -74,10 +77,11 @@ With this we also conform to the C/C++ _Atomic behaviour and things like
 P1236R1.
 
 
-SEMANTICS
----------
+Semantics
+=========
 
-Non-RMW ops:
+Non-RMW ops
+-----------
 
 The non-RMW ops are (typically) regular LOADs and STOREs and are canonically
 implemented using READ_ONCE(), WRITE_ONCE(), smp_load_acquire() and
@@ -86,7 +90,7 @@ the Non-RMW operations of atomic_t, you do not in fact need atomic_t at all
 and are doing it wrong.
 
 A note for the implementation of atomic_set{}() is that it must not break the
-atomicity of the RMW ops. That is:
+atomicity of the RMW ops. That is::
 
   C Atomic-RMW-ops-are-atomic-WRT-atomic_set
 
@@ -109,14 +113,14 @@ atomicity of the RMW ops. That is:
 
 In this case we would expect the atomic_set() from CPU1 to either happen
 before the atomic_add_unless(), in which case that latter one would no-op, or
-_after_ in which case we'd overwrite its result. In no case is "2" a valid
+**after** in which case we'd overwrite its result. In no case is "2" a valid
 outcome.
 
 This is typically true on 'normal' platforms, where a regular competing STORE
 will invalidate a LL/SC or fail a CMPXCHG.
 
 The obvious case where this is not so is when we need to implement atomic ops
-with a lock:
+with a lock::
 
   CPU0						CPU1
 
@@ -131,7 +135,8 @@ with a lock:
 the typical solution is to then implement atomic_set{}() with atomic_xchg().
 
 
-RMW ops:
+RMW ops
+-------
 
 These come in various forms:
 
@@ -148,7 +153,7 @@ These come in various forms:
  - swap operations: xchg(), cmpxchg() and try_cmpxchg()
 
  - misc; the special purpose operations that are commonly used and would,
-   given the interface, normally be implemented using (try_)cmpxchg loops but
+   given the interface, normally be implemented using (try\_)cmpxchg loops but
    are time critical and can, (typically) on LL/SC architectures, be more
    efficiently implemented.
 
@@ -157,25 +162,27 @@ atomic variable) can be fully ordered and no intermediate state is lost or
 visible.
 
 
-ORDERING  (go read memory-barriers.txt first)
---------
+Ordering
+========
+
+.. note::
+   Go read Documentation/core-api/memory-barriers.rst first if you
+   don't have yet grasped intricacies of operations involving
+   memory barriers.
 
 The rule of thumb:
 
  - non-RMW operations are unordered;
-
  - RMW operations that have no return value are unordered;
-
  - RMW operations that have a return value are fully ordered;
-
  - RMW operations that are conditional are unordered on FAILURE,
    otherwise the above rules apply.
 
 Except of course when a successful operation has an explicit ordering like:
 
- {}_relaxed: unordered
- {}_acquire: the R of the RMW (or atomic_read) is an ACQUIRE
- {}_release: the W of the RMW (or atomic_set)  is a  RELEASE
+ - {}_relaxed: unordered
+ - {}_acquire: the R of the RMW (or atomic_read) is an ACQUIRE
+ - {}_release: the W of the RMW (or atomic_set)  is a  RELEASE
 
 Where 'unordered' is against other memory locations. Address dependencies are
 not defeated.  Conditional operations are still unordered on FAILURE.
@@ -185,7 +192,7 @@ subsequent. Therefore a fully ordered primitive is like having an smp_mb()
 before and an smp_mb() after the primitive.
 
 
-The barriers:
+The barriers::
 
   smp_mb__{before,after}_atomic()
 
@@ -202,14 +209,15 @@ These helper barriers exist because architectures have varying implicit
 ordering on their SMP atomic primitives. For example our TSO architectures
 provide full ordered atomics and these barriers are no-ops.
 
-NOTE: when the atomic RmW ops are fully ordered, they should also imply a
-compiler barrier.
+.. note::
+   When the atomic RmW ops are fully ordered, they should also imply a
+   compiler barrier.
 
-Thus:
+Thus::
 
   atomic_fetch_add();
 
-is equivalent to:
+is equivalent to::
 
   smp_mb__before_atomic();
   atomic_fetch_add_relaxed();
@@ -217,7 +225,7 @@ is equivalent to:
 
 However the atomic_fetch_add() might be implemented more efficiently.
 
-Further, while something like:
+Further, while something like::
 
   smp_mb__before_atomic();
   atomic_dec(&X);
@@ -225,13 +233,13 @@ Further, while something like:
 is a 'typical' RELEASE pattern, the barrier is strictly stronger than
 a RELEASE because it orders preceding instructions against both the read
 and write parts of the atomic_dec(), and against all following instructions
-as well. Similarly, something like:
+as well. Similarly, something like::
 
   atomic_inc(&X);
   smp_mb__after_atomic();
 
 is an ACQUIRE pattern (though very much not typical), but again the barrier is
-strictly stronger than ACQUIRE. As illustrated:
+strictly stronger than ACQUIRE. As illustrated::
 
   C Atomic-RMW+mb__after_atomic-is-stronger-than-acquire
 
@@ -258,7 +266,7 @@ strictly stronger than ACQUIRE. As illustrated:
 This should not happen; but a hypothetical atomic_inc_acquire() --
 (void)atomic_fetch_inc_acquire() for instance -- would allow the outcome,
 because it would not order the W part of the RMW against the following
-WRITE_ONCE.  Thus:
+WRITE_ONCE.  Thus::
 
   P0			P1
 
@@ -273,34 +281,42 @@ WRITE_ONCE.  Thus:
 is allowed.
 
 
-CMPXCHG vs TRY_CMPXCHG
-----------------------
+cmpxchg vs try_cmpxchg
+======================
 
-  int atomic_cmpxchg(atomic_t *ptr, int old, int new);
-  bool atomic_try_cmpxchg(atomic_t *ptr, int *oldp, int new);
+.. code-block:: c
+
+   int atomic_cmpxchg(atomic_t *ptr, int old, int new);
+   bool atomic_try_cmpxchg(atomic_t *ptr, int *oldp, int new);
 
 Both provide the same functionality, but try_cmpxchg() can lead to more
 compact code. The functions relate like:
 
-  bool atomic_try_cmpxchg(atomic_t *ptr, int *oldp, int new)
-  {
-    int ret, old = *oldp;
-    ret = atomic_cmpxchg(ptr, old, new);
-    if (ret != old)
-      *oldp = ret;
-    return ret == old;
-  }
+.. code-block:: c
+
+   bool atomic_try_cmpxchg(atomic_t *ptr, int *oldp, int new)
+   {
+     int ret, old = *oldp;
+     ret = atomic_cmpxchg(ptr, old, new);
+     if (ret != old)
+       *oldp = ret;
+     return ret == old;
+   }
 
 and:
 
-  int atomic_cmpxchg(atomic_t *ptr, int old, int new)
-  {
-    (void)atomic_try_cmpxchg(ptr, &old, new);
-    return old;
-  }
+.. code-block:: c
+
+   int atomic_cmpxchg(atomic_t *ptr, int old, int new)
+   {
+     (void)atomic_try_cmpxchg(ptr, &old, new);
+     return old;
+   }
 
 Usage:
 
+.. code-block:: c
+
   old = atomic_read(&v);			old = atomic_read(&v);
   for (;;) {					do {
     new = func(old);				  new = func(old);
@@ -310,12 +326,13 @@ Usage:
     old = tmp;
   }
 
-NB. try_cmpxchg() also generates better code on some platforms (notably x86)
-where the function more closely matches the hardware instruction.
+.. note::
+   try_cmpxchg() also generates better code on some platforms (notably x86)
+   where the function more closely matches the hardware instruction.
 
 
-FORWARD PROGRESS
-----------------
+Forward Progress
+================
 
 In general strong forward progress is expected of all unconditional atomic
 operations -- those in the Arithmetic and Bitwise classes and xchg(). However
@@ -328,30 +345,34 @@ while an LL/SC architecture 'can/should/must' provide forward progress
 guarantees between competing LL/SC sections, such a guarantee does not
 transfer to cmpxchg() implemented using LL/SC. Consider:
 
-  old = atomic_read(&v);
-  do {
-    new = func(old);
-  } while (!atomic_try_cmpxchg(&v, &old, new));
+.. code-block:: c
+
+   old = atomic_read(&v);
+   do {
+     new = func(old);
+   } while (!atomic_try_cmpxchg(&v, &old, new));
 
 which on LL/SC becomes something like:
 
-  old = atomic_read(&v);
-  do {
-    new = func(old);
-  } while (!({
-    volatile asm ("1: LL  %[oldval], %[v]\n"
-                  "   CMP %[oldval], %[old]\n"
-                  "   BNE 2f\n"
-                  "   SC  %[new], %[v]\n"
-                  "   BNE 1b\n"
-                  "2:\n"
-                  : [oldval] "=&r" (oldval), [v] "m" (v)
-		  : [old] "r" (old), [new] "r" (new)
-                  : "memory");
-    success = (oldval == old);
-    if (!success)
-      old = oldval;
-    success; }));
+.. code-block:: c
+
+   old = atomic_read(&v);
+   do {
+     new = func(old);
+   } while (!({
+     volatile asm ("1: LL  %[oldval], %[v]\n"
+                   "   CMP %[oldval], %[old]\n"
+                   "   BNE 2f\n"
+                   "   SC  %[new], %[v]\n"
+                   "   BNE 1b\n"
+                   "2:\n"
+                   : [oldval] "=&r" (oldval), [v] "m" (v)
+                   : [old] "r" (old), [new] "r" (new)
+                   : "memory");
+     success = (oldval == old);
+     if (!success)
+       old = oldval;
+     success; }));
 
 However, even the forward branch from the failed compare can cause the LL/SC
 to fail on some architectures, let alone whatever the compiler makes of the C
Documentation/core-api/index.rst +1 -1
index 4bc132fefaab7f..6f15593d6889d4 100644
@@ -48,7 +48,7 @@ Library functionality that is used throughout the kernel.
    this_cpu_ops
    timekeeping
    errseq
-   wrappers/atomic_t
+   atomic_t
    atomic_bitops
    floating-point
    union_find
Documentation/core-api/wrappers/atomic_t.rst deleted +0 -19
deleted file mode 100644
index ed109a964c7789..00000000000000
@@ -1,19 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-   This is a simple wrapper to bring atomic_t.txt into the RST world
-   until such a time as that file can be converted directly.
-
-============
-Atomic types
-============
-
-.. raw:: latex
-
-    \footnotesize
-
-.. include:: ../../atomic_t.txt
-   :literal:
-
-.. raw:: latex
-
-    \normalsize
-
Signature · 1 line
An old man doll... just what I always wanted! - Clara
#5 lore raw

PATCH 4/4 Documentation: atomic_bitops, atomic_t, memory-barriers: Link to newly-converted docs

In reply to Bagas Sanjaya

Now that both atomic bitops, atomic types, and memory barriers docs have been converted, cross-reference them.

---
 Documentation/RCU/rcu_dereference.rst         |  2 +-
 Documentation/core-api/atomic_bitops.rst      |  6 ++++--
 Documentation/core-api/circular-buffers.rst   |  4 ++--
 Documentation/core-api/memory-barriers.rst    | 16 +++++++++-------
 Documentation/core-api/refcount-vs-atomic.rst |  5 +++--
 Documentation/driver-api/device-io.rst        |  4 ++--
 Documentation/locking/spinlocks.rst           |  5 ++---
 Documentation/virt/kvm/vcpu-requests.rst      |  4 ++--
 8 files changed, 25 insertions(+), 21 deletions(-)
Documentation/RCU/rcu_dereference.rst +1 -1
index 2524dcdadde2b8..dca197d689d78f 100644
@@ -192,7 +192,7 @@ readers working properly:
 		so that a control dependency preserves the needed ordering.
 		That said, it is easy to get control dependencies wrong.
 		Please see the "CONTROL DEPENDENCIES" section of
-		Documentation/memory-barriers.txt for more details.
+		Documentation/core-api/memory-barriers.rst for more details.
 
 	-	The pointers are not equal *and* the compiler does
 		not have enough information to deduce the value of the
Documentation/core-api/atomic_bitops.rst +4 -2
index b93c388fd9bdc4..7f58c31a37a938 100644
@@ -41,7 +41,8 @@ Semantics
 * Non-atomic ops:
 
   In particular __clear_bit_unlock() suffers the same issue as atomic_set(),
-  which is why the generic version maps to clear_bit_unlock(), see atomic_t.txt.
+  which is why the generic version maps to clear_bit_unlock(), see
+  Documentation/core-api/atomic_t.rst.
 
 
 * RMW ops:
@@ -64,5 +65,6 @@ clear_bit_unlock() which has RELEASE semantics and test_bit_acquire which has
 ACQUIRE semantics.
 
 Since a platform only has a single means of achieving atomic operations
-the same barriers as for atomic_t are used, see atomic_t.txt.
+the same barriers as for atomic_t are used, see
+Documentation/core-api/atomic_t.rst.
 
Documentation/core-api/circular-buffers.rst +2 -2
index 50966f66e39829..3dc18a9f7dcf8a 100644
@@ -233,5 +233,5 @@ against previous accesses.
 Further reading
 ===============
 
-See also Documentation/memory-barriers.txt for a description of Linux's memory
-barrier facilities.
+See also Documentation/core-api/memory-barriers.rst for a description of
+Linux's memory barrier facilities.
Documentation/core-api/memory-barriers.rst +9 -7
index da8e682dc58d86..afb9bee0b80c4b 100644
@@ -481,11 +481,12 @@ And a couple of implicit varieties:
      This means that ACQUIRE acts as a minimal "acquire" operation and
      RELEASE acts as a minimal "release" operation.
 
-A subset of the atomic operations described in atomic_t.txt have ACQUIRE and
-RELEASE variants in addition to fully-ordered and relaxed (no barrier
-semantics) definitions.  For compound atomics performing both a load and a
-store, ACQUIRE semantics apply only to the load and RELEASE semantics apply
-only to the store portion of the operation.
+A subset of the atomic operations described in
+Documentation/core-api/atomic_t.rst have ACQUIRE and RELEASE variants in
+addition to fully-ordered and relaxed (no barrier semantics) definitions.
+For compound atomics performing both a load and a store, ACQUIRE semantics
+apply only to the load and RELEASE semantics apply only to the store portion
+of the operation.
 
 Memory barriers are only required where there's a possibility of interaction
 between two CPUs or between a CPU and a device.  If it can be guaranteed that
@@ -1972,7 +1973,8 @@ There are some more advanced barrier functions:
    This makes sure that the death mark on the object is perceived to be set
    *before* the reference counter is decremented.
 
-   See Documentation/atomic_{t,bitops}.txt for more information.
+   See Documentation/core-api/atomic_t.rst and
+   Documentation/core-api/atomic_bitops.rst for more information.
 
 
  * dma_wmb();
@@ -2549,7 +2551,7 @@ operations are noted specially as some of them imply full memory barriers and
 some don't, but they're very heavily relied on as a group throughout the
 kernel.
 
-See Documentation/atomic_t.txt for more information.
+See Documentation/core-api/atomic_t.rst for more information.
 
 
 Accessing Devices
Documentation/core-api/refcount-vs-atomic.rst +3 -2
index 94e628c1eb4975..28f5d6f80d19d0 100644
@@ -19,7 +19,8 @@ these memory ordering guarantees.
 The terms used through this document try to follow the formal LKMM defined in
 tools/memory-model/Documentation/explanation.txt.
 
-memory-barriers.txt and atomic_t.txt provide more background to the
+Documentation/core-api/memory-barriers.rst and
+Documentation/core-api/atomic_t.rst provide more background to the
 memory ordering in general and for atomic operations specifically.
 
 Relevant types of memory ordering
@@ -28,7 +29,7 @@ Relevant types of memory ordering
 .. note:: The following section only covers some of the memory
    ordering types that are relevant for the atomics and reference
    counters and used through this document. For a much broader picture
-   please consult memory-barriers.txt document.
+   please consult Documentation/core-api/memory-barriers.rst.
 
 In the absence of any memory ordering guarantees (i.e. fully unordered)
 atomics & refcounters only provide atomicity and
Documentation/driver-api/device-io.rst +2 -2
index 5c7e8194bef92b..9e27f64ce7b8b1 100644
@@ -186,8 +186,8 @@ writeq_relaxed(), writel_relaxed(), writew_relaxed(), writeb_relaxed()
   comment that explains why the usage in a specific location is safe without
   the extra barriers.
 
-  See memory-barriers.txt for a more detailed discussion on the precise ordering
-  guarantees of the non-relaxed and relaxed versions.
+  See Documentation/core-api/memory-barriers.rst for a more detailed discussion
+  on the precise ordering guarantees of the non-relaxed and relaxed versions.
 
 ioread64(), ioread32(), ioread16(), ioread8(),
 iowrite64(), iowrite32(), iowrite16(), iowrite8()
Documentation/locking/spinlocks.rst +2 -3
index bec96f7a9f2d7a..8cb1bf557a30e9 100644
@@ -21,9 +21,8 @@ there is only one thread-of-control within the region(s) protected by that
 lock. This works well even under UP also, so the code does _not_ need to
 worry about UP vs SMP issues: the spinlocks work correctly under both.
 
-   NOTE! Implications of spin_locks for memory are further described in:
-
-     Documentation/memory-barriers.txt
+   NOTE! Implications of spin_locks for memory are further described in
+   Documentation/core-api/memory-barriers.rst.
 
        (5) ACQUIRE operations.
 
Documentation/virt/kvm/vcpu-requests.rst +2 -2
index 06718b9bc95977..0dd1308dc5252a 100644
@@ -289,6 +289,6 @@ architectures a function where requests may be checked if necessary.
 References
 ==========
 
-.. [atomic-ops] Documentation/atomic_bitops.txt and Documentation/atomic_t.txt
-.. [memory-barriers] Documentation/memory-barriers.txt
+.. [atomic-ops] Documentation/core-api/atomic_bitops.rst and Documentation/core-api/atomic_t.rst
+.. [memory-barriers] Documentation/core-api/memory-barriers.rst
 .. [lwn-mb] https://lwn.net/Articles/573436/
Signature · 1 line
An old man doll... just what I always wanted! - Clara
maintainer NAK
#6 lore raw
In reply to Bagas Sanjaya
Quoted 11 lines · Bagas Sanjaya

Atomic types, atomic bitops, and memory barriers docs are included in kernel docs build since commit e40573a43d163a ("docs: put atomic*.txt and memory-barriers.txt into the core-api book") as a wrapper stub for corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs.

Bagas Sanjaya (4):
Documentation: memory-barriers: Convert to reST format
Documentation: atomic_bitops: Convert to reST format
Documentation: atomic_t: Convert to reST format
Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
newly-converted docs

NAK

If these are merged I will no longer touch / update these files.

#7 lore raw
Quoted 11 lines · Peter Zijlstra
Quoted 6 lines · Bagas Sanjaya

Bagas Sanjaya (4):
Documentation: memory-barriers: Convert to reST format
Documentation: atomic_bitops: Convert to reST format
Documentation: atomic_t: Convert to reST format
Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
newly-converted docs

NAK

If these are merged I will no longer touch / update these files.

Why? Do you mean these docs should be kept as-is (not converted)? Jon wrote in e40573a43d163a that the conversion were opposed but AFAIK I can't find the rationale on lore.

Thanks.

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#8 lore raw
Quoted 9 lines · Bagas Sanjaya
Quoted 8 lines · Peter Zijlstra
Quoted 6 lines · Bagas Sanjaya

Bagas Sanjaya (4):
Documentation: memory-barriers: Convert to reST format
Documentation: atomic_bitops: Convert to reST format
Documentation: atomic_t: Convert to reST format
Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
newly-converted docs

Quoted 7 lines
Quoted 3 lines

NAK

If these are merged I will no longer touch / update these files.

Why? Do you mean these docs should be kept as-is (not converted)? Jon wrote in e40573a43d163a that the conversion were opposed but AFAIK I can't find the rationale on lore.

Here's one:

https://lore.kernel.org/all/[email protected]/

Vegard

#9 lore raw
Quoted 14 lines · Vegard Nossum
Quoted 13 lines · Bagas Sanjaya
Quoted 11 lines · Peter Zijlstra
Quoted 6 lines · Bagas Sanjaya

Bagas Sanjaya (4):
Documentation: memory-barriers: Convert to reST format
Documentation: atomic_bitops: Convert to reST format
Documentation: atomic_t: Convert to reST format
Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
newly-converted docs

NAK

If these are merged I will no longer touch / update these files.

Quoted 7 lines
Quoted 3 lines

Why? Do you mean these docs should be kept as-is (not converted)? Jon wrote in e40573a43d163a that the conversion were opposed but AFAIK I can't find the rationale on lore.

Here's one:

https://lore.kernel.org/all/[email protected]/

OK, thanks!

Signature · 1 line
An old man doll... just what I always wanted! - Clara
#10 lore raw
In reply to Peter Zijlstra
Quoted 13 lines · On Thu, 17 Jul 2025 12:55:54 +0200 Peter Zijlstra <[email protected]> wrote:
Quoted 11 lines · Bagas Sanjaya

Atomic types, atomic bitops, and memory barriers docs are included in kernel docs build since commit e40573a43d163a ("docs: put atomic*.txt and memory-barriers.txt into the core-api book") as a wrapper stub for corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs.

Bagas Sanjaya (4):
Documentation: memory-barriers: Convert to reST format
Documentation: atomic_bitops: Convert to reST format
Documentation: atomic_t: Convert to reST format
Documentation: atomic_bitops, atomic_t, memory-barriers: Link to
newly-converted docs

Quoted 3 lines

NAK

If these are merged I will no longer touch / update these files.

One way a human discovers why something is the way it is, is to change it, and see what the fallout is for that change.

;-)

-- Steve

maintainer
#11 lore raw
In reply to Bagas Sanjaya
Quoted 4 lines · Bagas Sanjaya

Atomic types, atomic bitops, and memory barriers docs are included in kernel docs build since commit e40573a43d163a ("docs: put atomic*.txt and memory-barriers.txt into the core-api book") as a wrapper stub for corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs.

Did it occur to you to look at the changelog for the commit you cite, which explains why those documents are handled the way they are...?

jon

maintainer
#12 lore raw
Quoted 9 lines · Jonathan Corbet
Quoted 4 lines · Bagas Sanjaya

Atomic types, atomic bitops, and memory barriers docs are included in kernel docs build since commit e40573a43d163a ("docs: put atomic*.txt and memory-barriers.txt into the core-api book") as a wrapper stub for corresponding uncoverted txt docs. Let's turn them into full-fledged reST docs.

Did it occur to you to look at the changelog for the commit you cite, which explains why those documents are handled the way they are...?

I'm sorry, that caught me at the wrong time, and I was rather more harsh than I should have been. I should not have responded that way.

For future reference, though, when somebody has gone out of their way to accomplish a task in a specific way, there usually *is* a reason for it. If you can't find that reason, the best thing to do is usually to ask.

Thanks,

jon