Skip to contentSkip to conversation

Fix trivial nits in RCU docs

PATCH Superseded SeongJae Park 2 participants 10 messages Jan 6, 2020

Subsystems (3)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

v2 cover Fix trivial nits in RCU docs

This patchset fixes trivial nits in the RCU documentations.

It is based on the latest dev branch of Paul's linux-rcu git repository. The Complete git tree is also available at
https://github.com/sjp38/linux/tree/patches/rcu/docs/2019-12-31/v2.

Changes from v1
(https://lore.kernel.org/linux-doc/[email protected]/)

- Add 'Reviewed-by' from Madhuparna
- Fix wrong author email address
- Rebased on latest dev branch of Paul's linux-rcu git repository.

SeongJae Park (7):
doc/RCU/Design: Remove remaining HTML tags in ReST files doc/RCU/listRCU: Fix typos in a example code snippets doc/RCU/listRCU: Update example function name doc/RCU/rcu: Use ':ref:' for links to other docs doc/RCU/rcu: Use absolute paths for non-rst files doc/RCU/rcu: Use https instead of http if possible
rcu: Fix typos in beginning comments

 .../Tree-RCU-Memory-Ordering.rst               |  8 ++++----
 Documentation/RCU/listRCU.rst                  | 10 +++++-----
 Documentation/RCU/rcu.rst                      | 18 +++++++++---------
 kernel/rcu/srcutree.c                          |  2 +-
 kernel/rcu/tree.c                              |  4 ++--
 5 files changed, 21 insertions(+), 21 deletions(-)
Signature · 1 line
2.17.1
#1 lore raw

PATCH v2 1/7 doc/RCU/Design: Remove remaining HTML tags in ReST files

Commit ccc9971e2147 ("docs: rcu: convert some articles from html to ReST") has converted a few of html RCU docs into ReST files, but a few of html tags which not supported on rst is remaining. This commit converts those to ReST appropriate alternatives.

---
 .../Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst   | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst +4 -4
index 1a8b129cfc04..83ae3b79a643 100644
@@ -4,7 +4,7 @@ A Tour Through TREE_RCU's Grace-Period Memory Ordering
 
 August 8, 2017
 
-This article was contributed by Paul E. McKenney
+This article was contributed by Paul E. McKenney
 
 Introduction
 ============
@@ -48,7 +48,7 @@ Tree RCU Grace Period Memory Ordering Building Blocks
 
 The workhorse for RCU's grace-period memory ordering is the
 critical section for the ``rcu_node`` structure's
-``->lock``. These critical sections use helper functions for lock
+``->lock``. These critical sections use helper functions for lock
 acquisition, including ``raw_spin_lock_rcu_node()``,
 ``raw_spin_lock_irq_rcu_node()``, and ``raw_spin_lock_irqsave_rcu_node()``.
 Their lock-release counterparts are ``raw_spin_unlock_rcu_node()``,
@@ -102,9 +102,9 @@ lock-acquisition and lock-release functions::
    23   r3 = READ_ONCE(x);
    24 }
    25
-   26 WARN_ON(r1 == 0 && r2 == 0 && r3 == 0);
+   26 WARN_ON(r1 == 0 && r2 == 0 && r3 == 0);
 
-The ``WARN_ON()`` is evaluated at “the end of time”,
+The ``WARN_ON()`` is evaluated at "the end of time",
 after all changes have propagated throughout the system.
 Without the ``smp_mb__after_unlock_lock()`` provided by the
 acquisition functions, this ``WARN_ON()`` could trigger, for example
Signature · 1 line
2.17.1
#2 lore raw

PATCH v2 2/7 doc/RCU/listRCU: Fix typos in a example code snippets

In reply to SeongJae Park
---
 Documentation/RCU/listRCU.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/RCU/listRCU.rst +2 -2
index 55d2b30db481..e768f56e8fa3 100644
@@ -226,7 +226,7 @@ need to be filled in)::
 		list_for_each_entry(e, list, list) {
 			if (!audit_compare_rule(rule, &e->rule)) {
 				e->rule.action = newaction;
-				e->rule.file_count = newfield_count;
+				e->rule.field_count = newfield_count;
 				write_unlock(&auditsc_lock);
 				return 0;
 			}
@@ -255,7 +255,7 @@ RCU (*read-copy update*) its name.  The RCU code is as follows::
 					return -ENOMEM;
 				audit_copy_rule(&ne->rule, &e->rule);
 				ne->rule.action = newaction;
-				ne->rule.file_count = newfield_count;
+				ne->rule.field_count = newfield_count;
 				list_replace_rcu(&e->list, &ne->list);
 				call_rcu(&e->rcu, audit_free_rule);
 				return 0;
Signature · 1 line
2.17.1
#3 lore raw

PATCH v2 3/7 doc/RCU/listRCU: Update example function name

In reply to SeongJae Park

listRCU.rst document gives an example with 'ipc_lock()', but the function has dropped off by commit 82061c57ce93 ("ipc: drop ipc_lock()"). Because the main logic of 'ipc_lock()' has melded in 'shm_lock()' by the commit, this commit updates the document to use 'shm_lock()' instead.

---
 Documentation/RCU/listRCU.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)
Documentation/RCU/listRCU.rst +3 -3
index e768f56e8fa3..2a643e293fb4 100644
@@ -286,11 +286,11 @@ time the external state changes before Linux becomes aware of the change,
 additional RCU-induced staleness is generally not a problem.
 
 However, there are many examples where stale data cannot be tolerated.
-One example in the Linux kernel is the System V IPC (see the ipc_lock()
-function in ipc/util.c).  This code checks a *deleted* flag under a
+One example in the Linux kernel is the System V IPC (see the shm_lock()
+function in ipc/shm.c).  This code checks a *deleted* flag under a
 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 lock, as ipc_lock() does in fact do.
+return holding the per-entry spinlock, as shm_lock() does in fact do.
 
 .. _quick_quiz:
 
Signature · 1 line
2.17.1
#4 lore raw

PATCH v2 4/7 doc/RCU/rcu: Use ':ref:' for links to other docs

In reply to SeongJae Park
---
 Documentation/RCU/rcu.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)
Documentation/RCU/rcu.rst +6 -6
index 8dfb437dacc3..a1dd71d01862 100644
@@ -11,8 +11,8 @@ must be long enough that any readers accessing the item being deleted have
 since dropped their references.  For example, an RCU-protected deletion
 from a linked list would first remove the item from the list, wait for
 a grace period to elapse, then free the element.  See the
-Documentation/RCU/listRCU.rst file for more information on using RCU with
-linked lists.
+:ref:`Documentation/RCU/listRCU.rst <list_rcu_doc>` for more information on
+using RCU with linked lists.
 
 Frequently Asked Questions
 --------------------------
@@ -50,7 +50,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 Documentation/RCU/UP.rst file for more information.
+  See :ref:`Documentation/RCU/UP.rst <up_doc>` for more information.
 
 - How can I see where RCU is currently used in the Linux kernel?
 
@@ -68,9 +68,9 @@ Frequently Asked Questions
 
 - Why the name "RCU"?
 
-  "RCU" stands for "read-copy update".  The file Documentation/RCU/listRCU.rst
-  has more information on where this name came from, search for
-  "read-copy update" to find it.
+  "RCU" stands for "read-copy update".
+  :ref:`Documentation/RCU/listRCU.rst <list_rcu_doc>` has more information on where
+  this name came from, search for "read-copy update" to find it.
 
 - I hear that RCU is patented?  What is with that?
 
Signature · 1 line
2.17.1
#5 lore raw

PATCH v2 5/7 doc/RCU/rcu: Use absolute paths for non-rst files

In reply to SeongJae Park
---
 Documentation/RCU/rcu.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/RCU/rcu.rst +2 -2
index a1dd71d01862..2a830c51477e 100644
@@ -75,7 +75,7 @@ Frequently Asked Questions
 - 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.
+  search for the string "Patent" in Documentation/RCU/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
@@ -88,5 +88,5 @@ Frequently Asked Questions
 
 - Where can I find more information on RCU?
 
-  See the RTFP.txt file in this directory.
+  See the Documentation/RCU/RTFP.txt file.
   Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).
Signature · 1 line
2.17.1
#6 lore raw

PATCH v2 6/7 doc/RCU/rcu: Use https instead of http if possible

In reply to SeongJae Park
---
 Documentation/RCU/rcu.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/RCU/rcu.rst +1 -1
index 2a830c51477e..0e03c6ef3147 100644
@@ -79,7 +79,7 @@ Frequently Asked Questions
   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/).
+  available (https://liburcu.org/).
 
 - I hear that RCU needs work in order to support realtime kernels?
 
Signature · 1 line
2.17.1
#7 lore raw

PATCH v2 7/7 rcu: Fix typos in beginning comments

In reply to SeongJae Park
---
 kernel/rcu/srcutree.c | 2 +-
 kernel/rcu/tree.c     | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)
kernel/rcu/srcutree.c +1 -1
index 3c4e6441bbf9..0b561480e6c4 100644
@@ -5,7 +5,7 @@
  * Copyright (C) IBM Corporation, 2006
  * Copyright (C) Fujitsu, 2012
  *
- * Author: Paul McKenney <[email protected]>
+ * Authors: Paul McKenney <[email protected]>
  *	   Lai Jiangshan <[email protected]>
  *
  * For detailed explanation of Read-Copy Update mechanism see -
kernel/rcu/tree.c +2 -2
index 982c7b48cd9b..8367fc080801 100644
@@ -1,12 +1,12 @@
 // SPDX-License-Identifier: GPL-2.0+
 /*
- * Read-Copy Update mechanism for mutual exclusion
+ * Read-Copy Update mechanism for mutual exclusion (tree-based version)
  *
  * Copyright IBM Corporation, 2008
  *
  * Authors: Dipankar Sarma <[email protected]>
  *	    Manfred Spraul <[email protected]>
- *	    Paul E. McKenney <[email protected]> Hierarchical version
+ *	    Paul E. McKenney <[email protected]>
  *
  * Based on the original work by Paul McKenney <[email protected]>
  * and inputs from Rusty Russell, Andrea Arcangeli and Andi Kleen.
Signature · 1 line
2.17.1
#8 lore raw
In reply to SeongJae Park

Author email ([email protected]) is not applied to this patch set mails... Maybe my git send-email setting is somewhere broken. Sorry, I will correct this and send v3 soon.

Thanks,
SeongJae Park

Quoted 32 lines · On Mon, 6 Jan 2020 20:18:45 +0100 SeongJae Park <[email protected]>…

This patchset fixes trivial nits in the RCU documentations.

It is based on the latest dev branch of Paul's linux-rcu git repository. The Complete git tree is also available at
https://github.com/sjp38/linux/tree/patches/rcu/docs/2019-12-31/v2.

Changes from v1
(https://lore.kernel.org/linux-doc/[email protected]/)

- Add 'Reviewed-by' from Madhuparna
- Fix wrong author email address
- Rebased on latest dev branch of Paul's linux-rcu git repository.

SeongJae Park (7):
doc/RCU/Design: Remove remaining HTML tags in ReST files doc/RCU/listRCU: Fix typos in a example code snippets doc/RCU/listRCU: Update example function name doc/RCU/rcu: Use ':ref:' for links to other docs doc/RCU/rcu: Use absolute paths for non-rst files doc/RCU/rcu: Use https instead of http if possible
rcu: Fix typos in beginning comments

 .../Tree-RCU-Memory-Ordering.rst               |  8 ++++----
 Documentation/RCU/listRCU.rst                  | 10 +++++-----
 Documentation/RCU/rcu.rst                      | 18 +++++++++---------
 kernel/rcu/srcutree.c                          |  2 +-
 kernel/rcu/tree.c                              |  4 ++--
 5 files changed, 21 insertions(+), 21 deletions(-)
Signature · 1 line
2.17.1
maintainer
#9 lore raw
Quoted 3 lines · SeongJae Park

Author email ([email protected]) is not applied to this patch set mails... Maybe my git send-email setting is somewhere broken. Sorry, I will correct this and send v3 soon.

Given my recent change in email address, I can certainly sympathize! ;-)

Thanx, Paul

Quoted 37 lines

Thanks,
SeongJae Park

Quoted 32 lines · On Mon, 6 Jan 2020 20:18:45 +0100 SeongJae Park <[email protected]>…

This patchset fixes trivial nits in the RCU documentations.

It is based on the latest dev branch of Paul's linux-rcu git repository. The Complete git tree is also available at
https://github.com/sjp38/linux/tree/patches/rcu/docs/2019-12-31/v2.

Changes from v1
(https://lore.kernel.org/linux-doc/[email protected]/)

- Add 'Reviewed-by' from Madhuparna
- Fix wrong author email address
- Rebased on latest dev branch of Paul's linux-rcu git repository.

SeongJae Park (7):
doc/RCU/Design: Remove remaining HTML tags in ReST files doc/RCU/listRCU: Fix typos in a example code snippets doc/RCU/listRCU: Update example function name doc/RCU/rcu: Use ':ref:' for links to other docs doc/RCU/rcu: Use absolute paths for non-rst files doc/RCU/rcu: Use https instead of http if possible
rcu: Fix typos in beginning comments

 .../Tree-RCU-Memory-Ordering.rst               |  8 ++++----
 Documentation/RCU/listRCU.rst                  | 10 +++++-----
 Documentation/RCU/rcu.rst                      | 18 +++++++++---------
 kernel/rcu/srcutree.c                          |  2 +-
 kernel/rcu/tree.c                              |  4 ++--
 5 files changed, 21 insertions(+), 21 deletions(-)
Signature · 1 line
2.17.1