深入理解XDP核心上下文xdp_md：字段解析与工程实践指南

1. 为什么说 xdp_md 是 XDP 程序的“最小上下文”

写 eBPF XDP 程序的人，第一眼看到 struct xdp_md *ctx 这个参数时，十有八九会愣一下。它不像 struct sk_buff 那样自带一堆协议指针和缓存信息，也不像 struct pt_regs 那样直接暴露寄存器现场，它看起来就是六个 __u32 字段，挤在一张不到 24 字节的“卡片”里。但这张卡片恰恰是 XDP 程序唯一能拿到的上下文信息，搞不懂它，后面所有代码都是空中楼阁。

我最近在把几个 XDP 程序从 5.4 内核适配到 6.8 内核，顺便给团队写了一篇内部文档，把 xdp_md 从字段含义到报文解析、从踩坑到调试链路整理了一遍。有人问“XDP 程序不就是要处理包吗，直接给我网卡发来的指针不就行了，为什么还包一层结构体？”这个问题问到点子上了，xdp_md 的设计初衷就是：它是 eBPF 虚拟指令集和真实内核数据结构之间的“翻译层”。

XDP 挂载在网卡驱动里，在 sk_buff 还没分配、甚至没有进入协议栈之前就运行。此时内核手里只有一块原始内存页，里面是一帧网络数据。如果直接把 struct xdp_buff * 塞给 BPF 程序，问题就来了：BPF 指令集不能随意访问任意内核内存，verifier 也无法保证你访问的内存一定在包范围内。于是内核抽象出 xdp_md，只暴露当前上下文里最关键的几个数字：数据在哪、数据到哪、元数据在哪、从哪个网卡哪个队列进来的。

它的定位很像电影院给你的一张座位票：上面不写影厅的完整建筑图纸，只写“你在 3 排 5 座，入口在左边”，你顺着这个信息就能找到座位，又不会被卷进整栋楼的安保系统。这也是 XDP 能跑这么快的根基之一——程序能碰的东西被压缩到极致，verifier 审查起来也快。

如果你正在读《深入理解 eBPF 与可观测性》这类书，或者从可观测性角度研究 XDP，你会发现很多高级用法到最后都绕不开 xdp_md 的字段语义。它不复杂，但细节非常多：哪些字段什么时候能读、哪些字段需要配合特定返回码、data 和 data_end 到底是偏移量还是指针、元数据区怎么用。下面我按自己的使用顺序，把这些细节一个个拆开。

1.1 它和 sk_buff 的根本差异

先澄清一个最常见的误区：xdp_md 不是 sk_buff 的简化版，它的存在前提是“没有 sk_buff”。XDP 程序运行在网卡驱动收到包、把 DMA 数据映射到内存页之后，在 netif_receive_skb 之前。这个节点上，数据是一整块干净的 page，没有协议栈的额外封装，没有 netfilter 钩子，没有路由表查询。

sk_buff 是协议栈内部的“万能背包”，里面有 head、data、tail、end 四个指针指来指去，还有 protocol、cb[48] 这种辅助字段，甚至可以通过 bpf_skb_load_bytes 这类 helper 跨区间读数据。而 xdp_md 只有两个真正指向包内容的字段：data 和 data_end，中间这段就是完整的一帧报文。你不需要关心 skb 里的各种偏移量，因为 XDP 阶段根本没有这些概念。

这个差异带来一个直接后果：在 XDP 里你不能用处理 sk_buff 的习惯去调用 bpf_skb_store_bytes 或 bpf_skb_change_tail，想改包只能用 bpf_xdp_adjust_head、bpf_xdp_adjust_tail、bpf_xdp_adjust_meta 这几个 helper，或者直接改 data 和 data_end 之间的内容。理解这一点，你就知道为什么所有 XDP 教程都在强调“直接报文访问”（Direct Packet Access），而不是“通过 helper 读包”。

1.2 结构体定义与每个字段的来历

打开内核头文件 include/uapi/linux/bpf.h，你会看到这样一段定义：

c复制struct xdp_md {
    __u32 data;
    __u32 data_end;
    __u32 data_meta;
    __u32 ingress_ifindex;  /* rxq->dev->ifindex */
    __u32 rx_queue_index;   /* rxq->queue_index  */
    __u32 egress_ifindex;   /* txq->dev->ifindex */
};

注意这里有个非常反直觉的设计：data、data_end、data_meta 在结构体里声明成 __u32，但在 BPF 程序里你几乎总是把它们当作指针来用。我最早写 XDP 代码时直接写 ctx->data 然后就想解引用，结果编译过了，verifier 直接报错。原因在于，这个 __u32 只是“用户态视角的声明”，内核在实际加载程序时，会把它们翻译成 xdp_buff 里真正的指针值。BPF 字节码层面，你看到的是一个 64 位的标量值，但 verifier 会给它打上 PTR_TO_PACKET 类型标签，允许你在通过边界检查的前提下做解引用。

六个字段的来历：

• data / data_end：数据区的起止偏移。data 指向帧的起始位置（通常是 Ethernet 头），data_end 指向数据区末尾。两者之差就是当前 XDP 程序可见的包长。
• data_meta：元数据区的起点。它和 data 之间夹着一段额外的头部空间，由之前执行的 XDP 程序通过 bpf_xdp_adjust_meta 预留。默认情况下 data_meta 等于 data，也就是没有元数据。
• ingress_ifindex：包进入的网卡 ifindex。用于路由、策略判断、防欺骗等场景。
• rx_queue_index：网卡收包队列的索引。配合 RSS（Receive Side Scaling）做 per-queue 统计、CPU 亲和性判断非常好用。
• egress_ifindex：5.6 内核之后新增的字段，表示发送方向网卡的 ifindex。它只在特定上下文里有效（例如 XDP_TX 或 BPF_PROG_TEST_RUN 里做回包测试时），普通收包路径读它是没有意义的。

字段不长，但每一个展开都能讲一堆东西。下面我先从 data / data_end 这两位主角讲起，因为它们是解析报文的底气所在。

2. 拿着 xdp_md 安全地拆报文：data / data_end 实操

XDP 程序 90% 的工作都是“看一看包里的内容，然后决定放行、丢弃还是转发”。而这个“看”的动作，靠的就是 data 和 data_end。我见过太多人第一次写 XDP 解析逻辑时，直接写 struct ethhdr *eth = (void *)ctx->data; 然后放心大胆地访问 eth->h_proto，结果一加载就被 verifier 拒绝：R0 invalid mem access 'inv'。

这不是代码写得不对，而是没有理解 verifier 的边界检查机制。

2.1 偏移量还是指针？先把这个概念掰清楚

很多材料说 ctx->data 是“指向包头的指针”，这没错，但容易让人忽略一个关键点：在 eBPF 的上下文模型里，data 被当作一个 packet 类型的指针来跟踪，verifier 会记录它指向的区域以及这个区域的大小。你必须通过和 data_end 的显式比较，让 verifier 相信“你确实要访问的这块内存没有越界”，它才肯给你放行。

看下面这段最常见的前缀：

c复制void *data = (void *)(long)ctx->data;
void *data_end = (void *)(long)ctx->data_end;

这里为什么要写 (void *)(long)？因为 ctx->data 是 __u32，直接当作指针在 64 位内核上语义不清。先转成 long 再转成 void *，是 libbpf 生态里的标准写法，Cilium、Facebook 的代码里也都是这么写的。后面所有访问都必须在这个“指针 + 上界”的框架下完成。

拿到指针之后，第一件事就是做第一个边界检查：

c复制struct ethhdr *eth = data;
if ((void *)eth + sizeof(*eth) > data_end)
    return XDP_DROP;

这行代码的含义是：我要把 data 这个位置解读为 struct ethhdr，那它至少要能容纳 sizeof(struct ethhdr) 这么多字节。只有这个条件成立，verifier 才会允许你访问 eth->h_dest、eth->h_proto。整个 XDP 程序里，每一次新的协议头访问，都要重复一次“声明 + 边界比较”的步骤，直到你对所有要用的字段都完成了保护。

2.2 三段式校验：从以太网头拆到四层端口

下面给一个我反复在用的解析模板，目标是从包里面提取 UDP 目的端口。它覆盖了从 L2 到 L4 的完整链路，也把几个容易漏掉的细节都标出来了：

c复制#include <linux/bpf.h>
#include <linux/if_ether.h>
#include <linux/ip.h>
#include <linux/udp.h>
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_endian.h>

SEC("xdp")
int xdp_udp_dst(struct xdp_md *ctx)
{
    void *data = (void *)(long)ctx->data;
    void *data_end = (void *)(long)ctx->data_end;

    struct ethhdr *eth = data;
    if ((void *)eth + sizeof(*eth) > data_end)
        return XDP_DROP;

    if (eth->h_proto != bpf_htons(ETH_P_IP))
        return XDP_PASS;

    struct iphdr *ip = (void *)eth + sizeof(*eth);
    if ((void *)ip + sizeof(*ip) > data_end)
        return XDP_DROP;

    if (ip->ihl < 5)
        return XDP_DROP;
    if ((void *)ip + ip->ihl * 4 > data_end)
        return XDP_DROP;

    if (ip->protocol != IPPROTO_UDP)
        return XDP_PASS;

    struct udphdr *udp = (void *)ip + ip->ihl * 4;
    if ((void *)udp + sizeof(*udp) > data_end)
        return XDP_DROP;

    if (bpf_ntohs(udp->dest) == 53)
        return XDP_PASS;

    return XDP_DROP;
}

char LICENSE[] SEC("license") = "GPL";

说几个值得注意的点：

第一，判断 h_proto != ETH_P_IP 时必须用 bpf_htons 而不是直接比较，因为报文里存的是网络字节序。很多人在这里踩坑，把 ETH_P_IP 直接拿来和 eth->h_proto 比，结果永远匹配不上，程序看着没逻辑错误但就是不过滤任何包。

第二，ip->ihl < 5 这个检查特别容易被漏掉。ihl 表示 IP 头长度，单位是 4 字节，最小合法值就是 5。如果不检查，直接拿它做乘法，可能算出负值或异常值。我在生产环境里见过一个程序就因为这个被攻击者构造畸形 IP 头绕过了 DDoS 防护逻辑。

第三，struct iphdr 默认按 4 字节对齐声明，而实际报文里 IP 头就正好是 20 字节的整数倍，所以直接访问理论上没问题。但如果你要访问带选项的 IP 头，或者后面要拆 TCP 头，建议把所有协议结构体都声明成 __attribute__((packed))，让编译器处理可能出现的非对齐访问，避免 verifier 报 alignment 错误。

2.3 verifier 边界检查的脾气

verifier 对 data / data_end 的跟踪是“路径敏感”的。它会把每个分支里你做的比较记录下来，然后在对应的路径上更新可访问范围。比如：

c复制if ((void *)ip + sizeof(*ip) > data_end)
    return XDP_DROP;
/* 从这里开始，verifier 知道 ip 到 data_end 至少有 sizeof(*ip) 字节 */

一旦你在这个分支之后访问 ip->protocol，它就会检查这个访问是否在已知的可访问范围内。如果通过了，就放行；如果之前少做了一个边界比较，它会在加载时拒绝程序。

这个机制带来一个实际约束：不要在同一个分支里跳过边界检查，也不要试图用“反正包不会那么短”这种理由欺骗 verifier。它不吃这一套。更坑的是，它有时候会在更早的位置报错，让你以为是某个字段有问题，实际上是前面的比较写错了。我自己的习惯是：每解析一层头，就立刻在一次 if + return 里完成边界检查，然后才访问字段，这样错误定位起来最快。

另外，data_meta 的边界规则比较特殊。verifier 认为元数据区是 [data_meta, data) 这段，你访问元数据时，需要用 data 作为上界，而不是 data_end。这也是新手常常搞反的地方。

3. 被人忽略的 data_meta、ifindex 与 tx_port

data 和 data_end 是 XDP 主菜，但 xdp_md 后面四个字段才是区分“会用 XDP”和“玩得转 XDP”的分水岭。我见过很多人在 XDP 程序里只用了 data 和 data_end，其他字段全程没读过，一方面说明程序简单，另一方面也说明 xdp_md 的潜力被浪费了。

3.1 data_meta：XDP 到 TC 的“栈顶传参”

data_meta 是 xdp_md 里最容易被忽视、也最有工程价值的字段。它允许 XDP 程序在报文真实数据之前预留一小段空间，写入自定义元数据，然后当包通过 XDP_PASS 进入协议栈、最终到达 TC 层的 eBPF 程序时，TC 程序可以读取这段元数据，实现“XDP 算一次、TC 复用结果”的协作模式。

这个机制我特别喜欢，它相当于函数调用里的“调用者保留寄存器”：XDP 程序是调用者，TC 程序是被调用者，data_meta 就是那个共享的寄存器窗口。典型用法是 XDP 阶段做协议解析、算完哈希或者打了时间戳，TC 阶段直接用，避免重复解析。

XDP 程序中预留元数据的标准写法：

c复制#define META_SIZE 16

struct meta_info {
    __u64 pkt_ts;
    __u32 hash;
    __u32 flags;
};

SEC("xdp")
int xdp_with_meta(struct xdp_md *ctx)
{
    void *data = (void *)(long)ctx->data;
    void *data_end = (void *)(long)ctx->data_end;
    void *meta = (void *)(long)ctx->data_meta;

    /* 预留 META_SIZE 字节的元数据空间 */
    if (bpf_xdp_adjust_meta(ctx, -(int)META_SIZE) != 0)
        return XDP_DROP;

    /* adjust_meta 之后要重新取 data / data_meta */
    data = (void *)(long)ctx->data;
    data_end = (void *)(long)ctx->data_end;
    meta = (void *)(long)ctx->data_meta;

    if ((void *)meta + sizeof(struct meta_info) > data)
        return XDP_DROP;

    struct meta_info *mi = meta;
    mi->pkt_ts = bpf_ktime_get_ns();
    mi->hash = 0;
    mi->flags = 0;

    return XDP_PASS;
}

几个关键点：

bpf_xdp_adjust_meta 的负数参数表示向包前部“撑开”空间。传入 -16，data_meta 会向低地址移动 16 字节，data 保持不变，于是 [data_meta, data) 这段就是新预留的元数据区。实参为正数则是把元数据区收回，多用于包在 XDP 内被二次处理后对称清理。

调用 helper 之后必须重新读取 ctx->data 和 ctx->data_meta。因为原始上下文里的值在调用后可能已经失效，verifier 也不会允许你继续用旧的指针。这是 XDP 编程里非常经典的一个坑，忘了刷新指针，轻则 verifier 拒绝，重则读到旧地址的脏数据。

元数据区的上界是 data，不是 data_end。data 指向真实报文开头，元数据区就夹在它前面。校验时用 (void *)meta + sizeof(*mi) > data，如果 meta 和 data 之间不够 16 字节，说明预留失败或者元数据不完整，必须丢弃。

TC 侧读取元数据时，程序类型变成了 BPF_PROG_TYPE_SCHED_CLS，上下文是 __sk_buff，但你可以通过 bpf_skb_load_bytes 或者直接读 ctx->data_meta 来拿到同样的区域。注意 TC 程序里访问元数据也要做边界检查，上界仍然是 data。两段程序配合好了，整个收包路径的性能能省不少。

3.2 ingress_ifindex / rx_queue_index 的工程价值

ingress_ifindex 是接收网卡的 ifindex，rx_queue_index 是网卡接收到这个包时使用的 DMA 队列编号。这两个字段平时不起眼，但在多队列服务器上特别有用。

我做过一个按队列做负载统计的 XDP 程序，逻辑很简单：每收到一个包，就用 rx_queue_index 作为数组索引，给对应的 per-CPU 计数器加一。这样可以直观地看到多队列网卡的哈希分配是否均衡。如果某个队列计数特别高，而其他队列几乎为 0，说明 RSS 配置有问题，流量全压在一个 CPU 上了，这时候用 ethtool -L eth0 调整队列数或者修改哈希字段，能立刻看出效果。这个诊断手段比反复看 ethtool -S 和 mpstat 要直接得多。

ingress_ifindex 在防欺骗场景也很实用。比如一个 XDP 防火墙程序，如果发现包声明的源 IP 属于某个内网网段，但 ingress_ifindex 对应的不是内网网卡，直接丢。这类“源 IP + 入接口”联合校验，是我在做云主机安全组时最常用的手段。

3.3 egress_ifindex / tx_port：什么时候才能读

egress_ifindex 是 5.6 内核引入的字段，语义是“发送方向的网卡 ifindex”。它最大的特点就是：在普通收包路径上读它没有任何意义。

这个字段的真正用途集中在两种场景。第一种是 XDP_TX 回包场景，程序收到包后把包从原网卡发回去，此时 egress_ifindex 等于 ingress_ifindex；第二种是 BPF_PROG_TEST_RUN 模式下测试 XDP 程序，内核会为测试程序构造一个 egress 上下文，此时可以读它拿到发送网卡的信息。5.6 之前没有这个字段，很多想在 XDP 里拿发送网卡的程序只能靠 map 手动配置，麻烦得很。

到了 6.6 左右的内核，这个字段被改名为 tx_port，语义更准确，功能一脉相承。如果你的代码要跨内核版本编译，记得用 LINUX_VERSION_CODE 或者 BTF 做字段名兼容。别小看这个改名，我见过有人在 6.8 内核上编译 5.4 时代的老代码，报 invalid mem access 'ctx' 找了一天，最后发现是结构体字段对不上。

4. 一个完整示例：用 xdp_md 实现按队列流量统计

理论讲了这么多，不如直接把一个能跑的程序贴出来。这个示例我用来做网卡多队列健康检查，功能是统计每个 RX 队列收到的包数量、字节数以及 UDP 包数量。它把 xdp_md 里 data、data_end、rx_queue_index 三个字段全用上了，代码量不大但覆盖了大多数人需要的模式。

4.1 程序骨架与关键代码

先定义统计用的 per-CPU 数组 map，原因很简单：XDP 程序运行在软中断上下文，可能多个 CPU 同时执行同一个程序实例，如果只用普通数组 map，计数器会互相覆盖，必须自己处理并发；per-CPU 数组自带 CPU 维度隔离，更新时不需要锁，用户态读取时只需要把所有 CPU 的值累加即可。

c复制#include <linux/bpf.h>
#include <linux/if_ether.h>
#include <linux/ip.h>
#include <linux/udp.h>
#include <bpf/bpf_helpers.h>
#include <bpf/bpf_endian.h>

#define MAX_RX_QUEUES 64

struct queue_stats {
    __u64 packets;
    __u64 bytes;
    __u64 udp_packets;
};

struct {
    __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY);
    __uint(max_entries, MAX_RX_QUEUES);
    __type(key, __u32);
    __type(value, struct queue_stats);
} qstats SEC(".maps");

SEC("xdp")
int xdp_queue_stats(struct xdp_md *ctx)
{
    void *data = (void *)(long)ctx->data;
    void *data_end = (void *)(long)ctx->data_end;
    __u32 queue = ctx->rx_queue_index;

    if (queue >= MAX_RX_QUEUES)
        return XDP_PASS;

    __u32 key = queue;
    struct queue_stats *st = bpf_map_lookup_elem(&qstats, &key);
    if (!st)
        return XDP_PASS;

    __u64 pkt_len = (__u64)(unsigned long)(data_end - data);
    st->packets += 1;
    st->bytes += pkt_len;

    /* UDP 协议识别，只测 IPv4 */
    struct ethhdr *eth = data;
    if ((void *)eth + sizeof(*eth) > data_end)
        return XDP_PASS;

    if (eth->h_proto == bpf_htons(ETH_P_IP)) {
        struct iphdr *ip = (void *)eth + sizeof(*eth);
        if ((void *)ip + sizeof(*ip) <= data_end &&
            ip->ihl >= 5 && ip->protocol == IPPROTO_UDP) {
            st->udp_packets += 1;
        }
    }

    return XDP_PASS;
}

char LICENSE[] SEC("license") = "GPL";

这段代码有几个细节值得讲：

• 我在拿 data_end - data 计算包长之前，并没有做任何边界检查。这是安全的，因为 data_end 和 data 本身都是 verifier 确认的 packet 指针，两者相减得到标量长度，不涉及解引用，verifier 允许。但这个值不要直接参与 data_end 之外的内存运算。
• 统计 map 的更新放在了解析之前，而且把 UDP 识别放进了 if 分支里。这样即使包不完整或者不是 IP/UDP，计数也已经完成，不会因为解析失败而漏掉包。
• 所有不认识的、不需要处理的包全部 XDP_PASS，保持业务透明。只有你确认要丢弃的包才 XDP_DROP，这是 XDP 程序的基本素养，不然挂上去网络就断了。

4.2 编译、加载与验证

编译用 clang 加 BPF 目标：

bash复制clang -O2 -g -Wall -target bpf -c xdp_stats.c -o xdp_stats.o

注意一定要开 -O2，不开优化的话生成的 BPF 字节码里可能有太多无用指令，verifier 复杂度超限直接拒绝。-g 是为了生成 BTF 信息，方便 bpftool 调试。

加载方式我用 ip 命令自带的 XDP 基础设施：

bash复制# native 模式，要求网卡驱动支持 XDP
ip link set dev eth0 xdp obj xdp_stats.o sec xdp

# 如果驱动不支持，退回 generic 模式
ip link set dev eth0 xdpgeneric obj xdp_stats.o sec xdp

native 模式和 generic 模式的区别我用一个自己的实际观察说：native 模式在驱动收包路径里跑，性能最好，甚至能达到线速处理；generic 模式其实是在内核协议栈入口 netif_receive_skb 里模拟一个 XDP 上下文，代码逻辑一样，但性能差一个数量级。我做过一次粗测，同一台机器上 native 模式轻松跑满 10G 网卡，generic 模式每包多花几百纳秒，吞吐掉一半都不止。所以你调试功能可以用 xdpgeneric，线上必须用 native。

查看统计结果需要一点用户态代码，或者直接用 bpftool 配合临时 map 导出。最简单的验证方式：

bash复制bpftool prog show
bpftool map dump name qstats

bpftool 会把 per-CPU 数组每个 CPU 的值都列出来，把全部 CPU 的 packets 加起来，和网卡 ethtool -S eth0 里的收包计数做个对照。如果数值接近（通常会有少量因为驱动 GRO、XDP 自身跳过等原因造成的差异），说明程序工作正常。

5. 我从这些 bug 里把 xdp_md 彻底弄懂了

光看代码不踩坑，理解总是差一层。下面这四类问题是我在这几个月的适配和重构过程中真实遇到过的，每一个都让我对 xdp_md 的理解深了一点。

5.1 把 data 当裸指针用：verifier 教做人

我最早犯的错很有代表性。当时想快速做一个按 IP 白名单过滤的 XDP 程序，我图省事，直接写：

c复制struct iphdr *ip = (void *)(long)ctx->data + 14;
if (ip->protocol == IPPROTO_TCP) { ... }

结果加载失败，verifier 报 invalid access to packet。我当时的反应是：“我已经加 14 了，为什么还说我越界？”后来才明白，verifier 的边界跟踪是基于你比较过的范围，不是基于你的“常识”。你做了 ip + sizeof(*ip) > data_end 的比较，它才知道 ip 这个位置往后有至少一个 iphdr 的空间。否则即使你只访问一个字节，它也认为可能越界。

修正后的写法就是第二节里的三段式校验。这件事给我的启发是：XDP 的边界检查不是一个形式，而是一种对 verifier 的“承诺兑现”。你承诺访问的范围不超过 data_end，verifier 才允许你访问。少一个检查，相当于承诺没兑现，整个程序就会被拒。

5.2 bpf_trace_printk 打不出数：格式串的坑

调试 XDP 程序时，最常用的手段是 bpf_trace_printk，把上下文信息打到 /sys/kernel/debug/tracing/trace_pipe。但它的限制比想象中多。

首先，格式串最多支持三个附加参数。多传一个，llvm 会编译报错，或者运行时直接忽略。其次，格式串里的 %d、%u、%x 之类的占位符，传给 BPF helper 的参数类型必须匹配，否则打印出来全是乱码。更隐蔽的是：如果你把 ctx->rx_queue_index 这种 __u32 以 %d 打印没问题，但把指针值 data 以 %p 打印，很多内核上不支持，需要先转成 __u64。

我的经验是：尽量少在热路径里用 trace_printk，它虽然方便，但会大幅拖慢收包性能。调试完就必须移除。如果确实需要观察线上行为，优先用 per-CPU map 记录计数，用户态轮询展示。这比打印每一包高效得多，也符合可观测性工程的标准姿势。

5.3 统计结果莫名偏少：多队列、大包与 generic 模式的干扰

我把队列统计程序挂到测试机上，发现一个诡异现象：qstats 里的总包数比 ethtool -S 的收包计数少了约 3%。排查过程走了不少弯路，最终定位到三个因素叠加：

第一，多队列分配不均衡。测试机网卡开 8 个队列，但 RSS 的哈希字段配置成了只哈希源 IP，测试流量恰好是一两个客户端打进来的，结果大部分包落在同一个队列，其他队列几乎空闲。这不是程序 bug，但会让 per-queue 统计看起来“某队列包数异常”。解决方法是调整 ethtool -X 的哈希字段，让流量分布更均匀。

第二，XDP 对超大帧的处理限制。如果网卡开启了 LRO（Large Receive Offload）或收到大于单页的 jumbo frame，老内核上 XDP 可能拿不到完整数据，或者直接跳过 XDP 路径进入协议栈。统计程序看到的包数自然会少于网卡计数。5.18 之后内核引入了 XDP multi-buff 支持，但需要网卡驱动配合。遇到这种场景，先确认网卡收包模式，再决定 XDP 程序如何处理分片帧。

第三，generic 模式和 native 模式的路径差异。我一开始为了调试方便用 xdpgeneric 挂载，后来切到 native 模式，发现计数行为也不完全一样。原因很简单：generic 模式下程序在 netif_receive_skb 里执行，有些包在到达协议栈之前已经被驱动层处理掉了；native 模式在驱动 DMA 完成之后立刻执行，看到的包更接近原始流量。所以线上统计必须用 native 模式，generic 只配做功能验证。

5.4 完整排查链路：从 xlated 到 trace_pipe

如果 XDP 程序加载失败或者行为异常，我的排查链路是固定的，这里分享给大家：

第一步，看 verifier 报错。加载失败时，内核会打印详细的拒绝原因，包括指令编号和变量状态。比如 off=0 size=4 end_of_packet access 通常意味着边界检查缺失，R2 type=ctx expected=fp 则是指针类型不匹配。这些信息基本能定位 80% 的问题。

第二步，dump 翻译后的指令：

bash复制bpftool prog dump xlated name xdp_queue_stats

这会打印经过 verifier 校验的 BPF 指令序列，能看出你的边界比较是否真的被跟踪到了，哪条指令引发了拒绝。xlated 和原 C 代码有对应关系（配合 -g 生成的 BTF），基本能找出问题行。

第三步，看运行时 trace。确认程序成功加载但行为不对时，打开 trace_pipe：

bash复制cat /sys/kernel/debug/tracing/trace_pipe

这里会输出 bpf_trace_printk 的表现（如果还有的话）。注意需要 root 权限，并且内核开启了 CONFIG_DEBUG_FS 和 CONFIG_BPF_SYSCALL。

第四步，看 map 内容变化。程序跑了一段时间后，dump map 看计数是否符合预期。这一步能快速区分“程序没执行”和“程序执行了但逻辑不对”两种情况。

这套排查链路我屡试不爽，推荐每个写 XDP 的人都把 bpftool 用熟。- 它不只是加载工具，更是俯视 eBPF 程序内部状态的显微镜。

6. 关于 xdp_md 的版本演进与一点性能体会

最后聊聊 xdp_md 在内核版本演进中的变化，以及我在实际部署中的一些性能体感。这些东西不写在大多数教程里，但写 XDP 程序的人早晚会遇到。

6.1 内核版本差异：5.4 / 5.6 / 6.6

我最早接触 XDP 是在 5.4 内核上，那时候 xdp_md 只有五个字段，没有 egress_ifindex。当时想在 XDP 里拿到发送网卡信息，只能通过查 map 或者直接从 ingress_ifindex 猜，很别扭。

5.6 内核加入了 egress_ifindex，配合 BPF_PROG_TEST_RUN 和 XDP_TX 回包场景，编程模型完整了不少。我后来写的一个回包检测程序就是靠它拿到了正确的发送网卡。

6.6 左右内核把 egress_ifindex 改名成 tx_port。对老代码的兼容性处理建议是：在头文件里做一次条件编译，探测 tx_port 字段是否存在；或者干脆不要直接访问这个字段，改用 bpf_xdp_metadata 相关 kfunc 从 XDP 帧里拿信息，这样对版本更不敏感。

另外，6.x 内核里 bpf_xdp_adjust_meta 的行为在一些边界场景下更严格了，比如预留元数据后如果包被 XDP_REDIRECT 到其他设备，元数据是否保留、是否清零，不同版本有不同的细粒度语义。写这类代码时一定多看当前内核的 bpf.h 注释和 tools/testing/selftests/bpf 里的测试用例。

6.2 和 __sk_buff、xdp_buff 的关系

搞清楚 xdp_md 和另外两个结构体的关系，能帮你快速定位很多问题。

struct xdp_md 是 BPF 程序看见的“用户态契约”，它经过 verifier 特殊处理，data 等字段可以当指针用。struct xdp_buff 是驱动层和内核 XDP 核心代码之间传递数据的真实结构体，它包含 data、data_end、data_meta、data_hard_start 等指针，以及 frame_sz、flags 这些 BPF 程序看不到的信息。BPF 程序访问 xdp_md 字段时，内核会按照偏移映射到 xdp_buff 对应成员上。

struct __sk_buff 则是 TC 层 eBPF 程序的上下文，它同样是一层抽象，但背后的 sk_buff 要复杂得多。有个记忆技巧：xdp_md 是“包在手心、裸数据随便看”，__sk_buff 是“包在背包里，你得先拉开放行条”。两者中间靠 data_meta 传递少量元数据，这就是前面说的传话筒机制。

6.3 性能数字与优化方向

我在多队列 10G 网卡上做过一个简单的 XDP 计数程序测试，只做 data / data_end 读和 map 更新，native 模式大约能跑到 400 万到 600 万 PPS，具体取决于包大小