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`](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 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 orientat