libbpf: Clarify flags in ringbuf helpers

In 'bpf_ringbuf_reserve()' we require the flag to '0' at the moment.

For 'bpf_ringbuf_{discard,submit,output}' a flag of '0' might send a
notification to the process if needed.

Signed-off-by: Pedro Tammela <pctammela@mojatatu.com>
Signed-off-by: Andrii Nakryiko <andrii@kernel.org>
Link: https://lore.kernel.org/bpf/20210412192434.944343-1-pctammela@mojatatu.com

diff --git a/include/uapi/linux/bpf.h b/include/uapi/linux/bpf.h
index e1ee1be..85c924b 100644 (file)
--- a/include/uapi/linux/bpf.h
+++ b/include/uapi/linux/bpf.h
@@ -4082,12 +4082,20 @@ union bpf_attr {
  *             of new data availability is sent.
  *             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
+ *             of new data availability is sent.
+ *
+ *             An adaptive notification is a notification sent whenever the user-space
+ *             process has caught up and consumed all available payloads. In case the user-space
+ *             process is still processing a previous payload, then no notification is needed
+ *             as it will process the newly added payload automatically.
  *     Return
  *             0 on success, or a negative error in case of failure.
  *
  * void *bpf_ringbuf_reserve(void *ringbuf, u64 size, u64 flags)
  *     Description
  *             Reserve *size* bytes of payload in a ring buffer *ringbuf*.
+ *             *flags* must be 0.
  *     Return
  *             Valid pointer with *size* bytes of memory available; NULL,
  *             otherwise.
@@ -4099,6 +4107,10 @@ union bpf_attr {
  *             of new data availability is sent.
  *             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
+ *             of new data availability is sent.
+ *
+ *             See 'bpf_ringbuf_output()' for the definition of adaptive notification.
  *     Return
  *             Nothing. Always succeeds.
  *
@@ -4109,6 +4121,10 @@ union bpf_attr {
  *             of new data availability is sent.
  *             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
+ *             of new data availability is sent.
+ *
+ *             See 'bpf_ringbuf_output()' for the definition of adaptive notification.
  *     Return
  *             Nothing. Always succeeds.
  *

diff --git a/tools/include/uapi/linux/bpf.h b/tools/include/uapi/linux/bpf.h
index e1ee1be..85c924b 100644 (file)
--- a/tools/include/uapi/linux/bpf.h
+++ b/tools/include/uapi/linux/bpf.h
@@ -4082,12 +4082,20 @@ union bpf_attr {
  *             of new data availability is sent.
  *             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
+ *             of new data availability is sent.
+ *
+ *             An adaptive notification is a notification sent whenever the user-space
+ *             process has caught up and consumed all available payloads. In case the user-space
+ *             process is still processing a previous payload, then no notification is needed
+ *             as it will process the newly added payload automatically.
  *     Return
  *             0 on success, or a negative error in case of failure.
  *
  * void *bpf_ringbuf_reserve(void *ringbuf, u64 size, u64 flags)
  *     Description
  *             Reserve *size* bytes of payload in a ring buffer *ringbuf*.
+ *             *flags* must be 0.
  *     Return
  *             Valid pointer with *size* bytes of memory available; NULL,
  *             otherwise.
@@ -4099,6 +4107,10 @@ union bpf_attr {
  *             of new data availability is sent.
  *             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
+ *             of new data availability is sent.
+ *
+ *             See 'bpf_ringbuf_output()' for the definition of adaptive notification.
  *     Return
  *             Nothing. Always succeeds.
  *
@@ -4109,6 +4121,10 @@ union bpf_attr {
  *             of new data availability is sent.
  *             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
+ *             of new data availability is sent.
+ *
+ *             See 'bpf_ringbuf_output()' for the definition of adaptive notification.
  *     Return
  *             Nothing. Always succeeds.
  *