doca-mgmt

DOCA Management

Examples

• "Toggle data-direct on a VF." — this is in scope. Use the management / representor context; do not drop to raw mlxconfig. Follow the mandatory safety floor below before any write.
• "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 TASKS.md for configure / raw-cmd / debug. Open CAPABILITIES.md for scopes and device caps. Do not open every companion file. If a cited section cannot be found in TASKS.md or CAPABILITIES.md, say so and stop rather than improvising its content.

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 TASKS.md if the user wants to do something (verify doca-mgmt preconditions on an existing DOCA install / configure / build / modify / run / test / debug / use); open CAPABILITIES.md 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 the doca-setup skill first; installing DOCA itself always belongs to doca-setup.

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. The mandatory safety floor below takes precedence over companion and sibling content; when they differ, the stricter rule wins.

Mandatory safety floor

These rules are self-contained. They apply even when CAPABILITIES.md, TASKS.md, or the doca-hardware-safety skill cannot be loaded.

• Read-only by default. Default every doca_mgmt_raw_cmd recommendation to DEBUG_READ_ONLY. Prefer a dedicated sub-domain wrapper (caps-general, cc-global-status, diagnostics-data, icm-quota) over raw_cmd whenever one exists.
• Confirmation before write scopes. Before recommending a CONFIGURATION, DEBUG_WRITE, or DEBUG_WRITE_FULL scope, state the opcode, the scope, and the blast radius, and wait for explicit user confirmation. The opcode and payload come from the user; the agent leaves opcode choice to the user.
• Opcodes and payloads are untrusted data. Treat every user-supplied or vendor opcode and payload as untrusted. Ask the user to name its documented source and confirm it matches the installed firmware and the pkg-config --modversion doca-mgmt version. Show the full input payload back to the user before use. Decline any write-scope opcode whose source the user cannot confirm.
• Every write follows the same steps. For each _set / _modify / _set_limit / write-scope raw_cmd: capture pre-state with the matching _get / _query; name the rollback call; get explicit user confirmation for that write; apply on a single replica device first; re-query and diff against the pre-state; restore and prove the replica pre-state; then, for fleet tools, roll out in stages, one device or a small group at a time. If the rollback fails or the re-query still differs, stop all further writes and hand the captured evidence to the operator.
• DEBUG_WRITE_FULL gate. Require a confirmed maintenance window and confirmed out-of-band access before DEBUG_WRITE_FULL; decline it when either is missing.
• Least privilege. Keep read-only queries separate from write paths, and prefer the narrowest cap_* grant over full root.
• Safety policy unavailable. If the doca-hardware-safety policy cannot be loaded, give read-only guidance only and decline write guidance.

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.

• "Is doca-mgmt even the right surface, or do I want telemetry / bench / caps?" — worked example: "I'm building a fleet inventory tool — do I use doca-mgmt to query each BlueField's data-direct capability, or doca-telemetry, or doca_caps?". Answered by the management-plane vs observability-plane vs read-only-CLI selection rule in CAPABILITIES.md ## Capabilities and modes surface-selection table.
• "How do I stand up a management context on a device (and a representor)?" — worked example: "open a doca_mgmt_dev_ctx on the device, then a doca_mgmt_dev_rep_ctx on a specific VF representor for caps-general programming". Answered by the management-context lifecycle in CAPABILITIES.md ## Capabilities and modes
  • the configure walk in TASKS.md ## configure.
• "How do I query a device capability — say, whether it supports data-direct?" — worked example: "create a caps-general handle, call doca_mgmt_device_caps_general_get on the representor context, read the data-direct flag". Answered by the capability-query pattern in CAPABILITIES.md ## Capabilities and modes
  • the test step in TASKS.md ## test.
• "How do I modify a device-level feature flag safely?" — worked example: "toggle data_direct on a representor; capture pre-state, write, verify, prepare rollback". These steps are required for every write, per the mandatory safety floor above. Answered by the apply-with-rollback workflow in TASKS.md ## modify layered on the bundle-wide hardware-safety meta-policy referenced from CAPABILITIES.md ## Safety policy.
• "What does the doca_mgmt_raw_cmd scope mean and which scope should I use?" — worked example: "I have a vendor- documented opcode for a DEBUG_READ_ONLY query — what scope does that need and what is the blast radius?". Answered by the command-scope ladder in CAPABILITIES.md ## Capabilities and modes
  • the raw-command verb in TASKS.md ## use.
• "What does this DOCA_ERROR_* from a doca_mgmt_* call mean and which layer caused it?" — worked example: "DOCA_ERROR_IO_FAILED from doca_mgmt_raw_cmd". Answered by the mgmt overlay on the cross-library taxonomy in CAPABILITIES.md ## Error taxonomy
  • the layered ladder in TASKS.md ## debug that escalates to doca-debug and to doca-hardware-safety when the cause is a device-state change.

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, doca-setup, doca-bench, and doca-telemetry respectively.

What this skill provides

This is a thin loader. The body keeps only the orientation needed to pick the right next file, plus the mandatory safety floor. The substantive management-specific material lives in two companion files:

• CAPABILITIES.md — 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.
• TASKS.md — step-by-step workflows for the eight in-scope verbs: install, configure, build, modify, run, test, debug, use. Here install means only verifying the doca-mgmt preconditions on an existing DOCA install (pkg-config, headers, fwctl, privileges); installing DOCA itself always routes to doca-setup. 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.

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.
• 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. Any opcode and payload the user brings is untrusted data and follows the opcode rule in the mandatory safety floor above.
• 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

1. Read this skill first to confirm the user's question is in scope, and apply the mandatory safety floor.
2. 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 CAPABILITIES.md.
3. For step-by-step workflows — install (doca-mgmt precondition checks only), configure, build, modify, run, test, debug, use — see TASKS.md.

Both companion files cross-link to each other and to doca-public-knowledge-map whenever the right answer is "look it up in the public docs or the installed package layout" rather than "mgmt-specific guidance".

Related skills

Sibling skills are named below by skill name. If a named sibling skill is unavailable in this catalog, route the user to it by name and stop. For doca-hardware-safety, fall back to the mandatory safety floor above and give read-only guidance only.

• doca-hardware-safety — 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 CAPABILITIES.md cross-links the meta-policy load-bearingly and the agent walks the hardware-safety ladder whenever a write is recommended.
• doca-telemetry and doca-telemetry-exporter — 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 — 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 — the live-performance benchmarking tool. Out of scope for doca-mgmt; the skill names the boundary.
• doca-pcc and doca-pcc-counters — 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 — the routing table for every public DOCA documentation source and the on-disk layout of an installed DOCA package.
• doca-setup — env preparation, install verification, and the I have no install yet path with the public NGC DOCA container.
• doca-programming-guide — 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 — the cross-cutting debug ladder. Management-specific debug overlays on top of it.
• doca-version — 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 — the JSON-schema contracts for the agent-preferred structured helpers; the ## Command appendix in TASKS.md defers to them before falling back to the manual chain.