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
- "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
skill uses the same kind: tool three-file shape as the rest of
the bundle so the agent's task-verb contract
(configure / build / modify / run / test / debug) is uniform
across libraries, services, and tools.
When to load this skill
Load this skill when the user is — or the agent needs to — invoke
the DOCA Comm Channel Admin Tool on a real host or BlueField Arm
with DOCA installed (or inside the public NGC DOCA container with
the right device passthrough). Concretely:
- Listing currently active comch channels on a host or DPU.
- Reading the row for one named server or connection from the
complete zero-argument scan.
- Cross-checking the admin tool's view against the program-side
connection callback state when the two appear to disagree.
- Capturing a side-effect-free channel snapshot as prerequisite
evidence for a later debug session that crosses program /
channel / driver layers.
Do not load this skill for general DOCA orientation, the comch
programming API, library install, or comch protocol design. For
those, route to
doca-public-knowledge-map/SKILL.md,
doca-comch/SKILL.md, or
doca-setup/SKILL.md.
What this skill provides
This is a thin loader. Substantive material lives in two
companion files:
- the capabilities companion — what the Comm Channel Admin Tool reports:
the two read-only tables, the version-availability overlay
that redirects to
doca-version/SKILL.md,
the layered error taxonomy (tool-not-installed / device-binding
/ channel-discovery / channel-state-stuck / permission /
version / cross-cutting), the tool's role as an observability
primitive for doca-comch/SKILL.md
debug sessions, and the read-only safety policy.
- the tasks companion — step-by-step workflows for the in-scope task verbs:
configure (route to install), build (route to install),
modify (refuse), run (one scan-and-print), test
(cross-check the printed rows), debug (the layered
diagnosis ladder), plus a Deferred task verbs block and a
Command appendix that honors the bundle's
doca-structured-tools-contract/SKILL.md
preamble.
The skill assumes a host or BlueField where DOCA is already
installed (or the public NGC DOCA container is running with the
right device passthrough) and the operator has whatever privileges
the public DOCA Comm Channel Admin Tool guide requires.
What this skill deliberately does not ship
This skill is agent guidance, not a samples or scripts bundle.
To keep the boundary clean, it deliberately does not contain — and
pull requests should not add:
- Verbatim flag inventories, subcommand names, or output column
names. The public DOCA Comm Channel Admin Tool guide on
docs.nvidia.com and the installed --help on the user's
version are the joint source of truth; copying them here pins
the skill to one release and silently rots when the tool
evolves. The skill routes the agent at those sources instead.
- Pre-baked example output. Output is install-, version-, and
channel-state-specific. A captured example will mislead an
operator on a different platform / state.
- Wrappers, parsers, or scripts in any language that consume
the admin tool's output. The output format is documented; users
who want to script against it should read the live guide and
write the parser against their installed version.
- A
samples/ or reference/ subtree. This is a thin loader
for a documented CLI; substantive material lives on the public
page and in --help.
Loading order
- Read this skill first to confirm the user's question is in
scope (the user wants to inventory a comch
channel from the outside, not learn the comch API).
- For what the tool reports, version availability, the layered error surface,
observability, and safety posture, see
the capabilities companion.
- For the single invocation and cross-check
workflow —
configure, build, modify, run, test,
debug, plus the Command appendix — see
the tasks companion.
Related skills
doca-comch/SKILL.md — the library
whose channels this tool inventories. Pair them in every
triage session: the program-side connection callback and the
admin tool's channel state are the two halves of the same
picture.
doca-public-knowledge-map/SKILL.md
— routing to the public DOCA Comm Channel Admin Tool guide and
the rest of the public DOCA documentation set.
doca-version/SKILL.md — canonical DOCA
version-handling rules. The ## Version compatibility section
in the capabilities companion is a concise overlay
that redirects here for the body.
doca-structured-tools-contract/SKILL.md
— the bundle's detect → prefer → fall back → report contract for
structured helper tools. The Command appendix in
the tasks companion honors this contract.
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-debug/SKILL.md — the cross-cutting
debug ladder. The Comm Channel Admin Tool slots in at the
runtime layer as the read-only inventory surface before any
code change is recommended.
1---2license: Apache-2.03name: doca-comm-channel-admin4description: >5 Use this skill to enumerate host↔DPU DOCA comch (formerly Comm6 Channel) servers and connections via the shipped7 doca_comm_channel_admin binary — listing comch-capable devices and8 decoding the per-device server / connection table (server name, PID,9 in-use / max, PCIe address). The shipped binary is a SINGLE-SHOT10 SCAN-AND-PRINT tool with no registered arguments — NO list / inspect /11 drain / restart subcommands; one inventory pass over every12 comch-capable doca_dev on this side. Channel reset / drain / restart13 go to doca-comch (program side), doca-setup / doca-hardware-safety14 (driver reload), or BFB / RShim — NOT to this binary. Trigger on15 phrasings like "list comch servers", "which channels are active on16 this BlueField", or "verify admin tool sees same channel as program."17 Refuse and route elsewhere for the comch programming API, library18 install, protocol design, channel reset, or general orientation.19metadata:20 source: https://skillmd.com/skills/nvidia/doca-comm-channel-admin21 author: NVIDIA <doca-feedback@nvidia.com>22 kind: tool23 doca_version: "3.5"24 tags:25 - doca26 - comch27 - tools28compatibility: >29 Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu30 22.04/24.04 or RHEL/SLES) with the Comm Channel tooling subpackage so31 the CLI is present under /opt/mellanox/doca/tools/. Runs from either32 the x86/Arm host or the BlueField Arm side; a live host↔DPU comch33 channel created via the doca-comch library is needed for non-empty34 tables. The validation steps require a live DOCA install.35---3637# DOCA Comm Channel Admin Tool3839## Examples4041- **"Which comch servers and connections are currently visible?"** —42 this is in scope. Stay on the admin CLI; do not open a new43 comch channel from this skill.44- **"The program reports CONNECTED but the admin tool lists zero45 channels."** — cross-check representor binding before rewriting46 the comch app.4748## Instructions4950Follow Loading order below. Open the tasks companion for run /51debug. Open the capabilities companion for table columns and52error layers. Do not open every companion file.5354> **Actual binary contract.** `doca_comm_channel_admin` is one55> zero-application-argument, read-only scan-and-print operation.56> It scans every comch-capable `doca_dev` on the current side via57> `resourcedump` (MFT) and prints SERVERS and CONNECTIONS tables.58> It has no list, inspect, device-scope, drain, restart, or other59> application operation. This skill does not retain conceptual60> workflows under invented command names.6162**Where to start:** This is a tool skill for invoking the DOCA Comm63Channel Admin Tool — the **read-only inventory** CLI counterpart64to the `doca-comch/SKILL.md` library. The65shipped `doca_comm_channel_admin` binary takes **no arguments66beyond ARGP defaults** (`--help`, `--version`, `--log-level`,67`--sdk-log-level`, `--json`) and performs **one inventory pass**68per invocation: it walks every `doca_dev` on this side, filters69to comch-capable devices, shells out to `resourcedump` (MFT) on70each, and prints two ASCII tables (SERVERS and CONNECTIONS).71There is no `list` subcommand, no `inspect` subcommand, no72`drain` flag, and no `restart` flag — those are not part of the73tool's surface. Open the tasks companion and start at74`## run` for the single-shot invocation, or75`## debug` when the user reports the tool sees76a different channel set than the program. Open77the capabilities companion when the question is *what78the printed tables actually mean* and *what is not in this79tool's scope*. If the user has not installed DOCA yet, route to80`doca-setup/SKILL.md` first; if the user81needs MFT (`resourcedump` on `PATH` with the privilege documented82for the installed release), `doca-setup` + `doca-public-knowledge-map`83cover that. If the user is holding pre-2.5 docs that mention84"Comm Channel", route to85`doca-comch/SKILL.md`86for the rename rule. If the user wants to *change* channel87state, route to the program-side88reconnect lifecycle in `doca-comch/SKILL.md`89or to BlueField mode / driver reload in90`doca-setup/SKILL.md` +91`doca-hardware-safety/SKILL.md` — **not**92to this tool.9394## Example questions this skill answers well9596The CLASSES of admin-tool questions this skill is built to answer,97each with one worked example. The class is the load-bearing piece;98the worked example is one instance.99100- **"Which comch servers and connections are currently visible?"** —101 worked example: *"print every server and connection row visible102 on this side"*. Answered by the scan-and-print surface in103 the capabilities companion104 + the single invocation in105 the tasks companion.106- **"What does the tool report for this server or connection?"** —107 locate the matching row in the SERVERS or CONNECTIONS table;108 there is no second per-channel query. Answered by109 the capabilities companion110 + the tasks companion.111- **"How do I know the admin tool's view matches what my Comch112 program sees?"** — worked example: *"the program reports113 CONNECTED but the admin tool lists zero channels"*. Answered by114 the cross-checking pattern in115 the tasks companion and the representor-binding116 layer in117 the capabilities companion.118- **"Is this admin tool on my installed DOCA version, and does it119 match the comch library version?"** — worked example: *"is the120 tool available on DOCA 2.4"*. Answered by the overlay in121 the capabilities companion,122 which redirects to the canonical123 `doca-version/SKILL.md` rules and adds the124 Comm Channel Admin Tool specifics.125- **"The tool prints nothing — is the install broken or is there126 genuinely no channel?"** — worked example: *"`list` returned an127 empty result on a host with a known-good Comch client"*.128 Answered by the empty-output interpretation rules in129 the tasks companion +130 the capabilities companion.131132## Audience133134This skill serves **external operators and AI agents who need to135inventory a host-DPU comch channel from the outside**136— after the `doca-comch/SKILL.md` library137has been used to create the channel from a program. Concretely:138139- A platform operator who runs a Comch-using service on BlueField140 and needs to confirm the channel is healthy before declaring the141 service ready.142- A developer of a Comch consumer who sees `DOCA_ERROR_AGAIN` or a143 silent stall on the program side and wants to read the channel's144 state from outside the program rather than guessing.145- An AI agent capturing the external server/connection rows before146 recommending a program-side code or lifecycle change.147148It is **not** for users debugging the admin tool itself, **not** a149substitute for the live public DOCA Comm Channel Admin Tool guide,150and **not** the right place for users learning the comch API —151that audience belongs in152`doca-comch/SKILL.md`.153154The tool is shipped as a CLI binary under155`/opt/mellanox/doca/tools/`, not a library you link against. The156skill uses the same `kind: tool` three-file shape as the rest of157the bundle so the agent's task-verb contract158(`configure / build / modify / run / test / debug`) is uniform159across libraries, services, and tools.160161## When to load this skill162163Load this skill when the user is — or the agent needs to — invoke164the DOCA Comm Channel Admin Tool on a real host or BlueField Arm165with DOCA installed (or inside the public NGC DOCA container with166the right device passthrough). Concretely:167168- Listing currently active comch channels on a host or DPU.169- Reading the row for one named server or connection from the170 complete zero-argument scan.171- Cross-checking the admin tool's view against the program-side172 connection callback state when the two appear to disagree.173- Capturing a side-effect-free channel snapshot as prerequisite174 evidence for a later debug session that crosses program /175 channel / driver layers.176177Do **not** load this skill for general DOCA orientation, the comch178programming API, library install, or comch protocol design. For179those, route to180`doca-public-knowledge-map/SKILL.md`,181`doca-comch/SKILL.md`, or182`doca-setup/SKILL.md`.183184## What this skill provides185186This is a **thin loader**. Substantive material lives in two187companion files:188189- the capabilities companion — what the Comm Channel Admin Tool reports:190 the two read-only tables, the version-availability overlay191 that redirects to `doca-version/SKILL.md`,192 the layered error taxonomy (tool-not-installed / device-binding193 / channel-discovery / channel-state-stuck / permission /194 version / cross-cutting), the tool's role as an observability195 primitive for `doca-comch/SKILL.md`196 debug sessions, and the read-only safety policy.197- the tasks companion — step-by-step workflows for the in-scope task verbs:198 `configure` (route to install), `build` (route to install),199 `modify` (refuse), `run` (one scan-and-print), `test`200 (cross-check the printed rows), `debug` (the layered201 diagnosis ladder), plus a `Deferred task verbs` block and a202 `Command appendix` that honors the bundle's203 `doca-structured-tools-contract/SKILL.md`204 preamble.205206The skill assumes a host or BlueField where DOCA is already207installed (or the public NGC DOCA container is running with the208right device passthrough) and the operator has whatever privileges209the public DOCA Comm Channel Admin Tool guide requires.210211## What this skill deliberately does not ship212213This skill is **agent guidance**, not a samples or scripts bundle.214To keep the boundary clean, it deliberately does not contain — and215pull requests should not add:216217- **Verbatim flag inventories, subcommand names, or output column218 names.** The public DOCA Comm Channel Admin Tool guide on219 `docs.nvidia.com` and the installed `--help` on the user's220 version are the joint source of truth; copying them here pins221 the skill to one release and silently rots when the tool222 evolves. The skill routes the agent at those sources instead.223- **Pre-baked example output.** Output is install-, version-, and224 channel-state-specific. A captured example will mislead an225 operator on a different platform / state.226- **Wrappers, parsers, or scripts** in any language that consume227 the admin tool's output. The output format is documented; users228 who want to script against it should read the live guide and229 write the parser against their installed version.230- **A `samples/` or `reference/` subtree.** This is a thin loader231 for a documented CLI; substantive material lives on the public232 page and in `--help`.233234## Loading order2352361. Read this skill first to confirm the user's question is in237 scope (the user wants to inventory a comch238 channel from the outside, not learn the comch API).2392. **For what the tool reports, version availability, the layered error surface,240 observability, and safety posture, see241 the capabilities companion.**2423. **For the single invocation and cross-check243 workflow — `configure`, `build`, `modify`, `run`, `test`,244 `debug`, plus the `Command appendix` — see245 the tasks companion.**246247## Related skills248249- `doca-comch/SKILL.md` — the library250 whose channels this tool inventories. Pair them in every251 triage session: the program-side connection callback and the252 admin tool's channel state are the two halves of the same253 picture.254- `doca-public-knowledge-map/SKILL.md`255 — routing to the public DOCA Comm Channel Admin Tool guide and256 the rest of the public DOCA documentation set.257- `doca-version/SKILL.md` — canonical DOCA258 version-handling rules. The `## Version compatibility` section259 in the capabilities companion is a concise overlay260 that redirects here for the body.261- `doca-structured-tools-contract/SKILL.md`262 — the bundle's detect → prefer → fall back → report contract for263 structured helper tools. The Command appendix in264 the tasks companion honors this contract.265- `doca-setup/SKILL.md` — env preparation,266 install verification, representor visibility checks, and the267 *I have no install yet* path with the public NGC DOCA268 container. This skill assumes its preconditions are satisfied.269- `doca-debug/SKILL.md` — the cross-cutting270 debug ladder. The Comm Channel Admin Tool slots in at the271 *runtime* layer as the read-only inventory surface before any272 code change is recommended.