[PATCH] srcu: Add comments for srcu_size_state

[PATCH] srcu: Add comments for srcu_size_state

[Pingfan Liu]

Signed-off-by: Pingfan Liu <kernelfans@gmail.com>
Cc: Lai Jiangshan <jiangshanlai@gmail.com>
Cc: "Paul E. McKenney" <paulmck@kernel.org>
Cc: Frederic Weisbecker <frederic@kernel.org>,
Cc: Josh Triplett <josh@joshtriplett.org>
Cc: Steven Rostedt <rostedt@goodmis.org>
Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Cc: "Zhang, Qiang1" <qiang1.zhang@intel.com>
To: rcu@vger.kernel.org
---
 include/linux/srcutree.h | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/include/linux/srcutree.h b/include/linux/srcutree.h
index d4b7f3daf2f8..ee4f3ffa1cce 100644
--- a/include/linux/srcutree.h
+++ b/include/linux/srcutree.h
@@ -94,8 +94,16 @@ struct srcu_struct {
 /* Values for size state variable (->srcu_size_state). */
 #define SRCU_SIZE_SMALL		0
 #define SRCU_SIZE_ALLOC		1
+/* snp tree has been initialized */
 #define SRCU_SIZE_WAIT_BARRIER	2
+/* In this state, any srcu_barrier(), which considers the system not using snp
+ * tree, has finished.
+ */
 #define SRCU_SIZE_WAIT_CALL	3
+/*
+ * Before snp tree is used, there can be two GPs , each takes two seq snap values.
+ * Wait until CBS1 - CBS4 elapse so these callbacks finishes.
+ */
 #define SRCU_SIZE_WAIT_CBS1	4
 #define SRCU_SIZE_WAIT_CBS2	5
 #define SRCU_SIZE_WAIT_CBS3	6
-- 
2.31.1

Re: [PATCH] srcu: Add comments for srcu_size_state

[Paul E. McKenney]

On Fri, Dec 23, 2022 at 09:02:28PM +0800, Pingfan Liu wrote:
> Signed-off-by: Pingfan Liu <kernelfans@gmail.com>
> Cc: Lai Jiangshan <jiangshanlai@gmail.com>
> Cc: "Paul E. McKenney" <paulmck@kernel.org>
> Cc: Frederic Weisbecker <frederic@kernel.org>,
> Cc: Josh Triplett <josh@joshtriplett.org>
> Cc: Steven Rostedt <rostedt@goodmis.org>
> Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
> Cc: "Zhang, Qiang1" <qiang1.zhang@intel.com>
> To: rcu@vger.kernel.org

Queued, thank you!

After the inevitable wordsmithing, it appears as follows.  Could you
please check it?  (And yes, it does take advantage of 100 columns.)

							Thanx, Paul

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

commit 9c473f0ef9eb8f3ac76d8295cfb4065a738b07a1
Author: Pingfan Liu <kernelfans@gmail.com>
Date:   Wed Jan 4 12:29:01 2023 -0800

    srcu: Add comments for srcu_size_state
    
    The SRCU_SIZE_* names are not self-explanatory, so this commit therefore
    adds comments to the definitions.
    
    Signed-off-by: Pingfan Liu <kernelfans@gmail.com>
    Cc: Lai Jiangshan <jiangshanlai@gmail.com>
    Cc: "Paul E. McKenney" <paulmck@kernel.org>
    Cc: Frederic Weisbecker <frederic@kernel.org>,
    Cc: Josh Triplett <josh@joshtriplett.org>
    Cc: Steven Rostedt <rostedt@goodmis.org>
    Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
    Cc: "Zhang, Qiang1" <qiang1.zhang@intel.com>
    To: rcu@vger.kernel.org
    Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

diff --git a/include/linux/srcutree.h b/include/linux/srcutree.h
index 558057b517b74..a6910805f9c51 100644
--- a/include/linux/srcutree.h
+++ b/include/linux/srcutree.h
@@ -92,16 +92,29 @@ struct srcu_struct {
 	struct lockdep_map dep_map;
 };
 
-/* Values for size state variable (->srcu_size_state). */
-#define SRCU_SIZE_SMALL		0
-#define SRCU_SIZE_ALLOC		1
-#define SRCU_SIZE_WAIT_BARRIER	2
-#define SRCU_SIZE_WAIT_CALL	3
-#define SRCU_SIZE_WAIT_CBS1	4
-#define SRCU_SIZE_WAIT_CBS2	5
-#define SRCU_SIZE_WAIT_CBS3	6
-#define SRCU_SIZE_WAIT_CBS4	7
-#define SRCU_SIZE_BIG		8
+// Values for size state variable (->srcu_size_state).  Once the state
+// has been set to SRCU_SIZE_ALLOC, the grace-period code advances through
+// this state machine one step per grace period until the SRCU_SIZE_BIG state
+// is reached.  Otherwise, the state machine remains in the SRCU_SIZE_SMALL
+// state indefinitely.
+#define SRCU_SIZE_SMALL		0	// No srcu_node combining tree, ->node == NULL
+#define SRCU_SIZE_ALLOC		1	// An srcu_node tree is being allocated, initialized,
+					//  and then referenced by ->node.  It will not be used.
+#define SRCU_SIZE_WAIT_BARRIER	2	// The srcu_node tree starts being used by everything
+					//  except call_srcu(), especially by srcu_barrier().
+					//  By the end of this state, all CPUs and threads
+					//  are aware of this tree's existence.
+#define SRCU_SIZE_WAIT_CALL	3	// The srcu_node tree starts being used by call_srcu().
+					//  By the end of this state, all of the call_srcu()
+					//  invocations that were running on a non-boot CPU
+					//  and using the boot CPU's callback queue will have
+					//  completed.
+#define SRCU_SIZE_WAIT_CBS1	4	// Don't trust the ->srcu_have_cbs[] grace-period
+#define SRCU_SIZE_WAIT_CBS2	5	//  sequence elements or the ->srcu_data_have_cbs[]
+#define SRCU_SIZE_WAIT_CBS3	6	//  CPU-bitmask elements until all four elements of
+#define SRCU_SIZE_WAIT_CBS4	7	//  each array have been initialized.
+#define SRCU_SIZE_BIG		8	// The srcu_node combining tree is fully initialized
+					//  and all aspects of it are being put to use.
 
 /* Values for state variable (bottom bits of ->srcu_gp_seq). */
 #define SRCU_STATE_IDLE		0

Re: [PATCH] srcu: Add comments for srcu_size_state

[Pingfan Liu]

On Thu, Jan 5, 2023 at 4:43 AM Paul E. McKenney <paulmck@kernel.org> wrote:
>
> On Fri, Dec 23, 2022 at 09:02:28PM +0800, Pingfan Liu wrote:
> > Signed-off-by: Pingfan Liu <kernelfans@gmail.com>
> > Cc: Lai Jiangshan <jiangshanlai@gmail.com>
> > Cc: "Paul E. McKenney" <paulmck@kernel.org>
> > Cc: Frederic Weisbecker <frederic@kernel.org>,
> > Cc: Josh Triplett <josh@joshtriplett.org>
> > Cc: Steven Rostedt <rostedt@goodmis.org>
> > Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
> > Cc: "Zhang, Qiang1" <qiang1.zhang@intel.com>
> > To: rcu@vger.kernel.org
>
> Queued, thank you!
>
> After the inevitable wordsmithing, it appears as follows.  Could you

Sorry for the poor English expression.

> please check it?  (And yes, it does take advantage of 100 columns.)
>

It looks better to me.

Thanks,

    Pingfan


>                                                         Thanx, Paul
>
> ------------------------------------------------------------------------
>
> commit 9c473f0ef9eb8f3ac76d8295cfb4065a738b07a1
> Author: Pingfan Liu <kernelfans@gmail.com>
> Date:   Wed Jan 4 12:29:01 2023 -0800
>
>     srcu: Add comments for srcu_size_state
>
>     The SRCU_SIZE_* names are not self-explanatory, so this commit therefore
>     adds comments to the definitions.
>
>     Signed-off-by: Pingfan Liu <kernelfans@gmail.com>
>     Cc: Lai Jiangshan <jiangshanlai@gmail.com>
>     Cc: "Paul E. McKenney" <paulmck@kernel.org>
>     Cc: Frederic Weisbecker <frederic@kernel.org>,
>     Cc: Josh Triplett <josh@joshtriplett.org>
>     Cc: Steven Rostedt <rostedt@goodmis.org>
>     Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
>     Cc: "Zhang, Qiang1" <qiang1.zhang@intel.com>
>     To: rcu@vger.kernel.org
>     Signed-off-by: Paul E. McKenney <paulmck@kernel.org>
>
> diff --git a/include/linux/srcutree.h b/include/linux/srcutree.h
> index 558057b517b74..a6910805f9c51 100644
> --- a/include/linux/srcutree.h
> +++ b/include/linux/srcutree.h
> @@ -92,16 +92,29 @@ struct srcu_struct {
>         struct lockdep_map dep_map;
>  };
>
> -/* Values for size state variable (->srcu_size_state). */
> -#define SRCU_SIZE_SMALL                0
> -#define SRCU_SIZE_ALLOC                1
> -#define SRCU_SIZE_WAIT_BARRIER 2
> -#define SRCU_SIZE_WAIT_CALL    3
> -#define SRCU_SIZE_WAIT_CBS1    4
> -#define SRCU_SIZE_WAIT_CBS2    5
> -#define SRCU_SIZE_WAIT_CBS3    6
> -#define SRCU_SIZE_WAIT_CBS4    7
> -#define SRCU_SIZE_BIG          8
> +// Values for size state variable (->srcu_size_state).  Once the state
> +// has been set to SRCU_SIZE_ALLOC, the grace-period code advances through
> +// this state machine one step per grace period until the SRCU_SIZE_BIG state
> +// is reached.  Otherwise, the state machine remains in the SRCU_SIZE_SMALL
> +// state indefinitely.
> +#define SRCU_SIZE_SMALL                0       // No srcu_node combining tree, ->node == NULL
> +#define SRCU_SIZE_ALLOC                1       // An srcu_node tree is being allocated, initialized,
> +                                       //  and then referenced by ->node.  It will not be used.
> +#define SRCU_SIZE_WAIT_BARRIER 2       // The srcu_node tree starts being used by everything
> +                                       //  except call_srcu(), especially by srcu_barrier().
> +                                       //  By the end of this state, all CPUs and threads
> +                                       //  are aware of this tree's existence.
> +#define SRCU_SIZE_WAIT_CALL    3       // The srcu_node tree starts being used by call_srcu().
> +                                       //  By the end of this state, all of the call_srcu()
> +                                       //  invocations that were running on a non-boot CPU
> +                                       //  and using the boot CPU's callback queue will have
> +                                       //  completed.
> +#define SRCU_SIZE_WAIT_CBS1    4       // Don't trust the ->srcu_have_cbs[] grace-period
> +#define SRCU_SIZE_WAIT_CBS2    5       //  sequence elements or the ->srcu_data_have_cbs[]
> +#define SRCU_SIZE_WAIT_CBS3    6       //  CPU-bitmask elements until all four elements of
> +#define SRCU_SIZE_WAIT_CBS4    7       //  each array have been initialized.
> +#define SRCU_SIZE_BIG          8       // The srcu_node combining tree is fully initialized
> +                                       //  and all aspects of it are being put to use.
>
>  /* Values for state variable (bottom bits of ->srcu_gp_seq). */
>  #define SRCU_STATE_IDLE                0