rcu: upgrade stallwarn.txt documentation for CPU-bound RT processes

CPU-bound real-time processes can cause RCU CPU stall warnings, and much other trouble as well. Document the fact that they can cause RCU CPU stall warnings. Suggested-by: Darren Hart <dvhltc@us.ibm.com> Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>

rcu: upgrade stallwarn.txt documentation for CPU-bound RT processes
CPU-bound real-time processes can cause RCU CPU stall warnings, and much other trouble as well. Document the fact that they can cause RCU CPU stall warnings. Suggested-by: Darren Hart <dvhltc@us.ibm.com> Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>
Paul E. McKenney
1 parent a6b9b4d50f
Showing 1 changed file with 18 additions and 0 deletions Side-by-side Diff
Documentation/RCU/stallwarn.txt
@@ -80,6 +80,24 @@
 o	For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel
 	without invoking schedule().
  
+o	A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might
+	happen to preempt a low-priority task in the middle of an RCU
+	read-side critical section.   This is especially damaging if
+	that low-priority task is not permitted to run on any other CPU,
+	in which case the next RCU grace period can never complete, which
+	will eventually cause the system to run out of memory and hang.
+	While the system is in the process of running itself out of
+	memory, you might see stall-warning messages.
+
+o	A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
+	is running at a higher priority than the RCU softirq threads.
+	This will prevent RCU callbacks from ever being invoked,
+	and in a CONFIG_TREE_PREEMPT_RCU kernel will further prevent
+	RCU grace periods from ever completing.  Either way, the
+	system will eventually run out of memory and hang.  In the
+	CONFIG_TREE_PREEMPT_RCU case, you might see stall-warning
+	messages.
+
 o	A bug in the RCU implementation.
  
 o	A hardware failure.  This is quite unlikely, but has occurred
...	...	@@ -80,6 +80,24 @@
80	80	o For !CONFIG_PREEMPT kernels, a CPU looping anywhere in the kernel
81	81	without invoking schedule().
82	82
	83	+o A CPU-bound real-time task in a CONFIG_PREEMPT kernel, which might
	84	+ happen to preempt a low-priority task in the middle of an RCU
	85	+ read-side critical section. This is especially damaging if
	86	+ that low-priority task is not permitted to run on any other CPU,
	87	+ in which case the next RCU grace period can never complete, which
	88	+ will eventually cause the system to run out of memory and hang.
	89	+ While the system is in the process of running itself out of
	90	+ memory, you might see stall-warning messages.
	91	+
	92	+o A CPU-bound real-time task in a CONFIG_PREEMPT_RT kernel that
	93	+ is running at a higher priority than the RCU softirq threads.
	94	+ This will prevent RCU callbacks from ever being invoked,
	95	+ and in a CONFIG_TREE_PREEMPT_RCU kernel will further prevent
	96	+ RCU grace periods from ever completing. Either way, the
	97	+ system will eventually run out of memory and hang. In the
	98	+ CONFIG_TREE_PREEMPT_RCU case, you might see stall-warning
	99	+ messages.
	100	+
83	101	o A bug in the RCU implementation.
84	102
85	103	o A hardware failure. This is quite unlikely, but has occurred