dcgmi discovery#

NAME#

dcgmi-discovery - list DCGM entities and query their attributes

SYNOPSIS#

dcgmi discovery (--list | -l) [--all | -a] [--host <address>]
dcgmi discovery (--info | -i) <attributes>
                [--gpuid <id> | --cpuid <id> | --group <id>]
                [--verbose] [--host <address>]
dcgmi discovery (--compute-hierarchy | -c) [--host <address>]

DESCRIPTION#

dcgmi discovery lists entities known to the host engine, displays the MIG hierarchy, or reports selected attributes for a GPU, CPU, or GPU group.

The list form shows GPUs, NVSwitches, ConnectX devices, and NVIDIA CPUs. The information form defaults to the built-in all-GPU group when no target is given. The hierarchy form shows GPU instances and compute instances.

OPTIONS#

-l, --list

List discovered GPUs, NVSwitches, ConnectX devices, and NVIDIA CPUs. Inactive GPUs are omitted unless --all is specified.

-a, --all

Include inactive GPUs in --list output. This option does not change information or hierarchy queries. For each included GPU whose status is not OK, the output adds Status: <state>. Its device name and PCI bus ID are suffixed with (last known) to identify cached values. The UUID remains displayed without that suffix.

-i <attributes>, --info <attributes>

Report the selected attributes. Combine each of the following letters at most once:

a: Device identity, firmware, and PCI information.
p: Power limits.
t: Thermal limits.
c: Supported application-clock pairs.
w: Workload power profiles.

For example, -i apt reports device, power, and thermal information.

--gpuid <id>

Query one GPU by DCGM GPU ID.

--cpuid <id>

Query one NVIDIA CPU by DCGM CPU ID. For the a attribute, CPU queries report its owned core ranges and serial number.

-g <id>, --group <id>

Query a persistent GPU group. The default is the built-in all-GPU group.

-v, --verbose

For a group information query, report the selected attributes separately for each GPU instead of summarizing common values.

-c, --compute-hierarchy

List the MIG GPU-instance and compute-instance hierarchy.

--host <address>

Connect to the specified host engine. See dcgmi for address syntax.

-h, --help

Print generated usage information and exit.

ENTITY ID DISCOVERY#

Use the following runtime operations rather than assuming that entity IDs are stable across hosts or host-engine lifetimes.

Entity ID sources#
Entity selector	Enumeration command	Identifier shown
`gpu`, `nvswitch`, `cx`, `cpu`	`dcgmi discovery --list`	GPU ID, Switch ID, ConnectX ID, or CPU ID
`core`	`dcgmi discovery --list` or `dcgmi discovery --info a --cpuid <id>`	`Cores`/`CPU Ranges` owned by the CPU
`instance`, `compute_instance`	`dcgmi discovery --compute-hierarchy`	DCGM entity ID together with its parent GPU and MIG placement
`link`, `gpu_link`, `switch_link`	`dcgmi nvlink --link-status --show-entity-ids`	Port index and packed `link` entity ID for every supported GPU and NVSwitch port

DCGM 4.6 has no dedicated dcgmi operation that enumerates vgpu entity IDs. Obtain those from the vGPU management/API inventory before using a vgpu:<id> selector. --all affects only the GPU portion of --list; it adds inactive GPUs but does not change the other entity lists.

ATTRIBUTE REFERENCE#

The information letters select the following complete output sets. These are also the discovery operations to use when choosing hardware-dependent values for dcgmi config.

Information attribute sets#
Letter	Values reported	Practical use
`a`	Device name, PCI bus ID, UUID, serial number, InfoROM image version, and VBIOS version	Identify a GPU and correlate DCGM IDs with inventory or PCI data
`p`	Current, default, minimum, maximum, and enforced power limits in watts	Choose a valid `config --powerlimit` value
`t`	Shutdown and slowdown temperatures in degrees Celsius	Interpret thermal policy and health thresholds
`c`	Every supported `memory clock, SM clock` pair in MHz	Choose an exact `config --appclocks` pair
`w`	Supported, requested, and enforced workload power-profile index masks	Choose and verify a `config --workloadpowerprofile` index

Letters can be concatenated in any order, for example --info aptc. Support is device-specific: an attribute query can report that a feature is unsupported even though another GPU or architecture provides it. For a group query, **** means that the GPUs do not share one value; repeat the query with --verbose to see each GPU. Query every GPU that will receive a configuration, because a value supported by one member need not be supported by the others.

--cpuid currently supplies useful output only for a. Use --list --all to distinguish active and inactive physical GPUs.

EXAMPLES#

List active GPUs and the other discovered platform entities:

$ dcgmi discovery --list

Include detached or otherwise inactive GPUs:

$ dcgmi discovery --list --all

Show identity, power, thermal, and clock information for GPU 0:

$ dcgmi discovery --info aptc --gpuid 0

Display the MIG hierarchy:

$ dcgmi discovery --compute-hierarchy