bpf: Clarify BPF_RB_NO_WAKEUP behavior for bpf_ringbuf_discard()

Clarify bpf_ringbuf_discard() documentation for BPF_RB_NO_WAKEUP.

Discarded ring buffer records are still left in the ring buffer and are
only skipped when user space consumes them. This can matter when
BPF_RB_NO_WAKEUP is used: a later submit relying on adaptive wakeup
might not wake the consumer, because the discarded record still needs to
be consumed first.

Scenario:

epoll_wait(rb_fd);                     // blocks

rec = bpf_ringbuf_reserve(&rb, ...);
bpf_ringbuf_discard(rec, BPF_RB_NO_WAKEUP);

rec = bpf_ringbuf_reserve(&rb, ...);
bpf_ringbuf_submit(rec, 0);           // valid record, but no wakeup

Document this in bpf_ringbuf_discard() to make the interaction between
discarded records, user-space consumption, and adaptive wakeups explicit.

Reported-by: Shmulik Ladkani <shmulik.ladkani@gmail.com>
Signed-off-by: Eyal Birger <eyal.birger@gmail.com>
Signed-off-by: Andrii Nakryiko <andrii@kernel.org>
Link: https://lore.kernel.org/bpf/20260331130612.3762433-1-eyal.birger@gmail.com
----

v2: adapt wording per feedback from Andrii.

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index c8d400b7680a81236f1b352b38fef4bdc099cfb5..552bc5d9afbd1604286b5eafe8fb5fb4e31d163b 100644 (file)
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -4645,7 +4645,9 @@ union bpf_attr {
  *     Description
  *             Discard reserved ring buffer sample, pointed to by *data*.
  *             If **BPF_RB_NO_WAKEUP** is specified in *flags*, no notification
- *             of new data availability is sent.
+ *             of new data availability is sent. Discarded records remain in
+ *             the ring buffer until consumed by user space, so a later submit
+ *             using adaptive wakeup might not wake up the consumer.
  *             If **BPF_RB_FORCE_WAKEUP** is specified in *flags*, notification
  *             of new data availability is sent unconditionally.
  *             If **0** is specified in *flags*, an adaptive notification

diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h
index 5e38b4887de6ae59fe0a62511757be2d1019eded..677be9a47347686e98eece291f46031f20512a27 100644 (file)
--- a/tools/include/uapi/linux/bpf.h
+++ b/tools/include/uapi/linux/bpf.h
@@ -4645,7 +4645,9 @@ union bpf_attr {
  *     Description
  *             Discard reserved ring buffer sample, pointed to by *data*.
  *             If **BPF_RB_NO_WAKEUP** is specified in *flags*, no notification
- *             of new data availability is sent.
+ *             of new data availability is sent. Discarded records remain in
+ *             the ring buffer until consumed by user space, so a later submit
+ *             using adaptive wakeup might not wake up the consumer.
  *             If **BPF_RB_FORCE_WAKEUP** is specified in *flags*, notification
  *             of new data availability is sent unconditionally.
  *             If **0** is specified in *flags*, an adaptive notification