Commit c28adacc authored by Frederic Weisbecker's avatar Frederic Weisbecker Committed by Paul E. McKenney
Browse files

rcu/doc: Add a quick quiz to explain further why we need smp_mb__after_unlock_lock() 



Add some missing critical pieces of explanation to understand the need
for full memory barriers throughout the whole grace period state machine,
thanks to Paul's explanations.

Signed-off-by: default avatarFrederic Weisbecker <frederic@kernel.org>
Cc: Neeraj Upadhyay <neeraju@codeaurora.org>
Cc: Joel Fernandes <joel@joelfernandes.org>
Cc: Uladzislau Rezki <urezki@gmail.com>
Cc: Boqun Feng <boqun.feng@gmail.com>
[ paulmck: Adjust code block per Akira Yokosawa. ]
Signed-off-by: default avatarPaul E. McKenney <paulmck@kernel.org>
parent 9984fd7e

Documentation/RCU/Design/Memory-Ordering/Tree-RCU-Memory-Ordering.rst

+29 −0
Original line number Diff line number Diff line
@@ -112,6 +112,35 @@ on PowerPC. 
The ``smp_mb__after_unlock_lock()`` invocations prevent this

``WARN_ON()`` from triggering.



+-----------------------------------------------------------------------+

| **Quick Quiz**:                                                       |

+-----------------------------------------------------------------------+

| But the chain of rcu_node-structure lock acquisitions guarantees      |

| that new readers will see all of the updater's pre-grace-period       |

| accesses and also guarantees that the updater's post-grace-period     |

| accesses will see all of the old reader's accesses.  So why do we     |

| need all of those calls to smp_mb__after_unlock_lock()?               |

+-----------------------------------------------------------------------+

| **Answer**:                                                           |

+-----------------------------------------------------------------------+

| Because we must provide ordering for RCU's polling grace-period       |

| primitives, for example, get_state_synchronize_rcu() and              |

| poll_state_synchronize_rcu().  Consider this code::                   |

|                                                                       |

|  CPU 0                                     CPU 1                      |

|  ----                                      ----                       |

|  WRITE_ONCE(X, 1)                          WRITE_ONCE(Y, 1)           |

|  g = get_state_synchronize_rcu()           smp_mb()                   |

|  while (!poll_state_synchronize_rcu(g))    r1 = READ_ONCE(X)          |

|          continue;                                                    |

|  r0 = READ_ONCE(Y)                                                    |

|                                                                       |

| RCU guarantees that the outcome r0 == 0 && r1 == 0 will not           |

| happen, even if CPU 1 is in an RCU extended quiescent state           |

| (idle or offline) and thus won't interact directly with the RCU       |

| core processing at all.                                               |

+-----------------------------------------------------------------------+



This approach must be extended to include idle CPUs, which need

RCU's grace-period memory ordering guarantee to extend to any

RCU read-side critical sections preceding and following the current