[译] BPF ring buffer：使用场景、核心设计及程序示例（2020）

Published at 2022-04-25 | Last Update 2022-04-25

译者序

本文翻译自 BPF 核心开发者 Andrii Nakryiko 2020 的一篇文章：BPF ring buffer。

文章介绍了 BPF ring buffer 解决的问题及背后的设计，并给出了一些代码示例和内核 patch 链接，深度和广度兼备，是学习 ring buffer 的极佳参考。

由于译者水平有限，本文不免存在遗漏或错误之处。如有疑问，请查阅原文。

以下是译文。

译者序
1 ringbuf 相比 perfbuf 的改进
2 ringbuf 使用场景和性能
3 示例程序（show me the code）
4 ringbuf 事件通知控制
5 总结
其他相关资料（译注）

很多场景下，BPF 程序都需要将数据发送到用户空间（userspace）， BPF perf buffer（perfbuf）是目前这一过程的事实标准，但它存在一些问题，例如 浪费内存（因为其 per-CPU 设计）、事件顺序无法保证等。

作为改进，内核 5.8 引入另一个新的 BPF 数据结构：BPF ring buffer（环形缓冲区，ringbuf），

相比 perf buffer，它内存效率更高、保证事件顺序，性能也不输前者；
在使用上，既提供了与 perf buffer 类似的 API ，以方便用户迁移；又提供了一套新的 reserve/commit API（先预留再提交），以实现更高性能。

此外，实验与真实环境的压测结果都表明，从 BPF 程序发送数据给用户空间时， 应该首选 BPF ring buffer。

1 ringbuf 相比 perfbuf 的改进

perfbuf 是 per-CPU 环形缓冲区（circular buffers），能实现高效的 “内核-用户空间”数据交互，在实际中也非常有用，但 per-CPU 的设计导致两个严重缺陷：

内存使用效率低下（inefficient use of memory）
事件顺序无法保证（event re-ordering）

因此内核 5.8 引入了 ringbuf 来解决这个问题。 ringbuf 是一个“多生产者、单消费者”（multi-producer, single-consumer，MPSC）队列，可安全地在多个 CPU 之间共享和操作。perfbuf 支持的一些功能它都支持，包括，

可变长数据（variable-length data records）；
通过 memory-mapped region 来高效地从 userspace 读数据，避免内存复制或系统调用；
支持 epoll notifications 和 busy-loop 两种获取数据方式。

此外，它还解决了 perfbuf 的下列问题：

内存开销（memory overhead）；
数据乱序；
无效的处理逻辑和不必要的数据复制（extra data copying）。

下面具体来看。

1.1 降低内存开销（memory overhead）

perfbuf 为每个 CPU 分配一个独立的缓冲区，这意味着开发者通常需要 在内存效率和数据丢失之间做出折中：

越大的 per-CPU buffer 越能避免丢数据，但也意味着大部分时间里，大部分内存都是浪费的；
尽量小的 per-CPU buffer 能提高内存使用效率，但在数据量陡增（毛刺）时将导致丢数据。

对于那些大部分时间都比较空闲、周期性来一大波数据的场景，这个问题尤其突出，很难在两者之间取得一个很好的平衡。

ringbuf 的解决方式是分配一个所有 CPU 共享的大缓冲区，

“大缓冲区”意味着能更好地容忍数据量毛刺
“共享”则意味着内存使用效率更高

另外，ringbuf 内存效率的扩展性也更好，比如 CPU 数量从 16 增加到 32 时，

perfbuf 的总 buffer 会跟着翻倍，因为它是 per-CPU buffer；
ringbuf 的总 buffer 不一定需要翻倍，就足以处理扩容之后的数据量。

1.2 保证事件顺序（event ordering）

如果 BPF 应用要跟踪一系列关联事件（correlated events），例如进程的启动和终止、网络连接的生命周期事件等，那保持事件的顺序就非常关键。 perfbuf 在这种场景下有一些问题：如果这些事件发生的间隔非常短（几毫秒）并且分散在不同 CPU 上，那事件的发送顺序可能就会乱掉 ——这同样是 perbuf 的 per-CPU 特性决定的。

举个真实例子，几年前我写的一个应用需要跟踪进程 fork/exec/exit 事件，收集进程级别（per-process）的资源使用量。BPF 程序将这些事件写入 perfbuf，但它们到达的顺序经常乱掉。这是因为内核调度器在不同 CPU 上调度进程时，对于那些存活时间很短的进程，fork(), exec(), and exit() 会在极短的时间内在不同 CPU 上执行。这里的问题很清楚，但要解决这个问题，就需要在应用逻辑中加入大量的判断和处理，只有亲自做过才知道有多复杂。

但对于 ringbuf 来说，这根本不是问题，因为它是共享的同一个缓冲区。ringbuf 保证 如果事件 A 发生在事件 B 之前，那 A 一定会先于 B 被提交，也会在 B 之前被消费。这个特性显著简化了应用处理逻辑。

1.3 减少数据复制（wasted data copy）

BPF 程序使用 perfbuf 时，必须先初始化一份事件数据，然后将它复制到 perfbuf，然后才能发送到用户空间。这意味着数据会被复制两次：

第一次：复制到一个局部变量（a local variable）或 per-CPU array （BPF 的栈空间很小，因此较大的变量无法放到栈上，后面有例子）中；
第二次：复制到 perfbuf 中。

更糟糕的是，如果 perfbuf 已经没有足够空间放数据了，那第一步的复制完全是浪费的。

BPF ringbuf 提供了一个可选的 reservation/submit API 来避免这种问题。

首先申请为数据预留空间（reserve the space），
预留成功后，
- 应用就可以直接将准备发送的数据放到 ringbuf 了，从而节省了 perfbuf 中的第一次复制，
- 将数据提交到用户空间将是一件极其高效、不会失败的操作，也不涉及任何额外的内存复制。
如果因为 buffer 没有空间而预留失败了，那 BPF 程序马上就能知道，从而也不用再执行 perfbuf 中的第一步复制。

后面会有具体例子。

2 ringbuf 使用场景和性能

2.1 常规场景

对于所有实际场景（尤其是那些基于 bcc/libbpf 的默认配置在使用 perfbuf 的场景）， ringbuf 的性能都优于 perfbuf 性能。各种不同场景的仿真压测（synthetic benchmarking）结果见内核 patch。

2.2 高吞吐场景

Per-CPU buffer 特性的 perfbuf 在理论上能支持更高的数据吞吐，但这只有在每秒百万级事件（millions of events per second）的场景下才会显现。

在编写了一个真实场景的高吞吐应用之后，我们证实了 ringbuf 在作为与 perfbuf 类似的 per-CPU buffer 使用时，仍然可以作为 perfbuf 的一个高性能替代品，尤其是用到手动管理事件通知（manual data availability notification）机制时。

基本的 multi-ringbuf example 见内核 selftests：

2.3 不可掩码中断（non-maskable interrupt）场景

唯一需要注意、最好先试验一下的场景：BPF 程序必须在 NMI (non-maskable interrupt) context 中执行时，例如处理 cpu-cycles 等 perf events 时。

ringbuf 内部使用了一个非常轻量级的 spin-lock，这意味着如果 NMI context 中有竞争，data reservation 可能会失败。因此，在 NMI context 中，如果 CPU 竞争非常严重，可能会 导致丢数据，虽然此时 ringbuf 仍然有可用空间。

2.4 小结

除了 NMI context 之外，在其他所有场景中优先选择 ringbuf 而不是 perfbuf 都是非常明智的。

3 示例程序（show me the code）

完整代码见 bpf-ringbuf-examples project。

BPF 程序的功能是 trace 所有进程的 exec() 操作，也就是创建新进程事件。

每次 exec() 事件：收集进程 ID (pid)、进程名字 (comm)、可执行文件路径 (filename)，然后发送给用户空间程序；
用户空间简单通过 printf() 打印输出。

用三种不同方式实现，输出都类似：

$ sudo ./ringbuf-reserve-commit    # or ./ringbuf-output, or ./perfbuf-output
TIME     EVENT PID     COMM             FILENAME
17:39 EXEC  3232062 sh               /bin/sh
17:39 EXEC  3232062 timeout          /usr/bin/timeout
17:39 EXEC  3232063 ipmitool         /usr/bin/ipmitool
17:39 EXEC  3232065 env              /usr/bin/env
17:39 EXEC  3232066 env              /usr/bin/env
17:39 EXEC  3232065 timeout          /bin/timeout
17:39 EXEC  3232066 timeout          /bin/timeout
17:39 EXEC  3232067 sh               /bin/sh
17:39 EXEC  3232068 sh               /bin/sh
^C

事件的结构体定义：

#define TASK_COMM_LEN 16
#define MAX_FILENAME_LEN 512

// BPF 程序发送给 userspace 的事件
struct event {
    int pid;
    char comm[TASK_COMM_LEN];
    char filename[MAX_FILENAME_LEN];
};

这里有意让这个结构体的大小超过 512 字节，这样 event 变量就无法放到 BPF 栈空间（max 512Byte）上，后面会看到 perfbuf 和 ringbuf 程序分别怎么处理。

3.1 perfbuf 示例

内核 BPF 程序

// 声明一个 perfbuf map。几点注意：
// 1. 不用特意设置 max_entries，libbpf 会自动将其设置为 CPU 数量；
// 2. 这个 map 的 per-CPU buffer 大小是 userspace 设置的，后面会看到
struct {
	__uint(type, BPF_MAP_TYPE_PERF_EVENT_ARRAY); // perf buffer (array)
	__uint(key_size, sizeof(int));
	__uint(value_size, sizeof(int));
} pb SEC(".maps");

// 一个 struct event 变量的大小超过了 512 字节，无法放到 BPF 栈上，
// 因此声明一个 size=1 的 per-CPU array 来存放 event 变量
struct {
	__uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);    // per-cpu array
	__uint(max_entries, 1);
	__type(key, int);
	__type(value, struct event);
} heap SEC(".maps");

SEC("tp/sched/sched_process_exec")
int handle_exec(struct trace_event_raw_sched_process_exec *ctx)
{
	unsigned fname_off = ctx->__data_loc_filename & 0xFFFF;
	struct event *e;
	int zero = 0;
	
	e = bpf_map_lookup_elem(&heap, &zero);
	if (!e) /* can't happen */
		return 0;

	e->pid = bpf_get_current_pid_tgid() >> 32;
	bpf_get_current_comm(&e->comm, sizeof(e->comm));
	bpf_probe_read_str(&e->filename, sizeof(e->filename), (void *)ctx + fname_off);

	// 发送事件，参数列表 <context, &perfbuf, flag, event, sizeof(event)>
	bpf_perf_event_output(ctx, &pb, BPF_F_CURRENT_CPU, e, sizeof(*e));
	return 0;
}

用户空间程序

完整代码 the user-space side，基于 BPF skeleton（更多信息见这里）。

看一个关键点：使用 libbpf user-space perf_buffer__new() API 来创建一个 perf buffer consumer：

	struct perf_buffer *pb = NULL;
	struct perf_buffer_opts pb_opts = {};
	struct perfbuf_output_bpf *skel;

	/* Set up ring buffer polling */
	pb_opts.sample_cb = handle_event;
	pb = perf_buffer__new(bpf_map__fd(skel->maps.pb), 8 /* 32KB per CPU */, &pb_opts);

这里设置 per-CPU buffer 为 32KB，注意其中的 8 表示的是 number of memory pages，每个 page 是 4KB，因此总大小： 8 pages x 4096 byte/page = 32KB。

3.2 ringbuf 示例

完整代码：

内核 BPF 程序

bpf_ringbuf_output() 在设计上遵循了 bpf_perf_event_output() 的语义，以使应用从 perfbuf 迁移到 ringbuf 时更容易。为了看出二者有多相似，这里展示下两个示例代码的 diff。

--- src/perfbuf-output.bpf.c	2020-10-25 18:52:22.247019800 -0700
+++ src/ringbuf-output.bpf.c	2020-10-25 18:44:14.510630322 -0700
@@ -6,12 +6,11 @@
 
 char LICENSE[] SEC("license") = "Dual BSD/GPL";
 
-/* BPF perfbuf map */
+/* BPF ringbuf map */
 struct {
-	__uint(type, BPF_MAP_TYPE_PERF_EVENT_ARRAY);
-	__uint(key_size, sizeof(int));
-	__uint(value_size, sizeof(int));
-} pb SEC(".maps");
+	__uint(type, BPF_MAP_TYPE_RINGBUF);
+	__uint(max_entries, 256 * 1024 /* 256 KB */);
+} rb SEC(".maps");
 
 struct {
 	__uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
@@ -35,7 +34,7 @@
 	bpf_get_current_comm(&e->comm, sizeof(e->comm));
 	bpf_probe_read_str(&e->filename, sizeof(e->filename), (void *)ctx + fname_off);
 
-	bpf_perf_event_output(ctx, &pb, BPF_F_CURRENT_CPU, e, sizeof(*e));
+	bpf_ringbuf_output(&rb, e, sizeof(*e), 0);
 	return 0;
 }

只有两个小改动：

ringbuf map 的大小（max_entries）可以在 BPF 侧指定了，注意这是所有 CPU 共享的大小。
- 在 userspace 侧来设置（或 override） max_entries 也是可以的，API 是 bpf_map__set_max_entries()；
- max_entries 的单位是字节，必须是内核页大小（几乎永远是 4096）的倍数，也必须是 2 的幂次。
bpf_perf_event_output() 替换成了类似的 bpf_ringbuf_output()，后者更简单，不需要 BPF context 参数。

用户空间程序

事件 handler 签名有点变化：

会返回错误信息（进而终止 consumer 循环）
参数里面去掉了产生这个事件的 CPU Index

-void handle_event(void *ctx, int cpu, void *data, unsigned int data_sz)
+int handle_event(void *ctx, void *data, size_t data_sz)
{
	const struct event *e = data;
	struct tm *tm;

如果 CPU index 对你很重要，那你需要自己在 BPF 代码中记录它。

另外，ring_buffer API 不提供丢失数据（lost samples）的回调函数，而 perf_buffer 是支持的。如果需要这个功能，必须自己在 BPF 代码中处理。这样的设计对于一个（所有 CPU）共享的 ring buffer 能最小化锁竞争，同时也避免了为不需要的功能买单：在实际中，这功能除了能用户在 userspace 打印出有数据丢失之外，其他基本也做不了什么，而类似的目的在 BPF 中可以更显式和高效地完成。

第二个不同是 ring_buffer__new() API 更加简洁：

 	/* Set up ring buffer polling */
-	pb_opts.sample_cb = handle_event;
-	pb = perf_buffer__new(bpf_map__fd(skel->maps.pb), 8 /* 32KB per CPU */, &pb_opts);
-	if (libbpf_get_error(pb)) {
+	rb = ring_buffer__new(bpf_map__fd(skel->maps.rb), handle_event, NULL, NULL);
+	if (!rb) {
 		err = -1;
-		fprintf(stderr, "Failed to create perf buffer\n");
+		fprintf(stderr, "Failed to create ring buffer\n");
 		goto cleanup;
 	}

接下来基本上就是文本替换一下的事情了： perf_buffer__poll() -> ring_buffer__poll()

 	printf("%-8s %-5s %-7s %-16s %s\n",
 	       "TIME", "EVENT", "PID", "COMM", "FILENAME");
 	while (!exiting) {
-		err = perf_buffer__poll(pb, 100 /* timeout, ms */);
+		err = ring_buffer__poll(rb, 100 /* timeout, ms */);
 		/* Ctrl-C will cause -EINTR */
 		if (err == -EINTR) {
 			err = 0;
 			break;
 		}
 		if (err < 0) {
-			printf("Error polling perf buffer: %d\n", err);
+			printf("Error polling ring buffer: %d\n", err);
 			break;
 		}
 	}

3.3 ringbuf reserve/commit API 示例

bpf_ringbuf_output() API 的目的是确保从 perfbuf 到 ringbuf 迁移时无需对 BPF 代码做重大改动，但这也意味着它继承了 perfbuf API 的一些缺点：

额外的内存复制（extra memory copy）

这意味着需要额外的空间来构建 event 变量，然后将其复制到 buffer。不仅低效，而且经常需要引入只有一个元素的 per-CPU array，增加了不必要的处理复杂性。
非常晚的 buffer 空间申请（data reservation）

如果这一步失败了（例如由于用户空间消费不及时导致 buffer 满了，或者有大量突发事件导致 buffer 溢出了），那上一步的工作将变得完全无效，浪费内存空间和计算资源。

原理

如果能提前知道事件将在第二步被丢弃，就无需做第一步了，节省一些内存和计算资源，消费端反而因此而消费地更快一些。但 xxx_output() 风格的 API 是无法实现这个目的的。

这就是为什么引入了新的 bpf_ringbuf_reserve()/bpf_ringbuf_commit() API。

提前预留空间，或者能立即发现没有可以空间了（返回 NULL）；
预留成功后，一旦数据写好了，将它发送到 userspace 是一个不会失败的操作。

也就是说只要 bpf_ringbuf_reserve() 返回非空，那随后的 bpf_ringbuf_commit() 就永远会成功，因此它没有返回值。

另外，ring buffer 中预留的空间在被提交之前，用户空间是看不到的，因此 BPF 程序可以从容地组织自己的 event 数据，不管它有多复杂、需要多少步骤。这种方式也避免了额外的内存复制和临时存储空间（extra memory copying and temporary storage spaces）。

限制

唯一的限制是：BPF 校验器在校验时（at verification time）， 必须知道预留数据的大小 （size of the reservation），因此不支持动态大小的事件数据。

对于动态大小的数据，用户只能退回到用 bpf_ringbuf_output() 方式来提交，忍受额外的数据复制开销；
其他所有情况下，reserve/commit API 都应该是首选。

内核 BPF 程序

--- src/ringbuf-output.bpf.c	2020-10-25 18:44:14.510630322 -0700
+++ src/ringbuf-reserve-submit.bpf.c	2020-10-25 18:36:53.409470270 -0700
@@ -12,29 +12,21 @@
 	__uint(max_entries, 256 * 1024 /* 256 KB */);
 } rb SEC(".maps");
 
-struct {
-	__uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
-	__uint(max_entries, 1);
-	__type(key, int);
-	__type(value, struct event);
-} heap SEC(".maps");
-
 SEC("tp/sched/sched_process_exec")
 int handle_exec(struct trace_event_raw_sched_process_exec *ctx)
 {
 	unsigned fname_off = ctx->__data_loc_filename & 0xFFFF;
 	struct event *e;
-	int zero = 0;
 	
-	e = bpf_map_lookup_elem(&heap, &zero);
-	if (!e) /* can't happen */
+	e = bpf_ringbuf_reserve(&rb, sizeof(*e), 0);
+	if (!e)
 		return 0;
 
 	e->pid = bpf_get_current_pid_tgid() >> 32;
 	bpf_get_current_comm(&e->comm, sizeof(e->comm));
 	bpf_probe_read_str(&e->filename, sizeof(e->filename), (void *)ctx + fname_off);
 
-	bpf_ringbuf_output(&rb, e, sizeof(*e), 0);
+	bpf_ringbuf_submit(e, 0);
 	return 0;
 }

用户空间程序

用户空间代码与之前的 ringbuf output API 完全一样，因为这个 API 涉及到的只是提交方（生产方），消费方还是一样的方式来消费。

4 ringbuf 事件通知控制

4.1 事件通知开销

在高吞吐场景中，最大的性能损失经常来自提交数据时，内核的信号通知开销（in-kernel signalling of data availability），也就是内核的 poll/epoll 通知阻塞在读数据上的 userspace handler 接收数据。

这一点对 perfbuf 和 ringbuf 都是一样的。

4.2 perbuf 解决方式

perfbuf 处理这种场景的方式是提供了一个采样通知（sampled notification）机制：每 N 个事件才会发送一次通知。用户空间创建 perfbuf 时可以指定这个参数。

这种机制能否解决问题，因具体场景而异。

4.3 ringbuf 解决方式

ringbuf 选了一条不同的路：bpf_ringbuf_output() 和 bpf_ringbuf_commit() 都支持一个额外的 flags 参数，

BPF_RB_NO_WAKEUP：不触发通知
BPF_RB_FORCE_WAKEUP：会触发通知

基于这个 flags，用户能实现更加精确的通知控制。例子见 BPF ringbuf benchmark。

默认情况下，如果没指定任何 flag，ringbuf 会采用自适应通知 （adaptive notification）机制，根据 userspace 消费者是否有滞后（lagging）来动态调整通知间隔，尽量确保 userspace 消费者既不用承担额外开销，又不丢失任何数据。这种默认配置在大部分场景下都是有效和安全的，但如果想获得极致性能，那显式控制数据通知就是有必要的，需要结合具体应用场景和处理逻辑来设计。

5 总结

本文介绍了 BPF ring buffer 解决的问题及其背后的设计。

文中给出的示例代码和内核代码链接，展示了 ringbuf API 的基础和高级用法。希望阅读本文之后，读者能对 ringbuf 有一个很好的理解和把握，能根据自己的具体应用选择合适的 API 来使用。

其他相关资料（译注）

内核文档，BPF ring buffer

有一些更细节的设计与实现，可作为本文补充。

« Cracking Kubernetes RBAC Authorization (AuthZ) Model (2022) BPF 进阶笔记（四）：调试 BPF 程序 »

ArthurChiao's Blog

[译] BPF ring buffer：使用场景、核心设计及程序示例（2020）

译者序

1 ringbuf 相比 perfbuf 的改进

1.1 降低内存开销（memory overhead）

1.2 保证事件顺序（event ordering）

1.3 减少数据复制（wasted data copy）

2 ringbuf 使用场景和性能

2.1 常规场景

2.2 高吞吐场景

2.3 不可掩码中断（non-maskable interrupt）场景

2.4 小结

3 示例程序（show me the code）

3.1 perfbuf 示例

内核 BPF 程序

用户空间程序

3.2 ringbuf 示例

内核 BPF 程序

用户空间程序

3.3 ringbuf reserve/commit API 示例

原理

限制

内核 BPF 程序

用户空间程序

4 ringbuf 事件通知控制

4.1 事件通知开销

4.2 perbuf 解决方式

4.3 ringbuf 解决方式

5 总结

其他相关资料（译注）