Skip to contentSkip to conversation

bpftool: Consume ring buffer maps with event_pipe

PATCH Applied Tianyi Chen 4 participants 8 messages Sep 21

Subsystems (4)
lore
Share & tools
lore
#0 lore raw

v5 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 v5:
- Suppress cpu/index completion after selecting a ring buffer map by id, name or pinned path, using _bpftool_map_guess_map_type(). Keep the existing suggestions for perf event arrays and unresolved map types.
- Rebase onto current bpf-next. No other changes from v4.

This addresses the v4 review:
https://lore.kernel.org/r/a89e2e325b87c215e0fb6e4a24284922d7656cfc0e2a247f0c8c1cd823764c23@mail.kernel.org

Built bpftool and reran all 18 ringbuf subtests against it in an x86-64 VM; all passed. Also checked completion against live ringbuf and perf_event_array maps by id, name and pinned path, plus unresolved maps and already-specified selectors with mocked output.

v4: 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     |  59 +--
 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, 578 insertions(+), 49 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: 48ea1ba704aa3a9975e917411ee05bbe67d65744

Signature · 1 line
2.55.0
#1 lore raw

PATCH v5 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     | 59 +++++++------
 tools/bpf/bpftool/map_perf_ring.c             | 87 ++++++++++++++-----
 3 files changed, 112 insertions(+), 48 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 +33 -26

140 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 v5 1/2] bpftool: Read ring buffer maps with event_pipe

This isn't a bug, but the switch from a bare substring grep to an anchored '"type": "..."' match also tightens the existing stack/queue/struct_ops completions. For example, 'bpftool map peek id'…
Quoted 4 lines
tools/bpf/bpftool/bash-completion/bpftool +0 -0
index 75cbcb512ebae..c9e8761e4ef2a 100644

[ ... ]

Quoted 13 lines
tools/bpf/bpftool/bash-completion/bpftool +5 -3
@@ -50,12 +50,19 @@ _bpftool_get_map_ids()
         command sed -n 's/.*"id": \(.*\),$/\1/p' )" -- "$cur" ) )
 }
 
-# Takes map type and adds matching map ids to the list of suggestions.
-_bpftool_get_map_ids_for_type()
+# Takes map types and prints a pattern matching their JSON type fields.
+_bpftool_build_type_pattern()
 {
-    local type="$1"
+    local IFS='|'
+    printf '"type": "(%s)"\n' "$*"
+}

tools/bpf/bpftool/bash-completion/bpftool _bpftool_get_map_ids() · line 67

Quoted 10 lines
tools/bpf/bpftool/bash-completion/bpftool +6 -1
+
+# Takes map types and adds matching map ids to the list of suggestions.
+_bpftool_get_map_ids_for_types()
+{
+    local types=$(_bpftool_build_type_pattern "$@")
     COMPREPLY+=( $( compgen -W "$( bpftool -jp map  2>&1 | \
-        command grep -C2 "$type" | \
+        command grep -C2 -E "$types" | \
         command sed -n 's/.*"id": \(.*\),$/\1/p' )" -- "$cur" ) )
 }

This isn't a bug, but the switch from a bare substring grep to an anchored '"type": "..."' match also tightens the existing stack/queue/struct_ops completions. For example, 'bpftool map peek id' previously matched "type": "stack_trace" because it contained the substring 'stack', so stack_trace map IDs were suggested; they no longer are. Maps whose name contained 'stack' or 'queue' were likewise picked up via the -C2 window and no longer are.

The tightening is well motivated for the new ringbuf call (it keeps user_ringbuf out of the event_pipe suggestions), and every type string used is an exact libbpf map_type_name[] entry, so nothing is wrongly excluded. Would it be worth a line in the changelog about this behavior change to unrelated completions, or splitting the anchoring out from the ringbuf support?

---
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/35575071830

maintainer Tested-by on v5 1/2
#3 lore raw

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

In reply to Tianyi Chen

2026-09-21 16:35 UTC+0900 ~ Tianyi Chen <[email protected]>

Quoted 9 lines

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.

Quoted 8 lines

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
#4 lore raw

PATCH v5 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
#5 lore raw

Re: [PATCH bpf-next v5 2/2] selftests/bpf: Cover bpftool ring buffer event_pipe

This isn't a bug, but since emit_record() also drives the bpf_perf_event_output() path for record 3, would a buffer-neutral tag like "record output" read better here than "ringbuf output"?
Quoted 29 lines
tools/testing/selftests/bpf/bpftool_helpers.c +1 -1
index c49fdd90eb033..9380b24bbf52b 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 dec1ba201410f..17e3be8e70730 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 +0 -0
new file mode 100644
index 0000000000000..e9724c55d1dc6

[ ... ]

Quoted 4 lines
tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c new file +4 -0
+static bool emit_record(struct bpftool_ringbuf *skel, int record)
+{
+	char packet[64] = {};
+

tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c line 179

Quoted 10 lines
tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c new file +10 -0
+	LIBBPF_OPTS(bpf_test_run_opts, opts,
+		    .data_in = packet,
+		    .data_size_in = sizeof(packet),
+	);
+
+	skel->bss->record = record;
+	return ASSERT_OK(bpf_prog_test_run_opts(bpf_program__fd(skel->progs.produce),
+					      &opts), "produce record") &&
+	       ASSERT_OK(skel->bss->output_err, "ringbuf output");
+}

This isn't a bug, but since emit_record() also drives the bpf_perf_event_output() path for record 3, would a buffer-neutral tag like "record output" read better here than "ringbuf output"?

[ ... ]

Quoted 2 lines
tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c new file +2 -0
+static void test_consumer(const char *format, bool idle, int signo, bool pinned)
+{

[ ... ]

tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c line 251

Quoted 4 lines
tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c new file +4 -0
+	if (!idle) {
+		/* Both prefilled records occupy 16 bytes including their headers. */
+		if (!consumed(position, 32))
+			goto out;

This isn't a bug, but would it read more clearly as something like "each prefilled record occupies 16 bytes including its header", so the 32 below follows directly from the comment?

[ ... ]

Quoted 2 lines
tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c new file +2 -0
+static void test_perf_consumer(void)
+{

[ ... ]

tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c line 325

Quoted 9 lines
tools/testing/selftests/bpf/prog_tests/bpftool_ringbuf.c new file +9 -0
+	if (!ASSERT_OK(bpftool_ringbuf__load(skel), "load") ||
+	    !consumer_start(&child, bpf_map__fd(skel->maps.perfbuf), NULL,
+			    NULL, NULL, false, false) || !consumer_ready(&child) ||
+	    !emit_record(skel, 3))
+		goto out;
+	/* One large record flushes the existing buffered perf output callback. */
+	pfd = (struct pollfd) { .fd = child.fd, .events = POLLIN };
+	if (!ASSERT_GT(poll(&pfd, 1, WAIT_STEPS * WAIT_US / 1000), 0,
+		       "perf record output") ||

This isn't a bug, but could this comment spell out that the perf callback does not fflush() and the payload is sized so its hex output overflows stdio's pipe buffer, so the poll() below has something to see?

[ ... ]

Quoted 10 lines
tools/testing/selftests/bpf/progs/bpftool_ringbuf.c new file +4 -0
new file mode 100644
index 0000000000000..bbbc93c30a833
@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: GPL-2.0
+#include <linux/bpf.h>
+#include <bpf/bpf_helpers.h>
+

tools/testing/selftests/bpf/progs/bpftool_ringbuf.c line 14

Quoted 10 lines
tools/testing/selftests/bpf/progs/bpftool_ringbuf.c new file +10 -0
+struct {
+	__uint(type, BPF_MAP_TYPE_RINGBUF);
+} ringbuf SEC(".maps");
+
+struct {
+	__uint(type, BPF_MAP_TYPE_PERF_EVENT_ARRAY);
+	__uint(key_size, sizeof(__u32));
+	__uint(value_size, sizeof(__u32));
+	__uint(max_entries, 1);
+} perfbuf SEC(".maps");

This isn't a bug, but since produce() emits with BPF_F_CURRENT_CPU and test_perf_consumer() already resizes perfbuf to libbpf_num_possible_cpus(), would it read better to drop __uint(max_entries, 1) and let libbpf size the perf event array itself, the way progs/test_perf_buffer.c and progs/perfbuf_bench.c do?

[ ... ]

---
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/35575071830

maintainer Acked-by on the v5 series
#6 lore raw
In reply to Tianyi Chen

2026-09-21 16:35 UTC+0900 ~ Tianyi Chen <[email protected]>

Quoted 12 lines

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 v5:
- Suppress cpu/index completion after selecting a ring buffer map by id, name or pinned path, using _bpftool_map_guess_map_type(). Keep the existing suggestions for perf event arrays and unresolved map types.
- Rebase onto current bpf-next. No other changes from v4.

This addresses the v4 review:
https://lore.kernel.org/r/a89e2e325b87c215e0fb6e4a24284922d7656cfc0e2a247f0c8c1cd823764c23@mail.kernel.org

Quoted 6 lines

Built bpftool and reran all 18 ringbuf subtests against it in an x86-64 VM; all passed. Also checked completion against live ringbuf and perf_event_array maps by id, name and pinned path, plus unresolved maps and already-specified selectors with mocked output.

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

Looks good to me, thanks for this.

#7 lore raw
In reply to Tianyi Chen
This series was applied to bpf/bpf-next.git (master) by Andrii Nakryiko <[email protected]>:

Hello:

This series was applied to bpf/bpf-next.git (master) by Andrii Nakryiko <[email protected]>:

Quoted 10 lines · On Mon, 21 Sep 2026 16:35:54 +0900 you wrote:

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 v5:
- Suppress cpu/index completion after selecting a ring buffer map by id, name or pinned path, using _bpftool_map_guess_map_type(). Keep the existing suggestions for perf event arrays and unresolved map types.
- Rebase onto current bpf-next. No other changes from v4.

[...]

Here is the summary with links:
- [bpf-next,v5,1/2] bpftool: Read ring buffer maps with event_pipe

    https://git.kernel.org/bpf/bpf-next/c/b5dc1b184f32
  - [bpf-next,v5,2/2] selftests/bpf: Cover bpftool ring buffer event_pipe
    https://git.kernel.org/bpf/bpf-next/c/b09784655ecc

You are awesome, thank you!

Signature · 2 lines
Deet-doot-dot, I am a bot.
https://korg.docs.kernel.org/patchwork/pwbot.html