在 Linux 上编写/调试 eBPF 程序时：用…

适用于 Linux eBPF 可观测性与网络编程：选择工具、编写内核/用户态程序、排查 verifier 错误，并使用 maps、XDP、CO-RE、ring buffer、iterator 与 atomics。

适用场景

解决思路

1. 一次性内核追踪/脚本：使用 bpftrace。
2. 带用户态的生产 eBPF 程序：使用 libbpf（C）或 aya（Rust）。
3. 检查已加载程序和 maps：使用 bpftool。
4. 高性能包处理：使用 XDP + libbpf。
5. 用 bpftrace 追踪所有 execve 调用并打印 comm 和参数：bpftrace -e 'tracepoint:syscalls:sys_enter_execve { printf("%s %s\n", comm, str(args->filename)); }'
6. 用 bpftrace 按进程统计系统调用次数：bpftrace -e 'tracepoint:raw_syscalls:sys_enter { @[comm] = count(); }'
7. 用 bpftrace 统计 read() 系统调用延迟直方图：bpftrace -e ' tracepoint:syscalls:sys_enter_read { @start[tid] = nsecs; } tracepoint:syscalls:sys_exit_read { @us = hist((nsecs - @start[tid]) / 1000); delete(@start[tid]); }'
8. 列出可用 tracepoints：bpftrace -l 'tracepoint:syscalls:*'
9. 列出可用 kprobes：bpftrace -l 'kprobe:tcp_*'
10. 编写内核侧 counter.bpf.c：包含 <vmlinux.h> 和 <bpf/bpf_helpers.h>；定义 BPF_MAP_TYPE_HASH 类型的 call_count，key 为 u32，value 为 u64，max_entries 为 1024，放在 SEC(".maps")；定义 SEC("tracepoint/syscalls/sys_enter_read") 的 trace_read；用 bpf_get_current_pid_tgid() >> 32 获取 pid；bpf_map_lookup_elem 查找计数，存在则递增，否则用 bpf_map_update_elem 写入 1，flag 为 BPF_ANY；返回 0；声明 char LICENSE[] SEC("license") = "GPL";
11. 编写用户态加载器 counter.c：包含 counter.skel.h；用 counter_bpf__open() 打开；用 counter_bpf__load(skel) 加载；用 counter_bpf__attach(skel) 挂载；读取 map 并打印结果；用 counter_bpf__destroy(skel) 清理。
12. 用 libbpf 1.x 构建：clang -g -O2 -target bpf -D__TARGET_ARCH_x86 -I/usr/include/bpf -c counter.bpf.c -o counter.bpf.o
13. 生成 skeleton：bpftool gen skeleton counter.bpf.o > counter.skel.h
14. 编译用户态程序：gcc -o counter counter.c -lbpf -lelf -lz
15. libbpf 1.x 打开和加载 API：使用 counter_bpf__open()、counter_bpf__load(skel)、counter_bpf__attach(skel)（替代旧的分步 bpf_object__open/load 模式）。
16. 显式文件打开：struct bpf_object *obj = bpf_object__open_file("counter.bpf.o", NULL); bpf_object__load(obj);
17. Skeleton 生成始终通过 bpftool：bpftool gen skeleton counter.bpf.o name counter > counter.skel.h
18. BPF_MAP_TYPE_HASH：任意 key→任意 value，用于按 PID 计数、状态。
19. BPF_MAP_TYPE_ARRAY：u32 key→固定 value，用于配置、按 CPU 索引的 metrics。
20. BPF_MAP_TYPE_PERCPU_HASH：key→每 CPU value，用于无锁高频计数。
21. BPF_MAP_TYPE_RINGBUF：用于高效内核→用户态事件。
22. BPF_MAP_TYPE_PERF_EVENT_ARRAY：旧式 perf 事件输出。
23. BPF_MAP_TYPE_LRU_HASH：key→value，用于连接跟踪、有限大小场景。
24. BPF_MAP_TYPE_PROG_ARRAY：u32→prog，用于尾调用、程序链。
25. BPF_MAP_TYPE_XSKMAP：用于 AF_XDP socket 重定向。
26. 新代码优先使用 BPF_MAP_TYPE_RINGBUF 而不是 PERF_EVENT_ARRAY：开销更低，支持变长记录。
27. invalid mem access 'scalar'：解引用未限界指针；修复：使用前对指针做 null 检查。
28. R0 !read_ok：没有设置 R0 就返回；修复：确保所有路径设置返回值。
29. jump out of range：分支目标超出程序末尾；修复：重构条件分支。
30. back-edge detected：向后跳转（循环）；修复：使用 bpf_loop() helper（kernel ≥5.17）或有界循环。
31. unreachable insn：return 后存在死代码；修复：移除死分支。
32. invalid indirect read：读取未初始化栈字节；修复：零初始化结构体，如 struct foo x = {}。
33. misaligned stack access：指针算术未对齐；修复：按 __u64 边界对齐读取。
34. 获取详细 verifier 日志：bpftool prog load prog.bpf.o /sys/fs/bpf/prog type kprobe 2>&1 | head -100
35. 检查已加载程序：bpftool prog list
36. 转储已翻译指令：bpftool prog dump xlated id 42
37. 编写 XDP 程序 xdp_drop_icmp.bpf.c：包含 <vmlinux.h>、<bpf/bpf_helpers.h>、<bpf/bpf_endian.h>；定义 SEC("xdp") int xdp_filter(struct xdp_md *ctx)；读取 data_end 和 data；eth = data；若 (void *)(eth + 1) > data_end 返回 XDP_PASS；若 bpf_ntohs(eth->h_proto) != ETH_P_IP 返回 XDP_PASS；ip = (void *)(eth + 1)；若 (void *)(ip + 1) > data_end 返回 XDP_PASS；若 ip->protocol == IPPROTO_ICMP 返回 XDP_DROP；否则返回 XDP_PASS；声明 GPL license。
38. 将 XDP 程序挂载到接口：ip link set dev eth0 xdp obj xdp_drop_icmp.bpf.o sec xdp
39. 移除 XDP 程序：ip link set dev eth0 xdp off
40. 最佳性能使用 native（驱动）模式：ip link set dev eth0 xdp obj prog.bpf.o sec xdp mode native
41. XDP 返回码：XDP_PASS、XDP_DROP、XDP_TX（hairpin）、XDP_REDIRECT。
42. CO-RE（Compile Once - Run Everywhere）使用 BTF 类型信息在加载时重定位字段访问。
43. 使用基于 BTF 的字段访问（CO-RE aware）：包含由运行内核 BTF 生成的 <vmlinux.h> 和 <bpf/bpf_core_read.h>。
44. kprobe/tcp_connect 示例：struct sock *sk = (struct sock *)PT_REGS_PARM1(ctx); u16 dport = BPF_CORE_READ(sk, __sk_common.skc_dport); BPF_CORE_READ 在加载时重定位字段偏移；用 bpf_printk 打印 bpf_ntohs(dport)；返回 0。
45. 从运行内核生成 vmlinux.h：bpftool btf dump file /sys/kernel/btf/vmlinux format c > vmlinux.h
46. 验证 BTF 已启用：ls /sys/kernel/btf/vmlinux
47. 编写 ring buffer：定义 BPF_MAP_TYPE_RINGBUF 类型 map rb，max_entries 为 256 * 1024；在 SEC("kprobe/sys_open") handle_open 中用 bpf_ringbuf_reserve(&rb, sizeof(*e), 0) 预留事件；若失败返回 0；设置 e->pid = bpf_get_current_pid_tgid() >> 32；用 bpf_ringbuf_submit(e, 0) 提交；错误路径用 bpf_ringbuf_discard(e, 0)；返回 0。
48. Ring buffer 与 perf buffer 对比 API：Ring buffer 用 bpf_ringbuf_reserve/submit；Perf buffer 用 bpf_perf_event_output。
49. 对比背压：Ring buffer 满时 reserve 失败；Perf buffer 可能丢弃事件。
50. 对比用户态：Ring buffer 用 ring_buffer__poll（libbpf）；Perf buffer 用 perf_buffer__poll。
51. 对比多生产者：Ring buffer 支持多生产者；Perf buffer 使用每 CPU buffer。
52. 编写 BPF iterator：定义 BPF_MAP_TYPE_PROG_ARRAY 类型 iter_prog，max_entries 为 1，放在 SEC(".maps")；定义 SEC("iter/task") int dump_tasks(struct bpf_iter__task *ctx)；task = ctx->task；若 task 存在，用 bpf_seq_printf(ctx->meta->seq, "%d %s\n", task->tgid, task->comm)；返回 0。
53. 从用户态读取 iterator 输出：bpftool prog tracelog，或把 iter 挂到 seq_file reader；cat /sys/kernel/debug/tracing/trace_pipe
54. Iterator 可遍历内核数据结构（tasks、maps、TCP sockets），无需每个元素都用 kprobe 的开销。
55. 在 BPF 程序中使用 GCC/Clang 原子内建（kernel 5.12+）：static __always_inline void inc_counter(__u32 *counter) { __sync_fetch_and_add(counter, 1); }
56. 在并发探针下对 per-CPU 或 map 支持的计数器使用原子操作。
57. 高频计数器优先使用 per-CPU array maps；当聚合到单个 map value 时使用 atomics。
58. 完整 map 类型参考见 references/ebpf-map-types.md。
59. 如需 Aya 框架的 Rust eBPF 程序，使用 skills/observability/ebpf-rust。
60. 如需不依赖 eBPF 的 perf 追踪，使用 skills/profilers/linux-perf。
61. 如需 seccomp-bpf 系统调用过滤，使用 skills/runtimes/binary-hardening。
62. 如需内核模块开发，使用 skills/low-level-programming/linux-kernel-modules。
63. 如需 XDP_REDIRECT 到 AF_XDP socket，使用 skills/async-io/af-xdp。

适用边界 · 注意事项

• 非 Linux 环境，或内核不支持 eBPF/BTF/所需版本（例如缺少 /sys/kernel/btf/vmlinux、kernel 版本过低）时不适用。
• 无 root 或 CAP_BPF/CAP_SYS_ADMIN 等权限，无法加载或挂载 eBPF 程序时不适用。
• 只需用户态可观测性、简单调试或普通应用层抓包时，不必引入 eBPF 的复杂性和权限要求。