doca-flow-dpa-provider

DOCA Flow DPA Provider

示例

• “DPA 内核无法看到已导出的管道中的条目。” — 这是本技能涵盖的范围。遵循导出握手顺序；不要从 DPA 内核重建 Flow 管道。
• “_pipe_export 返回 BAD_STATE。” — 完成 _export_prepare 并添加条目，然后再执行 _export。不要直接跳到设备地址。

说明

遵循下文的加载顺序。打开任务配套文档，了解配置 / 导出 / 调试。打开功能配套文档，了解队列类型和握手。

从哪里开始： 本技能假设 DOCA 已安装，用户拥有一台 BlueField，其 DPA 处理器可由主机通过 DOCA 识别；用户已在主机上编程 DOCA Flow（doca-flow），并已在主机上运行 DPA 内核（doca-dpa / DPACC 编译器）；用户正在亲自处理 DPA Flow Provider 工作：使用 doca-flow-dpa-provider 将现有 DOCA Flow 管道或外部资源导出到 DPA 地址空间，以便 DPA 内核能够以内联方式操作它。如果用户想要执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开任务配套文档；如果用户想了解此版本 + 此 BlueField 代际的 Provider 能够表达哪些内容，请打开功能配套文档。如果用户尚未安装 DOCA，请先引导至 doca-setup/SKILL.md；如果用户尚未建立主机端 Flow 管道，请先引导至 doca-flow/SKILL.md；如果用户尚未建立主机端 DPA 执行环境，请先引导至 doca-dpa/SKILL.md。

此技能擅长回答的示例问题

此技能旨在回答 DPA Flow Provider 问题类别中的以下各类问题，每类都附有一个完整示例。Agent 应将类别视为核心要点——完整示例只是一个具体实例。

• “这个库真的是我需要的工具吗？” — 完整示例：“我希望 DPA 内核能够读取我的 DOCA Flow 管道，或者我想做一些超出主机端 doca-flow API 能力范围的高级操作”。由

  功能和模式

  中的决策规则解答 （“三程序模型：何时应使用此库，而非纯主机端 Flow 或纯 DPA”）。大多数 初次提问的人确实不需要此库；该技能的首要任务是确认他们是否需要。
• “如何将现有 DOCA Flow 管道导出到 DPA 端？” — 完整示例：“我有一个每个条目都带有计数器的 Flow 管道；我希望 DPA 内核能够内联读取这些计数器，并据此决定下一步操作”。由

  功能和模式

  中的主机端导出流程 以及 ## 配置 中的启动步骤解答。
• “如何在 DPA 内核内部驱动已导出的管道？” — 完整示例：“我有一个已导出的哈希管道的设备地址；如何从 DPA 禁用一个条目，又如何确认操作已完成？”。 由 ## 功能和模式 中的设备端 API 接口 （“DPA 端使用”）、主机端队列分配 以及 ## 运行 中的 DPA 端轮询步骤解答。
• “doca_flow_dpa_* 调用返回的这个 DOCA_ERROR_* 是什么意思？问题出在主机端、DPA 端，还是两者之间的导出握手？” — 完整示例：“doca_flow_dpa_pipe_export 返回 DOCA_ERROR_BAD_STATE”。由

  错误分类

  中针对跨库分类的 Provider 补充说明 以及 ## 调试 中升级到 doca-debug/SKILL.md 的分层排查流程解答。
• “为什么我的管道导出成功了，但 DPA 内核始终看不到条目？” — 完整示例：“我在向管道添加条目之后调用了 doca_flow_dpa_pipe_export_prepare”。由 ## 安全策略 中的生命周期顺序规则 以及 ## 测试 中的分阶段导出工作流解答。
• “我读到的主机端／DPA 端 Provider API 在我安装的 DOCA 中可用吗？” — 完整示例：“此主机上的 DOCA 和 DPACC 版本是否支持三种队列类型的 doca_flow_dpa_queues_create，还是我仍在使用基于 doca_flow_dpa_pipe_queues 的旧接口？”。由

  版本兼容性

  中的版本兼容性补充说明解答；该说明交叉链接到 doca-version/SKILL.md 中的规范检测流程，并添加继承自 doca-dpa/SKILL.md 的 Provider 专属补充说明。

适用对象

本技能面向构建应用以使用 DOCA Flow DPA Provider 库的外部开发者——也就是说，用户已有主机端 doca-flow pipe 和主机端 doca-dpa 执行上下文，并希望将二者连接起来，使 DPA 内核能够内联读取计数器、修改条目，或读取、写入与该 Flow pipe 关联的外部资源，而不必往返于主机 CPU。它不适用于为 Provider 库贡献代码的 NVIDIA 开发者，也不适用于只需要主机端 Flow 编程（即 doca-flow）或与 Flow 无关的通用 DPA 计算（即 doca-dpa）的用户。

语言范围。 DOCA Flow DPA Provider 以配对库的形式提供：一个主机端 C 库（pkg-config 模块 doca-flow-dpa-provider，头文件 doca_flow_dpa_provider.h），以及一个 DPA 端设备库；当内核包含 doca_flow_dpa_provider_dev.h 时，DPACC 编译器会将设备库链接到 DPA 端转换单元中。两部分均使用 C 语言。随附示例（位于已安装的 DOCA 示例目录树下）包含这两个转换单元。其他语言的主机端调用方可以通过 FFI 调用主机端 C 库，但 DPA 端内核没有 FFI 变通方案（DPACC 编译器对每个内核映像仅接受一个转换单元）。本技能在主机端提供语言无关的生命周期、能力发现、环境前置条件和错误分类指导；对于所有 DPA 端内核编写问题，则引导用户参阅 doca-public-knowledge-map/SKILL.md 所链接的公开 DOCA DPA 和 DOCA Flow 编程指南。

何时加载此技能

当用户使用任意主机语言开展 DOCA Flow DPA Provider 实际工作，且有一个由 dpacc 构建的 DPA 端转换单元时，请加载此技能。具体包括：

• 针对一个 flexio_process 初始化 doca_flow_dpa_ctx；该进程映射到一台 BlueField，其 DPA 处理器对主机可见，并且已有一个主机端 doca-flow 端口针对同一设备启动。
• 通过 doca_flow_dpa_queues_create 为端口分配三种 DPA 端队列类型（通用队列／条目队列、资源写入队列、资源读取队列）。
• 通过 doca_flow_dpa_pipe_export_prepare → _pipe_export → _pipe_get_device_addr 序列，将主机端 doca_flow_pipe 导出到 DPA 地址空间；必须在向 pipe 添加任何条目之前执行。
• 通过对应的 doca_flow_dpa_external_resource_* 函数族，将外部 Flow 资源（索引选择器资源、内存资源）导出到 DPA。
• 将生成的 doca_flow_dpa_addr 设备指针传递给 DPA 端内核，以便内核据此调用 doca_flow_pipe_hash_* / doca_flow_external_resource_* / doca_flow_queue_poll_completion。
• 调试 doca_flow_dpa_* 调用返回的 DOCA_ERROR_*；尤其是区分 在 pipe 生命周期过晚阶段调用导出、尚未创建队列，以及 DPA 端队列已满且尚未清空 这几种情况。
• 设计非 C 语言的主机端绑定，以驱动 Provider 的主机端设置，并将设备地址传递给单独使用 dpacc 构建的 DPA 应用映像。

对于常规 DOCA Flow 编程（使用 doca-flow/SKILL.md）、通用主机端 DPA 工作（使用 doca-dpa/SKILL.md）或 DPA 端内核编写本身（通过 doca-public-knowledge-map/SKILL.md 转至公开的 DOCA DPA、DPACC 和 Flow 编程指南），请勿加载此技能。

此技能提供的内容

这是一个精简加载器。正文仅保留用于选择正确下一份文件所需的概览。实质性的、特定于提供程序的材料位于两个配套文件中：

• capabilities 配套文件——说明在此版本和此 BlueField 代际上，主机侧和 DPA 侧提供程序 API 能够实现什么：每端口的 doca_flow_dpa_ctx 上下文、三种队列类型（DOCA_FLOW_DPA_QUEUE_TYPE_GENERAL / _RESOURCES_WRITE / _RESOURCES_READ）、管道导出握手（准备 → 导出 → 获取设备地址）、并行的外部资源导出握手、用于哈希管道条目操作的 DPA 侧设备 API（doca_flow_pipe_hash_enable_index / _hash_disable_index / _hash_replace_index）、用于外部资源的 DPA 侧设备 API（doca_flow_external_resource_index_selector_modify*、doca_flow_external_resource_memory_update、doca_flow_external_resource_memory_read*）、完成队列轮询（doca_flow_queue_poll_completion）、三程序模型规则（主机侧 doca-flow + 主机侧 doca-dpa + DPA 侧内核）、映射到跨库 DOCA_ERROR_* 集合的错误分类、可观测性接口，以及用于管控导出生命周期的安全策略。
• tasks 配套文件——针对范围内的提供程序动词提供分步工作流：install、configure、build、modify、run、test、debug、use。此外还有一个 Deferred task verbs 部分，将范围外的问题指向合适的下一项技能。

此技能假定主机已在标准位置安装 DOCA；BlueField（含 DPA 处理器）已物理连接且主机可见；DPACC 编译器已安装，其版本按照 DOCA 兼容性策略与 DOCA 安装版本匹配；用户已了解如何启动 doca-flow 端口，以及如何创建用于执行内核的主机侧 doca_dpa（或其 FlexIO 等效项）；并且用户至少大致了解将使用所导出管道设备地址的 DPA 侧内核。

此技能有意不提供的内容

此技能是Agent 指南，而非示例或模板包。为明确划分范围，此技能有意不包含以下内容，且不应通过拉取请求添加：

• 预先编写的 DOCA Flow DPA Provider 应用程序源代码或任何语言的 DPA 侧内核源代码。 已验证的提供程序源代码是已安装 DOCA 示例目录树中的 C + DPA 侧示例（每次安装的示例目录树路径见 doca-public-knowledge-map/SKILL.md）。Agent 的职责是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用“修改示例”工作流，在这些文件上规定最小差异修改，同时叠加 ## modify 中特定于提供程序的覆盖项。
• 独立的构建清单（meson.build、CMakeLists.txt 等）。Agent 会在用户的项目目录中，针对用户已安装的 DOCA 和 DPACC 编译器构建清单，其中 pkg-config --modversion doca-flow-dpa-provider（以及 doca-flow 和 doca-dpa）与已安装的 dpacc 共同作为事实依据。
• 任何类型的 samples/、bindings/ 或 reference/ 子目录。 此技能目录树中的模拟或不完整产物，即使标注为“参考”，也会造成误导：用户会以为它可以构建。
• 主机侧 doca-flow 管道规格内容。 这属于 doca-flow/SKILL.md 的范围；此技能负责导出已构建的管道，不会重新定义其构建方式。
• DPA 侧内核编程的一般性内容。 编写 DPA 侧函数体、在内核中分配 DPA 内存、使用内建函数，以及使用 doca-dpa-comms 和 doca-dpa-verbs 等 DPA 侧库，均不在范围内。请通过 doca-public-knowledge-map/SKILL.md 查阅公开的 DOCA DPA / DPACC 指南。

加载顺序

1. 首先阅读此技能，确认用户的问题 属于其适用范围（Flow 导出到 DPA 的工作，而不是纯粹的 doca-flow 工作，也不是通用的 doca-dpa 工作）。
2. 有关提供方能力矩阵、三程序模型、每端口的 doca_flow_dpa_ctx、三种队列类型、管道导出和外部资源导出 握手、DPA 侧设备 API、完成模型、错误分类、可观测性 以及安全策略，请参阅能力配套文档。
3. 有关分步工作流——安装、配置、构建、 修改、运行、测试、调试和使用——请参阅任务配套文档。

这两个配套文件会互相交叉链接，也会链接到 doca-flow/SKILL.md 和 doca-dpa/SKILL.md，以了解此库所桥接的 主机侧接口；链接到 doca-version/SKILL.md，以了解规范的 DOCA 版本处理规则（并继承 doca-dpa/SKILL.md 中的 DOCA 和 DPACC 补充说明）；每当 正确的答案是“查阅公开的 DOCA Flow / DOCA DPA / DPACC 编程指南或磁盘上的安装布局”，而不是“提供方专属指导”时， 也会链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-flow/SKILL.md — 规范的主机端 Flow 编程技能。此库导出的 Flow 管道 MUST 首先依据 doca-flow ## Capabilities and modes 进行初始化；本技能仅在其基础上添加 DPA 导出层。
• doca-dpa/SKILL.md — 主机端 DPA 控制库。使用导出的设备地址的 DPA 内核通过 doca-dpa（或其 FlexIO-process 等效方式）加载和启动；本技能继承其中的双端程序模型、DPACC 与 DOCA 版本匹配规则，以及环境前置条件矩阵。
• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的路由表（DOCA Flow 指南见 https://docs.nvidia.com/doca/sdk/doca-flow/index.html； DOCA DPA 指南见 https://docs.nvidia.com/doca/sdk/doca-dpa/index.html； DPACC 编译器指南和 DPA Tools 总览可通过同一张路由表找到），以及已安装 DOCA 软件包的磁盘布局。
• doca-setup/SKILL.md — 环境准备、安装验证、DPACC 编译器安装／验证，以及使用公开 NGC DOCA 容器的 I have no install yet 路径。本技能假定其前置条件已满足，且 DPACC 已安装并与 DOCA 版本匹配。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。本技能的 ## Version compatibility 会交叉引用四方匹配规则，并依据 DOCA Compatibility Policy 添加特定于提供程序的 DOCA-and-DPACC must match 覆盖规则（继承自 doca-dpa/SKILL.md）。
• doca-structured-tools-contract/SKILL.md — 此套件的结构化工具优先级规则（检测／优先使用／回退／报告）。任务配套文档中的 Command 附录遵循此约定。
• doca-programming-guide/SKILL.md — 通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的“先修改随附示例”的首个应用工作流、通用 Core-context 生命周期、跨库 DOCA_ERROR_* 分类，以及程序端调试顺序。本技能在此基础上叠加提供程序特定的细节。
• doca-debug/SKILL.md — 跨领域调试阶梯（安装／版本／构建／链接／运行时／程序／驱动程序）。特定于提供程序的调试（Flow 管道创建、队列创建、导出准备、条目添加和导出之间的生命周期顺序；DPA 端轮询时队列已满；传递给目标为不同 doca_flow_dpa_ctx 的内核的管道设备地址）在此基础上叠加。
• doca-hardware-safety/SKILL.md — 跨领域的硬件安全元策略，本技能的 ## Safety policy 会在此基础上叠加。由于导出的管道会被 DPA 端内核代码直接修改，因此 doca-flow 中的先验证再提交规范以及 doca-dpa 中的双端程序重建规范 BOTH 适用；元策略则提供跨领域的整体框架。