[PATCH 4/4] Documentation: atomic_bitops, atomic_t, memory-barriers: Link to newly-converted docs
From: Bagas Sanjaya <hidden>
Date: 2025-07-17 08:07:04
Also in:
kvm, linux-arch, lkml, rcu
Subsystem:
documentation, kernel virtual machine (kvm), linux kernel memory consistency model (lkmm), locking primitives, read-copy update (rcu), the rest · Maintainers:
Jonathan Corbet, Paolo Bonzini, Alan Stern, Andrea Parri, Will Deacon, Peter Zijlstra, Boqun Feng, Nicholas Piggin, David Howells, Jade Alglave, Luc Maranget, "Paul E. McKenney", Ingo Molnar, Frederic Weisbecker, Neeraj Upadhyay, Joel Fernandes, Josh Triplett, Uladzislau Rezki, Linus Torvalds
Now that both atomic bitops, atomic types, and memory barriers docs have been converted, cross-reference them. Signed-off-by: Bagas Sanjaya <redacted> --- 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(-)
diff --git a/Documentation/RCU/rcu_dereference.rst b/Documentation/RCU/rcu_dereference.rst
index 2524dcdadde2b8..dca197d689d78f 100644
--- a/Documentation/RCU/rcu_dereference.rst
+++ b/Documentation/RCU/rcu_dereference.rst@@ -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
diff --git a/Documentation/core-api/atomic_bitops.rst b/Documentation/core-api/atomic_bitops.rst
index b93c388fd9bdc4..7f58c31a37a938 100644
--- a/Documentation/core-api/atomic_bitops.rst
+++ b/Documentation/core-api/atomic_bitops.rst@@ -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.
diff --git a/Documentation/core-api/circular-buffers.rst b/Documentation/core-api/circular-buffers.rst
index 50966f66e39829..3dc18a9f7dcf8a 100644
--- a/Documentation/core-api/circular-buffers.rst
+++ b/Documentation/core-api/circular-buffers.rst@@ -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.
diff --git a/Documentation/core-api/memory-barriers.rst b/Documentation/core-api/memory-barriers.rst
index da8e682dc58d86..afb9bee0b80c4b 100644
--- a/Documentation/core-api/memory-barriers.rst
+++ b/Documentation/core-api/memory-barriers.rst@@ -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
diff --git a/Documentation/core-api/refcount-vs-atomic.rst b/Documentation/core-api/refcount-vs-atomic.rst
index 94e628c1eb4975..28f5d6f80d19d0 100644
--- a/Documentation/core-api/refcount-vs-atomic.rst
+++ b/Documentation/core-api/refcount-vs-atomic.rst@@ -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
diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst
index 5c7e8194bef92b..9e27f64ce7b8b1 100644
--- a/Documentation/driver-api/device-io.rst
+++ b/Documentation/driver-api/device-io.rst@@ -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()
diff --git a/Documentation/locking/spinlocks.rst b/Documentation/locking/spinlocks.rst
index bec96f7a9f2d7a..8cb1bf557a30e9 100644
--- a/Documentation/locking/spinlocks.rst
+++ b/Documentation/locking/spinlocks.rst@@ -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.
diff --git a/Documentation/virt/kvm/vcpu-requests.rst b/Documentation/virt/kvm/vcpu-requests.rst
index 06718b9bc95977..0dd1308dc5252a 100644
--- a/Documentation/virt/kvm/vcpu-requests.rst
+++ b/Documentation/virt/kvm/vcpu-requests.rst@@ -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/
--
An old man doll... just what I always wanted! - Clara