doca-dma

DOCA DMA

示例

• “将主机缓冲区复制到 BlueField，而不使用 CPU。” — 这属于适用范围。使用随附的 DMA 示例和 doca_dma_task_memcpy。
• “首次提交时，复制返回 NOT_PERMITTED。” — 检查 mmap 权限和 doca_dma_cap_*，再更改任务类型。

说明

请遵循下文的加载顺序。需要配置 / 构建 / 运行时，打开任务配套文档。需要了解 memcpy 任务以及路径选择与 RDMA 的区别时，打开能力配套文档。不要打开所有配套文件。

从这里开始： 此技能假设 DOCA 已安装，且用户正在 BlueField / ConnectX / 主机上进行 DMA 实操。如果用户想要执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开任务配套文档；如果问题是关于此版本的 DMA 能表达什么能力，请打开能力配套文档。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户不确定 DMA 是否适合该场景——数据必须经过网络，或者数据流是在两个进程之间传递小消息——请在进行任何配置之前，阅读

Capabilities and modes 中的路径选择规则。

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

此技能旨在回答的 DMA 问题类别，每类各有一个实际示例。Agent 应将类别视为关键所在——实际示例只是其中一个具体场景。

• “如何启动 DOCA DMA 上下文，并在主机和 DPU 之间复制缓冲区？” — 实际示例：“从随附的 DMA Copy 参考应用开始，在一个任务中将 64 KiB 缓冲区从主机内存复制到 DPU 内存”。通过

  configure + ## Capabilities and modes

  中的任务类型表所述的生命周期 + memcpy 任务工作流来解答。
• “在此设备上，一个任务中最多可以 memcpy 多大的缓冲区？” — 实际示例：“我能否在单个 doca_dma_task_memcpy 中复制 16 MiB”。通过

  Capabilities and modes 中的能力查询规则

  （doca_dma_cap_task_memcpy_get_max_buf_size，散布-收集场景还需查询 _get_max_buf_list_len）以及

  configure 中的发现步骤来解答。

• “源和目标 mmap 需要哪些权限？” — 实际示例：“我的 memcpy 任务在首次提交时返回 DOCA_ERROR_NOT_PERMITTED”。通过

  Safety policy 中的源 / 目标权限矩阵

  • test 中的权限检查清单来解答。

• “此复制应使用 DOCA DMA、DOCA RDMA / Comch，还是普通的 CPU memcpy？” — 实际示例：“我有一个 1 MiB 的复制任务，需要从主机进程传到 DPU 进程；我应该使用 DMA 还是 Comch 快速路径”。通过

  Capabilities and modes 中的 “何时使用 DMA”

  与 “何时不使用 DMA” 路径选择条目，以及 ## Related skills 中的路由指引来解答。
• “我安装的版本是否支持 DOCA DMA？我的设备是否支持 memcpy 任务？” — 实际示例：“在此 ConnectX-6 上，DOCA 2.6 是否提供 doca_dma_task_memcpy”。通过

  Version compatibility 中的版本兼容性补充说明来解答；其中交叉链接到规范的检测流程

  doca-version/SKILL.md，同时也会用到

  Capabilities and modes 中的能力查询规则。

• “DMA 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪个层导致的？” — 实际示例：“在 doca_dma_task_memcpy 上调用 doca_task_submit 时返回 DOCA_ERROR_AGAIN”。通过

  Error taxonomy 中对跨库错误分类的 DMA 补充说明

  • debug 中的分层排查流程来解答；该流程会升级到

  doca-debug/SKILL.md。

受众

此技能面向构建应用以使用 DOCA DMA 库的外部开发者——也就是其代码调用 doca_dma_*（在 C/C++ 中直接调用，或通过其他语言的 FFI／绑定调用），使用 BlueField DMA 引擎而非主机 CPU，在两个 doca_mmap 区域之间复制字节的用户。此技能不面向参与开发 DOCA DMA 本身的 NVIDIA 开发者。

语言范围。 DOCA DMA 以 C 库的形式提供，pkg-config 模块名称为 doca-dma。随附示例以 C 编写。C 和 C++ 用户是典型场景，任务配套文件中的示例也假设采用这一途径。其他语言的用户（Rust、Go、Python，……）通过 FFI 或特定语言的绑定使用同一个 *.so；在这种情况下，此技能的作用是确保生命周期、能力发现、权限、错误分类和路径选择方面的指导不依赖特定语言，并引导 Agent 以公共 C ABI 为准，因为任何封装最终都会调用它。

何时加载此技能

当用户以任何语言亲自进行 DOCA DMA 开发时，加载此技能。具体包括：

• 在 doca_dev 上初始化 doca_dma 上下文，并在调用 doca_ctx_start() 前通过 doca_dma_task_memcpy_set_conf 配置 memcpy 任务类型。
• 为 memcpy 设置源和目标 doca_mmap 区域，包括每侧的权限标志（源使用 DOCA_ACCESS_FLAG_LOCAL_READ_ONLY，目标使用 DOCA_ACCESS_FLAG_LOCAL_READ_WRITE），以及在跨端点复制时执行 doca_mmap_export_* 步骤。
• 在设定任何缓冲区大小或假定支持分散-聚集之前，通过 doca_dma_cap_task_memcpy_* 查询系列（_is_supported、_get_max_buf_size、_get_max_buf_list_len）读取 DMA 设备的能力信息。
• 针对 DOCA 进度引擎提交 doca_dma_task_memcpy 任务，并响应每个任务的完成事件。
• 在 DOCA DMA 与相邻方案之间进行选择（数据需要通过网络传输时使用 DOCA RDMA；面向消息的生产者／消费者流程使用 DOCA Comch 快速路径；复制内容很小且只需执行一次时使用普通 CPU memcpy）。
• 调试 DMA 调用返回的 DOCA_ERROR_*（生命周期、权限、能力或暂时无法执行），以及进度引擎报告的每任务完成状态。
• 设计或扩展封装 DMA C ABI 的非 C 语言绑定（Rust、Go、Python，……），确保遵守生命周期、权限和能力规则。

对于一般的 DOCA 概览、DOCA 本身的安装或非 DMA 库问题，不要加载此技能。此类问题请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个轻量加载器。正文仅保留选择下一个文件所需的概览信息。实质性的 DMA 专属内容位于两个配套文件中：

• 能力配套文件——说明此版本的 DMA 可以实现哪些功能：单一的 doca_dma_task_memcpy 任务类型及其分散-聚集缓冲区列表结构、能力查询接口（doca_dma_cap_task_memcpy_*）、DMA 错误分类（映射到跨库通用的 DOCA_ERROR_* 集合）、可观测性接口（进度引擎上的每任务完成事件）、源／目标 mmap 权限策略，以及与相邻库（RDMA／Comch／CPU memcpy）的路径选择规则。
• 任务配套文件——介绍六种适用的 DMA 动词的分步工作流：configure、build、modify、run、test、debug。另有一个 Deferred task verbs 块，指出范围外的问题应转向哪个技能。

此技能假设用户使用的主机或 BlueField 已在标准位置安装 DOCA，并且用户拥有其公开安装配置文件所要求的权限。此技能不涉及安装 DOCA——安装请参阅 doca-setup/SKILL.md。

此技能有意不包含的内容

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

• **任何语言编写的预先编写好的 DOCA DMA 应用源代码。**经过验证的 DMA 源代码是已随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_dma/<name>/，以及可通过 doca-public-knowledge-map/SKILL.md 找到的 DMA Copy 参考应用。 Agent 的工作是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中通用的修改示例工作流，指导用户对这些文件进行最小差异修改，再叠加 ## 修改中的 DMA 特定覆盖规则。
• 停放在技能目录中的独立构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）。Agent 会在用户的项目目录中，针对用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-dma 是事实依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子树。即使标注为“参考”，此技能目录中的模拟或不完整产物也会造成误导：用户会以为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题属于适用范围。
2. 有关 DMA 能力范围、memcpy 任务类型、能力查询规则、源 / 目标权限矩阵、错误分类、可观测性，以及相对于 RDMA / Comch / CPU memcpy 的路径选择规则，请参阅能力配套文件。
3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文件。

这两个配套文件会互相链接，并链接到 doca-version/SKILL.md，以获取规范的版本处理规则；在正确答案是“查阅公开文档或已安装的软件包布局”而非“DMA 特定指南”时，也会链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的路由表，以及已安装 DOCA 软件包在磁盘上的布局。DMA URL 为 https://docs.nvidia.com/doca/sdk/DOCA-DMA/index.html；规范的参考应用是 DMA Copy。
• doca-setup/SKILL.md — 环境准备、 安装验证，以及使用公开 NGC DOCA 容器的我还没有安装路径。此技能假定其前置条件已满足。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。此技能中的 ## Version compatibility 链接到四方匹配规则 + 检测链，并最多增加一条 DMA 特定的叠加规则。
• doca-structured-tools-contract/SKILL.md — 此套件的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文件中的命令附录遵循此约定。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的优先修改随附示例的首次应用工作流、通用生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序端调试顺序。此技能在此基础上叠加 DMA 特定内容。
• doca-rdma/SKILL.md — 当 复制必须经过网络时应使用的库。若 DMA 不适用，此技能的路径选择规则会引导用户转向 RDMA。
• doca-comch/SKILL.md — 当 流程是在主机与 DPU 进程对之间进行生产者 / 消费者消息传递，而非原始 mmap-to-mmap 复制时应使用的库。
• doca-debug/SKILL.md — 跨领域的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。DMA 特定调试（生命周期违规、权限不匹配、超大缓冲区被拒绝）叠加在此阶梯之上。