cuda.core.system: Add basic Nvlink and Utilization support (#1918)

* cuda.core.system: Add basic Nvlink and Utilization support

* Address comments in the PR

* Fix test

Author: mdboom

cuda_core/cuda/core/system/_device.pyx

@@ -33,10 +33,12 @@ include "_field_values.pxi"
 include "_inforom.pxi"
 include "_memory.pxi"
 include "_mig.pxi"
+include "_nvlink.pxi"
 include "_pci_info.pxi"
 include "_performance.pxi"
 include "_repair_status.pxi"
 include "_temperature.pxi"
+include "_utilization.pxi"
 
 
 cdef class Device:
@@ -702,6 +704,20 @@ cdef class Device:
         """
         return MemoryInfo(nvml.device_get_memory_info_v2(self._handle))
 
+    ##########################################################################
+    # NVLINK
+    # See external class definitions in _nvlink.pxi
+
+    def get_nvlink(self, link: int) -> NvlinkInfo:
+        """
+        Get :obj:`~NvlinkInfo` about this device.
+
+        For devices with NVLink support.
+        """
+        if link < 0 or link >= NvlinkInfo.max_links:
+            raise ValueError(f"Link index {link} is out of range [0, {NvlinkInfo.max_links})")
+        return NvlinkInfo(self, link)
+
     ##########################################################################
     # PCI INFO
     # See external class definitions in _pci_info.pxi
@@ -798,6 +814,31 @@ cdef class Device:
             device._handle = handle
             yield device
 
+    #######################################################################
+    # UTILIZATION
+
+    @property
+    def utilization(self) -> Utilization:
+        """
+        Retrieves the current :obj:`~Utilization` rates for the device's major
+        subsystems.
+
+        For Fermi™ or newer fully supported devices.
+
+        Note: During driver initialization when ECC is enabled one can see high
+        GPU and Memory Utilization readings.  This is caused by ECC Memory
+        Scrubbing mechanism that is performed during driver initialization.
+
+        Note: On MIG-enabled GPUs, querying device utilization rates is not
+        currently supported.
+
+        Returns
+        -------
+        Utilization
+            An object containing the current utilization rates for the device.
+        """
+        return Utilization(nvml.device_get_utilization_rates(self._handle))
+
 
 def get_topology_common_ancestor(device1: Device, device2: Device) -> GpuTopologyLevel:
     """
@@ -872,10 +913,12 @@ __all__ = [
     "GpuP2PStatus",
     "GpuTopologyLevel",
     "InforomObject",
+    "NvlinkVersion",
     "PcieUtilCounter",
     "Pstates",
     "TemperatureSensors",
     "TemperatureThresholds",
     "ThermalController",
     "ThermalTarget",
+    "Utilization",
 ]

cuda_core/cuda/core/system/_nvlink.pxi

@@ -0,0 +1,52 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+NvlinkVersion = nvml.NvlinkVersion
+
+
+cdef class NvlinkInfo:
+    """
+    Nvlink information for a device.
+    """
+    cdef Device _device
+    cdef int _link
+
+    def __init__(self, device: Device, link: int):
+        self._device = device
+        self._link = link
+
+    @property
+    def version(self) -> NvlinkVersion:
+        """
+        Retrieves the :obj:`~NvlinkVersion` for the device and link.
+
+        For all products with NvLink support.
+
+        Returns
+        -------
+        NvlinkVersion
+            The Nvlink version.
+        """
+        return NvlinkVersion(nvml.device_get_nvlink_version(self._device._handle, self._link))
+
+    @property
+    def state(self) -> bool:
+        """
+        Retrieves the state of the device's Nvlink for the device and link specified.
+
+        For Pascal™ or newer fully supported devices.
+
+        For all products with Nvlink support.
+
+        Returns
+        -------
+        bool
+            `True` if the Nvlink is active.
+        """
+        return (
+            nvml.device_get_nvlink_state(self._device._handle, self._link) == nvml.EnableState.FEATURE_ENABLED
+        )
+
+    max_links = nvml.NVLINK_MAX_LINKS

cuda_core/cuda/core/system/_utilization.pxi

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+cdef class Utilization:
+    """
+    Utilization rates for a device.
+
+    For devices with compute capability 2.0 or higher.
+    """
+    cdef object _utilization
+
+    def __init__(self, utilization: nvml.Utilization):
+        self._utilization = utilization
+
+    @property
+    def gpu(self) -> int:
+        """
+        Percent of time over the past sample period during which one or more kernels was executing on the GPU.
+        """
+        return self._utilization.gpu
+
+    @property
+    def memory(self) -> int:
+        """
+        Percent of time over the past sample period during which global (device) memory was being read or written.
+        """
+        return self._utilization.memory

cuda_core/docs/source/api.rst

@@ -220,6 +220,7 @@ Enums
    system.FanControlPolicy
    system.FieldId
    system.InforomObject
+   system.NvlinkVersion
    system.PcieUtilCounter
    system.Pstates
    system.TemperatureSensors

cuda_core/docs/source/api_private.rst

@@ -77,6 +77,7 @@ NVML
    system._device.InforomInfo
    system._device.MemoryInfo
    system._device.MigInfo
+   system._device.NvlinkInfo
    system._device.PciInfo
    system._device.RepairStatus
    system._device.Temperature

cuda_core/tests/system/test_system_device.py

@@ -731,6 +731,41 @@ def test_pstates():
             assert isinstance(utilization.dec_threshold, int)
 
 
+def test_nvlink():
+    for device in system.Device.get_all_devices():
+        max_links = _device.NvlinkInfo.max_links
+        assert isinstance(max_links, int)
+        assert max_links > 0
+
+        for link in range(max_links):
+            with unsupported_before(device, None):
+                nvlink_info = device.get_nvlink(link)
+            assert isinstance(nvlink_info, _device.NvlinkInfo)
+
+            with unsupported_before(device, None):
+                version = nvlink_info.version
+            assert isinstance(version, system.NvlinkVersion)
+
+            with unsupported_before(device, None):
+                state = nvlink_info.state
+            assert isinstance(state, bool)
+
+
+def test_utilization():
+    for device in system.Device.get_all_devices():
+        with unsupported_before(device, None):
+            utilization = device.utilization
+        assert isinstance(utilization, system.Utilization)
+
+        gpu = utilization.gpu
+        assert isinstance(gpu, int)
+        assert 0 <= gpu <= 100
+
+        memory = utilization.memory
+        assert isinstance(memory, int)
+        assert 0 <= memory <= 100
+
+
 @pytest.mark.skipif(helpers.IS_WSL or helpers.IS_WINDOWS, reason="MIG not supported on WSL or Windows")
 def test_mig():
     for device in system.Device.get_all_devices():