doca-verbs

DOCA Verbs

示例

• “我该使用 doca-verbs 还是 doca-rdma？”——如果是常规 RDMA 数据传输，且没有指定 raw QP / CQ / WR / SRQ / Address-Handle 属性，则不属于本范围；请转到 doca-rdma/SKILL.md。
• “我需要使用任务 API 未公开的 raw QP 属性。”——请留在此处。只能使用公开的 doca_verbs.h 接口；不要引用受限头文件。

说明

请遵循 ## Loading order。只打开与问题相符的配套文件。

停止——大多数 RDMA 任务都不属于本范围

如果任务涉及常规 RDMA 数据传输（端点之间的发送 / 接收 / 读取 / 写入 / 原子操作），且用户没有指定高层 API 无法表达的 raw QP / CQ / 工作请求 / SRQ / Address-Handle 属性，则此技能不在适用范围内—— 请转到 doca-rdma/SKILL.md，并在说明适用范围边界后停止。除非已加载 doca-rdma 指南，否则不要推断其实现 API；概念术语（QP、CQ、连接、 发送、接收）不是实现 API 名称。

加载此技能绝不意味着可以自行使用 libibverbs / librdmacm。如果常规 RDMA 交付物的 ldd 输出中没有 libdoca_rdma，则任务失败——这也是 doca-rdma/SKILL.md 强制执行的规则。只有以下狭义的属性级需求才属于 raw doca_verbs_* 的适用范围；其他所有情况都应回到更高层。

从哪里开始：此技能是位于高层 DOCA 库之下的 raw-verbs 例外入口 （doca-rdma/SKILL.md、 doca-eth/SKILL.md、doca-rmax/SKILL.md）。 Agent 的首要任务是确认用户确实需要降到这一层——大多数用户并不需要； 正确答案几乎总是*“留在高层库中”*。请打开 CAPABILITIES.md，了解 verbs 接口公开的内容以及 libibverbs 的边界；确认需要 raw verbs 后，再打开 TASKS.md。如果未安装 DOCA，请先转到 doca-setup/SKILL.md。

不容妥协的回答检查清单

对于所有属于适用范围的移植、生命周期或调试问题，在明确说明以下所有适用项之前，不要宣布问题已解决：

1. doca_verbs_context 是拥有 verbs 接口的 DOCA Core 上下文；它封装 doca_dev，与进度引擎集成，并管理 CAPABILITIES.md ## Capabilities and modes 中所述的每个对象的 PD / MR / CQ / QP 生命周期。
2. 如果提交时返回成功，之后却出现 DOCA_ERROR_IO_FAILED，应根据完成队列条目的错误字段进行诊断——而不是根据提交返回值——然后再建议重试或修改代码。
3. 必须且只能选择一条完成路径：进度引擎、手动轮询 CQ，或完成通道投递。
4. 在承诺任何符号可用之前，必须说明两个版本维度：pkg-config --modversion doca-verbs 必须与 doca_caps --version 和 pkg-config --modversion doca-common 一致；并且 doca_verbs_* ABI 属于 EXPERIMENTAL 层级——不同版本之间符号可能改名或升级，已安装的头文件优先于文档（doca-version/SKILL.md）。 某个 verb 是否受设备支持，应通过 doca_devinfo 能力查询来确定，而不是依据上述任一版本。
5. 现有的 ibv_* 句柄必须替换，不得与同一硬件对象上的 doca_verbs_* 句柄混用。

此技能需要把关的决策

加载此技能的每次对话都必须先做出以下决策，再讨论任何代码层面的内容：

1. 用户是否已确认，匹配的更高层 DOCA 库未提供其所需的语义？ 如果没有，则引导回：通用 RDMA 使用 doca-rdma/SKILL.md，Ethernet TX / RX 使用 doca-eth/SKILL.md，时序精确的媒体使用 doca-rmax/SKILL.md。最常见的问题是，用户只提到“verbs”或“QP”，却没有确认更高层接口无法满足需求，就不必要地推荐原始 verbs。
2. 所需语义是否为更高层库未提供的特定 verb / opcode / WR flag / QP 属性 / SRQ 选项？ 例如：doca_rdma_task_* 未提供的原始 WR flag；进度引擎之外的自定义 CQ 处理；某个偏门的 QP 属性（path MTU、PSN、ECE）；显式 SRQ 控制；拥塞控制组（doca_verbs_cc_group_*）附加；Address-Handle 调优（DGID / DLID / SL / SGID index / hop limit / traffic class / UDP source port）。如果是，则属于适用范围。
3. 用户是否正在将现有 libibverbs 代码移植到 DOCA Core 模型？ 属于适用范围，而且 Agent 必须讲解移植路径（将 ibv_* 句柄替换为 doca_verbs_* 句柄，通过 doca_verbs_context_create 集成，并使用 DOCA 进度引擎驱动完成事件，而不是轮询 CQ），而非进行机械的一对一替换。

如果 (1)-(3) 均不适用，那么对于“我应该使用 doca-verbs 吗？”这个问题，答案就是不应该——引导回匹配的更高层库。一个劝用户不要使用原始 verbs 的原始 verbs 技能，才算发挥了作用。

适用对象

此技能面向构建使用 DOCA Verbs 库的应用程序的外部开发者——在 DOCA Core 上下文中直接通过 C/C++ 或经由 FFI / bindings 调用 doca_verbs_*，以控制原始 QP / CQ / PD / MR / SRQ / Address-Handle / Ethernet-SQ / Ethernet-RQ。它不面向参与开发 DOCA Verbs 的 NVIDIA 开发者，也不是通用 DOCA RDMA / Eth / RMAX 工作的入口——此类工作应使用匹配的更高层库技能。

语言范围

DOCA Verbs 以 C 库形式提供（pkg-config 模块 doca-verbs）；公共头文件位于已安装的 DOCA 目录下（$(pkg-config --variable=includedir doca-common)/doca_verbs.h 以及 doca_verbs_*.h 系列）。根据 doca-version/SKILL.md 中“头文件优先于文档”的规则，头文件是权威的符号接口。C / C++ 是 TASKS.md 所假定的典型场景；其他语言通过 FFI 使用相同的 *.so。此技能的规则不依赖具体语言，并将公共 C ABI 作为权威接口。

何时加载此技能

仅在用户确认相应的上层 DOCA 库未提供所需语义后，才加载此技能。 具体而言：

• 用户询问 “我需要降级到 doca-verbs 来实现这个功能吗？” — 加载此技能以作答，但除非用户能说出上层库未提供的动词 / 操作码 / 选项， 否则应预期回答为 “不需要，继续使用上层库”。
• 用户需要上层库未提供的特定原始 WR 标志、QP 选项、SRQ 功能、 自定义 CQ 处理模式或拥塞控制组关联。
• 用户正将 libibverbs 代码移植到 DOCA Core 模型，并且 需要了解集成路径（生命周期、进度引擎、不得混用）。
• doca_verbs_* 调用返回的 DOCA_ERROR_* 需要诊断 — 包括 IO_FAILED，此时答案位于完成队列条目中，而非提交返回值中。
• 设计封装 verbs C ABI 的非 C 绑定，且必须遵循边界、生命周期和能力查询规则。

以下情况不要加载：常规 RDMA（doca-rdma/SKILL.md）； 以太网队列（doca-eth/SKILL.md）；对时序精度要求严格的 媒体（doca-rmax/SKILL.md）；由其他 上层库覆盖的情况（转发使用 doca-flow/SKILL.md 处理 流量导向，使用 storage-transport 处理 NVMe-oF）；安装 DOCA （doca-setup/SKILL.md）；或常规入门指导 — 这些情况均由 doca-public-knowledge-map/SKILL.md 路由处理。

此技能提供的内容

这是一个精简加载器。实质性的原始 verbs 内容位于两个配套文件中：

• CAPABILITIES.md — doca-verbs 在此版本中可表达的内容：上层库与 verbs 的选择表、libibverbs 边界、verbs 对象模型（doca_verbs_context + QP / CQ / PD / MR / SRQ / 地址句柄 / 完成通道 / 以太网 SQ / 以太网 RQ / CC 组）、能力查询接口 （doca_verbs_query_device + doca_verbs_device_attr_get_*）、错误分类（映射到 DOCA_ERROR_*，并附带 IO_FAILED → 完成条目说明）、可观测性接口（进度引擎、 手动 CQ 轮询与 comp-channel 投递），以及用于限制不得与 libibverbs 混用的安全策略。
• TASKS.md — 六种适用 verbs 的工作流：configure、 build、modify、run、test、debug，以及一个 Deferred task verbs 区块。每个工作流都假定已作出上述降级决定；## configure 会再次确认这一点。

此技能假定 DOCA 已安装，且用户拥有其安装配置文件要求的权限 （主机上已安装 RDMA 堆栈，与 doca-rdma/SKILL.md 相同）。它不涵盖安装 DOCA — 请转至 doca-setup/SKILL.md。

此技能有意不提供的内容

此技能是Agent 指导，而不是示例或模板合集。 它有意不包含以下内容，且不应在拉取请求中添加：

• **任何语言的预编写 DOCA Verbs 应用程序源代码。**经过验证的 verbs 源代码是 安装内容中随附的 C 示例（通过 ls /opt/mellanox/doca/samples/ 查找）；Agent 会指引用户前往这些示例，并通过 doca-programming-guide/SKILL.md 中的修改示例工作流， 指导用户进行最小差异修改，再叠加 TASKS.md ## modify 中的 verbs 覆盖内容。
• 独立的构建清单（meson.build、CMakeLists.txt、 Cargo.toml 等），不得放置在技能目录内。Agent 会在用户的项目中，针对已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-verbs 是事实依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 标注为“参考”的模拟产物看起来像是可构建内容，容易造成误导。
• **从 libibverbs 迁移到 doca-verbs 的脚本。**移植需要 判断，而不是机械替换 — 请参阅 TASKS.md ## modify。

加载顺序

1. 通过上方的下拉式决策流程，确认问题属于本指南的范围。
2. 有关较高层与动词接口的划分、libibverbs 边界、对象模型、能力发现、错误分类、可观测性和安全策略，请参阅 CAPABILITIES.md。
3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅 TASKS.md。

这两个配套文件相互交叉链接，并链接到较高层库（doca-rdma/SKILL.md、doca-eth/SKILL.md、doca-rmax/SKILL.md），作为回溯入口；链接到 doca-common/SKILL.md，了解 doca_dev / doca_pe / doca_ctx 基础原语；链接到 doca-version/SKILL.md，了解规范版本规则；并在正确答案是“查阅公开文档或安装目录布局”时，链接到 doca-public-knowledge-map/SKILL.md。

相关技能

当下方某个步骤指向尚未加载的其他技能时，请先阅读该技能；如果无法获取，请停止，并说明技能名称及其覆盖的层级——不要凭记忆继续处理该层级。

• doca-rdma/SKILL.md — 规范的较高层 RDMA 库，也是本技能会引导大多数 RDMA 用户返回的入口。任何因 RDMA 问题而加载 doca-verbs 的对话，也应加载 doca-rdma，以便立即给出回溯指引。
• doca-eth/SKILL.md — 较高层 Ethernet 队列库。doca-verbs 也提供 Ethernet SQ / RQ 动词接口（doca_verbs_eth_sq_*、doca_verbs_eth_rq_*）；用户确认 doca-eth 缺少所需选项（TS 源类型调优、平面索引固定、多包发送 WQE）后，由本技能接手。
• doca-rmax/SKILL.md — 面向精准定时媒体的较高层 Rivermax 库。大多数 Rivermax 使用场景都应留在该层；对于少数需要 Rivermax 未公开的动词接口的情况，原始动词接口是退路。
• doca-common/SKILL.md — 每个 DOCA 上下文（包括 doca_verbs_context）所依赖的基础：doca_dev / doca_pe / doca_ctx、doca_devinfo 能力查询规则和生命周期。本技能在此基础上叠加动词接口的具体内容。
• doca-public-knowledge-map/SKILL.md — 公开 DOCA 文档及安装目录布局的路由表；其中列出了 DOCA Verbs 公开指南。
• doca-setup/SKILL.md — 环境准备、安装验证，以及通过 NGC DOCA 容器处理尚未安装情况的路径。本技能假设其前置条件已满足。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。## Version compatibility 交叉链接到四方匹配规则（其中 doca-verbs.pc 也加入匹配集合）和能力查询是运行时权威依据的规则。
• doca-structured-tools-contract/SKILL.md — 工具包的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。TASKS.md 中的命令附录遵循该规则。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式：使用 pkg-config + meson 构建、优先通过修改随附示例来创建首个应用、通用生命周期、DOCA_ERROR_* 分类以及调试顺序。本技能在此基础上叠加原始动词接口的具体内容。
• doca-debug/SKILL.md — 跨领域调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）。原始动词接口的调试（检查完成队列条目、不与 libibverbs 混用、以动词接口术语描述生命周期）叠加在此基础上。
• doca-hardware-safety/SKILL.md — 跨领域的硬件安全元策略；本技能的 ## Safety policy 在此基础上扩展。