HCA 将连接状态、队列配置、地址转换和事件路由组织为硬件对象。设备通过命令接口建立这些对象，再根据内存中的描述符和 UAR 门铃执行工作。本篇从对象与内存关系出发，解释设备如何启动、取得运行所需的内存、执行管理命令，以及满足什么条件后可以关闭和回收资源。
1. 整体架构
1.1 HCA 功能
HCA 是具备 RDMA 传输、DMA 和访问保护资源的网络适配器。对一次 RDMA 操作，设备需要识别目标，取得工作描述符，检查内存访问权限，将业务地址转换为设备可访问地址，执行网络传输，并按配置生成完成记录或事件。发送与接收两端分别执行本端的访问检查和资源管理。
下图按接口作用区分命令配置、工作执行和结果报告。图中的处理单元表示软件可见的逻辑职责；内部流水线、缓存数量和调度器实现由具体设备决定。
HCA 能够直接访问已经建立 DMA 映射的主机内存。正常发送、接收和 CQ 轮询可以通过已映射队列与 UAR 完成；受保护对象的创建、设备初始化和异常事件处理仍需要系统软件参与。
1.2 软硬件接口
1.2.1 控制接口
Command Queue 传递设备管理命令。输入包含操作码、上下文参数和页面地址，输出包含执行状态、对象编号或查询结果。CREATE_QP、CREATE_CQ 和 CREATE_MKEY 等命令建立不同的对象。
控制命令具有独立的所有权和完成机制。一个 CREATE_QP 命令成功，只能说明对应 QP 已建立；该 QP 能否传输，还取决于状态、路径及所引用资源的配置。
1.2.2 数据接口
SQ、RQ 和 SRQ 保存 WQE。HCA 根据 QPC/SRQC、队列页面映射和发布计数器取得 WQE，再使用其中的操作码、地址、Key 和长度执行工作。软件发布 SQ WQE 时更新发送 DBR，并通过 Send Doorbell 或 BlueFlame 通知设备。软件发布 RQ／SRQ WQE 时更新接收 DBR，HCA 在入站请求需要接收资源时取得已发布的 WQE；普通接收不需要额外写入 UAR Doorbell。
WQE 是设备工作描述符，业务数据可以位于其引用的缓冲区，也可以作为 Inline 数据放在 WQE 内。接收缓冲区的位置由接收 WQE 或 RDMA 请求指定，取决于具体操作。
1.2.3 事件接口
工作完成时，HCA 先将 CQE 写入 CQ。CQ 满足通知条件时，HCA 再向目标 EQ 写入携带 CQN 的 Completion EQE；EQ 满足中断条件时，HCA 通过 MSI-X 通知 CPU。中断处理程序消费 EQE、定位软件 CQ 对象并通知上层，上层再读取 CQE 获得完成结果。持续轮询 CQ 时可以直接处理 CQE，无需为每次完成生成 EQE 和中断。
EQ 将多个 CQ 的完成通知与命令、页面请求和设备异常等事件汇聚到有限的 MSI-X 通道，使软件可以批量处理事件并控制中断频率。一个 CQ 在同一时刻配置一个目标 EQ，多个 CQ 可以共享同一 EQ，多个 EQ 也可以共享一个 MSI-X entry。CQE、EQE 与 MSI-X 不必一一对应。
| 结果载体 | 所描述的结果 | 主要识别信息 |
|---|---|---|
| Command Entry 与输出数据 | 管理命令传递及执行结果 | 槽位、Token、status、syndrome |
| CQE | 工作请求的完成结果 | WQE 标识、操作类型、长度、错误信息 |
| EQE | 需要通知软件的事件 | 事件类型、CQN/QPN 等相关标识 |
下图展示 WQ、CQ、EQ 与 MSI-X 的汇聚关系。
1.3 对象关系
一个 QPC 对应一个 QP。通常的 QP 配有一个 SQ 和一个私有 RQ；"私有"表示该 RQ 由单个 QP 专用，使各 QP 独立管理接收资源。使用共享接收时，QPC 通过 SRQN 关联 SRQ，多个 QP 共用其中的接收 WQE。QPC 中记录的是队列参数和关联信息，WQE 位于单独的队列缓冲区。
| 对象 | 标识 | 主要关联 | HCA 的访问入口 |
|---|---|---|---|
| QP | QPN | SQ/RQ、PD、发送/接收 CQN、UAR、SRQ | 发送门铃或入站报文 |
| SRQ | SRQN | 接收 WQE 池、PD、DBR | QPC 的接收资源关联 |
| CQ | CQN | CQ 缓冲区、DBR、EQN | 工作完成时由队列配置选择 |
| EQ | EQN | EQ 缓冲区、事件映射、MSI-X | 设备事件路由 |
| MKey | Index 与 Key 部分 | MKC、转换表、PD、地址范围 | WQE 的 lkey 或请求的 rkey |
多个 QP 可以引用同一个 CQ，多个 CQ 可以将通知发送到同一个 EQ。对象引用决定创建和销毁依赖：被引用的对象需要先存在，释放时需要先解除依赖。
1.4 内存与地址
HCA 使用的主机内存分为专供设备使用的 ICM、双方按协议访问的队列/DBR，以及业务数据缓冲区。UAR 则属于 PCI 地址空间，通过 CPU MMIO 访问。
下图展示三类存储位置。软件交给 HCA 的地址需要在设备发起访问的整个期间保持有效。
| 地址或标识 | 用途 |
|---|---|
| CPU 虚拟地址 | 软件访问主机内存或 BAR 映射 |
| DMA 地址 | HCA 发起主机接口访问；有 IOMMU 时可以是 IOVA |
| HCA 虚拟地址 | 与 lkey/rkey 一起接受 MKC 范围与权限检查 |
| 对象编号 | HCA 查找上下文，不能当作 CPU 指针 |
| BAR 偏移 | 在对应设备地址窗口内定位寄存器 |
队列页面 PAS 与业务内存 MKey/MTT 分别配置。HCA 找到 WQE 的过程和根据 WQE 找到业务数据的过程使用不同的映射，详见《RDMA-HCA-Mellanox网卡队列 (三)》与《RDMA-HCA-Mellanox网卡地址转换与保护 (四)》。
2. 硬件资源
2.1 上下文与队列
Context（包括 QPC、SRQC、CQC、EQC 和 MKC 等对象上下文）保存对象的配置、关联和运行状态，Queue Buffer（包括存放 WQE 的 SQ、RQ 和 SRQ，存放 CQE 的 CQ，以及存放 EQE 的 EQ）保存实际描述符。对象建立时，软件通过命令提供软件可见字段及页面列表，HCA 管理内部对象。查询命令返回的上下文布局是接口格式，并不直接暴露设备内部 ICM 的存储地址。
一个对象内部可能同时存在软件配置字段、设备维护的运行状态和保留字段。修改范围由命令及对象状态决定；查询获得的状态快照也不等同于暂停对象执行。
2.2 容量与限制
2.2.1 上下文大小
Entry size 描述单个 ICM 条目的资源开销。下表是手册给出的资源估算值；实际条目大小取决于设备配置，应结合设备查询结果确定。命令中的 Context 格式长度、ICM 条目大小和实际队列缓冲区大小各有用途，内存估算需要分别计算。
| 对象 | 单个 ICM 条目的开销 | 表列对象数量上限 | 队列规模或映射规模 |
|---|---|---|---|
| QPC | 256 B | 16M | SQ 按 WQEBB 计数，RQ 按 WQE stride 组织 |
| SRQC | 32 B | 16M | WQE 数量与每个 WQE 的 stride |
| CQC | 64 B | 16M | 2^log_cq_size 个硬件槽位 |
| EQC | 64 B | 512 | 2^log_eq_size 个 EQE |
| Memory Key Context | 128 B | 16M | 地址范围与转换条目数 |
| MTT／KLM | 8 B／16 B | 表列 unlimited | 取决于映射页数或间接条目数 |
例如表列 QPC 的 ICM 开销为 256 B，而软件可见 QPC 格式覆盖到 0xE7；其差异不表示剩余字节可由软件作为私有数据使用。MTT/KLM 的表列 unlimited 表示该资源表未给定固定条目上限，实际数量仍受设备能力和可供页面约束。
2.2.2 对象数量
Max entries supported per virtual HCA 是对象数量的规格上限。实际可配置或可分配数量还取决于 QUERY_HCA_CAP 返回值、预留对象、已占用资源以及页面供给。一个 CQC 对应一个 CQ，不能将 CQC 的对象数当作某个 CQ 的槽位数。
对象编号允许存在空洞。即使知道条目大小，也不能据此构造可由主机直接访问的 ICM_base + object_id × entry_size 地址；设备只承诺通过相应对象标识和命令访问这些资源。
2.2.3 队列深度
队列深度来自该对象的上下文参数。CQ/EQ 的槽位数分别为 2^log_cq_size、2^log_eq_size；SQ 的规模按 64 B WQEBB 计量，一个 WQE 可以占用多个 WQEBB；RQ/SRQ 的容量同时涉及槽数和 stride。
软件能够同时提交的 WR 数还受最大 WQE 大小、预留槽及资源回收方式影响。硬件槽数、Buffer 字节数和可挂起 WR 数应分别表达。
2.3 ICM 管理
ICM 是交给 HCA 专用的固定主机页面，用于设备运行和 Context 管理。页面交接后，软件保留分配记录和 DMA 映射，但不得读写页面内容；内部布局由 HCA 管理。对象销毁通常只改变设备内部资源占用，页面何时可以回收由页面交接协议决定。
页面需求按 Function 关联。设备向可信 PF 软件请求页面，相关 VF 的需求由可信管理侧承接。这种关联保证设备内部资源有可追踪的归属，并支持 Function 的独立初始化和关闭。
2.4 页面供给与回收
设备通过 QUERY_PAGES 返回值或 Pages Request EQE 告知页面需求。QUERY_PAGES 返回指定 Function 当前需要补充或可以归还的聚合 ICM 页面数量；这些页面主要承载 Firmware 管理的对象 Context 和内部状态，不包含 WQE、CQE、EQE 等 Queue Buffer。MANAGE_PAGES 将 DMA 页地址交给设备，或取得设备归还的页地址。软件应按命令实际成功接收、实际归还的清单更新记账。
下面的时序图展示页面从软件可用、设备专用到归还后的状态变化。运行期 Pages Request 事件同样通过 MANAGE_PAGES 响应。
每个 Pages Request 事件至少需要一次 MANAGE_PAGES 响应。在获得响应前，同一 function_id 不会再次发送页面请求事件；其他 Function 的事件不受这项等待约束。无法提供页面时，也需要使用相应模式报告分配失败，使等待资源的命令能够以资源不足结束。
回收命令可能需要重复执行，直到设备不再返回页面。页面需求通知并不直接解除 DMA 映射，实际归还结果才是软件恢复页面使用权的依据。
2.5 资源隔离
Function、PD 和 UAR 分别承担不同层面的资源关联。Function 管理命令接口和所属设备资源；PD 用于 QP 与内存对象之间的保护检查；UAR 为直接提交工作的执行主体提供 MMIO 入口。
| 机制 | 约束对象 | 配置含义 |
|---|---|---|
| Function 归属 | 命令、上下文和 ICM | 限定对象管理的设备实例 |
| PD | QP、SRQ、MKey 等 | 限定可组合使用的通信和内存资源 |
| UAR 关联 | 发送与完成通知入口 | 指定相应队列使用的用户访问区域 |
| MKey 权限 | 本地/远端内存访问 | 检查 Key、范围和操作许可 |
这些配置需要一起满足。例如一个有效的 rkey 仍需通过目标 QP、PD、权限及地址范围等适用检查，才能形成数据访问。
3. 初始化
3.1 启动与就绪
复位解除后，设备从 Flash 加载 Firmware，并检查读取内容的签名。完成内部加载后，设备可以响应 PCI 枚举。平台分配 BAR 后，CPU 可以访问位于 PCIe BAR0 起始位置的 Initialization Segment MMIO 寄存器区域，其详细布局和位域含义见[第 5 节"寄存器与查询"](#第 5 节“寄存器与查询”)。设备执行命令和 DMA 前，PCI Bus Master 必须已启用。PCI 枚举完成、initializing=0 和 INIT_HCA 成功分别表示不同阶段：地址入口可用、命令接口可接收工作、HCA 运行资源初始化完成。
3.2 命令接口建立
Command Queue 位于 4 KiB 大小且 4 KiB 对齐的物理连续内存块。软件从 Initialization Segment 读取队列的槽位数和 stride，分配并映射队列，再将设备可使用的地址写入 Initialization Segment；相关寄存器字段见[第 5 节"寄存器与查询"](#第 5 节“寄存器与查询”)。
使用两个 32 bit MMIO 写地址时，先写高位，再写低位。低位所在 DWORD 同时包含 nic_interface；完整 HCA 驱动启动时该字段选择 full_driver，写入时其余要求清零的位保持零。随后轮询 initializing，设备就绪后才开始命令交互。
下面的 UML 图展示启动依赖。图中相邻的依赖命令都需要等待前一命令成功；Boot Pages、Init Pages 与运行期页面需求分阶段处理。
3.3 ISSI 选择
ENABLE_HCA 使 Function 进入允许后续初始化的状态。QUERY_ISSI 返回接口支持信息，SET_ISSI 选择双方共同支持的接口语义，使后续命令按照该接口定义解释。
ISSI 与 Firmware 版本号、Command Interface revision 各有职责。软件需要识别命令传输接口，并选择有效的 ISSI；设备返回不支持时应停止依赖该接口的初始化，避免继续提交字段含义不匹配的命令。
3.4 能力查询与配置
QUERY_HCA_CAP 用于读取设备能力和资源限制，SET_HCA_CAP 设置允许由软件选择的系统参数。能力值决定可创建的对象规模、允许的页面粒度和可使用的功能；对象创建命令仍会校验具体请求。
| 能力类别 | 影响 |
|---|---|
| 对象数量 | QP、CQ、SRQ、MKey 等资源规模 |
| 队列参数 | 最大队列深度、WQE/CQE 相关限制 |
| 地址与页面 | 页面大小、转换方式、内存访问能力 |
| 传输能力 | 传输类型、READ/Atomic 等操作支持 |
| 接口功能 | BlueFlame、Fast Teardown 等可选机制 |
能力选择位于 INIT_HCA 之前；设备已经运行后，修改对象的参数应使用对应命令和允许的状态转换，不能把 SET_HCA_CAP 当作任意运行参数更新接口。
3.5 页面准备
Boot Pages 支持设备启动阶段的内部资源；Init Pages 满足 HCA 初始化和后续命令所需的页面要求。QUERY_PAGES 在相应阶段返回数量，MANAGE_PAGES 可以分批提供。设备允许的情况下也可以预先提供 Boot Pages 与 Init Pages 的总和。
若 Init Pages 需求为零，可以跳过该阶段的页面提供；需求非零时，应完成页面交接后再执行依赖它的 INIT_HCA。所有已交接页面都必须保留记录，以便失败处理和正常关闭时逐一收回。
3.6 HCA 激活
INIT_HCA 使用已经选定的能力配置和已交接页面建立运行环境。命令成功后，可以创建 EQ 和后续数据对象。该成功结果并不替代各 QP 的状态转换，也不说明物理链路和对端连接已经准备完毕。
软件需要逐步区分三项条件：Function 已启用、HCA 已初始化、数据对象已具备执行条件。这样才能判断某项失败应回退到哪个已完成阶段。
3.7 事件与端口准备
EQ 建立后，页面请求和命令完成等事件可以使用事件通道。把 EQ 映射到命令完成通道的 CREATE_EQ 必须在命令队列为空时单独执行，切换期间不能并发提交其他命令。EQ 尚未建立时，通过 Command Entry ownership 轮询完成。
物理端口由端口管理寄存器配置，vport 命令用于查询和设置 Function 对应的逻辑端口状态、地址等信息。端口链路、vport 状态和 QP 传输状态需要分别满足条件。RoCE 需要有效的 Ethernet 地址与路径配置；InfiniBand 还涉及相应管理与路径信息。
4. 命令机制
4.1 命令队列布局
Command Queue 是固定步长条目数组。槽位数 N=2^log_cmdq_size，步长 T=2^log_cmdq_stride；本手册所述当前布局为 32 个槽位、64 B stride，队列驻留于前述 4 KiB 内存块。设备从 Initialization Segment 获取队列地址。
命令槽 i 的地址为 cmdq_dma_base + i × T。这是软件可见的命令队列数组寻址；上下文内部 ICM 的寻址不由此公式推导。输入和输出各有独立的 Mailbox 链。
下图把命令队列、槽位和两条 Mailbox 链放在同一布局中。箭头表示地址引用，槽位与链表数量不代表命令执行先后。
4.2 命令描述符
一个 Command Entry 同时容纳请求和响应的前 16 B。input_length 与 output_length 按完整逻辑消息计数，超出 16 B 的部分分别位于输入和输出 Mailbox。
下图显示描述符的字节区间及 Mailbox 控制尾部。表中的偏移均相对各自结构起点。
| Entry 偏移 | 位域 | 字段 | 含义与访问方 |
|---|---|---|---|
0x00 |
[31:24] |
type |
软件置 0x7，选择 PCIe Command Transport |
0x04 |
[31:0] |
input_length |
软件填写完整命令输入字节数 |
0x08／0x0C |
[31:0]／[31:9] |
input_mailbox_pointer |
输入 Mailbox 地址的高位／有效低位 |
0x10--0x1F |
128 bit | command_input_inline_data |
软件填写输入头 16 B |
0x20--0x2F |
128 bit | command_output_inline_data |
设备写入输出头 16 B |
0x30／0x34 |
[31:0]／[31:9] |
output_mailbox_pointer |
软件提供输出 Mailbox 地址 |
0x38 |
[31:0] |
output_length |
软件提供输出空间长度 |
0x3C |
[31:24] |
token |
软件设置，与该命令 Mailbox 的 token 一致 |
0x3C |
[23:16] |
signature |
Command Entry 校验值 |
0x3C |
[7:1] |
status |
软件提交时清零，设备返回传递状态 |
0x3C |
[0] |
ownership |
软件提交置 1，设备完成清零 |
命令消息头与上述传输描述符是两层结构。消息头决定实际要执行的 HCA 操作。
| 消息 | 偏移 | 位域 | 字段 | 含义 |
|---|---|---|---|---|
| 输入 | 0x00 | 31:16 | opcode | 管理操作码 |
| 输入 | 0x04 | 15:0 | op_mod | 操作修饰；未定义时为零 |
| 输入 | 0x08 起 | 按命令定义 | command | 对象配置或查询参数 |
| 输出 | 0x00 | 31:24 | status | 命令执行状态 |
| 输出 | 0x04 | 31:0 | syndrome | 进一步的错误信息 |
| 输出 | 0x08 起 | 按命令定义 | response | 对象编号、查询内容等 |
4.3 Mailbox 布局
每个 Mailbox 的数据区为 512 B，后面附带保留区、链指针、块编号和校验字段。有效描述范围到 0x23F；链指针的有效低位要求下一块按 1024 B 对齐。描述范围长度和块起点对齐分别满足要求。
| Mailbox 偏移 | 位域 | 字段 | 含义 |
|---|---|---|---|
0x000--0x1FF |
512 B | mailbox_data |
超过 Entry inline 部分的命令数据 |
0x200--0x22F |
48 B | Reserved | 软件清零 |
0x230／0x234 |
[31:0]／[31:10] |
next_pointer |
下一个 Mailbox 地址；链尾为零 |
0x238 |
[31:0] |
block_number |
从零递增的块编号 |
0x23C |
[23:16] |
token |
与 Command Entry 匹配 |
0x23C |
[15:8]／[7:0] |
ctrl_signature／signature |
控制区及整个块的校验值 |
当逻辑消息长于 16 B 时，所需数据块数为 ceil((length−16)/512)。例如长度 1040 B 的消息由 Entry 内 16 B 和两个各含 512 B 数据的 Mailbox 组成。输入和输出按各自长度独立计算，不要求使用相同数量的块。
Block number 从零连续递增，所有块的 Token 与命令一致，末块 next_pointer 为零。HCA 通过指针、块号与 Token 检查链条是否属于当前命令。启用签名检查时，输入数据和输出链控制信息都需要符合校验规则，设备输出的签名用于检查写回结果。
4.4 所有权与 Token
软件准备槽位时拥有其内容。提交时把 ownership 置 1，并在通知设备前保证相关内存写入可见；HCA 完成后将其清零。设备持有所有权期间，软件必须保持 Entry、Mailbox 和所引用的命令缓冲区有效。
Token 是命令与 Mailbox 的关联字段，能够识别链条和请求代次；它不代表对象编号，也不允许绕过所有权直接复用仍在执行的槽位。槽位只有在确认对应操作完成、读取结果并完成本地处理后才可重新提交。
4.5 提交与执行
command_doorbell_vector 是槽位位图。写入 bit i 表示槽 i 有新命令，一次 MMIO 写可以同时提交多个槽。HCA 取得相应 Entry 和输入链，执行命令，再写入输出和状态。
下面的时序图将写描述符、发布、设备执行和读取结果连起来。读写屏障分别保证设备能看到输入、软件能看到完成后的输出。
命令可以乱序执行和完成。创建 CQ 与随后引用其 CQN 的 CREATE_QP 存在依赖，必须等待前者成功；把两者同时置入 Doorbell 位图不能建立依赖顺序。互不依赖的命令才有条件使用多个槽位并发。
4.6 完成通知
HCA 写回结果并归还 ownership 后，软件可以通过轮询发现完成，也可以通过 Command Completion EQE 的完成位图定位相关槽位。事件位图可同时指示多个自前次事件以来完成的命令。
事件用于发现结果，最终仍需检查对应 Entry 的状态和输出。开启事件完成后，EQ 必须持续保有可用空间；若 EQ 没有空间，软件需要先推进其 Consumer，再继续提交依赖该完成通道的命令。
命令 EQ 的建立和映射必须使用前面描述的独占切换条件。轮询阶段与事件阶段都使用相同的 Command Entry，变化的是完成发现方式。
4.7 错误与超时
错误分为传递错误和命令执行错误。传递层检查 Entry 与 Mailbox 的格式、Token、链条和长度；执行层检查对象、状态、参数与资源条件。
| 层次 | 代表错误 | 处理时关注的内容 |
|---|---|---|
| Entry status | SIGNATURE_ERR、TOKEN_ERR | 输入与链控制信息是否匹配 |
| Entry status | BAD_BLOCK_NUMBER、BAD_INPUT_POINTER | 块顺序与地址对齐 |
| Entry status | INPUT_LEN_ERR、OUTPUT_LEN_ERR | 消息长度及输出空间 |
| Entry status | RESERVED_NOT_ZERO | 保留字段初始化 |
| 输出 status/syndrome | 参数、状态、权限或资源错误 | 对应命令语义和对象状态 |
设备命令接口未给出统一的硬件命令超时值，软件可以对提交计时。超时只说明在规定时间内没有观察到完成，不能证明 HCA 已停止 DMA，也不能据此立即释放 Mailbox。后续必须通过健康检查、已定义的关闭或复位机制确认设备访问结束。
5. 寄存器与查询
5.1 BAR 布局
HCA BAR 提供 Initialization Segment 和 UAR 等窗口。Initialization Segment 位于 BAR 起始位置；UAR 的定位使用相应分区和编号规则，详见《RDMA-HCA-Mellanox网卡UAR与门铃 (二)》。
下图强调直接 MMIO 寄存器与命令访问的管理寄存器之间的关系。ACCESS_REGISTER 的 register ID 是命令字段，不能直接用作 BAR 偏移。
5.2 初始化寄存器
下表汇总直接参与启动、命令与状态读取的 Initialization Segment 字段。所有偏移相对 Segment 起点。
| 偏移 | 位域 | 字段 | 访问 | 用途 |
|---|---|---|---|---|
0x000 |
[31:16]／[15:0] |
fw_rev_minor／fw_rev_major |
RO | Firmware 版本 |
0x004 |
[31:16]／[15:0] |
cmd_interface_rev／fw_rev_subminor |
RO | Command Interface 和补丁版本 |
0x010 |
[31:0] |
cmdq_phy_addr[63:32] |
RW | Command Queue 地址高位 |
0x014 |
[31:12] |
cmdq_phy_addr[31:12] |
RW | Command Queue 地址低位 |
0x014 |
[10:8] |
nic_interface |
RW | Full Driver、Disabled 等接口状态 |
0x014 |
[7:4]／[3:0] |
log_cmdq_size／log_cmdq_stride |
RO | 槽位数／stride 的 log2 值 |
0x018 |
[31:0] |
command_doorbell_vector |
WO | 提交一个或多个命令槽位 |
0x1FC |
[31] |
initializing |
RO | 为零时设备可以接收命令 |
0x1FC |
[19:16] |
initializing_state |
RO | 初始化中的等待／中止状态 |
0x200--0x23F |
64 B | health_buffer |
表列 RW | 设备健康诊断信息 |
0x1000--0x1007 |
64 bit | internal_timer |
RO | 设备内部计时值 |
0x100C |
[0] |
clear_int |
WO | 写 1 清除 Legacy Interrupt |
0x1010 |
[31:24]／[23:0] |
health_syndrome／health_counter |
RO | 健康错误和活动计数 |
5.3 命令寄存器
cmdq_phy_addr 指定命令队列基址，log_cmdq_size 和 log_cmdq_stride 描述其几何尺寸，command_doorbell_vector 通知各槽位。队列地址从 INIT_HCA 到 TEARDOWN_HCA 之间保持不变。
nic_interface 与命令地址低位共用 DWORD。写该寄存器时必须保留需要保持的地址位，并按操作要求设置接口状态。full_driver、disabled 和 reset 等状态具有不同效果；PF reset 可以影响整个设备的其他 Function，不能将其理解为单个普通队列的复位。
5.4 状态与健康信息
Firmware 版本字段和命令接口 revision 用于识别设备当前接口。health_counter 表示设备健康活动计数，health_syndrome 表示设备报告的健康错误，health_buffer 提供更详细的诊断内容。
一次读取到计数器不变不能单独证明设备失活，应结合持续观察、syndrome 和命令状态分析。健康缓冲区是诊断接口，即使表列访问属性为 RW，也不应把它作为业务缓冲区写入。
5.5 设备计时器
internal_timer 返回设备内部时间，可用于解释支持时间戳的 CQE。原始计时值与系统墙钟时间之间需要设备规定的频率、格式和换算关系，不能直接将其当作纳秒或 CPU 时钟。
计时器为 64 bit。若平台不能以一致方式读取整个值，需要采取能检测高位变化的读取方式，避免低位回绕造成拼接结果错误。该一致性处理只服务于读数，不会建立 RDMA 数据访问的先后顺序。
5.6 ACCESS_REG
ACCESS_REGISTER 将 register ID、访问方法和寄存器载荷封装为管理命令，用于物理端口状态、链路参数、计数等管理信息。寄存器载荷按该寄存器自己的位域定义解释。
| 查询入口 | 获得的信息 |
|---|---|
| QUERY_HCA_CAP | 对象数量、队列能力和支持功能 |
| QUERY_ADAPTER | Adapter 标识等设备信息 |
| QUERY_QP/CQ/EQ/MKEY | 已创建对象的配置或运行快照 |
| QUERY_VPORT_STATE | 逻辑端口状态 |
| ACCESS_REGISTER | 指定管理寄存器的内容 |
直接寄存器读取、对象查询和能力查询解决不同的问题。实际队列深度应查询对象配置，设备能够支持的最大深度应读取能力，两者不能互相替代。
5.7 ICMD 接口
ICMD 提供通过 PCI VSC Gateway 访问的工具侧命令入口。它具有独立的 Control、Mailbox Size、Syndrome 和 Mailbox 配置空间；常规 HCA 数据工作仍通过 WQE 执行。
| ICMD 地址 | 字段 | 作用 |
|---|---|---|
| 0x000000 | Control | opcode、status、exmb、busy |
| 0x001000 | Mailbox Size | Mailbox 容量信息 |
| 0x001008 | Syndrome | 进一步的结果信息 |
| 0x100000 起 | Mailbox | 命令参数与结果 |
Control 的 opcode[31:16] 指定操作，status[15:8] 返回状态，exmb[1] 指定外部 Mailbox 方式，busy[0] 表示启动与执行状态。软件需先取得 Gateway 所有权，访问结束后归还，避免不同访问者交叉修改地址和数据寄存器。
普通内部 Mailbox 路径选择 exmb=0，先按 Mailbox Size 清零整个 Mailbox，再填写输入；启动时写 opcode、清 status、置 busy。外部 Mailbox 需要 icmd_exmb 能力和有效的 MKey 配置，取得 Gateway 所有权后重新配置该 Key。
下面的 UML 图展示内部 Mailbox 的访问顺序。Gateway 访问成功和内部命令执行成功需要分别检查。
6. 关闭与恢复
6.1 资源释放条件
释放硬件可访问的内存，必须满足相关工作不再产生新访问、已提交访问已处理、对象引用已解除等条件。停止软件提交只能阻止新增工作；已经交给 HCA 的 WQE 和远端仍可发起的请求还需单独处理。
关闭 Function 前，应停止业务并销毁所属资源。QP、CQ、MKey 和共享接收资源之间的依赖决定释放次序：先停止新增工作并处理在途访问，再解除对象引用，最后释放底层页面与映射。
6.2 HCA 关闭
正常关闭在数据对象停止后解除页面请求事件映射并销毁 EQ，再执行 TEARDOWN_HCA。硬件确认成功后，不再代表该 ICM 发起 PCI 访问；此时可以继续按页面回收协议完成清理。
下图展示正常关闭的关键确认点。关闭 PF 时，其相关 VF 也受影响，需要先处理这些 Function 的工作。
6.3 页面归还
正常路径通过 MANAGE_PAGES 循环取得归还清单，直到相关页面全部回收。软件根据返回地址找到原分配记录，解除映射并释放。设备确认关闭与软件完成页面记账是两个相关但不同的动作。
最后执行 DISABLE_HCA，结束该 Function 的启用状态。若关闭命令失败，不能套用成功路径直接释放仍可能被 HCA 使用的页面。
6.4 Fast Teardown
设备能力 fast_teardown=1 时，可以请求 TEARDOWN_HCA(profile=prepare_fast_teardown)。结果 state=0 表示准备成功，随后将 Initialization Segment 的 nic_interface 设置为 disabled，并轮询确认该状态。结果 state=1 时使用正常关闭流程。
该机制缩短逐页归还所需的关闭过程，其可用性和完成确认都来自设备协议。只有看到相应关闭状态，软件才可以根据已记录页面执行释放，不能仅因准备命令已提交就撤销内存。
下面的 UML 图展示准备成功的路径；准备失败时转入上一节的正常关闭时序。
6.5 失败与重新初始化
初始化失败时，要保留已完成阶段的记录：命令队列是否已建立、Function 是否已启用、哪些 ICM 页面已交接、INIT_HCA 是否成功、哪些对象和 EQ 已创建。清理只针对已成功取得的资源，DMA 页面仍按设备确认的生命周期释放。
| 失败位置 | 后续重点 |
|---|---|
| 接口尚未就绪 | 读取初始化状态，停止提交后续命令 |
| 页面提供失败 | 报告资源不足，核对已接收页面 |
| INIT_HCA 或对象创建失败 | 按已建立资源解除依赖并执行适用关闭流程 |
| 命令超时或设备异常 | 先确认设备访问状态，再决定页面回收 |
重新初始化需要重新建立有效的队列地址、能力选择、页面和对象关联。旧对象编号、旧队列状态及旧 Key 不能假定在重新初始化后仍然有效。
7. 总结
HCA 的管理入口是 Command Queue，运行资源由 ICM 页面和各类对象构成，数据入口则是队列缓冲区与 UAR。对象编号连接各类上下文，页面映射连接硬件对象和实际存储。
初始化的关键依赖是命令通道、接口选择、页面供给和 HCA 激活。命令描述符通过所有权交接，多个槽位允许并发，存在依赖的命令仍需等待成功结果。关闭时，设备确认、页面归还和软件解除映射共同完成资源回收。
8. 参考资料
- Mellanox Adapters Programmer's Reference Manual，Rev 0.53。
- Linux 本地 mlx5 命令和页面管理实现：
linux/drivers/net/ethernet/mellanox/mlx5/core/cmd.c、linux/drivers/net/ethernet/mellanox/mlx5/core/pagealloc.c。