/doca-comm-channel-admin

license: Apache-2.0
name: doca-comm-channel-admin
description: >
  Use this skill to enumerate host↔DPU DOCA comch (formerly
  Comm Channel) servers and connections via the shipped
  doca_comm_channel_admin binary — listing comch-capable
  devices and decoding the per-device server / connection
  table (server name, PID, in-use / max, PCIe address). The
  shipped binary is a SINGLE-SHOT SCAN-AND-PRINT tool with no
  registered arguments — NO list / inspect / drain / restart
  subcommands; one inventory pass over every comch-capable
  doca_dev on this side. Channel reset / drain / restart go to
  doca-comch (program side), doca-setup / doca-hardware-safety
  (driver reload), or BFB / RShim — NOT to this binary.
  Trigger on phrasings like "list comch servers", "which
  channels are active on this BlueField", or "verify admin
  tool sees same channel as program." Refuse and route
  elsewhere for the comch programming API, library install,
  protocol design, channel reset, or general orientation.
metadata:
  kind: tool
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux
  (Ubuntu 22.04/24.04 or RHEL/SLES) with the Comm Channel tooling
  subpackage so the CLI is present under
  /opt/mellanox/doca/tools/. Runs from either the x86/Arm host or
  the BlueField Arm side; a live host↔DPU comch channel created
  via the doca-comch library is needed for non-empty tables.

DOCA Comm Channel Admin Tool

> **Actual binary contract.** `doca_comm_channel_admin` is one > zero-application-argument, read-only scan-and-print operation. > It scans every comch-capable `doca_dev` on the current side via > `resourcedump` (MFT) and prints SERVERS and CONNECTIONS tables. > It has no list, inspect, device-scope, drain, restart, or other > application operation. This skill does not retain conceptual > workflows under invented command names.

**Where to start:** This is a tool skill for invoking the DOCA Comm Channel Admin Tool — the **read-only inventory** CLI counterpart to the [`doca-comch`](../../libs/doca-comch/SKILL.md) library. The shipped `doca_comm_channel_admin` binary takes **no arguments beyond ARGP defaults** (`--help`, `--version`, `--log-level`, `--sdk-log-level`, `--json`) and performs **one inventory pass** per invocation: it walks every `doca_dev` on this side, filters to comch-capable devices, shells out to `resourcedump` (MFT) on each, and prints two ASCII tables (SERVERS and CONNECTIONS). There is no `list` subcommand, no `inspect` subcommand, no `drain` flag, and no `restart` flag — those are not part of the tool's surface. Open [`TASKS.md`](TASKS.md) and start at [`## run`](TASKS.md#run) for the single-shot invocation, or [`## debug`](TASKS.md#debug) when the user reports the tool sees a different channel set than the program. Open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what the printed tables actually mean* and *what is not in this tool's scope*. If the user has not installed DOCA yet, route to [`doca-setup`](../../doca-setup/SKILL.md) first; if the user needs MFT (`resourcedump` on `PATH` with the privilege documented for the installed release), `doca-setup` + `doca-public-knowledge-map` cover that. If the user is holding pre-2.5 docs that mention "Comm Channel", route to [`doca-comch CAPABILITIES.md ## Version compatibility`](../../libs/doca-comch/CAPABILITIES.md#version-compatibility) for the rename rule. If the user wants to *change* channel state, route to the program-side reconnect lifecycle in [`doca-comch`](../../libs/doca-comch/SKILL.md) or to BlueField mode / driver reload in [`doca-setup`](../../doca-setup/SKILL.md) + [`doca-hardware-safety`](../../doca-hardware-safety/SKILL.md) — **not** to this tool.

Example questions this skill answers well

The CLASSES of admin-tool questions this skill is built to answer, each with one worked example. The class is the load-bearing piece; the worked example is one instance.

• **"Which comch servers and connections are currently visible?"** —

worked example: *"print every server and connection row visible on this side"*. Answered by the scan-and-print surface in [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the single invocation in

[`TASKS.md ## run`](TASKS.md#run).

• **"What does the tool report for this server or connection?"** —

locate the matching row in the SERVERS or CONNECTIONS table; there is no second per-channel query. Answered by [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• [`TASKS.md ## run`](TASKS.md#run).
• **"How do I know the admin tool's view matches what my Comch

program sees?"** — worked example: *"the program reports CONNECTED but the admin tool lists zero channels"*. Answered by the cross-checking pattern in [`TASKS.md ## test`](TASKS.md#test) and the representor-binding layer in [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).

• **"Is this admin tool on my installed DOCA version, and does it

match the comch library version?"** — worked example: *"is the tool available on DOCA 2.4"*. Answered by the overlay in [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility), which redirects to the canonical [`doca-version`](../../doca-version/SKILL.md) rules and adds the Comm Channel Admin Tool specifics.

• **"The tool prints nothing — is the install broken or is there

genuinely no channel?"** — worked example: *"`list` returned an empty result on a host with a known-good Comch client"*. Answered by the empty-output interpretation rules in [`TASKS.md ## debug`](TASKS.md#debug) + [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy).

Audience

This skill serves **external operators and AI agents who need to inventory a host-DPU comch channel from the outside** — after the [`doca-comch`](../../libs/doca-comch/SKILL.md) library has been used to create the channel from a prog