4、核心数据结构：ibv_context、ibv_pd、ibv_mr、ibv_qp、ibv_cq的创建与销毁

RDMA编程模型中，ibv_context、ibv_pd、ibv_mr、ibv_qp、ibv_cq是五个最核心的抽象对象。它们分别对应设备上下文、保护域、内存注册、队列对和完成队列，构成了RDMA应用从“打开设备”到“收发数据”的完整生命周期。理解这些对象的创建顺序、依赖关系、销毁规则以及常见陷阱，是编写可靠RDMA程序的基础。本章将逐一拆解这五个数据结构的职责、创建与销毁API、典型参数，并结合实际代码片段和排障案例，帮助读者建立清晰的内存与资源管理模型。

上图展示了五个核心对象之间的依赖关系。可以看到，ibv_context是所有操作的基础，ibv_pd是资源隔离的边界，ibv_mr和ibv_cq分别服务于内存和完成通知，而ibv_qp则是数据收发的核心引擎。下面逐一深入讲解。

4.1 ibv_context：设备访问的入口

核心原理：ibv_context代表一个已打开的RDMA设备（如InfiniBand HCA或RoCE网卡）的句柄。它封装了设备的能力、端口信息、固件状态等。所有后续的资源创建（PD、CQ、QP）都必须基于一个有效的context。在verbs API中，ibv_open_device()通过ibv_get_device_list()获取设备列表后，选择目标设备打开。

操作流程：

1. 调用ibv_get_device_list()获取可用设备数组。
2. 遍历设备，通过ibv_get_device_name()或ibv_get_device_guid()匹配目标设备。
3. 调用ibv_open_device()打开设备，返回struct ibv_context *。
4. 使用完毕后，调用ibv_close_device()关闭，并调用ibv_free_device_list()释放设备列表。

struct ibv_device **dev_list;
struct ibv_context *ctx = NULL;
int num_devices;

dev_list = ibv_get_device_list(&num_devices);
if (!dev_list) { /* 错误处理 */ }

for (int i = 0; i < num_devices; i++) {
    if (strcmp(ibv_get_device_name(dev_list[i]), "mlx5_0") == 0) {
        ctx = ibv_open_device(dev_list[i]);
        break;
    }
}
if (!ctx) { /* 设备打开失败 */ }

// ... 使用ctx ...

ibv_close_device(ctx);
ibv_free_device_list(dev_list);

4.2 ibv_pd：资源隔离与权限控制

核心原理：保护域（Protection Domain）是RDMA资源（MR、QP、AH等）的逻辑容器。同一PD内的资源可以相互访问，不同PD间的资源默认隔离。这为多租户或多应用场景提供了安全边界。创建PD使用ibv_alloc_pd()，销毁使用ibv_dealloc_pd()。

关键参数与行为：

案例拆解：在一个多线程服务器中，每个工作线程处理不同的客户端连接。如果所有线程共享一个PD，则任何线程都可以访问其他线程注册的内存，存在安全隐患。更合理的做法是：每个线程（或每个客户端会话）分配独立的PD，确保内存隔离。但要注意，PD数量过多会消耗内核资源，通常建议按业务模块划分，而非按连接划分。

4.3 ibv_mr：内存注册与访问权限

核心原理：RDMA网卡直接访问主机内存（DMA）时，需要提前将内存区域注册到网卡，并获取L_Key（本地键）和R_Key（远程键）。ibv_mr就是注册内存区域的句柄。注册时需指定内存地址、长度和访问权限（如IBV_ACCESS_LOCAL_WRITE、IBV_ACCESS_REMOTE_WRITE等）。

操作流程：

1. 分配内存缓冲区（如用posix_memalign或malloc，建议页对齐）。
2. 调用ibv_reg_mr(pd, addr, length, access_flags)。
3. 成功后，通过mr->lkey和mr->rkey获取键值。
4. 使用完毕后，调用ibv_dereg_mr(mr)注销。

struct ibv_mr *mr;
char *buf;
int buf_size = 4096;

posix_memalign((void**)&buf, 4096, buf_size);
mr = ibv_reg_mr(pd, buf, buf_size, 
                IBV_ACCESS_LOCAL_WRITE | IBV_ACCESS_REMOTE_READ);
if (!mr) { /* 注册失败 */ }

// 使用 mr->lkey 和 mr->rkey 进行后续操作

ibv_dereg_mr(mr);
free(buf);

4.4 ibv_cq：完成队列的创建与销毁

核心原理：完成队列（Completion Queue）用于异步通知应用程序其发送/接收请求已完成。每个CQ可以关联多个QP，但一个QP的发送队列和接收队列必须关联到同一个CQ（或分别关联到不同CQ，但通常使用同一个）。创建CQ使用ibv_create_cq()，销毁使用ibv_destroy_cq()。

关键参数：

• cqe：CQ的容量（可容纳的完成事件数）。建议设置为QP队列深度的1.5~2倍，避免溢出。
• channel：完成事件通道（struct ibv_comp_channel *），可以为NULL，表示不使用事件通知，而是轮询。
• context：用户自定义上下文，可通过ibv_get_cq_event()获取。

struct ibv_cq *cq;
struct ibv_comp_channel *channel = NULL; // 使用轮询模式

cq = ibv_create_cq(ctx, 256, NULL, channel, 0);
if (!cq) { /* 创建失败 */ }

// 轮询完成事件
struct ibv_wc wc;
int n = ibv_poll_cq(cq, 1, &wc);
if (n > 0) {
    // 处理 wc.status, wc.opcode 等
}

ibv_destroy_cq(cq);

4.5 ibv_qp：队列对的创建与销毁

核心原理：队列对（Queue Pair）是RDMA通信的核心，包含一个发送队列（SQ）和一个接收队列（RQ）。创建QP需要指定PD、CQ、发送/接收队列深度、QP类型（如RC、UC、UD）等。创建后，QP处于RESET状态，需要依次经历INIT、RTR、RTS状态才能开始收发数据。

创建流程：

1. 填充struct ibv_qp_init_attr结构体。
2. 调用ibv_create_qp(pd, &qp_init_attr)。
3. 修改QP状态（ibv_modify_qp()）至RTS。

struct ibv_qp_init_attr attr = {
    .send_cq = cq,
    .recv_cq = cq,
    .cap = {
        .max_send_wr = 128,
        .max_recv_wr = 128,
        .max_send_sge = 1,
        .max_recv_sge = 1,
    },
    .qp_type = IBV_QPT_RC,
};

struct ibv_qp *qp = ibv_create_qp(pd, &attr);
if (!qp) { /* 创建失败 */ }

// 修改QP状态到RTS（需要填充ibv_qp_attr）
// ...

ibv_destroy_qp(qp);

案例拆解：QP创建失败排查

某应用在创建QP时返回EINVAL错误。排查过程如下：

• 检查max_send_wr和max_recv_wr是否超过设备能力（通过ibv_query_device()获取）。
• 检查max_send_sge和max_recv_sge是否超过设备限制。
• 确认send_cq和recv_cq是否有效，且CQ深度足够。
• 确认QP类型是否被设备支持（如RoCE网卡通常支持RC和UD，但不支持UC）。

最终发现是max_send_wr设置为256，而设备最大支持128，导致失败。调整后正常。

4.6 资源生命周期管理最佳实践

核心原则：创建顺序与销毁顺序严格相反。创建时：context → pd → (mr, cq) → qp。销毁时：qp → cq → mr → pd → context。任何违反顺序的操作都会导致资源泄漏或未定义行为。

对比表：五种资源的创建/销毁API

总结复盘：在实际项目中，建议封装一个资源管理类（如RdmaResourceManager），统一管理上述对象的创建和销毁，并在析构函数中按逆序释放。同时，利用ibv_query_device()在初始化时校验设备能力，避免运行时错误。对于长时间运行的服务，定期检查资源使用情况（如通过ibv_query_qp()查询QP状态）有助于提前发现泄漏。