Skip to contentSkip to conversation

srcu: Add comments for srcu_size_state

PATCH Applied Pingfan Liu 2 participants 3 messages Dec 23, 2022 – Jan 6, 2023

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 srcu: Add comments for srcu_size_state

Cc Lai Jiangshan <[email protected]>
Cc "Paul E. McKenney" <[email protected]>
Cc Frederic Weisbecker <[email protected]>,
Cc Josh Triplett <[email protected]>
Cc Steven Rostedt <[email protected]>
Cc Mathieu Desnoyers <[email protected]>
Cc "Zhang, Qiang1" <[email protected]>

To: [email protected]

---
 include/linux/srcutree.h | 8 ++++++++
 1 file changed, 8 insertions(+)
include/linux/srcutree.h +8 -0
index d4b7f3daf2f8..ee4f3ffa1cce 100644
@@ -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
Signature · 1 line
2.31.1
maintainer Applied
#1 lore raw
Quoted 9 lines · Pingfan Liu
Cc Lai Jiangshan <[email protected]>
Cc "Paul E. McKenney" <[email protected]>
Cc Frederic Weisbecker <[email protected]>,
Cc Josh Triplett <[email protected]>
Cc Steven Rostedt <[email protected]>
Cc Mathieu Desnoyers <[email protected]>
Cc "Zhang, Qiang1" <[email protected]>

To: [email protected]

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 <[email protected]>
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.

Cc Lai Jiangshan <[email protected]>
Cc "Paul E. McKenney" <[email protected]>
Cc Frederic Weisbecker <[email protected]>,
Cc Josh Triplett <[email protected]>
Cc Steven Rostedt <[email protected]>
Cc Mathieu Desnoyers <[email protected]>
Cc "Zhang, Qiang1" <[email protected]>

To: [email protected]

include/linux/srcutree.h +23 -10
index 558057b517b74..a6910805f9c51 100644
@@ -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
#2 lore raw
Quoted 12 lines · Paul E. McKenney
Quoted 9 lines · Pingfan Liu
Cc Lai Jiangshan <[email protected]>
Cc "Paul E. McKenney" <[email protected]>
Cc Frederic Weisbecker <[email protected]>,
Cc Josh Triplett <[email protected]>
Cc Steven Rostedt <[email protected]>
Cc Mathieu Desnoyers <[email protected]>
Cc "Zhang, Qiang1" <[email protected]>

To: [email protected]

Quoted 3 lines

Queued, thank you!

After the inevitable wordsmithing, it appears as follows. Could you

Sorry for the poor English expression.

Quoted 2 lines

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

It looks better to me.

Thanks,

Pingfan

Quoted 68 lines

Thanx, Paul

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

commit 9c473f0ef9eb8f3ac76d8295cfb4065a738b07a1

Author: Pingfan Liu <[email protected]>
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.

Cc Lai Jiangshan <[email protected]>
Cc "Paul E. McKenney" <[email protected]>
Cc Frederic Weisbecker <[email protected]>,
Cc Josh Triplett <[email protected]>
Cc Steven Rostedt <[email protected]>
Cc Mathieu Desnoyers <[email protected]>
Cc "Zhang, Qiang1" <[email protected]>

To: [email protected]

include/linux/srcutree.h +23 -10
index 558057b517b74..a6910805f9c51 100644
@@ -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