doca-programming-guide

DOCA 编程指南

示例

• “如何编写我的第一个 DOCA 程序？” — 复制一个随附的示例，按照修改工作流操作，然后使用标准的 pkg-config + meson 构建方式。Docker / NGC 可以编译和链接；运行时需要真实的 BlueField 或 ConnectX。
• “每个 DOCA 对象都要遵循怎样的生命周期？” — 创建 → 配置 → 启动 → 连接 → 使用 → 停止 → 销毁。配置必须在启动前完成。

说明

按照下方的加载顺序操作。打开任务配套文件，了解具体做法；打开功能配套文件，了解覆盖范围。不要打开所有配套文件。

从这里开始： 阅读 ## Audience，确认用户是在使用 DOCA，而不是为其贡献代码。然后跳转到与动词相匹配的 H2 标题（从现有程序派生第一个应用，跳转到 ## modify；查看标准构建模式，跳转到 ## build；了解测试循环，跳转到 ## test；查看程序类别调试步骤，跳转到 ## debug）。Docker / NGC 负责构建部分，不负责运行时部分。 NGC 容器可以编译和链接。创建 Flow pipe、执行 RDMA QP 操作，以及任何需要端口上存在 doca_dev 的调用，都需要真实的 BlueField 或 ConnectX。不要承诺应用可以完全在 docker 内运行。

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

以下是此技能旨在解答的程序类别问题，每个问题都附有一个完整示例。特定库的扩展内容（Flow / DMS / Caps / …）位于对应的库技能中；此技能解答与库无关的问题。

• “如何为 <any library> 编写我的第一个 DOCA 程序？” — 完整示例：“我有 docker；请帮我构建第一个 DOCA Flow 应用。”由 ## modify 中的修改随附示例工作流以及 ## build 中的规范构建模式解答。说明 docker / NGC 可用于构建和链接，但运行时需要真正的 NIC 或 DPU。
• “任何 DOCA 库的正确构建命令是什么？” — 完整示例： “如何编译调用 doca_rdma_* 的程序？” 由 ## build（C/C++ Track 1）中的 pkg-config doca-<library> 模式以及 Track 2 中的 FFI/绑定模式解答。
• “每个 DOCA 对象都遵循什么生命周期？” — 完整示例： “我的程序中 doca_flow_pipe_* 调用的正确顺序是什么？” 由 ## Capabilities and modes 中的核心顺序 create → configure → start → connect → use → stop → destroy 解答（cfg-create / init 实现 configure，并在 start 前完成）。
• “返回了 DOCA_ERROR_*——这是什么意思，我该怎么做？” — 完整示例：“我的代码收到 DOCA_ERROR_BAD_STATE。”由

  Error taxonomy 中跨库通用的 doca_error_get_descr() 规则

  以及 ## debug 中程序类别的调试顺序解答。
• “我的程序构建并启动了，但线路上没有任何活动。” — 完整示例：“我的 Flow 程序运行正常，但没有匹配到流量。” 由 ## Safety policy 中的先验证再提交规则以及

  debug 中分层的程序类别调试步骤解答。

• “<language> 的 DOCA 使用者是什么样的（FFI / 绑定）？” — 完整示例：“如何在不编写 C 的情况下从 Rust 调用 DOCA Comch？”由 ## build（针对公共 C ABI 的 FFI）中的 Track 2 以及 ## Capabilities and modes 中 与语言无关的生命周期解答。
• “应该如何分类并构建所有随附的 DOCA 示例和应用？示例与 应用有什么区别？” — 完整示例：“我尝试构建所有 DOCA 应用， 其中 20/159 个失败了——哪些是真正的回归，哪些是缺少 可选软件栈导致的？”由 ## sample-and-app-categorization 中的示例与应用模型以及类别 / 依赖 / 跳过与失败的分类法解答； 该分类法将“SDK 已损坏”与“此 BlueField 上没有可选的 GPU / RMAX / MPI 软件栈”区分开来。

如果问题属于环境类别（安装 / 构建环境 / 大页 / 设备），请转到 doca-setup/SKILL.md。如果问题特定于库（Flow 管道拓扑、RDMA QP 设置、DMS 服务 部署），请叠加使用对应的库技能。

受众

此技能面向构建应用程序并使用 DOCA 库的外部开发者——也就是说，他们的代码会调用一个或多个 doca_<library>_* 符号（直接通过 C/C++ 调用，或通过其他语言的 FFI／绑定调用）。这是使用 DOCA 进行编程，而不是开发 DOCA 本身：它不面向参与 DOCA 开发的 NVIDIA 开发者，也不假设用户能够访问 DOCA 源代码树、NVIDIA 内部工具或任何非公开信息。它指引 Agent 使用的输入仅限任何外部用户都能获取的内容：公开文档 docs.nvidia.com/doca/sdk/、公开目录 catalog.ngc.nvidia.com、github.com/NVIDIA／github.com/NVIDIA-DOCA 下的公开 GitHub 仓库、公开开发者论坛，以及公共 DOCA 安装（或公开的 NGC DOCA 容器 nvcr.io/nvidia/doca/doca）放置在用户主机上的 /opt/mellanox/doca 目录。有关去哪里查找和如何安装的问题，请转到其他位置处理——请参阅下文的相关技能。

语言范围。 DOCA 本身是一系列 C 库；/opt/mellanox/doca/samples/ 中随附的每个示例以及 /opt/mellanox/doca/applications/ 中随附的每个参考应用程序均为 C。对于本技能中所有规定性工作流，C 和 C++ 消费者是典型情况。其他语言的消费者（Rust、Go、Python 等）通过 FFI 或针对公开 C ABI 的特定语言绑定来使用相同的 *.so 库；本技能提供与语言无关的生命周期、功能、错误、可观测性和安全指导，并将特定语言的构建／FFI 工作交回消费者自己的工具链处理，不编写封装器。

何时加载此技能

当用户已安装 DOCA，并且 已满足环境类别的前置条件（即 doca-setup/SKILL.md 已完成干净安装， pkg-config doca-<library> 能够解析，已挂载大页， 且设备可见），现在提出与如何实际使用 DOCA 编程有关、 且不针对特定库的问题时，加载此技能：

• 了解 DOCA 包含哪些部分（库、应用、服务、 工具），以及它们运行在通信链路的哪一端。
• 任何 DOCA 应用都会遵循的标准 pkg-config + meson 构建模式， 无论它使用哪个库。
• 通用的从已发布的示例派生自定义首个应用工作流；每个库技能都会 通过针对特定库的覆盖项扩展该工作流。此工作流从 doca-setup 移至此处，因为它属于编程操作，而非环境操作。
• 通用的 DOCA Core 生命周期（create → configure (including permissions and task set_conf) → start → connect → use → stop → destroy），以及它在各个库中的体现。配置必须在 doca_ctx_start() 之前完成。Connect 是 start 之后的独立步骤； 不要把 connect/use 写成一个整体。
• 通用的 DOCA_ERROR_* 模式、doca_error_t 和 doca_error_get_descr()——跨库通用模式，而非 Flow 或 RDMA 特定的扩展。
• 先验证再提交的规则，以及每个库技能都会继承的程序端安全策略。
• 适用于任何语言使用者的编程模式（直接使用 C/C++，以及通过 FFI / 绑定使用 Rust / Go / Python / …）——此 技能中的模式与语言无关，并会引导 Agent 将公开的 C ABI 视为权威接口。

不要在以下情况下加载此技能：

• “我的安装正常吗？为什么 pkg-config 找不到 doca-flow？ 如何挂载大页？我还没有安装 DOCA——能否使用容器？”——环境类别问题应由 doca-setup/SKILL.md 处理，它负责安装 验证、环境准备、环境类别调试，以及面向任何使用 macOS、 Windows 或 Linux 且未安装 DOCA 的用户提供的 未安装 → NGC 容器回退路径。
• “DOCA 是什么？Flow 编程指南在哪里？应安装哪个软件包？”——路由／概览问题应由 doca-public-knowledge-map/SKILL.md 处理。
• “如何构造 Flow pipe／设置 RDMA 队列／使用 Comch 发送消息？”——库内部 API 问题应由对应的库技能处理（例如 doca-flow/SKILL.md）。

此技能提供的内容

这是一个轻量加载器。正文只保留了用于选择下一个文件所需的概览内容。实质性材料位于两个配套文件中：

• 能力配套文件——概述每个 DOCA 程序的抽象形态：DOCA 的组成（主机／DPU／交换机、库／应用／ 服务／工具、构建类型选择理由）、通用程序生命周期、适用于任何链接 DOCA 的程序的统一版本兼容规则、跨库的 DOCA_ERROR_* 错误分类、程序端可观测性接口（DOCA 日志、能力快照），以及每个库技能都会继承的程序端安全策略。
• 任务配套文件——针对六种适用的编程操作，提供分步工作流： configure、build、modify、run、test、debug。其中 ## modify 操作负责通用的从示例派生自定义首个应用模式， 每个 DOCA 库技能都会通过针对特定库的覆盖项扩展该模式；## build 操作负责标准的 pkg-config doca-<library> 构建模式，分为两种语言路径 （直接使用 C/C++，以及通过 FFI 使用非 C 语言）。

此技能假设 doca-setup/SKILL.md 已完成干净安装。它不涵盖环境准备；这属于 doca-setup 的职责，其中包括面向使用 macOS、Windows 或 Linux 且未安装 DOCA 的用户提供的*未安装 → NGC 容器 （nvcr.io/nvidia/doca/doca）*回退路径。

此技能有意不提供的内容

此技能是Agent 指南，不是示例或模板包。 它有意不包含以下内容，拉取请求也不应添加：

• 任何语言的预编写 DOCA 应用程序源代码。 这 包括 C / C++ 文件、Rust crate、Go 软件包、Python 模块， 以及任何其他语言的包装代码。DOCA API 接口 会随版本更新而变化；仅根据文档文字编写的代码，若不在真实安装环境中 针对实际库进行编译 / 链接 / FFI 加载，就无法验证。经过验证的 DOCA 应用程序源代码，是用户已安装系统中随附的 C 示例；Agent 的工作是引导用户找到该文件， 并为其指定最小差异修改 （## modify）——面向 C/C++ 用户——或 引导非 C 用户使用其绑定将调用的公开 C ABI 接口（## build Track 2）， 而不是编写包装代码。
• 独立构建清单（meson.build、CMakeLists.txt、 Cargo.toml、setup.py、go.mod，……）放在技能内部。Agent 会在 用户的项目目录中，针对用户已安装的 DOCA 构建清单， 其中 pkg-config --modversion doca-<library> 是事实依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 此技能目录树中的模拟或不完整产物，即使标注为“reference”，也会误导用户：用户会认为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题属于编程类问题（不是环境、路由或库 API 问题）。
2. 关于 DOCA 的形态、通用生命周期、跨库错误分类、程序侧可观测性接口，以及所有库技能都继承的安全策略，请参阅能力配套文档。
3. 关于分步编程工作流——configure、build、modify、run、test、debug——请参阅任务配套文档。

如果用户询问特定库的第一个应用，请先讲解 ## modify 中的通用复制和编辑模式，然后转交给库技能（例如 doca-flow/SKILL.md），了解需要替换的库特定值。

相关技能

• doca-public-knowledge-map/SKILL.md — 公开 DOCA 文档路由，以及已安装 DOCA 软件包的磁盘布局。对于所有*"在哪里记录了 X"、"Y 在磁盘上的什么位置"和"如何检查已安装版本"*问题，此技能均交由知识地图处理。
• doca-setup/SKILL.md — 环境准备、安装验证、环境类调试，以及我还没有安装环境的操作流程；对于没有 DOCA 的 macOS、Windows 或 Linux 用户，使用 NGC 容器（nvcr.io/nvidia/doca/doca）作为通用 Stage-1 后备方案。此技能假定 doca-setup 的前置条件已满足。
• doca-flow/SKILL.md — BlueField 上的 DOCA Flow。 在此技能的 ## modify（通用首个应用派生）基础上， 补充 Flow 专用的待替换字段列表。
• doca-container-deployment/SKILL.md — 发布已成功构建的应用程序：容器清单、 部署和服务就绪状态验证。此技能在程序本地编译并运行后结束；不涉及应用程序部署。