[PATCH tip/core/rcu 0/5] Documentation changes for 4.4

[PATCH tip/core/rcu 0/5] Documentation changes for 4.4

[Paul E. McKenney]

Hello!

This series contains a few documentation updates:

1.	Clearly state that RCU readers have no acquire/release semantics.

2.	Call out slow consoles as a cause of stall warnings.

3.	Update whatisRCU() to show rcu_dereference_protected(),
	courtesy of Jason A. Donenfeld.

4.	Catch up list of torture_type options.

5.	Add lockless_dereference() to memory-barriers.txt.

							Thanx, Paul

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

 b/Documentation/RCU/stallwarn.txt   |    7 ++++++
 b/Documentation/RCU/torture.txt     |   39 ++++++++++++------------------------
 b/Documentation/RCU/whatisRCU.txt   |    6 ++---
 b/Documentation/memory-barriers.txt |   12 ++++++++++-
 4 files changed, 34 insertions(+), 30 deletions(-)

[PATCH tip/core/rcu 1/5] documentation: No acquire/release for RCU readers

[Paul E. McKenney]

Documentation/memory-barriers.txt calls out RCU as one of the sets
of primitives associated with ACQUIRE and RELEASE.  There really
is an association in that rcu_assign_pointer() includes a RELEASE
operation, but a quick read can convince people that rcu_read_lock() and
rcu_read_unlock() have ACQUIRE and RELEASE semantics, which they do not.

This commit therefore removes RCU from this list in order to avoid
this confusion.

Reported-by: Boqun Feng <boqun.feng@gmail.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/memory-barriers.txt | 1 -
 1 file changed, 1 deletion(-)

diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index 2ba8461b0631..d336e4d42029 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -1789,7 +1789,6 @@ The Linux kernel has a number of locking constructs:
  (*) mutexes
  (*) semaphores
  (*) R/W semaphores
- (*) RCU
 
 In all cases there are variants on "ACQUIRE" operations and "RELEASE" operations
 for each construct.  These operations all imply certain barriers:
-- 
2.5.2

[PATCH tip/core/rcu 2/5] documentation: Call out slow consoles as cause of stall warnings

[Paul E. McKenney]

The Linux kernel outputs copious text during boot, and a slow serial
console can result in stall warnings, particularly when messages are
printed with interrupts disabled.  This commit adds this to the list
of causes of RCU CPU stall warning messages.

Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/RCU/stallwarn.txt | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt
index efb9454875ab..0f7fb4298e7e 100644
--- a/Documentation/RCU/stallwarn.txt
+++ b/Documentation/RCU/stallwarn.txt
@@ -205,6 +205,13 @@ o	For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the
 	behavior, you might need to replace some of the cond_resched()
 	calls with calls to cond_resched_rcu_qs().
 
+o	Booting Linux using a console connection that is too slow to
+	keep up with the boot-time console-message rate.  For example,
+	a 115Kbaud serial console can be -way- too slow to keep up
+	with boot-time message rates, and will frequently result in
+	RCU CPU stall warning messages.  Especially if you have added
+	debug printk()s.
+
 o	Anything that prevents RCU's grace-period kthreads from running.
 	This can result in the "All QSes seen" console-log message.
 	This message will include information on when the kthread last
-- 
2.5.2

[PATCH tip/core/rcu 3/5] documentation: Correct doc to use rcu_dereference_protected

[Paul E. McKenney]

From: "Jason A. Donenfeld" <Jason@zx2c4.com>

As there is lots of misinformation and outdated information on the
Internet about nearly all topics related to the kernel, I thought it
would be best if I based my RCU code on the guidelines of the examples
in the Documentation/ tree of the latest kernel. One thing that stuck
out when reading the whatisRCU.txt document was, "interesting how we
don't need any function to dereference rcu protected pointers when doing
updates if a lock is held. I wonder how static analyzers will work with
that." Then, a few weeks later, upon discovering sparse's __rcu support,
I ran it over my code, and lo and behold, things weren't done right.
Examining other RCU usages in the kernel reveal consistent usage of
rcu_dereference_protected, passing in lockdep_is_held as the
conditional. So, this patch adds that idiom to the documentation, so
that others ahead of me won't endure the same exercise.

Signed-off-by: Jason A. Donenfeld <Jason@zx2c4.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/RCU/whatisRCU.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt
index adc2184009c5..dc49c6712b17 100644
--- a/Documentation/RCU/whatisRCU.txt
+++ b/Documentation/RCU/whatisRCU.txt
@@ -364,7 +364,7 @@ uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
 	};
 	DEFINE_SPINLOCK(foo_mutex);
 
-	struct foo *gbl_foo;
+	struct foo __rcu *gbl_foo;
 
 	/*
 	 * Create a new struct foo that is the same as the one currently
@@ -386,7 +386,7 @@ uses of RCU may be found in listRCU.txt, arrayRCU.txt, and NMI-RCU.txt.
 
 		new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
 		spin_lock(&foo_mutex);
-		old_fp = gbl_foo;
+		old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
 		*new_fp = *old_fp;
 		new_fp->a = new_a;
 		rcu_assign_pointer(gbl_foo, new_fp);
@@ -487,7 +487,7 @@ The foo_update_a() function might then be written as follows:
 
 		new_fp = kmalloc(sizeof(*new_fp), GFP_KERNEL);
 		spin_lock(&foo_mutex);
-		old_fp = gbl_foo;
+		old_fp = rcu_dereference_protected(gbl_foo, lockdep_is_held(&foo_mutex));
 		*new_fp = *old_fp;
 		new_fp->a = new_a;
 		rcu_assign_pointer(gbl_foo, new_fp);
-- 
2.5.2

[PATCH tip/core/rcu 4/5] documentation: Catch up list of torture_type options

[Paul E. McKenney]

This commit rids the documentation of long-obsolete torture_type options
such as rcu_sync and adds new ones such as tasks.  Also add verbiage
noting the fact that rcutorture now concurrently tests the asynchrounous,
synchronous, expedited synchronous, and polling grace-period primitives.

Reported-by: David Miller <davem@davemloft.net>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Acked-by: David Miller <davem@davemloft.net>
---
 Documentation/RCU/torture.txt | 39 +++++++++++++--------------------------
 1 file changed, 13 insertions(+), 26 deletions(-)

diff --git a/Documentation/RCU/torture.txt b/Documentation/RCU/torture.txt
index dac02a6219b1..118e7c176ce7 100644
--- a/Documentation/RCU/torture.txt
+++ b/Documentation/RCU/torture.txt
@@ -166,40 +166,27 @@ test_no_idle_hz	Whether or not to test the ability of RCU to operate in
 
 torture_type	The type of RCU to test, with string values as follows:
 
-		"rcu":  rcu_read_lock(), rcu_read_unlock() and call_rcu().
-
-		"rcu_sync":  rcu_read_lock(), rcu_read_unlock(), and
-			synchronize_rcu().
-
-		"rcu_expedited": rcu_read_lock(), rcu_read_unlock(), and
-			synchronize_rcu_expedited().
+		"rcu":  rcu_read_lock(), rcu_read_unlock() and call_rcu(),
+			along with expedited, synchronous, and polling
+			variants.
 
 		"rcu_bh": rcu_read_lock_bh(), rcu_read_unlock_bh(), and
-			call_rcu_bh().
-
-		"rcu_bh_sync": rcu_read_lock_bh(), rcu_read_unlock_bh(),
-			and synchronize_rcu_bh().
+			call_rcu_bh(), along with expedited and synchronous
+			variants.
 
-		"rcu_bh_expedited": rcu_read_lock_bh(), rcu_read_unlock_bh(),
-			and synchronize_rcu_bh_expedited().
+		"rcu_busted": This tests an intentionally incorrect version
+			of RCU in order to help test rcutorture itself.
 
 		"srcu": srcu_read_lock(), srcu_read_unlock() and
-			call_srcu().
-
-		"srcu_sync": srcu_read_lock(), srcu_read_unlock() and
-			synchronize_srcu().
-
-		"srcu_expedited": srcu_read_lock(), srcu_read_unlock() and
-			synchronize_srcu_expedited().
+			call_srcu(), along with expedited and
+			synchronous variants.
 
 		"sched": preempt_disable(), preempt_enable(), and
-			call_rcu_sched().
-
-		"sched_sync": preempt_disable(), preempt_enable(), and
-			synchronize_sched().
+			call_rcu_sched(), along with expedited,
+			synchronous, and polling variants.
 
-		"sched_expedited": preempt_disable(), preempt_enable(), and
-			synchronize_sched_expedited().
+		"tasks": voluntary context switch and call_rcu_tasks(),
+			along with expedited and synchronous variants.
 
 		Defaults to "rcu".
 
-- 
2.5.2

[PATCH tip/core/rcu 5/5] documentation: Add lockless_dereference()

[Paul E. McKenney]

The recently added lockless_dereference() macro is not present in the
Documentation/ directory, so this commit fixes that.

Reported-by: Dmitry Vyukov <dvyukov@google.com>
Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
---
 Documentation/memory-barriers.txt | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/Documentation/memory-barriers.txt b/Documentation/memory-barriers.txt
index d336e4d42029..8e7cf9ad3db1 100644
--- a/Documentation/memory-barriers.txt
+++ b/Documentation/memory-barriers.txt
@@ -1710,6 +1710,17 @@ There are some more advanced barrier functions:
      operations" subsection for information on where to use these.
 
 
+ (*) lockless_dereference();
+     This can be thought of as a pointer-fetch wrapper around the
+     smp_read_barrier_depends() data-dependency barrier.
+
+     This is also similar to rcu_dereference(), but in cases where
+     object lifetime is handled by some mechanism other than RCU, for
+     example, when the objects removed only when the system goes down.
+     In addition, lockless_dereference() is used in some data structures
+     that can be used both with and without RCU.
+
+
  (*) dma_wmb();
  (*) dma_rmb();
 
-- 
2.5.2

Re: [PATCH tip/core/rcu 0/5] Documentation changes for 4.4

[Josh Triplett]

On Tue, Oct 06, 2015 at 09:33:58AM -0700, Paul E. McKenney wrote:
> Hello!
> 
> This series contains a few documentation updates:
> 
> 1.	Clearly state that RCU readers have no acquire/release semantics.
> 
> 2.	Call out slow consoles as a cause of stall warnings.
> 
> 3.	Update whatisRCU() to show rcu_dereference_protected(),
> 	courtesy of Jason A. Donenfeld.
> 
> 4.	Catch up list of torture_type options.
> 
> 5.	Add lockless_dereference() to memory-barriers.txt.

For all five:

Reviewed-by: Josh Triplett <josh@joshtriplett.org>