linux.git/Documentation/RCU/Design, branch v5.1

Merge branches 'doc.2019.01.26a', 'fixes.2019.01.26a', 'sil.2019.01.26a', 'spdx.2019.02.09a', 'srcu.2019.01.26a' and 'torture.2019.01.26a' into HEAD

2019-02-09T16:47:52+00:00

doc.2019.01.26a:  Documentation updates.
fixes.2019.01.26a:  Miscellaneous fixes.
sil.2019.01.26a:  Removal of a few more spin_is_locked() instances.
spdx.2019.02.09a:  Add SPDX identifiers to RCU files
srcu.2019.01.26a:  SRCU updates.
torture.2019.01.26a: Torture-test updates.

rcu: Rename rcu_process_callbacks() to rcu_core() for Tree RCU

2019-01-25T23:35:22+00:00

Although the name rcu_process_callbacks() still makes sense for Tiny
RCU, where most of what it does is invoke callbacks, it no longer makes
much sense for Tree RCU, especially given that the actually callback
invocation is relegated to rcu_do_batch(), or, for no-CBs CPUs, to the
rcuo kthreads.  Especially in the latter case, rcu_process_callbacks()
has very little to do with actual callbacks.  A better description of
this function is that it performs RCU's core processing.

This commit therefore changes the name of Tree RCU's rcu_process_callbacks()
function to rcu_core(), which also has the virtue of being consistent with
the existing invoke_rcu_core() function.

While in the area, the header comment is reworked.

Signed-off-by: Paul E. McKenney

rcu: Rename rcu_check_callbacks() to rcu_sched_clock_irq()

2019-01-25T23:35:21+00:00

The name rcu_check_callbacks() arguably made sense back in the early
2000s when RCU was quite a bit simpler than it is today, but it has
become quite misleading, especially with the advent of dyntick-idle
and NO_HZ_FULL.  The rcu_check_callbacks() function is RCU's hook into
the scheduling-clock interrupt, and is now but one of many ways that
callbacks get promoted to invocable state.

This commit therefore changes the name to rcu_sched_clock_irq(),
which is the same number of characters and clearly indicates this
function's relation to the rest of the Linux kernel.  In addition, for
the sake of consistency, rcu_flavor_check_callbacks() is also renamed
to rcu_flavor_sched_clock_irq().

While in the area, the header comments for both functions are reworked.

Signed-off-by: Paul E. McKenney

doc: CPU-hotplug notifiers cannot invoke synchronize_srcu() or srcu_barrier()

2019-01-25T23:34:18+00:00

SRCU's synchronize_srcu() may not be invoked from CPU-hotplug notifiers,
due to the fact that SRCU grace periods make use of timers and the
possibility of timers being temporarily stranded on the outgoing CPU.
This stranding of timers means that timers posted to the outgoing CPU
will not fire until late in the CPU-hotplug process.  The problem is
that if a notifier is waiting on an SRCU grace period, that grace period
is waiting on a timer, and that timer is stranded on the outgoing CPU,
then the notifier will never be awakened, in other words, deadlock has
occurred.  This same situation of course also prohibits srcu_barrier()
from being invoked from CPU-hotplug notifiers.

This commit therefore updates the requirements to include this restriction.

Signed-off-by: Paul E. McKenney

rcu: Determine expedited-GP IPI handler at build time

2019-01-25T23:28:27+00:00

Back when there could be multiple RCU flavors running in the same kernel
at the same time, it was necessary to specify the expedited grace-period
IPI handler at runtime.  Now that there is only one RCU flavor, the
IPI handler can be determined at build time.  There is therefore no
longer any reason for the RCU-preempt and RCU-sched IPI handlers to
have different names, nor is there any reason to pass these handlers in
function arguments and in the data structures enclosing workqueues.

This commit therefore makes all these changes, pushing the specification
of the expedited grace-period IPI handler down to the point of use.

Signed-off-by: Paul E. McKenney

doc: Fix "struction" typo in RCU memory-ordering documentation

2018-11-12T16:56:25+00:00

This commit replaces "struction" with the correct "structure".

Signed-off-by: Joel Fernandes (Google) 
Signed-off-by: Paul E. McKenney

doc: RCU scheduler spinlock rcu_read_unlock() restriction remains

2018-11-12T16:56:25+00:00

Given RCU flavor consolidation, when rcu_read_unlock() is invoked with
interrupts disabled, the reporting of the corresponding quiescent state is
deferred until interrupts are re-enabled.  There was therefore some hope
that this would allow dropping the restriction against holding scheduler
spinlocks across an rcu_read_unlock() without disabling interrupts across
the entire corresponding RCU read-side critical section.  Unfortunately,
the need to quickly provide a quiescent state to expedited grace periods
sometimes requires a call to raise_softirq() during rcu_read_unlock()
execution.  Because raise_softirq() can sometimes acquire the scheduler
spinlocks, the restriction must remain in effect.  This commit therefore
updates the RCU requirements documentation accordingly.

Signed-off-by: Paul E. McKenney

doc: Make listing in RCU perf/scale requirements use rcu_assign_pointer()

2018-11-12T16:56:25+00:00

The code listing under this section has a quick quiz that says line
19 uses rcu_access_pointer, but the code listing itself instead uses
rcu_dereference().  This commit therefore makes the code listing match
the quick quiz.

Signed-off-by: Joel Fernandes (Google) 
Signed-off-by: Paul E. McKenney

doc: Remove obsolete (non-)requirement about disabling preemption

2018-11-12T16:56:25+00:00

The Requirements.html document says "Disabling Preemption Does
Not Block Grace Periods".  However this is no longer true with
the RCU consolidation.  This commit therefore removes the obsolete
(non-)requirement entirely.

Signed-off-by: Joel Fernandes (Google) 
Signed-off-by: Paul E. McKenney

doc: rcu: Update description of gp_seq fields in rcu_data

2018-11-12T16:56:25+00:00

The rcu_state structure doesn't have a gp_seq_needed field. Update the
description under rcu_data accordingly, to reflect this.

Signed-off-by: Joel Fernandes (Google) 
Cc: 
Signed-off-by: Paul E. McKenney