/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:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - comch
    - comm-channel
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}.
  The validation steps require a live DOCA install.

DOCA Comch

Examples

• **"Send a control message from host to BlueField over PCIe."** —

this is in scope. Pick server (DPU) vs client (host) and stay on the Comch send/recv path; do not fall back to TCP.

• **"Connect callback never fires."** — check role, representor

visibility, and the 2.5 rename overlay before rewriting the app as raw verbs.

Instructions

Follow Loading order below. Open the tasks companion for configure / modify / debug. Open the capabilities companion for slow-path vs fast-path and the 2.5 rename. Do not open every companion file.

**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 the tasks companion if the user wants to *do* something (configure / build / modify / run / test / debug); open the capabilities companion when the question is *what can Comch express* on this version. If the user has not installed DOCA yet, route to `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

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

configure +

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 and modes

• the channel-setup workflow in

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 and modes

• the property-set workflow in

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

Safety policy

• the env-prep checklist in

configure step 1, which

routes representor-side env questions to `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

Version compatibility,

which cross-links the canonical detection chain in `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

Error taxonomy

• the layered ladder in

debug that escalates to

`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 the tasks companion 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