DOCA Management
Examples
- "Toggle data-direct on a VF." — this is in scope. Use the
management / representor context; do not drop to raw mlxconfig.
- "DOCA_ERROR_IO_FAILED from raw_cmd." — the firmware rejected
the command: re-check the four-way version match, the opcode, and the
narrowest correct scope (CONFIGURATION, DEBUG_READ_ONLY, DEBUG_WRITE,
DEBUG_WRITE_FULL). fwctl or permission failures surface as
DOCA_ERROR_OPERATING_SYSTEM instead.
Instructions
Follow Loading order below. Open the tasks companion for configure /
raw-cmd / debug. Open the capabilities companion for scopes and
device caps. Do not open every companion file.
Where to start: This skill assumes DOCA is already installed
and the user is doing hands-on management-plane work against
a BlueField / ConnectX device — typically a fleet-management or
orchestration tool that needs to query or modify device-level
state programmatically. Open the tasks companion if the user
wants to do something (install / configure / build / modify /
run / test / debug / use); open the capabilities companion
when the question is what can doca-mgmt express on this version —
the management context model, the raw-command scope ladder, the
sub-domain surfaces (caps-general, cc-global-status, diagnostics-
data, icm-quota), version compatibility, and the safety overlay.
If the user has not installed DOCA yet, route to
doca-setup/SKILL.md first.
How to use this skill. Read this file, then search the companion file
for the ## <name> heading the question needs and read that whole section.
Answer completely from it, quoting only its symbols and commands. Do not
browse docs; use the entry points in doca-public-knowledge-map. Give
environment checks as commands for the user's DOCA host. Any change to
device state also follows doca-hardware-safety: say so and cite it. For
out-of-scope requests, name the skill that owns them and stop.
Example questions this skill answers well
The CLASSES of management-plane questions this skill is built to
answer, each with one worked example. The agent should treat the
class as the load-bearing piece — the worked example is a
single instance.
When to load this skill
Load this skill when the user is doing hands-on DOCA Management
work on a host with one or more BlueField / ConnectX devices.
Concretely:
- Standing up a
doca_mgmt_dev_ctx on a doca_dev to inspect
or modify device-level state.
- Standing up a
doca_mgmt_dev_rep_ctx on a doca_dev_rep (or
via doca_mgmt_dev_rep_ctx_create_by_pci_addr when the
representor is not available) to inspect or modify a VF /
function-level configuration.
- Querying a device's general capabilities via
doca_mgmt_device_caps_general_* (data-direct support and
similar device-wide attributes).
- Programming a representor's general capabilities via the same
set path.
- Querying or modifying congestion-control global status via
doca_mgmt_cc_global_status_* (RP / NP protocol type,
priority, enable / disable).
- Modifying or querying multi-domain diagnostics data via
doca_mgmt_diagnostics_data_* against a specific device.
- Setting ICM quota limits per device or per representor via
doca_mgmt_icm_quota_* and reading the current allocation /
max-reached.
- Issuing a
doca_mgmt_raw_cmd against the device's
firmware-control endpoint, choosing the right
enum doca_mgmt_cmd_scope for the operation's blast radius.
- Debugging a
DOCA_ERROR_* returned by a doca_mgmt_* call
and deciding whether the cause is a configuration mistake, a
lifecycle ordering bug, a missing capability on the device,
an fwctl ioctl failure, or a firmware-side rejection.
Do not load this skill for general DOCA orientation, install
of DOCA itself, live performance benchmarking, or stream-based
telemetry. For those, use
doca-public-knowledge-map/SKILL.md,
doca-setup/SKILL.md,
doca-bench/SKILL.md, and
doca-telemetry/SKILL.md respectively.
What this skill provides
This is a thin loader. The body keeps only the orientation
needed to pick the right next file. The substantive
management-specific material lives in two companion files:
- the capabilities companion — what doca-mgmt can express on this
version: the management-context object model
(
doca_mgmt_dev_ctx + doca_mgmt_dev_rep_ctx), the raw-
command scope ladder (DOCA_MGMT_CMD_SCOPE_CONFIGURATION,
DOCA_MGMT_CMD_SCOPE_DEBUG_READ_ONLY,
DOCA_MGMT_CMD_SCOPE_DEBUG_WRITE,
DOCA_MGMT_CMD_SCOPE_DEBUG_WRITE_FULL), the sub-domain
surfaces (caps-general, cc-global-status, diagnostics-data,
icm-quota) with their capability-query gates, the EXPERIMENTAL
symbol-set policy (every public doca_mgmt_* symbol is
tagged EXPERIMENTAL), the mgmt overlay on the cross-library
DOCA_ERROR_* taxonomy, the observability surface (pre-state
capture + post-write re-query), and the per-artifact safety
overlay on the bundle-wide hardware-safety meta-policy.
- the tasks companion — step-by-step workflows for the eight in-scope
verbs:
install, configure, build, modify, run,
test, debug, use. Plus a Deferred task verbs block
that points out-of-scope questions at the right next skill.
The skill assumes a host or BlueField where DOCA is already
installed at the standard location and the user has the
privileges their public install profile expects (management-
plane operations typically require root or an equivalent
device-administration capability). It does not cover installing
DOCA — that path goes through
doca-setup/SKILL.md.
What this skill deliberately does not ship
This skill is agent guidance, not a samples or templates
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:
- Pre-written DOCA Management application source code, in any
language. Management-plane code touches device state and a
wrong write can take the device offline; authoring it from
documentation prose, especially against an EXPERIMENTAL
symbol set whose shape can change between releases, is
forbidden by this skill. The agent's job is to route the user
to verified reference code (the shipped DOCA samples on the
installed package set are the canonical worked examples) and
to prescribe a minimum-diff modification via the universal
modify-a-sample workflow in
doca-programming-guide/SKILL.md.
- Standalone build manifests parked inside the skill. The
agent constructs the build manifest in the user's project
directory against the user's installed DOCA, where
pkg-config --modversion doca-mgmt is the source of truth.
- Raw-command opcode catalogs. The
doca_mgmt_raw_cmd
in-payload and out-payload are device / firmware specific;
the skill names the scope of a command class and the
discipline the agent applies (pre-state capture, scope
ladder, rollback path) but it does NOT enumerate opcodes —
those are vendor / device documentation and looked up via
doca-public-knowledge-map/SKILL.md.
- A
samples/, bindings/, or reference/ subtree of any
kind. A mock or incomplete artifact in this skill's tree,
even one labeled "reference", is misleading: users will read
it as buildable.
Loading order
- Read this skill first to confirm the user's question is
in scope.
- For the management-context object model, the raw-command
scope ladder, the sub-domain surfaces, version
compatibility, the error taxonomy, observability, and the
per-artifact safety overlay, see
the capabilities companion.
- For step-by-step workflows — install, configure, build,
modify, run, test, debug, use — see the tasks companion.
Both companion files cross-link to each other and to
doca-public-knowledge-map/SKILL.md
whenever the right answer is "look it up in the public docs or
the installed package layout" rather than "mgmt-specific
guidance".
Related skills
doca-hardware-safety/SKILL.md —
the bundle-wide hardware-safety meta-policy. Because
doca-mgmt is the surface through which agents most commonly
modify device state programmatically, the safety overlay
in the capabilities companion cross-links the meta-policy
load-bearingly and the agent walks the hardware-safety
ladder whenever a write is recommended.
doca-telemetry/SKILL.md and
doca-telemetry-exporter/SKILL.md —
the observability surfaces for streaming telemetry from the
device. Use those when the user wants live metrics; use
doca-mgmt when the user wants point-in-time programmatic
query or modification.
doca-caps/SKILL.md — the
read-only CLI for inspecting device capabilities. Use the
tool when the user wants an interactive snapshot; use
doca-mgmt when the user wants the same information through
the C API in a fleet tool.
doca-bench/SKILL.md — the
live-performance benchmarking tool. Out of scope for
doca-mgmt; the skill names the boundary.
doca-pcc/SKILL.md and
doca-pcc-counters/SKILL.md —
programmable congestion control. doca-mgmt's
doca_mgmt_cc_global_status_* surface is the global
enable/disable + protocol selection control plane that
layers on the deeper programmable-CC surface owned by
doca-pcc.
doca-public-knowledge-map/SKILL.md — the
routing table for every public DOCA documentation source and
the on-disk layout of an installed DOCA package.
doca-setup/SKILL.md — env preparation,
install verification, and the I have no install yet path
with the public NGC DOCA container.
doca-programming-guide/SKILL.md —
general DOCA programming patterns shared by every library:
the canonical pkg-config + meson build pattern, the
universal modify-a-shipped-sample first-app workflow, the
cross-library DOCA_ERROR_* taxonomy. This skill layers
management-plane specifics on top.
doca-debug/SKILL.md — the cross-cutting
debug ladder. Management-specific debug overlays on top of
it.
doca-version/SKILL.md — the version
detection / four-way match rule every per-artifact ## Version compatibility anchor builds on. This skill quotes
the management-specific overlay only.
doca-structured-tools-contract/SKILL.md —
the JSON-schema contracts for the agent-preferred structured
helpers; the ## Command appendix in the tasks companion defers to
them before falling back to the manual chain.
1---2license: Apache-2.03name: doca-mgmt4description: >5 Use this skill when the user is doing hands-on DOCA Management6 programming against BlueField / ConnectX devices — standing up a7 management or representor context (doca_mgmt_dev_ctx /8 doca_mgmt_dev_rep_ctx), querying device caps (data-direct,9 caps-general), toggling congestion-control global status, modifying10 diagnostics-data, setting ICM quotas, or issuing a raw firmware11 command via doca_mgmt_raw_cmd with the right scope (CONFIGURATION /12 DEBUG_READ_ONLY / DEBUG_WRITE / DEBUG_WRITE_FULL). Trigger even when13 the user does not say "DOCA Management" — typical implicit phrasings14 include "fleet tool that walks every BlueField and reads device15 state", "toggle data-direct on a VF", "set an ICM quota per16 representor", "send a raw firmware command from C",17 "DOCA_ERROR_IO_FAILED from raw_cmd", or "fwctl ioctl is failing".18 Refuse and route elsewhere for mlxconfig direct operation, BFB /19 firmware reflash, streaming telemetry, doca_caps CLI snapshots, or20 DOCA install itself — those belong to other skills.21metadata:22 source: https://skillmd.com/skills/nvidia/doca-mgmt23 author: NVIDIA <doca-feedback@nvidia.com>24 kind: library25 doca_version: "3.5"26 tags:27 - doca28 - mgmt29 - firmware30compatibility: >31 Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu32 22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC33 attached. Reads the user's local install via `pkg-config doca-mgmt` +34 `doca-common` and inspects35 /opt/mellanox/doca/{lib,include,samples,applications}; runtime36 operations require root (or device-admin cap_*) and an /dev/fwctl*37 character device exposed by the host kernel. The validation steps38 require a live DOCA install.39---4041# DOCA Management4243## Examples4445- **"Toggle data-direct on a VF."** — this is in scope. Use the46 management / representor context; do not drop to raw mlxconfig.47- **"DOCA_ERROR_IO_FAILED from raw_cmd."** — the firmware rejected48 the command: re-check the four-way version match, the opcode, and the49 narrowest correct scope (CONFIGURATION, DEBUG_READ_ONLY, DEBUG_WRITE,50 DEBUG_WRITE_FULL). fwctl or permission failures surface as51 `DOCA_ERROR_OPERATING_SYSTEM` instead.5253## Instructions5455Follow Loading order below. Open the tasks companion for configure /56raw-cmd / debug. Open the capabilities companion for scopes and57device caps. Do not open every companion file.5859**Where to start:** This skill assumes DOCA is already installed60and the user is doing **hands-on management-plane work** against61a BlueField / ConnectX device — typically a fleet-management or62orchestration tool that needs to query or modify device-level63state programmatically. Open the tasks companion if the user64wants to *do* something (install / configure / build / modify /65run / test / debug / use); open the capabilities companion66when the question is *what can doca-mgmt express on this version* —67the management context model, the raw-command scope ladder, the68sub-domain surfaces (caps-general, cc-global-status, diagnostics-69data, icm-quota), version compatibility, and the safety overlay.70If the user has not installed DOCA yet, route to71`doca-setup/SKILL.md` first.7273**How to use this skill.** Read this file, then search the companion file74for the `## <name>` heading the question needs and read that whole section.75Answer completely from it, quoting only its symbols and commands. Do not76browse docs; use the entry points in `doca-public-knowledge-map`. Give77environment checks as commands for the user's DOCA host. Any change to78device state also follows `doca-hardware-safety`: say so and cite it. For79out-of-scope requests, name the skill that owns them and stop.8081## Example questions this skill answers well8283The CLASSES of management-plane questions this skill is built to84answer, each with one worked example. The agent should treat the85*class* as the load-bearing piece — the worked example is a86single instance.8788- **"Is `doca-mgmt` even the right surface, or do I want89 telemetry / bench / caps?"** — worked example: *"I'm building a90 fleet inventory tool — do I use doca-mgmt to query each91 BlueField's data-direct capability, or doca-telemetry, or92 doca_caps?"*. Answered by the *management-plane vs93 observability-plane vs read-only-CLI* selection rule in94 ## Capabilities and modes95 surface-selection table.96- **"How do I stand up a management context on a device (and a97 representor)?"** — worked example: *"open a `doca_mgmt_dev_ctx`98 on the device, then a `doca_mgmt_dev_rep_ctx` on a specific99 VF representor for caps-general programming"*. Answered by100 the management-context lifecycle in101 ## Capabilities and modes102 + the configure walk in103 ## configure.104- **"How do I query a device capability — say, whether it105 supports data-direct?"** — worked example: *"create a106 caps-general handle, call `doca_mgmt_device_caps_general_get`107 on the representor context, read the data-direct flag"*.108 Answered by the capability-query pattern in109 ## Capabilities and modes110 + the test step in ## test.111- **"How do I modify a device-level feature flag safely?"** —112 worked example: *"toggle `data_direct` on a representor;113 capture pre-state, write, verify, prepare rollback"*.114 Answered by the apply-with-rollback workflow in115 ## modify layered on the116 bundle-wide hardware-safety meta-policy referenced from117 ## Safety policy.118- **"What does the `doca_mgmt_raw_cmd` scope mean and which119 scope should I use?"** — worked example: *"I have a vendor-120 documented opcode for a `DEBUG_READ_ONLY` query — what scope121 does that need and what is the blast radius?"*. Answered by122 the command-scope ladder in123 ## Capabilities and modes124 + the raw-command verb in ## use.125- **"What does this `DOCA_ERROR_*` from a `doca_mgmt_*` call126 mean and which layer caused it?"** — worked example:127 *"`DOCA_ERROR_IO_FAILED` from `doca_mgmt_raw_cmd`"*.128 Answered by the mgmt overlay on the cross-library taxonomy129 in ## Error taxonomy130 + the layered ladder in131 ## debug that escalates to132 `doca-debug/SKILL.md` and to133 `doca-hardware-safety/SKILL.md`134 when the cause is a device-state change.135136## When to load this skill137138Load this skill when the user is doing **hands-on DOCA Management139work** on a host with one or more BlueField / ConnectX devices.140Concretely:141142- Standing up a `doca_mgmt_dev_ctx` on a `doca_dev` to inspect143 or modify device-level state.144- Standing up a `doca_mgmt_dev_rep_ctx` on a `doca_dev_rep` (or145 via `doca_mgmt_dev_rep_ctx_create_by_pci_addr` when the146 representor is not available) to inspect or modify a VF /147 function-level configuration.148- Querying a device's general capabilities via149 `doca_mgmt_device_caps_general_*` (data-direct support and150 similar device-wide attributes).151- Programming a representor's general capabilities via the same152 `set` path.153- Querying or modifying congestion-control global status via154 `doca_mgmt_cc_global_status_*` (RP / NP protocol type,155 priority, enable / disable).156- Modifying or querying multi-domain diagnostics data via157 `doca_mgmt_diagnostics_data_*` against a specific device.158- Setting ICM quota limits per device or per representor via159 `doca_mgmt_icm_quota_*` and reading the current allocation /160 max-reached.161- Issuing a `doca_mgmt_raw_cmd` against the device's162 firmware-control endpoint, choosing the right163 `enum doca_mgmt_cmd_scope` for the operation's blast radius.164- Debugging a `DOCA_ERROR_*` returned by a `doca_mgmt_*` call165 and deciding whether the cause is a configuration mistake, a166 lifecycle ordering bug, a missing capability on the device,167 an `fwctl` ioctl failure, or a firmware-side rejection.168169Do **not** load this skill for general DOCA orientation, install170of DOCA itself, live performance benchmarking, or stream-based171telemetry. For those, use172`doca-public-knowledge-map/SKILL.md`,173`doca-setup/SKILL.md`,174`doca-bench/SKILL.md`, and175`doca-telemetry/SKILL.md` respectively.176177## What this skill provides178179This is a **thin loader**. The body keeps only the orientation180needed to pick the right next file. The substantive181management-specific material lives in two companion files:182183- the capabilities companion — what doca-mgmt can express on this184 version: the management-context object model185 (`doca_mgmt_dev_ctx` + `doca_mgmt_dev_rep_ctx`), the raw-186 command scope ladder (`DOCA_MGMT_CMD_SCOPE_CONFIGURATION`,187 `DOCA_MGMT_CMD_SCOPE_DEBUG_READ_ONLY`,188 `DOCA_MGMT_CMD_SCOPE_DEBUG_WRITE`,189 `DOCA_MGMT_CMD_SCOPE_DEBUG_WRITE_FULL`), the sub-domain190 surfaces (caps-general, cc-global-status, diagnostics-data,191 icm-quota) with their capability-query gates, the EXPERIMENTAL192 symbol-set policy (every public `doca_mgmt_*` symbol is193 tagged EXPERIMENTAL), the mgmt overlay on the cross-library194 `DOCA_ERROR_*` taxonomy, the observability surface (pre-state195 capture + post-write re-query), and the per-artifact safety196 overlay on the bundle-wide hardware-safety meta-policy.197- the tasks companion — step-by-step workflows for the eight in-scope198 verbs: `install`, `configure`, `build`, `modify`, `run`,199 `test`, `debug`, `use`. Plus a `Deferred task verbs` block200 that points out-of-scope questions at the right next skill.201202The skill assumes a host or BlueField where DOCA is already203installed at the standard location and the user has the204privileges their public install profile expects (management-205plane operations typically require root or an equivalent206device-administration capability). It does not cover installing207DOCA — that path goes through208`doca-setup/SKILL.md`.209210## What this skill deliberately does not ship211212This skill is **agent guidance**, not a samples or templates213bundle. To keep the boundary clean, it deliberately does not214contain — and pull requests should not add:215216- **Pre-written DOCA Management application source code, in any217 language.** Management-plane code touches device state and a218 wrong write can take the device offline; authoring it from219 documentation prose, especially against an EXPERIMENTAL220 symbol set whose shape can change between releases, is221 forbidden by this skill. The agent's job is to route the user222 to verified reference code (the shipped DOCA samples on the223 installed package set are the canonical worked examples) and224 to prescribe a minimum-diff modification via the universal225 modify-a-sample workflow in226 `doca-programming-guide/SKILL.md`.227- **Standalone build manifests** parked inside the skill. The228 agent constructs the build manifest *in the user's project229 directory* against the user's installed DOCA, where230 `pkg-config --modversion doca-mgmt` is the source of truth.231- **Raw-command opcode catalogs.** The `doca_mgmt_raw_cmd`232 in-payload and out-payload are device / firmware specific;233 the skill names the *scope* of a command class and the234 *discipline* the agent applies (pre-state capture, scope235 ladder, rollback path) but it does NOT enumerate opcodes —236 those are vendor / device documentation and looked up via237 `doca-public-knowledge-map/SKILL.md`.238- **A `samples/`, `bindings/`, or `reference/` subtree** of any239 kind. A mock or incomplete artifact in this skill's tree,240 even one labeled "reference", is misleading: users will read241 it as buildable.242243## Loading order2442451. Read this skill first to confirm the user's question is246 in scope.2472. **For the management-context object model, the raw-command248 scope ladder, the sub-domain surfaces, version249 compatibility, the error taxonomy, observability, and the250 per-artifact safety overlay, see251 the capabilities companion.**2523. **For step-by-step workflows — install, configure, build,253 modify, run, test, debug, use — see the tasks companion.**254255Both companion files cross-link to each other and to256`doca-public-knowledge-map/SKILL.md`257whenever the right answer is "look it up in the public docs or258the installed package layout" rather than "mgmt-specific259guidance".260261## Related skills262263- `doca-hardware-safety/SKILL.md` —264 the bundle-wide hardware-safety meta-policy. Because265 doca-mgmt is the surface through which agents most commonly266 *modify* device state programmatically, the safety overlay267 in the capabilities companion cross-links the meta-policy268 load-bearingly and the agent walks the hardware-safety269 ladder whenever a write is recommended.270- `doca-telemetry/SKILL.md` and271 `doca-telemetry-exporter/SKILL.md` —272 the observability surfaces for *streaming* telemetry from the273 device. Use those when the user wants live metrics; use274 doca-mgmt when the user wants point-in-time programmatic275 query or modification.276- `doca-caps/SKILL.md` — the277 read-only CLI for inspecting device capabilities. Use the278 tool when the user wants an interactive snapshot; use279 doca-mgmt when the user wants the same information through280 the C API in a fleet tool.281- `doca-bench/SKILL.md` — the282 live-performance benchmarking tool. Out of scope for283 doca-mgmt; the skill names the boundary.284- `doca-pcc/SKILL.md` and285 `doca-pcc-counters/SKILL.md` —286 programmable congestion control. doca-mgmt's287 `doca_mgmt_cc_global_status_*` surface is the *global288 enable/disable + protocol selection* control plane that289 layers on the deeper programmable-CC surface owned by290 doca-pcc.291- `doca-public-knowledge-map/SKILL.md` — the292 routing table for every public DOCA documentation source and293 the on-disk layout of an installed DOCA package.294- `doca-setup/SKILL.md` — env preparation,295 install verification, and the *I have no install yet* path296 with the public NGC DOCA container.297- `doca-programming-guide/SKILL.md` —298 general DOCA programming patterns shared by every library:299 the canonical `pkg-config` + meson build pattern, the300 universal modify-a-shipped-sample first-app workflow, the301 cross-library `DOCA_ERROR_*` taxonomy. This skill layers302 management-plane specifics on top.303- `doca-debug/SKILL.md` — the cross-cutting304 debug ladder. Management-specific debug overlays on top of305 it.306- `doca-version/SKILL.md` — the version307 detection / four-way match rule every per-artifact `##308 Version compatibility` anchor builds on. This skill quotes309 the management-specific overlay only.310- `doca-structured-tools-contract/SKILL.md` —311 the JSON-schema contracts for the agent-preferred structured312 helpers; the `## Command appendix` in the tasks companion defers to313 them before falling back to the manual chain.314