📚 课程目录第4章内存注册API详解

4. 内存注册API详解：ibv_reg_mr、ibv_dereg_mr等函数的使用与参数

4.1 核心原理：为什么需要内存注册

RDMA网卡（HCA）通过DMA直接访问主机内存，但与传统网卡不同，HCA不经过CPU和内核协议栈，因此内核无法在每次I/O时动态建立页表映射。为了在不打断CPU的前提下安全、高效地访问用户态缓冲区，必须提前将虚拟内存区域“固定”下来，并建立虚拟地址→物理地址的映射表，同时记录该区域的访问权限。这一过程就是内存注册（Memory Registration）。

注册完成后，HCA会得到一个lkey（本地键）和rkey（远程键）。lkey用于本端QP访问该内存区域（如接收缓冲区写入），rkey则随请求发送给远端节点，用于RDMA Read/Write操作时远端验证访问权限。两者本质上是内存区域的“门禁卡”，携带错误的键值会导致访问被拒绝并产生错误事件。

关键概念：内存注册的本质是“提前锁定物理页面 + 生成访问凭据”。未注册的内存，HCA无法直接访问；注册后，内核会将该区域锁定在物理内存中，防止被换出（swap），从而保证DMA操作的安全性。

4.2 方法流程：ibv_reg_mr 与 ibv_dereg_mr 详解

libibverbs 提供了标准的内存注册与注销接口，函数原型如下：

#include <infiniband/verbs.h>

struct ibv_mr *ibv_reg_mr(struct ibv_pd *pd, void *addr,
                          size_t length, int access_flags);

int ibv_dereg_mr(struct ibv_mr *mr);

4.2.1 ibv_reg_mr 参数说明

参数	含义	注意事项
`pd`	保护域（Protection Domain）	必须与QP、AH使用同一个PD，否则无法关联
`addr`	待注册内存的起始虚拟地址	通常要求页对齐（4KB），但verbs库会内部处理非对齐情况
`length`	注册区域长度（字节）	实际锁定的页面会向上取整到页边界
`access_flags`	访问权限组合标志	常用：IBV_ACCESS_LOCAL_WRITE、IBV_ACCESS_REMOTE_WRITE、IBV_ACCESS_REMOTE_READ、IBV_ACCESS_REMOTE_ATOMIC

access_flags 关键说明：

IBV_ACCESS_LOCAL_WRITE：允许本端QP通过该MR作为接收缓冲区或本地写操作目标。若未设置，则不能用于接收。
IBV_ACCESS_REMOTE_WRITE：允许远端节点通过rkey对该区域执行RDMA Write。
IBV_ACCESS_REMOTE_READ：允许远端节点通过rkey对该区域执行RDMA Read。
IBV_ACCESS_REMOTE_ATOMIC：允许远端执行原子操作（如fetch-and-add、compare-and-swap）。

重要：如果仅用于本端发送（作为发送缓冲区），通常只需设置IBV_ACCESS_LOCAL_WRITE即可；但若该缓冲区同时要作为接收目标，则必须显式包含IBV_ACCESS_LOCAL_WRITE。许多初学者遗漏该标志导致接收请求失败。

4.2.2 ibv_dereg_mr 行为

注销操作会执行以下动作：

从HCA的地址转换表中移除该MR的映射条目；
释放物理页面的锁定状态，允许页面再次被换出；
使lkey和rkey立即失效，任何在途的RDMA操作将触发错误完成（WC status = IBV_WC_REM_ACCESS_ERR）。

注销后，mr指针不可再使用，必须置空避免悬垂指针。

4.3 案例/场景：典型注册与使用流程

以下代码展示了一个完整的注册→使用→注销流程，包含错误处理：

struct ibv_pd *pd = ibv_alloc_pd(context);
if (!pd) { /* 错误处理 */ }

// 分配并注册缓冲区
char *buf = aligned_alloc(4096, 64 * 1024);  // 64KB，页对齐
if (!buf) { /* 错误处理 */ }

struct ibv_mr *mr = ibv_reg_mr(pd, buf, 64 * 1024,
    IBV_ACCESS_LOCAL_WRITE |
    IBV_ACCESS_REMOTE_READ |
    IBV_ACCESS_REMOTE_WRITE);
if (!mr) {
    fprintf(stderr, "ibv_reg_mr failed: %s\n", strerror(errno));
    free(buf);
    ibv_dealloc_pd(pd);
    return -1;
}

printf("MR registered: lkey=0x%x, rkey=0x%x\n",
       mr->lkey, mr->rkey);

// ... 使用 mr->lkey 填充接收WR，或通过rkey发起远程访问 ...

// 注销并释放
if (ibv_dereg_mr(mr)) {
    fprintf(stderr, "ibv_dereg_mr failed\n");
}
free(buf);
ibv_dealloc_pd(pd);

典型应用场景：在服务端，通常将接收缓冲区注册为LOCAL_WRITE | REMOTE_WRITE，以便客户端通过RDMA Write直接写入数据；在客户端，若需要读取服务端内存，则服务端需注册REMOTE_READ权限。对于高性能计算中的原子操作，还需增加REMOTE_ATOMIC标志。

4.4 误区/复盘：常见错误与最佳实践

误区1：注册后修改缓冲区内容不需要重新注册。实际上，只要不改变缓冲区地址和长度，内容修改无需重新注册。但若缓冲区被realloc或free后重新分配，则必须注销旧MR并注册新MR。

误区2：注册的内存区域越大越好。注册会锁定物理页面，过大的注册区域会浪费物理内存并增加页表开销。建议按实际I/O需求分块注册，例如每块1MB～4MB。

最佳实践：

使用posix_memalign或aligned_alloc分配页对齐缓冲区，避免内部处理非对齐带来的性能损耗；
注册完成后立即保存lkey/rkey，避免每次使用前从mr结构体读取（虽然开销很小，但在高频路径上应减少依赖）；
多线程环境下，注册/注销操作是线程安全的，但同一MR的并发使用需要自行同步；
注销前确保所有依赖该MR的WR已完成（通过轮询CQ确认），否则会产生保护错误。

复盘案例：某团队在开发中遇到“间歇性RDMA Write失败”，排查发现服务端将接收缓冲区注册时仅设置了IBV_ACCESS_LOCAL_WRITE，未包含IBV_ACCESS_REMOTE_WRITE。客户端发送的Write请求携带的rkey虽然有效，但权限不足，HCA直接返回IBV_WC_REM_ACCESS_ERR。修复方法是在注册时增加IBV_ACCESS_REMOTE_WRITE标志，问题随即消失。这提醒我们：access_flags必须与预期使用方式严格匹配，遗漏权限标志比多余标志更隐蔽且难以排查。

此外，还需注意PD（保护域）的隔离作用：不同PD下的MR与QP无法互相访问。在多租户或多应用共享HCA的场景中，应使用独立PD隔离内存域，防止跨应用访问。注册API本身不涉及网络传输，但它是所有RDMA操作的基石——没有正确的MR，后续的发送、接收、远程读写都将无从谈起。