4、核心数据结构：ibv_context、ibv_pd、ibv_mr、ibv_qp、ibv_cq等关键对象的作用与创建流程

RDMA编程模型中，用户态通过libibverbs库与内核驱动交互，而这一切的起点是一系列核心数据结构。这些对象并非简单的内存结构体，而是贯穿verbs API、内核驱动与硬件网卡（HCA）的资源抽象。理解这些对象的职责边界、生命周期与依赖关系，是编写可靠RDMA应用的基础。本章将逐一剖析ibv_context、ibv_pd、ibv_mr、ibv_qp、ibv_cq等关键对象，并给出完整的创建流程与实战注意事项。

4.1 核心对象的作用与依赖关系

RDMA编程中，每个对象都承担着明确的职责，且对象之间存在严格的依赖关系。理解这些关系是正确使用verbs API的前提。

4.1.1 ibv_context：设备访问的入口

ibv_context代表一个打开的设备上下文，是用户态与内核驱动通信的桥梁。它封装了设备文件描述符、设备能力信息以及内核态对应的ib_ucontext。每个进程可以打开多个设备上下文，但通常一个进程只需要一个。创建该对象时，内核会分配设备相关的资源，并建立用户态与内核态之间的通道。

struct ibv_context *ctx = ibv_open_device(device_list[i]);
if (!ctx) {
    fprintf(stderr, "Failed to open device %s\n", device_list[i]->name);
    return -1;
}
printf("Device opened: %s, fd=%d\n", ctx->device->name, ctx->cmd_fd);

4.1.2 ibv_pd：资源保护域

保护域（Protection Domain）是RDMA资源隔离的边界。同一PD下的QP、MR、AH等资源可以相互访问，不同PD之间的资源默认不可互操作。PD本身不占用硬件资源，但它是所有资源归属的根节点。创建PD后，后续创建的MR、QP、AH都必须关联到该PD。

4.1.3 ibv_mr：内存注册

ibv_mr描述一段已注册的内存区域。RDMA网卡访问内存前，必须先将该内存区域注册到PD下，获得L_Key（本地键）和R_Key（远程键）。L_Key用于本地QP访问该内存，R_Key用于远程节点访问。注册过程中，内核会锁定物理内存页并建立DMA映射，因此注册的内存不能被换出。

struct ibv_mr *mr = ibv_reg_mr(pd, buf, size, 
                                IBV_ACCESS_LOCAL_WRITE | 
                                IBV_ACCESS_REMOTE_READ | 
                                IBV_ACCESS_REMOTE_WRITE);
if (!mr) {
    fprintf(stderr, "Failed to register MR\n");
    return -1;
}
printf("MR registered: lkey=0x%x, rkey=0x%x\n", mr->lkey, mr->rkey);

4.1.4 ibv_cq：完成队列

ibv_cq用于存放WQE（工作队列元素）的完成状态。每个QP可以关联一个发送CQ和一个接收CQ，也可以共享同一个CQ。CQ的深度（cqe数量）决定了能够缓存的完成事件数量。当CQ满时，新的完成事件会被丢弃，导致QP进入错误状态。

4.1.5 ibv_qp：队列对

ibv_qp是RDMA通信的核心执行单元，包含发送队列（SQ）和接收队列（RQ）。QP的状态机包括RESET、INIT、RTR、RTS等状态，必须按顺序迁移。QP关联PD、CQ以及可选的SRQ（共享接收队列）。创建QP时需指定QP类型（RC、UC、UD等），不同类型决定了通信语义。

4.2 创建流程与状态迁移

对象的创建顺序有严格依赖：必须先有context，才能创建pd；pd创建后才能注册mr和创建qp；cq可以独立创建，但qp必须绑定cq。下面给出标准创建流程。

4.2.1 标准创建步骤

1. 获取设备列表：调用ibv_get_device_list()获取可用HCA列表。
2. 打开设备：选择目标设备，调用ibv_open_device()获得ibv_context。
3. 查询设备能力：调用ibv_query_device()获取设备属性（最大QP数、CQ深度等）。
4. 创建PD：调用ibv_alloc_pd()创建保护域。
5. 注册内存：调用ibv_reg_mr()注册发送/接收缓冲区。
6. 创建CQ：调用ibv_create_cq()创建完成队列。
7. 创建QP：调用ibv_create_qp()创建队列对，并关联PD和CQ。
8. QP状态迁移：依次执行ibv_modify_qp()将QP从RESET迁移到INIT、RTR、RTS。

// 创建QP的完整示例
struct ibv_qp_init_attr qp_init_attr = {
    .send_cq = cq,
    .recv_cq = cq,
    .qp_type = IBV_QPT_RC,
    .cap = {
        .max_send_wr = 64,
        .max_recv_wr = 64,
        .max_send_sge = 1,
        .max_recv_sge = 1,
    }
};
struct ibv_qp *qp = ibv_create_qp(pd, &qp_init_attr);
if (!qp) {
    fprintf(stderr, "Failed to create QP\n");
    return -1;
}
printf("QP created: qp_num=0x%x\n", qp->qp_num);

4.2.2 QP状态机详解

QP状态迁移是RDMA编程中最容易出错的部分。RC类型QP必须经历以下状态：

• RESET：初始状态，QP不处理任何WQE。
• INIT：允许提交WQE到SQ，但不会发送数据包。
• RTR（Ready to Receive）：允许接收数据包，需指定对端QPN和LID。
• RTS（Ready to Send）：允许发送数据包，通信正式开始。

4.3 实战案例：多QP共享CQ与PD

在实际高性能场景中，通常需要创建多个QP来提升并发度。合理的资源规划可以显著降低内存开销和硬件资源消耗。

4.3.1 场景描述

某分布式存储系统需要建立16条RC连接，每条连接独立收发数据。初始方案为每个连接创建独立的PD、CQ和QP，结果发现内存占用过高且CQ中断频繁。优化方案采用共享PD和共享CQ策略。

4.3.2 优化方案

// 共享PD和CQ，创建多个QP
struct ibv_pd *shared_pd = ibv_alloc_pd(ctx);
struct ibv_cq *shared_cq = ibv_create_cq(ctx, 1024, NULL, NULL, 0);

for (int i = 0; i < 16; i++) {
    struct ibv_qp_init_attr attr = {
        .send_cq = shared_cq,
        .recv_cq = shared_cq,
        .qp_type = IBV_QPT_RC,
        .cap = { .max_send_wr = 128, .max_recv_wr = 128 }
    };
    struct ibv_qp *qp = ibv_create_qp(shared_pd, &attr);
    // 保存qp指针到数组
    qps[i] = qp;
}

4.3.3 结果对比

4.4 常见误区与最佳实践

通过分析大量生产环境中的问题，以下误区最为常见：

4.4.1 误区一：忽略设备能力限制

每个HCA都有最大QP数、最大CQ深度、最大MR数量等限制。创建资源前必须查询设备能力，否则可能因资源耗尽而失败。

struct ibv_device_attr dev_attr;
ibv_query_device(ctx, &dev_attr);
printf("Max QP: %d, Max CQ: %d, Max MR: %d\n",
       dev_attr.max_qp, dev_attr.max_cq, dev_attr.max_mr);

4.4.2 误区二：内存注册后修改缓冲区

MR注册后，内核会锁定物理内存页。如果应用修改缓冲区大小或释放内存，会导致DMA操作访问非法地址。正确做法是：注册前分配固定大小的内存，通信结束后再注销MR并释放内存。

4.4.3 误区三：CQ深度设置过小

CQ深度决定了能够缓存的完成事件数量。如果CQ满，新的完成事件会被丢弃，导致QP进入错误状态（SQ/QQ errors）。建议CQ深度设置为所有关联QP的WQE总和，并预留20%余量。

4.4.4 最佳实践总结

• 资源复用：多个QP共享PD和CQ，降低资源消耗。
• 内存对齐：注册的内存建议按页对齐（4KB），避免跨页开销。
• 错误处理：每次verbs调用后检查返回值，失败时打印errno。
• 资源释放：按逆序释放资源：QP → CQ → MR → PD → context。
• 调试技巧：使用ibv_debug_level环境变量开启详细日志。

掌握这些核心数据结构的创建与管理，是构建高性能RDMA应用的基础。下一阶段将深入探讨Send/Receive操作的WQE构造与完成处理流程。