Diagnostic Configuration File#

DCGM Diagnostics uses the dcgm-diag-v1 YAML format for device-specific plugin permissions, thresholds, and parameters. The installed diag-skus.yaml file supplies NVIDIA’s product defaults. A file passed to dcgmi diag --configfile uses the same skus structure as an overlay.

This configuration selects values for a plugin that is already installed and available. It cannot install a plugin, add a test to a numbered suite, or make an unsupported test available on a GPU.

Configuration sources and precedence#

DCGM resolves a parameter from the following sources, from lowest to highest priority:

Diagnostic configuration precedence#
Priority	Source	Behavior
1	Plugin fallback	A default compiled into the plugin applies when no higher-priority source supplies the field.
2	Packaged `diag-skus.yaml`	The entry for the detected GPU supplies product-specific permissions, calibration, and thresholds. If the installed file cannot be read, DCGM uses a fallback copy compiled into the diagnostic executable.
3	`--configfile` overlay	Fields under an entry with the same `id` replace corresponding packaged fields. Omitted fields continue to use packaged values.
4	`--parameters`	Explicit `<test-name>.<parameter-name>=<value>` assignments replace corresponding values for that request.

The packaged file is normally under /usr/share/datacenter-gpu-manager-4/diag-skus.yaml. Treat it as package-owned: do not edit it in place. Use --configfile for a request-specific overlay.

The merge is recursive through the parameter level. For example, overriding memory.minimum_allocation_percentage does not remove the packaged memory.is_allowed value. A subtest field overrides only the same field in the same subtest. An overlay cannot delete a packaged field.

Document structure#

A complete packaged document has the following shape:

version: "<DCGM-release>"
spec: dcgm-diag-v1
skus:
  - name: <descriptive-product-name>
    id: '<PCI-device-id>'
    <test-name>:
      is_allowed: true
      <parameter-name>: <scalar-value>
      <subtest-name>:
        <subtest-parameter-name>: <scalar-value>

An overlay supplied through --configfile needs only skus. It may retain version and spec as descriptive metadata, but DCGM dispatches the overlay by skus and does not use those two overlay fields when merging values.

Top-level fields#

`dcgm-diag-v1` top-level fields#
Field	Type	Required	Meaning
`version`	String	Packaged file only	DCGM release that supplied the packaged configuration. DCGM requires this metadata in its packaged baseline and records it for debugging. It does not control overlay compatibility or dispatch.
`spec`	String	Packaged file only	Format identifier. The current value is `dcgm-diag-v1`. DCGM requires this metadata in its packaged baseline and records it for debugging.
`skus`	Sequence	Yes	One or more GPU matching and plugin-configuration entries. An overlay with no `skus` sequence changes no diagnostic values.

SKU entry fields#

Each item in skus is a mapping with these fields:

SKU entry fields#
Field	Type	Required	Meaning
`id`	Quoted string	Yes	Lowercase hexadecimal PCI device ID, such as `'2331'`. An eight-character device-plus-subsystem ID can target a specific board, such as `'20b2147f'`.
`name`	String	No	Descriptive label for maintainers. DCGM does not use it to match a GPU.
`<test-name>`	Mapping	No	Canonical lowercase test name. The matching plugin page defines the public fields that its map consumes.

DCGM first looks for an exact device-plus-subsystem ID entry and otherwise uses the four-character device ID entry. Quote IDs so YAML preserves them as strings, including leading zeroes. If the packaged file contains an eight-character entry for a board, a four-character overlay does not replace that more-specific entry; use the ID selected for that board. Define an ID only once in an overlay.

Plugin maps and values#

A plugin map can contain scalar plugin parameters and, where documented, a single level of subtest maps. Deeper nesting, sequences, and arbitrary maps are not part of dcgm-diag-v1. Field names are case-sensitive; use the canonical lowercase spelling shown on the plugin page.

The common scalar field ignore_error_codes accepts the diagnostic error code specification documented for --ignoreErrorCodes in dcgmi diag. DCGM’s diagnostic framework consumes this field for the configured plugin; the command-line --ignoreErrorCodes option has higher priority.

Each plugin reference contains a Configuration-file dispatch section. It identifies:

the skus[].<test-name> map dispatched to that plugin;
the scalar fields accepted from that map;
any supported subtest maps; and
parameters that are request-only and therefore must be set with --parameters instead.

Do not infer that every command-line parameter can appear in a SKU file. In particular, string-valued selectors and passthrough arguments are generally request-only. Additional calibration fields can appear in NVIDIA’s packaged file; fields not documented in a plugin’s dispatch section are implementation-owned and are not a supported user-overlay interface.

Unknown test or parameter names do not make a plugin support that field. They can be rejected only after the configuration is merged and the plugin is dispatched, so validate an overlay by running the intended named test on an idle target rather than assuming an unreported key was accepted.

Overlay example#

This overlay enables memory for PCI device 2331 and changes only its allocation target. All other fields for that device continue to come from the packaged configuration or the plugin fallback:

skus:
  - name: H100 80GB PCIe
    id: '2331'
    memory:
      is_allowed: true
      minimum_allocation_percentage: 50.0
      l1_is_allowed: false

Run the named test with the overlay:

$ dcgmi diag --run memory --entity-id gpu:0 \
    --configfile custom-diag-tests.yaml

An explicit command-line value has final priority. This invocation changes the allocation target to 60 percent without changing the file:

$ dcgmi diag --run memory --entity-id gpu:0 \
    --configfile custom-diag-tests.yaml \
    --parameters memory.minimum_allocation_percentage=60.0