Coverage for cuda/core/typing.py: 0.00%
83 statements
« prev ^ index » next coverage.py v7.16.2, created at 2026-10-16 01:23 +0000
1# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
2#
3# SPDX-License-Identifier: Apache-2.0
5"""Public type aliases, protocols, and enumerations used in cuda.core API signatures."""
7from enum import StrEnum
8from typing import Literal as _Literal
9from typing import TypeAlias as _TypeAlias
11from cuda.core._context import DeviceResourcesType
12from cuda.core._stream import IsStreamType
13from cuda.core._utils.cuda_utils import driver
15__all__ = [
16 "AddressModeType",
17 "ArrayFormatType",
18 "CompilerBackendType",
19 "DevicePointerType",
20 "DeviceResourcesType",
21 "FilterModeType",
22 "GraphConditionalType",
23 "GraphMemoryType",
24 "IsStreamType",
25 "ManagedMemoryLocationType",
26 "ObjectCodeFormatType",
27 "PCHStatusType",
28 "ProcessStateType",
29 "ReadModeType",
30 "SourceCodeType",
31 "VirtualMemoryAccessType",
32 "VirtualMemoryAllocationType",
33 "VirtualMemoryGranularityType",
34 "VirtualMemoryHandleType",
35 "VirtualMemoryLocationType",
36 "WorkqueueSharingScopeType",
37]
40# A type union of :obj:`~driver.CUdeviceptr`, `int` and `None` for hinting
41# :attr:`Buffer.handle`.
42DevicePointerType: _TypeAlias = driver.CUdeviceptr | int | None
45ProcessStateType = _Literal["running", "locked", "checkpointed", "failed"]
48class SourceCodeType(StrEnum):
49 """Source language passed to :class:`~cuda.core.Program`.
51 * ``CXX`` — CUDA C++ source.
52 * ``PTX`` — PTX assembly text.
53 * ``NVVM`` — NVVM IR (LLVM bitcode).
54 """
56 CXX = "c++"
57 PTX = "ptx"
58 NVVM = "nvvm"
61class ObjectCodeFormatType(StrEnum):
62 """Output format for :meth:`~cuda.core.Program.compile`, :meth:`~cuda.core.Linker.link`, and :meth:`~cuda.core.Program.as_bytes`.
64 * ``PTX`` — PTX assembly text.
65 * ``CUBIN`` — device-native CUDA binary.
66 * ``LTOIR`` — LTO (link-time optimization) IR for later linking.
67 * ``FATBIN`` — fat binary bundling multiple device images.
68 * ``OBJECT`` — host object containing device code.
69 * ``LIBRARY`` — device code library.
70 """
72 PTX = "ptx"
73 CUBIN = "cubin"
74 LTOIR = "ltoir"
75 FATBIN = "fatbin"
76 OBJECT = "object"
77 LIBRARY = "library"
80class CompilerBackendType(StrEnum):
81 """Compiler backend inferred from the program's code type and exposed on :attr:`~cuda.core.Program.backend`.
83 * ``NVRTC`` — NVIDIA Runtime Compilation.
84 * ``NVVM`` — NVVM LLVM backend.
85 * ``NVJITLINK`` — nvJitLink device-side linker.
86 * ``DRIVER`` — CUDA driver PTX JIT compiler.
87 """
89 NVRTC = "NVRTC"
90 NVVM = "NVVM"
91 NVJITLINK = "nvJitLink"
92 DRIVER = "driver"
95class PCHStatusType(StrEnum):
96 """Precompiled-header (PCH) outcome reported by :meth:`~cuda.core.Program.compile`.
98 * ``CREATED`` — PCH was successfully written.
99 * ``NOT_ATTEMPTED`` — PCH creation was skipped (backend does not support it or the option was not requested).
100 * ``FAILED`` — PCH creation was attempted but failed.
101 """
103 CREATED = "created"
104 NOT_ATTEMPTED = "not_attempted"
105 FAILED = "failed"
108class GraphConditionalType(StrEnum):
109 """Conditional node flavor for :class:`~cuda.core.graph.GraphBuilder`.
111 * ``IF`` — body graph executes at most once based on a condition.
112 * ``WHILE`` — body graph loops while the condition is true.
113 * ``SWITCH`` — selects one child graph by an integer index.
114 """
116 IF = "if"
117 WHILE = "while"
118 SWITCH = "switch"
121class GraphMemoryType(StrEnum):
122 """Memory space for a graph memory-allocation or free node.
124 * ``DEVICE`` — GPU device memory.
125 * ``HOST`` — pinned host memory.
126 * ``MANAGED`` — CUDA managed (unified) memory.
127 """
129 DEVICE = "device"
130 HOST = "host"
131 MANAGED = "managed"
134class ManagedMemoryLocationType(StrEnum):
135 """Destination type for managed-memory prefetch and advise operations.
137 * ``DEVICE`` — target a GPU device.
138 * ``HOST`` — target the CPU host (any NUMA node).
139 * ``HOST_NUMA`` — target a specific host NUMA node.
140 """
142 DEVICE = "device"
143 HOST = "host"
144 HOST_NUMA = "host_numa"
147class VirtualMemoryHandleType(StrEnum):
148 """OS handle type for exporting virtual memory allocations across processes.
150 * ``POSIX_FD`` — POSIX file descriptor (Linux).
151 * ``WIN32_KMT`` — Win32 kernel-mode handle (Windows).
152 * ``FABRIC`` — NVLink/NVSwitch fabric handle for multi-node topologies.
153 """
155 POSIX_FD = "posix_fd"
156 WIN32_KMT = "win32_kmt"
157 FABRIC = "fabric"
160class VirtualMemoryLocationType(StrEnum):
161 """Physical backing location for a virtual memory allocation.
163 * ``DEVICE`` — GPU device memory.
164 * ``HOST`` — pinned host memory.
165 * ``HOST_NUMA`` — host memory pinned to a specific NUMA node.
166 * ``HOST_NUMA_CURRENT`` — host memory on the calling thread's NUMA node.
167 """
169 DEVICE = "device"
170 HOST = "host"
171 HOST_NUMA = "host_numa"
172 HOST_NUMA_CURRENT = "host_numa_current"
175class VirtualMemoryGranularityType(StrEnum):
176 """Granularity query type for virtual memory allocations.
178 * ``MINIMUM`` — smallest allocation size supported by the device.
179 * ``RECOMMENDED`` — granularity that yields best performance on the device.
180 """
182 MINIMUM = "minimum"
183 RECOMMENDED = "recommended"
186class VirtualMemoryAccessType(StrEnum):
187 """Access permissions for a virtual memory mapping.
189 * ``READ_WRITE`` — both read and write access.
190 * ``READ`` — read-only access.
191 """
193 READ_WRITE = "rw"
194 READ = "r"
197class VirtualMemoryAllocationType(StrEnum):
198 """Physical memory type for a virtual memory backing allocation.
200 * ``PINNED`` — pinned/non-migratable physical allocation (placement via :class:`VirtualMemoryLocationType`).
201 * ``MANAGED`` — CUDA managed (unified) memory (CUDA 13+ only).
202 """
204 PINNED = "pinned"
205 MANAGED = "managed"
208class ArrayFormatType(StrEnum):
209 """Element format for an :class:`~cuda.core.texture.OpaqueArray` allocation.
211 Corresponds to ``CUarray_format`` from the CUDA driver API. Each value maps
212 1:1 to a NumPy dtype; the enum is retained as an explicit escape hatch.
214 * ``UINT8`` / ``UINT16`` / ``UINT32`` — unsigned integer elements.
215 * ``INT8`` / ``INT16`` / ``INT32`` — signed integer elements.
216 * ``FLOAT16`` / ``FLOAT32`` — half- and single-precision float elements.
218 .. versionadded:: 1.1.0
219 """
221 UINT8 = "uint8"
222 UINT16 = "uint16"
223 UINT32 = "uint32"
224 INT8 = "int8"
225 INT16 = "int16"
226 INT32 = "int32"
227 FLOAT16 = "float16"
228 FLOAT32 = "float32"
231class AddressModeType(StrEnum):
232 """Boundary behavior for out-of-range texture coordinates.
234 Corresponds to ``CUaddress_mode`` from the CUDA driver API.
236 * ``WRAP`` — wrap coordinates around (tiling).
237 * ``CLAMP`` — clamp to the edge texel.
238 * ``MIRROR`` — reflect coordinates at the boundary.
239 * ``BORDER`` — return the configured border color.
241 .. versionadded:: 1.1.0
242 """
244 WRAP = "wrap"
245 CLAMP = "clamp"
246 MIRROR = "mirror"
247 BORDER = "border"
250class FilterModeType(StrEnum):
251 """Texel sampling mode for a :class:`~cuda.core.texture.TextureObject`.
253 Corresponds to ``CUfilter_mode`` from the CUDA driver API.
255 * ``POINT`` — nearest-texel sampling.
256 * ``LINEAR`` — (bi/tri)linear interpolation.
258 .. versionadded:: 1.1.0
259 """
261 POINT = "point"
262 LINEAR = "linear"
265class ReadModeType(StrEnum):
266 """How sampled values are returned to the kernel.
268 * ``ELEMENT_TYPE`` — return the raw element value (integer formats stay
269 integer, float stays float).
270 * ``NORMALIZED_FLOAT`` — integer formats are promoted to a normalized
271 ``float`` in ``[0, 1]`` (unsigned) or ``[-1, 1]`` (signed). Float
272 formats are unaffected.
274 .. versionadded:: 1.1.0
275 """
277 ELEMENT_TYPE = "element_type"
278 NORMALIZED_FLOAT = "normalized_float"
281class WorkqueueSharingScopeType(StrEnum):
282 """Sharing scope for :class:`~cuda.core.WorkqueueResource`.
284 * ``DEVICE_CTX`` — use all shared workqueue resources across all
285 contexts (default driver behavior).
286 * ``GREEN_CTX_BALANCED`` — when possible, use non-overlapping
287 workqueue resources with other balanced green contexts.
289 .. versionadded:: 1.1.0
290 """
292 DEVICE_CTX = "device_ctx"
293 GREEN_CTX_BALANCED = "green_ctx_balanced"
296del StrEnum