Skip to contentSkip to conversation

bpftool: Consume ring buffer maps with event_pipe

PATCH Superseded Tianyi Chen 2 participants 5 messages Sep 19 – Sep 21

Subsystems (4)

v4 of 5 Superseded Latest is v5 →

lore
Share & tools
lore
#0 lore raw

v4 cover bpftool: Consume ring buffer maps with event_pipe

Extend map event_pipe to consume BPF ring buffer records, with plain and JSON output and focused tests for records, shutdown and invalid arguments.

Changes in v4, addressing Quentin's review:
- Accept multiple map types in the completion helpers.
- Preserve the normal diagnostic for unknown arguments.
- Use p_err() for errors and drop the redundant ownership comment.
- Reuse detect_bpftool_path() and check the exec-error write result.
- Add a JSON regression for unknown arguments.

Rebased on current bpf-next. All 18 ringbuf subtests pass in an x86-64 VM, including the existing perf event array path. Completion matching and plain/JSON polling-error output were also checked.

v3: https://lore.kernel.org/r/[email protected]

Tianyi Chen (2):
bpftool: Read ring buffer maps with event_pipe selftests/bpf: Cover bpftool ring buffer event_pipe

 .../bpf/bpftool/Documentation/bpftool-map.rst |  14 +-
 tools/bpf/bpftool/bash-completion/bpftool     |  53 ++-
 tools/bpf/bpftool/map_perf_ring.c             |  87 +++-
 tools/testing/selftests/bpf/bpftool_helpers.c |   2 +-
 tools/testing/selftests/bpf/bpftool_helpers.h |   1 +
 .../bpf/prog_tests/bpftool_ringbuf.c          | 417 ++++++++++++++++++
 .../selftests/bpf/progs/bpftool_ringbuf.c     |  47 ++
 7 files changed, 574 insertions(+), 47 deletions(-)
 create mode 100644 tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c
 create mode 100644 tools/testing/selftests/bpf/progs/bpftool_ringbuf.c

base-commit: 559b90b855ce535572e743ed79a59f728ac30fb0

Signature · 1 line
2.55.0
#1 lore raw

PATCH v4 1/2 bpftool: Read ring buffer maps with event_pipe

map event_pipe only accepts perf event arrays, leaving no built-in way to inspect records produced through the BPF ring buffer API. Extend it to consume queued and live BPF_MAP_TYPE_RINGBUF records in plain or JSON output, retaining the existing perf event array path.

Ring buffers have a shared consumer position and no implicit CPU or timestamp. Document that this command consumes records rather than observing them passively, and reject perf-only CPU/index selectors.

A producer can keep ring_buffer__poll() busy after a stop signal, so return -EINTR from the record callback when stopping. Keep stdio out of the shared signal handler and preserve callback output errors.

Assisted-by LLM
---
 .../bpf/bpftool/Documentation/bpftool-map.rst | 14 ++-
 tools/bpf/bpftool/bash-completion/bpftool     | 53 ++++++-----
 tools/bpf/bpftool/map_perf_ring.c             | 87 ++++++++++++++-----
 3 files changed, 108 insertions(+), 46 deletions(-)
tools/bpf/bpftool/Documentation/bpftool-map.rst +13 -1
index 5daf3de5c744..e4ed7e701c9e 100644
@@ -120,7 +120,8 @@ bpftool map pin     *MAP*  *FILE*
     character ('.'), which is reserved for future extensions of *bpffs*.
 
 bpftool map event_pipe *MAP* [cpu *N* index *M*]
-    Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** map.
+    Read events from a **BPF_MAP_TYPE_PERF_EVENT_ARRAY** or
+    **BPF_MAP_TYPE_RINGBUF** map.
 
     Install perf rings into a perf event array map and dump output of any
     **bpf_perf_event_output**\ () call in the kernel. By default read the
@@ -134,6 +135,17 @@ bpftool map event_pipe *MAP* [cpu *N* index *M*]
     existing ring.  Any other application will stop receiving events if it
     installed its rings earlier.
 
+    For a ring buffer map, consume records submitted by BPF programs, including
+    records already queued before the command starts. **cpu** and **index**
+    are not supported. Each record is printed in full, including embedded zero
+    bytes. Plain output reports the record size followed by hexadecimal
+    bytes; JSON output contains **size** and **data** fields, with **data** an
+    array of byte values. Ring buffer records have no implicit CPU or timestamp.
+
+    Consuming a ring buffer advances its shared consumer position, so this
+    command must not run alongside another consumer of the same map.
+    **BPF_MAP_TYPE_USER_RINGBUF** maps are not supported.
+
 bpftool map peek  *MAP*
     Peek next value in the queue or stack.
 
tools/bpf/bpftool/bash-completion/bpftool +29 -24

122 lines not on this page · raw message

tools/bpf/bpftool/map_perf_ring.c +66 -21

144 lines not on this page · raw message

Signature · 1 line
2.55.0
#2 lore raw

Re: [PATCH bpf-next v4 1/2] bpftool: Read ring buffer maps with event_pipe

The event_pipe completion now offers ring buffer maps for the 'id' and 'name' cases, but the fallthrough '*' branch still suggests 'cpu index' via _bpftool_once_attr. Can this cause tab-completion…
Quoted 4 lines
tools/bpf/bpftool/bash-completion/bpftool +0 -0
index 75cbcb512ebae..1396083c4e67d 100644

[ ... ]

Quoted 15 lines
tools/bpf/bpftool/bash-completion/bpftool +2 -2
@@ -878,11 +883,11 @@ _bpftool()
                         return 0
                         ;;
                     id)
-                        _bpftool_get_map_ids_for_type perf_event_array
+                        _bpftool_get_map_ids_for_types perf_event_array ringbuf
                         return 0
                         ;;
                     name)
-                        _bpftool_get_map_names_for_type perf_event_array
+                        _bpftool_get_map_names_for_types perf_event_array ringbuf
                         return 0
                         ;;
                     cpu)
                         return 0
Quoted 8 lines
                         ;;
                     index)
                         return 0
                         ;;
                     *)
                         _bpftool_once_attr 'cpu index'
                         return 0
                         ;;

The event_pipe completion now offers ring buffer maps for the 'id' and 'name' cases, but the fallthrough '*' branch still suggests 'cpu index' via _bpftool_once_attr. Can this cause tab-completion to offer cpu/index keywords after a ring buffer map identifier?

Looking at do_event_pipe() in map_perf_ring.c:

    if (map_info.type == BPF_MAP_TYPE_RINGBUF && argc &&
        (is_prefix(*argv, "cpu") || is_prefix(*argv, "index"))) {
            p_err("ring buffer maps do not support cpu or index arguments");

the command explicitly rejects these selectors for ring buffers, and the follow-up selftest (commit e12bcaa3a4d8e, subtests reject_cpu and reject_index) verifies that error. The file already uses _bpftool_map_guess_map_type() to make completion suggestions type-dependent for other commands (lookup, update, push, enqueue), so the mechanism to conditionally suppress cpu/index exists but appears not to be applied here.

---
AI reviewed your patch. Please fix the bug or email reply why it's not a bug.
See: https://github.com/kernel-patches/vmtest/blob/master/ci/claude/README.md

CI run summary: https://github.com/kernel-patches/bpf/actions/runs/35440280049

#3 lore raw

Re: [PATCH bpf-next v4 1/2] bpftool: Read ring buffer maps with event_pipe

Quoted 2 lines

via _bpftool_once_attr. Can this cause tab-completion to offer cpu/index keywords after a ring buffer map identifier?

Yes. Fixed in v5 by teaching _bpftool_map_guess_map_type() about event_pipe and suppressing these selectors for ringbuf maps. Perf event arrays retain cpu/index completion; unresolved map types keep the existing fallback.

Sent as a new thread, with this review linked in the cover letter:
https://lore.kernel.org/r/[email protected]

Checked id/name/pinned completion against live maps, and all 18 ringbuf subtests pass with the rebuilt bpftool.

Thanks,
Tianyi

#4 lore raw

PATCH v4 2/2 selftests/bpf: Cover bpftool ring buffer event_pipe

In reply to Tianyi Chen

Produce known ring buffer records and check complete plain, JSON and pretty JSON output. Exercise ID and pinned map selection, SIGINT and SIGTERM shutdown, empty streams and invalid map types or selectors.

Also produce a perf event sample and check its existing header and raw payload output. Use a payload whose size plus the raw sample length field is aligned to eight bytes so the expected bytes exclude implicit perf padding.

Assisted-by LLM
---
 tools/testing/selftests/bpf/bpftool_helpers.c |   2 +-
 tools/testing/selftests/bpf/bpftool_helpers.h |   1 +
 .../bpf/prog_tests/bpftool_ringbuf.c          | 417 ++++++++++++++++++
 .../selftests/bpf/progs/bpftool_ringbuf.c     |  47 ++
 4 files changed, 466 insertions(+), 1 deletion(-)
 create mode 100644 tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c
 create mode 100644 tools/testing/selftests/bpf/progs/bpftool_ringbuf.c
tools/testing/selftests/bpf/bpftool_helpers.c +1 -1
index c49fdd90eb03..9380b24bbf52 100644
@@ -11,7 +11,7 @@
 
 #define BPFTOOL_DEFAULT_PATH		"tools/sbin/bpftool"
 
-static int detect_bpftool_path(char *buffer, size_t size)
+int detect_bpftool_path(char *buffer, size_t size)
 {
 	char tmp[PATH_MAX];
 	const char *env_path;
tools/testing/selftests/bpf/bpftool_helpers.h +1 -0
index dec1ba201410..17e3be8e7073 100644
@@ -7,5 +7,6 @@
 
 #define MAX_BPFTOOL_CMD_LEN	(256)
 
+int detect_bpftool_path(char *buffer, size_t size);
 int run_bpftool_command(char *args);
 int get_bpftool_command_output(char *args, char *output_buf, size_t output_max_len);
tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c new file +417 -0

417 lines not on this page · raw message

tools/testing/selftests/bpf/progs/bpftool_ringbuf.c new file +47 -0

47 lines not on this page · raw message

Signature · 1 line
2.55.0