⚡

DOCA通信通道（DOCAComch）Skill doca-comch

本技能用于指导 NVIDIA BlueField DPU 与主机之间的 DOCA Comch（通信通道）开发、配置与调试工作。涵盖主机↔DPU PCIe 控制平面消息、服务端/客户端角色选择、慢路径/快路径配置、能力查询、连接回调及 DOCA_ERROR_* 错误诊断。关键词：DOCA、Comch、Comm Channel、BlueField、DPU、主机通信、PCIe、控制平面、快路径、慢路径。

高速通信 0 次安装 0 次浏览 更新于 9/6/2026
开源协议 Apache-2.0
名称 doca-comch
描述 > 当用户在 host + BlueField 主机对上从事 DOCA Comch 实操工作时使用本技能——包括：启动 host ↔ DPU PCIe 控制面消息收发；选择服务器(DPU)与客户端(host)角色；选择慢路径 send-task / recv-callback 还是快路径 producer / consumer；查询 max-msg-size 或 max-clients 能力；注册连接回调；或调试 Comch API 返回的 DOCA_ERROR_* 错误。即使未明确提到 “DOCA Comch” 或 “Comm Channel”（在 DOCA 2.5 中更名）也触发——典型的隐含表述包括 “send a control message from host to BlueField over PCIe”、“DPU can’t see the host representor”、“DOCA_ERROR_NOT_PERMITTED on server_create”、“DOCA_ERROR_AGAIN on task_send submit”、“connect callback never fires” 或 “stream bulk data from a host driver to a DPU agent”。对于安装 DOCA 本身、BFB / 固件启动、非 Comch 的 DOCA 库、或在规模上部署 Comch 应用，请拒绝并路由到其他技能——这些属于其他技能。 metadata: kind: library compatibility: > 要求 DOCA SDK 安装在 Linux（Ubuntu 22.04/24.04 或 RHEL/SLES）上的 /opt/mellanox/doca，且适用 host + BlueField 主机对（Comch 通道运行在 RoCE/IB 协议之上，不是 TCP/IP 协议栈）。通过 pkg-config doca-comch（在 <2.5 的安装中为旧版 doca-comm-channel）读取用户的本地安装，并检查 /opt/mellanox/doca/{lib,include,samples,applications}。

DOCA 通信通道（DOCA Comch）

从哪里开始： 本技能假定 DOCA 已经安装，并且用户正在 BlueField + 主机对上执行 Comch 实操。如果用户想要执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开 TASKS.md；如果问题是这个版本 Comch 能够表达什么，请打开 CAPABILITIES.md。如果用户尚未安装 DOCA，请首先转到 doca-setup。如果用户因为阅读的文档提到 doca-comm-channel 而问 “这个 DOCA 上有没有 Comch？”，请转到 CAPABILITIES.md ## 版本兼容性 了解 2.5 中的重命名。

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

本技能构建用于回答的 Comch 问题类别，每个类别附带一个已演练示例。智能体应将类别视为承载重量的部分——而示例只是一个单个实例。

  • “如何在主机与DPU之间建立Comch通道？” — 示例：“DPU 侧为服务端，主机侧为客户端，交换第一条控制消息”。由 TASKS.md ## 配置 中的角色选择 + 生命周期工作流，以及 CAPABILITIES.md ## 能力与模式 中的服务端-客户端对照表来解答。
  • “如何在低 CPU 下通过 Comch 传输大量数据？” — 示例：“每 100 µs 从主机驱动程序向 DPU 代理程序流式传输一个 64 KiB 的块”。由 CAPABILITIES.md ## 能力与模式 中描述的 producer / consumer 快路径、TASKS.md ## 配置 中的通道设置工作流步骤 4，以及 “慢路径 vs 快路径” 选择规则来解答。
  • “我能发送的最大消息大小是多少？” — 示例：“我能一次发送 4 MiB 的控制消息吗？”。由 CAPABILITIES.md ## 能力与模式 中的能力查询规则（doca_comch_cap_get_max_msg_size）以及 TASKS.md ## 修改 中的属性设置工作流来解答。
  • “为什么 DPU 侧看不到 representor？” — 示例：“在刚刷完镜像的 BlueField 上，doca_comch_server_create 返回 DOCA_ERROR_NOT_PERMITTED”。由 CAPABILITIES.md ## 安全策略 中的 representor + 权限叠加内容、以及 TASKS.md ## 配置 第 1 步中的环境准备清单来解答，该清单将 representor 侧环境问题路由到 doca-setup。
  • “我安装的 DOCA 版本是否包含此 Comch 能力？” — 示例：“doca_comch_producer 在 DOCA 2.6.0 中存在吗，还是仍需要使用旧的慢路径 API？”。由 CAPABILITIES.md ## 版本兼容性 中的版本兼容性叠加来解答，它与 doca-version 中的标准检测链交叉引用，并加入 Comch 特有的 2.5 重命名规则。
  • “Comch 调用返回的某个 DOCA_ERROR_* 是什么意思，由哪一层导致？” — 示例：“通过 doca_task_submit 提交 doca_comch_task_send 时返回 DOCA_ERROR_AGAIN”。由 CAPABILITIES.md ## 错误分类 中跨库分类上的 Comch 叠加内容，以及 TASKS.md ## 调试 中升级到 doca-debug 的分层递进阶梯来解答。

受众

本技能服务于构建使用 DOCA Comch 库的应用的外部开发者——即代码调用 doca_comch_*（直接用 C/C++，或通过其他语言的 FFI/绑定）以通过 PCIe 在主机进程与 BlueField 代理之间交换控制消息或数据消息的开发者。它不面向为 DOCA Comch 本身贡献代码的 NVIDIA 开发者。

语言范围。 DOCA Comch 是一个 C 库，其 pkg-config 模块名为 doca-comch。提供的示例使用 C 编写。C 和 C++ 使用者是典型场景；TASKS.md 中的演练示例假定该路径。其他语言的使用者（Rust、Go、Python 等）通过 FFI 或语言特定的绑定来消费相同的 *.so；在这种情况下，本技能的贡献是使角色划分、生命周期、能力发现、权限和错误分类指导保持语言中立，并引导智能体使用公共 C ABI 作为所有包装最终都会调用的权威接口。

何时加载本技能

当用户以任何语言进行 DOCA Comch 实操时，加载本技能。具体场景包括：

  • 在 DPU 侧初始化 doca_comch_server，或在主机侧初始化 doca_comch_client，且使用主机可访问的 representor 或 PCIe 地址。
  • 在 doca_ctx_start() 之前，至少配置以下一项：用于慢路径消息的 recv 回调、用于快路径出站数据的 producer、用于快路径入站数据的 consumer。
  • 通过 doca_comch_set_* 和 doca_comch_cap_get_* 读取或设置 comch 属性——最大消息大小、最大客户端数量（服务器侧）、producer / consumer 队列大小。
  • 在两侧之间建立连接，并通过启动前注册的连接回调对连接状态变化做出反应。
  • 在 慢路径（send-task / recv-callback，面向消息，吞吐量较低，单次调用简单）和 快路径（producer / consumer，异步，吞吐量高得多，双上下文设置）之间进行选择。
  • 调试 Comch 调用返回的 DOCA_ERROR_*（生命周期 vs. 权限 vs. 能力 vs. 将阻塞）以及主机/DPU 对之间的连接状态机。
  • 设计或扩展现有的或新的非 C 绑定（Rust、Go、Python 等）以包装 Comch C ABI——从而了解包装器必须遵守的生命周期、角色划分、权限和能力规则。

对于一般的 DOCA 方向、DOCA 本身的安装或非 Comch 库的问题，不要加载本技能。对于这些情况，请使用 doca-public-knowledge-map。

本技能提供的内容

这是一个薄装载器。主体仅包含选择正确下一步文件所需的指导。实质性的 Comch 专属内容位于两个配套文件中：

  • CAPABILITIES.md — 此版本上 Comch 能表达什么：server 与 client 的角色划分、慢路径 send-task / recv-callback 的表层、producer / consumer 快路径的表层、能力查询表层（doca_comch_cap_get_*）、Comch 错误分类（映射到跨库的 DOCA_ERROR_* 集合）、可观测性表层（连接状态回调、任务完成回调），以及控制 representor 与权限决策的安全策略。
  • TASKS.md — 六个范围内 Comch 动词的分步工作流：configure、build、modify、run、test、debug。另外还有一个 Deferred task verbs 块，用于将范围外问题指向正确的下一个技能。

本技能假定存在一个 host + BlueField 主机对，DOCA 已安装在标准位置，并且用户拥有其公共安装配置所期望的权限（特别是，在 DPU 侧需要 sudo 才能看到主机 representor）。它不涵盖安装 DOCA——该路径经由 doca-setup。

本技能刻意不包含的内容

本技能属于智能体指南，不是示例或模板包。为了保持边界清晰，它刻意不包含——也不应通过拉取请求添加：

  • 任何语言的预编写 DOCA Comch 应用源代码。 经验证的 Comch 源代码是随附在 /opt/mellanox/doca/samples/doca_comch/<name>/ 目录下的 C 示例。智能体的职责是把用户引向这些文件，并通过 doca-programming-guide 中的通用修改示例工作流，结合 TASKS.md ## 修改 中的 Comch 特定覆盖，为其指定最小差异修改。
  • 独立的构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）驻留在技能内部。智能体应在用户的项目目录中，根据用户已安装的 DOCA 来构建构建清单，其中 pkg-config --modversion doca-comch 是事实来源。
  • 任何类型的 samples/、bindings/ 或 reference/ 子目录树。 本技能目录树中的模拟或不完整工件，即使标记为 “reference”，也会造成误导：用户会认为它可以构建。

加载顺序

  1. 首先阅读此 SKILL.md，以确认用户的问题在范围内。
  2. 有关 Comch 能力矩阵、角色划分、慢路径/快路径表层、权限策略、错误分类、可观测性和安全策略，请参阅 CAPABILITIES.md。
  3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅 TASKS.md。

两个配套文件相互交叉引用，doca-version 用于标准的版本处理规则，当正确答案是 “在公共文档或已安装的软件包布局中查找” 而非 “Comch 特定指南” 时，则使用 doca-public-knowledge-map。

相关技能

  • doca-public-knowledge-map — 这是每个公共 DOCA 文档源和已安装 DOCA 软件包磁盘布局的路由表。Comch 的 URL 段是 DOCA-Comch（DOCA 2.5+），而不是 doca-comm-channel。
  • doca-setup — 环境准备、安装验证、representor 可见性检查，以及 “我尚未安装” 的路径（使用公共 NGC DOCA 容器）。本技能假定其前置条件已满足。
  • doca-version — 规范的 DOCA 版本处理规则。本技能的 ## Version compatibility 与四项匹配规则交叉引用，并添加了 Comch 特定的 2.5 重命名叠加层。
  • doca-structured-tools-contract — 该技能包的结构化工具优先规则（检测 / 优先 / 回退 / 报告）。TASKS.md 中的命令附录遵循此约定。
  • doca-programming-guide — 所有库共享的通用 DOCA 编程模式：标准的 pkg-config + meson 构建模式、通用的修改随附示例的第一个应用工作流、通用生命周期、跨库 DOCA_ERROR_* 分类以及程序端调试顺序。本技能在其上叠加了 Comch 特定的内容。
  • doca-debug — 横切调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。Comch 特有的调试内容（生命周期违规、representor 可见性、慢路径与快路径队列已满的症状）叠加在该阶梯之上。