On Tue, Jun 22, 2021 at 03:55:25PM +0200, Toke Høiland-Jørgensen wrote:
> Toke Høiland-Jørgensen <toke@xxxxxxxxxx> writes:
>
> >> It would also be great if this scenario in general could be placed
> >> under the Documentation/RCU/whatisRCU.rst as an example, so we could
> >> refer to the official doc on this, too, if Paul is good with this.
> >
> > I'll take a look and see if I can find a way to fit it in there...
>
> OK, I poked around in Documentation/RCU and decided that the most
> natural place to put this was in checklist.rst which already talks about
> local_bh_disable(), but a bit differently. Fixing that up to correspond
> to what we've been discussing in this thread, and adding a mention of
> XDP as a usage example, results in the patch below.
>
> Paul, WDYT?
I think that my original paragraph needed to have been updated back
when v4.20 came out. And again when RCU Tasks Trace came out. ;-)
So I did that updating, then approximated your patch on top of it,
as shown below. Does this work for you?
Thanx, Paul
------------------------------------------------------------------------
commit c6ef58907d22f4f327f1e9a637b50a5899aac450
Author: Toke Høiland-Jørgensen <toke@xxxxxxxxxx>
Date: Tue Jun 22 11:54:34 2021 -0700
doc: Give XDP as example of non-obvious RCU reader/updater pairing
This commit gives an example of non-obvious RCU reader/updater pairing
in the guise of the XDP feature in networking, which calls BPF programs
from network-driver NAPI (softirq) context.
Signed-off-by: Toke Høiland-Jørgensen <toke@xxxxxxxxxx>
Signed-off-by: Paul E. McKenney <paulmck@xxxxxxxxxx>
diff --git a/Documentation/RCU/checklist.rst b/Documentation/RCU/checklist.rst
index 4df78f8bd700..f4545b7c9a63 100644
--- a/Documentation/RCU/checklist.rst
+++ b/Documentation/RCU/checklist.rst
@@ -236,8 +236,15 @@ over a rather long period of time, but improvements are always welcome!
Mixing things up will result in confusion and broken kernels, and
has even resulted in an exploitable security issue. Therefore,
- when using non-obvious pairs of primitives, commenting is of
- course a must.
+ when using non-obvious pairs of primitives, commenting is
+ of course a must. One example of non-obvious pairing is
+ the XDP feature in networking, which calls BPF programs from
+ network-driver NAPI (softirq) context. BPF relies heavily on RCU
+ protection for its data structures, but because the BPF program
+ invocation happens entirely within a single local_bh_disable()
+ section in a NAPI poll cycle, this usage is safe. The reason
+ that this usage is safe is that readers can use anything that
+ disables BH when updaters use call_rcu() or synchronize_rcu().
8. Although synchronize_rcu() is slower than is call_rcu(), it
usually results in simpler code. So, unless update performance is
