CO-RE全称 Compile Once, Run Everywhere——编译一次到处运行是 BPF 程序在多版本内核之间保持可移植的核心机制。我最早被它救了一命是因为手里一批跑在内核 5.4 到 5.15 混合集群上的探测程序每次有机器升级内核总有一两个 BPF 程序加载失败或者更糟加载成功了读到一堆乱码因为结构体字段偏移变了。后来我把整套加载逻辑切到 CO-RE 自动定位程序再也不用跟着内核版本走。这篇就把 CO-RE 自动定位的原理完整拆一遍适合正在写 BPF 工具、维护内核观测程序、或者刚接触 eBPF 想搞懂为啥同一个 .o 能到处跑的开发者。1. 老问题BPF 程序一换内核就歪1.1 内核结构体布局是内部细节BPF 程序想要读取内核数据比如当前进程的名字、某个 socket 的状态本质上是直接去访问内核内存里的结构体成员。以读取进程名task-comm为例这条 C 代码编译成 BPF 指令后会变成一条固定偏移的内存加载指令从task_struct基地址加上某个偏移处读一块内存。问题来了Linux 内核从不保证结构体布局对外稳定。源码里同一个struct task_struct在不同内核版本里可能新增字段、删除字段、调整字段顺序还可能因为内核配置项不同导致某些字段被条件编译掉。只要任何一个变动导致目标字段的偏移发生变化你编译时写死的偏移就废了。这种偏移错误不像普通编译错误那样会直接报出来。程序能加载能运行但读到的是别的东西可能是另一个字段的值可能是空值严重时还会因为访问了不合理的地址被 verifier 拒之门外。也就是说内核一升级你的 BPF 工具就歪了。1.2 旧方案的尴尬按内核版本配菜在这个问题面前传统思路是给每个目标内核版本准备一套对应的编译头文件和 BPF 字节码加载程序的时候先检测当前内核版本再挑对应的 .o 文件加载。听起来可行但实际操作非常难受。首先你得为每个内核版本准备全套内核头文件。其次你编译产物要多出好几份每个版本一份。最麻烦的是集群环境十台机器五个内核版本更新一次程序就要重新编译五遍如果某台机器悄悄做了安全升级内核版本变了你预编译的那份可能就不匹配了。就算用运行时编译的思路每次加载都现场拉取对应内核头文件再编译逻辑上也绕回到了按版本配菜只是把编译时间从构建期挪到了运行期对服务和容器的加载延迟打击很大。1.3 CO-RE 的思路把意图和布局彻底分开CO-RE 的思路和前面完全相反。它不去猜目标内核长什么样而是做三件事的组合编译期编译器记录你这次访问的意图——访问的是哪个类型的哪个字段而不是只写死一个偏移。内核侧目标内核通过 BTF 暴露自己的真实结构体布局。加载期加载器把意图和真实布局对齐重新计算偏移然后改写 BPF 指令里的偏移值。用大白话说以前是搬家前就把家具的位置钉死在地板上CO-RE 是到了新房子再量尺寸摆家具。家具还是同一套但位置是现场定的所以换个户型也能住。这个思路听起来不难难点全在三个环节的具体实现上。下面逐个拆。2. BTF让内核把家底摊给你看2.1 BTF 是什么怎么来的要想让加载器在运行期量尺寸首先得让内核愿意把结构体布局信息交出来。这就是 BTFBPF Type Format的职责。BTF 是一种紧凑的二进制类型元数据格式。内核在编译时如果开启CONFIG_DEBUG_INFO_BTFy会把自身所有的结构体、联合体、枚举、函数原型、全局变量等类型信息序列化到内核镜像的.BTF段里并在系统启动后以/sys/kernel/btf/vmlinux的形式暴露出来。注意一个关键词紧凑。和传统的 DWARF 调试信息相比BTF 去掉了很多重建设源码才需要的细节只保留类型图本身。这样它体积小得多也稳定得多。内核官方把它作为一种稳定的运行时接口对待专门为了让 BPF 生态使用。可以这么理解BTF 就是内核给自己做的一份结构体体检报告里面每个struct有什么字段、每个字段在第几个字节、每个枚举值是多少都写得清清楚楚。加载器只要会读这份报告就能算出正确的偏移。2.2 vmlinux.h把 BTF 变成开发者能用的头文件问题来了开发者总不能直接去读二进制 BTF 吧所以生态里提供了把 BTF 转换成人可读 C 头文件的工具。用bpftool btf dump file /sys/kernel/btf/vmlinux format c就能生成一个名为vmlinux.h的巨型 C 头文件。这个头文件里包含当前内核 BTF 中所有类型的 C 结构体声明你写 BPF 程序时直接#include vmlinux.h就行不再需要装一堆内核开发头文件。这也是 CO-RE 开发体验比传统方式舒服很多的原因以前为了访问task_struct你得搞来版本完全匹配的内核头文件现在只要手里有一份vmlinux.h编译环境就齐了。但要特别注意vmlinux.h是某个内核的布局快照。你拿 6.x 的vmlinux.h编译出来的程序可以放到 5.x 上运行靠的是运行时重定位而不是靠这份头文件本身兼容。这件事我在后面第 5 节详细说因为不少人在这里误解。2.3 编译器的两个产出.BTF 段和 .BTF.ext 段开发者写好的 BPF 程序用 clang 编译时通常会加-g参数。这个参数除了生成普通调试信息还会让编译器为 BPF 目标生成两个非常重要的附加段.BTF段记录这个 BPF 程序自身的类型信息包括程序里引用到的结构体类型。.BTF.ext段记录函数信息和行信息以及最关键的重定位记录CO-RE Relocation。.BTF.ext里的重定位记录才是自动定位的意图所在。它会明确记录某条 BPF 指令访问的是哪个类型例如task_struct的哪个字段例如comm。编译器同时也会在你最终的指令里填一个根据当前vmlinux.h算出的默认偏移但那个偏移只是一个待修改的占位值。有个坑我见过不止一次有人觉得-g只是生成调试信息为了减少产物体积把它去掉。结果编译出来的 BPF 程序完全没有 CO-RE 重定位记录装上 CO-RE 加载器也发挥不了自动定位的作用又退回老的按版本编译路线。所以 CO-RE 模式下-g是必须的。3. 自动定位的执行者libbpf 如何在加载时改指令3.1 加载时发生了什么CO-RE 的整套魔法在运行期由加载器完成。目前最主流、事实标准的实现是 libbpf。整个加载流程大致是这样的libbpf 打开你的.o文件解析出各个程序段、map 定义和变量定义。扫描.BTF.ext段里的 CO-RE 重定位记录。读取目标内核的/sys/kernel/btf/vmlinux构造出目标内核的 BTF 类型图。对每一条重定位记录结合目标 BTF 算出真实偏移或真实值。改写对应 BPF 指令里的off或imm让指令指到正确的位置。所有重定位完成后把修正过的指令和各类 object 一并加载进内核交给 verifier 验证。在整个过程里开发者唯一要做的事就是把 BTF、编译标记、加载器这三样准备齐全。至于指令怎么改完全由 libbpf 在毫秒级完成。3.2 几类重定位记录分别管什么不是只有访问结构体字段偏移一种情况需要自动定位。CO-RE 的完整重定位体系覆盖了好几种场景我挑重点列一下重定位类型作用典型场景字段字节偏移计算结构体成员的真实字节偏移改写指令偏移访问task-comm这类字段字段大小获取字段的真实字节大小动态判断字段宽度位偏移与位大小处理 bitfield 成员的位级信息访问标志位、状态位枚举值修正枚举常量的数值读取状态码、事件类型类型 ID在本地类型和内核类型之间映射 BTF ID类型匹配、BTF 引用类型存在性判断类型在当前内核是否存在返回 0/1兼容不同内核结构体差异字段存在性判断某个字段在当前内核是否存在返回 0/1老内核没有新字段时走另一条分支内核符号解析内核全局符号地址访问内核全局变量Kconfig 值读取内核配置项数值判断CONFIG_HZ、CONFIG_NR_CPUS这张表看下来你会发现CO-RE 的自动定位并不仅仅是偏移修正它是一整套让 BPF 程序和内核布局解耦的能力集合。字段偏移重定位是其中最基础、最常用的部分也是我今天讲的重点但其他类型在实际开发中同样重要。3.3 指令改写到底改什么想要理解指令改写得先知道 BPF 指令的基本形态。一条 BPF 指令是 64 位8 字节的其中有几个关键部分操作码、目标寄存器、源寄存器、16 位偏移off、32 位立即数imm。当一条指令要访问某个结构体字段时字段偏移一般会放在off或imm里。比如从某个寄存器指向的结构体地址加载数据偏移off就表示从基地址往后数多少个字节。libbpf 做字段偏移重定位时做的事情就是根据目标内核 BTF 里查到的真实偏移替换指令原来的off或imm。听起来很直接但里面有一个容易被忽略的细节同样的 C 代码经过编译器优化后指令形态可能有多种。可能是ldx指令直接带偏移可能先加载到中间寄存器也可能走ldimm64这种 64 位立即数。libbpf 必须区分这些形态分别处理。这正是实测排错时比较烧脑的部分。3.4 自动不是魔法它需要明确的标记CO-RE 的自动定位有一个前提编译器得知道哪些访问要生成重定位记录。如果你写的是task-comm这种普通 C 表达式不加任何标记clang 在编译时就是按普通访问处理直接把偏移写死就完事不会生成 CO-RE 重定位记录。只有在访问被标记为保留访问意图时编译器才会记录重定位信息。平时用到的bpf_core_read()、BPF_CORE_READ()这些宏内部都封装了__builtin_preserve_access_index()这个 clang 内置函数它的作用就是告诉编译器对这次访问请保留索引信息将来我要靠它做重定位。这一点非常关键因为很多人以为只要用了 CO-RE 框架代码里随便怎么写都能自动适配实际不是。该用宏的时候不用宏该加标记的时候不加标记编出来的程序依然会把偏移写死内核一升级照样崩。4. 推演一遍task_struct 里的字段是怎么被自动找到的4.1 一个读取进程名的 BPF 程序为了把原理讲透我拿一个最简单的 BPF 程序来推演。程序挂在sched_process_exec跟踪点上每次进程执行新程序时读取当前任务的进程名并打印。#include vmlinux.h #include bpf/bpf_helpers.h #include bpf/bpf_core_read.h SEC(tp/sched/sched_process_exec) int handle_exec(void *ctx) { struct task_struct *task (struct task_struct *)bpf_get_current_task(); char comm[16]; bpf_core_read(comm, sizeof(comm), task-comm); bpf_printk(exec: %s\n, comm); return 0; } char LICENSE[] SEC(license) GPL;这段代码里task-comm的访问没有直接写在解引用位置而是用bpf_core_read()包了一层。这就能保证编译器生成 CO-RE 重定位记录。4.2 编译产物里藏着什么编译命令很简单clang -g -O2 -target bpf -D__TARGET_ARCH_X86_64 \ -I. -c exec_tracer.bpf.c -o exec_tracer.o编译完成后用llvm-readelf -S exec_tracer.o看段表能看到一个普通 BPF 对象没有的东西.BTF段和.BTF.ext段。.BTF.ext里就有我们要找的 CO-RE 重定位记录。它记录了这条 BPF 程序里访问了task_struct.comm这一意图。注意这里记录的不仅是偏移是多少而是访问了什么类型的什么字段这个语义信息。有了语义信息加载器才能到目标内核的 BTF 里重新查偏移。4.3 加载器把指令改成了什么当 libbpf 加载这个.o文件时它会读到那条重定位记录然后去目标内核的/sys/kernel/btf/vmlinux里找到struct task_struct再在结构体成员列表里找到comm计算出它在目标内核里的真实字节偏移。假设编译用的vmlinux.h里comm的偏移是 0x1234目标内核的真实偏移是 0x1300那 libbpf 就会找出发送给内核的 BPF 指令序列中对应那条指令把指令里的偏移从 0x1234 改成 0x1300。整个过程在一两毫秒内完成之后再把指令交给内核 verifier。这就是自动定位四个字的准确含义字段到底是第几个字节不是写程序的人决定的也不是编译时决定的而是加载时由 libbpf 根据目标内核 BTF 现场决定的。4.4 如果内核改了字段顺序会怎样假设你在 5.10 上编译程序跑到 6.1 上。5.10 里task_struct的comm排在第 100 个字节6.1 里因为前面插入了别的字段comm排到了第 120 个字节。没有 CO-RE 的话程序读到的是task_struct起始地址加 100 的位置在 6.1 上那是别的字段数据自然就错了。有了 CO-RElibbpf 在加载时一查 6.1 的 BTF发现comm在 120直接改指令偏移程序读到的还是正确的进程名。这也是 CO-RE 最核心的价值同一个.o文件只要目标内核提供 BTFlibbpf 就能自动算出所有当前内核的正确布局程序本身不用重新编译。5. 实操中的坑CO-RE 不是开了 BTF 就万事大吉说了这么多原理接下来分享一下实际使用中踩过的坑。这几个问题几乎每个人都会碰到顺序排一下方便排查。5.1 目标内核必须提供 BTFCO-RE 成立的第一前提是目标内核有 BTF。你程序写得再对加载器也读不到/sys/kernel/btf/vmlinux那就没有布局信息可查。排查方法非常直接ls -l /sys/kernel/btf/vmlinux如果文件不存在说明内核没开CONFIG_DEBUG_INFO_BTFy。有些精简发行版为了省空间会把这个配置关掉。这种情况要么换内核要么在构建时携带一份外部 BTF 文件再用 libbpf 提供的自定义 BTF 路径加载。特别要注意即使你是在带 BTF 的机器上编译目标机器没有 BTF程序照样跑不起来。5.2 字段存在性检查不能省访问一个字段前先想清楚这个字段是不是所有目标内核都有比如较新内核里task_struct有__state字段旧内核没有。如果你的代码直接访问task-__state在旧内核加载时libbpf 会在目标 BTF 里找不到__state然后直接报错加载失败。正确做法是用字段存在性重定位if (bpf_core_field_exists(task-__state)) { int state; bpf_core_read(state, sizeof(state), task-__state); /* 新内核逻辑 */ } else { /* 旧内核逻辑 */ }bpf_core_field_exists()在编译期会生成一条字段存在性的重定位记录加载时由 libbpf 判断字段是否存在并把结果写成立即数 0 或 1让程序走对应的分支。这样同一个.o就能同时兼容新旧内核。需要提醒的是vmlinux.h本身来自你编译时用到的内核。如果你手上只有旧内核的vmlinux.h连task-__state这个表达式都写不出来更别谈兼容新内核了。所以做跨版本兼容时vmlinux.h尽量取较新内核的版本。5.3 -g 别乱去掉这个前面提过但值得再强调一遍。CO-RE 重定位记录依赖 clang 在-g模式下生成。有人为了减小.o体积把-g去掉结果.BTF.ext段消失所有自动定位退化为编译时固定偏移程序回到换个内核就崩的状态。这里给个经验值BPF 程序的.o也就几十 KB-g带来的体积增量完全可接受和它换取的可移植性相比不值一提。5.4 没有 BTF 的机器也能救一下虽然目标内核最好自带 BTF但如果实在跑在没有 BTF 的老内核上还有一个后备方案使用外部 BTF 文件。内核社区有现成的 BTF 存档项目你可以下载目标内核版本对应的 BTF 文件放在自己的程序包或镜像里加载时让 libbpf 用这个文件替代/sys/kernel/btf/vmlinux。还能进一步裁剪用bpftool gen min_core_btf从完整 BTF 里只抽取程序用到的类型生成一个小得多的 BTF 文件方便分发。这是一个很实用的降级手段但要注意外部 BTF 的版本必须和目标内核精确匹配否则布局信息是错的重定位结果也会跟着错。5.5 常见报错快速定位表实际加载时libbpf 的报错信息已经相当友好只要知道它在说什么就能很快定位报错关键字含义处理方向vmlinux BTF is not found内核没有提供 BTF检查CONFIG_DEBUG_INFO_BTF或使用外部 BTFfailed to resolve CO-RE relocation找不到字段或类型检查字段存在性补bpf_core_field_exists或版本分支field not found字段在目标 BTF 中不存在确认访问的字段确实存在于目标内核invalid mem access修正后指令仍访问非法地址检查访问方式是否该用bpf_probe_read_kernel6. 我的几个结论和实践习惯6.1 自动定位的本质是三步协作回头看CO-RE 自动定位的原理可以压缩成三句话编译器记录访问意图内核通过 BTF 暴露布局加载器在运行期把意图换算成具体数字并改写指令。每一条指令里的偏移都只是临时值真正有效的是.BTF.ext里那句我要访问 task_struct.comm。目标内核变成什么样加载器就按什么样算程序本身不动。理解这一点之后你遇到 CO-RE 相关报错时就不会慌因为问题只可能出现在三个环节要么程序编译时没生成重定位信息要么目标内核没给出 BTF要么加载器无法完成某一类重定位。6.2 写 BPF 程序的第一天就养成 CO-RE 习惯我现在写 BPF 程序已经默认把所有结构体访问都走bpf_core_read、BPF_CORE_READ这套 CO-RE 宏而不是图省事直接解引用。理由不是炫技而是成本低、收益高多写几个宏换来的是程序在多内核上能直接跑不用每次升级都重新编译。这里说的重新编译不只是构建机上跑一下的事情还包括维护多个版本产物、重新分发、重新验证。省掉这一整条链路比多敲几个字母值太多。6.3 自动定位不能解决所有问题也得说清楚 CO-RE 的边界。它解决的是内核本身布局变化的问题但如果你的 BPF 程序想读取的是内核模块里的自定义结构体或者某些没有进入全局 BTF 的类型自动定位就无从谈起。这类场景要么给模块单独准备 BTF要么放弃 CO-RE。另外CO-RE 只是保证加载时的偏移正确并不保证你的访问方式在内核里安全。随便读一个没有判空、没有probe_read的地址verifier 该拒还是拒运行期该崩还是崩。不要把 CO-RE 当成程序写对的替代品。6.4 一个我还在用的验证习惯最后分享一个让我少踩很多坑的习惯不要让 CO-RE 的自动适配替代多内核实测。我会在 CI 里准备两三个不同大版本内核的虚拟机或容器镜像把同一个.o丢上去做冒烟测试确认加载成功、关键字段能读到预期值。原因很简单CO-RE 自动定位再智能也只是避免了逐版本编译并不能保证你的代码逻辑在所有版本上都有意义。有些字段在老内核上的语义、取值范围可能完全不同这种情况不是偏移问题而是语义问题只能靠实测暴露。在实际排障中bpftool prog dump xlated可以把你加载后、经过重定位的最终指令 dump 出来。我遇到自动定位结果不对的怀疑时第一件事就是看这个确认指令里的偏移是不是我预期的新偏移。看到那个数字确实被改对了剩下问题基本就都在业务逻辑上了。