Merge branch 'main' into test/vuln-malware-onboarding

Author: gmanal

.github/workflows/coverage.yml

@@ -250,6 +250,14 @@ jobs:
       - name: Set up MSVC
         uses: step-security/msvc-dev-cmd@22c98154b708dbd743e6f27a933cf6ceba3305c4  # v1.13.1
 
+      - name: Raise the interpreter's stack reserve to 8 MiB
+        # Importing the coverage-built cuda.bindings.driver overflows the
+        # 2,000,000-byte main-thread stack of python-build-standalone (#3330).
+        run: |
+          base_py="$(.venv/Scripts/python -c 'import sys; print(sys._base_executable)')"
+          editbin -nologo -stack:8388608 "$base_py"
+          dumpbin -nologo -headers "$base_py" | grep -i "size of stack reserve"
+
       - name: Set up mini CTK
         uses: ./.github/actions/fetch_ctk
         continue-on-error: false

CONTRIBUTING.md

@@ -37,21 +37,26 @@ reproducers, documentation improvements, and code changes are welcome.
 
 ## Coordinate before implementing
 
-Review capacity is limited. If you are contributing from outside NVIDIA:
+Our review and CI capacities are limited. If you are contributing from outside NVIDIA:
 
-- **Existing issue:** comment and wait for a maintainer to assign it to you or
+- **Existing issues:** comment and wait for a maintainer to assign it to you or
   explicitly ask you to implement it. Check existing assignments and requests
   to take the issue.
-- **New features, design changes, or CI/release infrastructure:** open an issue
-  and agree on scope and validation before implementing.
-- **Small standalone bug or documentation fixes without an existing issue:**
-  a direct PR is welcome. Explain the problem and how you checked the fix.
+- **New features, bug/documentation fixes, RFCs, or code updates/enhancements:** open an
+  issue, agree on scope and validation, and wait for the assignment before implementing.
 
-NVIDIA contributors may use normal team planning and self-assignment.
+For obvious issues, opening a one-liner issue for tracking and assignment purposes is
+completely fine.
+
+For bug reports, please include a reproducer with a clear description for the expected
+versus observed behavior. Also include the CUDA driver version and the Python environment
+information (ex: `pip list`, `conda list`, ..., depending on how the environment was
+created).
 
-Feel free to report a bug or send reproducers, measurements, and suggestions
-without an assignment. Include relevant versions and expected versus observed
-behavior in bug reports.
+Please do not send unsolicited (i.e. without prior discussion and assignment) PRs, which
+could be closed without notice subject to the team's triage.
+
+NVIDIA contributors may use normal team planning and self-assignment.
 
 Keep changes focused, understand the complete diff, and report which checks
 ran and any validation gaps.

ci/test-matrix.yml

@@ -100,12 +100,10 @@ linux:
     - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '13.4.2', LOCAL_CTK: '0', GPU: 'rtx4090',    GPU_COUNT: '1', DRIVER: 'latest', FLAVOR: 'wsl' }
   nightly:
     # nightly-pytorch
-    - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '12.6.3', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.12.1', TORCH_CUDA: 'cu126' } }
-    - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '13.0.2', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.12.1', TORCH_CUDA: 'cu130' } }
+    - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '13.2.2', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.15.0', TORCH_CUDA: 'cu132' } }
     - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '12.6.3', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.9.1',  TORCH_CUDA: 'cu126' } }
     - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '13.0.2', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.9.1',  TORCH_CUDA: 'cu130' } }
-    - { ARCH: 'arm64', PY_VER: '3.12',  CUDA_VER: '12.6.3', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.12.1', TORCH_CUDA: 'cu126' } }
-    - { ARCH: 'arm64', PY_VER: '3.12',  CUDA_VER: '13.0.2', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.12.1', TORCH_CUDA: 'cu130' } }
+    - { ARCH: 'arm64', PY_VER: '3.12',  CUDA_VER: '13.2.2', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.15.0', TORCH_CUDA: 'cu132' } }
     - { ARCH: 'arm64', PY_VER: '3.12',  CUDA_VER: '12.6.3', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.9.1',  TORCH_CUDA: 'cu126' } }
     - { ARCH: 'arm64', PY_VER: '3.12',  CUDA_VER: '13.0.2', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',     ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.9.1',  TORCH_CUDA: 'cu130' } }
     # nightly-numba-cuda
@@ -153,8 +151,7 @@ windows:
     - { ARCH: 'amd64', PY_VER: '3.14',  CUDA_VER: '13.4.2', LOCAL_CTK: '0', GPU: 'h100',       GPU_COUNT: '2', DRIVER: 'latest',  DRIVER_MODE: 'MCDM' }
   nightly:
     # nightly-pytorch
-    - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '12.6.3', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',  DRIVER_MODE: 'TCC',  ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.12.1', TORCH_CUDA: 'cu126' } }
-    - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '13.0.2', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',  DRIVER_MODE: 'TCC',  ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.12.1', TORCH_CUDA: 'cu130' } }
+    - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '13.2.2', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',  DRIVER_MODE: 'TCC',  ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.15.0', TORCH_CUDA: 'cu132' } }
     - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '12.6.3', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',  DRIVER_MODE: 'TCC',  ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.9.1',  TORCH_CUDA: 'cu126' } }
     - { ARCH: 'amd64', PY_VER: '3.12',  CUDA_VER: '13.0.2', LOCAL_CTK: '0', GPU: 'l4',         GPU_COUNT: '1', DRIVER: 'latest',  DRIVER_MODE: 'TCC',  ENV: { MODE: 'nightly-pytorch', TORCH_VER: '2.9.1',  TORCH_CUDA: 'cu130' } }
     # nightly-numba-cuda

cuda_bindings_12/pyproject.toml

@@ -104,6 +104,9 @@ ignore = [
 exclude = ["cuda/bindings/_version.py"]
 
 [tool.ruff.lint.per-file-ignores]
+# This config replaces ../ruff.toml for this tree, so it repeats that file's
+# S101 policy: asserts are rejected only in cuda_core/cuda/core.
+"**" = ["S101"]
 "setup.py" = ["F401"]
 "__init__.py" = ["F401"]
 "site-packages/_cuda_bindings_redirector.py" = ["F401"]

cuda_bindings_13/cuda/bindings/cudla.pyx

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 # This code was automatically generated across versions from 1.5.0 to 13.4.1. Do not modify it directly.
-# CYTHON-BINDINGS-GENERATED-DO-NOT-MODIFY-THIS-FILE: format=1; content-sha256=50159aaec5737fc94f227c703c6abe29874cd8022b8f545b46498e9c5862c4e6
+# CYTHON-BINDINGS-GENERATED-DO-NOT-MODIFY-THIS-FILE: format=1; content-sha256=92945a025bf01ceb29f21539fb32be8db41c402bec2606a8d92b79e869a0c0ed
 
 
 # <<<< PREAMBLE CONTENT >>>>
@@ -1597,30 +1597,54 @@ class Status(_cyb_IntEnum):
     """
     See `cudlaStatus`.
     """
-    Success = cudlaSuccess
-    ErrorInvalidParam = cudlaErrorInvalidParam
-    ErrorOutOfResources = cudlaErrorOutOfResources
-    ErrorCreationFailed = cudlaErrorCreationFailed
-    ErrorInvalidAddress = cudlaErrorInvalidAddress
-    ErrorOs = cudlaErrorOs
-    ErrorCuda = cudlaErrorCuda
-    ErrorUmd = cudlaErrorUmd
-    ErrorInvalidDevice = cudlaErrorInvalidDevice
-    ErrorInvalidAttribute = cudlaErrorInvalidAttribute
-    ErrorIncompatibleDlaSWVersion = cudlaErrorIncompatibleDlaSWVersion
-    ErrorMemoryRegistered = cudlaErrorMemoryRegistered
-    ErrorInvalidModule = cudlaErrorInvalidModule
-    ErrorUnsupportedOperation = cudlaErrorUnsupportedOperation
-    ErrorNvSci = cudlaErrorNvSci
-    ErrorDriverNotFound = cudlaErrorDriverNotFound
-    ErrorDlaErrInvalidInput = cudlaErrorDlaErrInvalidInput
-    ErrorDlaErrInvalidPreAction = cudlaErrorDlaErrInvalidPreAction
-    ErrorDlaErrNoMem = cudlaErrorDlaErrNoMem
-    ErrorDlaErrProcessorBusy = cudlaErrorDlaErrProcessorBusy
-    ErrorDlaErrTaskStatusMismatch = cudlaErrorDlaErrTaskStatusMismatch
-    ErrorDlaErrEngineTimeout = cudlaErrorDlaErrEngineTimeout
-    ErrorDlaErrDataMismatch = cudlaErrorDlaErrDataMismatch
-    ErrorUnknown = cudlaErrorUnknown
+    SUCCESS = cudlaSuccess
+    Success = SUCCESS  # backward-compat alias
+    ERROR_INVALID_PARAM = cudlaErrorInvalidParam
+    ErrorInvalidParam = ERROR_INVALID_PARAM  # backward-compat alias
+    ERROR_OUT_OF_RESOURCES = cudlaErrorOutOfResources
+    ErrorOutOfResources = ERROR_OUT_OF_RESOURCES  # backward-compat alias
+    ERROR_CREATION_FAILED = cudlaErrorCreationFailed
+    ErrorCreationFailed = ERROR_CREATION_FAILED  # backward-compat alias
+    ERROR_INVALID_ADDRESS = cudlaErrorInvalidAddress
+    ErrorInvalidAddress = ERROR_INVALID_ADDRESS  # backward-compat alias
+    ERROR_OS = cudlaErrorOs
+    ErrorOs = ERROR_OS  # backward-compat alias
+    ERROR_CUDA = cudlaErrorCuda
+    ErrorCuda = ERROR_CUDA  # backward-compat alias
+    ERROR_UMD = cudlaErrorUmd
+    ErrorUmd = ERROR_UMD  # backward-compat alias
+    ERROR_INVALID_DEVICE = cudlaErrorInvalidDevice
+    ErrorInvalidDevice = ERROR_INVALID_DEVICE  # backward-compat alias
+    ERROR_INVALID_ATTRIBUTE = cudlaErrorInvalidAttribute
+    ErrorInvalidAttribute = ERROR_INVALID_ATTRIBUTE  # backward-compat alias
+    ERROR_INCOMPATIBLE_DLA_SW_VERSION = cudlaErrorIncompatibleDlaSWVersion
+    ErrorIncompatibleDlaSWVersion = ERROR_INCOMPATIBLE_DLA_SW_VERSION  # backward-compat alias
+    ERROR_MEMORY_REGISTERED = cudlaErrorMemoryRegistered
+    ErrorMemoryRegistered = ERROR_MEMORY_REGISTERED  # backward-compat alias
+    ERROR_INVALID_MODULE = cudlaErrorInvalidModule
+    ErrorInvalidModule = ERROR_INVALID_MODULE  # backward-compat alias
+    ERROR_UNSUPPORTED_OPERATION = cudlaErrorUnsupportedOperation
+    ErrorUnsupportedOperation = ERROR_UNSUPPORTED_OPERATION  # backward-compat alias
+    ERROR_NV_SCI = cudlaErrorNvSci
+    ErrorNvSci = ERROR_NV_SCI  # backward-compat alias
+    ERROR_DRIVER_NOT_FOUND = cudlaErrorDriverNotFound
+    ErrorDriverNotFound = ERROR_DRIVER_NOT_FOUND  # backward-compat alias
+    ERROR_DLA_ERR_INVALID_INPUT = cudlaErrorDlaErrInvalidInput
+    ErrorDlaErrInvalidInput = ERROR_DLA_ERR_INVALID_INPUT  # backward-compat alias
+    ERROR_DLA_ERR_INVALID_PRE_ACTION = cudlaErrorDlaErrInvalidPreAction
+    ErrorDlaErrInvalidPreAction = ERROR_DLA_ERR_INVALID_PRE_ACTION  # backward-compat alias
+    ERROR_DLA_ERR_NO_MEM = cudlaErrorDlaErrNoMem
+    ErrorDlaErrNoMem = ERROR_DLA_ERR_NO_MEM  # backward-compat alias
+    ERROR_DLA_ERR_PROCESSOR_BUSY = cudlaErrorDlaErrProcessorBusy
+    ErrorDlaErrProcessorBusy = ERROR_DLA_ERR_PROCESSOR_BUSY  # backward-compat alias
+    ERROR_DLA_ERR_TASK_STATUS_MISMATCH = cudlaErrorDlaErrTaskStatusMismatch
+    ErrorDlaErrTaskStatusMismatch = ERROR_DLA_ERR_TASK_STATUS_MISMATCH  # backward-compat alias
+    ERROR_DLA_ERR_ENGINE_TIMEOUT = cudlaErrorDlaErrEngineTimeout
+    ErrorDlaErrEngineTimeout = ERROR_DLA_ERR_ENGINE_TIMEOUT  # backward-compat alias
+    ERROR_DLA_ERR_DATA_MISMATCH = cudlaErrorDlaErrDataMismatch
+    ErrorDlaErrDataMismatch = ERROR_DLA_ERR_DATA_MISMATCH  # backward-compat alias
+    ERROR_UNKNOWN = cudlaErrorUnknown
+    ErrorUnknown = ERROR_UNKNOWN  # backward-compat alias
 
 class Mode(_cyb_IntEnum):
     """

cuda_bindings_13/cuda/bindings/driver.pyx

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 # This code was automatically generated with version 13.4.1. Do not modify it directly.
-# CYTHON-BINDINGS-GENERATED-DO-NOT-MODIFY-THIS-FILE: format=1; content-sha256=348b02f0a76a3a271fbb11535f02d660d811d3c21a877e46bfc070bbabf43e76
+# CYTHON-BINDINGS-GENERATED-DO-NOT-MODIFY-THIS-FILE: format=1; content-sha256=8932ee959b6a2f1e69316f813cb8e8492c8e112094812dc1310c49970f00779a
 from typing import Any, Optional
 import cython
 import ctypes
@@ -30899,7 +30899,7 @@ def cuDeviceRegisterAsyncNotification(device, callbackFunc, userData):
     if err != cydriver.CUDA_SUCCESS:
         free(cbData)
     else:
-        m_global._allocated[int(callback)] = cbData
+        m_global._insert(int(callback), cbData)
     _helper_input_void_ptr_free(&cyuserDataHelper)
     if err != cydriver.CUDA_SUCCESS:
         return (_CUresult(err), None)
@@ -30948,8 +30948,7 @@ def cuDeviceUnregisterAsyncNotification(device, callback):
     with nogil:
         err = cydriver.cuDeviceUnregisterAsyncNotification(cydevice, cycallback)
     if err == cydriver.CUDA_SUCCESS:
-        free(m_global._allocated[pcallback])
-        m_global._allocated.erase(<void_ptr>pcallback)
+        free(m_global._take(pcallback))
     return (_CUresult(err),)
 
 @cython.embedsignature(True)
@@ -55743,7 +55742,7 @@ def cuLogsRegisterCallback(callbackFunc, userData):
     if err != cydriver.CUDA_SUCCESS:
         free(cbData)
     else:
-        m_global._allocated[int(callback_out)] = cbData
+        m_global._insert(int(callback_out), cbData)
     _helper_input_void_ptr_free(&cyuserDataHelper)
     if err != cydriver.CUDA_SUCCESS:
         return (_CUresult(err), None)
@@ -55774,8 +55773,7 @@ def cuLogsUnregisterCallback(callback):
     with nogil:
         err = cydriver.cuLogsUnregisterCallback(cycallback)
     if err == cydriver.CUDA_SUCCESS:
-        free(m_global._allocated[pcallback])
-        m_global._allocated.erase(<void_ptr>pcallback)
+        free(m_global._take(pcallback))
     return (_CUresult(err),)
 
 @cython.embedsignature(True)
@@ -57375,6 +57373,19 @@ def cuGraphicsVDPAURegisterOutputSurface(vdpSurface, unsigned int flags):
 
 cdef class cudaBindingsDriverGlobal:
     cdef map[void_ptr, void*] _allocated
+    cdef cython.pymutex _lock
+
+    cdef void _insert(self, void_ptr key, void* value) noexcept:
+        with self._lock:
+            self._allocated[key] = value
+
+    cdef void* _take(self, void_ptr key) noexcept:
+        cdef void* value = NULL
+        with self._lock:
+            if self._allocated.count(key) != 0:
+                value = self._allocated[key]
+                self._allocated.erase(key)
+        return value
 
     def __dealloc__(self):
         for item in self._allocated:

cuda_bindings_13/cuda/bindings/runtime.pyx

@@ -2,7 +2,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 # This code was automatically generated with version 13.4.1. Do not modify it directly.
-# CYTHON-BINDINGS-GENERATED-DO-NOT-MODIFY-THIS-FILE: format=1; content-sha256=ea95eb12334cbd4c1bf3fc8e890fb6f9493063b12faea853bb3d8c6288934182
+# CYTHON-BINDINGS-GENERATED-DO-NOT-MODIFY-THIS-FILE: format=1; content-sha256=4cc5d08de16bc7cac781ba6e469ffe16b0d8e30beea5ec6f5e579f0fae24e834
 from typing import Any, Optional
 import cython
 import ctypes
@@ -21228,7 +21228,7 @@ def cudaDeviceRegisterAsyncNotification(int device, callbackFunc, userData):
     if err != cyruntime.cudaSuccess:
         free(cbData)
     else:
-        m_global._allocated[int(callback)] = cbData
+        m_global._insert(int(callback), cbData)
     _helper_input_void_ptr_free(&cyuserDataHelper)
 
     if err != cyruntime.cudaSuccess:
@@ -21270,8 +21270,7 @@ def cudaDeviceUnregisterAsyncNotification(int device, callback):
     with nogil:
         err = cyruntime.cudaDeviceUnregisterAsyncNotification(device, cycallback)
     if err == cyruntime.cudaSuccess:
-        free(m_global._allocated[pcallback])
-        m_global._allocated.erase(<void_ptr>pcallback)
+        free(m_global._take(pcallback))
     return (_cudaError_t(err),)
 
 @cython.embedsignature(True)
@@ -40262,6 +40261,19 @@ def getLocalRuntimeVersion():
 
 cdef class cudaBindingsRuntimeGlobal:
     cdef map[void_ptr, void*] _allocated
+    cdef cython.pymutex _lock
+
+    cdef void _insert(self, void_ptr key, void* value) noexcept:
+        with self._lock:
+            self._allocated[key] = value
+
+    cdef void* _take(self, void_ptr key) noexcept:
+        cdef void* value = NULL
+        with self._lock:
+            if self._allocated.count(key) != 0:
+                value = self._allocated[key]
+                self._allocated.erase(key)
+        return value
 
     def __dealloc__(self):
         for item in self._allocated:

cuda_bindings_13/tests/cudla/test_cudla_bindings.py

@@ -197,8 +197,9 @@ def test_cudla_error_stores_status(self):
         assert err.status == int(cudla.Status.ErrorInvalidParam)
 
     def test_cudla_error_str(self):
+        assert cudla.Status.ErrorInvalidParam is cudla.Status.ERROR_INVALID_PARAM
         err = cudla.CudlaError(int(cudla.Status.ErrorInvalidParam))
-        assert "ErrorInvalidParam" in str(err)
+        assert "ERROR_INVALID_PARAM" in str(err)
 
 
 # ---------------------------------------------------------------------------

cuda_bindings_13/tests/test_callback_threads.py

@@ -0,0 +1,45 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import threading
+
+import pytest
+
+from cuda.bindings import driver
+from cuda_python_test_helpers import driver_version_less_than
+
+NUM_THREADS = 16
+NUM_ITERATIONS = 500
+
+
+@pytest.mark.agent_authored(model="claude-sonnet-5-5")
+@pytest.mark.skipif(
+    driver_version_less_than(12090),
+    reason="cuLogs* functions were introduced in CUDA 12.9",
+)
+@pytest.mark.thread_unsafe(reason="starts its own threads and needs them to overlap")
+def test_culogs_register_unregister_from_many_threads():
+    (err,) = driver.cuInit(0)
+    assert err == driver.CUresult.CUDA_SUCCESS
+
+    barrier = threading.Barrier(NUM_THREADS)
+    failures = []
+
+    def worker():
+        try:
+            barrier.wait()
+            for _ in range(NUM_ITERATIONS):
+                err, handle = driver.cuLogsRegisterCallback(0, None)
+                assert err == driver.CUresult.CUDA_SUCCESS
+                (err,) = driver.cuLogsUnregisterCallback(handle)
+                assert err == driver.CUresult.CUDA_SUCCESS
+        except BaseException as e:
+            failures.append(e)
+
+    threads = [threading.Thread(target=worker) for _ in range(NUM_THREADS)]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    assert not failures, failures

cuda_bindings_13/tests/test_graphics_apis.py

@@ -13,6 +13,7 @@
     gl_context_not_on_nvidia_gpu_reason,
     is_gl_context_unavailable,
     open_gl_window,
+    select_headless_egl_device_for_cuda,
     tcc_skip_reason,
 )
 
@@ -22,12 +23,20 @@
 
 
 def _configure_pyglet_headless():
-    """On headless Linux: enable EGL mode or skip if EGL is absent."""
+    """On headless Linux: enable EGL mode, matched to CUDA device 0, or skip if EGL is absent."""
     if sys.platform.startswith("linux") and not (os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")):
         if ctypes.util.find_library("EGL") is None:
             pytest.skip("No DISPLAY and no EGL runtime available for headless context.")
         pyglet.options["headless"] = True
 
+        # CUDA_VISIBLE_DEVICES does not reorder EGL's device enumeration, so on
+        # headless multi-GPU systems EGL device 0 may not be the physical GPU
+        # behind CUDA device 0, which these tests register against. Pick the
+        # EGL device that the driver reports as corresponding to it.
+        egl_device = select_headless_egl_device_for_cuda(0)
+        if egl_device is not None:
+            pyglet.options["headless_device"] = egl_device
+
 
 def _allocate_gl_texture(win):
     """Allocate a 2-D RGBA8 texture. Caller must have a current GL context.