doca-mgmt

# 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* for NVIDIA developers contributing to DOCA
Management itself, and it is not the right surface for live
performance benchmarking or stream-based observability — those
belong to [`doca-bench`](../../tools/doca-bench/SKILL.md),
[`doca-telemetry`](../doca-telemetry/SKILL.md), and
[`doca-telemetry-exporter`](../doca-telemetry-exporter/SKILL.md).

## Language scope

DOCA Management ships as a C library with the `pkg-config` module
name `doca-mgmt`. The library's surface is C; the shipped samples
on a real install (where present) are C. C and C++ consumers are
the canonical case and the workflows in `TASKS.md` assume that
path. Other-language consumers (Rust, Go, Python, …) consume the
same `*.so` library through FFI or language-specific bindings;
the skill's contribution in that case is to keep the management-
context lifecycle, the command-scope ladder, the capability-query
pattern, the version-handling rule, and the safety overlay
language-neutral, and to route the agent to the public C ABI as
the authoritative surface that any wrapper will eventually call.
The skill does not author wrappers in any language.

## 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 mod