[PATCH v2 0/7] Fix trivial nits in RCU docs

[PATCH v2 0/7] Fix trivial nits in RCU docs

[SeongJae Park]

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/20191231151549.12797-1-sjpark@amazon.de/)

 - 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(-)

-- 
2.17.1

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

[SeongJae Park]

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.

Reviewed-by: Madhuparna Bhowmik <madhuparnabhowmik04@gmail.com>
Signed-off-by: SeongJae Park <sjpark@amazon.de>
---
 .../Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst   | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
index 1a8b129cfc04..83ae3b79a643 100644
--- a/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
+++ b/Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst
@@ -4,7 +4,7 @@ A Tour Through TREE_RCU's Grace-Period Memory Ordering
 
 August 8, 2017
 
-This article was contributed by Paul E.&nbsp;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
-``-&gt;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 &amp;&amp; r2 == 0 &amp;&amp; r3 == 0);
+   26 WARN_ON(r1 == 0 && r2 == 0 && r3 == 0);
 
-The ``WARN_ON()`` is evaluated at &ldquo;the end of time&rdquo;,
+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
-- 
2.17.1

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

[SeongJae Park]

Signed-off-by: SeongJae Park <sjpark@amazon.de>
---
 Documentation/RCU/listRCU.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
index 55d2b30db481..e768f56e8fa3 100644
--- a/Documentation/RCU/listRCU.rst
+++ b/Documentation/RCU/listRCU.rst
@@ -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;
-- 
2.17.1

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

[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.

Reviewed-by: Madhuparna Bhowmik <madhuparnabhowmik04@gmail.com>
Signed-off-by: SeongJae Park <sjpark@amazon.de>
---
 Documentation/RCU/listRCU.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/RCU/listRCU.rst b/Documentation/RCU/listRCU.rst
index e768f56e8fa3..2a643e293fb4 100644
--- a/Documentation/RCU/listRCU.rst
+++ b/Documentation/RCU/listRCU.rst
@@ -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:
 
-- 
2.17.1

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

[SeongJae Park]

Signed-off-by: SeongJae Park <sjpark@amazon.de>
---
 Documentation/RCU/rcu.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index 8dfb437dacc3..a1dd71d01862 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -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?
 
-- 
2.17.1

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

[SeongJae Park]

Signed-off-by: SeongJae Park <sjpark@amazon.de>
---
 Documentation/RCU/rcu.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index a1dd71d01862..2a830c51477e 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -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/).
-- 
2.17.1

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

[SeongJae Park]

Signed-off-by: SeongJae Park <sjpark@amazon.de>
---
 Documentation/RCU/rcu.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/RCU/rcu.rst b/Documentation/RCU/rcu.rst
index 2a830c51477e..0e03c6ef3147 100644
--- a/Documentation/RCU/rcu.rst
+++ b/Documentation/RCU/rcu.rst
@@ -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?
 
-- 
2.17.1

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

[SeongJae Park]

Signed-off-by: SeongJae Park <sjpark@amazon.de>
---
 kernel/rcu/srcutree.c | 2 +-
 kernel/rcu/tree.c     | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/kernel/rcu/srcutree.c b/kernel/rcu/srcutree.c
index 3c4e6441bbf9..0b561480e6c4 100644
--- a/kernel/rcu/srcutree.c
+++ b/kernel/rcu/srcutree.c
@@ -5,7 +5,7 @@
  * Copyright (C) IBM Corporation, 2006
  * Copyright (C) Fujitsu, 2012
  *
- * Author: Paul McKenney <paulmck@linux.ibm.com>
+ * Authors: Paul McKenney <paulmck@linux.ibm.com>
  *	   Lai Jiangshan <laijs@cn.fujitsu.com>
  *
  * For detailed explanation of Read-Copy Update mechanism see -
diff --git a/kernel/rcu/tree.c b/kernel/rcu/tree.c
index 982c7b48cd9b..8367fc080801 100644
--- a/kernel/rcu/tree.c
+++ b/kernel/rcu/tree.c
@@ -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 <dipankar@in.ibm.com>
  *	    Manfred Spraul <manfred@colorfullife.com>
- *	    Paul E. McKenney <paulmck@linux.ibm.com> Hierarchical version
+ *	    Paul E. McKenney <paulmck@linux.ibm.com>
  *
  * Based on the original work by Paul McKenney <paulmck@linux.ibm.com>
  * and inputs from Rusty Russell, Andrea Arcangeli and Andi Kleen.
-- 
2.17.1

Re: [PATCH v2 0/7] Fix trivial nits in RCU docs

[SeongJae Park]

Author email (sjpark@amazon.de) 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

On   Mon,  6 Jan 2020 20:18:45 +0100   SeongJae Park <sj38.park@gmail.com> wrote:

> 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/20191231151549.12797-1-sjpark@amazon.de/)
> 
>  - 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(-)
> 
> -- 
> 2.17.1
> 

Re: [PATCH v2 0/7] Fix trivial nits in RCU docs

[Paul E. McKenney]

On Mon, Jan 06, 2020 at 08:43:30PM +0100, SeongJae Park wrote:
> Author email (sjpark@amazon.de) 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

> Thanks,
> SeongJae Park
> 
> On   Mon,  6 Jan 2020 20:18:45 +0100   SeongJae Park <sj38.park@gmail.com> wrote:
> 
> > 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/20191231151549.12797-1-sjpark@amazon.de/)
> > 
> >  - 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(-)
> > 
> > -- 
> > 2.17.1
> >