doca-common

DOCA Common

示例

• “任务已提交，但没有任何任务完成。” — 从进度引擎和 ctx 生命周期入手，而不是重写单个库。
• “doca_ctx_start 返回 DOCA_ERROR_BAD_STATE。” — 先梳理 Common 生命周期顺序，再判断是否是 Flow 或 RDMA 的问题。

说明

请遵循下方的加载顺序。配置 / 构建 / 运行相关问题，请打开 tasks 配套文档。ctx / buf / pe / log 相关问题，请打开 capabilities 配套文档。不要打开所有配套文件。

从这里开始： 此技能是每个 DOCA 应用最先加载的基础，先于 doca-flow、doca-rdma、doca-eth、doca-comch 或任何其他更高级的库。每个 doca_<library>_* 上下文都构建在 doca_ctx 之上，每个设备句柄都是通过 doca_devinfo 发现的 doca_dev，每个零拷贝缓冲区都是从 doca_mmap 上的 doca_buf_inventory 获取的 doca_buf，每个任务完成事件都会通过 doca_pe 排空，每条日志都会通过 doca_log 输出。若问题是这次安装中的 Common 能提供什么，请打开 capabilities 配套文档；若用户想要执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开 tasks 配套文档。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户已经了解基础内容，并提出特定库的问题（例如 “如何编写 Flow 管道”），请同时加载相应的库专属技能——这些技能会通过交叉链接回到这里，介绍共享的基本功能。

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

此技能旨在回答的 doca-common 问题类别，每类各有一个完整示例。Agent 应将类别视为关键部分——完整示例只是其中一个具体实例。

• “在打开 doca-flow / doca-rdma / doca-eth / … 上下文之前，我必须先设置哪些 doca-common 基础？” — 完整示例：“我正在 BlueField-3 上从头编写一个 DOCA Flow 程序；打开 Flow 端口之前，需要准备哪些 doca-common 基础结构？”。由 ## configure + ## ctx + ## dev + ## progress engine 中的通用基础流程回答。
• “如何发现设备，并在信任公开文档之前检查设备是否具备相应能力？” — 完整示例：“我想使用 doca_eth_txq，但文档暗示该功能仅在某些固件版本范围内可用。”。由 ## dev + ## use 中的能力发现规则回答（针对活动的 doca_devinfo 执行 doca_devinfo_create_list → doca_*_cap_*，才是运行时的权威依据）。
• “零拷贝 I/O 中，doca_buf / doca_mmap / doca_buf_inventory 应如何连接？生命周期顺序是什么？” — 完整示例：“我想向设备注册用户空间缓冲区，将其划分为 N 个数据平面缓冲区，并在多个 DOCA 库之间对它们进行引用计数。”。由 ## buf 中的零拷贝缓冲区模型，以及 ## configure + ## use 中的缓冲区生命周期流程回答。
• “进度引擎如何工作？我必须在哪里调用它？” — 完整示例：“我的 doca_rdma 任务提交顺利，但没有任何任务完成——我漏掉了什么循环？”。由 ## progress engine 中的 PE 接口，以及 ## run 中的运行循环模式回答。
• “为什么我的 DOCA 日志没有按预期级别显示？--sdk-log-level 和应用侧 setter 有什么区别？” — 完整示例：“我设置了 --sdk-log-level 60（DEBUG），但我自己的 DOCA_LOG_DBG 日志仍然没有打印。”。由 ## log 中的双层日志模型，以及 ## log 中的层级切换迭代说明回答。
• “doca_buf_* / doca_ctx_* / doca_dev_* / doca_pe_* / doca_log_* 调用返回的这个 DOCA_ERROR_* 是什么意思？” — 完整示例：“doca_ctx_start 返回 DOCA_ERROR_BAD_STATE。”。由 ## Error taxonomy 中跨库 DOCA_ERROR_* 分类体系的 Common 补充说明，以及 ## debug 中最终升级至 doca-debug/SKILL.md 的分层排查流程回答。

受众

本技能面向所有构建应用程序、并使用任意 DOCA 库的外部开发者——也就是说，他们的代码会调用任意 doca_* 符号（直接在 C/C++ 中调用，或通过 FFI／其他语言的绑定调用）。无论用户主要使用的是 doca-flow、doca-rdma、doca-eth、doca-comch、doca-dma、doca-rmax、doca-sha、doca-aes-gcm、doca-erasure-coding，还是其他库，doca-common 都是其底层基础；在构建首个应用的过程中，用户都会用到 doca_buf、doca_ctx、doca_dev、doca_pe 和 doca_log。本技能不面向为 DOCA Common 本身做贡献的 NVIDIA 开发者。

语言范围

DOCA Common 以 C 库的形式提供，其 pkg-config 模块名为 doca-common。展示 Common 基础功能的示例位于每个库各自的示例目录中（任意 /opt/mellanox/doca/samples/<library>/<sample>/*_main.c 都是通用基础流程的完整示例——doca_devinfo_create_list → doca_dev_open → 创建库专属的 doca_ctx → doca_pe_create → doca_pe_connect_ctx → doca_ctx_start → 提交工作 → 驱动 doca_pe_progress → 清空完成项 → doca_ctx_stop → 销毁）。C 和 C++ 使用者是典型场景，任务配套内容中的完整示例也假设采用这条路径。其他语言的使用者（Rust、Go、Python，……）通过 FFI 或特定语言的绑定使用同一个 *.so；在这种情况下，本技能旨在确保通用基础流程、生命周期、能力发现规则、由 PE 驱动完成处理的规则，以及双层日志模型都与语言无关，并引导 Agent 将公开的 C ABI 视为权威接口，因为任何封装最终都会调用该接口。

何时加载此技能

用户进行任何 DOCA 实际开发工作时，都应加载此技能——它是基础。具体包括：

• 在打开任何库专属上下文（Flow、RDMA、Eth、Comch、DMA、Rmax，……）之前，搭建通用 DOCA 侧骨架。
• 发现设备和 representor，并依据活动的 doca_devinfo，通过 doca_*_cap_* 系列接口判断是否使用相应能力。
• 配置 doca_mmap + doca_buf_inventory + doca_buf，用于跨库零拷贝 I/O（例如 doca-eth 向 doca-dma 提供数据，再由 doca-dma 提供给 doca-rdma——它们共用同一套 buf 接口）。
• 驱动进度引擎（doca_pe_create / doca_pe_connect_ctx / doca_pe_progress）——这是所有 DOCA Core 上下文都依赖的通用任务完成处理机制。
• 在新应用中接入 DOCA Log，或修改已提供的示例，通过双层模型（--sdk-log-level 与应用侧注册表）添加用户自己的组件级日志行。
• 调试任意 doca_buf_* / doca_ctx_* / doca_dev_* / doca_pe_* / doca_log_* 调用返回的 DOCA_ERROR_*——对于更高级别的库，大多数生命周期／能力／权限错误都会首先出现在 Common 接口层。
• 设计或扩展封装任意 DOCA 库的非 C 绑定（Rust、Go、Python，……）——对于通用基础接口（buf、ctx、dev、pe、log），封装必须首先提供这些接口。

对于单独的、特定于库的 Flow、RDMA、Eth、Comch、DMA、Rmax 等问题，不要加载此技能——应同时加载匹配的库专属技能。对于 DOCA 通用入门、DOCA 本身的安装，或*"在哪里可以找到文档"*这类问题，也不要加载此技能。这些情况请使用 doca-public-knowledge-map/SKILL.md 或 doca-setup/SKILL.md。

此技能提供的内容

这是一个轻量加载器。正文仅保留选择下一个正确文件所需的指引。实质性的 Common 内容位于两个配套文件中：

• capabilities 配套文件——说明此安装中的 doca-common 提供哪些功能：概述所有 DOCA 应用都会用到的通用原语的 ## Capabilities and modes；负责各原语接口的五个子系统 H2（## log、## buf、## ctx、## dev、## progress engine）；doca-common 专属的 ## Version compatibility 补充说明；Common 侧对通用 DOCA_ERROR_* 集合的 ## Error taxonomy 说明；## Observability 接口（日志、PE 事件、功能快照）；以及针对整个工具包硬件安全元策略的 ## Safety policy 补充说明。
• tasks 配套文件——介绍通用动词（configure、build、modify、run、test、debug、use）的分步工作流，另有 ## log 动词侧内容，以工作流形式介绍两层日志模型。此外，还有一个 Deferred task verbs 区块，将安装、部署和回滚问题指向相应的后续技能。

此技能假设主机或 BlueField 已在标准位置安装 DOCA，并且用户具备其公开安装配置所需的权限。此技能不介绍安装 DOCA——相关流程请参阅 doca-setup/SKILL.md。

此技能有意不包含的内容

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

• 任何语言编写的 DOCA 应用预编写源代码。 已验证的 Common 用法体现在每个随附 DOCA 示例的 /opt/mellanox/doca/samples/<library>/<sample>/*_main.c 中，以及每个随附的参考应用中。Agent 的职责是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中通用的修改示例工作流，指导用户以最小差异修改这些文件。
• 技能中随附的独立构建清单（meson.build、CMakeLists.txt、Cargo.toml、setup.py、go.mod，等等）。Agent 会在用户的项目目录中，根据用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-common 是事实依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。在此技能的目录树中提供模拟或不完整的产物，即使标注为“参考”，也会造成误导：用户会认为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其范围。
2. 通用原语（log / buf / ctx / dev / progress engine）、pkg-config --modversion doca-common 基准、Common 错误补充说明、可观测性和安全策略，请参阅 capabilities 配套文件。
3. 分步工作流——configure、build、modify、run、test、debug、use、log——请参阅 tasks 配套文件。

两个配套文件彼此交叉链接，并链接至 doca-version/SKILL.md（规范的版本处理规则）、doca-programming-guide/SKILL.md（通用的修改随附示例工作流，以及跨库的 DOCA_ERROR_* 分类）、doca-debug/SKILL.md（跨领域调试阶梯），以及 doca-public-knowledge-map/SKILL.md（当正确做法是“查阅公开文档或已安装的软件包目录结构”，而不是“参考 Common 专属指引”时）。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的路由表，以及已安装 DOCA 软件包的磁盘布局。此技能始终与本技能一同提供；本技能预期可将文档查找和安装布局相关问题交由其处理，而不重复说明。
• doca-setup/SKILL.md — 环境准备、 安装验证，以及 我还没有安装 路径，其中将公开 NGC DOCA 容器（nvcr.io/nvidia/doca/doca）作为通用的 Stage-1 备用方案。本技能假设其前置条件已满足。
• doca-version/SKILL.md — DOCA 版本处理的规范规则（四方匹配、NGC 语义、 以标头为准）。pkg-config --modversion doca-common 是每个 DOCA 安装都具备的构建时基准；本技能的 ## Version compatibility 在此基础上补充 Common 专属说明。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的先修改随附示例再构建首个应用的工作流、通用生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序端调试顺序。本技能是编程指南模式所依赖的基础原语层。
• doca-debug/SKILL.md — 跨领域的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）和详细程度升级方式。DOCA Log 是 doca-debug 构建其运行时调试方案的基础；本技能是两级日志模型和通用生命周期错误首次出现的地方，doca-debug 会在这两方面链接回本技能。
• doca-structured-tools-contract/SKILL.md — 此技能包结构化工具的优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的 Command 附录遵循此约定。
• doca-hardware-safety/SKILL.md — 跨领域的硬件安全元策略，本技能的 ## Safety policy 会在此基础上进行补充。
• 按库划分的技能（doca-flow、doca-rdma、doca-eth、 doca-comch、doca-dma、doca-rmax、doca-sha、doca-aes-gcm、 doca-erasure-coding、doca-compress、doca-dpa、doca-gpunetio、 doca-pcc、doca-sta、doca-telemetry、doca-urom、 doca-verbs、doca-argp、doca-devemu、 doca-dpdk-bridge、…）——每项按库划分的技能都会链接回本技能，以使用基础原语。建议默认将本技能与其中任一技能一同加载。