Skip to content

Privatize system.Device helper classes #1942

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mdboom wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Privatize system.Device helper classes #1942

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion cuda_core/cuda/core/system/_clock.pxi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -129,7 +129,7 @@ cdef class ClockInfo:

Returns
-------
ClockOffsets
:obj:`~_device.ClockOffsets`
An object with the min, max and current clock offset.
"""
return ClockOffsets(nvml.device_get_clock_offsets(self._handle, self._clock_type, pstate))
74 changes: 30 additions & 44 deletions cuda_core/cuda/core/system/_device.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,7 +159,7 @@ cdef class Device:
@property
def arch(self) -> DeviceArch:
"""
Device architecture.
:obj:`~DeviceArch` device architecture.

For example, a Tesla V100 will report ``DeviceArchitecture.name ==
"VOLTA"``, and RTX A6000 will report ``DeviceArchitecture.name ==
Expand All @@ -177,7 +177,7 @@ cdef class Device:
@property
def brand(self) -> BrandType:
"""
Brand of the device
:obj:`~BrandType` brand of the device
"""
return BrandType(nvml.device_get_brand(self._handle))

Expand Down Expand Up @@ -289,7 +289,7 @@ cdef class Device:

Returns
-------
Iterator of Device
Iterator over :obj:`~Device`
An iterator over available devices.
"""
for device_id in range(nvml.device_get_count_v2()):
Expand All @@ -301,7 +301,7 @@ cdef class Device:
@property
def addressing_mode(self) -> AddressingMode:
"""
Get the addressing mode of the device.
Get the :obj:`~AddressingMode` of the device.

Addressing modes can be one of:

Expand Down Expand Up @@ -334,7 +334,7 @@ cdef class Device:

Returns
-------
Iterator of Device
Iterator of :obj:`~Device`
An iterator over available devices.
"""
cdef Device device
Expand Down Expand Up @@ -411,7 +411,7 @@ cdef class Device:

def clock(self, clock_type: ClockType) -> ClockInfo:
"""
Get information about and manage a specific clock on a device.
:obj:`~_device.ClockInfo` object to get information about and manage a specific clock on a device.
"""
return ClockInfo(self._handle, clock_type)

Expand Down Expand Up @@ -442,7 +442,7 @@ cdef class Device:

def get_current_clock_event_reasons(self) -> list[ClocksEventReasons]:
"""
Retrieves the current clocks event reasons.
Retrieves the current :obj:`~ClocksEventReasons`.

For all fully supported products.
"""
Expand All @@ -452,7 +452,7 @@ cdef class Device:

def get_supported_clock_event_reasons(self) -> list[ClocksEventReasons]:
"""
Retrieves supported clocks event reasons that can be returned by
Retrieves supported :obj:`~ClocksEventReasons` that can be returned by
:meth:`get_current_clock_event_reasons`.

For all fully supported products.
Expand All @@ -470,7 +470,7 @@ cdef class Device:
@property
def cooler(self) -> CoolerInfo:
"""
Get information about cooler on a device.
:obj:`~_device.CoolerInfo` object with cooler information for the device.
"""
return CoolerInfo(nvml.device_get_cooler_info(self._handle))

Expand All @@ -481,7 +481,7 @@ cdef class Device:
@property
def attributes(self) -> DeviceAttributes:
"""
Get various device attributes.
:obj:`~_device.DeviceAttributes` object with various device attributes.

For Ampere™ or newer fully supported devices. Only available on Linux
systems.
Expand Down Expand Up @@ -549,9 +549,9 @@ cdef class Device:

Returns
-------
:class:`DeviceEvents`
:obj:`~_device.DeviceEvents`
An object representing the registered events. Call
:meth:`DeviceEvents.wait` on this object to wait for events.
:meth:`~_device.DeviceEvents.wait` on this object to wait for events.

Raises
------
Expand Down Expand Up @@ -582,7 +582,7 @@ cdef class Device:

def fan(self, fan: int = 0) -> FanInfo:
"""
Get information and manage a specific fan on a device.
:obj:`~_device.FanInfo` object to get information and manage a specific fan on a device.
"""
if fan < 0 or fan >= self.num_fans:
raise ValueError(f"Fan index {fan} is out of range [0, {self.num_fans})")
Expand All @@ -605,22 +605,22 @@ cdef class Device:

Each value specified can raise its own exception. That exception will
be raised when attempting to access the corresponding ``value`` from the
returned :class:`FieldValues` container.
returned :obj:`~_device.FieldValues` container.

To confirm that there are no exceptions in the entire container, call
:meth:`FieldValues.validate`.
:meth:`~_device.FieldValues.validate`.

Parameters
----------
field_ids: list of int or tuple of (int, int)
field_ids: list[int | tuple[int, int]]
List of field IDs to query.

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

Returns
-------
:class:`FieldValues`
:obj:`~_device.FieldValues`
Container of field values corresponding to the requested field IDs.
"""
return FieldValues(nvml.device_get_field_values(self._handle, field_ids))
Expand All @@ -631,7 +631,7 @@ cdef class Device:

Parameters
----------
field_ids: list of int or tuple of (int, int)
field_ids: list[int | tuple[int, int]]
List of field IDs to clear.

Each item may be either a single value from the :class:`FieldId`
Expand All @@ -646,7 +646,7 @@ cdef class Device:
@property
def inforom(self) -> InforomInfo:
"""
Accessor for InfoROM information.
:obj:`~_device.InforomInfo` object with InfoROM information.

For all products with an InfoROM.
"""
Expand All @@ -659,7 +659,7 @@ cdef class Device:
@property
def bar1_memory_info(self) -> BAR1MemoryInfo:
"""
Get information about BAR1 memory.
:obj:`~_device.BAR1MemoryInfo` object with BAR1 memory information.

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
Expand All @@ -670,7 +670,7 @@ cdef class Device:
@property
def memory_info(self) -> MemoryInfo:
"""
Object with memory information.
:obj:`~_device.MemoryInfo` object with memory information.
"""
return MemoryInfo(nvml.device_get_memory_info_v2(self._handle))

Expand All @@ -681,7 +681,7 @@ cdef class Device:
@property
def pci_info(self) -> PciInfo:
"""
The PCI attributes of this device.
:obj:`~_device.PciInfo` object with the PCI attributes of this device.
"""
return PciInfo(nvml.device_get_pci_info_ext(self._handle), self._handle)

Expand All @@ -703,7 +703,7 @@ cdef class Device:
@property
def dynamic_pstates_info(self) -> GpuDynamicPstatesInfo:
"""
Retrieve performance monitor samples from the associated subdevice.
:obj:`~_device.GpuDynamicPstatesInfo` object with performance monitor samples from the associated subdevice.
"""
return GpuDynamicPstatesInfo(nvml.device_get_dynamic_pstates_info(self._handle))

Expand All @@ -713,6 +713,11 @@ cdef class Device:

The returned list contains a contiguous list of valid P-States supported by
the device.

Return
------
list[Pstates]
A list of supported P-States for the device.
"""
return [Pstates(x) for x in nvml.device_get_supported_performance_states(self._handle)]

Expand All @@ -723,7 +728,7 @@ cdef class Device:
@property
def repair_status(self) -> RepairStatus:
"""
Get the repair status for TPC/Channel repair.
:obj:`~_device.RepairStatus` object with TPC/Channel repair status.

For Ampere™ or newer fully supported devices.
"""
Expand All @@ -736,7 +741,7 @@ cdef class Device:
@property
def temperature(self) -> Temperature:
"""
Get information about temperatures on a device.
:obj:`~_device.Temperature` object with temperature information for the device.
"""
return Temperature(self._handle)

Expand Down Expand Up @@ -822,46 +827,27 @@ def get_p2p_status(device1: Device, device2: Device, index: GpuP2PCapsIndex) ->
__all__ = [
"AddressingMode",
"AffinityScope",
"BAR1MemoryInfo",
"BrandType",
"ClockId",
"ClockInfo",
"ClockOffsets",
"ClocksEventReasons",
"ClockType",
"CoolerControl",
"CoolerInfo",
"CoolerTarget",
"Device",
"DeviceArch",
"DeviceAttributes",
"DeviceEvents",
"EventData",
"EventType",
"FanControlPolicy",
"FanInfo",
"FieldId",
"FieldValue",
"FieldValues",
"get_p2p_status",
"get_topology_common_ancestor",
"GpuDynamicPstatesInfo",
"GpuDynamicPstatesUtilization",
"GpuP2PCapsIndex",
"GpuP2PStatus",
"GpuTopologyLevel",
"InforomInfo",
"InforomObject",
"MemoryInfo",
"PcieUtilCounter",
"PciInfo",
"Pstates",
"RepairStatus",
"Temperature",
"TemperatureSensors",
"TemperatureThresholds",
"ThermalController",
"ThermalSensor",
"ThermalSettings",
"ThermalTarget",
]
20 changes: 13 additions & 7 deletions cuda_core/cuda/core/system/_system_events.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ cdef class SystemEvent:
@property
def event_type(self) -> SystemEventType:
"""
The type of event that was triggered.
The :obj:`~SystemEventType` that was triggered.
"""
return SystemEventType(self._event_data.event_type)

Expand All @@ -40,7 +40,7 @@ cdef class SystemEvent:
@property
def device(self) -> _device.Device:
"""
The device associated with this event.
The :obj:`~_device.Device` associated with this event.
"""
return _device.Device(pci_bus_id=self.gpu_id)

Expand All @@ -56,6 +56,9 @@ cdef class SystemEvents:
return len(self._event_data)

def __getitem__(self, idx: int) -> SystemEvent:
"""
Get the :obj:`~_system_events.SystemEvent` at the specified index.
"""
return SystemEvent(self._event_data[idx])


Expand Down Expand Up @@ -107,6 +110,12 @@ cdef class RegisteredSystemEvents:
buffer_size: int
The maximum number of events to retrieve. Must be at least 1.

Returns
-------
:obj:`~_system_events.SystemEvents`
A set of events that were received. The number of events returned may
be less than the specified buffer size if fewer events were available.

Raises
------
:class:`cuda.core.system.TimeoutError`
Expand Down Expand Up @@ -142,9 +151,9 @@ def register_events(events: SystemEventType | int | list[SystemEventType | int])

Returns
-------
:class:`RegisteredSystemEvents`
:obj:`~_system_events.RegisteredSystemEvents`
An object representing the registered events. Call
:meth:`RegisteredSystemEvents.wait` on this object to wait for events.
:meth:`~_system_events.RegisteredSystemEvents.wait` on this object to wait for events.

Raises
------
Expand All @@ -156,8 +165,5 @@ def register_events(events: SystemEventType | int | list[SystemEventType | int])

__all__ = [
"register_events",
"RegisteredSystemEvents",
"SystemEvent",
"SystemEvents",
"SystemEventType",
]
2 changes: 1 addition & 1 deletion cuda_core/cuda/core/system/_temperature.pxi
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,7 +140,7 @@ cdef class Temperature:

Returns
-------
:class:`ThermalSettings`
:obj:`~_device.ThermalSettings`
The thermal settings for the specified sensor.
"""
return ThermalSettings(nvml.device_get_thermal_settings(self._handle, sensor_index))
27 changes: 1 addition & 26 deletions cuda_core/docs/source/api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -199,9 +199,6 @@ Events
:toctree: generated/

system.register_events
system.RegisteredSystemEvents
system.SystemEvent
system.SystemEvents
system.SystemEventType

Enums
Expand All @@ -215,6 +212,7 @@ Enums
system.BrandType
system.ClockId
system.ClocksEventReasons
system.ClockType
system.CoolerControl
system.CoolerTarget
system.DeviceArch
Expand All @@ -238,29 +236,6 @@ Types
:template: autosummary/cyclass.rst

system.Device
system.BAR1MemoryInfo
system.ClockInfo
system.ClockOffsets
system.ClockType
system.CoolerInfo
system.DeviceAttributes
system.DeviceEvents
system.EventData
system.FanInfo
system.FieldValue
system.FieldValues
system.GpuDynamicPstatesInfo
system.GpuDynamicPstatesUtilization
system.GpuP2PCapsIndex
system.GpuP2PStatus
system.GpuTopologyLevel
system.InforomInfo
system.MemoryInfo
system.PciInfo
system.RepairStatus
system.Temperature
system.ThermalSensor
system.ThermalSettings

.. module:: cuda.core.utils

Expand Down
Loading
Loading