doca-dpa

DOCA DPA

示例

• “在 DPA 上运行计算任务，并由我的主机发起。”——这属于本技能的范围。 请继续使用 doca_dpa 和由 DPACC 构建的映像；不要改写为主机 CPU 或 GPUNetIO 方案。
• “DPA 内核挂起，没有完成通知。”——排空 doca_dpa_completion，并在更改内核前检查 DOCA/DPACC 版本是否不匹配。

说明

请遵循下方的加载顺序。需要配置、启动或调试时，请打开任务配套文档。需要了解线程与内核的区别以及 DPA 能力查询时，请打开能力配套文档。不要打开所有配套文件。

从这里开始：本技能假定已安装 DOCA，用户的 BlueField 配有 DPA 处理器，且主机可以通过 DOCA 访问该处理器；用户正在主机侧亲自进行 DPA 开发，即使用 doca-dpa 加载 DPA 应用映像、启动 DPA 内核，并与 DPA 处理器交换数据。用户想要执行某项操作（配置／构建／修改／运行／测试／调试）时，请打开任务配套文档；问题涉及此版本与此 BlueField 代际的主机侧 DPA API 能表达什么时，请打开能力配套文档。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md；如果用户询问如何编写 DPA 侧内核本身（即在 DPA 处理器上运行、由 dpacc 编译的代码），那属于不同范围——请通过 doca-public-knowledge-map/SKILL.md 转到公开的 DOCA DPA／DPACC／DPA-Comms／DPA-Verbs 指南（本技能不会重新定义这些 DPA 侧接口）。

适用对象

本技能面向从主机侧使用 DOCA DPA 库构建应用的外部开发者——也就是说，他们的代码通过主机端 C／C++ 调用 doca_dpa_*，为每个 DPA 实例建立上下文，加载由 dpacc 根据其 DPA 侧源代码生成的 DPA 应用映像，创建一个或多个 DPA 线程，传入参数启动 DPA 内核，并排空完成通知。本技能不面向参与开发 DOCA DPA 本身的 NVIDIA 开发者，也不是学习如何编写 DPA 侧内核代码的地方（这类内容请通过 doca-public-knowledge-map/SKILL.md 查阅公开的 DOCA DPA、DPACC、DPA-Comms 和 DPA-Verbs 指南）。

**语言范围。**DOCA DPA 以主机侧 C 库的形式提供，其 pkg-config 模块名称为 doca-dpa。主机侧 API 使用 C；DPA 侧内核是独立的翻译单元，使用 DPACC 编译器接受的语言编写，并由 dpacc 编译为二进制文件，再由主机将其打包到可执行文件中，作为 DPA 应用映像。/opt/mellanox/doca/samples/doca_dpa/ 下提供的示例使用 C 和 DPA 侧源代码编写（这是 NVIDIA 的选择）。实际上，其他语言的使用者会受到限制——DPA 侧内核没有 FFI 逃生通道，因为它必须是 dpacc 能接受的翻译单元——但使用 Rust／Go／Python 编写的主机侧封装仍然有用：它可以驱动 doca_dpa_* 设置并启动单独构建的 DPA 内核映像。本技能在生命周期、能力发现、环境前置条件和错误分类方面的指导不限定语言。

何时加载本技能

当用户从主机侧亲自进行 DOCA DPA 开发时，请加载本技能；主机端可以使用任何语言，但需配有由 dpacc 构建的 DPA 侧翻译单元。具体来说：

• 针对映射到 BlueField 的 doca_dev 初始化 doca_dpa，且该 BlueField 的 DPA 处理器对主机可见。
• 将 dpacc 根据用户的 DPA 端源代码生成的 DPA 应用映像（doca_dpa_app）加载到 doca_dpa 上下文中。
• 创建一个或多个 DPA 执行上下文（doca_dpa_thread），为 DPA 内核提供在 DPA 处理器上运行的位置。
• 通过 doca_dpa_kernel_launch_update_* 系列从主机启动带参数的 DPA 内核函数，并判断此安装支持哪种参数形式。
• 将 doca_dpa_completion 附加到异步 DPA 工作，以便观察其何时完成，并在主机端排空完成队列。
• 通过 doca_dpa_cap_* 系列检查活动 doca_devinfo 支持哪些 DPA 功能——不同代的 BlueField 在 DPA 硬件支持方面有所不同。
• 调试 doca_dpa_* 调用返回的 DOCA_ERROR_*——尤其要区分 此 BlueField 上不存在 DPA、此硬件代际不支持较新的 DPA 功能、dpacc 生成的映像与主机端 DOCA 安装不匹配，以及 DPA 驱动层报告失败。
• 为非 C 语言设计主机端绑定，以驱动通过 dpacc 单独构建的 DPA 应用映像——此技能中的环境前置条件和功能发现规则仍然适用。

“我的 DPA 内核挂起了，而且一直没有收到完成通知”首先是一个主机端问题。 启动调用是异步的，因此成功返回表示已提交，而非已完成。在查看一行内核代码之前，先确认主机确实能够观察到完成：已附加 doca_dpa_completion，并且主机正在与未完成的启动并行驱动 doca_pe_progress。如果主机提交任务后阻塞，不再推进 PE，就看不到任何完成通知，并会误以为“DPA 挂起了”——实际上内核可能早已完成。只有排除这一情况后，才应怀疑内核主体无法终止。这两个步骤及其顺序见 ## run steps 2-3。

• 编写调用 DPA 设备端通信组件 libdoca_dpa_dev_comm.a（头文件 doca_dpa_dev_comch_msgq.h）的 DPA 端内核代码——用于同一 doca_dpa_app 上的 DPA 线程之间进行消息传递或协调信号。DPA-Comms 的路由规则、原语系列、功能规则（不存在按原语划分的主机端功能查询系列——主机端 DPA 发现仅使用 doca_dpa_cap_is_supported / doca_dpa_cap_get_max_kernel_time_alive_supported）、错误覆盖说明（_AGAIN → 内核必须让出执行权；以及将 _BAD_STATE 与父级主机端的 _BAD_STATE 区分开来），以及配置 / 构建 / 修改 / 运行 / 测试 / 调试的覆盖说明，均见此技能中的 ## comms 和 ## comms。
• 编写调用 DPA 设备端 verbs 组件 libdoca_dpa_dev_verbs.a（头文件 doca_dpa_dev_verbs.h）的 DPA 端内核代码——当主机往返延迟是测得的瓶颈时，用于在 DPA 内核内部向远程对等端执行 RDMA。四向 RDMA 矩阵、主机配置 QP / DPA 使用 QP 的耦合规则、功能规则（不存在按 verbs 划分的主机端功能查询系列；verbs 是否可用取决于 BlueField 代际以及匹配的 DOCA/DPACC 安装，可从 doca_dpa_dev_verbs.h 和随附示例中查看）、IO_FAILED → CQE 检查的覆盖说明，以及回到更高层级的规则，均见此技能中的 ## verbs 和 ## verbs。

一般性的 DOCA 入门、DOCA 或 DPACC 编译器的安装、DPA 端编程模型本身（如何编写 DPA 内核；在 DPA 内核内部运行的 DPA 设备端通信和 verbs 组件（libdoca_dpa_dev_comm.a / libdoca_dpa_dev_verbs.a），或非 DPA 库问题，不要加载此技能。 这些问题应通过 doca-public-knowledge-map/SKILL.md 转到相应的上游指南。

此技能提供的内容

这是一个精简加载器。正文仅保留选择下一份合适文件所需的指引。实质性的 DPA 专属内容位于两个配套文件中：

• 能力配套文件——说明此版本和此 BlueField 代际上的主机侧 DPA API 能够表达什么：每个 DPA 实例的 doca_dpa 上下文、由 dpacc 生成的已加载 doca_dpa_app 映像、doca_dpa_thread 执行上下文、由主机发起的内核启动接口（doca_dpa_kernel_launch_update_*）、doca_dpa_completion 机制、能力查询接口（doca_dpa_cap_*）、映射到跨库 DOCA_ERROR_* 集合的 DPA 错误分类、可观测性接口（主机侧完成通知，以及可通过 doca-public-knowledge-map 访问的公开 DPA 开发者工具接口），以及用于约束环境前置条件的安全策略（具备 DPA 能力的 BlueField、DOCA 与 DPACC 版本匹配、DPA 侧映像与主机侧预期入口点一致）。
• 任务配套文件——针对六个范围内的 DPA 动词提供分步工作流：configure、build、modify、run、test、debug。此外，还有一个 Deferred task verbs 区块，将范围外的问题引导至合适的下一项技能。

此技能假定主机已在标准位置安装 DOCA，已物理接入 DPA 处理器且主机能够识别该 BlueField，已安装与 DOCA 安装版本相匹配的 DPACC 编译器（遵循 DOCA 兼容性策略），并且用户已了解如何编写将由 dpacc 编译的 DPA 侧内核（至少具备大致了解）。此技能不涵盖安装 DOCA 或 DPACC 编译器——相关流程请参阅 doca-setup/SKILL.md。

此技能有意不包含的内容

此技能提供的是Agent 指引，而非示例或模板包。为明确边界，此技能有意不包含以下内容，拉取请求也不应添加：

• 预先编写的 DOCA DPA 应用程序源代码或任何语言的 DPA 侧内核源代码。 已验证的 DPA 源代码是随附于 /opt/mellanox/doca/samples/doca_dpa/ 的 C + DPA 侧示例。Agent 的职责是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用修改示例工作流，辅以 ## modify 中的 DPA 专属覆盖说明，对这些文件进行最小差异修改。
• 独立的构建清单（meson.build、CMakeLists.txt，等等），不得放在此技能目录中。Agent 会在用户的项目目录中构建构建清单，并使用用户已安装的 DOCA + DPACC 编译器；其中 pkg-config --modversion doca-dpa 和已安装的 dpacc 是两个事实依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子树。 即使标注为“reference”，此技能目录中的模拟或不完整产物也会造成误导：用户会以为它可以构建。
• 用于 comm / verbs 组件的 DPA 设备侧内容（libdoca_dpa_dev_comm.a / libdoca_dpa_dev_verbs.a）。 这些是作为 doca-dpa 一部分提供的DPA 侧归档文件（不是独立的 pkg-config 模块）：其符号由 DPA 内核内部调用，并由 dpacc 链接到 DPA 映像中，而非由主机调用。其公开指南可通过 doca-public-knowledge-map/SKILL.md 访问。此技能只提及并指引用户查阅它们，不会重新定义它们。

加载顺序

1. 首先阅读此技能，以确认用户的问题属于适用范围（主机端 DPA 工作，而非 DPA 端内核编写）。
2. 有关 DPA 功能矩阵、doca_dpa 的每实例上下文、已加载的 doca_dpa_app 映像、doca_dpa_thread 执行上下文、内核启动与完成模型、双重功能查询、环境前置条件策略、错误分类、可观测性界面和安全策略，请参阅功能配套文档。
3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文档。

这两个配套文件会相互交叉引用；还会引用 doca-version/SKILL.md，了解规范的 DOCA 版本处理规则（其中包含 DOCA 必须与 DPACC 编译器匹配的 DPA 补充规则），并在正确答案是“查阅公开的 DOCA DPA、DPACC、DPA-Comms 或 DPA-Verbs 指南，或查阅磁盘上的安装布局”，而非“主机端 DPA 专属指导”时，引用 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源及已安装 DOCA 软件包磁盘布局的路由表。DPA 公开指南位于 https://docs.nvidia.com/doca/sdk/DOCA-DPA/index.html；DPACC 编译器指南、DPA-Comms 指南（DPA 端通信）、DPA-Verbs 指南（DPA 端动词）以及 DPA Tools 总览（DPA 开发者 / 管理员 CLI）也都收录在同一张路由表中，它们是本技能的配套界面，而非本技能重新定义的内容。
• doca-setup/SKILL.md — 环境准备、安装验证、DPACC 编译器安装 / 验证，以及我还没有安装时使用公开 NGC DOCA 容器的流程。本技能假设已满足前置条件，且 DPACC 已安装，并且版本与 DOCA 匹配。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。本技能的 ## Version compatibility 会交叉引用四方匹配规则，并根据 DOCA 兼容性策略补充 DPA 专属的DOCA 与 DPACC 必须匹配规则。
• doca-structured-tools-contract/SKILL.md — 本套件结构化工具的优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的命令附录遵循此契约。
• doca-programming-guide/SKILL.md — 各库通用的 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的先修改随附示例再构建首个应用的工作流、通用的 Core 上下文生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序端调试顺序。本技能在此基础上补充 DPA 专属内容。
• doca-debug/SKILL.md — 跨领域调试流程（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。DPA 专属调试问题（DPACC 与 DOCA 版本不匹配、此 BlueField 代际不具备 DPA、DPA 内核挂起且主机端看不到完成信号、主机启动调用与 DPA 端函数签名之间的启动参数形态不匹配）会在此流程基础上进一步说明。

DOCA DPA 的 DPA 设备端组件——通信归档文件 libdoca_dpa_dev_comm.a（DPA 内核本身调用的通信原语，头文件 doca_dpa_dev_comch_msgq.h）和 verbs 归档文件 libdoca_dpa_dev_verbs.a（DPA 内核本身调用的类 ibverbs RDMA verbs，头文件 doca_dpa_dev_verbs.h）——是随 doca-dpa 提供的 DPA 端归档文件，不是独立的 pkg-config 模块，且各自都有公开指南。本套件目前尚未为它们提供库技能；对于任何 DPA 端问题，请通过 doca-public-knowledge-map/SKILL.md 查阅公开的 DOCA DPA Comms 和 DOCA DPA Verbs 指南，以及随附的 /opt/mellanox/doca/samples/doca_dpa/ 示例（其中包含主机端和 DPA 端翻译单元）。将它们与 doca-dpa 混为一谈，是 DPA 首个应用设计中最常见的错误。