rcu: Further comment and explain the state space of GP sequences

The state space of the GP sequence number isn't documented and the
definitions of its special values are scattered.  This commit therefore
gathers some common knowledge near the grace-period sequence-number
definitions.

Signed-off-by: Frederic Weisbecker <frederic@kernel.org>
Reviewed-by: Joel Fernandes (Google) <joel@joelfernandes.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Joel Fernandes (Google) <joel@joelfernandes.org>

diff --git a/kernel/rcu/rcu.h b/kernel/rcu/rcu.h
index 115616ac3bfa6d1cb83bd0efdf823f64df3ab855..a3adcf9a9919b9fecc4af29599980bc1bb7f4eda 100644 (file)
--- a/kernel/rcu/rcu.h
+++ b/kernel/rcu/rcu.h
@@ -14,6 +14,43 @@
 
 /*
  * Grace-period counter management.
+ *
+ * The two least significant bits contain the control flags.
+ * The most significant bits contain the grace-period sequence counter.
+ *
+ * When both control flags are zero, no grace period is in progress.
+ * When either bit is non-zero, a grace period has started and is in
+ * progress. When the grace period completes, the control flags are reset
+ * to 0 and the grace-period sequence counter is incremented.
+ *
+ * However some specific RCU usages make use of custom values.
+ *
+ * SRCU special control values:
+ *
+ *     SRCU_SNP_INIT_SEQ       :       Invalid/init value set when SRCU node
+ *                                     is initialized.
+ *
+ *     SRCU_STATE_IDLE         :       No SRCU gp is in progress
+ *
+ *     SRCU_STATE_SCAN1        :       State set by rcu_seq_start(). Indicates
+ *                                     we are scanning the readers on the slot
+ *                                     defined as inactive (there might well
+ *                                     be pending readers that will use that
+ *                                     index, but their number is bounded).
+ *
+ *     SRCU_STATE_SCAN2        :       State set manually via rcu_seq_set_state()
+ *                                     Indicates we are flipping the readers
+ *                                     index and then scanning the readers on the
+ *                                     slot newly designated as inactive (again,
+ *                                     the number of pending readers that will use
+ *                                     this inactive index is bounded).
+ *
+ * RCU polled GP special control value:
+ *
+ *     RCU_GET_STATE_COMPLETED :       State value indicating an already-completed
+ *                                     polled GP has completed.  This value covers
+ *                                     both the state and the counter of the
+ *                                     grace-period sequence number.
  */
 
 #define RCU_SEQ_CTR_SHIFT      2