[FEA]: Add CUDA driver version query to cuda.pathfinder (private API) (#1953)

* Add a reusable pathfinder driver info helper.

Break out CUDA driver version querying into a standalone internal utility so it can be reused independently from compatibility checks, and cover the ctypes loader paths with focused tests.

Made-with: Cursor

* Refine pathfinder driver info loader checks.

Treat the Windows WinDLL path as the normal runtime case and keep the focused tests aligned with the stricter driver-loader invariants.

Made-with: Cursor

* Add parsed pathfinder driver version metadata.

Wrap the encoded cuDriverGetVersion() result in a DriverVersion dataclass so callers can use major and minor fields directly while retaining a low-level integer helper for loader-focused tests.

Made-with: Cursor

* Add a real pathfinder driver version test.

Cover query_driver_version() alongside the driver library loading tests and reuse the existing strictness mode so host-specific failures still surface cleanly in all_must_work mode.

Made-with: Cursor

* Reduce redundant pathfinder driver info mocks.

Drop the non-Windows loader mock now that a real driver-version test covers the Linux success path, while keeping the Windows branch and failure-path unit coverage.

Made-with: Cursor

* Rename the pathfinder CUDA driver version dataclass.

Use DriverCudaVersion for clearer pairing with the planned release-version type while keeping the existing driver info API behavior unchanged.

Made-with: Cursor

* Add a pathfinder NVML driver release version helper.

Query nvmlSystemGetDriverVersion() through pathfinder's driver library loading path and add a minimal real test so the implementation is preserved as a future reference.

Made-with: Cursor

* Revert the pathfinder NVML driver release version helper.

Step back from the exploratory NVML-based release-version query for now because it adds non-trivial complexity and a new dependency surface without a current pathfinder need, while keeping the reference implementation in history if we need it later.

Made-with: Cursor

* Clarify the pathfinder CUDA driver version naming.

Document that DriverCudaVersion matches the CUDA Version shown by nvidia-smi rather than the graphics driver release, so the dataclass name reads clearly in context.

Made-with: Cursor

* Finalize the pathfinder CUDA driver version query API.

Expose DriverCudaVersion, QueryDriverCudaVersionError, and query_driver_cuda_version publicly, and align the internal naming, caching, docs, and test coverage around the CUDA-specific driver version query.

Made-with: Cursor

* Add a public pathfinder driver info regression test.

Protect the new top-level driver-info re-exports so internal-only test coverage does not miss a broken `cuda.pathfinder` plumbing layer.

Made-with: Cursor

* Remove pathfinder driver info public re-exports

Stop exposing the new driver info helper through cuda.pathfinder while keeping the internal implementation and internal test coverage in place.

Made-with: Cursor

* Clarify DriverCudaVersion docstring terminology.

Spell out that `cuDriverGetVersion()` reports the CUDA-facing user-mode driver (UMD) version rather than the kernel-mode driver (KMD) package version so the `nvidia-smi` comparison is less ambiguous.

Made-with: Cursor

Author: rwgk

cuda_pathfinder/cuda/pathfinder/_utils/driver_info.py

@@ -0,0 +1,80 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+import ctypes
+import functools
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from cuda.pathfinder._dynamic_libs.load_nvidia_dynamic_lib import (
+    load_nvidia_dynamic_lib as _load_nvidia_dynamic_lib,
+)
+from cuda.pathfinder._utils.platform_aware import IS_WINDOWS
+
+
+class QueryDriverCudaVersionError(RuntimeError):
+    """Raised when ``query_driver_cuda_version()`` cannot determine the CUDA driver version."""
+
+
+@dataclass(frozen=True, slots=True)
+class DriverCudaVersion:
+    """
+    CUDA-facing driver version reported by ``cuDriverGetVersion()``.
+
+    The name ``DriverCudaVersion`` is intentionally specific: this dataclass
+    models the version shown as ``CUDA Version`` in ``nvidia-smi``, not the
+    graphics driver release shown as ``Driver Version``. More specifically,
+    it reflects the CUDA user-mode driver (UMD) interface version reported by
+    ``cuDriverGetVersion()``, not the kernel-mode driver (KMD) package
+    version.
+
+    Example ``nvidia-smi`` output::
+
+        +---------------------------------------------------------------------+
+        | NVIDIA-SMI 595.58.03  Driver Version: 595.58.03  CUDA Version: 13.2 |
+        +---------------------------------------------------------------------+
+
+    For the example above, ``DriverCudaVersion(encoded=13020, major=13,
+    minor=2)`` corresponds to ``CUDA Version: 13.2``. It does not correspond
+    to ``Driver Version: 595.58.03``.
+    """
+
+    encoded: int
+    major: int
+    minor: int
+
+
+@functools.cache
+def query_driver_cuda_version() -> DriverCudaVersion:
+    """Return the CUDA driver version parsed into its major/minor components."""
+    try:
+        encoded = _query_driver_cuda_version_int()
+        return DriverCudaVersion(
+            encoded=encoded,
+            major=encoded // 1000,
+            minor=(encoded % 1000) // 10,
+        )
+    except Exception as exc:
+        raise QueryDriverCudaVersionError("Failed to query the CUDA driver version.") from exc
+
+
+def _query_driver_cuda_version_int() -> int:
+    """Return the encoded CUDA driver version from ``cuDriverGetVersion()``."""
+    loaded_cuda = _load_nvidia_dynamic_lib("cuda")
+    if IS_WINDOWS:
+        # `ctypes.WinDLL` exists on Windows at runtime. The ignore is only for
+        # Linux mypy runs, where the platform stubs do not define that attribute.
+        loader_cls: Callable[[str], ctypes.CDLL] = ctypes.WinDLL  # type: ignore[attr-defined]
+    else:
+        loader_cls = ctypes.CDLL
+    driver_lib = loader_cls(loaded_cuda.abs_path)
+    cu_driver_get_version = driver_lib.cuDriverGetVersion
+    cu_driver_get_version.argtypes = [ctypes.POINTER(ctypes.c_int)]
+    cu_driver_get_version.restype = ctypes.c_int
+    version = ctypes.c_int()
+    status = cu_driver_get_version(ctypes.byref(version))
+    if status != 0:
+        raise RuntimeError(f"Failed to query CUDA driver version via cuDriverGetVersion() (status={status}).")
+    return version.value

cuda_pathfinder/tests/test_driver_lib_loading.py

@@ -25,6 +25,7 @@
     _load_lib_no_cache,
 )
 from cuda.pathfinder._dynamic_libs.subprocess_protocol import STATUS_NOT_FOUND, parse_dynamic_lib_subprocess_payload
+from cuda.pathfinder._utils import driver_info
 from cuda.pathfinder._utils.platform_aware import IS_WINDOWS, quote_for_shell
 
 STRICTNESS = os.environ.get("CUDA_PATHFINDER_TEST_LOAD_NVIDIA_DYNAMIC_LIB_STRICTNESS", "see_what_works")
@@ -157,3 +158,23 @@ def raise_child_process_failed():
         assert abs_path is not None
         info_summary_append(f"abs_path={quote_for_shell(abs_path)}")
         assert os.path.isfile(abs_path)
+
+
+def test_real_query_driver_cuda_version(info_summary_append):
+    driver_info._load_nvidia_dynamic_lib.cache_clear()
+    driver_info.query_driver_cuda_version.cache_clear()
+    try:
+        version = driver_info.query_driver_cuda_version()
+    except driver_info.QueryDriverCudaVersionError as exc:
+        if STRICTNESS == "all_must_work":
+            raise
+        info_summary_append(f"driver version unavailable: {exc.__class__.__name__}: {exc}")
+        return
+    finally:
+        driver_info._load_nvidia_dynamic_lib.cache_clear()
+        driver_info.query_driver_cuda_version.cache_clear()
+
+    info_summary_append(f"driver_version={version.major}.{version.minor} (encoded={version.encoded})")
+    assert version.encoded > 0
+    assert version.major == version.encoded // 1000
+    assert version.minor == (version.encoded % 1000) // 10

cuda_pathfinder/tests/test_utils_driver_info.py

@@ -0,0 +1,101 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import ctypes
+
+import pytest
+
+from cuda.pathfinder._dynamic_libs.load_dl_common import LoadedDL
+from cuda.pathfinder._utils import driver_info
+
+
+@pytest.fixture(autouse=True)
+def _clear_driver_cuda_version_query_cache():
+    driver_info.query_driver_cuda_version.cache_clear()
+    yield
+    driver_info.query_driver_cuda_version.cache_clear()
+
+
+class _FakeCuDriverGetVersion:
+    def __init__(self, *, status: int, version: int):
+        self.argtypes = None
+        self.restype = None
+        self._status = status
+        self._version = version
+
+    def __call__(self, version_ptr) -> int:
+        ctypes.cast(version_ptr, ctypes.POINTER(ctypes.c_int)).contents.value = self._version
+        return self._status
+
+
+class _FakeDriverLib:
+    def __init__(self, *, status: int, version: int):
+        self.cuDriverGetVersion = _FakeCuDriverGetVersion(status=status, version=version)
+
+
+def _loaded_cuda(abs_path: str) -> LoadedDL:
+    return LoadedDL(
+        abs_path=abs_path,
+        was_already_loaded_from_elsewhere=False,
+        _handle_uint=0xBEEF,
+        found_via="system-search",
+    )
+
+
+def test_query_driver_cuda_version_uses_windll_on_windows(monkeypatch):
+    fake_driver_lib = _FakeDriverLib(status=0, version=12080)
+    loaded_paths: list[str] = []
+
+    monkeypatch.setattr(driver_info, "IS_WINDOWS", True)
+    monkeypatch.setattr(
+        driver_info,
+        "_load_nvidia_dynamic_lib",
+        lambda _libname: _loaded_cuda(r"C:\Windows\System32\nvcuda.dll"),
+    )
+
+    def fake_windll(abs_path: str):
+        loaded_paths.append(abs_path)
+        return fake_driver_lib
+
+    monkeypatch.setattr(driver_info.ctypes, "WinDLL", fake_windll, raising=False)
+
+    assert driver_info._query_driver_cuda_version_int() == 12080
+    assert loaded_paths == [r"C:\Windows\System32\nvcuda.dll"]
+
+
+def test_query_driver_cuda_version_returns_parsed_dataclass(monkeypatch):
+    monkeypatch.setattr(driver_info, "_query_driver_cuda_version_int", lambda: 12080)
+
+    assert driver_info.query_driver_cuda_version() == driver_info.DriverCudaVersion(
+        encoded=12080,
+        major=12,
+        minor=8,
+    )
+
+
+def test_query_driver_cuda_version_wraps_internal_failures(monkeypatch):
+    root_cause = RuntimeError("low-level query failed")
+
+    def fail_query_driver_cuda_version_int() -> int:
+        raise root_cause
+
+    monkeypatch.setattr(driver_info, "_query_driver_cuda_version_int", fail_query_driver_cuda_version_int)
+
+    with pytest.raises(
+        driver_info.QueryDriverCudaVersionError,
+        match="Failed to query the CUDA driver version",
+    ) as exc_info:
+        driver_info.query_driver_cuda_version()
+
+    assert exc_info.value.__cause__ is root_cause
+
+
+def test_query_driver_cuda_version_int_raises_when_cuda_call_fails(monkeypatch):
+    fake_driver_lib = _FakeDriverLib(status=1, version=0)
+
+    monkeypatch.setattr(driver_info, "IS_WINDOWS", False)
+    monkeypatch.setattr(driver_info, "_load_nvidia_dynamic_lib", lambda _libname: _loaded_cuda("/usr/lib/libcuda.so.1"))
+    monkeypatch.setattr(driver_info.ctypes, "CDLL", lambda _abs_path: fake_driver_lib)
+
+    with pytest.raises(RuntimeError, match=r"cuDriverGetVersion\(\) \(status=1\)"):
+        driver_info._query_driver_cuda_version_int()