/doca-comch

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