/doca-mgmt

license: Apache-2.0
name: doca-mgmt
description: >
  Use this skill when the user is doing hands-on DOCA Management
  programming against BlueField / ConnectX devices — standing up a
  management or representor context (doca_mgmt_dev_ctx /
  doca_mgmt_dev_rep_ctx), querying device caps (data-direct,
  caps-general), toggling congestion-control global status, modifying
  diagnostics-data, setting ICM quotas, or issuing a raw firmware
  command via doca_mgmt_raw_cmd with the right scope (CONFIGURATION /
  DEBUG_READ_ONLY / DEBUG_WRITE / DEBUG_WRITE_FULL). Trigger even when
  the user does not say "DOCA Management" — typical implicit phrasings
  include "fleet tool that walks every BlueField and reads device
  state", "toggle data-direct on a VF", "set an ICM quota per
  representor", "send a raw firmware command from C",
  "DOCA_ERROR_IO_FAILED from raw_cmd", or "fwctl ioctl is failing".
  Refuse and route elsewhere for mlxconfig direct operation, BFB /
  firmware reflash, streaming telemetry, doca_caps CLI snapshots, or
  DOCA install itself — those belong to other skills.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - mgmt
    - firmware
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC
  attached. Reads the user's local install via `pkg-config doca-mgmt` +
  `doca-common` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}; runtime
  operations require root (or device-admin cap_*) and an /dev/fwctl*
  character device exposed by the host kernel. The validation steps
  require a live DOCA install.

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.

• **"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 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 and modes

• the configure walk in

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 and modes

• the test step in ## 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"*. Answered by the apply-with-rollback workflow in

modify layered on the

bundle-wide hardware-safety meta-policy referenced from

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 and modes

• the raw-command verb in ## 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 ## Error taxonomy

• the layered ladder in

##