/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:
  kind: library
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.

DOCA Management

**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`](TASKS.md) if the user wants to *do* something (install / configure / build / modify / run / test / debug / use); open [`CAPABILITIES.md`](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 [`doca-setup`](../../doca-setup/SKILL.md) first.

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`](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`](CAPABILITIES.md#capabilities-and-modes)

• the configure walk in

[`TASKS.md ## configure`](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`](CAPABILITIES.md#capabilities-and-modes)

• the test step in [`TASKS.md ## test`](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"*. Answered by the apply-with-rollback workflow in [`TASKS.md ## modify`](TASKS.md#modify) layered on the bundle-wide hardware-safety meta-policy referenced from [`CAPABILITIES.md ## Safety policy`](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`](CAPABILITIES.md#capabilities-and-modes)

• the raw-command verb in [`TASKS.md ## use`](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`](CAPABILITIES.md#error-taxonomy)

• the layered ladder in

[`TASKS.md ## debug`](TASKS.md#debug) that escalates to [`doca-debug`](../../doca-debug/SKILL.md) and to [`doca-hardware-safety`](../../doca-hardware-safety/SKILL.md) when the cause is a device-state change.

Audience

This skill serves **external developers building fleet-management, orchestration, or device-administration tools that programmatically query and modify BlueField / ConnectX device-level state** — i.e., users whose code calls `doca_mgmt_*` (directly in C/C++, or through FFI/bindings from another language) to inspect device capabilities, toggle device feature flags, query diagnostics counters, set ICM quotas, or issue raw firmware-control commands. The canonical caller is a fleet-management agent that walks every BlueField in a data center and applies a desired-state diff. This skill is *not* fo