rcu: Call out dangers of expedited RCU primitives

The expedited RCU primitives can be quite useful, but they have some
high costs as well.  This commit updates and creates docbook comments
calling out the costs, and updates the RCU documentation as well.

Signed-off-by: Paul E. McKenney <paulmck@linux.vnet.ibm.com>

1 files changed, 14 insertions, 0 deletions

diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index bff2d8be1e1..5c8d7496809 100644
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.txt
@@ -180,6 +180,20 @@ over a rather long period of time, but improvements are always welcome!
         operations that would not normally be undertaken while a real-time
         workload is running.
 
+        In particular, if you find yourself invoking one of the expedited
+        primitives repeatedly in a loop, please do everyone a favor:
+        Restructure your code so that it batches the updates, allowing
+        a single non-expedited primitive to cover the entire batch.
+        This will very likely be faster than the loop containing the
+        expedited primitive, and will be much much easier on the rest
+        of the system, especially to real-time workloads running on
+        the rest of the system.
+
+        In addition, it is illegal to call the expedited forms from
+        a CPU-hotplug notifier, or while holding a lock that is acquired
+        by a CPU-hotplug notifier.  Failing to observe this restriction
+        will result in deadlock.
+
 7.      If the updater uses call_rcu() or synchronize_rcu(), then the
         corresponding readers must use rcu_read_lock() and
         rcu_read_unlock().  If the updater uses call_rcu_bh() or