--- license: Apache-2.0 name: doca-comch description: > Use this skill when the user is doing hands-on DOCA Comch work on a host + BlueField pair — bringing up host ↔ DPU PCIe control-plane messaging, picking server (DPU) vs client (host) roles, choosing slow-path send-task / recv-callback vs fast-path producer / consumer, querying max-msg-size or max-clients capabilities, registering connection callbacks, or debugging DOCA_ERROR_* returns from the Comch API. Trigger even when the user does not explicitly mention "DOCA Comch" or "Comm Channel" (renamed in DOCA 2.5) — typical implicit phrasings include "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", or "stream bulk data from a host driver to a DPU agent". Refuse and route elsewhere for installing DOCA itself, BFB / firmware bring-up, non-Comch DOCA libraries, or deploying Comch apps at scale — those belong to other skills. metadata: kind: library compatibility: > Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu 22.04/24.04 or RHEL/SLES) on a host + BlueField pair (the Comch channel runs over the RoCE/IB protocol, not the TCP/IP stack). Reads the user's local install via `pkg-config doca-comch` (legacy `doca-comm-channel` on installs <2.5) and inspects /opt/mellanox/doca/{lib,include,samples,applications}. --- # DOCA Comch **Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on Comch work** on a BlueField + host pair with DOCA. Open [`TASKS.md`](TASKS.md) if the user wants to *do* something (configure / build / modify / run / test / debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can Comch express* on this version. If the user has not installed DOCA yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first. If the user is asking *"is Comch even on this DOCA"* because the docs they read mention `doca-comm-channel`, route to [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility) for the 2.5 rename. ## Example questions this skill answers well The CLASSES of Comch questions this skill is built to answer, each with one worked example. The agent should treat the *class* as the load-bearing piece — the worked example is a single instance. - **"How do I bring up a Comch channel between host and DPU?"** — worked example: *"server side on the DPU, client side on the host, exchange a first control message"*. Answered by the role-selection + lifecycle workflow in [`TASKS.md ## configure`](TASKS.md#configure) + [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) server-vs-client table. - **"How do I move bulk data over Comch with low CPU?"** — worked example: *"stream a 64 KiB chunk every 100 µs from the host driver to a DPU agent"*. Answered by the producer / consumer fast-path described in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) + the channel-setup workflow in [`TASKS.md ## configure`](TASKS.md#configure) step 4, with the *"slow-path vs fast-path"* selection rule. - **"What is the maximum message size I can send?"** — worked example: *"can I send a 4 MiB control message in one shot?"*. Answered by the capability-query rule (`doca_comch_cap_get_max_msg_size`) in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) + the property-set workflow in [`TASKS.md ## modify`](TASKS.md#modify). - **"Why doesn't the DPU side see the representor?"** — worked example: *"`doca_comch_server_create` returns `DOCA_ERROR_NOT_PERMITTED` on a freshly imaged BlueField"*. Answered by the representor + permission overlay in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy) + the env-prep checklist in [`TASKS.md ## configure`](TASKS.md#configure) step 1, which routes representor-side env questions to [`doca-setup`](../../doca-setup/SKILL.md). - **"Is this Comch capability on my installed DOCA version?"** — worked example: *"is `doca_comch_producer` in DOCA 2.6.0, or do I still need the old slow-path API?"*. Answered by the version-compatibility overlay in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility), which cross-links the canonical detection chain in [`doca-version`](../../doca-version/SKILL.md) and adds the Comch-specific 2.5 rename rule. - **"What does this `DOCA_ERROR_*` from a Comch call mean and which layer caused it?"** — worked example: *"`DOCA_ERROR_AGAIN` on submitting a `doca_comch_task_send` via `doca_task_submit`"*. Answered by the Comch overlay on the cross-library taxonomy in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy) + the layered ladder in [`TASKS.md ## debug`](TASKS.md#debug) that escalates to [`doca-debug`](../../doca-debug/SKILL.md). ## Audience This skill serves **external developers building applications that consume the DOCA Comch library** — i.e., users whose code calls `doca_comch_*` (directly in C/C++, or through FFI/bindings from another language) to exchange control or data messages between a host process and a BlueField agent over PCIe. It is *not* for NVIDIA developers contributing to DOCA Comch itself. **Language scope.** DOCA Comch ships as a C library with `pkg-config` module name `doca-comch`. The shipped samples are written in C. C and C++ consumers are the canonical case; the worked examples in `TASKS.md` assume that path. Other-language consumers (Rust, Go, Python, …) consume the same `*.so` through FFI or language-specific bindings; the skill's contribution in that case is to keep the role-split, lifecycle, capability-discovery, permission, and error-taxonomy guidance language-neutral, and to route the agent to the public C ABI as the authoritative surface that any wrapper will eventually call. ## When to load this skill Load this skill when the user is doing hands-on DOCA Comch work, in any language. Concretely: - Initializing a `doca_comch_server` on the DPU side or a `doca_comch_client` on the host side, on a representor or PCIe address the host can reach. - Configuring at least one of: a recv callback for slow-path messages, a producer for fast-path outbound data, a consumer for fast-path inbound data, before `doca_ctx_start()`. - Reading or setting comch properties via `doca_comch_set_*` and `doca_comch_cap_get_*` — max message size, max number of clients (server side), producer / consumer queue sizing. - Establishing a connection between the two sides and reacting to connection-state transitions via the connection callbacks registered before start. - Choosing between the **slow-path** (send-task / recv-callback, message-oriented, lower throughput, single-call simplicity) and the **fast-path** (producer / consumer, asynchronous, much higher throughput, two-context setup). - Debugging a `DOCA_ERROR_*` returned from a Comch call (lifecycle vs. permission vs. capability vs. would-block) and the connection state machine across the host / DPU pair. - Designing or extending non-C bindings (Rust, Go, Python, …) that wrap the Comch C ABI — for the lifecycle, role-split, permission, and capability rules the wrapper must honor. Do **not** load this skill for general DOCA orientation, install of DOCA itself, or non-Comch library questions. For those, use [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md). ## What this skill provides This is a **thin loader**. The body keeps only the orientation needed to pick the right next file. The substantive Comch-specific material lives in two companion files: - `CAPABILITIES.md` — what Comch can express on this version: the server vs client role split, the slow-path send-task / recv-callback surface, the producer / consumer fast-path surface, the capability-query surface (`doca_comch_cap_get_*`), the Comch error taxonomy (mapped onto the cross-library `DOCA_ERROR_*` set), the observability surface (connection state callbacks, task completion callbacks), and the safety policy that gates representor and permission decisions. - `TASKS.md` — step-by-step workflows for the six in-scope Comch verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`. Plus a `Deferred task verbs` block that points out-of-scope questions at the right next skill. The skill assumes a host + BlueField pair where DOCA is already installed at the standard location and the user has the privileges their public install profile expects (in particular, sudo on the DPU side to see the host representor). It does not cover installing DOCA — that path goes through [`doca-setup`](../../doca-setup/SKILL.md). ## What this skill deliberately does not ship This skill is **agent guidance**, not a samples or templates bundle. To keep the boundary clean, it deliberately does not contain — and pull requests should not add: - **Pre-written DOCA Comch application source code, in any language.** The verified Comch source code is the shipped C samples at `/opt/mellanox/doca/samples/doca_comch//`. The agent's job is to route the user to those files and prescribe a minimum-diff modification on them via the universal modify-a-sample workflow in [`doca-programming-guide`](../../doca-programming-guide/SKILL.md), layered with the Comch-specific overrides in [`TASKS.md ## modify`](TASKS.md#modify). - **Standalone build manifests** (`meson.build`, `CMakeLists.txt`, `Cargo.toml`, …) parked inside the skill. The agent constructs the build manifest *in the user's project directory* against the user's installed DOCA, where `pkg-config --modversion doca-comch` is the source of truth. - **A `samples/`, `bindings/`, or `reference/` subtree** of any kind. A mock or incomplete artifact in this skill's tree, even one labeled "reference", is misleading: users will read it as buildable. ## Loading order 1. Read this `SKILL.md` first to confirm the user's question is in scope. 2. **For the Comch capability matrix, role split, slow-path / fast-path surfaces, permission policy, error taxonomy, observability, and safety policy, see [CAPABILITIES.md](CAPABILITIES.md).** 3. **For step-by-step workflows — configure, build, modify, run, test, debug — see [TASKS.md](TASKS.md).** Both companion files cross-link to each other, [`doca-version`](../../doca-version/SKILL.md) for the canonical version-handling rules, and [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) whenever the right answer is "look it up in the public docs or the installed package layout" rather than "Comch-specific guidance". ## Related skills - [`doca-public-knowledge-map`](../../doca-public-knowledge-map/SKILL.md) — the routing table for every public DOCA documentation source and the on-disk layout of an installed DOCA package. The Comch URL slug is `DOCA-Comch` (DOCA 2.5+), not `doca-comm-channel`. - [`doca-setup`](../../doca-setup/SKILL.md) — env preparation, install verification, representor visibility checks, and the *I have no install yet* path with the public NGC DOCA container. This skill assumes its preconditions are satisfied. - [`doca-version`](../../doca-version/SKILL.md) — canonical DOCA version-handling rules. This skill's `## Version compatibility` cross-links the four-way match rule and adds the Comch-specific 2.5 rename overlay. - [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md) — the bundle's structured-tools precedence rule (detect / prefer / fall back / report). The Command appendix in [TASKS.md](TASKS.md) honors this contract. - [`doca-programming-guide`](../../doca-programming-guide/SKILL.md) — general DOCA programming patterns shared by every library: the canonical `pkg-config` + meson build pattern, the universal modify-a-shipped-sample first-app workflow, the universal lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the program-side debug order. This skill layers Comch specifics on top. - [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting debug ladder (install / version / build / link / runtime / program / driver). Comch-specific debug (lifecycle violations, representor visibility, slow-path vs fast-path queue-full symptoms) overlays on top of that ladder.