doca-comch

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

  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 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 the capabilities companion.
3. 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.