<!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_dynticks Structure"> The <tt>rcu_dynticks</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 <tt>CONFIG_RCU_FANOUT</tt> to beas small as 2 if you wish, which would permit only 16 CPUs, whichis useful for testing. </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>The Linux kernel actually supports multiple flavors of RCUrunning concurrently, so RCU builds separate data structures for eachflavor.For example, for <tt>CONFIG_TREE_RCU=y</tt> kernels, RCU providesrcu_sched and rcu_bh, as shown below: </p><p><img src="BigTreeClassicRCUBH.svg" alt="BigTreeClassicRCUBH.svg" width="33%"> </p><p>Energy efficiency is increasingly important, and for thatreason the Linux kernel provides <tt>CONFIG_NO_HZ_IDLE</tt>, whichturns off the scheduling-clock interrupts on idle CPUs, which inturn allows those CPUs to attain deeper sleep states and to consumeless energy.CPUs whose scheduling-clock interrupts have been turned off aresaid to be in <i>dyntick-idle mode</i>.RCU must handle dyntick-idle CPUs speciallybecause RCU would otherwise wake up each CPU on every grace period,which would defeat the whole purpose of <tt>CONFIG_NO_HZ_IDLE</tt>.RCU uses the <tt>rcu_dynticks</tt> structure to trackwhich CPUs are in dyntick idle mode, as shown below: </p><p><img src="BigTreeClassicRCUBHdyntick.svg" alt="BigTreeClassicRCUBHdyntick.svg" width="33%"> </p><p>However, if a CPU is in dyntick-idle mode, it is in that modefor all flavors of RCU.Therefore, a single <tt>rcu_dynticks</tt> structure is allocated perCPU, and all of a given CPU's <tt>rcu_data</tt> structures sharethat <tt>rcu_dynticks</tt>, as shown in the figure. </p><p>Kernels built with <tt>CONFIG_PREEMPT_RCU</tt> supportrcu_preempt in addition to rcu_sched and rcu_bh, as shown below: </p><p><img src="BigTreePreemptRCUBHdyntick.svg" alt="BigTreePreemptRCUBHdyntick.svg" width="35%"> </p><p>RCU updaters wait for normal grace periods by registeringRCU callbacks, either directly via <tt>call_rcu()</tt> andfriends (namely <tt>call_rcu_bh()</tt> and <tt>call_rcu_sched()</tt>),there being a separate interface per flavor of RCU)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.<li> Similarly, the fields in <tt>rcu_dynticks</tt> are private to the corresponding CPU, although a few can be read 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_dynticks</tt>: This per-CPU structure tracks the current dyntick-idle state for the corresponding CPU. Unlike the other three structures, the <tt>rcu_dynticks</tt> structure is not replicated per RCU flavor.<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>, <tt>rcu_data</tt>,and <tt>rcu_dynticks</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 thatrepresents a flavor of RCU.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 gpnum; 2 unsigned long completed;</pre> <p>RCU grace periods are numbered, andthe <tt>->gpnum</tt> field contains the number of the graceperiod that started most recently.The <tt>->completed</tt> field contains the number of thegrace period that completed most recently.If the two fields are equal, the RCU grace period that most recentlystarted has already completed, and therefore the correspondingflavor of RCU is idle.If <tt>->gpnum</tt> is one greater than <tt>->completed</tt>,then <tt>->gpnum</tt> gives the number of the current RCUgrace period, which has not yet completed.Any other combination of values indicates that something is broken.These two fields are protected by the root <tt>rcu_node</tt>'s<tt>->lock</tt> field. </p><p>There are <tt>->gpnum</tt> and <tt>->completed</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 values, and those of the other structures are comparedin order to detect the start of a new grace period 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> field points to the name of the RCU flavor(for example, “rcu_sched”), and is constant.The <tt>->abbr</tt> field contains a one-character abbreviation,for example, “s” for RCU-sched. <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>Lines 1–500 of 1435. 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_dynticks Structure"> The <tt>rcu_dynticks</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 <tt>CONFIG_RCU_FANOUT</tt> to be as small as 2 if you wish, which would permit only 16 CPUs, which is useful for testing. </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>The Linux kernel actually supports multiple flavors of RCU running concurrently, so RCU builds separate data structures for each flavor. For example, for <tt>CONFIG_TREE_RCU=y</tt> kernels, RCU provides rcu_sched and rcu_bh, as shown below: </p><p><img src="BigTreeClassicRCUBH.svg" alt="BigTreeClassicRCUBH.svg" width="33%"> </p><p>Energy efficiency is increasingly important, and for that reason the Linux kernel provides <tt>CONFIG_NO_HZ_IDLE</tt>, which turns off the scheduling-clock interrupts on idle CPUs, which in turn allows those CPUs to attain deeper sleep states and to consume less energy. CPUs whose scheduling-clock interrupts have been turned off are said to be in <i>dyntick-idle mode</i>. RCU must handle dyntick-idle CPUs specially because RCU would otherwise wake up each CPU on every grace period, which would defeat the whole purpose of <tt>CONFIG_NO_HZ_IDLE</tt>. RCU uses the <tt>rcu_dynticks</tt> structure to track which CPUs are in dyntick idle mode, as shown below: </p><p><img src="BigTreeClassicRCUBHdyntick.svg" alt="BigTreeClassicRCUBHdyntick.svg" width="33%"> </p><p>However, if a CPU is in dyntick-idle mode, it is in that mode for all flavors of RCU. Therefore, a single <tt>rcu_dynticks</tt> structure is allocated per CPU, and all of a given CPU's <tt>rcu_data</tt> structures share that <tt>rcu_dynticks</tt>, as shown in the figure. </p><p>Kernels built with <tt>CONFIG_PREEMPT_RCU</tt> support rcu_preempt in addition to rcu_sched and rcu_bh, as shown below: </p><p><img src="BigTreePreemptRCUBHdyntick.svg" alt="BigTreePreemptRCUBHdyntick.svg" width="35%"> </p><p>RCU updaters wait for normal grace periods by registering RCU callbacks, either directly via <tt>call_rcu()</tt> and friends (namely <tt>call_rcu_bh()</tt> and <tt>call_rcu_sched()</tt>), there being a separate interface per flavor of RCU) 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. <li> Similarly, the fields in <tt>rcu_dynticks</tt> are private to the corresponding CPU, although a few can be read 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_dynticks</tt>: This per-CPU structure tracks the current dyntick-idle state for the corresponding CPU. Unlike the other three structures, the <tt>rcu_dynticks</tt> structure is not replicated per RCU flavor. <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>, <tt>rcu_data</tt>, and <tt>rcu_dynticks</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 a flavor of RCU. 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 gpnum; 2 unsigned long completed; </pre> <p>RCU grace periods are numbered, and the <tt>->gpnum</tt> field contains the number of the grace period that started most recently. The <tt>->completed</tt> field contains the number of the grace period that completed most recently. If the two fields are equal, the RCU grace period that most recently started has already completed, and therefore the corresponding flavor of RCU is idle. If <tt>->gpnum</tt> is one greater than <tt>->completed</tt>, then <tt>->gpnum</tt> gives the number of the current RCU grace period, which has not yet completed. Any other combination of values indicates that something is broken. These two fields are protected by the root <tt>rcu_node</tt>'s <tt>->lock</tt> field. </p><p>There are <tt>->gpnum</tt> and <tt>->completed</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 values, and those of the other structures are compared in order to detect the start of a new grace period 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> field points to the name of the RCU flavor (for example, “rcu_sched”), and is constant. The <tt>->abbr</tt> field contains a one-character abbreviation, for example, “s” for RCU-sched. <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>