Doca Mgmt

DOCA Management capabilities, version compatibility, errors, observability, safety

Where to start: The pattern overview below names the recurring management-class patterns. Pick the pattern first, then drill into the H2 that owns the substance. For the how of executing each pattern, jump to TASKS.md.

Read this file when the loader sent you here from SKILL.md. For step-by-step workflows that use these capabilities (install, configure, build, modify, run, test, debug, use) see TASKS.md. For where the underlying public documentation and installed package paths live, defer to doca-public-knowledge-map/SKILL.md — do not duplicate URLs or install paths in this file.

Pattern overview

Every management-class question this skill teaches resolves into one of SIX patterns. The patterns are CLASSES — they apply across every fleet-management or device-administration use case, not just the worked example shown.

Two cross-cutting rules that apply to every pattern above:

• Capture pre-state before any write. Every _set / _modify / _set_limit / raw_cmd with a write scope is preceded by the matching _get / _query against the current state. The pre-state is what the rollback path quotes; without it, rollback is impossible. This is the doca-hardware-safety pre-flight inventory (doca-hardware-safety/CAPABILITIES.md#capabilities-and-modes) rule applied at the API surface.

• Capability-supported-first. Each sub-domain has a capability gate: for icm-quota, doca_mgmt_cap_icm_quota_is_supported; for multi-domain diagnostics data, doca_mgmt_cap_diagnostics_data_multi_domain_is_supported; for the general device caps, doca_mgmt_device_caps_general_get to read the current cap set. The agent does not recommend a set against a sub-domain whose is_supported returned a failure.

Capabilities and modes

DOCA Management is the management-plane API surface for BlueField / ConnectX device-level operations. The host-side library exposes a management context per device, an optional representor context per VF / function-level surface, four typed sub-domains (general caps, congestion-control global status, diagnostics data, ICM quota), two raw HCA/register surfaces (raw HCA capability, raw register), target info enumeration, and a raw-command pipe with an explicit scope classifier.

doca-mgmt vs telemetry vs caps vs bench

Four DOCA surfaces appear in fleet-management conversations. They are NOT interchangeable; pick one before writing any code:

Decision rule for the agent. If the user's intent is "my fleet agent needs to programmatically read or write device-level state", doca-mgmt is the right surface. If the intent contains the words continuous, streaming, Prometheus, time-series, or real-time monitoring, telemetry is the right answer. If the operator is at an interactive prompt rather than writing code, doca-caps is the answer. If the question is about throughput or latency, doca-bench is the answer.

The management context object model

Two objects expose the management plane. Verified surface (doca_mgmt.h):

Every public doca_mgmt_* symbol is currently declared DOCA_EXPERIMENTAL in the installed headers. The agent must surface this whenever it recommends a symbol — see ## Version compatibility.

The raw-command scope ladder

doca_mgmt_raw_cmd(ctx, command_id, scope, in, in_size, out, out_size) is the firmware-control passthrough for operations that don't have a dedicated sub-domain surface. The enum doca_mgmt_cmd_scope field is the load-bearing piece:

Scope selection rule for the agent. Pick the narrowest scope that satisfies the user's intent. A read-only query goes through DEBUG_READ_ONLY; a write that has a dedicated sub-domain surface (caps-general, cc-global-status, diagnostics-data, icm-quota) should go through that surface, not through raw_cmd. raw_cmd is the escape valve for vendor-documented commands without a dedicated wrapper — not the primary management surface.

Raw HCA capability and register surfaces

DOCA 3.5 adds two dedicated raw surfaces for HCA capabilities and registers. They are not doca_mgmt_raw_cmd; they use typed field descriptors and do not take an enum doca_mgmt_cmd_scope.

doca_mgmt_raw_hca_cap_modify and doca_mgmt_raw_register_modify change device state. Apply the same pre-state capture, rollback, and doca-hardware-safety discipline as DOCA_MGMT_CMD_SCOPE_CONFIGURATION writes.

Target info enumeration

Target info enumeration lists devices and representors available as management targets. Use doca_mgmt_target_info_dev_create_list to enumerate device targets and doca_mgmt_target_info_dev_rep_create_list on a device target to enumerate its representors. Accessors return target strings, interface names, PCI function types, and representor indices. doca_mgmt_target_info_dev_rep_get_pci_pf_type returns DOCA_MGMT_PCI_PF_TYPE_EXTERNAL_HOST or DOCA_MGMT_PCI_PF_TYPE_SATELLITE. Destroy lists with the corresponding _destroy_list calls.

Device target accessors: doca_mgmt_target_info_dev_get_ibdev_name, doca_mgmt_target_info_dev_get_iface_name, doca_mgmt_target_info_dev_get_native_port_num, doca_mgmt_target_info_dev_get_pci_func_type, doca_mgmt_target_info_dev_get_target_string.

Representor target accessors: doca_mgmt_target_info_dev_rep_get_controller_num, doca_mgmt_target_info_dev_rep_get_iface_name, doca_mgmt_target_info_dev_rep_get_pci_func_type, doca_mgmt_target_info_dev_rep_get_pci_pf_type, doca_mgmt_target_info_dev_rep_get_pf_index, doca_mgmt_target_info_dev_rep_get_sf_index, doca_mgmt_target_info_dev_rep_get_target_string, doca_mgmt_target_info_dev_rep_get_vf_index, doca_mgmt_target_info_dev_rep_get_vhca_id.

Sub-domain surfaces

Four sub-domains expose typed wrappers on top of the management context. Each has its own capability gate and lifecycle:

Configuration shape

Mandatory before any sub-domain operation: a doca_mgmt_dev_ctx on the target device (created from a doca_dev or a target string), and (for representor-targeted operations) a doca_mgmt_dev_rep_ctx on the target VF / function (created from a doca_dev_rep, a PCI address, or a target string). The sub-domain handle is a transient configuration carrier: create it, populate fields, apply via _set, then destroy. Persistent state lives on the device, not on the handle. The handle's _clear call is for re-use of the same handle across multiple fields; the handle's _destroy is the final teardown.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over- docs rule, see doca-version/SKILL.md. The body lives there; this skill does not duplicate it.

The doca-mgmt-specific overlay is:

• Every public doca_mgmt_* symbol is currently tagged EXPERIMENTAL. The installed headers declare every doca_mgmt_* symbol DOCA_EXPERIMENTAL. The agent must surface this whenever it recommends a management symbol: the API can change shape between DOCA releases, and building a long-lived fleet-management tool against this surface requires explicit per-release re-verification (see TASKS.md ## test).

• DOCA 3.5 added new public API functions and constants. The agent must treat these additions as part of the same EXPERIMENTAL surface and verify them against the installed headers before recommending them. The added functions are:

  Copy

  doca_mgmt_cap_diagnostics_data_multi_domain_is_supported
  doca_mgmt_dev_ctx_create_from_target_string
  doca_mgmt_dev_rep_ctx_create_by_pci_addr
  doca_mgmt_dev_rep_ctx_create_from_target_string
  doca_mgmt_diagnostics_data_clear
  doca_mgmt_diagnostics_data_create
  doca_mgmt_diagnostics_data_destroy
  doca_mgmt_diagnostics_data_get_multi_domain
  doca_mgmt_diagnostics_data_modify_for_dev
  doca_mgmt_diagnostics_data_query_for_dev
  doca_mgmt_diagnostics_data_set_multi_domain
  doca_mgmt_raw_field_desc_list_free
  doca_mgmt_raw_field_list_free
  doca_mgmt_raw_hca_cap_describe
  doca_mgmt_raw_hca_cap_list
  doca_mgmt_raw_hca_cap_modify
  doca_mgmt_raw_hca_cap_query
  doca_mgmt_raw_hca_cap_query_all
  doca_mgmt_raw_register_describe
  doca_mgmt_raw_register_list
  doca_mgmt_raw_register_modify
  doca_mgmt_raw_register_query
  doca_mgmt_raw_register_query_all
  doca_mgmt_raw_str_list_free
  doca_mgmt_target_info_dev_create_list
  doca_mgmt_target_info_dev_destroy_list
  doca_mgmt_target_info_dev_get_ibdev_name
  doca_mgmt_target_info_dev_get_iface_name
  doca_mgmt_target_info_dev_get_native_port_num
  doca_mgmt_target_info_dev_get_pci_func_type
  doca_mgmt_target_info_dev_get_target_string
  doca_mgmt_target_info_dev_rep_create_list
  doca_mgmt_target_info_dev_rep_destroy_list
  doca_mgmt_target_info_dev_rep_get_controller_num
  doca_mgmt_target_info_dev_rep_get_iface_name
  doca_mgmt_target_info_dev_rep_get_pci_func_type
  doca_mgmt_target_info_dev_rep_get_pci_pf_type
  doca_mgmt_target_info_dev_rep_get_pf_index
  doca_mgmt_target_info_dev_rep_get_sf_index
  doca_mgmt_target_info_dev_rep_get_target_string
  doca_mgmt_target_info_dev_rep_get_vf_index
  doca_mgmt_target_info_dev_rep_get_vhca_id

  The added constants are:

  Copy

  DOCA_MGMT_PCI_PF_TYPE_EXTERNAL_HOST
  DOCA_MGMT_PCI_PF_TYPE_SATELLITE
  DOCA_MGMT_RAW_FIELD_ACCESS_INDEX
  DOCA_MGMT_RAW_FIELD_ACCESS_OP
  DOCA_MGMT_RAW_FIELD_ACCESS_RO
  DOCA_MGMT_RAW_FIELD_ACCESS_RW
  DOCA_MGMT_RAW_FIELD_ACCESS_UNKNOWN
  DOCA_MGMT_RAW_FIELD_ACCESS_WO
  DOCA_MGMT_RAW_HCA_CAP_MODE_CUR
  DOCA_MGMT_RAW_HCA_CAP_MODE_MAX
  DOCA_MGMT_RAW_HCA_CAP_TARGET_TYPE_OTHER_FUNCTION_ID
  DOCA_MGMT_RAW_HCA_CAP_TARGET_TYPE_OTHER_VHCA_ID
  DOCA_MGMT_RAW_HCA_CAP_TARGET_TYPE_SELF

• The runtime authority is the installed headers, not the public docs. Per the cross-cutting rule in doca-version CAPABILITIES.md ## Observability (doca-version/CAPABILITIES.md#observability), the agent confirms a symbol exists by checking the installed header set (doca_mgmt.h, doca_mgmt_device_caps_general.h, doca_mgmt_cc_global_status.h, doca_mgmt_diagnostics_data.h, doca_mgmt_icm_quota.h) before recommending it.

• doca-mgmt.pc plus doca-common.pc must match doca_caps --version at the four-way-match check (per doca-version CAPABILITIES.md ## Version compatibility (doca-version/CAPABILITIES.md#version-compatibility)). Management-plane operations depend on the firmware version on the device matching the host-side library's expectations; a four-way-match failure is the first hypothesis when doca_mgmt_raw_cmd returns DOCA_ERROR_IO_FAILED for an opcode that the vendor docs say should work.

• The closest public docs surface is the DOCA SDK index. The agent does not quote a specific docs URL for doca-mgmt from agent memory; instead it routes to the DOCA SDK index and through doca-public-knowledge-map/SKILL.md for the up-to-date URL pattern. Where a DOCA Management page is published, it is the authoritative source for current opcodes, scopes, and supported sub-domains; until the agent has verified it on docs.nvidia.com/doca/sdk/, the agent frames version-specific claims as "check against the installed headers and the release notes for your DOCA version".

Error taxonomy

The cross-library DOCA_ERROR_* taxonomy (what each family means and which debug layer it routes to) lives in doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy). The mgmt-specific overlay names the families the agent will see most often from doca_mgmt_* calls and what they specifically indicate:

Quote doca_error_get_descr() verbatim — do not paraphrase. The cross-cutting debug ladder (doca-debug TASKS.md ## debug (doca-debug/TASKS.md#debug)) is the canonical layered diagnosis path that the agent escalates to once the mgmt-specific cause has been narrowed.

Observability

doca-mgmt's observability surface is point-in-time and request/response, not streaming. Three primary signals the agent should reach for:

1. Pre-state capture before any write. Every sub-domain exposes a _get / _query symmetric to its _set / _modify; the pre-state is the baseline every rollback depends on. Without it, the agent cannot tell what was changed if the user wants to back out. This is the bundle- wide pre-flight inventory (doca-hardware-safety/CAPABILITIES.md#capabilities-and-modes) rule applied at the API surface.

2. Post-write re-query. After every _set / _modify / _set_limit / raw_cmd write, the agent re-runs the matching _get / _query to confirm the device adopted the new state. "The call returned success" is not sufficient evidence; the device's reported state is.

3. Capability snapshots at start of session. Every sub-domain's _is_supported and _get_max_* / _get result is a snapshot of what the device said was possible at the start. Save it as a baseline; if a later call fails with DOCA_ERROR_NOT_SUPPORTED the diff against this snapshot is the regression — either the firmware was reset between sessions or the device's representor was reconfigured.

For continuous observability (counters streamed over time, historical metrics), doca-mgmt is the wrong surface — that is doca-telemetry/SKILL.md. For cross-cutting observability primitives (--sdk-log-level, DOCA_LOG_LEVEL) see doca-debug CAPABILITIES.md ## Observability (doca-debug/CAPABILITIES.md#observability). For the install-tree observability (logger names, package layout) defer to doca-public-knowledge-map/SKILL.md.

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy) (specifically ### Per-artifact overlay pattern (doca-hardware-safety/CAPABILITIES.md#per-artifact-overlay-pattern)). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

doca-mgmt is — alongside mlxconfig and BFB reflash — one of the primary surfaces through which an agent can modify device-level state programmatically. A wrong raw_cmd opcode, a wrong scope, or an unrollbackable write can leave a device in a state the operator cannot restore. Three policies follow from that:

1. Pre-state-capture is a hard precondition for any write. The agent does NOT recommend any _set / _modify / _set_limit / raw_cmd-with-write-scope call — including doca_mgmt_raw_hca_cap_modify, doca_mgmt_raw_register_modify, and doca_mgmt_diagnostics_data_modify_for_dev — without first walking the matching _get / _query to capture the current state. The captured state is what the rollback path quotes; the agent does not invent rollback values from memory. This is the doca-hardware-safety pre-flight inventory (doca-hardware-safety/CAPABILITIES.md#capabilities-and-modes) rule applied at the API surface.

2. Narrowest scope wins. When the user describes an operation, the agent picks the narrowest doca_mgmt_cmd_scope (or sub-domain wrapper) that satisfies it. Read-only operations go through DEBUG_READ_ONLY. Write operations that have a dedicated wrapper (caps-general, cc-global-status, diagnostics-data, icm-quota) go through that wrapper, NOT through raw_cmd. doca_mgmt_raw_hca_cap_modify and doca_mgmt_raw_register_modify are write-scope raw surfaces and require the same precondition gates as raw_cmd with write scope. raw_cmd with DEBUG_WRITE_FULL is the widest scope and requires the most precondition gates from the meta-policy — maintenance window, OOB access, replica-first validation, documented rollback.

3. No documented rollback → refuse and escalate. Per doca-hardware-safety ## Safety policy (doca-hardware-safety/CAPABILITIES.md#safety-policy), any change for which the operator cannot describe a rollback path is refused and routed to the operator's change-control process. doca-mgmt is the surface where this refusal is enforced at the API call: the agent does not issue a write whose _get counterpart cannot reproduce the pre-write state.

For changes that touch hardware state below the doca-mgmt library itself — mlxconfig-class writes that bypass DOCA, NIC firmware burns, BlueField BFB reflash, host kernel boot parameter changes — the cross-cutting meta-policy in doca-hardware-safety/SKILL.md applies without modification. The agent walks the hardware-safety ladder first whenever the recommended change falls into any of those classes, then the doca-mgmt overlay above for the API-surface specifics.

Deferred topic boundaries

This skill scopes itself to the DOCA Management library. Adjacent topics the agent will get asked but should route elsewhere:

• mlxconfig-class firmware-stored configuration outside the DOCA API — out of scope. The doca-mgmt surface and mlxconfig partially overlap (both can affect device configuration); for mlxconfig proper, route to the doca-hardware-safety/SKILL.md meta-policy and to the public Mellanox / NVIDIA firmware tools documentation reachable through doca-public-knowledge-map/SKILL.md.

• Live telemetry streaming — owned by doca-telemetry/SKILL.md and doca-telemetry-exporter/SKILL.md.

• Read-only capability snapshots from a CLI — owned by doca-caps/SKILL.md.

• Programmable congestion control — owned by doca-pcc/SKILL.md and doca-pcc-counters/SKILL.md. 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.

• Cross-library DOCA_ERROR_* taxonomy — owned by doca-programming-guide CAPABILITIES.md ## Error taxonomy (doca-programming-guide/CAPABILITIES.md#error-taxonomy). This skill adds the mgmt overlay, not the taxonomy itself.

• Cross-cutting hardware-state change discipline — owned by doca-hardware-safety/SKILL.md. This skill's safety overlay cross-links the meta-policy; it does not redefine the rules.