Orange Pi5 kernel

^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  1) .. _rcu_doc:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  2) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  3) RCU Concepts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  4) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  5) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  6) The basic idea behind RCU (read-copy update) is to split destructive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  7) operations into two parts, one that prevents anyone from seeing the data
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  8) item being destroyed, and one that actually carries out the destruction.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300  9) A "grace period" must elapse between the two parts, and this grace period
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) must be long enough that any readers accessing the item being deleted have
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) since dropped their references.  For example, an RCU-protected deletion
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) from a linked list would first remove the item from the list, wait for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) a grace period to elapse, then free the element.  See the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) :ref:`Documentation/RCU/listRCU.rst <list_rcu_doc>` for more information on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) using RCU with linked lists.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) Frequently Asked Questions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) - Why would anyone want to use RCU?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)   The advantage of RCU's two-part approach is that RCU readers need
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)   not acquire any locks, perform any atomic instructions, write to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)   shared memory, or (on CPUs other than Alpha) execute any memory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)   barriers.  The fact that these operations are quite expensive
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)   on modern CPUs is what gives RCU its performance advantages
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27)   in read-mostly situations.  The fact that RCU readers need not
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)   acquire locks can also greatly simplify deadlock-avoidance code.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) - How can the updater tell when a grace period has completed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)   if the RCU readers give no indication when they are done?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)   Just as with spinlocks, RCU readers are not permitted to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)   block, switch to user-mode execution, or enter the idle loop.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)   Therefore, as soon as a CPU is seen passing through any of these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)   three states, we know that that CPU has exited any previous RCU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)   read-side critical sections.  So, if we remove an item from a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)   linked list, and then wait until all CPUs have switched context,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)   executed in user mode, or executed in the idle loop, we can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)   safely free up that item.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)   Preemptible variants of RCU (CONFIG_PREEMPT_RCU) get the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)   same effect, but require that the readers manipulate CPU-local
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)   counters.  These counters allow limited types of blocking within
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)   RCU read-side critical sections.  SRCU also uses CPU-local
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)   counters, and permits general blocking within RCU read-side
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)   critical sections.  These variants of RCU detect grace periods
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)   by sampling these counters.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) - If I am running on a uniprocessor kernel, which can only do one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)   thing at a time, why should I wait for a grace period?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)   See :ref:`Documentation/RCU/UP.rst <up_doc>` for more information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) - How can I see where RCU is currently used in the Linux kernel?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)   Search for "rcu_read_lock", "rcu_read_unlock", "call_rcu",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)   "rcu_read_lock_bh", "rcu_read_unlock_bh", "srcu_read_lock",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)   "srcu_read_unlock", "synchronize_rcu", "synchronize_net",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)   "synchronize_srcu", and the other RCU primitives.  Or grab one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)   of the cscope databases from:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)   (http://www.rdrop.com/users/paulmck/RCU/linuxusage/rculocktab.html).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) - What guidelines should I follow when writing code that uses RCU?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67)   See the checklist.txt file in this directory.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) - Why the name "RCU"?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71)   "RCU" stands for "read-copy update".
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)   :ref:`Documentation/RCU/listRCU.rst <list_rcu_doc>` has more information on where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)   this name came from, search for "read-copy update" to find it.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) - I hear that RCU is patented?  What is with that?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)   Yes, it is.  There are several known patents related to RCU,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)   search for the string "Patent" in Documentation/RCU/RTFP.txt to find them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79)   Of these, one was allowed to lapse by the assignee, and the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)   others have been contributed to the Linux kernel under GPL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)   There are now also LGPL implementations of user-level RCU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)   available (https://liburcu.org/).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) - I hear that RCU needs work in order to support realtime kernels?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)   Realtime-friendly RCU can be enabled via the CONFIG_PREEMPT_RCU
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87)   kernel configuration parameter.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) - Where can I find more information on RCU?
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) 
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)   See the Documentation/RCU/RTFP.txt file.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)   Or point your browser at (http://www.rdrop.com/users/paulmck/RCU/).