doca-comch

DOCA Comch

示例

• “通过 PCIe 从主机向 BlueField 发送控制消息。” — 这属于本技能范围。选择服务端（DPU）或客户端（主机），并始终使用 Comch 发送／接收路径；不要改用 TCP。
• “连接回调始终不会触发。” — 检查角色、representor 可见性，以及 2.5 重命名覆盖规则，然后再考虑将应用重写为原始 verbs。

说明

请遵循下方的加载顺序。需要配置／修改／调试时，打开任务 companion。需要了解慢速路径与快速路径的区别以及 2.5 重命名时，打开功能 companion。不要打开所有 companion 文件。

从这里开始： 此技能假定 DOCA 已安装，且用户正在 BlueField 与主机组成的设备对上进行 DOCA Comch 实际操作。如果用户想要执行某项操作（配置／构建／修改／运行／测试／调试），请打开任务 companion；如果用户询问此版本的 Comch 能实现什么，请打开功能 companion。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户因为读到的文档提及 doca-comm-channel 而询问 “这个 DOCA 版本到底有没有 Comch”，请转到

版本兼容性

，了解 2.5 重命名。

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

此技能旨在回答的 Comch 问题类别，每类各附一个详细示例。Agent 应将类别视为关键所在——详细示例只是一个具体实例。

• “如何在主机和 DPU 之间建立 Comch 通道？” — 详细示例：“DPU 端作为服务端、主机端作为客户端，并交换第一条控制消息”。可通过

  配置 +

  功能和模式

  中的角色选择与生命周期工作流，以及服务端与客户端对照表来解答。
• “如何以较低 CPU 开销通过 Comch 传输大量数据？” — 详细示例： “每隔 100 µs，将一个 64 KiB 数据块从主机驱动程序流式传输到 DPU Agent”。可通过

  功能和模式

  中介绍的生产者／消费者快速路径，以及

  配置

  第 4 步中的通道设置工作流来解答，并遵循*“慢速路径与快速路径”*选择规则。
• “我最多可以发送多大的消息？” — 详细示例： “能否一次性发送一条 4 MiB 的控制消息？”。 可通过

  功能和模式

  中的功能查询规则 （doca_comch_cap_get_max_msg_size）以及

  修改

  中的属性设置工作流来解答。
• “为什么 DPU 端看不到 representor？” — 详细示例： “在刚刷写镜像的 BlueField 上，doca_comch_server_create 返回 DOCA_ERROR_NOT_PERMITTED。” 可通过

  安全策略

  中关于 representor 和权限的说明，以及

  配置第 1 步中的环境准备检查清单来解答；representor 端的环境问题应转到

  doca-setup/SKILL.md。
• “我安装的 DOCA 版本支持这项 Comch 功能吗？” — 详细示例：“DOCA 2.6.0 中有 doca_comch_producer 吗？还是仍需使用旧的慢速路径 API？”。可通过

  版本兼容性

  中的版本兼容性说明来解答；该说明会交叉链接到 doca-version/SKILL.md 中的标准检测流程，并补充 Comch 专属的 2.5 重命名规则。
• “这个 Comch 调用返回的 DOCA_ERROR_* 表示什么？是哪一层导致的？” — 详细示例： “通过 doca_task_submit 提交 doca_comch_task_send 时返回 DOCA_ERROR_AGAIN。” 可通过

  错误分类

  中对跨库错误分类的 Comch 补充说明，以及

  调试

  中会升级至 doca-debug/SKILL.md 的分层排查流程来解答。

受众

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

语言范围。 DOCA Comch 以 C 库形式提供，pkg-config 模块名称为 doca-comch。随附的示例以 C 编写。C 和 C++ 是典型的使用场景；任务配套文件中的示例也以此为前提。其他语言的使用者（Rust、Go、Python，……）通过 FFI 或特定语言的绑定使用相同的 *.so；在这种情况下，此技能将角色划分、生命周期、能力发现、权限和错误分类方面的指导保持为与语言无关的内容，并引导 Agent 使用公开的 C ABI 作为权威接口，因为任何包装器最终都会调用该接口。

何时加载此技能

当用户以任何语言实际使用 DOCA Comch 时，加载此技能。具体包括：

• 在 DPU 端初始化 doca_comch_server，或在主机端初始化 doca_comch_client，并使用主机可访问的 representor 或 PCIe 地址。
• 在 doca_ctx_start() 之前，配置以下至少一项：用于慢速路径消息的接收回调、用于快速路径出站数据的生产者，或用于快速路径入站数据的消费者。
• 通过 doca_comch_set_* 和 doca_comch_cap_get_* 读取或设置 Comch 属性，例如最大消息大小、最大客户端数量（服务端）以及生产者／消费者队列大小。
• 在两端之间建立连接，并通过启动前注册的连接回调处理连接状态转换。
• 在 慢速路径（发送任务／接收回调，面向消息、吞吐量较低、调用简单）和 快速路径（生产者／消费者、异步、吞吐量高得多、需要设置两个上下文）之间进行选择。
• 调试 Comch 调用返回的 DOCA_ERROR_*（生命周期、权限、能力或可能暂时无法处理）以及主机／DPU 对之间的连接状态机。
• 设计或扩展包装 Comch C ABI 的非 C 绑定（Rust、Go、Python，……），以遵循生命周期、角色划分、权限和能力规则。

不要将此技能用于一般 DOCA 介绍、安装 DOCA 本身或非 Comch 库相关问题。此类问题请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

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

• 能力配套文件——说明此版本的 Comch 能实现什么：服务端与客户端的角色划分、慢速路径发送任务／接收回调接口、快速路径生产者／消费者接口、能力查询接口（doca_comch_cap_get_*）、Comch 错误分类（映射到跨库的 DOCA_ERROR_* 集合）、可观测性接口（连接状态回调、任务完成回调），以及用于限制 representor 和权限决策的安全策略。
• 任务配套文件——针对六种范围内的 Comch 操作，提供分步工作流：configure、build、modify、run、test、debug。此外还有一个 Deferred task verbs 区块，将范围外的问题指向合适的后续技能。

此技能假定主机与 BlueField 配对环境中已在标准位置安装 DOCA，且用户具有其公开安装配置所要求的权限（尤其是需要在 DPU 端使用 sudo 才能查看主机 representor）。此技能不涵盖安装 DOCA；相关流程请参阅 doca-setup/SKILL.md。

此技能刻意不包含的内容

此技能是Agent 指南，不是示例或模板 合集。为明确划定边界，此技能刻意不包含以下内容—— 也不应通过拉取请求添加：

• **任何语言的预写 DOCA Comch 应用源代码。**经过验证的 Comch 源代码是已随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_comch/<name>/。Agent 的任务是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用 修改示例工作流，在这些文件上进行 最小差异修改，再叠加 ## 修改 中的 Comch 专属覆盖规则。
• 独立的构建清单（meson.build、CMakeLists.txt、 Cargo.toml，……），存放在技能目录内。Agent 会在用户的项目目录中，针对 用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-comch 是权威依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。即使在此技能目录中放入标注为“参考”的模拟或不完整产物，也会造成误导：用户会将其视为可构建内容。

加载顺序

1. 首先阅读此技能，确认用户的问题 属于其适用范围。
2. 关于 Comch 能力矩阵、角色划分、慢速路径 / 快速路径接口、权限策略、错误分类、 可观测性和安全策略，请参阅能力配套文档。
3. 关于分步工作流——配置、构建、修改、运行、 测试、调试——请参阅任务配套文档。

两个配套文件彼此交叉链接， 并链接到 doca-version/SKILL.md，以查阅规范的 版本处理规则；当正确答案是“查阅公开文档或 已安装软件包布局”，而非“Comch 专属指南”时， 也会链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的路由表，以及已安装 DOCA 软件包的磁盘布局。Comch 的 URL 路径段是 DOCA-Comch（DOCA 2.5+），而不是 doca-comm-channel。
• doca-setup/SKILL.md — 环境准备、 安装验证、representor 可见性检查，以及通过公开 NGC DOCA 容器完成的我还没有安装路径。 此技能假定其前置条件已满足。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。此技能中的 ## 版本兼容性 交叉链接到四方匹配规则，并补充了 Comch 专属的 2.5 重命名说明。
• doca-structured-tools-contract/SKILL.md — 此套件的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的命令附录 遵循此约定。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的 首个应用工作流（修改随附示例）、通用生命周期、 跨库的 DOCA_ERROR_* 错误分类，以及程序侧的调试顺序。此技能在此基础上叠加 Comch 专属内容。
• doca-debug/SKILL.md — 跨领域的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）。Comch 专属调试内容（生命周期违规、 representor 可见性、慢速路径与快速路径的队列已满 症状）叠加在该阶梯之上。