/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:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: tool
  doca_version: "3.5"
  tags:
    - doca
    - comch
    - tools
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. The validation steps require a live DOCA install.

DOCA Comm Channel Admin Tool

Examples

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

this is in scope. Stay on the admin CLI; do not open a new comch channel from this skill.

• **"The program reports CONNECTED but the admin tool lists zero

channels."** — cross-check representor binding before rewriting the comch app.

Instructions

Follow Loading order below. Open the tasks companion for run / debug. Open the capabilities companion for table columns and error layers. Do not open every companion file.

> **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/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 the tasks companion and start at `## run` for the single-shot invocation, or `## debug` when the user reports the tool sees a different channel set than the program. Open the capabilities companion 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/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/SKILL.md` for the rename rule. If the user wants to *change* channel state, route to the program-side reconnect lifecycle in `doca-comch/SKILL.md` or to BlueField mode / driver reload in `doca-setup/SKILL.md` + `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 the capabilities companion

• the single invocation in

the tasks companion.

• **"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 the capabilities companion

• the tasks companion.
• **"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 the tasks companion and the representor-binding layer in the capabilities companion.

• **"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 the capabilities companion, which redirects to the canonical `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 the tasks companion + the capabilities companion.

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/SKILL.md` library has been