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) inCapabilities 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 inSafety 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 inVersion 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 inError taxonomy
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 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/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:
- the capabilities companion — 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.
- the tasks companion — 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/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/<name>/. 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/SKILL.md,
layered with the Comch-specific overrides inmodify.
- 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
- Read this skill first to confirm the user's question is
in scope.
- For the Comch capability matrix, role split, slow-path /
fast-path surfaces, permission policy, error taxonomy,
observability, and safety policy, see the capabilities companion.
- For step-by-step workflows — configure, build, modify, run,
test, debug — see the tasks companion.
Both companion files cross-link to each other,
doca-version/SKILL.md for the canonical
version-handling rules, and
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/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/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/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/SKILL.md —
the bundle's structured-tools precedence rule (detect / prefer
/ fall back / report). The Command appendix in
the tasks companion honors this contract.
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/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.
1---2license: Apache-2.03name: doca-comch4description: >5 Use this skill when the user is doing hands-on DOCA Comch work on a6 host + BlueField pair — bringing up host ↔ DPU PCIe control-plane7 messaging, picking server (DPU) vs client (host) roles, choosing8 slow-path send-task / recv-callback vs fast-path producer / consumer,9 querying max-msg-size or max-clients capabilities, registering10 connection callbacks, or debugging DOCA_ERROR_* returns from the Comch11 API. Trigger even when the user does not explicitly mention "DOCA12 Comch" or "Comm Channel" (renamed in DOCA 2.5) — typical implicit13 phrasings include "send a control message from host to BlueField over14 PCIe", "DPU can't see the host representor", "DOCA_ERROR_NOT_PERMITTED15 on server_create", "DOCA_ERROR_AGAIN on task_send submit", "connect16 callback never fires", or "stream bulk data from a host driver to a17 DPU agent". Refuse and route elsewhere for installing DOCA itself, BFB18 / firmware bring-up, non-Comch DOCA libraries, or deploying Comch apps19 at scale — those belong to other skills.20metadata:21 source: https://skillmd.com/skills/nvidia/doca-comch22 author: NVIDIA <doca-feedback@nvidia.com>23 kind: library24 doca_version: "3.5"25 tags:26 - doca27 - comch28 - comm-channel29compatibility: >30 Requires DOCA SDK installed at /opt/mellanox/doca on Linux31 (Ubuntu 22.04/24.04 or RHEL/SLES) on a host + BlueField pair32 (the Comch channel runs over the RoCE/IB protocol, not the33 TCP/IP stack). Reads the user's34 local install via `pkg-config doca-comch` (legacy35 `doca-comm-channel` on installs <2.5) and inspects36 /opt/mellanox/doca/{lib,include,samples,applications}.37 The validation steps require a live DOCA install.38---3940# DOCA Comch4142## Examples4344- **"Send a control message from host to BlueField over PCIe."** —45 this is in scope. Pick server (DPU) vs client (host) and stay46 on the Comch send/recv path; do not fall back to TCP.47- **"Connect callback never fires."** — check role, representor48 visibility, and the 2.5 rename overlay before rewriting the49 app as raw verbs.5051## Instructions5253Follow Loading order below. Open the tasks companion for configure /54modify / debug. Open the capabilities companion for slow-path vs55fast-path and the 2.5 rename. Do not open every companion file.5657**Where to start:** This skill assumes DOCA is already installed and58the user is doing **hands-on Comch work** on a BlueField + host59pair with DOCA. Open the tasks companion if the user wants to60*do* something (configure / build / modify / run / test / debug);61open the capabilities companion when the question is62*what can Comch express* on this version. If the user has not63installed DOCA yet, route to64`doca-setup/SKILL.md` first. If the user is65asking *"is Comch even on this DOCA"* because the docs they read66mention `doca-comm-channel`, route to67## Version compatibility68for the 2.5 rename.6970## Example questions this skill answers well7172The CLASSES of Comch questions this skill is built to answer, each73with one worked example. The agent should treat the *class* as the74load-bearing piece — the worked example is a single instance.7576- **"How do I bring up a Comch channel between host and DPU?"** —77 worked example: *"server side on the DPU, client side on the78 host, exchange a first control message"*. Answered by the79 role-selection + lifecycle workflow in80 ## configure +81 ## Capabilities and modes82 server-vs-client table.83- **"How do I move bulk data over Comch with low CPU?"** — worked84 example: *"stream a 64 KiB chunk every 100 µs from the host85 driver to a DPU agent"*. Answered by the producer / consumer86 fast-path described in87 ## Capabilities and modes88 + the channel-setup workflow in89 ## configure90 step 4, with the *"slow-path vs fast-path"* selection rule.91- **"What is the maximum message size I can send?"** — worked92 example: *"can I send a 4 MiB control message in one shot?"*.93 Answered by the capability-query rule94 (`doca_comch_cap_get_max_msg_size`) in95 ## Capabilities and modes96 + the property-set workflow in97 ## modify.98- **"Why doesn't the DPU side see the representor?"** — worked99 example: *"`doca_comch_server_create` returns100 `DOCA_ERROR_NOT_PERMITTED` on a freshly imaged BlueField"*.101 Answered by the representor + permission overlay in102 ## Safety policy103 + the env-prep checklist in104 ## configure step 1, which105 routes representor-side env questions to106 `doca-setup/SKILL.md`.107- **"Is this Comch capability on my installed DOCA version?"** —108 worked example: *"is `doca_comch_producer` in DOCA 2.6.0, or do109 I still need the old slow-path API?"*. Answered by the110 version-compatibility overlay in111 ## Version compatibility,112 which cross-links the canonical detection chain in113 `doca-version/SKILL.md` and adds the114 Comch-specific 2.5 rename rule.115- **"What does this `DOCA_ERROR_*` from a Comch call mean and116 which layer caused it?"** — worked example: *"`DOCA_ERROR_AGAIN`117 on submitting a `doca_comch_task_send` via `doca_task_submit`"*. Answered by the Comch118 overlay on the cross-library taxonomy in119 ## Error taxonomy120 + the layered ladder in121 ## debug that escalates to122 `doca-debug/SKILL.md`.123124## Audience125126This skill serves **external developers building applications that127consume the DOCA Comch library** — i.e., users whose code calls128`doca_comch_*` (directly in C/C++, or through FFI/bindings from129another language) to exchange control or data messages between a130host process and a BlueField agent over PCIe. It is *not* for131NVIDIA developers contributing to DOCA Comch itself.132133**Language scope.** DOCA Comch ships as a C library with134`pkg-config` module name `doca-comch`. The shipped samples are135written in C. C and C++ consumers are the canonical case; the136worked examples in the tasks companion assume that path. Other-language137consumers (Rust, Go, Python, …) consume the same `*.so` through138FFI or language-specific bindings; the skill's contribution in139that case is to keep the role-split, lifecycle,140capability-discovery, permission, and error-taxonomy guidance141language-neutral, and to route the agent to the public C ABI as142the authoritative surface that any wrapper will eventually call.143144## When to load this skill145146Load this skill when the user is doing hands-on DOCA Comch work,147in any language. Concretely:148149- Initializing a `doca_comch_server` on the DPU side or a150 `doca_comch_client` on the host side, on a representor or PCIe151 address the host can reach.152- Configuring at least one of: a recv callback for slow-path153 messages, a producer for fast-path outbound data, a consumer for154 fast-path inbound data, before `doca_ctx_start()`.155- Reading or setting comch properties via `doca_comch_set_*` and156 `doca_comch_cap_get_*` — max message size, max number of157 clients (server side), producer / consumer queue sizing.158- Establishing a connection between the two sides and reacting to159 connection-state transitions via the connection callbacks160 registered before start.161- Choosing between the **slow-path** (send-task / recv-callback,162 message-oriented, lower throughput, single-call simplicity) and163 the **fast-path** (producer / consumer, asynchronous, much164 higher throughput, two-context setup).165- Debugging a `DOCA_ERROR_*` returned from a Comch call (lifecycle166 vs. permission vs. capability vs. would-block) and the167 connection state machine across the host / DPU pair.168- Designing or extending non-C bindings (Rust, Go, Python, …) that169 wrap the Comch C ABI — for the lifecycle, role-split,170 permission, and capability rules the wrapper must honor.171172Do **not** load this skill for general DOCA orientation, install173of DOCA itself, or non-Comch library questions. For those, use174`doca-public-knowledge-map/SKILL.md`.175176## What this skill provides177178This is a **thin loader**. The body keeps only the orientation179needed to pick the right next file. The substantive Comch-specific180material lives in two companion files:181182- the capabilities companion — what Comch can express on this version: the183 server vs client role split, the slow-path send-task /184 recv-callback surface, the producer / consumer fast-path185 surface, the capability-query surface186 (`doca_comch_cap_get_*`), the Comch error taxonomy (mapped onto187 the cross-library `DOCA_ERROR_*` set), the observability surface188 (connection state callbacks, task completion callbacks), and189 the safety policy that gates representor and permission190 decisions.191- the tasks companion — step-by-step workflows for the six in-scope Comch192 verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`.193 Plus a `Deferred task verbs` block that points out-of-scope194 questions at the right next skill.195196The skill assumes a host + BlueField pair where DOCA is already197installed at the standard location and the user has the privileges198their public install profile expects (in particular, sudo on the199DPU side to see the host representor). It does not cover installing200DOCA — that path goes through201`doca-setup/SKILL.md`.202203## What this skill deliberately does not ship204205This skill is **agent guidance**, not a samples or templates206bundle. To keep the boundary clean, it deliberately does not207contain — and pull requests should not add:208209- **Pre-written DOCA Comch application source code, in any210 language.** The verified Comch source code is the shipped C211 samples at `/opt/mellanox/doca/samples/doca_comch/<name>/`. The212 agent's job is to route the user to those files and prescribe a213 minimum-diff modification on them via the universal214 modify-a-sample workflow in215 `doca-programming-guide/SKILL.md`,216 layered with the Comch-specific overrides in217 ## modify.218- **Standalone build manifests** (`meson.build`, `CMakeLists.txt`,219 `Cargo.toml`, …) parked inside the skill. The agent constructs220 the build manifest *in the user's project directory* against221 the user's installed DOCA, where `pkg-config --modversion222 doca-comch` is the source of truth.223- **A `samples/`, `bindings/`, or `reference/` subtree** of any224 kind. A mock or incomplete artifact in this skill's tree, even225 one labeled "reference", is misleading: users will read it as226 buildable.227228## Loading order2292301. Read this skill first to confirm the user's question is231 in scope.2322. **For the Comch capability matrix, role split, slow-path /233 fast-path surfaces, permission policy, error taxonomy,234 observability, and safety policy, see the capabilities companion.**2353. **For step-by-step workflows — configure, build, modify, run,236 test, debug — see the tasks companion.**237238Both companion files cross-link to each other,239`doca-version/SKILL.md` for the canonical240version-handling rules, and241`doca-public-knowledge-map/SKILL.md`242whenever the right answer is "look it up in the public docs or243the installed package layout" rather than "Comch-specific244guidance".245246## Related skills247248- `doca-public-knowledge-map/SKILL.md` —249 the routing table for every public DOCA documentation source and250 the on-disk layout of an installed DOCA package. The Comch URL251 slug is `DOCA-Comch` (DOCA 2.5+), not `doca-comm-channel`.252- `doca-setup/SKILL.md` — env preparation,253 install verification, representor visibility checks, and the *I254 have no install yet* path with the public NGC DOCA container.255 This skill assumes its preconditions are satisfied.256- `doca-version/SKILL.md` — canonical257 DOCA version-handling rules. This skill's `## Version258 compatibility` cross-links the four-way match rule and adds the259 Comch-specific 2.5 rename overlay.260- `doca-structured-tools-contract/SKILL.md` —261 the bundle's structured-tools precedence rule (detect / prefer262 / fall back / report). The Command appendix in263 the tasks companion honors this contract.264- `doca-programming-guide/SKILL.md` —265 general DOCA programming patterns shared by every library: the266 canonical `pkg-config` + meson build pattern, the universal267 modify-a-shipped-sample first-app workflow, the universal268 lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the269 program-side debug order. This skill layers Comch specifics on270 top.271- `doca-debug/SKILL.md` — the cross-cutting272 debug ladder (install / version / build / link / runtime /273 program / driver). Comch-specific debug (lifecycle violations,274 representor visibility, slow-path vs fast-path queue-full275 symptoms) overlays on top of that ladder.