最近在做某个RDMA子系统的控制面功能验证，正好推进到“队列管理 + 连接建立”这一环，也就是这个系列文档的第58篇对应的实测阶段。RDMA说白了就是绕过内核和CPU，让数据直接从一端网卡搬到另一端应用内存，但真正把它跑通，从创建一块内存区域到两个节点之间建立起一条可靠的传输连接，中间涉及的保护域、内存注册、队列对、完成队列、状态机迁移这一整套控制面逻辑，才是日常开发里最容易翻车的地方。这篇博客就把我这轮功能测试的用例设计、执行过程、踩过的坑和排查思路完整记录下来，给正在做RDMA驱动适配，或者想把队列模型彻底吃透的朋友做个参考。
RDMA的队列管理是整个传输体系的地基。发送队列、接收队列、完成队列，它们各自的创建参数、生命周期、状态迁移，直接决定了上层应用能不能稳定地收发数据。而连接建立则是把“队列资源”和“物理链路”串起来的关键动作：两端各自把QP推到RTR、RTS状态，参数的匹配性、状态机的合法性、硬件响应行为都会在这个阶段集中暴露。所以这轮测试我没有急着上带宽压测，而是先老老实实把队列管理和连接建立的功能路径走了一遍。
1. 为什么单独测“队列管理 + 连接建立”
1.1 队列管理是整个RDMA控制面的地基
RDMA能实现高吞吐、低延迟，依赖的是硬件直接访问应用内存，但硬件怎么知道该访问哪块内存、该把数据放到哪个队列？这些都要靠控制面提前配置好。Queue Pair（QP）是收发队列的组合体，Completion Queue（CQ）负责上报完成信息，Memory Region（MR）承载实际的数据缓冲区，Protection Domain（PD）则把这些资源圈在同一个信任边界里。
如果这一层没有验证到位，后续所有性能测试都是在沙地上盖楼。比如QP创建时队列深度配小了，高并发场景下直接丢WR；CQ深度不足，业务量一大就溢出；MR注册权限不对，远端读写根本进不来。这些问题在功能测试阶段最容易定位，因为现场简单、变量少，一旦到了性能测试阶段，问题会被大量并发请求淹没。
1.2 连接建立是控制面逻辑的试金石
连接建立这条链路，本质上是一次“两端控制面参数的完整握手”。从RESET到INIT，从INIT到RTR，再从RTR到RTS，每一步都要下发一堆属性：端口号、P_Key、MTU、对端QP号、初始PSN、目的LID/GID、超时重传参数等。
任何一个字段不匹配，硬件都会给出错误完成事件，或者底层重传机制不停重试。也就是说，连接建立是把队列管理的所有资源串起来跑一遍的最佳场景。它能验证的不只是QP状态机本身，还包括CQ能不能正确产生完成项、MR能不能被硬件正确解析、PD作用域是否真的起到了隔离作用。
1.3 功能测试和性能测试的分工
我见过不少团队一上来就跑perftest，ib_write_bw一拉，带宽数据很好看，但换个应用场景立刻出问题——因为perftest这种工具帮你把队列参数都配置好了，你根本没机会去看控制面细节。
功能测试要回答的是“能不能用”，性能测试回答的是“好不好用”。队列管理和连接建立属于前者，它要在最小配置、最典型路径下证明资源生命周期完整、状态迁移合规、首包收发成功。这个基础打不牢，后面做拥塞控制、多QP调度、可扩展性分析都会很痛苦。
2. 测试环境准备：硬件、软件栈与拓扑
2.1 软硬件选型
这轮测试用的是两台同配置的服务器，直连背靠背，不经过交换机。这么做是为了先把链路层面的变量降到最低——交换机上的流控、PFC配置、MTU不一致等问题留到后续再单独验证。
硬件是某厂商支持RoCE的网卡，固件和驱动都是当前测试分支的版本。软件栈用的是常见的OFED套件，用户态走libibverbs接口。特别说明一下，libibverbs之上的librdmacm（CM）封装层次太高，这轮测试没有直接用，而是自研了一个小的控制程序，走传统的带外参数交换方式。原因后面在第4章细说。
2.2 链路状态检查
动手写代码之前，先把链路状态确认一遍。用ibv_devinfo看设备能力，确认端口是ACTIVE状态，速率和宽度符合预期。再用ibstat看物理端口状态，确保网线、模块、协商都正常。
这一步看起来简单，但确实是很多问题的源头。有一次我折腾了半天QP一直建不上，最后发现是网线松动导致端口降速，设备端口根本没到active状态。虽然驱动不会报错，但硬件内部的端口状态决定了QP能否被成功迁移到RTR/RTS。
检查命令类似这样：
ibv_devinfo -d <device> ibstat <device>2.3 链路层数据面确认
在跑队列管理测试前，先确认最基本的RoCE数据面能否通。最简单的方法是用ibv_ud_pingpong这类工具跑一下UD模式的数据报收发。UD模式的状态机要求和RC不同，它不需要走到RTR，但只要UD能通，至少说明物理链路、GID配置、端口属性这些基础条件是好的。
不过要注意，UD通不代表RC一定通。RC多了一堆可靠性机制：PSN校验、重传排序、接收端RNR处理，这些是UD完全不涉及的。所以在UD验证通过后，RC连接建立相关测试才有意义。
3. 队列管理核心资源与关键参数剖析
3.1 PD与MR：内存保护边界
PD（Protection Domain）本质上是资源所有权分组。一个PD下可以挂多个QP、MR、AH（Address Handle）。不同PD之间的资源不能互相引用，比如用PD A创建的QP去访问PD B下的MR，硬件会直接拒绝。这个设计有点像进程的地址空间隔离，只不过它是在RDMA硬件层面强制执行的。
MR注册时最关键的是权限位。本地写、远端读、远端写、远端原子操作等权限都是独立位。常见坑是把远端写权限和本地写权限搞混：本地写权限只影响本端CPU能否通过这个MR地址写内存，远端写权限才是给对端网卡用的。如果申请了远端写但没加IBV_ACCESS_REMOTE_WRITE，对端发过来的RDMA Write就会被硬件丢弃，错误表现还很隐蔽。
3.2 QP创建：队列深度与属性取舍
QP创建时有两组最重要的参数：cap.max_send_wr / cap.max_recv_wr / cap.max_inline_data，以及qp_type（RC、UC、UD等）。
队列深度不是随便填的。创建时驱动会向硬件申请对应大小的内存资源，如果填得太大，设备内存不够会直接创建失败；填得太小，业务峰值一到就会返回ENOMEM。通常工程经验是取一个“超过预期峰值并发数”的值，比如预期同时下发32个WR，那么队列深度给64比较稳。max_inline_data则决定了小包能否直接嵌入WQE，省掉一次额外的内存访问，跑低延迟场景时尤其值得关注。
QP类型的选择也要提前想清楚。RC适合可靠字节流，UD适合多对一通信但不可靠，UC虽然可靠但不对顺序做保证。这轮测试主打连接建立，所以以RC为主要验证对象。
3.3 CQ：完成事件是队列管理最直观的反馈通道
CQ在队列体系里承担“结果汇报”的角色。发送完成、接收完成、错误完成，全部以CQE的形式出现在CQ里。应用有两种消费方式：轮询（ibv_poll_cq）和事件（ibv_get_cq_event）。
轮询适合低延迟场景，因为CPU一直盯着CQ看，拿到完成项立刻处理；事件模式适合高吞吐后台处理，CPU可以先干别的，有完成事件再唤醒。但事件模式如果处理不及时，CQ里的队列项越积越多，最终可能导致CQ溢出，此时设备会进入错误状态。
CQ深度一般建议大于等于关联QP的发送队列深度加接收队列深度之和，或者按厂商建议放大到某个倍数。如果多个QP共享同一个CQ，深度还要加上裕量。下面这张表列出了常见参数的取值逻辑，供参考。
| 资源 | 关键字段 | 建议策略 |
|---|---|---|
| PD | 无 | 一个应用域一个PD，不要全局共用 |
| MR | access_flags | 按需申请权限，别动不动就给远端写 |
| CQ | cqe | 建议大于等于所有关联QP的SQ+RQ之和 |
| QP | max_send_wr | 取峰值并发WR数的2倍以上 |
| QP | qp_type | 功能测试首选用RC，简单可控 |
3.4 QP状态机：连接建立前的必经路径
RC类型的QP状态机必须走RESET -> INIT -> RTR -> RTS这条路径才能正常收发。
RESET是出厂状态，此时QP不参与任何通信。第一次modify到INIT时，需要指定端口号、P_Key索引、枚举值必须和IBV_QPS_INIT一致。INIT状态下，QP还不会真正收发数据，但硬件已经知道这个QP将绑定在哪个端口上。接着modify到RTR，这一步要填对端的QP号、初始PSN、目的LID/GID、路径MTU、接收端内存的RKEY和虚拟地址。最后从RTR到RTS，需要配置超时重传参数、重试次数、RNR重试次数等。
每一步迁移如果参数不合格，ibv_modify_qp会返回错误码，配合errno和驱动扩展错误信息基本能定位。状态机的验证要做到位：要走合法路径，也要故意尝试非法迁移，比如从RESET直接跳到RTS，确认驱动和硬件都能正确拒绝。
4. 连接建立功能测试实操记录
4.1 为什么不用CM而走带外参数交换
librdmacm这套CM库确实方便，rdma_create_id、rdma_resolve_addr、rdma_connect三件套就能建连。但它的封装把很多细节藏起来了：QP内部状态怎么迁的、PSN怎么协商的、哪些参数用了默认值，外部根本看不见。
这轮测试的目标恰恰是验证控制面细节，所以我选择了传统方式：两端各自创建资源和状态迁移，通过一个独立的TCP通道交换QPN、LID、GID、PSN、RKEY等参数。这样的好处是每个参数都可以人为指定，也能人为注入错误，方便验证异常分支。
4.2 测试用例总览
整个队列管理和连接建立测试分成四组用例：资源创建合法性、状态迁移正确性、首包收发完整性、异常路径防护。具体如下表所示。
| 用例编号 | 测试点 | 操作方式 | 预期结果 |
|---|---|---|---|
| TC01 | 资源创建全流程 | 创建PD、注册MR、创建CQ、创建QP | 所有资源句柄正确返回 |
| TC02 | 非法状态迁移拒绝 | 尝试RESET直接到RTS | modify返回错误，QP状态不变 |
| TC03 | 带外参数交换后建连 | TCP交换QPN/GID/PSN，双端迁移到RTS | 双端成功进入RTS |
| TC04 | 双向SEND首包 | 两端各post一个SEND，轮询CQ | CQE状态为SUCCESS，数据内容匹配 |
这四组用例跑通后，控制面主线基本就算稳定了。后续再做RDMA Write/Read、原子操作、断链重连时，可以在这个基础上扩展。
4.3 双端资源初始化流程
两端代码逻辑完全一样，先创建PD、注册MR、创建CQ、创建QP。创建QP时的初始化属性用一个典型配置，队列深度我给了64，内联数据量先保持默认，因为首包测试用不到大内联。关键调用顺序大概是：
struct ibv_pd *pd = ibv_alloc_pd(ctx); struct ibv_mr *mr = ibv_reg_mr(pd, buf, size, IBV_ACCESS_LOCAL_WRITE | IBV_ACCESS_REMOTE_WRITE); struct ibv_cq *cq = ibv_create_cq(ctx, 128, NULL, NULL, 0); ibv_create_qp(pd, &qp_init_attr);注意MR的权限位。即使首包测试只用了SEND操作，不涉及远端读写，我仍然把REMOTE_WRITE加上是为了后续扩展测试用例时不用重新注册。但这只是测试环境做法，生产环境建议按最小权限原则来。
资源创建完成后，用ibv_query_port拿到本端LID和GID信息，再决定要交换哪些参数。RoCEv2环境下LID不一定关键，但GID是必须的。GID索引要选对，尤其是多网卡或多IP场景，选错索引会导致建连后首包根本发不出去。
4.4 握手参数交换与QP状态迁移
参数交换用TCP带外通道完成。客户端连上服务端的TCP端口后，双方交换以下信息：本端QP号、本端LID、源GID索引及GID内容、初始PSN、接收缓冲区地址和RKEY。
这个PSN需要多说一句。虽然PSN可以由应用任意指定，但两端协商时必须一致，否则硬件在接收端做序列号校验时会直接丢弃报文。大多数实现里，发送端的初始PSN就是接收端期望的对端初始PSN，这个字段必须在握手时对齐。
交换完成后，双端各自执行状态迁移。我先迁到INIT，再迁到RTR，最后迁到RTS。每次modify成功后，用ibv_query_qp查询回来的属性做校验，包括状态、路径MTU、端口号、目标QP号等。这一步很关键，因为某些硬件看起来modify成功了，但实际属性落到硬件时被改写了，靠query才能发现。
4.5 双向首包发送与CQ校验
进入RTS后，双端各自预先post一个接收WR到接收队列，然后各发一个SEND报文，携带一段固定pattern的数据。发送完成后，轮询CQ，检查CQE的status字段，并校验收到的数据内容是否为预期的pattern。
这个测试设计成双向同时发，是为了验证两端QP都在真实收发路径上工作，而不是一端正常另一端靠运气。实际执行时，两端都能在CQ里看到成功的发送完成项和接收完成项。通过这个用例，可以确认队列资源创建、参数协商、状态迁移、数据面首包全链路都正常。
5. 实测问题排查与心得
5.1 QP状态迁移失败：先从返回参数查起
这轮测试里最常遇到的是modify失败。比如从INIT往RTR迁移时，返回EINVAL，通常代码里看不出来问题，需要把modify时传入的属性逐个印出来，和对端交换的参数表对照。
我踩过的具体坑有两个：一个是路径MTU两端不一致，本端设了4096，对端实际只有2048，硬件直接拒绝迁到RTR；另一个是P_Key索引填了一个无效值——虽然在很多简单配置里P_Key是默认值，但索引不能随便填，必须对应端口上实际存在的分区表项。
排查这类问题建议打开驱动的调试日志，或者在每次modify失败后立刻打印errno和厂商扩展错误码。厂商扩展错误码往往能直接告诉你是哪个字段非法，比自己瞎猜高效得多。
5.2 首包一直不完成：CQ和事件机制的坑
首包测试时出现过一个诡异现象：发送端已经显示完成，接收端CQ里却一直等不到接收完成项。一开始怀疑是内存权限问题，查了半天，最后发现是接收端根本没有提前post接收WR。
RDMA的接收端必须预先用ibv_post_recv把接收缓冲区挂到RQ上，硬件收到对端数据时才能往内存里写。如果RQ里没有接收WR，对端会触发RNR重传，表现为对端发送侧CQ迟迟不出现完成项，或者出现错误完成事件。这个设计很像生活中的信箱逻辑：你得先把空信封放进信箱，邮差才能把信投进去。
5.3 状态同步问题：双端必须同时就绪
连接建立最忌讳“一端已经RTS，另一端还在INIT”。此时先就绪的一端发送首包，对端根本不会响应，重传定时器不断触发，最终以超时错误结束。
排查时会看到发送端CQ出现本地队列错误之类的状态，但根因其实在对端没有及时迁到RTR。这个问题的处理方式是设计一个简单的屏障机制：双方都确认自己进入RTS后，再统一触发首包发送。测试工具里这个屏障一定要做好，否则会把正常的业务逻辑误判成控制面缺陷。
5.4 常见问题速查
我把这轮测试中典型的异常现象、原因和排查手段整理成一张速查表，方便后续直接对照：
| 异常现象 | 可能原因 | 排查方向 |
|---|---|---|
| modify返回EINVAL | 参数字段非法或两端不一致 | 打印全部modify属性，逐项比对 |
| 发送侧超时重传 | 对端未进入RTR，或收到RNR | 检查对端状态机和接收WR |
| 首包数据不对 | MR注册权限不全或地址错误 | 核对RKEY、缓冲区地址、权限位 |
| CQ溢出 | CQ深度小于实际并发完成数 | 调大CQ深度，检查是否有CQ事件残留 |
| 一直等不到接收完成 | 接收端没有提前post接收WR | 检查接收队列的WR数量和回调逻辑 |
5.5 测试工具设计上的建议
如果自己写队列管理测试程序，建议从一开始就把“可观测性”当成一等公民。每个关键接口调用之后，把返回码、errno、厂商扩展错误码、以及修改后的QP属性完整记录下来。这轮测试里我就在每次modify后调用ibv_query_qp打印当前状态，定位问题时节省了大量时间。
日志带上时间戳和双端标识，条件允许的话把驱动日志同步打开。整个过程里还有一个值得推荐的手段：在关键节点人为注入错误。比如故意把PSN改错、故意不post接收WR、故意设置不一致的MTU，确认系统能给出预期的错误而不是挂死。这才是功能测试真正有价值的部分。
我个人在这轮测试里最大的体会是，RDMA队列管理和连接建立的复杂度不在代码量，而在隐藏的时序约束和参数间的隐性依赖。很多问题看起来是数据面异常，根子都在控制面。把状态机每一步的输入输出都搞清楚，把每个完成事件的语义都确认到位，比盲目调优有意义得多。希望这篇记录对正在做类似验证工作的同行有帮助。
