Skip to contentSkip to conversation

Documentation updates for v5.9

PATCH New Paul E. McKenney 1 participant 11 messages Jun 23, 2020

Subsystems (6)
Networking Documentation Sockets RCU +2 more subsystems
lore
Share & tools
lore

Paul E. McKenney

author maintainer
#0 lore raw

cover Documentation updates for v5.9

Hello!

This series provides documentation updates.

1-7. Convert Documentation/RCU files to .rst, courtesy of Mauro
Carvalho Chehab.

8. RCU: Don't duplicate chapter names in rculist_nulls.rst, courtesy
of Mauro Carvalho Chehab.

9. Timer problems can cause RCU CPU stall warnings.

10. Tasks RCU must protect instructions before trampoline.

Thanx, Paul

------------------------------------------------------------------------

 Documentation/RCU/rculist_nulls.txt                      |  172 ------------
 b/Documentation/RCU/Design/Requirements/Requirements.rst |    7 
 b/Documentation/RCU/checklist.rst                        |   17 -
 b/Documentation/RCU/index.rst                            |    9 
 b/Documentation/RCU/lockdep-splat.rst                    |  109 ++++----
 b/Documentation/RCU/lockdep.rst                          |   12 
 b/Documentation/RCU/rculist_nulls.rst                    |  200 +++++++++++++++
 b/Documentation/RCU/rcuref.rst                           |  199 +++++++-------
 b/Documentation/RCU/stallwarn.rst                        |   62 +++-
 b/Documentation/RCU/torture.rst                          |  117 ++++----
 b/Documentation/locking/locktorture.rst                  |    2 
 b/MAINTAINERS                                            |    4 
 b/include/linux/rculist_nulls.h                          |    2 
 b/kernel/rcu/rcutorture.c                                |    2 
 b/kernel/rcu/tree_stall.h                                |    4 
 b/net/core/sock.c                                        |    4 
 16 files changed, 509 insertions(+), 413 deletions(-)
author maintainer
#1 lore raw

PATCH 1/10 docs: RCU: Convert checklist.txt to ReST

From: Mauro Carvalho Chehab <[email protected]>

- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Use the right list markups;
- Add it to RCU/index.rst.

---
 Documentation/RCU/{checklist.txt => checklist.rst} | 17 ++++++++++++-----
 Documentation/RCU/index.rst                        |  3 +++
 2 files changed, 15 insertions(+), 5 deletions(-)
 rename Documentation/RCU/{checklist.txt => checklist.rst} (98%)
Documentation/RCU/checklist.rst renamed from Documentation/RCU/checklist.txt +12 -5
similarity index 98%
rename from Documentation/RCU/checklist.txt
rename to Documentation/RCU/checklist.rst
index e98ff26..2efed99 100644
@@ -1,4 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+================================
 Review Checklist for RCU Patches
+================================
 
 
 This document contains a checklist for producing and reviewing patches
@@ -411,18 +415,21 @@ over a rather long period of time, but improvements are always welcome!
 	__rcu sparse checks to validate your RCU code.	These can help
 	find problems as follows:
 
-	CONFIG_PROVE_LOCKING: check that accesses to RCU-protected data
+	CONFIG_PROVE_LOCKING:
+		check that accesses to RCU-protected data
 		structures are carried out under the proper RCU
 		read-side critical section, while holding the right
 		combination of locks, or whatever other conditions
 		are appropriate.
 
-	CONFIG_DEBUG_OBJECTS_RCU_HEAD: check that you don't pass the
+	CONFIG_DEBUG_OBJECTS_RCU_HEAD:
+		check that you don't pass the
 		same object to call_rcu() (or friends) before an RCU
 		grace period has elapsed since the last time that you
 		passed that same object to call_rcu() (or friends).
 
-	__rcu sparse checks: tag the pointer to the RCU-protected data
+	__rcu sparse checks:
+		tag the pointer to the RCU-protected data
 		structure with __rcu, and sparse will warn you if you
 		access that pointer without the services of one of the
 		variants of rcu_dereference().
@@ -442,8 +449,8 @@ over a rather long period of time, but improvements are always welcome!
 
 	You instead need to use one of the barrier functions:
 
-	o	call_rcu() -> rcu_barrier()
-	o	call_srcu() -> srcu_barrier()
+	-	call_rcu() -> rcu_barrier()
+	-	call_srcu() -> srcu_barrier()
 
 	However, these barrier functions are absolutely -not- guaranteed
 	to wait for a grace period.  In fact, if there are no call_rcu()
Documentation/RCU/index.rst +3 -0
index 81a0a1e..c1ba4d1 100644
@@ -1,3 +1,5 @@
+.. SPDX-License-Identifier: GPL-2.0
+
 .. _rcu_concepts:
 
 ============
@@ -8,6 +10,7 @@ RCU concepts
    :maxdepth: 3
 
    arrayRCU
+   checklist
    rcubarrier
    rcu_dereference
    whatisRCU
Signature · 1 line
2.9.5
author maintainer
#2 lore raw

PATCH 2/10 docs: RCU: Convert lockdep-splat.txt to ReST

In reply to Paul E. McKenney

From: Mauro Carvalho Chehab <[email protected]>

- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.

---
 Documentation/RCU/index.rst                        |   1 +
 .../RCU/{lockdep-splat.txt => lockdep-splat.rst}   | 109 +++++++++++----------
 2 files changed, 58 insertions(+), 52 deletions(-)
 rename Documentation/RCU/{lockdep-splat.txt => lockdep-splat.rst} (54%)
Documentation/RCU/index.rst +1 -0
index c1ba4d1..430a371 100644
@@ -11,6 +11,7 @@ RCU concepts
 
    arrayRCU
    checklist
+   lockdep-splat
    rcubarrier
    rcu_dereference
    whatisRCU
Documentation/RCU/lockdep-splat.rst renamed from Documentation/RCU/lockdep-splat.txt +57 -52

136 lines not on this page · raw message

Signature · 1 line
2.9.5
author maintainer
#3 lore raw

PATCH 3/10 docs: RCU: Convert lockdep.txt to ReST

In reply to Paul E. McKenney

From: Mauro Carvalho Chehab <[email protected]>

- Add a SPDX header;
- Adjust document title;
- Mark literal blocks as such;
- Add it to RCU/index.rst.

---
 Documentation/RCU/index.rst                    |  1 +
 Documentation/RCU/{lockdep.txt => lockdep.rst} | 12 ++++++++----
 2 files changed, 9 insertions(+), 4 deletions(-)
 rename Documentation/RCU/{lockdep.txt => lockdep.rst} (96%)
Documentation/RCU/index.rst +1 -0
index 430a371..fa7a2a8 100644
@@ -11,6 +11,7 @@ RCU concepts
 
    arrayRCU
    checklist
+   lockdep
    lockdep-splat
    rcubarrier
    rcu_dereference
Documentation/RCU/lockdep.rst renamed from Documentation/RCU/lockdep.txt +8 -4
similarity index 96%
rename from Documentation/RCU/lockdep.txt
rename to Documentation/RCU/lockdep.rst
index 89db949e..f1fc8ae 100644
@@ -1,4 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
 RCU and lockdep checking
+========================
 
 All flavors of RCU have lockdep checking available, so that lockdep is
 aware of when each task enters and leaves any flavor of RCU read-side
@@ -8,7 +12,7 @@ tracking to include RCU state, which can sometimes help when debugging
 deadlocks and the like.
 
 In addition, RCU provides the following primitives that check lockdep's
-state:
+state::
 
 	rcu_read_lock_held() for normal RCU.
 	rcu_read_lock_bh_held() for RCU-bh.
@@ -63,7 +67,7 @@ checking of rcu_dereference() primitives:
 The rcu_dereference_check() check expression can be any boolean
 expression, but would normally include a lockdep expression.  However,
 any boolean expression can be used.  For a moderately ornate example,
-consider the following:
+consider the following::
 
 	file = rcu_dereference_check(fdt->fd[fd],
 				     lockdep_is_held(&files->file_lock) ||
@@ -82,7 +86,7 @@ RCU read-side critical sections, in case (2) the ->file_lock prevents
 any change from taking place, and finally, in case (3) the current task
 is the only task accessing the file_struct, again preventing any change
 from taking place.  If the above statement was invoked only from updater
-code, it could instead be written as follows:
+code, it could instead be written as follows::
 
 	file = rcu_dereference_protected(fdt->fd[fd],
 					 lockdep_is_held(&files->file_lock) ||
@@ -105,7 +109,7 @@ false and they are called from outside any RCU read-side critical section.
 
 For example, the workqueue for_each_pwq() macro is intended to be used
 either within an RCU read-side critical section or with wq->mutex held.
-It is thus implemented as follows:
+It is thus implemented as follows::
 
 	#define for_each_pwq(pwq, wq)
 		list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,
Signature · 1 line
2.9.5
author maintainer
#4 lore raw

PATCH 4/10 docs: RCU: Convert rculist_nulls.txt to ReST

In reply to Paul E. McKenney

From: Mauro Carvalho Chehab <[email protected]>

- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.

---
 Documentation/RCU/index.rst         |   1 +
 Documentation/RCU/rculist_nulls.rst | 194 ++++++++++++++++++++++++++++++++++++
 Documentation/RCU/rculist_nulls.txt | 172 --------------------------------
 include/linux/rculist_nulls.h       |   2 +-
 net/core/sock.c                     |   4 +-
 5 files changed, 198 insertions(+), 175 deletions(-)
 create mode 100644 Documentation/RCU/rculist_nulls.rst
 delete mode 100644 Documentation/RCU/rculist_nulls.txt
Documentation/RCU/index.rst +1 -0
index fa7a2a8..577a47e 100644
@@ -17,6 +17,7 @@ RCU concepts
    rcu_dereference
    whatisRCU
    rcu
+   rculist_nulls
    listRCU
    NMI-RCU
    UP
Documentation/RCU/rculist_nulls.rst new file +194 -0

194 lines not on this page · raw message

Documentation/RCU/rculist_nulls.txt deleted +0 -172

172 lines not on this page · raw message

include/linux/rculist_nulls.h +1 -1
index 9670b54..ff3e947 100644
@@ -162,7 +162,7 @@ static inline void hlist_nulls_add_fake(struct hlist_nulls_node *n)
  * The barrier() is needed to make sure compiler doesn't cache first element [1],
  * as this loop can be restarted [2]
  * [1] Documentation/core-api/atomic_ops.rst around line 114
- * [2] Documentation/RCU/rculist_nulls.txt around line 146
+ * [2] Documentation/RCU/rculist_nulls.rst around line 146
  */
 #define hlist_nulls_for_each_entry_rcu(tpos, pos, head, member)			\
 	for (({barrier();}),							\
net/core/sock.c +2 -2
index 6c4acf1..37229cf 100644
@@ -1972,7 +1972,7 @@ struct sock *sk_clone_lock(const struct sock *sk, const gfp_t priority)
 
 		/*
 		 * Before updating sk_refcnt, we must commit prior changes to memory
-		 * (Documentation/RCU/rculist_nulls.txt for details)
+		 * (Documentation/RCU/rculist_nulls.rst for details)
 		 */
 		smp_wmb();
 		refcount_set(&newsk->sk_refcnt, 2);
@@ -3033,7 +3033,7 @@ void sock_init_data(struct socket *sock, struct sock *sk)
 	sk_rx_queue_clear(sk);
 	/*
 	 * Before updating sk_refcnt, we must commit prior changes to memory
-	 * (Documentation/RCU/rculist_nulls.txt for details)
+	 * (Documentation/RCU/rculist_nulls.rst for details)
 	 */
 	smp_wmb();
 	refcount_set(&sk->sk_refcnt, 1);
Signature · 1 line
2.9.5
author maintainer
#5 lore raw

PATCH 5/10 docs: RCU: Convert torture.txt to ReST

In reply to Paul E. McKenney

From: Mauro Carvalho Chehab <[email protected]>

- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.

---
 Documentation/RCU/index.rst                    |   1 +
 Documentation/RCU/{torture.txt => torture.rst} | 117 ++++++++++++++-----------
 Documentation/locking/locktorture.rst          |   2 +-
 MAINTAINERS                                    |   4 +-
 kernel/rcu/rcutorture.c                        |   2 +-
 5 files changed, 69 insertions(+), 57 deletions(-)
 rename Documentation/RCU/{torture.txt => torture.rst} (76%)
Documentation/RCU/index.rst +1 -0
index 577a47e..5d5f9a1 100644
@@ -18,6 +18,7 @@ RCU concepts
    whatisRCU
    rcu
    rculist_nulls
+   torture
    listRCU
    NMI-RCU
    UP
Documentation/RCU/torture.rst renamed from Documentation/RCU/torture.txt +64 -53

251 lines not on this page · raw message

Documentation/locking/locktorture.rst +1 -1
index 8012a74..dfaf9fc 100644
@@ -166,4 +166,4 @@ checked for such errors.  The "rmmod" command forces a "SUCCESS",
 two are self-explanatory, while the last indicates that while there
 were no locking failures, CPU-hotplug problems were detected.
 
-Also see: Documentation/RCU/torture.txt
+Also see: Documentation/RCU/torture.rst
MAINTAINERS +2 -2
index 68f21d4..62b67aa 100644
@@ -14424,7 +14424,7 @@ T:	git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
 F:	Documentation/RCU/
 F:	include/linux/rcu*
 F:	kernel/rcu/
-X:	Documentation/RCU/torture.txt
+X:	Documentation/RCU/torture.rst
 X:	include/linux/srcu*.h
 X:	kernel/rcu/srcu*.c
 
@@ -17273,7 +17273,7 @@ M:	Josh Triplett <[email protected]>
 L:	[email protected]
 S:	Supported
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu.git dev
-F:	Documentation/RCU/torture.txt
+F:	Documentation/RCU/torture.rst
 F:	kernel/locking/locktorture.c
 F:	kernel/rcu/rcuperf.c
 F:	kernel/rcu/rcutorture.c
kernel/rcu/rcutorture.c +1 -1
index efb792e..8205295 100644
@@ -7,7 +7,7 @@
  * Authors: Paul E. McKenney <[email protected]>
  *	  Josh Triplett <[email protected]>
  *
- * See also:  Documentation/RCU/torture.txt
+ * See also:  Documentation/RCU/torture.rst
  */
 
 #define pr_fmt(fmt) fmt
Signature · 1 line
2.9.5
author maintainer
#6 lore raw

PATCH 6/10 docs: RCU: Convert rcuref.txt to ReST

In reply to Paul E. McKenney

From: Mauro Carvalho Chehab <[email protected]>

- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.

---
 Documentation/RCU/index.rst                  |   1 +
 Documentation/RCU/{rcuref.txt => rcuref.rst} | 199 ++++++++++++++-------------
 2 files changed, 104 insertions(+), 96 deletions(-)
 rename Documentation/RCU/{rcuref.txt => rcuref.rst} (50%)
Documentation/RCU/index.rst +1 -0
index 5d5f9a1..9a1d51f 100644
@@ -18,6 +18,7 @@ RCU concepts
    whatisRCU
    rcu
    rculist_nulls
+   rcuref
    torture
    listRCU
    NMI-RCU
Documentation/RCU/rcuref.rst renamed from Documentation/RCU/rcuref.txt +103 -96

233 lines not on this page · raw message

Signature · 1 line
2.9.5
author maintainer
#7 lore raw

PATCH 7/10 docs: RCU: Convert stallwarn.txt to ReST

In reply to Paul E. McKenney

From: Mauro Carvalho Chehab <[email protected]>

- Add a SPDX header;
- Adjust document and section titles;
- Fix list markups;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to RCU/index.rst.

---
 Documentation/RCU/index.rst                        |  1 +
 Documentation/RCU/{stallwarn.txt => stallwarn.rst} | 55 +++++++++++++---------
 kernel/rcu/tree_stall.h                            |  4 +-
 3 files changed, 37 insertions(+), 23 deletions(-)
 rename Documentation/RCU/{stallwarn.txt => stallwarn.rst} (90%)
Documentation/RCU/index.rst +1 -0
index 9a1d51f..e703d3d 100644
@@ -20,6 +20,7 @@ RCU concepts
    rculist_nulls
    rcuref
    torture
+   stallwarn
    listRCU
    NMI-RCU
    UP
Documentation/RCU/stallwarn.rst renamed from Documentation/RCU/stallwarn.txt +34 -21

193 lines not on this page · raw message

kernel/rcu/tree_stall.h +2 -2
index 54a6dba..b04256c 100644
@@ -468,7 +468,7 @@ static void print_other_cpu_stall(unsigned long gp_seq, unsigned long gps)
 
 	/*
 	 * OK, time to rat on our buddy...
-	 * See Documentation/RCU/stallwarn.txt for info on how to debug
+	 * See Documentation/RCU/stallwarn.rst for info on how to debug
 	 * RCU CPU stall warnings.
 	 */
 	pr_err("INFO: %s detected stalls on CPUs/tasks:\n", rcu_state.name);
@@ -535,7 +535,7 @@ static void print_cpu_stall(unsigned long gps)
 
 	/*
 	 * OK, time to rat on ourselves...
-	 * See Documentation/RCU/stallwarn.txt for info on how to debug
+	 * See Documentation/RCU/stallwarn.rst for info on how to debug
 	 * RCU CPU stall warnings.
 	 */
 	pr_err("INFO: %s self-detected stall on CPU\n", rcu_state.name);
Signature · 1 line
2.9.5
author maintainer
#8 lore raw

PATCH 8/10 docs: RCU: Don't duplicate chapter names in rculist_nulls.rst

In reply to Paul E. McKenney

From: Mauro Carvalho Chehab <[email protected]>

Since changeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst"), auto-references for chapters are generated. This is a nice feature, but has a drawback: no chapters can have the same sumber.

So, we need to add two higher hierarchy chapters on this document, in order to avoid such duplication.

Fixes 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")
---
 Documentation/RCU/rculist_nulls.rst | 6 ++++++
 1 file changed, 6 insertions(+)
Documentation/RCU/rculist_nulls.rst +6 -0
index d403742..a9fc774 100644
@@ -10,6 +10,9 @@ objects using SLAB_TYPESAFE_BY_RCU allocations.
 
 Please read the basics in Documentation/RCU/listRCU.rst
 
+Using 'nulls'
+=============
+
 Using special makers (called 'nulls') is a convenient way
 to solve following problem :
 
@@ -126,6 +129,9 @@ very very fast (before the end of RCU grace period)
 
 --------------------------------------------------------------------------
 
+Avoiding extra smp_rmb()
+========================
+
 With hlist_nulls we can avoid extra smp_rmb() in lockless_lookup()
 and extra smp_wmb() in insert function.
 
Signature · 1 line
2.9.5
author maintainer
#9 lore raw

PATCH 9/10 doc: Timer problems can cause RCU CPU stall warnings

In reply to Paul E. McKenney

From: "Paul E. McKenney" <[email protected]>

Over the past few years, there have been several cases where timekeeping bugs have caused RCU CPU stall warnings, particularly during hardware bringup. This commit therefore adds such bugs to the list of things that can result in RCU CPU stall warnings.

---
 Documentation/RCU/stallwarn.rst | 7 +++++++
 1 file changed, 7 insertions(+)
Documentation/RCU/stallwarn.rst +7 -0
index 08bc9ae..c9ab6af 100644
@@ -87,6 +87,13 @@ warnings:
 	problem really has happened, and seems to be most likely to
 	result in RCU CPU stall warnings for CONFIG_NO_HZ_COMMON=n kernels.
 
+-	A hardware or software issue that prevents time-based wakeups
+	from occurring.  These issues can range from misconfigured or
+	buggy timer hardware through bugs in the interrupt or exception
+	path (whether hardware, firmware, or software) through bugs
+	in Linux's timer subsystem through bugs in the scheduler, and,
+	yes, even including bugs in RCU itself.
+
 -	A bug in the RCU implementation.
 
 -	A hardware failure.  This is quite unlikely, but has occurred
Signature · 1 line
2.9.5
author maintainer
#10 lore raw

PATCH 10/10 doc: Tasks RCU must protect instructions before trampoline

In reply to Paul E. McKenney

From: "Paul E. McKenney" <[email protected]>

Protecting the code in a trampoline can also require protecting a number of instructions prior to actually entering the trampoline. For example, these earlier instructions might be computing the address of the trampoline. This commit therefore updates RCU's requirements to record this for posterity.

---
 Documentation/RCU/Design/Requirements/Requirements.rst | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)
Documentation/RCU/Design/Requirements/Requirements.rst +6 -1
index 75b8ca0..a69b5c4 100644
@@ -2583,7 +2583,12 @@ not work to have these markers in the trampoline itself, because there
 would need to be instructions following ``rcu_read_unlock()``. Although
 ``synchronize_rcu()`` would guarantee that execution reached the
 ``rcu_read_unlock()``, it would not be able to guarantee that execution
-had completely left the trampoline.
+had completely left the trampoline. Worse yet, in some situations
+the trampoline's protection must extend a few instructions *prior* to
+execution reaching the trampoline.  For example, these few instructions
+might calculate the address of the trampoline, so that entering the
+trampoline would be pre-ordained a surprisingly long time before execution
+actually reached the trampoline itself.
 
 The solution, in the form of `Tasks
 RCU <https://lwn.net/Articles/607117/>`__, is to have implicit read-side
Signature · 1 line
2.9.5