企业官网建设流程全解析

1. 接收队列不是“自动收货”：ib_post_recv 在 RDMA 栈里的真实位置

第一次接手一个内核态 RDMA 接收端的时候，我盯着一个“对端明明发了，本端 CQ 上什么都没有”的现象排查了整整两天，最后发现问题不在硬件、不在交换机，而在于我把ib_post_recv()当成了一件“注册完 QP 就会自动发生”的事。这个函数的名字起得很朴素，post就是投递，recv就是接收，但它在整个 RDMA 收发模型里的地位远比字面意思重要：它是软件侧把一块已经固定住物理页的内存“抵押”给硬件的唯一入口，没有这一步，网卡收到任何东西都无处安放，只能丢弃或者报错。

所以这篇东西我打算把ib_post_recv()从内核头文件里的那几行内联代码一路拆到驱动层的 WQE 构造，中间顺带把 SGE、lkey、doorbell、RQ 环这些绕不开的概念塞进去。它不是一篇 API 手册式的罗列，而是我在实际写内核态接收模块、调驱动、追 CQE 错误码的过程中攒下来的理解顺序。适合已经能跑通一个简单 RDMA 连接、但对自己写的post_recv到底在硬件上留下了什么痕迹说不清楚的读者；也适合那些准备去读某家高性能网卡驱动源码、被post_recv回调的几百行代码劝退过的同行。读完你至少应该能做到三件事：知道这个函数每一个参数最终变成了硬件队列里的什么，知道它返回错误时问题最可能出在哪一层，知道内核版本升级后有哪些行为悄悄变了。

1.1 一个必须提前“预订”缓冲区的模型

RDMA 的接收侧跟 socket 完全不同。用 socket 的时候，数据先落到内核的接收缓冲区，应用调recv()才把数据从内核缓冲区拷到用户空间，缓冲区什么时候不够是内核的事，应用感知不到。RDMA 把这层“内核缓冲”整个拿掉了，网卡收到报文后要做的第一件事是找到一条接收 WQE（Work Queue Element），从里面读出“这块内存的物理地址、长度、访问钥匙”，然后直接把 payload 用 DMA 写进那块内存，最后在 CQ 上挂一个完成事件。

这里的因果顺序跟直觉是拧着的：不是“收到数据再找地方放”，而是“先告诉硬件地方在哪，硬件才敢收”。ib_post_recv()干的就是前半个动作。你把一块缓冲区描述成一个ib_recv_wr，链成链表递给这个函数，它转手交给驱动，驱动把它翻译成硬件队列里的若干个字节，推进生产索引，敲一下 doorbell。从这一刻起，这块内存在硬件眼里就是“可用”的，直到它被消费掉并在 CQ 上产生一条 CQE 为止，你都不能碰它。

这个模型带来两个必须记住的推论。第一，接收缓冲区的数量就是 RQ（Receive Queue）的容量上限，你 post 了多少条 WR，就最多能接多少条入站消息（不考虑多 SGE 合并成一条消息的细节）。第二，接收缓冲区的生命周期管理完全落在软件头上，泄漏了没人帮你回收，重复 post 同一块内存更是会直接把数据写花。

1.2 从 verbs 到驱动：这个函数站在哪两条路径的交汇处

从代码组织上看，ib_post_recv()属于内核 RDMA 子系统里的 verbs 层，声明在include/rdma/ib_verbs.h，实现是static inline。这点很关键，意味着它不会在vmlinux里留下一个独立的函数符号，你用 ftrace 抓不到它，用objdump反汇编某个模块时倒是能看到它被内联展开的痕迹。

它往下走通过qp->device->ops.post_recv这个函数指针跳到具体驱动，往上被rdma_rw、nvmet-rdma、rds、iser这些内核态消费者调用。所以它实际上是“宽腰”设计里的那个细腰：上层一堆协议模块只认这套 WR 结构，下层各家驱动各显神通去填自家硬件的 WQE 格式。你读源码的时候会发现上层模块几乎从不关心驱动是谁，而驱动也完全不关心上层在传什么协议，分界线就在这个函数上。

也正因为它是内联的，调试时打点会比较别扭。想看调用频次用 tracepoint 或者干脆在驱动回调里加printk；想看参数合法性，得去看头文件里的校验逻辑有没有被触发。我在排查早期问题时就吃过这个亏，一上来就去找ib_post_recv的符号地址，找了半天没找着。

1.3 先看清它的契约：参数、返回值、副作用

三个参数，qp、recv_wr、bad_recv_wr。第一个是目标 QP，必须已经创建并且处于能接受接收请求的状态；第二个是 WR 链表头，注意是链表不是单个，一次调用可以提交一串；第三个是出参，用来告诉调用方“从哪一条开始没提交成功”。

返回值只有 0 和非 0 两种语义。0 表示链表里所有 WR 都被硬件队列接纳了，非 0 表示中途失败，此时*bad_recv_wr指向第一个失败的 WR，它后面的所有 WR 都没有被处理，而它前面那些是已经成功提交的。这个“部分成功”语义是很多人踩坑的地方，看到返回非 0 就以为整批都没进去，于是重新 post 一整条链，结果前几条被重复投递，同一块缓冲区被硬件用了两次。

副作用方面，除了把 WR 写进硬件队列，还有一个容易被忽略的：它不保证内存可见性的建立顺序，但会要求调用方在此前完成 DMA 映射。也就是说，ib_dma_map_single之类的操作必须在ib_post_recv之前做完，而ib_dma_unmap_single必须等到对应的 CQE 被 poll 出来之后。这个顺序错了，在 x86 上可能因为 IOMMU 行为宽松而侥幸不出问题，换到对 DMA 一致性要求更严的平台上就是偶发的数据错乱。

2. 逐行读 ib_verbs.h：内核态 wrapper 到底做了什么

打开include/rdma/ib_verbs.h，搜ib_post_recv，你会看到一段几十行的内联函数。这几十行在不同内核版本之间差异不小，值得单独拎出来对比。我手头习惯对照的是 4.x 中期和 5.x 之后的两个形态，前者极简，后者开始承担一些保护职责。

2.1 老版本的“一行转发”与它的隐患

早期内核里这个函数短得让人怀疑人生，大意就是把三个参数原样透传给驱动的回调，然后把驱动的返回值原样返回。没有校验，没有 trace，出问题时内核不会有任何提示，错误信息全靠驱动自己打印。

这种设计的隐患不在于功能，而在于错误定位的成本被完全转嫁给了调用方。比如你写了一个 WR，num_sge填了 8，但创建 QP 时max_recv_sge只申请了 1 个，老版本里这行代码会一路走到驱动，驱动可能校验也可能不校验，有的驱动直接按 8 个 SGE 去写 WQE，把相邻的内存覆盖掉；有的驱动返回-EINVAL，但bad_recv_wr忘了填。你拿到一个-EINVAL，完全不知道是自己参数错了还是硬件资源不够。

我在早期版本上排查过一个“隔三差五崩溃”的模块，最后定位到就是max_recv_sge配小了，越界写坏了相邻的 ring buffer 元数据。那次之后我养成了一个习惯：创建 QP 时把cap.max_recv_sge按业务最大值给足，哪怕当前用不上，因为改这个参数要重建 QP，代价比浪费几字节的 WQE 空间大得多。

2.2 新版本多出来的那道 num_sge 校验

后来的内核在 wrapper 里加了参数检查，大致逻辑是：取链表头recv_wr，比较它的num_sge和qp->max_recv_sge，超了就直接把*bad_recv_wr指向它并返回-EINVAL，根本不去调驱动。

这道检查值得单独说，因为它只检查了链表头这一个 WR。也就是说，如果你 post 的是一条链，第二条 WR 的num_sge超限，这一层是拦不住的，还得靠驱动兜底。这个细节在源码里很容易被忽略，我看到过有人据此认为“wrapper 帮我做了全量校验”，然后在链式提交里踩了坑。

qp->max_recv_sge这个字段也不是凭空来的，它由 core 层在创建 QP 时根据qp_init_attr.cap.max_recv_sge和驱动上报的能力取交集后缓存到struct ib_qp里。所以你后续查这个值，得到的是“协商后的实际值”，不是“你申请的值”，两者在驱动能力不足时会不一致，这本身就可能是你 post 失败的根因。

2.3 tracepoint 为什么插在 ops 调用之后

新版实现里在驱动回调返回之后加了trace_ib_post_recv(qp, recv_wr)。位置很讲究：放在调用之后，意味着只有真正进了驱动才会留下记录；返回非 0 的路径上是否记录，取决于代码怎么写的分支，通常失败会提前 return，所以 trace 只反映“成功递交”的那部分。

这个 tracepoint 在我实际调试里非常有用。用perf record -e ib_post_recv或者 tracefs 里打开对应事件，能看到每次投递的 QP 号、WR 数量、SGE 数量。有一次我怀疑某个上层模块在疯狂地单条 post 而没有批量，抓了十秒钟的 trace 一看，果然平均每次只投 1 条 WR，把 doorbell 敲成了心跳。改成一次链 16 条之后，那个核的 CPU 占用从接近满掉到了个位数百分比。

这里给个实操提醒：tracepoint 的事件名在不同版本里可能挂在rdma_core这个 trace system 下，字段集合也随版本变化，管道脚本别写死字段名，先cat /sys/kernel/debug/tracing/events/rdma_core/*/format看一眼再用。

2.4 ib_post_recv_1 与 dma_optimized 那条支线

较新的内核把 wrapper 拆成了两层：一个带额外布尔参数的内部版本，和一个对外保持原签名的薄壳。那个布尔参数（名字里带dma_optimized）跟“直接 DMA 路径”有关，服务于那些不需要经过中间 bounce buffer、直接把设备 DMA 地址填进 WQE 的场景。

对绝大多数写内核态接收端的人来说，你调用的是外层的那个，布尔值恒为 false，你感知不到这条支线。但它存在本身说明一件事：这个函数不只是“转发”那么简单了，它开始承载“这条路径是否需要特殊地址处理”的语义。如果你的代码是从老版本迁移上来的，并且用了一些非常规的地址映射方式，升级内核后要留意这里的行为变化，别默认它还是那个纯透传的一行代码。

2.5 返回码为什么被映射成 -ENOMEM

驱动返回非 0 时，wrapper 里有些版本会做一次映射，把驱动给的错误码统一成-ENOMEM。这个处理乍看粗暴，其实是符合语义的：驱动那边post_recv失败最常见的原因就是 RQ 满了，没有空位放新 WQE，这在接口层面就等价于“资源不足”。

但问题在于，驱动也可能因为别的原因失败，比如 SGE 数量非法、lkey 无效、QP 状态不对，这些错误被统一压成-ENOMEM之后，调用方就没法区分“等一会儿再来”和“我参数写错了永远也来不了”。这个信息损失是我在实际项目里最头疼的一点。

应对办法有两层。第一层，自己在提交前把能校验的都校验一遍，num_sge、lkey非零、缓冲区长度不超过 MTU 对应的最大值，让错误尽量在自己的代码里暴露，而不是退化成-ENOMEM。第二层，出问题的时候不要只盯着返回值，去看驱动有没有额外的日志，或者用dmesg -w挂着看有没有WARN_ON之类的报警。有些驱动的路径上会有ibdev_warn输出，那才是真正的原因。

3. 数据结构深挖：ib_recv_wr 与 SGE 里的每一个字节

struct ib_recv_wr只有四个字段，看起来简单得不像一个贯穿软件栈的核心结构。但每个字段背后都有一堆隐含约定，其中两个字段的误用能直接导致数据错乱或者内存泄漏，值得一条一条抠。

3.1 wr_id：唯一一个不进入硬件的字段

wr_id是一个u64，语义上完全由调用方定义，RDMA 子系统从头到尾不解释它。你 post 的时候填什么，CQE 里就原样返回什么。它不会进 WQE，不会占硬件队列空间，纯粹是软件层的“回执凭据”。

正因为如此，它的用法几乎是自由的：可以存缓冲区指针，可以存一个索引，可以存一个打包了 ID 和标志位的小结构（只要塞得进 8 字节）。我在自己写的接收模块里习惯存一个数组下标，因为指针在 32 位内核和 64 位内核之间移植时会出问题，下标则不会；而且下标还能直接拿来查一块静态分配的元数据数组，比裸指针多一层校验。

这里有个必须提的坑：如果你用wr_id存了指针，一定要保证那块内存在 CQE 被处理之前一直有效。有人为了省事，wr_id里存了一个栈上的临时结构体地址，post 完函数就返回了，等 CQE 回来再去解引用，拿到的要么是垃圾要么直接 panic。我踩过一次类似的，表现是跑了几个小时才崩，因为栈上那块内存在此期间被别的调用复用了。

3.2 next 指针：链表语义与“部分成功”的边界

next把多个 WR 串成单向链表，链表的尾节点next必须是 NULL。这个设计让“一次系统调用提交多条 WR”成为可能，是降低 doorbell 频率、提升吞吐的基础。

但next的写法有个经典的错误：为了图快，在循环里复用同一个 WR 结构体，每次改完内容就 post 一次。这在单线程下能跑，但一旦你想批量提交，就会发现自己手里只有最后一个节点的内容，前面几次的修改全被覆盖了。正确做法是为每个待提交的 WR 准备独立的存储，通常是预分配一个数组，用下标轮转。

另一个跟“部分成功”语义直接相关的点：当驱动在中途失败时，它会设置*bad_recv_wr指向失败节点。这个节点及其之后的整条链都还归你管，你有两条路可选：要么把整条链重新组织后重试，要么只重试失败节点之后的部分。前者更简单，后者更精确。我一般选后者，因为前面已经进队列的那些 WR 对应的缓冲区不能再被投递一次，否则同一块内存会被挂两次，硬件写第一次之后，第二次写入的可能是脏数据。

3.3 sg_list 与 lkey：地址不是虚拟地址

sg_list指向一个struct ib_sge数组，每个元素三个字段：addr、length、lkey。初学者最容易误解的是addr——它不是内核虚拟地址，而是已经映射给这块设备的 DMA 地址，也就是ib_dma_map_single()的返回值。

为什么要这么设计？因为网卡不经过 MMU，它看到的地址要么是物理地址，要么是 IOMMU 转换后的地址。内核里你用kmalloc拿到的void *对它毫无意义。所以流程必须是：先分配内存（kmalloc、__get_free_pages、或者从大页池里切），再ib_dma_map_single得到 DMA 地址，把 DMA 地址填进ib_sge.addr，把映射时返回的长度填进length，lkey则来自这块内存注册成 MR 时拿到的钥匙。

lkey这一项是硬件用来做内存保护校验的。它告诉网卡“这块内存确实被授权访问，访问权限是这个钥匙定义的”。如果lkey填错、或者是用一个已经 dereg 的 MR 的钥匙，硬件在校验失败时会在 CQE 上打一个 local protection error，然后 QP 进入错误状态。这个错误的排查成本很高，因为lkey是个 32 位数字，看日志看不出对错，只能反查是哪个 MR。

实操上我的建议是：给每个接收缓冲区维护一个小结构体，把dma_addr、length、lkey、mr指针、以及当前状态（空闲/已投递/已完成）都放进去，post 之前和 poll 之后都更新状态。这么做的成本是几十字节内存，收益是出问题时能立刻定位到是哪一块。

3.4 num_sge 与 RQ WQE 的容量换算

num_sge决定这条 WR 用几个分散的缓冲区拼一条消息。多个 SGE 的存在是为了支持零拷贝的散射聚集，比如接收端想把报文头和 payload 分开放，或者想接一块非连续的大缓冲。

但它跟 QP 创建时申请的max_recv_sge是强绑定的。硬件的 RQ WQE 大小在创建 QP 时就定死了，能容纳的 SGE 数量固定，超了就写不下。不同的驱动对“超限”的处理不一样，有的返回错误，有的直接截断，后者更危险，因为你会收到一条“短了”的消息但没有任何报错。

容量换算的实际情况大概是：一个 RQ WQE 头部占若干个 16 字节的槽，每个 SGE 占一个 16 字节槽（字节数、钥匙、地址各占一部分，剩下是保留或者用于签名场景）。所以max_recv_sge每增加 1，WQE 就要多 16 字节，RQ 的总内存占用也随之增长。RQ 深度乘以单 WQE 大小，那就是你为接收队列付出的内存代价。这个账在资源紧张的环境里必须提前算清楚，我见过把max_recv_sge设成 30、队列深度设成 8192 的配置，光 RQ 就吃掉了几十 MB。

4. 落到驱动层：一个 recv WR 在硬件队列里长什么样

理解了软件层的结构，再往下就看驱动怎么把它翻译成硬件能懂的东西。各家驱动的代码风格差异极大，但骨架是共通的：上锁、循环处理每条 WR、构造 WQE、推进索引、判断是否需要敲 doorbell、解锁。下面用一个脱敏后的典型实现路径来讲，函数名用xxx_ib_post_recv代指。

4.1 RQ 环、WQE 与生产者索引

硬件的接收队列在物理上是一段连续的 DMA 内存，被组织成环形，每个槽是一个 WQE。驱动维护三个东西：环的基地址、环的深度（以 WQE 为单位）、当前的生产者索引。

“生产”这个动作就是往当前索引指向的槽里写 WQE 内容，然后索引加一（到尾部回绕到 0）。硬件侧有它自己的消费者索引，它看到生产者索引超过自己，就知道有新东西可以取了。两者之间靠 doorbell 寄存器同步，敲 doorbell 相当于告诉硬件“生产者索引更新了，来看一眼”。

这里有个隐含约束：环上的槽数（深度）就是你最多能积压的未消费 WR 数量。当生产者追上消费者，说明环满了，驱动只能返回-ENOMEM。所以-ENOMEM的本质是“环形缓冲区满”，跟系统内存一毛钱关系都没有。这个命名误导过太多人，我见过有人看到-ENOMEM就去加内存、调vm.overcommit，方向完全跑偏。

4.2 一个典型驱动的 post_recv 主循环（脱敏伪码）

下面是这类实现常见的骨架，我把跟具体厂商相关的宏和字段名都替换掉了，保留结构：

static int xxx_ib_post_recv(struct ib_qp *ibqp, const struct ib_recv_wr *wr, const struct ib_recv_wr **bad_wr) { struct xxx_qp *qp = to_xqp(ibqp); unsigned long flags; int nreq = 0; int err = 0; spin_lock_irqsave(&qp->rq.lock, flags); while (wr) { /* 1. 检查环上还有没有空槽 */ if (!xxx_rq_has_space(qp)) { err = -ENOMEM; break; } /* 2. 在当前生产索引处构造 WQE */ err = xxx_fill_recv_wqe(qp, wr); if (err) break; /* 3. 推进生产者索引 */ xxx_rq_advance(qp); nreq++; wr = wr->next; } /* 4. 有新增就敲一次 doorbell，批量只敲一次 */ if (nreq) xxx_ring_rq_doorbell(qp); /* 5. 把失败位置回填给调用方 */ if (err) *bad_wr = wr; spin_unlock_irqrestore(&qp->rq.lock, flags); return err; }

xxx_fill_recv_wqe里面做的事，大致是把每个ib_sge的addr、lkey、length按硬件要求排布进 WQE 的数据段。这里有个细节值得留意：length字段通常写的是缓冲区总长度而不是预期接收的字节数，因为接收侧并不知道对端会发多少，硬件收到多少就写多少，只要不超过这个长度。如果对端发的比这个大，硬件会截断并可能在 CQE 上标记一个 flag。

提示：有些驱动在填充 WQE 时会顺手做一次 lkey 检查（查本地的 key 表），有些则完全交给硬件。前者能在软件层提前返回错误，后者只能等 CQE 上的保护错误。别假设你用的驱动属于哪一种，读一眼就知道。

4.3 doorbell 的触发时机与批量提交

上面伪码里if (nreq)那个判断是性能的关键。doorbell 本质上是一次 MMIO 写，代价远高于普通内存写，在某些架构上甚至是几十到上百纳秒级别。一条 WR 敲一次 doorbell，和十六 条 WR 敲一次，吞吐差距可以是倍数级的。

但批量也不是无脑越大越好。批量意味着这些 WR 提交的延迟被拉长了，对延迟敏感的 RPC 类应用可能得不偿失。我在一个消息中间件场景里测过，批量 8 到 16 之间是拐点，再往上吞吐提升趋缓，而 P99 延迟已经开始明显抬头。

还有个容易踩的坑：如果你写的是上层模块，每次只 post 一条 WR，那么驱动的批量能力对你毫无意义，doorbell 该敲还是敲。所以批量的责任在调用方，不在驱动。想吃到这个红利，就得在自己的代码里攒够一批再调。攒的过程中要注意超时，不能因为等凑够数把消息压太久。

4.4 QP 状态机对 post_recv 的隐性约束

理论上讲，只要 QP 不是 ERROR 状态，post_recv都能往 RQ 里塞 WQE，硬件在 QP 进入 RTR 之后才开始真正消费它们。实践中大多数实现也确实是这样：你在 INIT 状态投递接收缓冲区，然后迁移到 RTR，硬件立刻就能开始接收。

但有两点要留意。第一，QP 进入 ERROR 之后，很多驱动会拒绝新的post_recv，因为此时 RQ 的内容已经没有意义了，硬件不会再消费。第二，某些驱动在modify_qp里会重置 RQ 的索引和状态，如果你在状态迁移之前 post 了一批，迁移过程中这批 WR 可能被丢弃。所以稳妥的做法是：在 QP 迁到 INIT 之后、迁到 RTR 之前完成首轮的接收缓冲区投递，别在状态迁移的中间穿插 post。

我遇到过一次因为顺序错了导致首批报文全部丢失的问题，表现是对端发了、本端没收到、也没有任何错误 CQE。后来把日志打全才发现，接收缓冲区是在modify_qp到 RTR 之后紧接着 post 的，而驱动的modify_qp里有一步会清空 RQ，正好把刚 post 的那批吃掉了。改了顺序就再没复现过。

5. 手写最小可跑代码：内核态收包端的一次完整提交

原理讲够了，落到能跑的代码上。下面这段是我从自己一个内核模块里抽出来的简化版，去掉了业务逻辑，只保留“分配、映射、投递、轮询、回收”这条主干。假设 QP 已经创建好、已经完成modify_qp到 INIT，max_recv_sge申请的是 1。

5.1 缓冲区分配与 DMA 映射的参数推演

先定几个参数。假定单条消息最大 4 KB，想同时挂 256 个接收缓冲区，那么需要的总内存是 1 MB。单个缓冲区的分配我用kmalloc（对 4 KB 来说够用），如果用大页池或者__get_free_pages，映射方式会略有差别。

#define RX_BUF_SIZE 4096 #define RX_BUF_CNT 256 struct rx_slot { void *buf; /* 内核虚拟地址 */ dma_addr_t dma; /* 设备可见地址 */ struct ib_mr *mr; u32 lkey; bool posted; }; static struct rx_slot rx_slots[RX_BUF_CNT]; static int rx_slots_init(struct ib_device *dev) { int i, ret; for (i = 0; i < RX_BUF_CNT; i++) { rx_slots[i].buf = kmalloc(RX_BUF_SIZE, GFP_KERNEL); if (!rx_slots[i].buf) return -ENOMEM; rx_slots[i].dma = ib_dma_map_single(dev, rx_slots[i].buf, RX_BUF_SIZE, DMA_FROM_DEVICE); ret = ib_dma_mapping_error(dev, rx_slots[i].dma); if (ret) return ret; rx_slots[i].mr = ib_get_dma_mr(pd, IB_ACCESS_LOCAL_WRITE); if (IS_ERR(rx_slots[i].mr)) return PTR_ERR(rx_slots[i].mr); rx_slots[i].lkey = rx_slots[i].mr->lkey; rx_slots[i].posted = false; } return 0; }

几个参数选择的理由：方向用DMA_FROM_DEVICE，因为这块内存是设备往里写的；ib_dma_mapping_error的检查不能省，某些平台的映射失败是通过特殊地址值返回的而不是 NULL；IB_ACCESS_LOCAL_WRITE权限必须有，硬件要往这块内存写，没这个权限会在 CQE 上报保护错误。

注意：上面每条 MR 单独创建是图省事，实际生产里通常是一个ib_get_dma_mr覆盖整个 PD，或者用ib_map_mr_sg注册一块大内存然后自己切分。前者省 MR 资源，后者省注册开销，具体看你的缓冲区来源。

5.2 组装 WR 链并调用 ib_post_recv

有了 slot 数组，投递就是构造链表。这里我用一个局部的 WR 数组来避免栈上取地址的生命周期问题：

static struct ib_recv_wr wr_ring[RX_BUF_CNT]; static struct ib_sge sge_ring[RX_BUF_CNT]; static int rx_post_batch(struct ib_qp *qp, int start, int cnt) { struct ib_recv_wr *bad = NULL; int i, ret; for (i = 0; i < cnt; i++) { int idx = (start + i) % RX_BUF_CNT; struct rx_slot *s = &rx_slots[idx]; sge_ring[idx].addr = s->dma; sge_ring[idx].length = RX_BUF_SIZE; sge_ring[idx].lkey = s->lkey; wr_ring[idx].wr_id = idx; wr_ring[idx].sg_list = &sge_ring[idx]; wr_ring[idx].num_sge = 1; wr_ring[idx].next = (i == cnt - 1) ? NULL : &wr_ring[(start + i + 1) % RX_BUF_CNT]; } ret = ib_post_recv(qp, &wr_ring[start], &bad); if (ret) { pr_err("post_recv failed at wr_id=%llu\n", bad ? (unsigned long long)bad->wr_id : ~0ULL); } return ret; }

这段代码里有三处值得展开。第一，wr_ring和sge_ring必须是静态或堆上分配，不能是栈上的局部数组，因为 WR 结构体里存了指向 SGE 的指针，而驱动在ib_post_recv返回后才可能异步去读这些内容——严格的实现会在函数内同步读完，但依赖这个假设是危险的。第二，wr_id存下标，CQE 回来直接查表，比存指针安全。第三，bad回填后我打了日志但没有重试，这是有意的，重试逻辑应该独立出来，因为要处理“前半部分已经进队列”的情况。

5.3 CQE 轮询、错误判定与 repost

收包端的循环长这样，核心是 poll 到 CQE、查状态、处理数据、repost：

static int rx_poll_loop(struct ib_cq *cq, struct ib_qp *qp) { struct ib_wc wc[16]; int n, i; while (!kthread_should_stop()) { n = ib_poll_cq(cq, ARRAY_SIZE(wc), wc); for (i = 0; i < n; i++) { int idx = (int)wc[i].wr_id; if (wc[i].status != IB_WC_SUCCESS) { pr_err("cqe err: status=%d opcode=%d vendor=%d\n", wc[i].status, wc[i].opcode, wc[i].vendor_err); continue; } /* 处理 rx_slots[idx].buf 里的数据，长度是 wc[i].byte_len */ /* repost 同一条 WR，把缓冲区还给硬件 */ ib_post_recv(qp, &wr_ring[idx], NULL); } if (!n) cpu_relax(); } return 0; }

这里的byte_len是实际收到的字节数，不是缓冲区长度，业务层要按它来截取。错误路径上我选择了continue而不是把 QP 拆掉重建，这取决于错误类型：如果是IB_WC_WR_FLUSH_ERR（QP 在排空），说明整条 RQ 都已经废了，此时 repost 没有意义；如果是单条的本地保护错误，跳过继续跑是合理的。生产代码里我一般会按status分类处理，别一把梭。

关于 repost 的时机，有个性能上的小技巧：不要逐条 repost，可以在一个 poll 循环里攒够一批再一次性投递。这跟前面讲的批量提交是一个道理，只不过发生在接收侧。我实测下来，从逐条 repost 改成每 16 条批量 repost，接收侧 CPU 占用能降三成左右。

5.4 释放路径的顺序问题

清理的顺序如果搞反，轻则 oops，重则 DMA 还在跑的时候内存已经被释放，数据写到别的地方去了。正确的顺序是：先把 QP 迁到 ERROR 状态并销毁，确保硬件不再有未完成的接收请求；然后ib_destroy_cq；接着对每个 slot 做ib_dma_unmap_single，再ib_dereg_mr，最后kfree。

这里有个容易被忽略的点：在销毁 QP 之前，要保证所有已 post 的 WR 都已经完成（成功或失败）。有些驱动的destroy_qp会帮你 flush，但 flush 之后你是否还需要处理那些 CQE，各家行为不一致。稳妥的做法是在拆之前主动把 CQ poll 干净，或者至少等一个足够长的时间窗口。

6. 排查实录：那些让 post_recv 出问题的典型场景

这部分是我这些年攒下来的“病历本”，按症状组织，不讲理论只讲怎么定位。

6.1 返回 -ENOMEM 的三种不同真相

第一种，最直白的：RQ 真的满了。你 post 的速度超过了对端发送和本端消费的速度，环被填满。这种在持续压力下必然出现，属于设计问题，要加深度或加快消费。

第二种，以为自己在 repost 其实没 repost。这个极其常见。代码里 poll 到 CQE 之后直接处理数据，处理完忘了投回去，跑一阵子 RQ 就空了，对端开始收不到确认。表现是跑一段时间后整个通道卡住，而且没有任何报错。排查办法很简单，打个计数器分别记录 post 次数和 CQE 次数，两者差值持续增长就说明有泄漏。

第三种，QP 状态导致的伪满。QP 被打到 ERROR 之后，硬件不再消费 RQ，你的 post 看起来一直成功直到环满，然后开始返回-ENOMEM。这时候如果只看返回值，会误判成“对端发太快”，实际上是对端早就不通了。所以-ENOMEM出现的时候一定要顺手查一眼 QP 状态。

6.2 CQE 上的 local protection error 从哪来

这个错误码指向的是 lkey 或权限校验失败，来源大致三类。一是lkey用错了，比如从别的 MR 复制过来，或者 MR 已经被 dereg 了还在用。二是注册 MR 时权限没给够，接收侧必须要有本地写权限。三是 DMA 映射没做，或者映射之后地址变了导致 WQE 里的地址失效。

我遇到最诡异的一次是 MR 是在进程上下文注册的，但post_recv在软中断上下文里执行，中间发生了内存热插拔，映射表变了，而代码没有监听相关事件。这种问题只在特定环境出现，本地复现不出来，最后靠加打印把dma_addr和lkey全记下来对照才定位到。

6.3 队列“看着有空位却收不到包”

这类问题的特征是：post 全部成功，CQE 一个都不来。排查顺序我通常这样走：先确认对端确实发了（在对端看 send 完成），再看本端 QP 的当前状态是不是 RTR 以上，接着查 RQ 的生产者索引是否真的推进了（有些平台需要显式的写内存屏障），最后看 doorbell 有没有真的敲出去。

有一次的根因是 doorbell 的地址算错了，写到了相邻的寄存器上，硬件不知道有新 WQE。这个错误非常隐蔽，因为写操作本身不会报错，只是写错了地方。后来我加了一个“投递后立刻回读某个状态寄存器”的校验才抓出来。

6.4 速查表

7. 版本演进与性能取舍上的几个判断

7.1 内核版本差异对照

跨版本移植内核模块时，ib_post_recv相关的差异值得提前列出来对一遍。

这张表不是让你背，是让你在升级内核后发现行为变了的时候有个对照方向。我印象最深的一次是升级之后原本“能跑”的代码开始稳定返回-ENOMEM，查了半天发现新版 wrapper 对链表头做了num_sge检查，而我那个 MR 的max_recv_sge只在创建 QP 时申请了 1，实际用的时候填了 2。之前驱动不校验所以侥幸过关，升级后立刻暴露。

7.2 RQ 深度、批量与 CPU 消耗的平衡

RQ 深度不是越大越好。深度大，抗突发能力强，但内存占用线性增长，而且 CQE 的批量回收效率反而可能下降，因为 poll 一次只拿固定条数，队列越长越容易积压。

我的经验值是这样：小消息、高并发的场景，深度给 512 到 1024，配合每批 16 条的 poll 和 repost；大消息、低频的场景，深度 64 到 128 就够，把内存省下来给数据缓冲区。这个数不是拍脑袋，是拿实际压测数据算出来的——用perf stat看每包的 CPU 周期，逐步调深度看拐点，找到曲线开始变平的那个位置。

批量这块，接收侧和发送侧的节奏要匹配。发送端批量 16，接收端每次 poll 16 条，两边节拍一致的时候 doorbell 和 CQ 的开销都能压到最低。如果一边批量一边单条，效果会大打折扣。

7.3 cache line 与预取

有个细节挺多人忽略：WR 结构体在内存里的排布会影响驱动遍历链表的效率。如果每个 WR 都跨 cache line，每次读next都可能触发一次 miss。把 WR 数组按 64 字节对齐（或者干脆用____cacheline_aligned），让一个 WR 完整落在一个或两个 line 里，实测能省下可观的周期。

同样的道理适用于 SGE 数组和接收缓冲区本身。缓冲区起始地址对齐到页边界，能让 DMA 传输走更高效的路径；SGE 数组连续排布，驱动顺序读取时预取器能帮上忙。

这类优化属于“做完正确性再做”的范畴，先保证功能对、错误处理全，再回来抠这几个百分点。我见过有人在功能都没跑通的时候就去调对齐和预取，纯属浪费时间。

再补一个小技巧：如果你怀疑瓶颈在post_recv这条路径上，可以在驱动回调的入口和出口各打一个trace_printk（注意它开销不小，只适合短时间抓），算一下单次调用的耗时分布。我上次就是靠这个发现某次调用的耗时是平时的几百倍，顺着查下去发现是锁竞争——另一个 CPU 正在同一个 QP 上做modify_qp。把状态迁移和收包路径分开之后，毛刺就消失了。

我个人在实际操作中的体会是，ib_post_recv这个函数本身简单到不值一提，真正难的是它周边那一圈约定：内存什么时候映射、什么时候释放、失败了从哪一条重试、repost 的频率怎么控制。把这几件事想清楚了，代码自然就稳；想不清楚，哪怕把源码背下来也没用。