Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

docs: Add documentation for rude and trace RCU flavors

This commit belatedly adds documentation of Tasks Rude RCU and Tasks
Trace RCU to RCU's requirements document.

Tested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Paul E. McKenney <paulmck@kernel.org>

+32
+32
Documentation/RCU/Design/Requirements/Requirements.rst
··· 2654 2654 three APIs are therefore implemented by separate functions that check 2655 2655 for voluntary context switches. 2656 2656 2657 + Tasks Rude RCU 2658 + ~~~~~~~~~~~~~~ 2659 + 2660 + Some forms of tracing need to wait for all preemption-disabled regions 2661 + of code running on any online CPU, including those executed when RCU is 2662 + not watching. This means that synchronize_rcu() is insufficient, and 2663 + Tasks Rude RCU must be used instead. This flavor of RCU does its work by 2664 + forcing a workqueue to be scheduled on each online CPU, hence the "Rude" 2665 + moniker. And this operation is considered to be quite rude by real-time 2666 + workloads that don't want their ``nohz_full`` CPUs receiving IPIs and 2667 + by battery-powered systems that don't want their idle CPUs to be awakened. 2668 + 2669 + The tasks-rude-RCU API is also reader-marking-free and thus quite compact, 2670 + consisting of call_rcu_tasks_rude(), synchronize_rcu_tasks_rude(), 2671 + and rcu_barrier_tasks_rude(). 2672 + 2673 + Tasks Trace RCU 2674 + ~~~~~~~~~~~~~~~ 2675 + 2676 + Some forms of tracing need to sleep in readers, but cannot tolerate 2677 + SRCU's read-side overhead, which includes a full memory barrier in both 2678 + srcu_read_lock() and srcu_read_unlock(). This need is handled by a 2679 + Tasks Trace RCU that uses scheduler locking and IPIs to synchronize with 2680 + readers. Real-time systems that cannot tolerate IPIs may build their 2681 + kernels with ``CONFIG_TASKS_TRACE_RCU_READ_MB=y``, which avoids the IPIs at 2682 + the expense of adding full memory barriers to the read-side primitives. 2683 + 2684 + The tasks-trace-RCU API is also reasonably compact, 2685 + consisting of rcu_read_lock_trace(), rcu_read_unlock_trace(), 2686 + rcu_read_lock_trace_held(), call_rcu_tasks_trace(), 2687 + synchronize_rcu_tasks_trace(), and rcu_barrier_tasks_trace(). 2688 + 2657 2689 Possible Future Changes 2658 2690 ----------------------- 2659 2691