ACPI: button: Add DMI quirk for Asus T200TA

[linux.git] / Documentation / RCU / checklist.txt

diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt
index 6f469864d9f59aa5a4d2456f01d55409d58d32c6..e98ff261a438bd4e0858a943fc469437599cc284 100644 (file)
--- a/Documentation/RCU/checklist.txt
+++ b/Documentation/RCU/checklist.txt
@@ -182,16 +182,13 @@ over a rather long period of time, but improvements are always welcome!
                when publicizing a pointer to a structure that can
                be traversed by an RCU read-side critical section.
 
                when publicizing a pointer to a structure that can
                be traversed by an RCU read-side critical section.
 

-5.     If call_rcu(), or a related primitive such as call_rcu_bh(),
-       call_rcu_sched(), or call_srcu() is used, the callback function
-       will be called from softirq context.  In particular, it cannot
-       block.
+5.     If call_rcu() or call_srcu() is used, the callback function will
+       be called from softirq context.  In particular, it cannot block.

 
 

-6.     Since synchronize_rcu() can block, it cannot be called from
-       any sort of irq context.  The same rule applies for
-       synchronize_rcu_bh(), synchronize_sched(), synchronize_srcu(),
-       synchronize_rcu_expedited(), synchronize_rcu_bh_expedited(),
-       synchronize_sched_expedite(), and synchronize_srcu_expedited().
+6.     Since synchronize_rcu() can block, it cannot be called
+       from any sort of irq context.  The same rule applies
+       for synchronize_srcu(), synchronize_rcu_expedited(), and
+       synchronize_srcu_expedited().

 
        The expedited forms of these primitives have the same semantics
        as the non-expedited forms, but expediting is both expensive and
 
        The expedited forms of these primitives have the same semantics
        as the non-expedited forms, but expediting is both expensive and


@@ -212,20 +209,20 @@ over a rather long period of time, but improvements are always welcome!
        of the system, especially to real-time workloads running on
        the rest of the system.
 
        of the system, especially to real-time workloads running on
        the rest of the system.
 

-7.     If the updater uses call_rcu() or synchronize_rcu(), then the
-       corresponding readers must use rcu_read_lock() and
-       rcu_read_unlock().  If the updater uses call_rcu_bh() or
-       synchronize_rcu_bh(), then the corresponding readers must
-       use rcu_read_lock_bh() and rcu_read_unlock_bh().  If the
-       updater uses call_rcu_sched() or synchronize_sched(), then
-       the corresponding readers must disable preemption, possibly
-       by calling rcu_read_lock_sched() and rcu_read_unlock_sched().
-       If the updater uses synchronize_srcu() or call_srcu(), then
-       the corresponding readers must use srcu_read_lock() and
+7.     As of v4.20, a given kernel implements only one RCU flavor,
+       which is RCU-sched for PREEMPT=n and RCU-preempt for PREEMPT=y.
+       If the updater uses call_rcu() or synchronize_rcu(),
+       then the corresponding readers my use rcu_read_lock() and
+       rcu_read_unlock(), rcu_read_lock_bh() and rcu_read_unlock_bh(),
+       or any pair of primitives that disables and re-enables preemption,
+       for example, rcu_read_lock_sched() and rcu_read_unlock_sched().
+       If the updater uses synchronize_srcu() or call_srcu(),
+       then the corresponding readers must use srcu_read_lock() and

        srcu_read_unlock(), and with the same srcu_struct.  The rules for
        the expedited primitives are the same as for their non-expedited
        counterparts.  Mixing things up will result in confusion and
        srcu_read_unlock(), and with the same srcu_struct.  The rules for
        the expedited primitives are the same as for their non-expedited
        counterparts.  Mixing things up will result in confusion and

-       broken kernels.
+       broken kernels, and has even resulted in an exploitable security
+       issue.

 
        One exception to this rule: rcu_read_lock() and rcu_read_unlock()
        may be substituted for rcu_read_lock_bh() and rcu_read_unlock_bh()
 
        One exception to this rule: rcu_read_lock() and rcu_read_unlock()
        may be substituted for rcu_read_lock_bh() and rcu_read_unlock_bh()


@@ -288,8 +285,7 @@ over a rather long period of time, but improvements are always welcome!
        d.      Periodically invoke synchronize_rcu(), permitting a limited
                number of updates per grace period.
 
        d.      Periodically invoke synchronize_rcu(), permitting a limited
                number of updates per grace period.
 

-       The same cautions apply to call_rcu_bh(), call_rcu_sched(),
-       call_srcu(), and kfree_rcu().
+       The same cautions apply to call_srcu() and kfree_rcu().

 
        Note that although these primitives do take action to avoid memory
        exhaustion when any given CPU has too many callbacks, a determined
 
        Note that although these primitives do take action to avoid memory
        exhaustion when any given CPU has too many callbacks, a determined


@@ -322,7 +318,7 @@ over a rather long period of time, but improvements are always welcome!
 
 11.    Any lock acquired by an RCU callback must be acquired elsewhere
        with softirq disabled, e.g., via spin_lock_irqsave(),
 
 11.    Any lock acquired by an RCU callback must be acquired elsewhere
        with softirq disabled, e.g., via spin_lock_irqsave(),

-       spin_lock_bh(), etc.  Failing to disable irq on a given
+       spin_lock_bh(), etc.  Failing to disable softirq on a given

        acquisition of that lock will result in deadlock as soon as
        the RCU softirq handler happens to run your RCU callback while
        interrupting that acquisition's critical section.
        acquisition of that lock will result in deadlock as soon as
        the RCU softirq handler happens to run your RCU callback while
        interrupting that acquisition's critical section.


@@ -335,13 +331,16 @@ over a rather long period of time, but improvements are always welcome!
        must use whatever locking or other synchronization is required
        to safely access and/or modify that data structure.
 
        must use whatever locking or other synchronization is required
        to safely access and/or modify that data structure.
 

-       RCU callbacks are -usually- executed on the same CPU that executed
-       the corresponding call_rcu(), call_rcu_bh(), or call_rcu_sched(),
-       but are by -no- means guaranteed to be.  For example, if a given
-       CPU goes offline while having an RCU callback pending, then that
-       RCU callback will execute on some surviving CPU.  (If this was
-       not the case, a self-spawning RCU callback would prevent the
-       victim CPU from ever going offline.)
+       Do not assume that RCU callbacks will be executed on the same
+       CPU that executed the corresponding call_rcu() or call_srcu().
+       For example, if a given CPU goes offline while having an RCU
+       callback pending, then that RCU callback will execute on some
+       surviving CPU.  (If this was not the case, a self-spawning RCU
+       callback would prevent the victim CPU from ever going offline.)
+       Furthermore, CPUs designated by rcu_nocbs= might well -always-
+       have their RCU callbacks executed on some other CPUs, in fact,
+       for some  real-time workloads, this is the whole point of using
+       the rcu_nocbs= kernel boot parameter.

 
 13.    Unlike other forms of RCU, it -is- permissible to block in an
        SRCU read-side critical section (demarked by srcu_read_lock()
 
 13.    Unlike other forms of RCU, it -is- permissible to block in an
        SRCU read-side critical section (demarked by srcu_read_lock()


@@ -381,11 +380,11 @@ over a rather long period of time, but improvements are always welcome!
 
        SRCU's expedited primitive (synchronize_srcu_expedited())
        never sends IPIs to other CPUs, so it is easier on
 
        SRCU's expedited primitive (synchronize_srcu_expedited())
        never sends IPIs to other CPUs, so it is easier on

-       real-time workloads than is synchronize_rcu_expedited(),
-       synchronize_rcu_bh_expedited() or synchronize_sched_expedited().
+       real-time workloads than is synchronize_rcu_expedited().

 
 

-       Note that rcu_dereference() and rcu_assign_pointer() relate to
-       SRCU just as they do to other forms of RCU.
+       Note that rcu_assign_pointer() relates to SRCU just as it does to
+       other forms of RCU, but instead of rcu_dereference() you should
+       use srcu_dereference() in order to avoid lockdep splats.

 
 14.    The whole point of call_rcu(), synchronize_rcu(), and friends
        is to wait until all pre-existing readers have finished before
 
 14.    The whole point of call_rcu(), synchronize_rcu(), and friends
        is to wait until all pre-existing readers have finished before


@@ -405,6 +404,9 @@ over a rather long period of time, but improvements are always welcome!
        read-side critical sections.  It is the responsibility of the
        RCU update-side primitives to deal with this.
 
        read-side critical sections.  It is the responsibility of the
        RCU update-side primitives to deal with this.
 

+       For SRCU readers, you can use smp_mb__after_srcu_read_unlock()
+       immediately after an srcu_read_unlock() to get a full barrier.
+

 16.    Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the
        __rcu sparse checks to validate your RCU code.  These can help
        find problems as follows:
 16.    Use CONFIG_PROVE_LOCKING, CONFIG_DEBUG_OBJECTS_RCU_HEAD, and the
        __rcu sparse checks to validate your RCU code.  These can help
        find problems as follows:


@@ -428,22 +430,19 @@ over a rather long period of time, but improvements are always welcome!
        These debugging aids can help you find problems that are
        otherwise extremely difficult to spot.
 
        These debugging aids can help you find problems that are
        otherwise extremely difficult to spot.
 

-17.    If you register a callback using call_rcu(), call_rcu_bh(),
-       call_rcu_sched(), or call_srcu(), and pass in a function defined
-       within a loadable module, then it in necessary to wait for
-       all pending callbacks to be invoked after the last invocation
-       and before unloading that module.  Note that it is absolutely
-       -not- sufficient to wait for a grace period!  The current (say)
-       synchronize_rcu() implementation waits only for all previous
-       callbacks registered on the CPU that synchronize_rcu() is running
-       on, but it is -not- guaranteed to wait for callbacks registered
-       on other CPUs.
+17.    If you register a callback using call_rcu() or call_srcu(), and
+       pass in a function defined within a loadable module, then it in
+       necessary to wait for all pending callbacks to be invoked after
+       the last invocation and before unloading that module.  Note that
+       it is absolutely -not- sufficient to wait for a grace period!
+       The current (say) synchronize_rcu() implementation is -not-
+       guaranteed to wait for callbacks registered on other CPUs.
+       Or even on the current CPU if that CPU recently went offline
+       and came back online.

 
        You instead need to use one of the barrier functions:
 
        o       call_rcu() -> rcu_barrier()
 
        You instead need to use one of the barrier functions:
 
        o       call_rcu() -> rcu_barrier()

-       o       call_rcu_bh() -> rcu_barrier()
-       o       call_rcu_sched() -> rcu_barrier()

        o       call_srcu() -> srcu_barrier()
 
        However, these barrier functions are absolutely -not- guaranteed
        o       call_srcu() -> srcu_barrier()
 
        However, these barrier functions are absolutely -not- guaranteed