path: root/Documentation/RCU/Design/Data-Structures/Data-Structures.rst

===================================================
A Tour Through TREE_RCU's Data Structures [LWN.net]
===================================================

December 18, 2016

This article was contributed by Paul E. McKenney

Introduction
============

This document describes RCU's major data structures and their relationship
to each other.

Data-Structure Relationships
============================

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:

.. kernel-figure:: BigTreeClassicRCU.svg

This diagram shows an enclosing ``rcu_state`` structure containing a tree
of ``rcu_node`` structures. Each leaf node of the ``rcu_node`` tree has up
to 16 ``rcu_data`` structures associated with it, so that there are
``NR_CPUS`` number of ``rcu_data`` structures, one for each possible CPU.
This structure is adjusted at boot time, if needed, to handle the common
case where ``nr_cpu_ids`` is much less than ``NR_CPUs``.
For example, a number of Linux distributions set ``NR_CPUs=4096``,
which results in a three-level ``rcu_node`` tree.
If the actual hardware has only 16 CPUs, RCU will adjust itself
at boot time, resulting in an ``rcu_node`` tree with only a single node.

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 ``rcu_data`` structures,
and other events are recorded by the leaf-level ``rcu_node``
structures.
All of these events are combined at each level of the tree until finally
grace periods are completed at the tree's root ``rcu_node``
structure.
A grace period can be completed at the root once every CPU
(or, in the case of ``CONFIG_PREEMPT_RCU``, task)
has passed through a quiescent state.
Once a grace period has completed, record of that fact is propagated
back down the tree.

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.

+-----------------------------------------------------------------------+
| **Quick Quiz**:                                                       |
+-----------------------------------------------------------------------+
| Why isn't the fanout at the leaves also 64?                           |
+-----------------------------------------------------------------------+
| **Answer**:                                                           |
+-----------------------------------------------------------------------+
| Because there are more types of events that affect the leaf-level     |
| ``rcu_node`` structures than further up the tree. Therefore, if the   |
| leaf ``rcu_node`` structures have fanout of 64, the contention on     |
| these structures' ``->structures`` becomes excessive. Experimentation |
| on a wide variety of systems has shown that a fanout of 16 works well |
| for the leaves of the ``rcu_node`` tree.                              |
|                                                                       |
| Of course, further experience with systems having hundreds or         |
| thousands of CPUs may demonstrate that the fanout for the non-leaf    |
| ``rcu_node`` 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 ``rcu_node`` structures, you may use the              |
| ``CONFIG_RCU_FANOUT`` kernel configuration parameter to reduce the    |
| non-leaf fanout as needed.                                            |
|                                                                       |
| Kernels built for systems with strong NUMA characteristics might      |
| also need to adjust ``CONFIG_RCU_FANOUT`` so that the domains of      |
| the ``rcu_node`` structures align with hardware boundaries.           |
| However, there has thus far been no need for this.                    |
+-----------------------------------------------------------------------+

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 ``rcu_node`` tree as follows:

.. kernel-figure:: HugeTreeClassicRCU.svg

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
``CONFIG_RCU_FANOUT`` and ``CONFIG_RCU_FANOUT_LEAF`` 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.

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 ``rcu_node``
structure need advance to the ``rcu_node`` structure at the next level
up the tree. This means that at the leaf-level ``rcu_node`` structure,
only one access out of sixteen will progress up the tree. For the
internal ``rcu_node`` 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 ``rcu_node`` structure,
thus ensuring that the lock contention on that root ``rcu_node``
structure remains acceptably low.

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.

RCU updaters wait for normal grace periods by registering RCU callbacks,
either directly via ``call_rcu()`` or indirectly via
``synchronize_rcu()`` and friends. RCU callbacks are represented by
``rcu_head`` structures, which are queued on ``rcu_data`` structures
while they are waiting for a grace period to elapse, as shown in the
following figure:

.. kernel-figure:: BigTreePreemptRCUBHdyntickCB.svg

This figure shows how ``TREE_RCU``'s and ``PREEMPT_RCU``'s major data
structures are related. Lesser data structures will be introduced with
the algorithms that make use of them.

Note that each of the data structures in the above figure has its own
synchronization:

#. Each ``rcu_state`` structures has a lock and a mutex, and some fields
   are protected by the corresponding root ``rcu_node`` structure's lock.
#. Each ``rcu_node`` structure has a spinlock.
#. The fields in ``rcu_data`` are private to the corresponding CPU,
   although a few can be read and written by other CPUs.

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.

The general role of each of these data structures is as follows:

#. ``rcu_state``: This structure forms the interconnection between the
   ``rcu_node`` and ``rcu_data`` structures, tracks grace periods,
   serves as short-term repository for callbacks orphaned by CPU-hotplug
   events, maintains ``rcu_barrier()`` state, tracks expedited
   grace-period state, and maintains state used to force quiescent
   states when grace periods extend too long,
#. ``rcu_node``: 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 ``CONFIG_PREEMPT_RCU`` kernels, it manages the
   lists of tasks that have blocked while in their current RCU read-side
   critical section. In ``CONFIG_PREEMPT_RCU`` with
   ``CONFIG_RCU_BOOST``, it manages the per-\ ``rcu_node``
   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.
#. ``rcu_data``: This per-CPU structure is the focus of quiescent-state
   detection and RCU callback queuing. It also tracks its relationship
   to the corresponding leaf ``rcu_node`` structure to allow
   more-efficient propagation of quiescent states up the ``rcu_node``
   combining tree. Like the ``rcu_node`` 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.
#. ``rcu_head``: This structure represents RCU callbacks, and is the
   only structure allocated and managed by RCU users. The ``rcu_head``
   structure is normally embedded within the RCU-protected data
   structure.

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 ``rcu_state``, ``rcu_node``
and ``rcu_data`` data structures.

The ``rcu_state`` Structure
~~~~~~~~~~~~~~~~~~~~~~~~~~~

The ``rcu_state`` structure is the base structure that represents the
state of RCU in the system. This structure forms the interconnection
between the ``rcu_node`` and ``rcu_data`` 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,

A few of the ``rcu_state`` 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.

Relationship to rcu_node and rcu_data Structures
''''''''''''''''''''''''''''''''''''''''''''''''

This portion of the ``rcu_state`` structure is declared as follows:

::

     1   struct rcu_node node[NUM_RCU_NODES];
     2   struct rcu_node *level[NUM_RCU_LVLS + 1];
     3   struct rcu_data __percpu *rda;

+-----------------------------------------------------------------------+
| **Quick Quiz**:                                                       |
+-----------------------------------------------------------------------+
| Wait a minute! You said that the ``rcu_node`` structures formed a     |
| tree, but they are declared as a flat array! What gives?              |
+-----------------------------------------------------------------------+
| **Answer**:                                                           |
+-----------------------------------------------------------------------+
| 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.                                                               |
| See the following diagrams to see how this works.                     |
+-----------------------------------------------------------------------+

The ``rcu_node`` tree is embedded into the ``->node[]`` array as shown
in the following figure:

.. kernel-figure:: TreeMapping.svg

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 ``rcu_for_each_node_breadth_first()``
macro does. This macro is used at the beginning and ends of grace
periods.

Each entry of the ``->level`` array referenc