Doca Comch

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 if the user wants to

*do* something (configure / build / modify / run / test / debug);

open 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 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

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 +

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

+ the channel-setup workflow in

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

+ the property-set workflow in

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

+ the env-prep checklist in

TASKS.md ## configure step 1, which

routes representor-side env questions to

doca-setup.

• "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,

which cross-links the canonical detection chain in

doca-version 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

+ the layered ladder in

TASKS.md ## debug that escalates to

doca-debug.

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.

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.

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,

layered with the Comch-specific overrides in

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

• Read this SKILL.md 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 CAPABILITIES.md.**

• **For step-by-step workflows — configure, build, modify, run,

test, debug — see TASKS.md.**

Both companion files cross-link to each other,

doca-version for the canonical

version-handling rules, and

doca-public-knowledge-map

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 —

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 — 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 — 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 —

the bundle's structured-tools precedence rule (detect / prefer

/ fall back / report). The Command appendix in

TASKS.md honors this contract.

• doca-programming-guide —

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 — 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.