Documentation: RCU: Convert RCU linked list to ReST
Subsystems (2)
c0d1n61at3 at gmail.com (Jiunn Chang)
PATCH 2/3 Documentation: RCU: Convert RCU linked list to ReST
Convert RCU linked list and add TOC tree hook.
--- Documentation/RCU/index.rst | 1 + Documentation/RCU/listRCU.txt | 315 ------------------------------- Documentation/RCU/list_rcu.rst | 335 +++++++++++++++++++++++++++++++++ Documentation/RCU/rcu.rst | 4 +- 4 files changed, 338 insertions(+), 317 deletions(-) delete mode 100644 Documentation/RCU/listRCU.txt create mode 100644 Documentation/RCU/list_rcu.rst
Documentation/RCU/index.rst +1 -0
@@ -8,6 +8,7 @@ RCU concepts :maxdepth: 1 rcu + list_rcu .. only:: subproject and html
Documentation/RCU/listRCU.txt deleted +0 -315
315 lines not on this page · raw message
Documentation/RCU/list_rcu.rst new file +335 -0
335 lines not on this page · raw message
Documentation/RCU/rcu.rst +2 -2
@@ -11,7 +11,7 @@ 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 listRCU.txt +a grace period to elapse, then free the element. See :ref:`list_rcu_doc` for more information on using RCU with linked lists. Frequently Asked Questions
@@ -67,7 +67,7 @@ Frequently Asked Questions - Why the name "RCU"? - "RCU" stands for "read-copy update". listRCU.txt has + "RCU" stands for "read-copy update". :ref:`list_rcu_doc` has more information on where this name came from, search for "read-copy update" to find it.
Signature · 1 line
2.22.0
corbet at lwn.net (Jonathan Corbet)
PATCH 2/3 Documentation: RCU: Convert RCU linked list to ReST
Quoted 11 lines · On Sat, 22 Jun 2019 02:02:51 -0500 Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
Convert RCU linked list and add TOC tree hook.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>--- Documentation/RCU/index.rst | 1 + Documentation/RCU/listRCU.txt | 315 ------------------------------- Documentation/RCU/list_rcu.rst | 335 +++++++++++++++++++++++++++++++++ Documentation/RCU/rcu.rst | 4 +- 4 files changed, 338 insertions(+), 317 deletions(-) delete mode 100644 Documentation/RCU/listRCU.txt create mode 100644 Documentation/RCU/list_rcu.rst
Sometimes it can be better to do a change like this in two steps, with the second being just renaming the file. That can make it easier to see what has actually changed.
[...]
Quoted 25 lines
Documentation/RCU/list_rcu.rst new file +19
-0@@ -0,0 +1,335 @@ +.. _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 +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 +based on the results of the search. The most celebrated example is +the routing table. Because the routing table is tracking the state of +equipment outside of the computer, it will at times contain stale data.
Documentation/RCU/list_rcu.rst line 29
Quoted 10 lines
Documentation/RCU/list_rcu.rst new file +10
-0+Therefore, once the route has been computed, there is no need to hold +the routing table static during transmission of the packet. After all, +you can hold the routing table static all you want, but that won't keep +the external Internet from changing, and it is the state of the external +Internet that really matters. In addition, routing entries are typically +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:
Please don't mark up function names that way. Just leave them unadorned, and soon we'll have the magic to handle all of that automatically. Also,
Documentation/RCU/list_rcu.rst line 33
Quoted 5 lines
Documentation/RCU/list_rcu.rst new file +5
-0+implementation of *audit_filter_task()* might be as follows: + +.. code-block:: c + + static enum audit_state audit_filter_task(struct task_struct *tsk)
It's usually better to just use "::" to indicate a literal block:
Quoted 3 lines
implementation of
audit_filter_task()might be as follows::static enum
audit_state....
That minimizes the amount of non-text stuff that readers have to work through.
Thanks,
jon
c0d1n61at3 at gmail.com (Jiunn Chang)
v2 cover Documentation: RCU: Convert to
This patch series is the initial conversion of the RCU documentation section.
[PATCH v2 0/7] Documentation: RCU: Convert the following to ReST [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST
- ReST markup and TOC tree hook.
[PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST
- Rename RCU basic concepts txt file to rst.
[PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST
- ReST markup and TOC tree hook.
[PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST
- Rename RCU linked list txt file to rst.
[PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST
- ReST markup and TOC tree hook.
[PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST
- Rename RCU UP systems txt file to rst.
[PATCH v2 6/7] Documentation: RCU: Add links to rcu.rst
- Add the following links to rcu.rst:
list_rcu
up_rcu
[PATCH 1/3] Documentation: RCU: Convert RCU basic concepts to ReST
- Convert RCU basic concepts and add TOC tree hook.
[PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST
- Convert RCU linked list and add TOC tree hook.
[PATCH 3/3] Documentation: RCU: Convert RCU UP systems to ReST
- Convert RCU UP systems and add TOC tree hook.
Quoted 1 line
8-----------------------------------------------------------------8<
Jiunn Chang (7):
Documentation: RCU: Convert RCU basic concepts to ReST
Documentation: RCU: Rename RCU basic concepts to ReST
Documentation: RCU: Convert RCU linked list to ReST
Documentation: RCU: Rename RCU linked list to ReST
Documentation: RCU: Convert RCU UP systems to ReST
Documentation: RCU: Rename RCU UP systems to ReST
Documentation: RCU: Add links to rcu.rst
Documentation/RCU/index.rst | 19 ++++
.../RCU/{listRCU.txt => list_rcu.rst} | 33 ++++---
Documentation/RCU/rcu.rst | 91 +++++++++++++++++++
Documentation/RCU/rcu.txt | 89 ------------------
Documentation/RCU/{UP.txt => up_rcu.rst} | 27 +++---
5 files changed, 143 insertions(+), 116 deletions(-)
create mode 100644 Documentation/RCU/index.rst
rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (93%)
create mode 100644 Documentation/RCU/rcu.rst
delete mode 100644 Documentation/RCU/rcu.txt
rename Documentation/RCU/{UP.txt => up_rcu.rst} (89%)Signature · 1 line
2.22.0
v2 cover Documentation: RCU: Convert to
Hello Jiunn,
Nice to see the kernel mentees project in action! (I actually did not know about this project before this posting). I replied to your patches. Once you address the small nits I suggested, please feel free to add my Reviewed-by tag to your patches:
Reviewed-by: Joel Fernandes (Google) <joel at joelfernandes.org>
If you are interested in RCU, I have some listRCU hardening improvements I am working on and would be nice to work together with you on that (only if you are interested).
Quoted 2 lines · Jiunn Chang
This patch series is the initial conversion of the RCU documentation section.
I think you still did not CC rcu at vger.kernel.org . It would be nice if you could do that. I think Paul also suggested that in your v1.
thanks!
- Joel
Quoted 52 lines
[PATCH v2 0/7] Documentation: RCU: Convert the following to ReST [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST
- ReST markup and TOC tree hook.
[PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST
- Rename RCU basic concepts txt file to rst.
[PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST
- ReST markup and TOC tree hook.
[PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST
- Rename RCU linked list txt file to rst.
[PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST
- ReST markup and TOC tree hook.
[PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST
- Rename RCU UP systems txt file to rst.
[PATCH v2 6/7] Documentation: RCU: Add links torcu.rst
- Add the following links torcu.rst:
list_rcu
up_rcu[PATCH 1/3] Documentation: RCU: Convert RCU basic concepts to ReST
- Convert RCU basic concepts and add TOC tree hook.
[PATCH 2/3] Documentation: RCU: Convert RCU linked list to ReST
- Convert RCU linked list and add TOC tree hook.
[PATCH 3/3] Documentation: RCU: Convert RCU UP systems to ReST
- Convert RCU UP systems and add TOC tree hook.Quoted 1 line
8-----------------------------------------------------------------8<
Jiunn Chang (7):
Documentation: RCU: Convert RCU basic concepts to ReST
Documentation: RCU: Rename RCU basic concepts to ReST
Documentation: RCU: Convert RCU linked list to ReST
Documentation: RCU: Rename RCU linked list to ReST
Documentation: RCU: Convert RCU UP systems to ReST
Documentation: RCU: Rename RCU UP systems to ReST
Documentation: RCU: Add links torcu.rstDocumentation/RCU/index.rst | 19 ++++ .../RCU/{listRCU.txt => list_rcu.rst} | 33 ++++--- Documentation/RCU/rcu.rst | 91 +++++++++++++++++++ Documentation/RCU/rcu.txt | 89 ------------------ Documentation/RCU/{UP.txt => up_rcu.rst} | 27 +++--- 5 files changed, 143 insertions(+), 116 deletions(-) create mode 100644 Documentation/RCU/index.rst rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (93%) create mode 100644 Documentation/RCU/rcu.rst delete mode 100644 Documentation/RCU/rcu.txt rename Documentation/RCU/{UP.txt => up_rcu.rst} (89%)Signature · 1 line
2.22.0
corbet at lwn.net (Jonathan Corbet)
v2 cover Documentation: RCU: Convert to
In reply to c0d1n61at3 at gmail.com (Jiunn Chang)Quoted 12 lines · On Sun, 23 Jun 2019 03:14:06 -0500 Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
This patch series is the initial conversion of the RCU documentation section.
[PATCH v2 0/7] Documentation: RCU: Convert the following to ReST [PATCH v2 1/7] Documentation: RCU: Convert RCU basic concepts to ReST
- ReST markup and TOC tree hook.
[PATCH v2 2/7] Documentation: RCU: Rename RCU basic concepts to ReST
- Rename RCU basic concepts txt file to rst.
[PATCH v2 3/7] Documentation: RCU: Convert RCU linked list to ReST
- ReST markup and TOC tree hook.
[PATCH v2 4/7] Documentation: RCU: Rename RCU linked list to ReST
- Rename RCU linked list txt file to rst.
Quoted 8 lines
[PATCH v2 5/7] Documentation: RCU: Convert RCU UP systems to ReST
- ReST markup and TOC tree hook.
[PATCH v2 6/7] Documentation: RCU: Rename RCU UP systems to ReST
- Rename RCU UP systems txt file to rst.
[PATCH v2 6/7] Documentation: RCU: Add links torcu.rst
- Add the following links torcu.rst:
list_rcu
up_rcu
Thanks for working on this, we're getting closer. That said, I have some overall comments again:
- Thanks for including a cover letter, but there should be a bit more than a list of patches there. Put in a paragraph saying what the series as a whole is for; if somebody reads the cover letter and nothing else, they should know what you're up to.
- The cover letter should also say what has changed since the previous posting.
- Copying the relevant mailing lists really isn't optional, so I'll ask you again to do that. Most maintainers won't accept patches that have not been posted to the appropriate public list(s)
- Please thread your patches as replies to the cover letter, so they all stay together. "git send-email" will do that nicely for you.
- You have a couple of Reviewed-by tags from Joel now; be sure to add those before the next posting.
- Thanks for splitting out the renames - do you see how that makes it easier to see what has actually changed in the files? That said, you could easily and appropriately do all of the renames in a single commit.
Thanks,
jon
v3 cover Documentation: RCU: Convert to reST
In reply to c0d1n61at3 at gmail.com (Jiunn Chang)This patch series is the initial conversion of the RCU documentation section. This includes reST markup and renaming txt files to rst. For files converted, internal and external links have been created with cross-references. Checkpatch was used to leverage codespell for any spelling errors. Each patch in the series has been compiled and reviewed for warnings and errors. Patches can be bisected.
The changes made in v3 include:
- correcting markup to maintain even more of the original text
- correcting markup for line breaks
- combining all file renaming into one patch
- add reviewed-by tags
- add required public list to CC
The changes made in v2 include:
- correcting markup to maintain as much of the original text as possible
- correcting markup to reduce reader context switching
- breakout file renaming into individual patches in the series
Quoted 1 line
8-----------------------------------------------------------------8<
Jiunn Chang (6):
Documentation: RCU: Convert RCU basic concepts to reST
Documentation: RCU: Convert RCU linked list to reST
Documentation: RCU: Convert RCU UP systems to reST
Documentation: RCU: Rename txt files to rst
Documentation: RCU: Add links to rcu.rst
Documentation: RCU: Add TOC tree hooks
Documentation/RCU/index.rst | 19 ++++
.../RCU/{listRCU.txt => list_rcu.rst} | 38 ++++----
Documentation/RCU/rcu.rst | 91 +++++++++++++++++++
Documentation/RCU/rcu.txt | 89 ------------------
Documentation/RCU/{UP.txt => up_rcu.rst} | 37 +++++---
5 files changed, 155 insertions(+), 119 deletions(-)
create mode 100644 Documentation/RCU/index.rst
rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (92%)
create mode 100644 Documentation/RCU/rcu.rst
delete mode 100644 Documentation/RCU/rcu.txt
rename Documentation/RCU/{UP.txt => up_rcu.rst} (84%)Signature · 1 line
2.22.0
v4 cover Documentation: RCU: Convert to reST
This patch series is the initial conversion of the RCU documentation section. This includes reST markup and renaming txt files to rst. For files converted, internal links have been created. Checkpatch was used to leverage codespell for any spelling errors. Each patch in the series has been compiled and reviewed for warnings and errors. Patches can be bisected.
The changes made in v4 include:
- Change links in rcu.rst to the path in documentation section
- Maintain the original name of the txt files
The changes made in v3 include:
- correcting markup to maintain even more of the original text
- correcting markup for line breaks
- combining all file renaming into one patch
- add reviewed-by tags
- add required public list to CC
The changes made in v2 include:
- correcting markup to maintain as much of the original text as possible
- correcting markup to reduce reader context switching
- breakout file renaming into individual patches in the series
Quoted 1 line
8---------------------------------------------------------------------------8<
Jiunn Chang (5):
Documentation: RCU: Convert RCU basic concepts to reST
Documentation: RCU: Convert RCU linked list to reST
Documentation: RCU: Convert RCU UP systems to reST
Documentation: RCU: Rename txt files to rst
Documentation: RCU: Add TOC tree hooks
Documentation/RCU/{UP.txt => UP.rst} | 37 +++++---
Documentation/RCU/index.rst | 19 ++++
.../RCU/{listRCU.txt => listRCU.rst} | 38 ++++----
Documentation/RCU/rcu.rst | 92 +++++++++++++++++++
Documentation/RCU/rcu.txt | 89 ------------------
5 files changed, 156 insertions(+), 119 deletions(-)
rename Documentation/RCU/{UP.txt => UP.rst} (84%)
create mode 100644 Documentation/RCU/index.rst
rename Documentation/RCU/{listRCU.txt => listRCU.rst} (92%)
create mode 100644 Documentation/RCU/rcu.rst
delete mode 100644 Documentation/RCU/rcu.txtSignature · 1 line
2.22.0
v5 cover Documentation: RCU: Convert to reST
This patch series is the initial conversion of the RCU documentation section. This includes reST markup and renaming txt files to rst. For files converted, internal links have been created. Checkpatch was used to leverage codespell for any spelling errors. Each patch in the series has been compiled and reviewed for warnings and errors. Patches can be bisected.
The changes make in v5 include:
- add reviewed-by tags
The changes made in v4 include:
- Change links in rcu.rst to the path in documentation section
- Maintain the original name of the txt files
The changes made in v3 include:
- correcting markup to maintain even more of the original text
- correcting markup for line breaks
- combining all file renaming into one patch
- add reviewed-by tags
- add required public list to CC
The changes made in v2 include:
- correcting markup to maintain as much of the original text as possible
- correcting markup to reduce reader context switching
- breakout file renaming into individual patches in the series
Quoted 1 line
8---------------------------------------------------------------------------8<
Jiunn Chang (5):
Documentation: RCU: Convert RCU basic concepts to reST
Documentation: RCU: Convert RCU linked list to reST
Documentation: RCU: Convert RCU UP systems to reST
Documentation: RCU: Rename txt files to rst
Documentation: RCU: Add TOC tree hooks
Documentation/RCU/{UP.txt => UP.rst} | 37 +++++---
Documentation/RCU/index.rst | 19 ++++
.../RCU/{listRCU.txt => listRCU.rst} | 38 ++++----
Documentation/RCU/rcu.rst | 92 +++++++++++++++++++
Documentation/RCU/rcu.txt | 89 ------------------
5 files changed, 156 insertions(+), 119 deletions(-)
rename Documentation/RCU/{UP.txt => UP.rst} (84%)
create mode 100644 Documentation/RCU/index.rst
rename Documentation/RCU/{listRCU.txt => listRCU.rst} (92%)
create mode 100644 Documentation/RCU/rcu.rst
delete mode 100644 Documentation/RCU/rcu.txtSignature · 1 line
2.22.0
PATCH v5 1/5 Documentation: RCU: Convert RCU basic concepts to reST
In reply to Jiunn ChangRCU basic concepts reST markup.
--- Documentation/RCU/rcu.txt | 119 +++++++++++++++++++------------------- 1 file changed, 61 insertions(+), 58 deletions(-)
Documentation/RCU/rcu.txt +61 -58
@@ -1,5 +1,7 @@ -RCU Concepts +.. _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
@@ -8,82 +10,83 @@ 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. - +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 +-------------------------- -o Why would anyone want to use RCU? +- 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. + 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? +- 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. + 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. + 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? +- 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. + See the Documentation/RCU/UP.rst file for more information. -o How can I see where RCU is currently used in the Linux kernel? +- 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: + 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 + (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html). -o What guidelines should I follow when writing code that uses RCU? +- What guidelines should I follow when writing code that uses RCU? - See the checklist.txt file in this directory. + See the checklist.txt file in this directory. -o Why the name "RCU"? +- 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. + "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. -o I hear that RCU is patented? What is with that? +- 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/). + 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? +- 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. + Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU + kernel configuration parameter. -o Where can I find more information on RCU? +- 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/. + See the RTFP.txt file in this directory. + Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
Signature · 1 line
2.22.0
Jonathan Corbet
maintainerRe: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST
Quoted 4 lines · On Wed, 26 Jun 2019 15:07:01 -0500 Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
RCU basic concepts reST markup.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>Reviewed-by Joel Fernandes (Google) <joel at joelfernandes.org>
So this is a little detail but ... your signoff should be the last thing in the set of tags on the patch.
This isn't worth making you do yet another revision, so I went ahead and applied the patches and fixed the tag ordering on the way in. I'll also append a patch adding the new RCU stuff into the core-api manual so people can actually get to it.
Thanks,
jon
Steven Rostedt
reviewerRe: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST
Quoted 10 lines · On Thu, 27 Jun 2019 08:34:43 -0600 Jonathan Corbet <corbet at lwn.net> wrote:
Quoted 4 lines · On Wed, 26 Jun 2019 15:07:01 -0500 Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
RCU basic concepts reST markup.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>Reviewed-by Joel Fernandes (Google) <joel at joelfernandes.org>So this is a little detail but ... your signoff should be the last thing in the set of tags on the patch.
Note, I've been seeing this a lot lately, and then noticed, that when I downloaded a patch directly from patchwork, it placed all the Reviewed-by and Acked-by tags after the original Signed-off-by. I checked the original patch on the mailing list, and it had no other tags but the Signed-off-by. I then pulled one of my own patches, and it did it to that patch as well.
I too prefer the Signed-off-by be last, but our tooling needs to do this as well, otherwise it's a failure in our procedures.
-- Steve
Shuah Khan
reviewerRe: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST
Quoted 21 lines · Steven Rostedt
Quoted 10 lines · On Thu, 27 Jun 2019 08:34:43 -0600 Jonathan Corbet <corbet at lwn.net> wrote:
Quoted 4 lines · On Wed, 26 Jun 2019 15:07:01 -0500 Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
RCU basic concepts reST markup.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>Reviewed-by Joel Fernandes (Google) <joel at joelfernandes.org>So this is a little detail but ... your signoff should be the last thing in the set of tags on the patch.
Note, I've been seeing this a lot lately, and then noticed, that when I downloaded a patch directly from patchwork, it placed all the Reviewed-by and Acked-by tags after the original Signed-off-by. I checked the original patch on the mailing list, and it had no other tags but the Signed-off-by. I then pulled one of my own patches, and it did it to that patch as well.
Quoted 3 lines
I too prefer the Signed-off-by be last, but our tooling needs to do this as well, otherwise it's a failure in our procedures.
Thanks Steve for pointing this out. I am seeing some odd behavior with tags.
It appears some maintainers want the tags in chronological order, which is Reviewed-by after Signed-off which doesn't make sense to me.
I prefer Signed-off-by last.
I am working on FAQ (Frequently Answered Questions) section for mentees. I will add this to it.
thanks,
-- Shuah
Paul E. McKenney
Acked-byRe: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST
In reply to Jonathan CorbetQuoted 8 lines · Jonathan Corbet
Quoted 4 lines · On Wed, 26 Jun 2019 15:07:01 -0500 Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
RCU basic concepts reST markup.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>Reviewed-by Joel Fernandes (Google) <joel at joelfernandes.org>
Quoted 7 lines
So this is a little detail but ... your signoff should be the last thing in the set of tags on the patch.
This isn't worth making you do yet another revision, so I went ahead and applied the patches and fixed the tag ordering on the way in. I'll also append a patch adding the new RCU stuff into the core-api manual so people can actually get to it.
Please feel free to add my ack:
Thanx, Paul
Re: [Linux-kernel-mentees][PATCH v5 1/5] Documentation: RCU: Convert RCU basic concepts to reST
In reply to Jonathan CorbetQuoted 11 lines · Jonathan Corbet
Quoted 4 lines · On Wed, 26 Jun 2019 15:07:01 -0500 Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
RCU basic concepts reST markup.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>Reviewed-by Joel Fernandes (Google) <joel at joelfernandes.org>So this is a little detail but ... your signoff should be the last thing in the set of tags on the patch.
Quoted 8 lines
This isn't worth making you do yet another revision, so I went ahead and applied the patches and fixed the tag ordering on the way in. I'll also append a patch adding the new RCU stuff into the core-api manual so people can actually get to it.
Thanks,
jon
Hello Jon,
I will keep this in mind for next time. I would like to thank you, Joel, Paul and everyone else who has helped me learn the Linux kernel patch process.
I will send a patch for the UP systems change Paul sent me for _bh suffix.
THX,
Jiunn
PATCH v5 2/5 Documentation: RCU: Convert RCU linked list to reST
In reply to Jiunn ChangRCU linked list reST markup.
--- Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 16 deletions(-)
Documentation/RCU/listRCU.txt +22 -16
@@ -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?
Signature · 1 line
2.22.0
PATCH v5 3/5 Documentation: RCU: Convert RCU UP systems to reST
In reply to Jiunn ChangRCU UP systems reST markup.
--- Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-)
Documentation/RCU/UP.txt +23 -14
@@ -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.
@@ -119,7 +128,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:
Signature · 1 line
2.22.0
PATCH v5 4/5 Documentation: RCU: Rename txt files to rst
In reply to Jiunn ChangRename the following files to reST:
- rcu.txt
- listRCU.txt
- UP.txt
---
Documentation/RCU/{UP.txt => UP.rst} | 0
Documentation/RCU/{listRCU.txt => listRCU.rst} | 0
Documentation/RCU/{rcu.txt => rcu.rst} | 0
3 files changed, 0 insertions(+), 0 deletions(-)
rename Documentation/RCU/{UP.txt => UP.rst} (100%)
rename Documentation/RCU/{listRCU.txt => listRCU.rst} (100%)
rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)Documentation/RCU/UP.rst renamed from Documentation/RCU/UP.txt +0 -0
Documentation/RCU/listRCU.rst renamed from Documentation/RCU/listRCU.txt +0 -0
Documentation/RCU/rcu.rst renamed from Documentation/RCU/rcu.txt +0 -0
Signature · 1 line
2.22.0
PATCH v5 5/5 Documentation: RCU: Add TOC tree hooks
In reply to Jiunn ChangAdd TOC tree hooks for:
- rcu
- listRCU
- UP
--- Documentation/RCU/index.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 Documentation/RCU/index.rst
Documentation/RCU/index.rst new file +19 -0
@@ -0,0 +1,19 @@ +.. _rcu_concepts: + +============ +RCU concepts +============ + +.. toctree:: + :maxdepth: 1 + + rcu + listRCU + UP + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex`
Signature · 1 line
2.22.0
PATCH v4 1/5 Documentation: RCU: Convert RCU basic concepts to reST
In reply to Jiunn ChangRCU basic concepts reST markup.
--- Documentation/RCU/rcu.txt | 119 +++++++++++++++++++------------------- 1 file changed, 61 insertions(+), 58 deletions(-)
Documentation/RCU/rcu.txt +61 -58
@@ -1,5 +1,7 @@ -RCU Concepts +.. _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
@@ -8,82 +10,83 @@ 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. - +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 +-------------------------- -o Why would anyone want to use RCU? +- 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. + 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? +- 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. + 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. + 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? +- 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. + See the Documentation/RCU/UP.rst file for more information. -o How can I see where RCU is currently used in the Linux kernel? +- 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: + 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 + (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html). -o What guidelines should I follow when writing code that uses RCU? +- What guidelines should I follow when writing code that uses RCU? - See the checklist.txt file in this directory. + See the checklist.txt file in this directory. -o Why the name "RCU"? +- 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. + "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. -o I hear that RCU is patented? What is with that? +- 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/). + 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? +- 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. + Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU + kernel configuration parameter. -o Where can I find more information on RCU? +- 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/. + See the RTFP.txt file in this directory. + Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
Signature · 1 line
2.22.0
PATCH v4 2/5 Documentation: RCU: Convert RCU linked list to reST
In reply to Jiunn ChangRCU linked list reST markup.
--- Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 16 deletions(-)
Documentation/RCU/listRCU.txt +22 -16
@@ -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?
Signature · 1 line
2.22.0
PATCH v4 3/5 Documentation: RCU: Convert RCU UP systems to reST
In reply to Jiunn ChangRCU UP systems reST markup.
--- Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-)
Documentation/RCU/UP.txt +23 -14
@@ -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.
@@ -119,7 +128,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:
Signature · 1 line
2.22.0
PATCH v4 4/5 Documentation: RCU: Rename txt files to rst
In reply to Jiunn ChangRename the following files to reST:
- rcu.txt
- listRCU.txt
- UP.txt
---
Documentation/RCU/{UP.txt => UP.rst} | 0
Documentation/RCU/{listRCU.txt => listRCU.rst} | 0
Documentation/RCU/{rcu.txt => rcu.rst} | 0
3 files changed, 0 insertions(+), 0 deletions(-)
rename Documentation/RCU/{UP.txt => UP.rst} (100%)
rename Documentation/RCU/{listRCU.txt => listRCU.rst} (100%)
rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)Documentation/RCU/UP.rst renamed from Documentation/RCU/UP.txt +0 -0
Documentation/RCU/listRCU.rst renamed from Documentation/RCU/listRCU.txt +0 -0
Documentation/RCU/rcu.rst renamed from Documentation/RCU/rcu.txt +0 -0
Signature · 1 line
2.22.0
PATCH v4 5/5 Documentation: RCU: Add TOC tree hooks
In reply to Jiunn ChangAdd TOC tree hooks for:
- rcu
- listRCU
- UP
--- Documentation/RCU/index.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 Documentation/RCU/index.rst
Documentation/RCU/index.rst new file +19 -0
@@ -0,0 +1,19 @@ +.. _rcu_concepts: + +============ +RCU concepts +============ + +.. toctree:: + :maxdepth: 1 + + rcu + listRCU + UP + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex`
Signature · 1 line
2.22.0
c0d1n61at3 at gmail.com (Jiunn Chang)
PATCH v3 1/6 Documentation: RCU: Convert RCU basic concepts to reST
In reply to c0d1n61at3 at gmail.com (Jiunn Chang)RCU basic concepts reST markup.
--- Documentation/RCU/rcu.txt | 114 +++++++++++++++++++------------------- 1 file changed, 58 insertions(+), 56 deletions(-)
Documentation/RCU/rcu.txt +58 -56
@@ -1,5 +1,7 @@ -RCU Concepts +.. _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
@@ -11,79 +13,79 @@ 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? +- 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. + 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? +- 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. + 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. + 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? +- 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. + See the UP.txt file in this directory. -o How can I see where RCU is currently used in the Linux kernel? +- 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: + 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 + (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html). -o What guidelines should I follow when writing code that uses RCU? +- What guidelines should I follow when writing code that uses RCU? - See the checklist.txt file in this directory. + See the checklist.txt file in this directory. -o Why the name "RCU"? +- 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. + "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? +- 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/). + 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? +- 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. + Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU + kernel configuration parameter. -o Where can I find more information on RCU? +- 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/. + See the RTFP.txt file in this directory. + Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
Signature · 1 line
2.22.0
PATCH v3 2/6 Documentation: RCU: Convert RCU linked list to reST
In reply to c0d1n61at3 at gmail.com (Jiunn Chang)RCU linked list reST markup.
--- Documentation/RCU/listRCU.txt | 38 ++++++++++++++++++++--------------- 1 file changed, 22 insertions(+), 16 deletions(-)
Documentation/RCU/listRCU.txt +22 -16
@@ -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?
Signature · 1 line
2.22.0
c0d1n61at3 at gmail.com (Jiunn Chang)
PATCH v3 3/6 Documentation: RCU: Convert RCU UP systems to reST
In reply to c0d1n61at3 at gmail.com (Jiunn Chang)RCU UP systems reST markup.
--- Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-)
Documentation/RCU/UP.txt +23 -14
@@ -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.
@@ -119,7 +128,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:
Signature · 1 line
2.22.0
paulmck at linux.ibm.com (Paul E. McKenney)
PATCH v3 3/6 Documentation: RCU: Convert RCU UP systems to reST
Quoted 82 lines · Jiunn Chang
RCU UP systems reST markup.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>Reviewed-by Joel Fernandes (Google) <joel at joelfernandes.org>--- Documentation/RCU/UP.txt | 37 +++++++++++++++++++++++-------------- 1 file changed, 23 insertions(+), 14 deletions(-)Documentation/RCU/UP.txt +15
-10@@ -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.
Documentation/RCU/UP.txt there are cases where this can be quite ugly: · line 103
Quoted 10 lines
Documentation/RCU/UP.txt +6
-2+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:
As long as you are in the area, the answer is overly constraining. The locking primitives could use either _irq suffixes (as stated) or _bh suffixes. This is obviously not your fault, but please feel free to fix this with an additional patch.
Thanx, Paul
Quoted 18 lines
Documentation/RCU/UP.txt +2
-2Answer 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.@@ -119,7 +128,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:Signature · 1 line
2.22.0
PATCH v3 4/6 Documentation: RCU: Rename txt files to rst
In reply to c0d1n61at3 at gmail.com (Jiunn Chang)Rename the following files to reST:
- rcu.txt
- listRCU.txt
- UP.txt
---
Documentation/RCU/{listRCU.txt => list_rcu.rst} | 0
Documentation/RCU/{rcu.txt => rcu.rst} | 0
Documentation/RCU/{UP.txt => up_rcu.rst} | 0
3 files changed, 0 insertions(+), 0 deletions(-)
rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (100%)
rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)
rename Documentation/RCU/{UP.txt => up_rcu.rst} (100%)Documentation/RCU/list_rcu.rst renamed from Documentation/RCU/listRCU.txt +0 -0
Documentation/RCU/rcu.rst renamed from Documentation/RCU/rcu.txt +0 -0
Documentation/RCU/up_rcu.rst renamed from Documentation/RCU/UP.txt +0 -0
Signature · 1 line
2.22.0
c0d1n61at3 at gmail.com (Jiunn Chang)
PATCH v3 5/6 Documentation: RCU: Add links to rcu.rst
In reply to c0d1n61at3 at gmail.com (Jiunn Chang)Add the following links:
- list_rcu
- up_rcu
--- Documentation/RCU/rcu.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/RCU/rcu.rst +4 -4
@@ -10,8 +10,8 @@ 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. +a grace period to elapse, then free the element. See :ref:`list_rcu` +for more information on using RCU with linked lists. Frequently Asked Questions --------------------------
@@ -49,7 +49,7 @@ Frequently Asked Questions - 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. + See :ref:`up_rcu` for more information. - How can I see where RCU is currently used in the Linux kernel?
@@ -67,7 +67,7 @@ Frequently Asked Questions - Why the name "RCU"? - "RCU" stands for "read-copy update". The file listRCU.txt has + "RCU" stands for "read-copy update". :ref:`list_rcu` has more information on where this name came from, search for "read-copy update" to find it.
Signature · 1 line
2.22.0
paulmck at linux.ibm.com (Paul E. McKenney)
PATCH v3 5/6 Documentation: RCU: Add links to rcu.rst
Quoted 25 lines · Jiunn Chang
Add the following links:
-list_rcu
-up_rcuSigned-off-by Jiunn Chang <c0d1n61at3 at gmail.com>--- Documentation/RCU/rcu.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)Documentation/RCU/rcu.rst +2
-2@@ -10,8 +10,8 @@ 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. +a grace period to elapse, then free the element. See :ref:`list_rcu` +for more information on using RCU with linked lists. Frequently Asked Questions --------------------------
Documentation/RCU/rcu.rst Frequently Asked Questions · line 52
Quoted 5 lines
Documentation/RCU/rcu.rst +1
-1@@ -49,7 +49,7 @@ Frequently Asked Questions - 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. + See :ref:`up_rcu` for more information.
This rendered as straight text after "make htmldocs" instead of producing a link in the HTML output. The HTML itself is:
<span class="xref std std-ref">up_rcu</span>
This doesn't look like something that would create a link, though I freely admit that my HTML is rather outdated.
Documentation/RCU/rcu.rst Frequently Asked Questions · line 70
Quoted 8 lines
Documentation/RCU/rcu.rst +1
-1- How can I see where RCU is currently used in the Linux kernel?@@ -67,7 +67,7 @@ Frequently Asked Questions - Why the name "RCU"? - "RCU" stands for "read-copy update". The file listRCU.txt has + "RCU" stands for "read-copy update". :ref:`list_rcu` has
Same here for list_rcu.
Thanx, Paul
Quoted 6 lines
Documentation/RCU/rcu.rst +0
-0more information on where this name came from, search for "read-copy update" to find it.Signature · 1 line
2.22.0
corbet at lwn.net (Jonathan Corbet)
PATCH v3 5/6 Documentation: RCU: Add links to rcu.rst
Quoted 10 lines · On Tue, 25 Jun 2019 08:56:23 -0700 "Paul E. McKenney" <paulmck at…
Documentation/RCU/rcu.rst Frequently Asked Questions · line 52
Quoted 2 lines
Documentation/RCU/rcu.rst +1
-1- See the UP.txt file in this directory. + See :ref:`up_rcu` for more information.This rendered as straight text after "make htmldocs" instead of producing a link in the HTML output. The HTML itself is:
<span class="xref std std-ref">up_rcu</span>
This doesn't look like something that would create a link, though I freely admit that my HTML is rather outdated.
The problem is that the reference target isn't called "up_rcu" in the file itself:
Documentation/RCU/UP.txt line 1
Quoted 7 lines
Documentation/RCU/UP.txt +1
-1@@ -1,17 +1,19 @@ -RCU on Uniprocessor Systems +.. _up_doc:
Certainly "up_rcu" seems like a better name. I do believe, though, that you can also use the title directly:
See RCU on Uniprocessor Systems_ for more information
Quoted 10 lines
Documentation/RCU/rcu.rst Frequently Asked Questions · line 70
Quoted 8 lines
- How can I see where RCU is currently used in the Linux kernel?
Documentation/RCU/rcu.rst +1
-1@@ -67,7 +67,7 @@ Frequently Asked Questions - Why the name "RCU"? - "RCU" stands for "read-copy update". The file listRCU.txt has + "RCU" stands for "read-copy update". :ref:`list_rcu` hasSame here for
list_rcu.
And the problem is the same, it's list_rcu_doc in the actual source file.
Jiang, as with so many things in software, if you haven't tested it, it probably doesn't work. Please actually run "make htmldocs" and look at the results to be sure that they are what you expect. (Along those lines, it would also be good to add the new directory to Documentation/index.rst so that it gets built with the rest).
Thanks,
jon
paulmck at linux.ibm.com (Paul E. McKenney)
PATCH v3 5/6 Documentation: RCU: Add links to rcu.rst
Quoted 28 lines · Jonathan Corbet
Quoted 10 lines · On Tue, 25 Jun 2019 08:56:23 -0700 "Paul E. McKenney" <paulmck at…
Documentation/RCU/rcu.rst Frequently Asked Questions · line 52
Quoted 2 lines
Documentation/RCU/rcu.rst +1
-1- See the UP.txt file in this directory. + See :ref:`up_rcu` for more information.This rendered as straight text after "make htmldocs" instead of producing a link in the HTML output. The HTML itself is:
<span class="xref std std-ref">up_rcu</span>
This doesn't look like something that would create a link, though I freely admit that my HTML is rather outdated.
The problem is that the reference target isn't called "
up_rcu" in the file itself:Documentation/RCU/UP.txt line 1
Quoted 7 lines
Documentation/RCU/UP.txt +1
-1@@ -1,17 +1,19 @@ -RCU on Uniprocessor Systems +.. _up_doc:Certainly "
up_rcu" seems like a better name. I do believe, though, that you can also use the title directly:
Quoted 1 line
See
RCU on Uniprocessor Systems_ for more information
That does look prettier, though we might want to do something more directly mapped for people directly reading the .rst files.
Quoted 11 lines
Quoted 10 lines
Documentation/RCU/rcu.rst Frequently Asked Questions · line 70
Quoted 8 lines
- How can I see where RCU is currently used in the Linux kernel?
Documentation/RCU/rcu.rst +1
-1@@ -67,7 +67,7 @@ Frequently Asked Questions - Why the name "RCU"? - "RCU" stands for "read-copy update". The file listRCU.txt has + "RCU" stands for "read-copy update". :ref:`list_rcu` hasSame here for
list_rcu.
Quoted 7 lines
And the problem is the same, it's
list_rcu_docin the actual source file.Jiang, as with so many things in software, if you haven't tested it, it probably doesn't work. Please actually run "make htmldocs" and look at the results to be sure that they are what you expect. (Along those lines, it would also be good to add the new directory to
Documentation/index.rstso that it gets built with the rest).
What Jon said on the "haven't test it, it probably doesn't work" thought. Sometimes I fear that my own work could be all too accurately modeled as random mutations with rcutorture providing needed natural selection. :-/
Thanx, Paul
Jonathan Corbet
maintainerPATCH v3 5/6 Documentation: RCU: Add links to rcu.rst
Quoted 7 lines · On Tue, 25 Jun 2019 14:17:40 -0700 "Paul E. McKenney" <paulmck at…
Quoted 4 lines
Certainly "
up_rcu" seems like a better name. I do believe, though, that you can also use the title directly:See
RCU on Uniprocessor Systems_ for more informationThat does look prettier, though we might want to do something more directly mapped for people directly reading the .rst files.
Yeah, the alternative there is to just say "Documentation/RCU/UP.rst". It's vaporware at the moment, but the plan is to recognize such strings and link them up automatically in the build process. It's easy enough to do, I just have to get around to it. In anticipation of that, just putting in the file name is probably the right thing to do.
Thanks,
jon
PATCH v3 5/6 Documentation: RCU: Add links to rcu.rst
Quoted 8 lines · Jonathan Corbet
Quoted 5 lines · On Tue, 25 Jun 2019 14:17:40 -0700 "Paul E. McKenney" <paulmck at…
Quoted 4 lines
Certainly "
up_rcu" seems like a better name. I do believe, though, that you can also use the title directly:See
RCU on Uniprocessor Systems_ for more information
Quoted 8 lines
Quoted 2 lines
That does look prettier, though we might want to do something more directly mapped for people directly reading the .rst files.
Yeah, the alternative there is to just say "
Documentation/RCU/UP.rst". It's vaporware at the moment, but the plan is to recognize such strings and link them up automatically in the build process. It's easy enough to do, I just have to get around to it. In anticipation of that, just putting in the file name is probably the right thing to do.
Works for me! Easy enough to cut-and-paste the filename into the corresponding portion of the URL, in the meantime.
Thanx, Paul
c0d1n61at3 at gmail.com (Jiunn Chang)
PATCH v3 6/6 Documentation: RCU: Add TOC tree hooks
In reply to c0d1n61at3 at gmail.com (Jiunn Chang)Add TOC tree hooks for:
- rcu
- list_rcu
- up_rcu
--- Documentation/RCU/index.rst | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 Documentation/RCU/index.rst
Documentation/RCU/index.rst new file +19 -0
@@ -0,0 +1,19 @@ +.. _rcu_concepts: + +============ +RCU concepts +============ + +.. toctree:: + :maxdepth: 1 + + rcu + list_rcu + up_rcu + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex`
Signature · 1 line
2.22.0
PATCH v2 1/7 Documentation: RCU: Convert RCU basic concepts to ReST
In reply to corbet at lwn.net (Jonathan Corbet)ReST markup and TOC tree hook.
--- Documentation/RCU/index.rst | 17 ++++++ Documentation/RCU/rcu.txt | 114 ++++++++++++++++++------------------ 2 files changed, 75 insertions(+), 56 deletions(-) create mode 100644 Documentation/RCU/index.rst
Documentation/RCU/index.rst new file +17 -0
@@ -0,0 +1,17 @@ +.. _rcu_concepts: + +============ +RCU concepts +============ + +.. toctree:: + :maxdepth: 1 + + rcu + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex`
Documentation/RCU/rcu.txt +58 -56
142 lines not on this page · raw message
Signature · 1 line
2.22.0
joel at joelfernandes.org (Joel Fernandes)
PATCH v2 1/7 Documentation: RCU: Convert RCU basic concepts to ReST
Quoted 3 lines · Jiunn Chang
ReST markup and TOC tree hook.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>
This one LGTM.
thanks,
- Joel
Quoted 180 lines
--- Documentation/RCU/index.rst | 17 ++++++ Documentation/RCU/rcu.txt | 114 ++++++++++++++++++------------------ 2 files changed, 75 insertions(+), 56 deletions(-) create mode 100644 Documentation/RCU/index.rstDocumentation/RCU/index.rst new file +17
-0@@ -0,0 +1,17 @@ +.. _rcu_concepts: + +============ +RCU concepts +============ + +.. toctree:: + :maxdepth: 1 + + rcu + +.. only:: subproject and html + + Indices + ======= + + * :ref:`genindex`Documentation/RCU/rcu.txt +58
-56@@ -1,5 +1,8 @@ -RCU Concepts +.. _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@@ -11,79 +14,78 @@ 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? +- 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. + 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? +- 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. + 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. + 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? +- 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. + See the UP.txt file in this directory. -o How can I see where RCU is currently used in the Linux kernel? +- 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: + 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 + (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html). -o What guidelines should I follow when writing code that uses RCU? +- What guidelines should I follow when writing code that uses RCU? - See the checklist.txt file in this directory. + See the checklist.txt file in this directory. -o Why the name "RCU"? +- 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. + "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? +- 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/). + 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? +- 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. + Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU + kernel configuration parameter. -o Where can I find more information on RCU? +- 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/. + See the RTFP.txt file in this directory. + Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).Signature · 1 line
2.22.0
c0d1n61at3 at gmail.com (Jiunn Chang)
PATCH v2 2/7 Documentation: RCU: Rename RCU basic concepts to ReST
In reply to corbet at lwn.net (Jonathan Corbet)Rename RCU basic concepts txt file to rst.
---
Documentation/RCU/{rcu.txt => rcu.rst} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename Documentation/RCU/{rcu.txt => rcu.rst} (100%)Documentation/RCU/rcu.rst renamed from Documentation/RCU/rcu.txt +0 -0
Signature · 1 line
2.22.0
c0d1n61at3 at gmail.com (Jiunn Chang)
PATCH v2 3/7 Documentation: RCU: Convert RCU linked list to ReST
In reply to corbet at lwn.net (Jonathan Corbet)ReST markup and TOC tree hook.
--- Documentation/RCU/index.rst | 1 + Documentation/RCU/listRCU.txt | 33 +++++++++++++++++++-------------- 2 files changed, 20 insertions(+), 14 deletions(-)
Documentation/RCU/index.rst +1 -0
@@ -8,6 +8,7 @@ RCU concepts :maxdepth: 1 rcu + list_rcu .. only:: subproject and html
Documentation/RCU/listRCU.txt +19 -14
@@ -1,14 +1,16 @@ -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 +(*struct list_head* in ``list.h``). One big advantage of this approach 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
@@ -234,10 +236,12 @@ 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? +:ref:`answer_quick_quiz` + 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 +272,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 +294,10 @@ flag under the spinlock as follows: return -EFAULT; /* No matching rule */ } +.. _answer_quick_quiz: 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,7 +308,6 @@ 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 to Quick Quiz Why does the search function need to return holding the per-entry lock for this deleted-flag technique to be helpful?
Signature · 1 line
2.22.0
PATCH v2 3/7 Documentation: RCU: Convert RCU linked list to ReST
Quoted 139 lines · Jiunn Chang
ReST markup and TOC tree hook.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>--- Documentation/RCU/index.rst | 1 + Documentation/RCU/listRCU.txt | 33 +++++++++++++++++++-------------- 2 files changed, 20 insertions(+), 14 deletions(-)Documentation/RCU/index.rst +1
-0@@ -8,6 +8,7 @@ RCU concepts :maxdepth: 1 rcu + list_rcu .. only:: subproject and htmlDocumentation/RCU/listRCU.txt +17
-13@@ -1,14 +1,16 @@ -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 +(*struct list_head* in ``list.h``). One big advantage of this approach 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@@ -234,10 +236,12 @@ 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? +:ref:`answer_quick_quiz` + 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 +272,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)
Documentation/RCU/listRCU.txt flag under the spinlock as follows: · line 297
Quoted 4 lines
Documentation/RCU/listRCU.txt +1
-0@@ -290,8 +294,10 @@ flag under the spinlock as follows: return -EFAULT; /* No matching rule */ } +.. _answer_quick_quiz:
Should the _answer_quick_quiz label below where 'Answer to Quick Quiz' is below?
Documentation/RCU/listRCU.txt If stale data cannot be tolerated, then a "deleted" flag may be used · line 310
Quoted 10 lines
Documentation/RCU/listRCU.txt +1
-0Summary +------- 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,7 +308,6 @@ 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.
That is, should it be here?
Quoted 7 lines
Documentation/RCU/listRCU.txt +0
-1- 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?Signature · 1 line
2.22.0
thanks,
- Joel
corbet at lwn.net (Jonathan Corbet)
PATCH v2 3/7 Documentation: RCU: Convert RCU linked list to ReST
In reply to c0d1n61at3 at gmail.com (Jiunn Chang)Quoted 25 lines · On Sun, 23 Jun 2019 03:14:09 -0500 Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
ReST markup and TOC tree hook.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>--- Documentation/RCU/index.rst | 1 + Documentation/RCU/listRCU.txt | 33 +++++++++++++++++++-------------- 2 files changed, 20 insertions(+), 14 deletions(-)Documentation/RCU/index.rst +1
-0@@ -8,6 +8,7 @@ RCU concepts :maxdepth: 1 rcu + list_rcu .. only:: subproject and htmlDocumentation/RCU/listRCU.txt +0
-0
Documentation/RCU/listRCU.txt line 7
Quoted 9 lines
Documentation/RCU/listRCU.txt +4
-2@@ -1,14 +1,16 @@ -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 +(*struct list_head* in ``list.h``). One big advantage of this approach
Thanks for taking out the function markup from before; now I'll ask you to take out this markup as well. As a general rule, we try to use the minimal amount of markup possible in our documentation in order to maximize the readability of the .rst files.
Thanks,
jon
c0d1n61at3 at gmail.com (Jiunn Chang)
PATCH v2 4/7 Documentation: RCU: Rename RCU linked list to ReST
In reply to corbet at lwn.net (Jonathan Corbet)Rename RCU linked list txt file to rst.
---
Documentation/RCU/{listRCU.txt => list_rcu.rst} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename Documentation/RCU/{listRCU.txt => list_rcu.rst} (100%)Documentation/RCU/list_rcu.rst renamed from Documentation/RCU/listRCU.txt +0 -0
Signature · 1 line
2.22.0
PATCH v2 5/7 Documentation: RCU: Convert RCU UP systems to ReST
In reply to corbet at lwn.net (Jonathan Corbet)ReST markup and TOC tree hook.
--- Documentation/RCU/UP.txt | 27 ++++++++++++++------------- Documentation/RCU/index.rst | 1 + 2 files changed, 15 insertions(+), 13 deletions(-)
Documentation/RCU/UP.txt +14 -13
@@ -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,11 @@ 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 +Quick Quiz #1: why is it *not* legal to invoke synchronize_rcu() in this case? - 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
@@ -78,23 +80,22 @@ or API changes would be required. Quick Quiz #2: What locking restriction must RCU callbacks respect? - 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? - 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.
@@ -119,7 +120,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:
Documentation/RCU/index.rst +1 -0
@@ -9,6 +9,7 @@ RCU concepts rcu list_rcu + up_rcu .. only:: subproject and html
Signature · 1 line
2.22.0
PATCH v2 5/7 Documentation: RCU: Convert RCU UP systems to ReST
Quoted 46 lines · Jiunn Chang
ReST markup and TOC tree hook.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>--- Documentation/RCU/UP.txt | 27 ++++++++++++++------------- Documentation/RCU/index.rst | 1 + 2 files changed, 15 insertions(+), 13 deletions(-)Documentation/RCU/UP.txt +6
-4@@ -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
Documentation/RCU/UP.txt its arguments would cause it to fail to make the fundamental guarantee · line 51
Quoted 5 lines
Documentation/RCU/UP.txt +1
-1@@ -46,11 +48,11 @@ 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 +Quick Quiz #1: why is it *not* legal to invoke synchronize_rcu() in
To keep it consistent - here you can link to the quick quiz answers as well, like you did for list_rcu.rst
Other than that it looks fine to me.
thanks,
- Joel
Quoted 61 lines
Documentation/RCU/UP.txt +7
-8this case? - 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@@ -78,23 +80,22 @@ or API changes would be required. Quick Quiz #2: What locking restriction must RCU callbacks respect? - 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? - 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.@@ -119,7 +120,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:Documentation/RCU/index.rst +1
-0@@ -9,6 +9,7 @@ RCU concepts rcu list_rcu + up_rcu .. only:: subproject and htmlSignature · 1 line
2.22.0
corbet at lwn.net (Jonathan Corbet)
PATCH v2 5/7 Documentation: RCU: Convert RCU UP systems to ReST
In reply to Jiunn ChangQuoted 15 lines · On Sun, 23 Jun 2019 03:14:11 -0500 Jiunn Chang <c0d1n61at3 at gmail.com> wrote:
ReST markup and TOC tree hook.
Signed-off-by Jiunn Chang <c0d1n61at3 at gmail.com>--- Documentation/RCU/UP.txt | 27 ++++++++++++++------------- Documentation/RCU/index.rst | 1 + 2 files changed, 15 insertions(+), 13 deletions(-)Documentation/RCU/UP.txt +1
-1@@ -1,17 +1,19 @@ -RCU on Uniprocessor Systems +.. _up_doc:
Documentation/RCU/UP.txt line 10
Quoted 10 lines
Documentation/RCU/UP.txt +3
-1+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*
Just in case you're wondering, this markup is fine; it's an actual emphasis that you're preserving from the original.
Quoted 21 lines
Documentation/RCU/UP.txt +2
-2work 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
Documentation/RCU/UP.txt its arguments would cause it to fail to make the fundamental guarantee · line 52
Quoted 6 lines
Documentation/RCU/UP.txt +1
-1@@ -46,11 +48,11 @@ 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 +Quick Quiz #1: why is it *not* legal to invoke synchronize_rcu() in this case?
Have you actually built the docs with these changes and looked at the results? This will not render the way you might like.
Thanks,
jon
PATCH v2 6/7 Documentation: RCU: Rename RCU UP systems to ReST
In reply to corbet at lwn.net (Jonathan Corbet)Rename RCU UP systems txt file to rst.
---
Documentation/RCU/{UP.txt => up_rcu.rst} | 0
1 file changed, 0 insertions(+), 0 deletions(-)
rename Documentation/RCU/{UP.txt => up_rcu.rst} (100%)Documentation/RCU/up_rcu.rst renamed from Documentation/RCU/UP.txt +0 -0
Signature · 1 line
2.22.0
PATCH v2 7/7 Documentation: RCU: Add links to rcu.rst
In reply to corbet at lwn.net (Jonathan Corbet)Add the following links to rcu.rst:
list_rcu
up_rcu
--- Documentation/RCU/rcu.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/RCU/rcu.rst +4 -4
@@ -11,8 +11,8 @@ 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. +a grace period to elapse, then free the element. See :ref:`list_rcu` +for more information on using RCU with linked lists. Frequently Asked Questions
@@ -49,7 +49,7 @@ Frequently Asked Questions - 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. + See :ref:`up_rcu` for more information. - How can I see where RCU is currently used in the Linux kernel?
@@ -67,7 +67,7 @@ Frequently Asked Questions - Why the name "RCU"? - "RCU" stands for "read-copy update". The file listRCU.txt has + "RCU" stands for "read-copy update". :ref:`list_rcu` has more information on where this name came from, search for "read-copy update" to find it.
Signature · 1 line
2.22.0