linux-stable.git/Documentation/RCU/Design, branch v5.0

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

doc: rcu: Better clarify the rcu_segcblist ->len field

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

An important note under the rcu_segcblist description could use a more
detailed description. Especially explanation of the scenario where the
->head field may be temporarily NULL making it not wise to rely on it
to determine if callbacks are associated with the rcu_segcblist.

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

doc: rcu: Update Data-Structures for RCU flavor consolidation

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

This patch updates all Data-Structures document figures and text and
removes some unwanted figures, to reflect the recent work Paul has been
doing with consolidating all flavors of RCU.

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

doc: Remove rcu_dynticks from Data-Structures

2018-11-12T16:49:05+00:00

rcu_dynticks was folded into rcu_data structure. Update the data
structures RCU document accordingly.

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

doc: Update information about resched_cpu

2018-11-12T16:48:31+00:00

Since commit fced9c8cfe6b ("rcu: Avoid resched_cpu() when rescheduling
the current CPU"), resched_cpu is not directly called from
sync_sched_exp_handler. Update the documentation about the same.

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

doc: Clarify RCU data-structure comment about rcu_tree fanout

2018-11-09T05:44:41+00:00

RCU Data-Structures document describes a trick to test RCU with small
number of CPUs but with a taller tree. It wasn't immediately clear how
the document arrived at 16 CPUs which also requires setting the
FANOUT_LEAF to 2 instead of the default of 16.  This commit therefore
provides the needed clarification.

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