From: Bagas Sanjaya <bagasdotme@gmail.com>
To: Linux Kernel Mailing List <linux-kernel@vger.kernel.org>,
Linux Documentation <linux-doc@vger.kernel.org>,
Linux RCU <rcu@vger.kernel.org>,
Linux CPU Architectures Development <linux-arch@vger.kernel.org>,
Linux LKMM <lkmm@lists.linux.dev>,
Linux KVM <kvm@vger.kernel.org>
Cc: "Paul E. McKenney" <paulmck@kernel.org>,
Frederic Weisbecker <frederic@kernel.org>,
Neeraj Upadhyay <neeraj.upadhyay@kernel.org>,
Joel Fernandes <joelagnelf@nvidia.com>,
Josh Triplett <josh@joshtriplett.org>,
Boqun Feng <boqun.feng@gmail.com>,
Uladzislau Rezki <urezki@gmail.com>,
Steven Rostedt <rostedt@goodmis.org>,
Mathieu Desnoyers <mathieu.desnoyers@efficios.com>,
Lai Jiangshan <jiangshanlai@gmail.com>,
Zqiang <qiang.zhang@linux.dev>, Jonathan Corbet <corbet@lwn.net>,
Alan Stern <stern@rowland.harvard.edu>,
Andrea Parri <parri.andrea@gmail.com>,
Will Deacon <will@kernel.org>,
Peter Zijlstra <peterz@infradead.org>,
Nicholas Piggin <npiggin@gmail.com>,
David Howells <dhowells@redhat.com>,
Jade Alglave <j.alglave@ucl.ac.uk>,
Luc Maranget <luc.maranget@inria.fr>,
Akira Yokosawa <akiyks@gmail.com>,
Daniel Lustig <dlustig@nvidia.com>,
Mark Rutland <mark.rutland@arm.com>,
Ingo Molnar <mingo@redhat.com>, Waiman Long <longman@redhat.com>,
Paolo Bonzini <pbonzini@redhat.com>,
Bagas Sanjaya <bagasdotme@gmail.com>,
Andrew Morton <akpm@linux-foundation.org>,
Tejun Heo <tj@kernel.org>,
"Mike Rapoport (Microsoft)" <rppt@kernel.org>,
Changyuan Lyu <changyuanl@google.com>,
Dan Williams <dan.j.williams@intel.com>,
Xavier <xavier_qy@163.com>, Randy Dunlap <rdunlap@infradead.org>,
Maarten Lankhorst <dev@lankhorst.se>,
Christian Brauner <brauner@kernel.org>
Subject: [PATCH 4/4] Documentation: atomic_bitops, atomic_t, memory-barriers: Link to newly-converted docs
Date: Thu, 17 Jul 2025 15:06:17 +0700 [thread overview]
Message-ID: <20250717080617.35577-5-bagasdotme@gmail.com> (raw)
In-Reply-To: <20250717080617.35577-1-bagasdotme@gmail.com>
Now that both atomic bitops, atomic types, and memory barriers docs have
been converted, cross-reference them.
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
---
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
next prev parent reply other threads:[~2025-07-17 8:07 UTC|newest]
Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-07-17 8:06 [PATCH 0/4] Convert atomic_*.txt and memory-barriers.txt to reST Bagas Sanjaya
2025-07-17 8:06 ` [PATCH 1/4] Documentation: memory-barriers: Convert to reST format Bagas Sanjaya
2025-07-17 13:30 ` David Howells
2025-07-17 8:06 ` [PATCH 2/4] Documentation: atomic_bitops: " Bagas Sanjaya
2025-07-17 8:06 ` [PATCH 3/4] Documentation: atomic_t: " Bagas Sanjaya
2025-07-17 8:06 ` Bagas Sanjaya [this message]
2025-07-17 10:55 ` [PATCH 0/4] Convert atomic_*.txt and memory-barriers.txt to reST Peter Zijlstra
2025-07-17 11:26 ` Bagas Sanjaya
2025-07-17 11:56 ` Vegard Nossum
2025-07-19 7:08 ` Bagas Sanjaya
2025-07-17 12:32 ` Steven Rostedt
2025-07-17 13:34 ` Jonathan Corbet
2025-07-17 20:15 ` 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=20250717080617.35577-5-bagasdotme@gmail.com \
--to=bagasdotme@gmail.com \
--cc=akiyks@gmail.com \
--cc=akpm@linux-foundation.org \
--cc=boqun.feng@gmail.com \
--cc=brauner@kernel.org \
--cc=changyuanl@google.com \
--cc=corbet@lwn.net \
--cc=dan.j.williams@intel.com \
--cc=dev@lankhorst.se \
--cc=dhowells@redhat.com \
--cc=dlustig@nvidia.com \
--cc=frederic@kernel.org \
--cc=j.alglave@ucl.ac.uk \
--cc=jiangshanlai@gmail.com \
--cc=joelagnelf@nvidia.com \
--cc=josh@joshtriplett.org \
--cc=kvm@vger.kernel.org \
--cc=linux-arch@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=lkmm@lists.linux.dev \
--cc=longman@redhat.com \
--cc=luc.maranget@inria.fr \
--cc=mark.rutland@arm.com \
--cc=mathieu.desnoyers@efficios.com \
--cc=mingo@redhat.com \
--cc=neeraj.upadhyay@kernel.org \
--cc=npiggin@gmail.com \
--cc=parri.andrea@gmail.com \
--cc=paulmck@kernel.org \
--cc=pbonzini@redhat.com \
--cc=peterz@infradead.org \
--cc=qiang.zhang@linux.dev \
--cc=rcu@vger.kernel.org \
--cc=rdunlap@infradead.org \
--cc=rostedt@goodmis.org \
--cc=rppt@kernel.org \
--cc=stern@rowland.harvard.edu \
--cc=tj@kernel.org \
--cc=urezki@gmail.com \
--cc=will@kernel.org \
--cc=xavier_qy@163.com \
/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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.