Coverage for cuda / core / system / typing.py: 97.66%

1# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. 

2# 

3# SPDX-License-Identifier: Apache-2.0 

4 

5from cuda.core._utils.pycompat import StrEnum (empty)

6 

7__all__ = [ (empty)

8 "AddressingMode", 

9 "AffinityScope", 

10 "ClockId", 

11 "ClockType", 

12 "ClocksEventReasons", 

13 "CoolerControl", 

14 "CoolerTarget", 

15 "EventType", 

16 "FanControlPolicy", 

17 "GpuP2PCapsIndex", 

18 "GpuP2PStatus", 

19 "GpuTopologyLevel", 

20 "InforomObject", 

21 "SystemEventType", 

22 "TemperatureThresholds", 

23 "ThermalController", 

24 "ThermalTarget", 

25] 

26 

27 

28class AddressingMode(StrEnum): (empty)

29 """ 

30 Addressing mode of a device. 

31 

32 For Kepler™ or newer fully supported devices. 

33 """ 

34 

35 HMM = "hmm" (empty)

36 ATS = "ats" (empty)

37 

38 

39AddressingMode.HMM.__doc__ = """ (empty)

40 System allocated memory (``malloc``, ``mmap``) is addressable from the device 

41 (GPU), via software-based mirroring of the CPU's page tables, on the GPU. 

42""" 

43 

44AddressingMode.ATS.__doc__ = """ (empty)

45 System allocated memory (``malloc``, ``mmap``) is addressable from the device 

46 (GPU), via Address Translation Services. This means that there is (effectively) 

47 a single set of page tables, and the CPU and GPU both use them. 

48""" 

49 

50 

51class AffinityScope(StrEnum): (empty)

52 """ 

53 Scope for affinity queries. 

54 """ 

55 

56 NODE = "node" (empty)

57 SOCKET = "socket" (empty)

58 

59 

60AffinityScope.NODE.__doc__ = """ (empty)

61The NUMA node is the scope of the affinity query. This is the default scope. 

62""" 

63 

64AffinityScope.SOCKET.__doc__ = """ (empty)

65The CPU socket is the scope of the affinity query. 

66""" 

67 

68 

69class ClockId(StrEnum): (empty)

70 """ 

71 Clock Ids. These are used in combination with :class:`ClockType` to specify a single clock value. 

72 """ 

73 

74 CURRENT = "current" (empty)

75 CUSTOMER_BOOST_MAX = "customer_boost_max" (empty)

76 # APP_CLOCK_TARGET and APP_CLOCK_DEFAULT are deprecated so not included here 

77 

78 

79ClockId.CURRENT.__doc__ = "Current actual clock value." (empty)

80ClockId.CUSTOMER_BOOST_MAX.__doc__ = "OEM-defined maximum clock rate" (empty)

81 

82 

83class ClocksEventReasons(StrEnum): (empty)

84 """ 

85 Reasons for a clocks event. These are used in combination with :class:`ClockType` to specify the reason 

86 for a clocks event. 

87 """ 

88 

89 NONE = "none" (empty)

90 GPU_IDLE = "gpu_idle" (empty)

91 APPLICATIONS_CLOCKS_SETTING = "applications_clocks_setting" (empty)

92 SW_POWER_CAP = "sw_power_cap" (empty)

93 HW_SLOWDOWN = "hw_slowdown" (empty)

94 SYNC_BOOST = "sync_boost" (empty)

95 SW_THERMAL_SLOWDOWN = "sw_thermal_slowdown" (empty)

96 HW_THERMAL_SLOWDOWN = "hw_thermal_slowdown" (empty)

97 HW_POWER_BRAKE_SLOWDOWN = "hw_power_brake_slowdown" (empty)

98 DISPLAY_CLOCK_SETTING = "display_clock_setting" (empty)

99 

100 

101class ClockType(StrEnum): (empty)

102 """ 

103 Clock types. All speeds are in Mhz. 

104 """ 

105 

106 GRAPHICS = "graphics" (empty)

107 SM = "sm" (empty)

108 MEMORY = "memory" (empty)

109 VIDEO = "video" (empty)

110 

111 

112class CoolerControl(StrEnum): (empty)

113 """ 

114 Cooler control type. 

115 """ 

116 

117 TOGGLE = "toggle" (empty)

118 VARIABLE = "variable" (empty)

119 

120 

121CoolerControl.TOGGLE.__doc__ = """ (empty)

122This cooler can only be toggled either ON or OFF (e.g. a switch). 

123""" 

124 

125CoolerControl.VARIABLE.__doc__ = """ (empty)

126This cooler's level can be adjusted from some minimum to some maximum (e.g. a knob). 

127""" 

128 

129 

130class CoolerTarget(StrEnum): (empty)

131 """ 

132 Cooler target. 

133 """ 

134 

135 NONE = "none" (empty)

136 GPU = "gpu" (empty)

137 MEMORY = "memory" (empty)

138 POWER_SUPPLY = "power_supply" (empty)

139 # THERMAL_GPU_RELATED is a composite target, so it is omitted here and will 

140 # get returned as 3 separate targets: GPU, MEMORY, and POWER_SUPPLY. 

141 

142 

143CoolerTarget.NONE.__doc__ = "This cooler controls nothing." (empty)

144CoolerTarget.GPU.__doc__ = "This cooler can cool the GPU." (empty)

145CoolerTarget.MEMORY.__doc__ = "This cooler can cool the memory." (empty)

146CoolerTarget.POWER_SUPPLY.__doc__ = "This cooler can cool the power supply." (empty)

147 

148 

149class EventType(StrEnum): (empty)

150 """ 

151 Event types that can be waited on with :class:`DeviceEvents`. 

152 """ 

153 

154 NONE = "none" (empty)

155 SINGLE_BIT_ECC_ERROR = "single_bit_ecc_error" (empty)

156 DOUBLE_BIT_ECC_ERROR = "double_bit_ecc_error" (empty)

157 PSTATE = "pstate" (empty)

158 XID_CRITICAL_ERROR = "xid_critical_error" (empty)

159 CLOCK = "clock" (empty)

160 POWER_SOURCE_CHANGE = "power_source_change" (empty)

161 MIG_CONFIG_CHANGE = "mig_config_change" (empty)

162 SINGLE_BIT_ECC_ERROR_STORM = "single_bit_ecc_error_storm" (empty)

163 DRAM_RETIREMENT_EVENT = "dram_retirement_event" (empty)

164 DRAM_RETIREMENT_FAILURE = "dram_retirement_failure" (empty)

165 NON_FATAL_POISON_ERROR = "non_fatal_poison_error" (empty)

166 FATAL_POISON_ERROR = "fatal_poison_error" (empty)

167 GPU_UNAVAILABLE_ERROR = "gpu_unavailable_error" (empty)

168 GPU_RECOVERY_ACTION = "gpu_recovery_action" (empty)

169 

170 

171EventType.PSTATE.__doc__ = """ (empty)

172Event about PState changes 

173 

174On Fermi™ architecture, PState changes are also an indicator that GPU is throttling down due to 

175no work being executed on the GPU, power capping or thermal capping. In a typical situation, 

176Fermi-based GPU should stay in P0 for the duration of the execution of the compute process. 

177""" 

178 

179 

180class FanControlPolicy(StrEnum): (empty)

181 """ 

182 Fan control policies. 

183 """ 

184 

185 TEMPERATURE_CONTROLLED = "temperature_controlled" (empty)

186 MANUAL = "manual" (empty)

187 

188 

189class GpuP2PCapsIndex(StrEnum): (empty)

190 """ 

191 GPU peer-to-peer capabilities index. 

192 """ 

193 

194 READ = "read" (empty)

195 WRITE = "write" (empty)

196 NVLINK = "nvlink" (empty)

197 ATOMICS = "atomics" (empty)

198 PCI = "pci" (empty)

199 PROP = "prop" (empty)

200 UNKNOWN = "unknown" (empty)

201 

202 

203class GpuP2PStatus(StrEnum): (empty)

204 """ 

205 GPU peer-to-peer status. 

206 """ 

207 

208 OK = "ok" (empty)

209 CHIPSET_NOT_SUPPORTED = "chipset not supported" (empty)

210 GPU_NOT_SUPPORTED = "GPU not supported" (empty)

211 IOH_TOPOLOGY_NOT_SUPPORTED = "IOH topology not supported" (empty)

212 DISABLED_BY_REGKEY = "disabled by regkey" (empty)

213 NOT_SUPPORTED = "not supported" (empty)

214 UNKNOWN = "unknown" (empty)

215 

216 

217class GpuTopologyLevel(StrEnum): (empty)

218 """ 

219 Represents level relationships within a system between two GPUs. 

220 """ 

221 

222 INTERNAL = "internal" (empty)

223 SINGLE = "single" (empty)

224 MULTIPLE = "multiple" (empty)

225 HOSTBRIDGE = "hostbridge" (empty)

226 NODE = "node" (empty)

227 SYSTEM = "system" (empty)

228 

229 

230class InforomObject(StrEnum): (empty)

231 """ 

232 InfoROM objects types. 

233 """ 

234 

235 OEM = "oem" (empty)

236 ECC = "ecc" (empty)

237 POWER = "power" (empty)

238 DEN = "den" (empty)

239 

240 

241InforomObject.OEM.__doc__ = "An object defined by OEM." (empty)

242InforomObject.ECC.__doc__ = "The ECC object determining the level of ECC support." (empty)

243InforomObject.POWER.__doc__ = "The power management object." (empty)

244InforomObject.DEN.__doc__ = "DRAM Encryption object." (empty)

245 

246 

247class SystemEventType(StrEnum): (empty)

248 """ 

249 System event types. 

250 """ 

251 

252 UNBIND = "unbind" (empty)

253 BIND = "bind" (empty)

254 

255 

256class TemperatureThresholds(StrEnum): (empty)

257 """ 

258 Temperature threshold types. 

259 """ 

260 

261 SHUTDOWN = "shutdown" (empty)

262 SLOWDOWN = "slowdown" (empty)

263 MEM_MAX = "mem_max" (empty)

264 GPU_MAX = "gpu_max" (empty)

265 ACOUSTIC_MIN = "acoustic_min" (empty)

266 ACOUSTIC_CURR = "acoustic_curr" (empty)

267 ACOUSTIC_MAX = "acoustic_max" (empty)

268 GPS_CURR = "gps_curr" (empty)

269 

270 

271class ThermalController(StrEnum): (empty)

272 """ 

273 Thermal controller types. 

274 """ 

275 

276 GPU_INTERNAL = "gpu_internal" (empty)

277 ADM1032 = "adm1032" (empty)

278 ADT7461 = "adt7461" (empty)

279 MAX6649 = "max6649" (empty)

280 MAX1617 = "max1617" (empty)

281 LM99 = "lm99" (empty)

282 LM89 = "lm89" (empty)

283 LM64 = "lm64" (empty)

284 G781 = "g781" (empty)

285 ADT7473 = "adt7473" (empty)

286 SBMAX6649 = "sbmax6649" (empty)

287 VBIOSEVT = "vbiosevt" (empty)

288 OS = "os" (empty)

289 NVSYSCON_CANOAS = "nvsyscon_canoas" (empty)

290 NVSYSCON_E551 = "nvsyscon_e551" (empty)

291 MAX6649R = "max6649r" (empty)

292 ADT7473S = "adt7473s" (empty)

293 UNKNOWN = "unknown" (empty)

294 

295 

296class ThermalTarget(StrEnum): (empty)

297 """ 

298 Thermal sensor targets. 

299 """ 

300 

301 NONE = "none" (empty)

302 GPU = "gpu" (empty)

303 MEMORY = "memory" (empty)

304 POWER_SUPPLY = "power_supply" (empty)

305 BOARD = "board" (empty)

306 VCD_BOARD = "vcd_board" (empty)

307 VCD_INLET = "vcd_inlet" (empty)

308 VCD_OUTLET = "vcd_outlet" (empty)

309 ALL = "all" (empty)

310 

311 

312ThermalTarget.GPU.__doc__ = "GPU core temperature requires physical GPU handle." (empty)

313ThermalTarget.MEMORY.__doc__ = "GPU memory temperature requires physical GPU handle." (empty)

314ThermalTarget.POWER_SUPPLY.__doc__ = "GPU power supply temperature requires physical GPU handle." (empty)

315ThermalTarget.BOARD.__doc__ = "GPU board ambient temperature requires physical GPU handle." (empty)

316ThermalTarget.VCD_BOARD.__doc__ = "Visual Computing Device Board temperature requires visual computing device handle." (empty)

317ThermalTarget.VCD_INLET.__doc__ = "Visual Computing Device Inlet temperature requires visual computing device handle." (empty)

318ThermalTarget.VCD_OUTLET.__doc__ = "Visual Computing Device Outlet temperature requires visual computing device handle." (empty)

319 

320 

321# DeviceArch values are derived from cuda.bindings.nvml at definition time, so 

322# the class can only be defined when nvml is importable. 

323try: (empty)

324 from cuda.bindings import nvml as _nvml (empty)

325 

326 try: (empty)

327 from cuda.bindings._internal._fast_enum import FastEnum as _FastEnum (empty)

328 except ImportError: 

329 from enum import IntEnum as _FastEnum 

330 

331 # This uses FastEnum instead of StrEnum because the ordering of the values is 

332 # meaningful, e.g. Kepler "or later" 

333 class DeviceArch(_FastEnum): (empty)

334 """ 

335 Device architecture. 

336 """ 

337 

338 KEPLER = int(_nvml.DeviceArch.KEPLER) (empty)

339 MAXWELL = int(_nvml.DeviceArch.MAXWELL) (empty)

340 PASCAL = int(_nvml.DeviceArch.PASCAL) (empty)

341 VOLTA = int(_nvml.DeviceArch.VOLTA) (empty)

342 TURING = int(_nvml.DeviceArch.TURING) (empty)

343 AMPERE = int(_nvml.DeviceArch.AMPERE) (empty)

344 ADA = int(_nvml.DeviceArch.ADA) (empty)

345 HOPPER = int(_nvml.DeviceArch.HOPPER) (empty)

346 BLACKWELL = int(_nvml.DeviceArch.BLACKWELL) (empty)

347 UNKNOWN = int(_nvml.DeviceArch.UNKNOWN) (empty)

348 

349 __all__.append("DeviceArch") (empty)

350 

351 FieldId = _nvml.FieldId (empty)

352 

353 __all__.append("FieldId") (empty)

354 

355 del _nvml, _FastEnum (empty)

356 

357except ImportError: 

358 pass 

359 

360 

361del StrEnum (empty)