Merge branch 'main' into move_enum_explanations

Author: rwgk

conftest.py

@@ -1,13 +1,31 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+
 import os
 
 import pytest
 
+from cuda.pathfinder import get_cuda_path_or_home
+
+
+# Please keep in sync with the copy in cuda_core/tests/conftest.py.
+def _cuda_headers_available() -> bool:
+    """Return True if CUDA headers are available, False if no CUDA path is set.
+
+    Raises AssertionError if a CUDA path is set but has no include/ subdirectory.
+    """
+    cuda_path = get_cuda_path_or_home()
+    if cuda_path is None:
+        return False
+    assert os.path.isdir(os.path.join(cuda_path, "include")), (
+        f"CUDA path {cuda_path} does not contain an 'include' subdirectory"
+    )
+    return True
+
 
 def pytest_collection_modifyitems(config, items):  # noqa: ARG001
-    cuda_home = os.environ.get("CUDA_HOME")
+    have_headers = _cuda_headers_available()
     for item in items:
         nodeid = item.nodeid.replace("\\", "/")
 
@@ -31,6 +49,10 @@ def pytest_collection_modifyitems(config, items):  # noqa: ARG001
         ):
             item.add_marker(pytest.mark.cython)
 
-            # Gate core cython tests on CUDA_HOME
-            if "core" in item.keywords and not cuda_home:
-                item.add_marker(pytest.mark.skip(reason="CUDA_HOME not set; skipping core cython tests"))
+            # Gate core cython tests on CUDA_PATH
+            if "core" in item.keywords and not have_headers:
+                item.add_marker(
+                    pytest.mark.skip(
+                        reason="Environment variable CUDA_PATH or CUDA_HOME is not set: skipping core cython tests"
+                    )
+                )

cuda_bindings/README.md

@@ -33,7 +33,7 @@ To run these tests:
 
 Cython tests are located in `tests/cython` and need to be built. These builds have the same CUDA Toolkit header requirements as [Installing from Source](https://nvidia.github.io/cuda-python/cuda-bindings/latest/install.html#requirements) where the major.minor version must match `cuda.bindings`. To build them:
 
-1. Setup environment variable `CUDA_HOME` with the path to the CUDA Toolkit installation.
+1. Setup environment variable `CUDA_PATH` (or `CUDA_HOME`) with the path to the CUDA Toolkit installation. Note: If both are set, `CUDA_PATH` takes precedence.
 2. Run `build_tests` script located in `test/cython` appropriate to your platform. This will both cythonize the tests and build them.
 
 To run these tests:

cuda_bindings/build_hooks.py

@@ -34,13 +34,16 @@
 
 
 @functools.cache
-def _get_cuda_paths() -> list[str]:
-    CUDA_HOME = os.environ.get("CUDA_HOME", os.environ.get("CUDA_PATH", None))
-    if not CUDA_HOME:
-        raise RuntimeError("Environment variable CUDA_HOME or CUDA_PATH is not set")
-    CUDA_HOME = CUDA_HOME.split(os.pathsep)
-    print("CUDA paths:", CUDA_HOME)
-    return CUDA_HOME
+def _get_cuda_path() -> str:
+    # Not using cuda.pathfinder.get_cuda_path_or_home() here because this
+    # build backend runs in an isolated venv where the cuda namespace package
+    # from backend-path shadows the installed cuda-pathfinder. See #1803 for
+    # a workaround to apply after cuda-pathfinder >= 1.5 is released.
+    cuda_path = os.environ.get("CUDA_PATH", os.environ.get("CUDA_HOME"))
+    if not cuda_path:
+        raise RuntimeError("Environment variable CUDA_PATH or CUDA_HOME is not set")
+    print("CUDA path:", cuda_path)
+    return cuda_path
 
 
 # -----------------------------------------------------------------------
@@ -133,8 +136,8 @@ def _fetch_header_paths(required_headers, include_path_list):
     if missing_headers:
         error_message = "Couldn't find required headers: "
         error_message += ", ".join(missing_headers)
-        cuda_paths = _get_cuda_paths()
-        raise RuntimeError(f'{error_message}\nIs CUDA_HOME setup correctly? (CUDA_HOME="{cuda_paths}")')
+        cuda_path = _get_cuda_path()
+        raise RuntimeError(f'{error_message}\nIs CUDA_PATH setup correctly? (CUDA_PATH="{cuda_path}")')
 
     return header_dict
 
@@ -291,7 +294,7 @@ def _build_cuda_bindings(strip=False):
 
     global _extensions
 
-    cuda_paths = _get_cuda_paths()
+    cuda_path = _get_cuda_path()
 
     if os.environ.get("PARALLEL_LEVEL") is not None:
         warn(
@@ -307,7 +310,7 @@ def _build_cuda_bindings(strip=False):
     compile_for_coverage = bool(int(os.environ.get("CUDA_PYTHON_COVERAGE", "0")))
 
     # Parse CUDA headers
-    include_path_list = [os.path.join(path, "include") for path in cuda_paths]
+    include_path_list = [os.path.join(cuda_path, "include")]
     header_dict = _fetch_header_paths(_REQUIRED_HEADERS, include_path_list)
     found_types, found_functions, found_values, found_struct, struct_list = _parse_headers(
         header_dict, include_path_list, parser_caching
@@ -347,7 +350,7 @@ def _build_cuda_bindings(strip=False):
     ] + include_path_list
     library_dirs = [sysconfig.get_path("platlib"), os.path.join(os.sys.prefix, "lib")]
     cudalib_subdirs = [r"lib\x64"] if sys.platform == "win32" else ["lib64", "lib"]
-    library_dirs.extend(os.path.join(prefix, subdir) for prefix in cuda_paths for subdir in cudalib_subdirs)
+    library_dirs.extend(os.path.join(cuda_path, subdir) for subdir in cudalib_subdirs)
 
     extra_compile_args = []
     extra_link_args = []

cuda_bindings/cuda/bindings/runtime.pyx.in

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2021-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 # SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
-# This code was automatically generated with version 13.2.0, generator version 8797618. Do not modify it directly.
+# This code was automatically generated with version 13.2.0, generator version 0.3.1.dev1422+gf4812259e.d20260318. Do not modify it directly.
 from typing import Any, Optional
 import cython
 import ctypes
@@ -1858,7 +1858,9 @@ class cudaLogLevel(_FastEnum):
 {{if 'cudaDataType_t' in found_types}}
 
 class cudaDataType(_FastEnum):
-    """"""
+    """
+
+    """
     {{if 'CUDA_R_32F' in found_values}}
     CUDA_R_32F = cyruntime.cudaDataType_t.CUDA_R_32F{{endif}}
     {{if 'CUDA_R_64F' in found_values}}
@@ -1934,43 +1936,98 @@ class cudaDataType(_FastEnum):
 {{if 'cudaEmulationStrategy_t' in found_types}}
 
 class cudaEmulationStrategy(_FastEnum):
-    """"""
+    """
+    Enum for specifying how to leverage floating-point emulation
+    algorithms
+    """
     {{if 'CUDA_EMULATION_STRATEGY_DEFAULT' in found_values}}
-    CUDA_EMULATION_STRATEGY_DEFAULT = cyruntime.cudaEmulationStrategy_t.CUDA_EMULATION_STRATEGY_DEFAULT{{endif}}
+
+    CUDA_EMULATION_STRATEGY_DEFAULT = (
+        cyruntime.cudaEmulationStrategy_t.CUDA_EMULATION_STRATEGY_DEFAULT,
+        'The default emulation strategy. For emulated computations, this is\n'
+        'equivalent to CUDA_EMULATION_STRATEGY_PERFORMANT, unless a library\n'
+        'dependent environment variable is set\n'
+    ){{endif}}
     {{if 'CUDA_EMULATION_STRATEGY_PERFORMANT' in found_values}}
-    CUDA_EMULATION_STRATEGY_PERFORMANT = cyruntime.cudaEmulationStrategy_t.CUDA_EMULATION_STRATEGY_PERFORMANT{{endif}}
+
+    CUDA_EMULATION_STRATEGY_PERFORMANT = (
+        cyruntime.cudaEmulationStrategy_t.CUDA_EMULATION_STRATEGY_PERFORMANT,
+        'An emulation strategy which configures libraries to use emulation when it\n'
+        'provides a performance benefit\n'
+    ){{endif}}
     {{if 'CUDA_EMULATION_STRATEGY_EAGER' in found_values}}
-    CUDA_EMULATION_STRATEGY_EAGER = cyruntime.cudaEmulationStrategy_t.CUDA_EMULATION_STRATEGY_EAGER{{endif}}
+
+    CUDA_EMULATION_STRATEGY_EAGER = (
+        cyruntime.cudaEmulationStrategy_t.CUDA_EMULATION_STRATEGY_EAGER,
+        'An emulation strategy which configures libraries to use emulation whenever\n'
+        'possible\n'
+    ){{endif}}
 
 {{endif}}
 {{if 'cudaEmulationMantissaControl_t' in found_types}}
 
 class cudaEmulationMantissaControl(_FastEnum):
-    """"""
+    """
+    Enum to configure the mantissa related parameters for floating-
+    point emulation algorithms
+    """
     {{if 'CUDA_EMULATION_MANTISSA_CONTROL_DYNAMIC' in found_values}}
-    CUDA_EMULATION_MANTISSA_CONTROL_DYNAMIC = cyruntime.cudaEmulationMantissaControl_t.CUDA_EMULATION_MANTISSA_CONTROL_DYNAMIC{{endif}}
+
+    CUDA_EMULATION_MANTISSA_CONTROL_DYNAMIC = (
+        cyruntime.cudaEmulationMantissaControl_t.CUDA_EMULATION_MANTISSA_CONTROL_DYNAMIC,
+        'The number of retained mantissa bits are computed at runtime to ensure the\n'
+        'same or better accuracy than the floating point representation being\n'
+        'emulated\n'
+    ){{endif}}
     {{if 'CUDA_EMULATION_MANTISSA_CONTROL_FIXED' in found_values}}
-    CUDA_EMULATION_MANTISSA_CONTROL_FIXED = cyruntime.cudaEmulationMantissaControl_t.CUDA_EMULATION_MANTISSA_CONTROL_FIXED{{endif}}
+
+    CUDA_EMULATION_MANTISSA_CONTROL_FIXED = (
+        cyruntime.cudaEmulationMantissaControl_t.CUDA_EMULATION_MANTISSA_CONTROL_FIXED,
+        'The number of retained mantissa bits are known at runtime\n'
+    ){{endif}}
 
 {{endif}}
 {{if 'cudaEmulationSpecialValuesSupport_t' in found_types}}
 
 class cudaEmulationSpecialValuesSupport(_FastEnum):
-    """"""
+    """
+    Enum to configure how special floating-point values will be handled
+    by emulation algorithms
+    """
     {{if 'CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NONE' in found_values}}
-    CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NONE = cyruntime.cudaEmulationSpecialValuesSupport_t.CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NONE{{endif}}
+
+    CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NONE = (
+        cyruntime.cudaEmulationSpecialValuesSupport_t.CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NONE,
+        'There are no requirements for emulation algorithms to support special\n'
+        'values\n'
+    ){{endif}}
     {{if 'CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_INFINITY' in found_values}}
-    CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_INFINITY = cyruntime.cudaEmulationSpecialValuesSupport_t.CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_INFINITY{{endif}}
+
+    CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_INFINITY = (
+        cyruntime.cudaEmulationSpecialValuesSupport_t.CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_INFINITY,
+        'Require emulation algorithms to handle signed infinity inputs and outputs\n'
+    ){{endif}}
     {{if 'CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NAN' in found_values}}
-    CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NAN = cyruntime.cudaEmulationSpecialValuesSupport_t.CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NAN{{endif}}
+
+    CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NAN = (
+        cyruntime.cudaEmulationSpecialValuesSupport_t.CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_NAN,
+        'Require emulation algorithms to handle NaN inputs and outputs\n'
+    ){{endif}}
     {{if 'CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_DEFAULT' in found_values}}
-    CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_DEFAULT = cyruntime.cudaEmulationSpecialValuesSupport_t.CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_DEFAULT{{endif}}
+
+    CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_DEFAULT = (
+        cyruntime.cudaEmulationSpecialValuesSupport_t.CUDA_EMULATION_SPECIAL_VALUES_SUPPORT_DEFAULT,
+        'The default special value support mask which contains support for signed\n'
+        'infinities and NaN values\n'
+    ){{endif}}
 
 {{endif}}
 {{if 'libraryPropertyType_t' in found_types}}
 
 class libraryPropertyType(_FastEnum):
-    """"""
+    """
+
+    """
     {{if 'MAJOR_VERSION' in found_values}}
     MAJOR_VERSION = cyruntime.libraryPropertyType_t.MAJOR_VERSION{{endif}}
     {{if 'MINOR_VERSION' in found_values}}
@@ -6394,7 +6451,9 @@ class cudaTextureReadMode(_FastEnum):
 {{if 'cudaRoundMode' in found_types}}
 
 class cudaRoundMode(_FastEnum):
-    """"""
+    """
+
+    """
     {{if 'cudaRoundNearest' in found_values}}
     cudaRoundNearest = cyruntime.cudaRoundMode.cudaRoundNearest{{endif}}
     {{if 'cudaRoundZero' in found_values}}

cuda_bindings/docs/source/environment_variables.rst

@@ -15,7 +15,14 @@ Runtime Environment Variables
 Build-Time Environment Variables
 --------------------------------
 
-- ``CUDA_HOME`` or ``CUDA_PATH``: Specifies the location of the CUDA Toolkit.
+- ``CUDA_PATH`` or ``CUDA_HOME``: Specifies the location of the CUDA Toolkit. If both are set, ``CUDA_PATH`` takes precedence.
+
+  .. note::
+     The ``CUDA_PATH`` > ``CUDA_HOME`` priority is determined by ``cuda-pathfinder``.
+     Earlier versions of ``cuda-pathfinder`` (before 1.5.0) used the opposite order
+     (``CUDA_HOME`` > ``CUDA_PATH``). See the
+     `cuda-pathfinder 1.5.0 release notes <https://nvidia.github.io/cuda-python/cuda-pathfinder/latest/release/1.5.0-notes.html>`_
+     for details and migration guidance.
 
 - ``CUDA_PYTHON_PARSER_CACHING`` : bool, toggles the caching of parsed header files during the cuda-bindings build process. If caching is enabled (``CUDA_PYTHON_PARSER_CACHING`` is True), the cache path is set to ./cache_<library_name>, where <library_name> is derived from the cuda toolkit libraries used to build cuda-bindings.
 

cuda_bindings/docs/source/install.rst

@@ -87,11 +87,11 @@ Requirements
 
 [^2]: The CUDA Runtime static library (``libcudart_static.a`` on Linux, ``cudart_static.lib`` on Windows) is part of the CUDA Toolkit. If using conda packages, it is contained in the ``cuda-cudart-static`` package.
 
-Source builds require that the provided CUDA headers are of the same major.minor version as the ``cuda.bindings`` you're trying to build. Despite this requirement, note that the minor version compatibility is still maintained. Use the ``CUDA_HOME`` (or ``CUDA_PATH``) environment variable to specify the location of your headers. For example, if your headers are located in ``/usr/local/cuda/include``, then you should set ``CUDA_HOME`` with:
+Source builds require that the provided CUDA headers are of the same major.minor version as the ``cuda.bindings`` you're trying to build. Despite this requirement, note that the minor version compatibility is still maintained. Use the ``CUDA_PATH`` (or ``CUDA_HOME``) environment variable to specify the location of your headers. If both are set, ``CUDA_PATH`` takes precedence. For example, if your headers are located in ``/usr/local/cuda/include``, then you should set ``CUDA_PATH`` with:
 
 .. code-block:: console
 
-   $ export CUDA_HOME=/usr/local/cuda
+   $ export CUDA_PATH=/usr/local/cuda
 
 See `Environment Variables <environment_variables.rst>`_ for a description of other build-time environment variables.
 

cuda_bindings/docs/source/module/driver.rst

@@ -1,10 +1,28 @@
-.. SPDX-FileCopyrightText: Copyright (c) 2021-2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+.. SPDX-FileCopyrightText: Copyright (c) 2021-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
 .. SPDX-License-Identifier: LicenseRef-NVIDIA-SOFTWARE-LICENSE
 
 ------
 driver
 ------
 
+Profiler Control
+----------------
+
+This section describes the profiler control functions of the low-level CUDA driver application programming interface.
+
+.. autofunction:: cuda.bindings.driver.cuProfilerStart
+.. autofunction:: cuda.bindings.driver.cuProfilerStop
+
+VDPAU Interoperability
+----------------------
+
+This section describes the VDPAU interoperability functions of the low-level CUDA driver application programming interface.
+
+.. autofunction:: cuda.bindings.driver.cuVDPAUGetDevice
+.. autofunction:: cuda.bindings.driver.cuVDPAUCtxCreate
+.. autofunction:: cuda.bindings.driver.cuGraphicsVDPAURegisterVideoSurface
+.. autofunction:: cuda.bindings.driver.cuGraphicsVDPAURegisterOutputSurface
+
 Data types used by CUDA driver
 ------------------------------
 
@@ -7752,24 +7770,6 @@ Checkpoint and restore capabilities are currently restricted to Linux.
 .. autofunction:: cuda.bindings.driver.cuCheckpointProcessRestore
 .. autofunction:: cuda.bindings.driver.cuCheckpointProcessUnlock
 
-EGL Interoperability
---------------------
-
-This section describes the EGL interoperability functions of the low-level CUDA driver application programming interface.
-
-.. autofunction:: cuda.bindings.driver.cuGraphicsEGLRegisterImage
-.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerConnect
-.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerConnectWithFlags
-.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerDisconnect
-.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerAcquireFrame
-.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerReleaseFrame
-.. autofunction:: cuda.bindings.driver.cuEGLStreamProducerConnect
-.. autofunction:: cuda.bindings.driver.cuEGLStreamProducerDisconnect
-.. autofunction:: cuda.bindings.driver.cuEGLStreamProducerPresentFrame
-.. autofunction:: cuda.bindings.driver.cuEGLStreamProducerReturnFrame
-.. autofunction:: cuda.bindings.driver.cuGraphicsResourceGetMappedEglFrame
-.. autofunction:: cuda.bindings.driver.cuEventCreateFromEGLSync
-
 OpenGL Interoperability
 -----------------------
 
@@ -7798,20 +7798,20 @@ This section describes the OpenGL interoperability functions of the low-level CU
 .. autofunction:: cuda.bindings.driver.cuGraphicsGLRegisterImage
 .. autofunction:: cuda.bindings.driver.cuGLGetDevices
 
-Profiler Control
-----------------
-
-This section describes the profiler control functions of the low-level CUDA driver application programming interface.
-
-.. autofunction:: cuda.bindings.driver.cuProfilerStart
-.. autofunction:: cuda.bindings.driver.cuProfilerStop
-
-VDPAU Interoperability
-----------------------
+EGL Interoperability
+--------------------
 
-This section describes the VDPAU interoperability functions of the low-level CUDA driver application programming interface.
+This section describes the EGL interoperability functions of the low-level CUDA driver application programming interface.
 
-.. autofunction:: cuda.bindings.driver.cuVDPAUGetDevice
-.. autofunction:: cuda.bindings.driver.cuVDPAUCtxCreate
-.. autofunction:: cuda.bindings.driver.cuGraphicsVDPAURegisterVideoSurface
-.. autofunction:: cuda.bindings.driver.cuGraphicsVDPAURegisterOutputSurface
+.. autofunction:: cuda.bindings.driver.cuGraphicsEGLRegisterImage
+.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerConnect
+.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerConnectWithFlags
+.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerDisconnect
+.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerAcquireFrame
+.. autofunction:: cuda.bindings.driver.cuEGLStreamConsumerReleaseFrame
+.. autofunction:: cuda.bindings.driver.cuEGLStreamProducerConnect
+.. autofunction:: cuda.bindings.driver.cuEGLStreamProducerDisconnect
+.. autofunction:: cuda.bindings.driver.cuEGLStreamProducerPresentFrame
+.. autofunction:: cuda.bindings.driver.cuEGLStreamProducerReturnFrame
+.. autofunction:: cuda.bindings.driver.cuGraphicsResourceGetMappedEglFrame
+.. autofunction:: cuda.bindings.driver.cuEventCreateFromEGLSync