doca-comm-channel-admin

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• SKILLCARD.yaml
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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 used to create the channel from a program. Concretely:

- A platform operator who runs a Comch-using service on BlueField
  and needs to confirm the channel is healthy before declaring the
  service ready.
- A developer of a Comch consumer who sees `DOCA_ERROR_AGAIN` or a
  silent stall on the program side and wants to read the channel's
  state from outside the program rather than guessing.
- An AI agent capturing the external server/connection rows before
  recommending a program-side code or lifecycle change.

It is **not** for users debugging the admin tool itself, **not** a
substitute for the live public DOCA Comm Channel Admin Tool guide,
and **not** the right place for users learning the comch API —
that audience belongs in
`doca-comch/SKILL.md`.

The tool is shipped as a CLI binary under
`/opt/mellanox/doca/tools/`, not a library you link against. The

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills