Merge tag 'docs-5.3' of git://git.lwn.net/linux
Pull Documentation updates from Jonathan Corbet:
"It's been a relatively busy cycle for docs:
- A fair pile of RST conversions, many from Mauro. These create more
than the usual number of simple but annoying merge conflicts with
other trees, unfortunately. He has a lot more of these waiting on
the wings that, I think, will go to you directly later on.
- A new document on how to use merges and rebases in kernel repos,
and one on Spectre vulnerabilities.
- Various improvements to the build system, including automatic
markup of function() references because some people, for reasons I
will never understand, were of the opinion that
:c:func:``function()`` is unattractive and not fun to type.
- We now recommend using sphinx 1.7, but still support back to 1.4.
- Lots of smaller improvements, warning fixes, typo fixes, etc"
* tag 'docs-5.3' of git://git.lwn.net/linux: (129 commits)
docs: automarkup.py: ignore exceptions when seeking for xrefs
docs: Move binderfs to admin-guide
Disable Sphinx SmartyPants in HTML output
doc: RCU callback locks need only _bh, not necessarily _irq
docs: format kernel-parameters -- as code
Doc : doc-guide : Fix a typo
platform: x86: get rid of a non-existent document
Add the RCU docs to the core-api manual
Documentation: RCU: Add TOC tree hooks
Documentation: RCU: Rename txt files to rst
Documentation: RCU: Convert RCU UP systems to reST
Documentation: RCU: Convert RCU linked list to reST
Documentation: RCU: Convert RCU basic concepts to reST
docs: filesystems: Remove uneeded .rst extension on toctables
scripts/sphinx-pre-install: fix out-of-tree build
docs: zh_CN: submitting-drivers.rst: Remove a duplicated Documentation/
Documentation: PGP: update for newer HW devices
Documentation: Add section about CPU vulnerabilities for Spectre
Documentation: platform: Delete x86-laptop-drivers.txt
docs: Note that :c:func: should no longer be used
...
This commit is contained in:
Linus Torvalds
@@ -1,17 +1,19 @@
|
||||
RCU on Uniprocessor Systems
|
||||
.. _up_doc:
|
||||
|
||||
RCU on Uniprocessor Systems
|
||||
===========================
|
||||
|
||||
A common misconception is that, on UP systems, the call_rcu() primitive
|
||||
may immediately invoke its function. The basis of this misconception
|
||||
is that since there is only one CPU, it should not be necessary to
|
||||
wait for anything else to get done, since there are no other CPUs for
|
||||
anything else to be happening on. Although this approach will -sort- -of-
|
||||
anything else to be happening on. Although this approach will *sort of*
|
||||
work a surprising amount of the time, it is a very bad idea in general.
|
||||
This document presents three examples that demonstrate exactly how bad
|
||||
an idea this is.
|
||||
|
||||
|
||||
Example 1: softirq Suicide
|
||||
--------------------------
|
||||
|
||||
Suppose that an RCU-based algorithm scans a linked list containing
|
||||
elements A, B, and C in process context, and can delete elements from
|
||||
@@ -28,8 +30,8 @@ your kernel.
|
||||
This same problem can occur if call_rcu() is invoked from a hardware
|
||||
interrupt handler.
|
||||
|
||||
|
||||
Example 2: Function-Call Fatality
|
||||
---------------------------------
|
||||
|
||||
Of course, one could avert the suicide described in the preceding example
|
||||
by having call_rcu() directly invoke its arguments only if it was called
|
||||
@@ -46,11 +48,13 @@ its arguments would cause it to fail to make the fundamental guarantee
|
||||
underlying RCU, namely that call_rcu() defers invoking its arguments until
|
||||
all RCU read-side critical sections currently executing have completed.
|
||||
|
||||
Quick Quiz #1: why is it -not- legal to invoke synchronize_rcu() in
|
||||
this case?
|
||||
Quick Quiz #1:
|
||||
Why is it *not* legal to invoke synchronize_rcu() in this case?
|
||||
|
||||
:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
|
||||
|
||||
Example 3: Death by Deadlock
|
||||
----------------------------
|
||||
|
||||
Suppose that call_rcu() is invoked while holding a lock, and that the
|
||||
callback function must acquire this same lock. In this case, if
|
||||
@@ -76,25 +80,30 @@ there are cases where this can be quite ugly:
|
||||
If call_rcu() directly invokes the callback, painful locking restrictions
|
||||
or API changes would be required.
|
||||
|
||||
Quick Quiz #2: What locking restriction must RCU callbacks respect?
|
||||
Quick Quiz #2:
|
||||
What locking restriction must RCU callbacks respect?
|
||||
|
||||
:ref:`Answers to Quick Quiz <answer_quick_quiz_up>`
|
||||
|
||||
Summary
|
||||
-------
|
||||
|
||||
Permitting call_rcu() to immediately invoke its arguments breaks RCU,
|
||||
even on a UP system. So do not do it! Even on a UP system, the RCU
|
||||
infrastructure -must- respect grace periods, and -must- invoke callbacks
|
||||
infrastructure *must* respect grace periods, and *must* invoke callbacks
|
||||
from a known environment in which no locks are held.
|
||||
|
||||
Note that it -is- safe for synchronize_rcu() to return immediately on
|
||||
UP systems, including !PREEMPT SMP builds running on UP systems.
|
||||
Note that it *is* safe for synchronize_rcu() to return immediately on
|
||||
UP systems, including PREEMPT SMP builds running on UP systems.
|
||||
|
||||
Quick Quiz #3: Why can't synchronize_rcu() return immediately on
|
||||
UP systems running preemptable RCU?
|
||||
Quick Quiz #3:
|
||||
Why can't synchronize_rcu() return immediately on UP systems running
|
||||
preemptable RCU?
|
||||
|
||||
.. _answer_quick_quiz_up:
|
||||
|
||||
Answer to Quick Quiz #1:
|
||||
Why is it -not- legal to invoke synchronize_rcu() in this case?
|
||||
Why is it *not* legal to invoke synchronize_rcu() in this case?
|
||||
|
||||
Because the calling function is scanning an RCU-protected linked
|
||||
list, and is therefore within an RCU read-side critical section.
|
||||
@@ -104,12 +113,13 @@ Answer to Quick Quiz #1:
|
||||
Answer to Quick Quiz #2:
|
||||
What locking restriction must RCU callbacks respect?
|
||||
|
||||
Any lock that is acquired within an RCU callback must be
|
||||
acquired elsewhere using an _irq variant of the spinlock
|
||||
primitive. For example, if "mylock" is acquired by an
|
||||
RCU callback, then a process-context acquisition of this
|
||||
lock must use something like spin_lock_irqsave() to
|
||||
acquire the lock.
|
||||
Any lock that is acquired within an RCU callback must be acquired
|
||||
elsewhere using an _bh variant of the spinlock primitive.
|
||||
For example, if "mylock" is acquired by an RCU callback, then
|
||||
a process-context acquisition of this lock must use something
|
||||
like spin_lock_bh() to acquire the lock. Please note that
|
||||
it is also OK to use _irq variants of spinlocks, for example,
|
||||
spin_lock_irqsave().
|
||||
|
||||
If the process-context code were to simply use spin_lock(),
|
||||
then, since RCU callbacks can be invoked from softirq context,
|
||||
@@ -119,7 +129,7 @@ Answer to Quick Quiz #2:
|
||||
|
||||
This restriction might seem gratuitous, since very few RCU
|
||||
callbacks acquire locks directly. However, a great many RCU
|
||||
callbacks do acquire locks -indirectly-, for example, via
|
||||
callbacks do acquire locks *indirectly*, for example, via
|
||||
the kfree() primitive.
|
||||
|
||||
Answer to Quick Quiz #3:
|
||||
19
Documentation/RCU/index.rst
Normal file
19
Documentation/RCU/index.rst
Normal file
@@ -0,0 +1,19 @@
|
||||
.. _rcu_concepts:
|
||||
|
||||
============
|
||||
RCU concepts
|
||||
============
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
rcu
|
||||
listRCU
|
||||
UP
|
||||
|
||||
.. only:: subproject and html
|
||||
|
||||
Indices
|
||||
=======
|
||||
|
||||
* :ref:`genindex`
|
||||
@@ -1,5 +1,7 @@
|
||||
Using RCU to Protect Read-Mostly Linked Lists
|
||||
.. _list_rcu_doc:
|
||||
|
||||
Using RCU to Protect Read-Mostly Linked Lists
|
||||
=============================================
|
||||
|
||||
One of the best applications of RCU is to protect read-mostly linked lists
|
||||
("struct list_head" in list.h). One big advantage of this approach
|
||||
@@ -7,8 +9,8 @@ is that all of the required memory barriers are included for you in
|
||||
the list macros. This document describes several applications of RCU,
|
||||
with the best fits first.
|
||||
|
||||
|
||||
Example 1: Read-Side Action Taken Outside of Lock, No In-Place Updates
|
||||
----------------------------------------------------------------------
|
||||
|
||||
The best applications are cases where, if reader-writer locking were
|
||||
used, the read-side lock would be dropped before taking any action
|
||||
@@ -24,7 +26,7 @@ added or deleted, rather than being modified in place.
|
||||
|
||||
A straightforward example of this use of RCU may be found in the
|
||||
system-call auditing support. For example, a reader-writer locked
|
||||
implementation of audit_filter_task() might be as follows:
|
||||
implementation of audit_filter_task() might be as follows::
|
||||
|
||||
static enum audit_state audit_filter_task(struct task_struct *tsk)
|
||||
{
|
||||
@@ -48,7 +50,7 @@ the corresponding value is returned. By the time that this value is acted
|
||||
on, the list may well have been modified. This makes sense, since if
|
||||
you are turning auditing off, it is OK to audit a few extra system calls.
|
||||
|
||||
This means that RCU can be easily applied to the read side, as follows:
|
||||
This means that RCU can be easily applied to the read side, as follows::
|
||||
|
||||
static enum audit_state audit_filter_task(struct task_struct *tsk)
|
||||
{
|
||||
@@ -73,7 +75,7 @@ become list_for_each_entry_rcu(). The _rcu() list-traversal primitives
|
||||
insert the read-side memory barriers that are required on DEC Alpha CPUs.
|
||||
|
||||
The changes to the update side are also straightforward. A reader-writer
|
||||
lock might be used as follows for deletion and insertion:
|
||||
lock might be used as follows for deletion and insertion::
|
||||
|
||||
static inline int audit_del_rule(struct audit_rule *rule,
|
||||
struct list_head *list)
|
||||
@@ -106,7 +108,7 @@ lock might be used as follows for deletion and insertion:
|
||||
return 0;
|
||||
}
|
||||
|
||||
Following are the RCU equivalents for these two functions:
|
||||
Following are the RCU equivalents for these two functions::
|
||||
|
||||
static inline int audit_del_rule(struct audit_rule *rule,
|
||||
struct list_head *list)
|
||||
@@ -154,13 +156,13 @@ otherwise cause concurrent readers to fail spectacularly.
|
||||
So, when readers can tolerate stale data and when entries are either added
|
||||
or deleted, without in-place modification, it is very easy to use RCU!
|
||||
|
||||
|
||||
Example 2: Handling In-Place Updates
|
||||
------------------------------------
|
||||
|
||||
The system-call auditing code does not update auditing rules in place.
|
||||
However, if it did, reader-writer-locked code to do so might look as
|
||||
follows (presumably, the field_count is only permitted to decrease,
|
||||
otherwise, the added fields would need to be filled in):
|
||||
otherwise, the added fields would need to be filled in)::
|
||||
|
||||
static inline int audit_upd_rule(struct audit_rule *rule,
|
||||
struct list_head *list,
|
||||
@@ -187,7 +189,7 @@ otherwise, the added fields would need to be filled in):
|
||||
The RCU version creates a copy, updates the copy, then replaces the old
|
||||
entry with the newly updated entry. This sequence of actions, allowing
|
||||
concurrent reads while doing a copy to perform an update, is what gives
|
||||
RCU ("read-copy update") its name. The RCU code is as follows:
|
||||
RCU ("read-copy update") its name. The RCU code is as follows::
|
||||
|
||||
static inline int audit_upd_rule(struct audit_rule *rule,
|
||||
struct list_head *list,
|
||||
@@ -216,8 +218,8 @@ RCU ("read-copy update") its name. The RCU code is as follows:
|
||||
Again, this assumes that the caller holds audit_netlink_sem. Normally,
|
||||
the reader-writer lock would become a spinlock in this sort of code.
|
||||
|
||||
|
||||
Example 3: Eliminating Stale Data
|
||||
---------------------------------
|
||||
|
||||
The auditing examples above tolerate stale data, as do most algorithms
|
||||
that are tracking external state. Because there is a delay from the
|
||||
@@ -231,13 +233,16 @@ per-entry spinlock, and, if the "deleted" flag is set, pretends that the
|
||||
entry does not exist. For this to be helpful, the search function must
|
||||
return holding the per-entry spinlock, as ipc_lock() does in fact do.
|
||||
|
||||
Quick Quiz: Why does the search function need to return holding the
|
||||
per-entry lock for this deleted-flag technique to be helpful?
|
||||
Quick Quiz:
|
||||
Why does the search function need to return holding the per-entry lock for
|
||||
this deleted-flag technique to be helpful?
|
||||
|
||||
:ref:`Answer to Quick Quiz <answer_quick_quiz_list>`
|
||||
|
||||
If the system-call audit module were to ever need to reject stale data,
|
||||
one way to accomplish this would be to add a "deleted" flag and a "lock"
|
||||
spinlock to the audit_entry structure, and modify audit_filter_task()
|
||||
as follows:
|
||||
as follows::
|
||||
|
||||
static enum audit_state audit_filter_task(struct task_struct *tsk)
|
||||
{
|
||||
@@ -268,7 +273,7 @@ audit_upd_rule() would need additional memory barriers to ensure
|
||||
that the list_add_rcu() was really executed before the list_del_rcu().
|
||||
|
||||
The audit_del_rule() function would need to set the "deleted"
|
||||
flag under the spinlock as follows:
|
||||
flag under the spinlock as follows::
|
||||
|
||||
static inline int audit_del_rule(struct audit_rule *rule,
|
||||
struct list_head *list)
|
||||
@@ -290,8 +295,8 @@ flag under the spinlock as follows:
|
||||
return -EFAULT; /* No matching rule */
|
||||
}
|
||||
|
||||
|
||||
Summary
|
||||
-------
|
||||
|
||||
Read-mostly list-based data structures that can tolerate stale data are
|
||||
the most amenable to use of RCU. The simplest case is where entries are
|
||||
@@ -302,8 +307,9 @@ If stale data cannot be tolerated, then a "deleted" flag may be used
|
||||
in conjunction with a per-entry spinlock in order to allow the search
|
||||
function to reject newly deleted data.
|
||||
|
||||
.. _answer_quick_quiz_list:
|
||||
|
||||
Answer to Quick Quiz
|
||||
Answer to Quick Quiz:
|
||||
Why does the search function need to return holding the per-entry
|
||||
lock for this deleted-flag technique to be helpful?
|
||||
|
||||
92
Documentation/RCU/rcu.rst
Normal file
92
Documentation/RCU/rcu.rst
Normal file
@@ -0,0 +1,92 @@
|
||||
.. _rcu_doc:
|
||||
|
||||
RCU Concepts
|
||||
============
|
||||
|
||||
The basic idea behind RCU (read-copy update) is to split destructive
|
||||
operations into two parts, one that prevents anyone from seeing the data
|
||||
item being destroyed, and one that actually carries out the destruction.
|
||||
A "grace period" must elapse between the two parts, and this grace period
|
||||
must be long enough that any readers accessing the item being deleted have
|
||||
since dropped their references. For example, an RCU-protected deletion
|
||||
from a linked list would first remove the item from the list, wait for
|
||||
a grace period to elapse, then free the element. See the
|
||||
Documentation/RCU/listRCU.rst file for more information on using RCU with
|
||||
linked lists.
|
||||
|
||||
Frequently Asked Questions
|
||||
--------------------------
|
||||
|
||||
- Why would anyone want to use RCU?
|
||||
|
||||
The advantage of RCU's two-part approach is that RCU readers need
|
||||
not acquire any locks, perform any atomic instructions, write to
|
||||
shared memory, or (on CPUs other than Alpha) execute any memory
|
||||
barriers. The fact that these operations are quite expensive
|
||||
on modern CPUs is what gives RCU its performance advantages
|
||||
in read-mostly situations. The fact that RCU readers need not
|
||||
acquire locks can also greatly simplify deadlock-avoidance code.
|
||||
|
||||
- How can the updater tell when a grace period has completed
|
||||
if the RCU readers give no indication when they are done?
|
||||
|
||||
Just as with spinlocks, RCU readers are not permitted to
|
||||
block, switch to user-mode execution, or enter the idle loop.
|
||||
Therefore, as soon as a CPU is seen passing through any of these
|
||||
three states, we know that that CPU has exited any previous RCU
|
||||
read-side critical sections. So, if we remove an item from a
|
||||
linked list, and then wait until all CPUs have switched context,
|
||||
executed in user mode, or executed in the idle loop, we can
|
||||
safely free up that item.
|
||||
|
||||
Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
|
||||
same effect, but require that the readers manipulate CPU-local
|
||||
counters. These counters allow limited types of blocking within
|
||||
RCU read-side critical sections. SRCU also uses CPU-local
|
||||
counters, and permits general blocking within RCU read-side
|
||||
critical sections. These variants of RCU detect grace periods
|
||||
by sampling these counters.
|
||||
|
||||
- If I am running on a uniprocessor kernel, which can only do one
|
||||
thing at a time, why should I wait for a grace period?
|
||||
|
||||
See the Documentation/RCU/UP.rst file for more information.
|
||||
|
||||
- How can I see where RCU is currently used in the Linux kernel?
|
||||
|
||||
Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
|
||||
"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
|
||||
"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
|
||||
"synchronize_srcu", and the other RCU primitives. Or grab one
|
||||
of the cscope databases from:
|
||||
|
||||
(http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
|
||||
|
||||
- What guidelines should I follow when writing code that uses RCU?
|
||||
|
||||
See the checklist.txt file in this directory.
|
||||
|
||||
- Why the name "RCU"?
|
||||
|
||||
"RCU" stands for "read-copy update". The file Documentation/RCU/listRCU.rst
|
||||
has more information on where this name came from, search for
|
||||
"read-copy update" to find it.
|
||||
|
||||
- I hear that RCU is patented? What is with that?
|
||||
|
||||
Yes, it is. There are several known patents related to RCU,
|
||||
search for the string "Patent" in RTFP.txt to find them.
|
||||
Of these, one was allowed to lapse by the assignee, and the
|
||||
others have been contributed to the Linux kernel under GPL.
|
||||
There are now also LGPL implementations of user-level RCU
|
||||
available (http://liburcu.org/).
|
||||
|
||||
- I hear that RCU needs work in order to support realtime kernels?
|
||||
|
||||
Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
|
||||
kernel configuration parameter.
|
||||
|
||||
- Where can I find more information on RCU?
|
||||
|
||||
See the RTFP.txt file in this directory.
|
||||
Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
|
||||
@@ -1,89 +0,0 @@
|
||||
RCU Concepts
|
||||
|
||||
|
||||
The basic idea behind RCU (read-copy update) is to split destructive
|
||||
operations into two parts, one that prevents anyone from seeing the data
|
||||
item being destroyed, and one that actually carries out the destruction.
|
||||
A "grace period" must elapse between the two parts, and this grace period
|
||||
must be long enough that any readers accessing the item being deleted have
|
||||
since dropped their references. For example, an RCU-protected deletion
|
||||
from a linked list would first remove the item from the list, wait for
|
||||
a grace period to elapse, then free the element. See the listRCU.txt
|
||||
file for more information on using RCU with linked lists.
|
||||
|
||||
|
||||
Frequently Asked Questions
|
||||
|
||||
o Why would anyone want to use RCU?
|
||||
|
||||
The advantage of RCU's two-part approach is that RCU readers need
|
||||
not acquire any locks, perform any atomic instructions, write to
|
||||
shared memory, or (on CPUs other than Alpha) execute any memory
|
||||
barriers. The fact that these operations are quite expensive
|
||||
on modern CPUs is what gives RCU its performance advantages
|
||||
in read-mostly situations. The fact that RCU readers need not
|
||||
acquire locks can also greatly simplify deadlock-avoidance code.
|
||||
|
||||
o How can the updater tell when a grace period has completed
|
||||
if the RCU readers give no indication when they are done?
|
||||
|
||||
Just as with spinlocks, RCU readers are not permitted to
|
||||
block, switch to user-mode execution, or enter the idle loop.
|
||||
Therefore, as soon as a CPU is seen passing through any of these
|
||||
three states, we know that that CPU has exited any previous RCU
|
||||
read-side critical sections. So, if we remove an item from a
|
||||
linked list, and then wait until all CPUs have switched context,
|
||||
executed in user mode, or executed in the idle loop, we can
|
||||
safely free up that item.
|
||||
|
||||
Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
|
||||
same effect, but require that the readers manipulate CPU-local
|
||||
counters. These counters allow limited types of blocking within
|
||||
RCU read-side critical sections. SRCU also uses CPU-local
|
||||
counters, and permits general blocking within RCU read-side
|
||||
critical sections. These variants of RCU detect grace periods
|
||||
by sampling these counters.
|
||||
|
||||
o If I am running on a uniprocessor kernel, which can only do one
|
||||
thing at a time, why should I wait for a grace period?
|
||||
|
||||
See the UP.txt file in this directory.
|
||||
|
||||
o How can I see where RCU is currently used in the Linux kernel?
|
||||
|
||||
Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
|
||||
"rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
|
||||
"srcu_read_unlock", "synchronize_rcu", "synchronize_net",
|
||||
"synchronize_srcu", and the other RCU primitives. Or grab one
|
||||
of the cscope databases from:
|
||||
|
||||
http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html
|
||||
|
||||
o What guidelines should I follow when writing code that uses RCU?
|
||||
|
||||
See the checklist.txt file in this directory.
|
||||
|
||||
o Why the name "RCU"?
|
||||
|
||||
"RCU" stands for "read-copy update". The file listRCU.txt has
|
||||
more information on where this name came from, search for
|
||||
"read-copy update" to find it.
|
||||
|
||||
o I hear that RCU is patented? What is with that?
|
||||
|
||||
Yes, it is. There are several known patents related to RCU,
|
||||
search for the string "Patent" in RTFP.txt to find them.
|
||||
Of these, one was allowed to lapse by the assignee, and the
|
||||
others have been contributed to the Linux kernel under GPL.
|
||||
There are now also LGPL implementations of user-level RCU
|
||||
available (http://liburcu.org/).
|
||||
|
||||
o I hear that RCU needs work in order to support realtime kernels?
|
||||
|
||||
Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
|
||||
kernel configuration parameter.
|
||||
|
||||
o Where can I find more information on RCU?
|
||||
|
||||
See the RTFP.txt file in this directory.
|
||||
Or point your browser at http://www.rdrop.com/users/paulmck/RCU/.
|
||||
مرجع در شماره جدید
Block a user