Merge tag 'rcu.2022.05.19a' of git://git.kernel.org/pub/scm/linux/kernel/git/paulmck/linux-rcu

and from either dyntick-idle or user mode, so that this counter has an

even value when the CPU is in dyntick-idle mode or user mode and an odd

value otherwise. The transitions to/from user mode need to be counted

for user mode adaptive-ticks support (see timers/NO_HZ.txt).

for user mode adaptive-ticks support (see Documentation/timers/no_hz.rst).

The ``->rcu_need_heavy_qs`` field is used to record the fact that the

RCU core code would really like to see a quiescent state from the

period also drove it to completion. This straightforward approach had

the disadvantage of needing to account for POSIX signals sent to user

tasks, so more recent implemementations use the Linux kernel's

`workqueues <https://www.kernel.org/doc/Documentation/core-api/workqueue.rst>`__.

workqueues (see Documentation/core-api/workqueue.rst).

The requesting task still does counter snapshotting and funnel-lock

processing, but the task reaching the top of the funnel lock does a

outermost RCU read-side critical section containing that

rcu_dereference(), unless protection of the corresponding data

element has been passed from RCU to some other synchronization

mechanism, most commonly locking or `reference

counting <https://www.kernel.org/doc/Documentation/RCU/rcuref.txt>`__.

mechanism, most commonly locking or reference counting

(see ../../rcuref.rst).

.. |high-quality implementation of C11 memory_order_consume [PDF]| replace:: high-quality implementation of C11 ``memory_order_consume`` [PDF]

.. _high-quality implementation of C11 memory_order_consume [PDF]: http://www.rdrop.com/users/paulmck/RCU/consume.2015.07.13a.pdf

three APIs are therefore implemented by separate functions that check

for voluntary context switches.

Tasks Rude RCU

~~~~~~~~~~~~~~

Some forms of tracing need to wait for all preemption-disabled regions

of code running on any online CPU, including those executed when RCU is

not watching.  This means that synchronize_rcu() is insufficient, and

Tasks Rude RCU must be used instead.  This flavor of RCU does its work by

forcing a workqueue to be scheduled on each online CPU, hence the "Rude"

moniker.  And this operation is considered to be quite rude by real-time

workloads that don't want their ``nohz_full`` CPUs receiving IPIs and

by battery-powered systems that don't want their idle CPUs to be awakened.

The tasks-rude-RCU API is also reader-marking-free and thus quite compact,

consisting of call_rcu_tasks_rude(), synchronize_rcu_tasks_rude(),

and rcu_barrier_tasks_rude().

Tasks Trace RCU

~~~~~~~~~~~~~~~

Some forms of tracing need to sleep in readers, but cannot tolerate

SRCU's read-side overhead, which includes a full memory barrier in both

srcu_read_lock() and srcu_read_unlock().  This need is handled by a

Tasks Trace RCU that uses scheduler locking and IPIs to synchronize with

readers.  Real-time systems that cannot tolerate IPIs may build their

kernels with ``CONFIG_TASKS_TRACE_RCU_READ_MB=y``, which avoids the IPIs at

the expense of adding full memory barriers to the read-side primitives.

The tasks-trace-RCU API is also reasonably compact,

consisting of rcu_read_lock_trace(), rcu_read_unlock_trace(),

rcu_read_lock_trace_held(), call_rcu_tasks_trace(),

synchronize_rcu_tasks_trace(), and rcu_barrier_tasks_trace().

Possible Future Changes

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

Hash tables are often implemented as an array, where each array entry

has a linked-list hash chain.  Each hash chain can be protected by RCU

as described in the listRCU.txt document.  This approach also applies

to other array-of-list situations, such as radix trees.

as described in listRCU.rst.  This approach also applies to other

array-of-list situations, such as radix trees.

.. _static_arrays:

		prevents destructive compiler optimizations.  However,

		with a bit of devious creativity, it is possible to

		mishandle the return value from rcu_dereference().

		Please see rcu_dereference.txt in this directory for

		more information.

		Please see rcu_dereference.rst for more information.

		The rcu_dereference() primitive is used by the

		various "_rcu()" list-traversal primitives, such

		primitives.  This is particularly useful in code that

		is common to readers and updaters.  However, lockdep

		will complain if you access rcu_dereference() outside

		of an RCU read-side critical section.  See lockdep.txt

		of an RCU read-side critical section.  See lockdep.rst

		to learn what to do about this.

		Of course, neither rcu_dereference() nor the "_rcu()"

	primitives when the update-side lock is held is that doing so

	can be quite helpful in reducing code bloat when common code is

	shared between readers and updaters.  Additional primitives

	are provided for this case, as discussed in lockdep.txt.

	are provided for this case, as discussed in lockdep.rst.

	One exception to this rule is when data is only ever added to

	the linked data structure, and is never removed during any

	both rcu_barrier() and synchronize_rcu(), if necessary, using

	something like workqueues to to execute them concurrently.

	See rcubarrier.txt for more information.

	See rcubarrier.rst for more information.