Commit 9d3a0485 authored by Paul Gortmaker's avatar Paul Gortmaker Committed by Paul E. McKenney

docs: Fix typos and drop/fix dead links in RCU documentation

It appears the Compaq link moved to a machine at HP for a while
after the merger of the two, but that doesn't work either.  A search
of HP for "wiz_2637" (w and w/o html suffix) comes up empty.

Since the references aren't critical to the documents we remove them.

Also, the lkml.kernel.org/g links have been broken for ages, so replace
them with lore.kernel.org/r links - standardize on lore for all links too.

Note that we put off fixing these 4y ago - presumably thinking that a
treewide fixup was pending.  Probably safe to go fix the RCU ones now.

https://lore.kernel.org/r/20160915144926.GD10850@linux.vnet.ibm.com/

Cc: Michael Opdenacker <michael.opdenacker@free-electrons.com>
Cc: Steven Rostedt <rostedt@goodmis.org>
Cc: "Paul E. McKenney" <paulmck@linux.vnet.ibm.com>
Signed-off-by: default avatarPaul Gortmaker <paul.gortmaker@windriver.com>
Signed-off-by: default avatarPaul E. McKenney <paulmck@kernel.org>
parent 4704bd31
...@@ -321,11 +321,10 @@ do_something_gp_buggy() below: ...@@ -321,11 +321,10 @@ do_something_gp_buggy() below:
12 } 12 }
However, this temptation must be resisted because there are a However, this temptation must be resisted because there are a
surprisingly large number of ways that the compiler (to say nothing of surprisingly large number of ways that the compiler (or weak ordering
`DEC Alpha CPUs <https://h71000.www7.hp.com/wizard/wiz_2637.html>`__) CPUs like the DEC Alpha) can trip this code up. For but one example, if
can trip this code up. For but one example, if the compiler were short the compiler were short of registers, it might choose to refetch from
of registers, it might choose to refetch from ``gp`` rather than keeping ``gp`` rather than keeping a separate copy in ``p`` as follows:
a separate copy in ``p`` as follows:
:: ::
...@@ -1183,7 +1182,7 @@ costs have plummeted. However, as I learned from Matt Mackall's ...@@ -1183,7 +1182,7 @@ costs have plummeted. However, as I learned from Matt Mackall's
`bloatwatch <http://elinux.org/Linux_Tiny-FAQ>`__ efforts, memory `bloatwatch <http://elinux.org/Linux_Tiny-FAQ>`__ efforts, memory
footprint is critically important on single-CPU systems with footprint is critically important on single-CPU systems with
non-preemptible (``CONFIG_PREEMPT=n``) kernels, and thus `tiny non-preemptible (``CONFIG_PREEMPT=n``) kernels, and thus `tiny
RCU <https://lkml.kernel.org/g/20090113221724.GA15307@linux.vnet.ibm.com>`__ RCU <https://lore.kernel.org/r/20090113221724.GA15307@linux.vnet.ibm.com>`__
was born. Josh Triplett has since taken over the small-memory banner was born. Josh Triplett has since taken over the small-memory banner
with his `Linux kernel tinification <https://tiny.wiki.kernel.org/>`__ with his `Linux kernel tinification <https://tiny.wiki.kernel.org/>`__
project, which resulted in `SRCU <#Sleepable%20RCU>`__ becoming optional project, which resulted in `SRCU <#Sleepable%20RCU>`__ becoming optional
...@@ -1624,7 +1623,7 @@ against mishaps and misuse: ...@@ -1624,7 +1623,7 @@ against mishaps and misuse:
init_rcu_head() and cleaned up with destroy_rcu_head(). init_rcu_head() and cleaned up with destroy_rcu_head().
Mathieu Desnoyers made me aware of this requirement, and also Mathieu Desnoyers made me aware of this requirement, and also
supplied the needed supplied the needed
`patch <https://lkml.kernel.org/g/20100319013024.GA28456@Krystal>`__. `patch <https://lore.kernel.org/r/20100319013024.GA28456@Krystal>`__.
#. An infinite loop in an RCU read-side critical section will eventually #. An infinite loop in an RCU read-side critical section will eventually
trigger an RCU CPU stall warning splat, with the duration of trigger an RCU CPU stall warning splat, with the duration of
“eventually” being controlled by the ``RCU_CPU_STALL_TIMEOUT`` “eventually” being controlled by the ``RCU_CPU_STALL_TIMEOUT``
...@@ -1716,7 +1715,7 @@ requires almost all of them be hidden behind a ``CONFIG_RCU_EXPERT`` ...@@ -1716,7 +1715,7 @@ requires almost all of them be hidden behind a ``CONFIG_RCU_EXPERT``
This all should be quite obvious, but the fact remains that Linus This all should be quite obvious, but the fact remains that Linus
Torvalds recently had to Torvalds recently had to
`remind <https://lkml.kernel.org/g/CA+55aFy4wcCwaL4okTs8wXhGZ5h-ibecy_Meg9C4MNQrUnwMcg@mail.gmail.com>`__ `remind <https://lore.kernel.org/r/CA+55aFy4wcCwaL4okTs8wXhGZ5h-ibecy_Meg9C4MNQrUnwMcg@mail.gmail.com>`__
me of this requirement. me of this requirement.
Firmware Interface Firmware Interface
...@@ -1837,9 +1836,9 @@ NMI handlers. ...@@ -1837,9 +1836,9 @@ NMI handlers.
The name notwithstanding, some Linux-kernel architectures can have The name notwithstanding, some Linux-kernel architectures can have
nested NMIs, which RCU must handle correctly. Andy Lutomirski `surprised nested NMIs, which RCU must handle correctly. Andy Lutomirski `surprised
me <https://lkml.kernel.org/r/CALCETrXLq1y7e_dKFPgou-FKHB6Pu-r8+t-6Ds+8=va7anBWDA@mail.gmail.com>`__ me <https://lore.kernel.org/r/CALCETrXLq1y7e_dKFPgou-FKHB6Pu-r8+t-6Ds+8=va7anBWDA@mail.gmail.com>`__
with this requirement; he also kindly surprised me with `an with this requirement; he also kindly surprised me with `an
algorithm <https://lkml.kernel.org/r/CALCETrXSY9JpW3uE6H8WYk81sg56qasA2aqmjMPsq5dOtzso=g@mail.gmail.com>`__ algorithm <https://lore.kernel.org/r/CALCETrXSY9JpW3uE6H8WYk81sg56qasA2aqmjMPsq5dOtzso=g@mail.gmail.com>`__
that meets this requirement. that meets this requirement.
Furthermore, NMI handlers can be interrupted by what appear to RCU to be Furthermore, NMI handlers can be interrupted by what appear to RCU to be
...@@ -2264,7 +2263,7 @@ more extreme measures. Returning to the ``page`` structure, the ...@@ -2264,7 +2263,7 @@ more extreme measures. Returning to the ``page`` structure, the
``rcu_head`` field shares storage with a great many other structures ``rcu_head`` field shares storage with a great many other structures
that are used at various points in the corresponding page's lifetime. In that are used at various points in the corresponding page's lifetime. In
order to correctly resolve certain `race order to correctly resolve certain `race
conditions <https://lkml.kernel.org/g/1439976106-137226-1-git-send-email-kirill.shutemov@linux.intel.com>`__, conditions <https://lore.kernel.org/r/1439976106-137226-1-git-send-email-kirill.shutemov@linux.intel.com>`__,
the Linux kernel's memory-management subsystem needs a particular bit to the Linux kernel's memory-management subsystem needs a particular bit to
remain zero during all phases of grace-period processing, and that bit remain zero during all phases of grace-period processing, and that bit
happens to map to the bottom bit of the ``rcu_head`` structure's happens to map to the bottom bit of the ``rcu_head`` structure's
...@@ -2328,7 +2327,7 @@ preempted. This requirement made its presence known after users made it ...@@ -2328,7 +2327,7 @@ preempted. This requirement made its presence known after users made it
clear that an earlier `real-time clear that an earlier `real-time
patch <https://lwn.net/Articles/107930/>`__ did not meet their needs, in patch <https://lwn.net/Articles/107930/>`__ did not meet their needs, in
conjunction with some `RCU conjunction with some `RCU
issues <https://lkml.kernel.org/g/20050318002026.GA2693@us.ibm.com>`__ issues <https://lore.kernel.org/r/20050318002026.GA2693@us.ibm.com>`__
encountered by a very early version of the -rt patchset. encountered by a very early version of the -rt patchset.
In addition, RCU must make do with a sub-100-microsecond real-time In addition, RCU must make do with a sub-100-microsecond real-time
......
...@@ -70,7 +70,7 @@ over a rather long period of time, but improvements are always welcome! ...@@ -70,7 +70,7 @@ over a rather long period of time, but improvements are always welcome!
is less readable and prevents lockdep from detecting locking issues. is less readable and prevents lockdep from detecting locking issues.
Letting RCU-protected pointers "leak" out of an RCU read-side Letting RCU-protected pointers "leak" out of an RCU read-side
critical section is every bid as bad as letting them leak out critical section is every bit as bad as letting them leak out
from under a lock. Unless, of course, you have arranged some from under a lock. Unless, of course, you have arranged some
other means of protection, such as a lock or a reference count other means of protection, such as a lock or a reference count
-before- letting them out of the RCU read-side critical section. -before- letting them out of the RCU read-side critical section.
...@@ -129,9 +129,7 @@ over a rather long period of time, but improvements are always welcome! ...@@ -129,9 +129,7 @@ over a rather long period of time, but improvements are always welcome!
accesses. The rcu_dereference() primitive ensures that accesses. The rcu_dereference() primitive ensures that
the CPU picks up the pointer before it picks up the data the CPU picks up the pointer before it picks up the data
that the pointer points to. This really is necessary that the pointer points to. This really is necessary
on Alpha CPUs. If you don't believe me, see: on Alpha CPUs.
http://www.openvms.compaq.com/wizard/wiz_2637.html
The rcu_dereference() primitive is also an excellent The rcu_dereference() primitive is also an excellent
documentation aid, letting the person reading the documentation aid, letting the person reading the
...@@ -216,7 +214,7 @@ over a rather long period of time, but improvements are always welcome! ...@@ -216,7 +214,7 @@ over a rather long period of time, but improvements are always welcome!
7. As of v4.20, a given kernel implements only one RCU flavor, 7. As of v4.20, a given kernel implements only one RCU flavor,
which is RCU-sched for PREEMPT=n and RCU-preempt for PREEMPT=y. which is RCU-sched for PREEMPT=n and RCU-preempt for PREEMPT=y.
If the updater uses call_rcu() or synchronize_rcu(), If the updater uses call_rcu() or synchronize_rcu(),
then the corresponding readers my use rcu_read_lock() and then the corresponding readers may use rcu_read_lock() and
rcu_read_unlock(), rcu_read_lock_bh() and rcu_read_unlock_bh(), rcu_read_unlock(), rcu_read_lock_bh() and rcu_read_unlock_bh(),
or any pair of primitives that disables and re-enables preemption, or any pair of primitives that disables and re-enables preemption,
for example, rcu_read_lock_sched() and rcu_read_unlock_sched(). for example, rcu_read_lock_sched() and rcu_read_unlock_sched().
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment