cuda.core.system.Device#

Representation of a device.

cuda.core.system.Device provides access to various pieces of metadata about devices and their topology, as provided by the NVIDIA Management Library (NVML). To use CUDA with a device, use cuda.core.Device.

Creating a device instance causes NVML to initialize the target GPU. NVML may initialize additional GPUs if the target GPU is an SLI slave.

Parameters:

index (int, optional) –
Integer representing the CUDA device index to get a handle to. Valid values are between 0 and cuda.core.system.get_num_devices() - 1.

The order in which devices are enumerated has no guarantees of consistency between reboots. For that reason, it is recommended that devices are looked up by their PCI ids or UUID.
uuid (bytes or str, optional) – UUID of a CUDA device to get a handle to.
pci_bus_id (bytes or str, optional) – PCI bus ID of a CUDA device to get a handle to.

Raises:

ValueError – If anything other than a single index, uuid or pci_bus_id are specified.

Methods

__init__(*args, **kwargs)#

attributes(self) → DeviceAttributes#

Get various device attributes.

For Ampere™ or newer fully supported devices. Only available on Linux systems.

clear_field_values(self, list field_ids: list[int | tuple[int, int]]) → None#

Clear multiple field values from the device.

Parameters:

field_ids (list of int or tuple of (int, int)) –

List of field IDs to clear.

Each item may be either a single value from the FieldId enum, or a pair of (FieldId, scope ID).

classmethod get_all_devices(cls) → Iterable[Device]#

Query the available device instances.

Returns:: An iterator over available devices.
Return type:: Iterator of Device

classmethod get_all_devices_with_cpu_affinity( cls, int cpu_index: int, ) → Iterable[Device]#

Retrieve the set of GPUs that have a CPU affinity with the given CPU number.

Supported on Linux only.

Parameters:: cpu_index (int) – The CPU index.
Returns:: An iterator over available devices.
Return type:: Iterator of Device

classmethod get_device_count(cls) → int#

Get the number of available devices.

Returns:: The number of available devices.
Return type:: int

get_field_values(self, list field_ids: list[int | tuple[int, int]]) → FieldValues#

Get multiple field values from the device.

Each value specified can raise its own exception. That exception will be raised when attempting to access the corresponding value from the returned FieldValues container.

To confirm that there are no exceptions in the entire container, call FieldValues.validate().

Parameters:

field_ids (list of int or tuple of (int, int)) –

List of field IDs to query.

Each item may be either a single value from the FieldId enum, or a pair of (FieldId, scope ID).

Returns:

Container of field values corresponding to the requested field IDs.

Return type:

FieldValues

get_topology_nearest_gpus( self, level: GpuTopologyLevel, ) → Iterable[Device]#

Retrieve the GPUs that are nearest to this device at a specific interconnectivity level.

Supported on Linux only.

Parameters:: level (GpuTopologyLevel) – The topology level.
Returns:: The nearest devices at the given topology level.
Return type:: Iterable of Device

Attributes

addressing_mode#

AddressingMode

Get the addressing mode of the device.

Addressing modes can be one of:

AddressingMode.DEVICE_ADDRESSING_MODE_HMM: System allocated memory (malloc, mmap) is addressable from the device (GPU), via software-based mirroring of the CPU’s page tables, on the GPU.
AddressingMode.DEVICE_ADDRESSING_MODE_ATS: System allocated memory (malloc, mmap) is addressable from the device (GPU), via Address Translation Services. This means that there is (effectively) a single set of page tables, and the CPU and GPU both use them.
AddressingMode.DEVICE_ADDRESSING_MODE_NONE: Neither HMM nor ATS is active.

Type:: Device.addressing_mode

architecture#

DeviceArchitecture

Device architecture. For example, a Tesla V100 will report DeviceArchitecture.name == "Volta", and RTX A6000 will report DeviceArchitecture.name == "Ampere". If the device returns an architecture that is unknown to NVML then DeviceArchitecture.name == "Unknown" is reported, whereas an architecture that is unknown to cuda.core.system is reported as DeviceArchitecture.name == "Unlisted".

Type:: Device.architecture

bar1_memory_info#

BAR1MemoryInfo

Get information about BAR1 memory.

BAR1 is used to map the FB (device memory) so that it can be directly accessed by the CPU or by 3rd party devices (peer-to-peer on the PCIE bus).

Type:: Device.bar1_memory_info

brand#

BrandType

Brand of the device

Type:: Device.brand

cpu_affinity#

list[int]

Get a list containing the CPU indices to which the GPU is directly connected.

Examples

>>> Device(index=0).cpu_affinity
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19,
 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59]

Type:: Device.cpu_affinity

cuda_compute_capability#

tuple[int, int]

CUDA compute capability of the device, e.g.: (7, 0) for a Tesla V100.

Returns a tuple (major, minor).

Type:: Device.cuda_compute_capability

display_active#

bool

The display active status for this device.

Indicates whether a display is initialized on the device. For example, whether X Server is attached to this device and has allocated memory for the screen.

Display can be active even when no monitor is physically attached.

Type:: Device.display_active

display_mode#

bool

The display mode for this device.

Indicates whether a physical display (e.g. monitor) is currently connected to any of the device’s connectors.

Type:: Device.display_mode

index#

int

The NVML index of this device.

Valid indices are derived from the count returned by Device.get_device_count(). For example, if get_device_count() returns 2, the valid indices are 0 and 1, corresponding to GPU 0 and GPU 1.

The order in which NVML enumerates devices has no guarantees of consistency between reboots. For that reason, it is recommended that devices be looked up by their PCI ids or GPU UUID.

Note: The NVML index may not correlate with other APIs, such as the CUDA device index.

Type:: Device.index

inforom#

InforomInfo

Accessor for InfoROM information.

For all products with an InfoROM.

Type:: Device.inforom

is_c2c_mode_enabled#

bool

Whether the C2C (Chip-to-Chip) mode is enabled for this device.

Type:: Device.is_c2c_mode_enabled

memory_info#

MemoryInfo

Object with memory information.

Type:: Device.memory_info

minor_number#

int

The minor number of this device.

For Linux only.

The minor number is used by the Linux device driver to identify the device node in /dev/nvidiaX.

Type:: Device.minor_number

module_id#

int

Get a unique identifier for the device module on the baseboard.

This API retrieves a unique identifier for each GPU module that exists on a given baseboard. For non-baseboard products, this ID would always be 0.

Type:: Device.module_id

name#

str

Name of the device, e.g.: “Tesla V100-SXM2-32GB”

Type:: Device.name

pci_info#

PciInfo

The PCI attributes of this device.

Type:: Device.pci_info

persistence_mode_enabled#

bool

Whether persistence mode is enabled for this device.

For Linux only.

Type:: Device.persistence_mode_enabled

repair_status#

RepairStatus

Get the repair status for TPC/Channel repair.

For Ampere™ or newer fully supported devices.

Type:: Device.repair_status

serial#

str

Retrieves the globally unique board serial number associated with this device’s board.

Type:: Device.serial

uuid#

str

Retrieves the globally unique immutable UUID associated with this device, as a 5 part hexadecimal string, that augments the immutable, board serial identifier.

Type:: Device.uuid