<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head><title>A Tour Through TREE_RCU's Data Structures [LWN.net]</title> <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> <p>December 18, 2016</p> <p>This article was contributed by Paul E. McKenney</p> <h3>Introduction</h3> This document describes RCU's major data structures and their relationshipto each other. <ol><li> <a href="#Data-Structure Relationships"> Data-Structure Relationships</a><li> <a href="#The rcu_state Structure"> The <tt>rcu_state</tt> Structure</a><li> <a href="#The rcu_node Structure"> The <tt>rcu_node</tt> Structure</a><li> <a href="#The rcu_segcblist Structure"> The <tt>rcu_segcblist</tt> Structure</a><li> <a href="#The rcu_data Structure"> The <tt>rcu_data</tt> Structure</a><li> <a href="#The rcu_head Structure"> The <tt>rcu_head</tt> Structure</a><li> <a href="#RCU-Specific Fields in the task_struct Structure"> RCU-Specific Fields in the <tt>task_struct</tt> Structure</a><li> <a href="#Accessor Functions"> Accessor Functions</a></ol> <h3><a name="Data-Structure Relationships">Data-Structure Relationships</a></h3> <p>RCU is for all intents and purposes a large state machine, and itsdata structures maintain the state in such a way as to allow RCU readersto execute extremely quickly, while also processing the RCU grace periodsrequested by updaters in an efficient and extremely scalable fashion.The efficiency and scalability of RCU updaters is provided primarilyby a combining tree, as shown below: </p><p><img src="BigTreeClassicRCU.svg" alt="BigTreeClassicRCU.svg" width="30%"> </p><p>This diagram shows an enclosing <tt>rcu_state</tt> structurecontaining a tree of <tt>rcu_node</tt> structures.Each leaf node of the <tt>rcu_node</tt> tree has up to 16<tt>rcu_data</tt> structures associated with it, so that thereare <tt>NR_CPUS</tt> number of <tt>rcu_data</tt> structures,one for each possible CPU.This structure is adjusted at boot time, if needed, to handle thecommon case where <tt>nr_cpu_ids</tt> is much less than<tt>NR_CPUs</tt>.For example, a number of Linux distributions set <tt>NR_CPUs=4096</tt>,which results in a three-level <tt>rcu_node</tt> tree.If the actual hardware has only 16 CPUs, RCU will adjust itselfat boot time, resulting in an <tt>rcu_node</tt> tree with only a single node. </p><p>The purpose of this combining tree is to allow per-CPU eventssuch as quiescent states, dyntick-idle transitions,and CPU hotplug operations to be processed efficientlyand scalably.Quiescent states are recorded by the per-CPU <tt>rcu_data</tt> structures,and other events are recorded by the leaf-level <tt>rcu_node</tt>structures.All of these events are combined at each level of the tree until finallygrace periods are completed at the tree's root <tt>rcu_node</tt>structure.A grace period can be completed at the root once every CPU(or, in the case of <tt>CONFIG_PREEMPT_RCU</tt>, task)has passed through a quiescent state.Once a grace period has completed, record of that fact is propagatedback down the tree. </p><p>As can be seen from the diagram, on a 64-bit systema two-level tree with 64 leaves can accommodate 1,024 CPUs, with a fanoutof 64 at the root and a fanout of 16 at the leaves. <table><tr><th> </th></tr><tr><th align="left">Quick Quiz:</th></tr><tr><td> Why isn't the fanout at the leaves also 64?</td></tr><tr><th align="left">Answer:</th></tr><tr><td bgcolor="#ffffff"><font color="ffffff"> Because there are more types of events that affect the leaf-level <tt>rcu_node</tt> structures than further up the tree. Therefore, if the leaf <tt>rcu_node</tt> structures have fanout of 64, the contention on these structures' <tt>->structures</tt> becomes excessive. Experimentation on a wide variety of systems has shown that a fanout of 16 works well for the leaves of the <tt>rcu_node</tt> tree. </font> <p><font color="ffffff">Of course, further experience with systems having hundreds or thousands of CPUs may demonstrate that the fanout for the non-leaf <tt>rcu_node</tt> structures must also be reduced. Such reduction can be easily carried out when and if it proves necessary. In the meantime, if you are using such a system and running into contention problems on the non-leaf <tt>rcu_node</tt> structures, you may use the <tt>CONFIG_RCU_FANOUT</tt> kernel configuration parameter to reduce the non-leaf fanout as needed. </font> <p><font color="ffffff">Kernels built for systems with strong NUMA characteristics might also need to adjust <tt>CONFIG_RCU_FANOUT</tt> so that the domains of the <tt>rcu_node</tt> structures align with hardware boundaries. However, there has thus far been no need for this.</font></td></tr><tr><td> </td></tr></table> <p>If your system has more than 1,024 CPUs (or more than 512 CPUs ona 32-bit system), then RCU will automatically add more levels to thetree.For example, if you are crazy enough to build a 64-bit system with 65,536CPUs, RCU would configure the <tt>rcu_node</tt> tree as follows: </p><p><img src="HugeTreeClassicRCU.svg" alt="HugeTreeClassicRCU.svg" width="50%"> </p><p>RCU currently permits up to a four-level tree, which on a 64-bit systemaccommodates up to 4,194,304 CPUs, though only a mere 524,288 CPUs for32-bit systems.On the other hand, you can set both <tt>CONFIG_RCU_FANOUT</tt> and<tt>CONFIG_RCU_FANOUT_LEAF</tt> to be as small as 2, which would resultin a 16-CPU test using a 4-level tree.This can be useful for testing large-system capabilities on small testmachines. </p><p>This multi-level combining tree allows us to get most of theperformance and scalabilitybenefits of partitioning, even though RCU grace-period detection isinherently a global operation.The trick here is that only the last CPU to report a quiescent stateinto a given <tt>rcu_node</tt> structure need advance to the <tt>rcu_node</tt>structure at the next level up the tree.This means that at the leaf-level <tt>rcu_node</tt> structure, onlyone access out of sixteen will progress up the tree.For the internal <tt>rcu_node</tt> structures, the situation is evenmore extreme: Only one access out of sixty-four will progress upthe tree.Because the vast majority of the CPUs do not progress up the tree,the lock contention remains roughly constant up the tree.No matter how many CPUs there are in the system, at most 64 quiescent-statereports per grace period will progress all the way to the root<tt>rcu_node</tt> structure, thus ensuring that the lock contentionon that root <tt>rcu_node</tt> structure remains acceptably low. </p><p>In effect, the combining tree acts like a big shock absorber,keeping lock contention under control at all tree levels regardlessof the level of loading on the system. </p><p>RCU updaters wait for normal grace periods by registeringRCU callbacks, either directly via <tt>call_rcu()</tt>or indirectly via <tt>synchronize_rcu()</tt> and friends.RCU callbacks are represented by <tt>rcu_head</tt> structures,which are queued on <tt>rcu_data</tt> structures while they arewaiting for a grace period to elapse, as shown in the following figure: </p><p><img src="BigTreePreemptRCUBHdyntickCB.svg" alt="BigTreePreemptRCUBHdyntickCB.svg" width="40%"> </p><p>This figure shows how <tt>TREE_RCU</tt>'s and<tt>PREEMPT_RCU</tt>'s major data structures are related.Lesser data structures will be introduced with the algorithms thatmake use of them. </p><p>Note that each of the data structures in the above figure hasits own synchronization: <p><ol><li> Each <tt>rcu_state</tt> structures has a lock and a mutex, and some fields are protected by the corresponding root <tt>rcu_node</tt> structure's lock.<li> Each <tt>rcu_node</tt> structure has a spinlock.<li> The fields in <tt>rcu_data</tt> are private to the corresponding CPU, although a few can be read and written by other CPUs.</ol> <p>It is important to note that different data structures can havevery different ideas about the state of RCU at any given time.For but one example, awareness of the start or end of a given RCUgrace period propagates slowly through the data structures.This slow propagation is absolutely necessary for RCU to have goodread-side performance.If this balkanized implementation seems foreign to you, one usefultrick is to consider each instance of these data structures to bea different person, each having the usual slightly differentview of reality. </p><p>The general role of each of these data structures is asfollows: </p><ol><li> <tt>rcu_state</tt>: This structure forms the interconnection between the <tt>rcu_node</tt> and <tt>rcu_data</tt> structures, tracks grace periods, serves as short-term repository for callbacks orphaned by CPU-hotplug events, maintains <tt>rcu_barrier()</tt> state, tracks expedited grace-period state, and maintains state used to force quiescent states when grace periods extend too long,<li> <tt>rcu_node</tt>: This structure forms the combining tree that propagates quiescent-state information from the leaves to the root, and also propagates grace-period information from the root to the leaves. It provides local copies of the grace-period state in order to allow this information to be accessed in a synchronized manner without suffering the scalability limitations that would otherwise be imposed by global locking. In <tt>CONFIG_PREEMPT_RCU</tt> kernels, it manages the lists of tasks that have blocked while in their current RCU read-side critical section. In <tt>CONFIG_PREEMPT_RCU</tt> with <tt>CONFIG_RCU_BOOST</tt>, it manages the per-<tt>rcu_node</tt> priority-boosting kernel threads (kthreads) and state. Finally, it records CPU-hotplug state in order to determine which CPUs should be ignored during a given grace period.<li> <tt>rcu_data</tt>: This per-CPU structure is the focus of quiescent-state detection and RCU callback queuing. It also tracks its relationship to the corresponding leaf <tt>rcu_node</tt> structure to allow more-efficient propagation of quiescent states up the <tt>rcu_node</tt> combining tree. Like the <tt>rcu_node</tt> structure, it provides a local copy of the grace-period information to allow for-free synchronized access to this information from the corresponding CPU. Finally, this structure records past dyntick-idle state for the corresponding CPU and also tracks statistics.<li> <tt>rcu_head</tt>: This structure represents RCU callbacks, and is the only structure allocated and managed by RCU users. The <tt>rcu_head</tt> structure is normally embedded within the RCU-protected data structure.</ol> <p>If all you wanted from this article was a general notion of howRCU's data structures are related, you are done.Otherwise, each of the following sections give more details onthe <tt>rcu_state</tt>, <tt>rcu_node</tt> and <tt>rcu_data</tt> datastructures. <h3><a name="The rcu_state Structure">The <tt>rcu_state</tt> Structure</a></h3> <p>The <tt>rcu_state</tt> structure is the base structure thatrepresents the state of RCU in the system.This structure forms the interconnection between the<tt>rcu_node</tt> and <tt>rcu_data</tt> structures,tracks grace periods, contains the lock used tosynchronize with CPU-hotplug events,and maintains state used to force quiescent states whengrace periods extend too long, </p><p>A few of the <tt>rcu_state</tt> structure's fields are discussed,singly and in groups, in the following sections.The more specialized fields are covered in the discussion of theiruse. <h5>Relationship to rcu_node and rcu_data Structures</h5> This portion of the <tt>rcu_state</tt> structure is declaredas follows: <pre> 1 struct rcu_node node[NUM_RCU_NODES]; 2 struct rcu_node *level[NUM_RCU_LVLS + 1]; 3 struct rcu_data __percpu *rda;</pre> <table><tr><th> </th></tr><tr><th align="left">Quick Quiz:</th></tr><tr><td> Wait a minute! You said that the <tt>rcu_node</tt> structures formed a tree, but they are declared as a flat array! What gives?</td></tr><tr><th align="left">Answer:</th></tr><tr><td bgcolor="#ffffff"><font color="ffffff"> The tree is laid out in the array. The first node In the array is the head, the next set of nodes in the array are children of the head node, and so on until the last set of nodes in the array are the leaves. </font> <p><font color="ffffff">See the following diagrams to see how this works.</font></td></tr><tr><td> </td></tr></table> <p>The <tt>rcu_node</tt> tree is embedded into the<tt>->node[]</tt> array as shown in the following figure: </p><p><img src="TreeMapping.svg" alt="TreeMapping.svg" width="40%"> </p><p>One interesting consequence of this mapping is that abreadth-first traversal of the tree is implemented as a simplelinear scan of the array, which is in fact what the<tt>rcu_for_each_node_breadth_first()</tt> macro does.This macro is used at the beginning and ends of grace periods. </p><p>Each entry of the <tt>->level</tt> array referencesthe first <tt>rcu_node</tt> structure on the corresponding levelof the tree, for example, as shown below: </p><p><img src="TreeMappingLevel.svg" alt="TreeMappingLevel.svg" width="40%"> </p><p>The zero<sup>th</sup> element of the array references the root<tt>rcu_node</tt> structure, the first element references thefirst child of the root <tt>rcu_node</tt>, and finally the secondelement references the first leaf <tt>rcu_node</tt> structure. </p><p>For whatever it is worth, if you draw the tree to be tree-shapedrather than array-shaped, it is easy to draw a planar representation: </p><p><img src="TreeLevel.svg" alt="TreeLevel.svg" width="60%"> </p><p>Finally, the <tt>->rda</tt> field references a per-CPUpointer to the corresponding CPU's <tt>rcu_data</tt> structure. </p><p>All of these fields are constant once initialization is complete,and therefore need no protection. <h5>Grace-Period Tracking</h5> <p>This portion of the <tt>rcu_state</tt> structure is declaredas follows: <pre> 1 unsigned long gp_seq;</pre> <p>RCU grace periods are numbered, andthe <tt>->gp_seq</tt> field contains the current grace-periodsequence number.The bottom two bits are the state of the current grace period,which can be zero for not yet started or one for in progress.In other words, if the bottom two bits of <tt>->gp_seq</tt> arezero, then RCU is idle.Any other value in the bottom two bits indicates that something is broken.This field is protected by the root <tt>rcu_node</tt> structure's<tt>->lock</tt> field. </p><p>There are <tt>->gp_seq</tt> fieldsin the <tt>rcu_node</tt> and <tt>rcu_data</tt> structuresas well.The fields in the <tt>rcu_state</tt> structure represent themost current value, and those of the other structures are comparedin order to detect the beginnings and ends of grace periods in a distributedfashion.The values flow from <tt>rcu_state</tt> to <tt>rcu_node</tt>(down the tree from the root to the leaves) to <tt>rcu_data</tt>. <h5>Miscellaneous</h5> <p>This portion of the <tt>rcu_state</tt> structure is declaredas follows: <pre> 1 unsigned long gp_max; 2 char abbr; 3 char *name;</pre> <p>The <tt>->gp_max</tt> field tracks the duration of the longestgrace period in jiffies.It is protected by the root <tt>rcu_node</tt>'s <tt>->lock</tt>. <p>The <tt>->name</tt> and <tt>->abbr</tt> fields distinguishbetween preemptible RCU (“rcu_preempt” and “p”)and non-preemptible RCU (“rcu_sched” and “s”).These fields are used for diagnostic and tracing purposes. <h3><a name="The rcu_node Structure">The <tt>rcu_node</tt> Structure</a></h3> <p>The <tt>rcu_node</tt> structures form the combiningtree that propagates quiescent-stateinformation from the leaves to the root and also that propagatesgrace-period information from the root down to the leaves.They provides local copies of the grace-period state in orderto allow this information to be accessed in a synchronizedmanner without suffering the scalability limitations thatwould otherwise be imposed by global locking.In <tt>CONFIG_PREEMPT_RCU</tt> kernels, they manage the listsof tasks that have blocked while in their currentRCU read-side critical section.In <tt>CONFIG_PREEMPT_RCU</tt> with<tt>CONFIG_RCU_BOOST</tt>, they manage theper-<tt>rcu_node</tt> priority-boostingkernel threads (kthreads) and state.Finally, they record CPU-hotplug state in order to determinewhich CPUs should be ignored during a given grace period. </p><p>The <tt>rcu_node</tt> structure's fields are discussed,singly and in groups, in the following sections. <h5>Connection to Combining Tree</h5> <p>This portion of the <tt>rcu_node</tt> structure is declaredas follows: <pre> 1 struct rcu_node *parent; 2 u8 level; 3 u8 grpnum; 4 unsigned long grpmask; 5 int grplo; 6 int grphi;</pre> <p>The <tt>->parent</tt> pointer references the <tt>rcu_node</tt>one level up in the tree, and is <tt>NULL</tt> for the root<tt>rcu_node</tt>.The RCU implementation makes heavy use of this field to push quiescentstates up the tree.The <tt>->level</tt> field gives the level in the tree, withthe root being at level zero, its children at level one, and so on.The <tt>->grpnum</tt> field gives this node's position withinthe children of its parent, so this number can range between 0 and 31on 32-bit systems and between 0 and 63 on 64-bit systems.The <tt>->level</tt> and <tt>->grpnum</tt> fields areused only during initialization and for tracing.The <tt>->grpmask</tt> field is the bitmask counterpart of<tt>->grpnum</tt>, and therefore always has exactly one bit set.This mask is used to clear the bit corresponding to this <tt>rcu_node</tt>structure in its parent's bitmasks, which are described later.Finally, the <tt>->grplo</tt> and <tt>->grphi</tt> fieldscontain the lowest and highest numbered CPU served by this<tt>rcu_node</tt> structure, respectively. </p><p>All of these fields are constant, and thus do not require anysynchronization. <h5>Synchronization</h5> <p>This field of the <tt>rcu_node</tt> structure is declaredas follows: <pre> 1 raw_spinlock_t lock;</pre> <p>This field is used to protect the remaining fields in this structure,unless otherwise stated.That said, all of the fields in this structure can be accessed withoutlocking for tracing purposes.Yes, this can result in confusing traces, but better some tracing confusionthan to be heisenbugged out of existence. <h5>Grace-Period Tracking</h5> <p>This portion of the <tt>rcu_node</tt> structure is declaredas follows: <pre> 1 unsigned long gp_seq; 2 unsigned long gp_seq_needed;</pre> <p>The <tt>rcu_node</tt> structures' <tt>->gp_seq</tt> fields arethe counterparts of the field of the same name in the <tt>rcu_state</tt>structure.They each may lag up to one step behind their <tt>rcu_state</tt>counterpart.If the bottom two bits of a given <tt>rcu_node</tt> structure's<tt>->gp_seq</tt> field is zero, then this <tt>rcu_node</tt>structure believes that RCU is idle.</p><p>The <tt>>gp_seq</tt> field of each <tt>rcu_node</tt>structure is updated at the beginning and the endof each grace period. <p>The <tt>->gp_seq_needed</tt> fields record thefurthest-in-the-future grace period request seen by the corresponding<tt>rcu_node</tt> structure. The request is considered fulfilled whenthe value of the <tt>->gp_seq</tt> field equals or exceeds that ofthe <tt>->gp_seq_needed</tt> field. <table><tr><th> </th></tr><tr><th align="left">Quick Quiz:</th></tr><tr><td> Suppose that this <tt>rcu_node</tt> structure doesn't see a request for a very long time. Won't wrapping of the <tt>->gp_seq</tt> field cause problems?</td></tr><tr><th align="left">Answer:</th></tr><tr><td bgcolor="#ffffff"><font color="ffffff"> No, because if the <tt>->gp_seq_needed</tt> field lags behind the <tt>->gp_seq</tt> field, the <tt>->gp_seq_needed</tt> fieldLines 1–500 of 1391. Load more
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head><title>A Tour Through TREE_RCU's Data Structures [LWN.net]</title> <meta HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1"> <p>December 18, 2016</p> <p>This article was contributed by Paul E. McKenney</p> <h3>Introduction</h3> This document describes RCU's major data structures and their relationship to each other. <ol> <li> <a href="#Data-Structure Relationships"> Data-Structure Relationships</a> <li> <a href="#The rcu_state Structure"> The <tt>rcu_state</tt> Structure</a> <li> <a href="#The rcu_node Structure"> The <tt>rcu_node</tt> Structure</a> <li> <a href="#The rcu_segcblist Structure"> The <tt>rcu_segcblist</tt> Structure</a> <li> <a href="#The rcu_data Structure"> The <tt>rcu_data</tt> Structure</a> <li> <a href="#The rcu_head Structure"> The <tt>rcu_head</tt> Structure</a> <li> <a href="#RCU-Specific Fields in the task_struct Structure"> RCU-Specific Fields in the <tt>task_struct</tt> Structure</a> <li> <a href="#Accessor Functions"> Accessor Functions</a> </ol> <h3><a name="Data-Structure Relationships">Data-Structure Relationships</a></h3> <p>RCU is for all intents and purposes a large state machine, and its data structures maintain the state in such a way as to allow RCU readers to execute extremely quickly, while also processing the RCU grace periods requested by updaters in an efficient and extremely scalable fashion. The efficiency and scalability of RCU updaters is provided primarily by a combining tree, as shown below: </p><p><img src="BigTreeClassicRCU.svg" alt="BigTreeClassicRCU.svg" width="30%"> </p><p>This diagram shows an enclosing <tt>rcu_state</tt> structure containing a tree of <tt>rcu_node</tt> structures. Each leaf node of the <tt>rcu_node</tt> tree has up to 16 <tt>rcu_data</tt> structures associated with it, so that there are <tt>NR_CPUS</tt> number of <tt>rcu_data</tt> structures, one for each possible CPU. This structure is adjusted at boot time, if needed, to handle the common case where <tt>nr_cpu_ids</tt> is much less than <tt>NR_CPUs</tt>. For example, a number of Linux distributions set <tt>NR_CPUs=4096</tt>, which results in a three-level <tt>rcu_node</tt> tree. If the actual hardware has only 16 CPUs, RCU will adjust itself at boot time, resulting in an <tt>rcu_node</tt> tree with only a single node. </p><p>The purpose of this combining tree is to allow per-CPU events such as quiescent states, dyntick-idle transitions, and CPU hotplug operations to be processed efficiently and scalably. Quiescent states are recorded by the per-CPU <tt>rcu_data</tt> structures, and other events are recorded by the leaf-level <tt>rcu_node</tt> structures. All of these events are combined at each level of the tree until finally grace periods are completed at the tree's root <tt>rcu_node</tt> structure. A grace period can be completed at the root once every CPU (or, in the case of <tt>CONFIG_PREEMPT_RCU</tt>, task) has passed through a quiescent state. Once a grace period has completed, record of that fact is propagated back down the tree. </p><p>As can be seen from the diagram, on a 64-bit system a two-level tree with 64 leaves can accommodate 1,024 CPUs, with a fanout of 64 at the root and a fanout of 16 at the leaves. <table> <tr><th> </th></tr> <tr><th align="left">Quick Quiz:</th></tr> <tr><td> Why isn't the fanout at the leaves also 64? </td></tr> <tr><th align="left">Answer:</th></tr> <tr><td bgcolor="#ffffff"><font color="ffffff"> Because there are more types of events that affect the leaf-level <tt>rcu_node</tt> structures than further up the tree. Therefore, if the leaf <tt>rcu_node</tt> structures have fanout of 64, the contention on these structures' <tt>->structures</tt> becomes excessive. Experimentation on a wide variety of systems has shown that a fanout of 16 works well for the leaves of the <tt>rcu_node</tt> tree. </font> <p><font color="ffffff">Of course, further experience with systems having hundreds or thousands of CPUs may demonstrate that the fanout for the non-leaf <tt>rcu_node</tt> structures must also be reduced. Such reduction can be easily carried out when and if it proves necessary. In the meantime, if you are using such a system and running into contention problems on the non-leaf <tt>rcu_node</tt> structures, you may use the <tt>CONFIG_RCU_FANOUT</tt> kernel configuration parameter to reduce the non-leaf fanout as needed. </font> <p><font color="ffffff">Kernels built for systems with strong NUMA characteristics might also need to adjust <tt>CONFIG_RCU_FANOUT</tt> so that the domains of the <tt>rcu_node</tt> structures align with hardware boundaries. However, there has thus far been no need for this. </font></td></tr> <tr><td> </td></tr> </table> <p>If your system has more than 1,024 CPUs (or more than 512 CPUs on a 32-bit system), then RCU will automatically add more levels to the tree. For example, if you are crazy enough to build a 64-bit system with 65,536 CPUs, RCU would configure the <tt>rcu_node</tt> tree as follows: </p><p><img src="HugeTreeClassicRCU.svg" alt="HugeTreeClassicRCU.svg" width="50%"> </p><p>RCU currently permits up to a four-level tree, which on a 64-bit system accommodates up to 4,194,304 CPUs, though only a mere 524,288 CPUs for 32-bit systems. On the other hand, you can set both <tt>CONFIG_RCU_FANOUT</tt> and <tt>CONFIG_RCU_FANOUT_LEAF</tt> to be as small as 2, which would result in a 16-CPU test using a 4-level tree. This can be useful for testing large-system capabilities on small test machines. </p><p>This multi-level combining tree allows us to get most of the performance and scalability benefits of partitioning, even though RCU grace-period detection is inherently a global operation. The trick here is that only the last CPU to report a quiescent state into a given <tt>rcu_node</tt> structure need advance to the <tt>rcu_node</tt> structure at the next level up the tree. This means that at the leaf-level <tt>rcu_node</tt> structure, only one access out of sixteen will progress up the tree. For the internal <tt>rcu_node</tt> structures, the situation is even more extreme: Only one access out of sixty-four will progress up the tree. Because the vast majority of the CPUs do not progress up the tree, the lock contention remains roughly constant up the tree. No matter how many CPUs there are in the system, at most 64 quiescent-state reports per grace period will progress all the way to the root <tt>rcu_node</tt> structure, thus ensuring that the lock contention on that root <tt>rcu_node</tt> structure remains acceptably low. </p><p>In effect, the combining tree acts like a big shock absorber, keeping lock contention under control at all tree levels regardless of the level of loading on the system. </p><p>RCU updaters wait for normal grace periods by registering RCU callbacks, either directly via <tt>call_rcu()</tt> or indirectly via <tt>synchronize_rcu()</tt> and friends. RCU callbacks are represented by <tt>rcu_head</tt> structures, which are queued on <tt>rcu_data</tt> structures while they are waiting for a grace period to elapse, as shown in the following figure: </p><p><img src="BigTreePreemptRCUBHdyntickCB.svg" alt="BigTreePreemptRCUBHdyntickCB.svg" width="40%"> </p><p>This figure shows how <tt>TREE_RCU</tt>'s and <tt>PREEMPT_RCU</tt>'s major data structures are related. Lesser data structures will be introduced with the algorithms that make use of them. </p><p>Note that each of the data structures in the above figure has its own synchronization: <p><ol> <li> Each <tt>rcu_state</tt> structures has a lock and a mutex, and some fields are protected by the corresponding root <tt>rcu_node</tt> structure's lock. <li> Each <tt>rcu_node</tt> structure has a spinlock. <li> The fields in <tt>rcu_data</tt> are private to the corresponding CPU, although a few can be read and written by other CPUs. </ol> <p>It is important to note that different data structures can have very different ideas about the state of RCU at any given time. For but one example, awareness of the start or end of a given RCU grace period propagates slowly through the data structures. This slow propagation is absolutely necessary for RCU to have good read-side performance. If this balkanized implementation seems foreign to you, one useful trick is to consider each instance of these data structures to be a different person, each having the usual slightly different view of reality. </p><p>The general role of each of these data structures is as follows: </p><ol> <li> <tt>rcu_state</tt>: This structure forms the interconnection between the <tt>rcu_node</tt> and <tt>rcu_data</tt> structures, tracks grace periods, serves as short-term repository for callbacks orphaned by CPU-hotplug events, maintains <tt>rcu_barrier()</tt> state, tracks expedited grace-period state, and maintains state used to force quiescent states when grace periods extend too long, <li> <tt>rcu_node</tt>: This structure forms the combining tree that propagates quiescent-state information from the leaves to the root, and also propagates grace-period information from the root to the leaves. It provides local copies of the grace-period state in order to allow this information to be accessed in a synchronized manner without suffering the scalability limitations that would otherwise be imposed by global locking. In <tt>CONFIG_PREEMPT_RCU</tt> kernels, it manages the lists of tasks that have blocked while in their current RCU read-side critical section. In <tt>CONFIG_PREEMPT_RCU</tt> with <tt>CONFIG_RCU_BOOST</tt>, it manages the per-<tt>rcu_node</tt> priority-boosting kernel threads (kthreads) and state. Finally, it records CPU-hotplug state in order to determine which CPUs should be ignored during a given grace period. <li> <tt>rcu_data</tt>: This per-CPU structure is the focus of quiescent-state detection and RCU callback queuing. It also tracks its relationship to the corresponding leaf <tt>rcu_node</tt> structure to allow more-efficient propagation of quiescent states up the <tt>rcu_node</tt> combining tree. Like the <tt>rcu_node</tt> structure, it provides a local copy of the grace-period information to allow for-free synchronized access to this information from the corresponding CPU. Finally, this structure records past dyntick-idle state for the corresponding CPU and also tracks statistics. <li> <tt>rcu_head</tt>: This structure represents RCU callbacks, and is the only structure allocated and managed by RCU users. The <tt>rcu_head</tt> structure is normally embedded within the RCU-protected data structure. </ol> <p>If all you wanted from this article was a general notion of how RCU's data structures are related, you are done. Otherwise, each of the following sections give more details on the <tt>rcu_state</tt>, <tt>rcu_node</tt> and <tt>rcu_data</tt> data structures. <h3><a name="The rcu_state Structure"> The <tt>rcu_state</tt> Structure</a></h3> <p>The <tt>rcu_state</tt> structure is the base structure that represents the state of RCU in the system. This structure forms the interconnection between the <tt>rcu_node</tt> and <tt>rcu_data</tt> structures, tracks grace periods, contains the lock used to synchronize with CPU-hotplug events, and maintains state used to force quiescent states when grace periods extend too long, </p><p>A few of the <tt>rcu_state</tt> structure's fields are discussed, singly and in groups, in the following sections. The more specialized fields are covered in the discussion of their use. <h5>Relationship to rcu_node and rcu_data Structures</h5> This portion of the <tt>rcu_state</tt> structure is declared as follows: <pre> 1 struct rcu_node node[NUM_RCU_NODES]; 2 struct rcu_node *level[NUM_RCU_LVLS + 1]; 3 struct rcu_data __percpu *rda; </pre> <table> <tr><th> </th></tr> <tr><th align="left">Quick Quiz:</th></tr> <tr><td> Wait a minute! You said that the <tt>rcu_node</tt> structures formed a tree, but they are declared as a flat array! What gives? </td></tr> <tr><th align="left">Answer:</th></tr> <tr><td bgcolor="#ffffff"><font color="ffffff"> The tree is laid out in the array. The first node In the array is the head, the next set of nodes in the array are children of the head node, and so on until the last set of nodes in the array are the leaves. </font> <p><font color="ffffff">See the following diagrams to see how this works. </font></td></tr> <tr><td> </td></tr> </table> <p>The <tt>rcu_node</tt> tree is embedded into the <tt>->node[]</tt> array as shown in the following figure: </p><p><img src="TreeMapping.svg" alt="TreeMapping.svg" width="40%"> </p><p>One interesting consequence of this mapping is that a breadth-first traversal of the tree is implemented as a simple linear scan of the array, which is in fact what the <tt>rcu_for_each_node_breadth_first()</tt> macro does. This macro is used at the beginning and ends of grace periods. </p><p>Each entry of the <tt>->level</tt> array references the first <tt>rcu_node</tt> structure on the corresponding level of the tree, for example, as shown below: </p><p><img src="TreeMappingLevel.svg" alt="TreeMappingLevel.svg" width="40%"> </p><p>The zero<sup>th</sup> element of the array references the root <tt>rcu_node</tt> structure, the first element references the first child of the root <tt>rcu_node</tt>, and finally the second element references the first leaf <tt>rcu_node</tt> structure. </p><p>For whatever it is worth, if you draw the tree to be tree-shaped rather than array-shaped, it is easy to draw a planar representation: </p><p><img src="TreeLevel.svg" alt="TreeLevel.svg" width="60%"> </p><p>Finally, the <tt>->rda</tt> field references a per-CPU pointer to the corresponding CPU's <tt>rcu_data</tt> structure. </p><p>All of these fields are constant once initialization is complete, and therefore need no protection. <h5>Grace-Period Tracking</h5> <p>This portion of the <tt>rcu_state</tt> structure is declared as follows: <pre> 1 unsigned long gp_seq; </pre> <p>RCU grace periods are numbered, and the <tt>->gp_seq</tt> field contains the current grace-period sequence number. The bottom two bits are the state of the current grace period, which can be zero for not yet started or one for in progress. In other words, if the bottom two bits of <tt>->gp_seq</tt> are zero, then RCU is idle. Any other value in the bottom two bits indicates that something is broken. This field is protected by the root <tt>rcu_node</tt> structure's <tt>->lock</tt> field. </p><p>There are <tt>->gp_seq</tt> fields in the <tt>rcu_node</tt> and <tt>rcu_data</tt> structures as well. The fields in the <tt>rcu_state</tt> structure represent the most current value, and those of the other structures are compared in order to detect the beginnings and ends of grace periods in a distributed fashion. The values flow from <tt>rcu_state</tt> to <tt>rcu_node</tt> (down the tree from the root to the leaves) to <tt>rcu_data</tt>. <h5>Miscellaneous</h5> <p>This portion of the <tt>rcu_state</tt> structure is declared as follows: <pre> 1 unsigned long gp_max; 2 char abbr; 3 char *name; </pre> <p>The <tt>->gp_max</tt> field tracks the duration of the longest grace period in jiffies. It is protected by the root <tt>rcu_node</tt>'s <tt>->lock</tt>. <p>The <tt>->name</tt> and <tt>->abbr</tt> fields distinguish between preemptible RCU (“rcu_preempt” and “p”) and non-preemptible RCU (“rcu_sched” and “s”). These fields are used for diagnostic and tracing purposes. <h3><a name="The rcu_node Structure"> The <tt>rcu_node</tt> Structure</a></h3> <p>The <tt>rcu_node</tt> structures form the combining tree that propagates quiescent-state information from the leaves to the root and also that propagates grace-period information from the root down to the leaves. They provides local copies of the grace-period state in order to allow this information to be accessed in a synchronized manner without suffering the scalability limitations that would otherwise be imposed by global locking. In <tt>CONFIG_PREEMPT_RCU</tt> kernels, they manage the lists of tasks that have blocked while in their current RCU read-side critical section. In <tt>CONFIG_PREEMPT_RCU</tt> with <tt>CONFIG_RCU_BOOST</tt>, they manage the per-<tt>rcu_node</tt> priority-boosting kernel threads (kthreads) and state. Finally, they record CPU-hotplug state in order to determine which CPUs should be ignored during a given grace period. </p><p>The <tt>rcu_node</tt> structure's fields are discussed, singly and in groups, in the following sections. <h5>Connection to Combining Tree</h5> <p>This portion of the <tt>rcu_node</tt> structure is declared as follows: <pre> 1 struct rcu_node *parent; 2 u8 level; 3 u8 grpnum; 4 unsigned long grpmask; 5 int grplo; 6 int grphi; </pre> <p>The <tt>->parent</tt> pointer references the <tt>rcu_node</tt> one level up in the tree, and is <tt>NULL</tt> for the root <tt>rcu_node</tt>. The RCU implementation makes heavy use of this field to push quiescent states up the tree. The <tt>->level</tt> field gives the level in the tree, with the root being at level zero, its children at level one, and so on. The <tt>->grpnum</tt> field gives this node's position within the children of its parent, so this number can range between 0 and 31 on 32-bit systems and between 0 and 63 on 64-bit systems. The <tt>->level</tt> and <tt>->grpnum</tt> fields are used only during initialization and for tracing. The <tt>->grpmask</tt> field is the bitmask counterpart of <tt>->grpnum</tt>, and therefore always has exactly one bit set. This mask is used to clear the bit corresponding to this <tt>rcu_node</tt> structure in its parent's bitmasks, which are described later. Finally, the <tt>->grplo</tt> and <tt>->grphi</tt> fields contain the lowest and highest numbered CPU served by this <tt>rcu_node</tt> structure, respectively. </p><p>All of these fields are constant, and thus do not require any synchronization. <h5>Synchronization</h5> <p>This field of the <tt>rcu_node</tt> structure is declared as follows: <pre> 1 raw_spinlock_t lock; </pre> <p>This field is used to protect the remaining fields in this structure, unless otherwise stated. That said, all of the fields in this structure can be accessed without locking for tracing purposes. Yes, this can result in confusing traces, but better some tracing confusion than to be heisenbugged out of existence. <h5>Grace-Period Tracking</h5> <p>This portion of the <tt>rcu_node</tt> structure is declared as follows: <pre> 1 unsigned long gp_seq; 2 unsigned long gp_seq_needed; </pre> <p>The <tt>rcu_node</tt> structures' <tt>->gp_seq</tt> fields are the counterparts of the field of the same name in the <tt>rcu_state</tt> structure. They each may lag up to one step behind their <tt>rcu_state</tt> counterpart. If the bottom two bits of a given <tt>rcu_node</tt> structure's <tt>->gp_seq</tt> field is zero, then this <tt>rcu_node</tt> structure believes that RCU is idle. </p><p>The <tt>>gp_seq</tt> field of each <tt>rcu_node</tt> structure is updated at the beginning and the end of each grace period. <p>The <tt>->gp_seq_needed</tt> fields record the furthest-in-the-future grace period request seen by the corresponding <tt>rcu_node</tt> structure. The request is considered fulfilled when the value of the <tt>->gp_seq</tt> field equals or exceeds that of the <tt>->gp_seq_needed</tt> field. <table> <tr><th> </th></tr> <tr><th align="left">Quick Quiz:</th></tr> <tr><td> Suppose that this <tt>rcu_node</tt> structure doesn't see a request for a very long time. Won't wrapping of the <tt>->gp_seq</tt> field cause problems? </td></tr> <tr><th align="left">Answer:</th></tr> <tr><td bgcolor="#ffffff"><font color="ffffff"> No, because if the <tt>->gp_seq_needed</tt> field lags behind the <tt>->gp_seq</tt> field, the <tt>->gp_seq_needed</tt> field