DOCA Comm Channel Admin Tool

CRITICAL — how to read the body of this skill (drain / restart / inspect / state-changing-operation framing). The shipped doca_comm_channel_admin binary is a SINGLE-SHOT, READ-ONLY, SCAN-AND-PRINT tool. It registers ZERO application-level arguments in register_comm_channel_admin_params() (only ARGP defaults are registered), it shells out to resourcedump (MFT) per device, and it prints two ASCII tables. There is NO drain subcommand, NO restart subcommand, NO inspect <channel-id> subcommand, NO state-changing operation, and NO list-first → inspect-one → drain-or-restart workflow exposed BY THIS BINARY. Wherever the sections below (## Example questions, CAPABILITIES.md, TASKS.md) say "drain a channel", "restart it", "per-channel inspect step", "state-changing operation gate", or "smoke-before-bulk", read those as conceptual operator actions the operator performs via OTHER paths AFTER reading this tool's tables — not as subcommands the admin binary itself ships. Concretely: the operator drains/resets/reconnects by going to the program side through doca-comch (the comch library's doca_ctx_stop() → reset → doca_ctx_start() reconnect lifecycle), or by reloading the BlueField driver / mode via doca-setup + doca-hardware-safety, or by RShim / BFB reset for the deepest cases — NEVER by re-invoking the admin binary with a flag, because no such flag exists. The body below uses the legacy drain/restart/inspect/state-changing names because they describe the operator's mental model; this banner is the authoritative mapping from that model onto the actual binary surface.

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 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 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 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 first; if the user needs MFT (mst start + resourcedump on PATH and root/sudo privileges to invoke it), 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 for the rename rule. If the user wants to change channel state (reset / drain / restart), route to the program-side reconnect lifecycle in doca-comch or to BlueField mode / driver reload in doca-setup + doca-hardware-safety — 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 channels are currently active on this BlueField?" — worked example: "enumerate every comch channel the DPU server is presently accepting from host clients". Answered by the channel enumeration in CAPABILITIES.md ## Capabilities and modes
  • the list-first invocation in TASKS.md ## run.
• "What state is this channel in?" — worked example: "a host client reports its send-task is hanging; is the channel HEALTHY, draining, or stuck". Answered by the channel-state inspection surface in CAPABILITIES.md ## Capabilities and modes
  • the per-channel inspect step in TASKS.md ## run.
• "A channel is stuck — should I drain it or restart it?" — worked example: "a producer / consumer fast-path has no completions for 30 seconds and the consumer process is still alive". Answered by the drain-vs-restart decision rule in TASKS.md ## debug + CAPABILITIES.md ## Safety policy state-changing-operation gate.
• "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 and the representor-binding layer in 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, which redirects to the canonical doca-version 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 + CAPABILITIES.md ## Error taxonomy.

Audience

This skill serves external operators and AI agents who need to inspect or intervene on a host-DPU comch channel from the outside — after the doca-comch 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 driving an operational triage step "is the comch channel stuck" before recommending a code change or a process restart.

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.

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.
• Inspecting the state of one named channel before deciding whether to leave it alone, drain it, or restart it.
• Walking the drain-vs-restart decision for a stuck channel reported by a Comch-using application.
• 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, doca-comch, or doca-setup.

What this skill provides

This is a thin loader. Substantive material lives in two companion files:

• CAPABILITIES.md — what the Comm Channel Admin Tool reports and changes: the documented channel-state surface, the read-only vs state-changing operation split, the version-availability overlay that redirects to doca-version, 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 debug sessions, and the safety policy that makes drain and restart high-stakes operations gated on a clean inspection first.
• TASKS.md — step-by-step workflows for the in-scope task verbs: configure (route to install), build (route to install), modify (refuse), run (list-then-inspect), test (smoke-before-bulk capability check), debug (the layered diagnosis ladder), plus a Deferred task verbs block and a Command appendix that honors the bundle's doca-structured-tools-contract 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

1. Read this SKILL.md first to confirm the user's question is in scope (the user wants to inspect or intervene on a comch channel from the outside, not learn the comch API).
2. For what the tool reports, the read-only vs state-changing split, version availability, the layered error surface, observability, and safety posture, see CAPABILITIES.md.
3. For the documented invocations and the smoke-before-bulk workflow — configure, build, modify, run, test, debug, plus the Command appendix — see TASKS.md.

Related skills

• doca-comch — the library whose channels this tool inspects. 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 — routing to the public DOCA Comm Channel Admin Tool guide and the rest of the public DOCA documentation set.
• doca-version — canonical DOCA version-handling rules. The ## Version compatibility section in CAPABILITIES.md is a concise overlay that redirects here for the body.
• doca-structured-tools-contract — the bundle's detect → prefer → fall back → report contract for structured helper tools. The Command appendix in TASKS.md honors this contract.
• doca-setup — 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 — the cross-cutting debug ladder. The Comm Channel Admin Tool slots in at the runtime layer as the read-only inspection surface before any code change is recommended.