Merge branch 'for-mingo' of...

would need to be instructions following ``rcu_read_unlock()``. Although

``synchronize_rcu()`` would guarantee that execution reached the

``rcu_read_unlock()``, it would not be able to guarantee that execution

had completely left the trampoline.

had completely left the trampoline. Worse yet, in some situations

the trampoline's protection must extend a few instructions *prior* to

execution reaching the trampoline.  For example, these few instructions

might calculate the address of the trampoline, so that entering the

trampoline would be pre-ordained a surprisingly long time before execution

actually reached the trampoline itself.

The solution, in the form of `Tasks

RCU <https://lwn.net/Articles/607117/>`__, is to have implicit read-side

.. SPDX-License-Identifier: GPL-2.0

================================

Review Checklist for RCU Patches

================================

This document contains a checklist for producing and reviewing patches

	__rcu sparse checks to validate your RCU code.	These can help

	find problems as follows:

	CONFIG_PROVE_LOCKING: check that accesses to RCU-protected data

	CONFIG_PROVE_LOCKING:

		check that accesses to RCU-protected data

		structures are carried out under the proper RCU

		read-side critical section, while holding the right

		combination of locks, or whatever other conditions

		are appropriate.

	CONFIG_DEBUG_OBJECTS_RCU_HEAD: check that you don't pass the

	CONFIG_DEBUG_OBJECTS_RCU_HEAD:

		check that you don't pass the

		same object to call_rcu() (or friends) before an RCU

		grace period has elapsed since the last time that you

		passed that same object to call_rcu() (or friends).

	__rcu sparse checks: tag the pointer to the RCU-protected data

	__rcu sparse checks:

		tag the pointer to the RCU-protected data

		structure with __rcu, and sparse will warn you if you

		access that pointer without the services of one of the

		variants of rcu_dereference().

	You instead need to use one of the barrier functions:

	o	call_rcu() -> rcu_barrier()

	o	call_srcu() -> srcu_barrier()

	-	call_rcu() -> rcu_barrier()

	-	call_srcu() -> srcu_barrier()

	However, these barrier functions are absolutely -not- guaranteed

	to wait for a grace period.  In fact, if there are no call_rcu()

.. SPDX-License-Identifier: GPL-2.0

.. _rcu_concepts:

============

   :maxdepth: 3

   arrayRCU

   checklist

   lockdep

   lockdep-splat

   rcubarrier

   rcu_dereference

   whatisRCU

   rcu

   rculist_nulls

   rcuref

   torture

   stallwarn

   listRCU

   NMI-RCU

   UP

.. SPDX-License-Identifier: GPL-2.0

=================

Lockdep-RCU Splat

=================

Lockdep-RCU was added to the Linux kernel in early 2010

(http://lwn.net/Articles/371986/).  This facility checks for some common

misuses of the RCU API, most notably using one of the rcu_dereference()

being the real world and all that.

So let's look at an example RCU lockdep splat from 3.0-rc5, one that

has long since been fixed:

has long since been fixed::

    =============================

    WARNING: suspicious RCU usage

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

    block/cfq-iosched.c:2776 suspicious rcu_dereference_protected() usage!

other info that might help us debug this:

other info that might help us debug this::

    rcu_scheduler_active = 1, debug_locks = 0

    3 locks held by scsi_scan_6/1552:

    [<ffffffff81097510>] ? __kthread_init_worker+0x70/0x70

    [<ffffffff817db150>] ? gs_change+0xb/0xb

Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows:

Line 2776 of block/cfq-iosched.c in v3.0-rc5 is as follows::

	if (rcu_dereference(ioc->ioc_data) == cic) {

And maybe that lock really does protect this reference.  If so, the fix

is to inform RCU, perhaps by changing __cfq_exit_single_io_context() to

take the struct request_queue "q" from cfq_exit_queue() as an argument,

which would permit us to invoke rcu_dereference_protected as follows:

which would permit us to invoke rcu_dereference_protected as follows::

	if (rcu_dereference_protected(ioc->ioc_data,

				      lockdep_is_held(&q->queue_lock)) == cic) {

section.  In this case, the critical section must span the use of the

return value from rcu_dereference(), or at least until there is some

reference count incremented or some such.  One way to handle this is to

add rcu_read_lock() and rcu_read_unlock() as follows:

add rcu_read_lock() and rcu_read_unlock() as follows::

	rcu_read_lock();

	if (rcu_dereference(ioc->ioc_data) == cic) {

But in this particular case, we don't actually dereference the pointer

returned from rcu_dereference().  Instead, that pointer is just compared

to the cic pointer, which means that the rcu_dereference() can be replaced

by rcu_access_pointer() as follows:

by rcu_access_pointer() as follows::

	if (rcu_access_pointer(ioc->ioc_data) == cic) {

.. SPDX-License-Identifier: GPL-2.0

========================

RCU and lockdep checking

========================

All flavors of RCU have lockdep checking available, so that lockdep is

aware of when each task enters and leaves any flavor of RCU read-side

deadlocks and the like.

In addition, RCU provides the following primitives that check lockdep's

state:

state::

	rcu_read_lock_held() for normal RCU.

	rcu_read_lock_bh_held() for RCU-bh.

The rcu_dereference_check() check expression can be any boolean

expression, but would normally include a lockdep expression.  However,

any boolean expression can be used.  For a moderately ornate example,

consider the following:

consider the following::

	file = rcu_dereference_check(fdt->fd[fd],

				     lockdep_is_held(&files->file_lock) ||

any change from taking place, and finally, in case (3) the current task

is the only task accessing the file_struct, again preventing any change

from taking place.  If the above statement was invoked only from updater

code, it could instead be written as follows:

code, it could instead be written as follows::

	file = rcu_dereference_protected(fdt->fd[fd],

					 lockdep_is_held(&files->file_lock) ||

For example, the workqueue for_each_pwq() macro is intended to be used

either within an RCU read-side critical section or with wq->mutex held.

It is thus implemented as follows:

It is thus implemented as follows::

	#define for_each_pwq(pwq, wq)

		list_for_each_entry_rcu((pwq), &(wq)->pwqs, pwqs_node,