pathfinder: gate cudla support by machine architecture

Mark cudla and nvcudla as aarch64-only descriptors and derive the supported
library tables from the current machine as well as the current OS. This keeps
those libraries known to pathfinder while reporting them as unavailable on
linux-64, and updates the descriptor-registry tests to match the new
current-platform filtering model.

Made-with: Cursor

Author: rwgk

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/descriptor_catalog.py

@@ -8,6 +8,8 @@
 from dataclasses import dataclass
 from typing import Literal
 
+from cuda.pathfinder._utils.platform_aware import PLATFORM_MACHINE
+
 PackagedWith = Literal["ctk", "other", "driver"]
 
 
@@ -17,6 +19,7 @@ class DescriptorSpec:
     packaged_with: PackagedWith
     linux_sonames: tuple[str, ...] = ()
     windows_dlls: tuple[str, ...] = ()
+    platform_machines: tuple[str, ...] = ()
     site_packages_linux: tuple[str, ...] = ()
     site_packages_windows: tuple[str, ...] = ()
     dependencies: tuple[str, ...] = ()
@@ -27,6 +30,10 @@ class DescriptorSpec:
     requires_rtld_deepbind: bool = False
 
 
+def is_supported_on_current_machine(desc: DescriptorSpec) -> bool:
+    return not desc.platform_machines or PLATFORM_MACHINE in desc.platform_machines
+
+
 DESCRIPTOR_CATALOG: tuple[DescriptorSpec, ...] = (
     # -----------------------------------------------------------------------
     # CTK (CUDA Toolkit) libraries
@@ -328,6 +335,7 @@ class DescriptorSpec:
         name="cudla",
         packaged_with="other",
         linux_sonames=("libcudla.so.1",),
+        platform_machines=("aarch64",),
         site_packages_linux=("nvidia/cu13/lib",),
     ),
     DescriptorSpec(
@@ -396,6 +404,7 @@ class DescriptorSpec:
         name="nvcudla",
         packaged_with="driver",
         linux_sonames=("libnvcudla.so",),
+        platform_machines=("aarch64",),
     ),
     DescriptorSpec(
         name="nvml",

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/load_nvidia_dynamic_lib.py

@@ -9,6 +9,7 @@
 import sys
 from typing import TYPE_CHECKING
 
+from cuda.pathfinder._dynamic_libs.descriptor_catalog import is_supported_on_current_machine
 from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
 from cuda.pathfinder._dynamic_libs.load_dl_common import (
     DynamicLibNotAvailableError,
@@ -43,15 +44,19 @@
 # (CTK, third-party, driver).
 _ALL_KNOWN_LIBNAMES: frozenset[str] = frozenset(LIB_DESCRIPTORS)
 _ALL_SUPPORTED_LIBNAMES: frozenset[str] = frozenset(
-    name for name, desc in LIB_DESCRIPTORS.items() if (desc.windows_dlls if IS_WINDOWS else desc.linux_sonames)
+    name
+    for name, desc in LIB_DESCRIPTORS.items()
+    if is_supported_on_current_machine(desc) and (desc.windows_dlls if IS_WINDOWS else desc.linux_sonames)
 )
 _PLATFORM_NAME = "Windows" if IS_WINDOWS else "Linux"
 _CANARY_PROBE_TIMEOUT_SECONDS = 10.0
 
 # Driver libraries: shipped with the NVIDIA display driver, always on the
 # system linker path.  These skip all CTK search steps (site-packages,
 # conda, CUDA_PATH, canary) and go straight to system search.
-_DRIVER_ONLY_LIBNAMES = frozenset(name for name, desc in LIB_DESCRIPTORS.items() if desc.packaged_with == "driver")
+_DRIVER_ONLY_LIBNAMES = frozenset(
+    name for name, desc in LIB_DESCRIPTORS.items() if desc.packaged_with == "driver" and name in _ALL_SUPPORTED_LIBNAMES
+)
 
 
 def _load_driver_lib_no_cache(desc: LibDescriptor) -> LoadedDL:

cuda_pathfinder/cuda/pathfinder/_dynamic_libs/supported_nvidia_libs.py

@@ -10,20 +10,36 @@
 
 from __future__ import annotations
 
-from cuda.pathfinder._dynamic_libs.descriptor_catalog import DESCRIPTOR_CATALOG
+from cuda.pathfinder._dynamic_libs.descriptor_catalog import DESCRIPTOR_CATALOG, is_supported_on_current_machine
+from cuda.pathfinder._dynamic_libs.lib_descriptor import LibDescriptor
 from cuda.pathfinder._utils.platform_aware import IS_WINDOWS
 
 _CTK_DESCRIPTORS = tuple(desc for desc in DESCRIPTOR_CATALOG if desc.packaged_with == "ctk")
 _OTHER_DESCRIPTORS = tuple(desc for desc in DESCRIPTOR_CATALOG if desc.packaged_with == "other")
 _DRIVER_DESCRIPTORS = tuple(desc for desc in DESCRIPTOR_CATALOG if desc.packaged_with == "driver")
 _NON_CTK_DESCRIPTORS = _OTHER_DESCRIPTORS + _DRIVER_DESCRIPTORS
 
-SUPPORTED_LIBNAMES_COMMON = tuple(desc.name for desc in _CTK_DESCRIPTORS if desc.linux_sonames and desc.windows_dlls)
+
+def _has_supported_linux_sonames(desc: LibDescriptor) -> bool:
+    return bool(desc.linux_sonames) and is_supported_on_current_machine(desc)
+
+
+def _has_supported_windows_dlls(desc: LibDescriptor) -> bool:
+    return bool(desc.windows_dlls) and is_supported_on_current_machine(desc)
+
+
+SUPPORTED_LIBNAMES_COMMON = tuple(
+    desc.name for desc in _CTK_DESCRIPTORS if _has_supported_linux_sonames(desc) and _has_supported_windows_dlls(desc)
+)
 SUPPORTED_LIBNAMES_LINUX_ONLY = tuple(
-    desc.name for desc in _CTK_DESCRIPTORS if desc.linux_sonames and not desc.windows_dlls
+    desc.name
+    for desc in _CTK_DESCRIPTORS
+    if _has_supported_linux_sonames(desc) and not _has_supported_windows_dlls(desc)
 )
 SUPPORTED_LIBNAMES_WINDOWS_ONLY = tuple(
-    desc.name for desc in _CTK_DESCRIPTORS if desc.windows_dlls and not desc.linux_sonames
+    desc.name
+    for desc in _CTK_DESCRIPTORS
+    if _has_supported_windows_dlls(desc) and not _has_supported_linux_sonames(desc)
 )
 
 SUPPORTED_LIBNAMES_LINUX = SUPPORTED_LIBNAMES_COMMON + SUPPORTED_LIBNAMES_LINUX_ONLY
@@ -34,37 +50,57 @@
 DIRECT_DEPENDENCIES_CTK = {desc.name: desc.dependencies for desc in _CTK_DESCRIPTORS if desc.dependencies}
 DIRECT_DEPENDENCIES = {desc.name: desc.dependencies for desc in DESCRIPTOR_CATALOG if desc.dependencies}
 
-SUPPORTED_LINUX_SONAMES_CTK = {desc.name: desc.linux_sonames for desc in _CTK_DESCRIPTORS if desc.linux_sonames}
-SUPPORTED_LINUX_SONAMES_OTHER = {desc.name: desc.linux_sonames for desc in _OTHER_DESCRIPTORS if desc.linux_sonames}
-SUPPORTED_LINUX_SONAMES_DRIVER = {desc.name: desc.linux_sonames for desc in _DRIVER_DESCRIPTORS if desc.linux_sonames}
+SUPPORTED_LINUX_SONAMES_CTK = {
+    desc.name: desc.linux_sonames for desc in _CTK_DESCRIPTORS if _has_supported_linux_sonames(desc)
+}
+SUPPORTED_LINUX_SONAMES_OTHER = {
+    desc.name: desc.linux_sonames for desc in _OTHER_DESCRIPTORS if _has_supported_linux_sonames(desc)
+}
+SUPPORTED_LINUX_SONAMES_DRIVER = {
+    desc.name: desc.linux_sonames for desc in _DRIVER_DESCRIPTORS if _has_supported_linux_sonames(desc)
+}
 SUPPORTED_LINUX_SONAMES = SUPPORTED_LINUX_SONAMES_CTK | SUPPORTED_LINUX_SONAMES_OTHER | SUPPORTED_LINUX_SONAMES_DRIVER
 
-SUPPORTED_WINDOWS_DLLS_CTK = {desc.name: desc.windows_dlls for desc in _CTK_DESCRIPTORS if desc.windows_dlls}
-SUPPORTED_WINDOWS_DLLS_OTHER = {desc.name: desc.windows_dlls for desc in _OTHER_DESCRIPTORS if desc.windows_dlls}
-SUPPORTED_WINDOWS_DLLS_DRIVER = {desc.name: desc.windows_dlls for desc in _DRIVER_DESCRIPTORS if desc.windows_dlls}
+SUPPORTED_WINDOWS_DLLS_CTK = {
+    desc.name: desc.windows_dlls for desc in _CTK_DESCRIPTORS if _has_supported_windows_dlls(desc)
+}
+SUPPORTED_WINDOWS_DLLS_OTHER = {
+    desc.name: desc.windows_dlls for desc in _OTHER_DESCRIPTORS if _has_supported_windows_dlls(desc)
+}
+SUPPORTED_WINDOWS_DLLS_DRIVER = {
+    desc.name: desc.windows_dlls for desc in _DRIVER_DESCRIPTORS if _has_supported_windows_dlls(desc)
+}
 SUPPORTED_WINDOWS_DLLS = SUPPORTED_WINDOWS_DLLS_CTK | SUPPORTED_WINDOWS_DLLS_OTHER | SUPPORTED_WINDOWS_DLLS_DRIVER
 
 LIBNAMES_REQUIRING_OS_ADD_DLL_DIRECTORY = tuple(
-    desc.name for desc in DESCRIPTOR_CATALOG if desc.requires_add_dll_directory and desc.windows_dlls
+    desc.name for desc in DESCRIPTOR_CATALOG if desc.requires_add_dll_directory and _has_supported_windows_dlls(desc)
 )
 LIBNAMES_REQUIRING_RTLD_DEEPBIND = tuple(
-    desc.name for desc in DESCRIPTOR_CATALOG if desc.requires_rtld_deepbind and desc.linux_sonames
+    desc.name for desc in DESCRIPTOR_CATALOG if desc.requires_rtld_deepbind and _has_supported_linux_sonames(desc)
 )
 
 # Based on output of toolshed/make_site_packages_libdirs_linux.py
 SITE_PACKAGES_LIBDIRS_LINUX_CTK = {
-    desc.name: desc.site_packages_linux for desc in _CTK_DESCRIPTORS if desc.site_packages_linux
+    desc.name: desc.site_packages_linux
+    for desc in _CTK_DESCRIPTORS
+    if desc.site_packages_linux and _has_supported_linux_sonames(desc)
 }
 SITE_PACKAGES_LIBDIRS_LINUX_OTHER = {
-    desc.name: desc.site_packages_linux for desc in _NON_CTK_DESCRIPTORS if desc.site_packages_linux
+    desc.name: desc.site_packages_linux
+    for desc in _NON_CTK_DESCRIPTORS
+    if desc.site_packages_linux and _has_supported_linux_sonames(desc)
 }
 SITE_PACKAGES_LIBDIRS_LINUX = SITE_PACKAGES_LIBDIRS_LINUX_CTK | SITE_PACKAGES_LIBDIRS_LINUX_OTHER
 
 SITE_PACKAGES_LIBDIRS_WINDOWS_CTK = {
-    desc.name: desc.site_packages_windows for desc in _CTK_DESCRIPTORS if desc.site_packages_windows
+    desc.name: desc.site_packages_windows
+    for desc in _CTK_DESCRIPTORS
+    if desc.site_packages_windows and _has_supported_windows_dlls(desc)
 }
 SITE_PACKAGES_LIBDIRS_WINDOWS_OTHER = {
-    desc.name: desc.site_packages_windows for desc in _NON_CTK_DESCRIPTORS if desc.site_packages_windows
+    desc.name: desc.site_packages_windows
+    for desc in _NON_CTK_DESCRIPTORS
+    if desc.site_packages_windows and _has_supported_windows_dlls(desc)
 }
 SITE_PACKAGES_LIBDIRS_WINDOWS = SITE_PACKAGES_LIBDIRS_WINDOWS_CTK | SITE_PACKAGES_LIBDIRS_WINDOWS_OTHER
 

cuda_pathfinder/cuda/pathfinder/_utils/platform_aware.py

@@ -1,9 +1,11 @@
-# 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 platform
 import sys
 
 IS_WINDOWS = sys.platform == "win32"
+PLATFORM_MACHINE = platform.machine().lower()
 
 
 def quote_for_shell(s: str) -> str:

cuda_pathfinder/tests/test_lib_descriptor.py

@@ -2,10 +2,11 @@
 # SPDX-License-Identifier: Apache-2.0
 
 """Tests verifying that the LibDescriptor registry faithfully represents
-the existing data tables in supported_nvidia_libs.py."""
+the current-platform data tables in supported_nvidia_libs.py."""
 
 import pytest
 
+from cuda.pathfinder._dynamic_libs.descriptor_catalog import is_supported_on_current_machine
 from cuda.pathfinder._dynamic_libs.lib_descriptor import LIB_DESCRIPTORS
 from cuda.pathfinder._dynamic_libs.supported_nvidia_libs import (
     DIRECT_DEPENDENCIES,
@@ -33,7 +34,8 @@ def test_registry_covers_all_windows_dlls():
 
 def test_registry_has_no_extra_entries():
     expected = set(SUPPORTED_LINUX_SONAMES) | set(SUPPORTED_WINDOWS_DLLS)
-    assert set(LIB_DESCRIPTORS) == expected
+    extra = set(LIB_DESCRIPTORS) - expected
+    assert all(not is_supported_on_current_machine(LIB_DESCRIPTORS[name]) for name in extra)
 
 
 # ---------------------------------------------------------------------------
@@ -43,22 +45,30 @@ def test_registry_has_no_extra_entries():
 
 @pytest.mark.parametrize("name", sorted(LIB_DESCRIPTORS))
 def test_linux_sonames_match(name):
-    assert LIB_DESCRIPTORS[name].linux_sonames == SUPPORTED_LINUX_SONAMES.get(name, ())
+    desc = LIB_DESCRIPTORS[name]
+    expected = desc.linux_sonames if is_supported_on_current_machine(desc) else ()
+    assert expected == SUPPORTED_LINUX_SONAMES.get(name, ())
 
 
 @pytest.mark.parametrize("name", sorted(LIB_DESCRIPTORS))
 def test_windows_dlls_match(name):
-    assert LIB_DESCRIPTORS[name].windows_dlls == SUPPORTED_WINDOWS_DLLS.get(name, ())
+    desc = LIB_DESCRIPTORS[name]
+    expected = desc.windows_dlls if is_supported_on_current_machine(desc) else ()
+    assert expected == SUPPORTED_WINDOWS_DLLS.get(name, ())
 
 
 @pytest.mark.parametrize("name", sorted(LIB_DESCRIPTORS))
 def test_site_packages_linux_match(name):
-    assert LIB_DESCRIPTORS[name].site_packages_linux == SITE_PACKAGES_LIBDIRS_LINUX.get(name, ())
+    desc = LIB_DESCRIPTORS[name]
+    expected = desc.site_packages_linux if is_supported_on_current_machine(desc) else ()
+    assert expected == SITE_PACKAGES_LIBDIRS_LINUX.get(name, ())
 
 
 @pytest.mark.parametrize("name", sorted(LIB_DESCRIPTORS))
 def test_site_packages_windows_match(name):
-    assert LIB_DESCRIPTORS[name].site_packages_windows == SITE_PACKAGES_LIBDIRS_WINDOWS.get(name, ())
+    desc = LIB_DESCRIPTORS[name]
+    expected = desc.site_packages_windows if is_supported_on_current_machine(desc) else ()
+    assert expected == SITE_PACKAGES_LIBDIRS_WINDOWS.get(name, ())
 
 
 @pytest.mark.parametrize("name", sorted(LIB_DESCRIPTORS))
@@ -68,12 +78,16 @@ def test_dependencies_match(name):
 
 @pytest.mark.parametrize("name", sorted(LIB_DESCRIPTORS))
 def test_requires_add_dll_directory_match(name):
-    assert LIB_DESCRIPTORS[name].requires_add_dll_directory == (name in LIBNAMES_REQUIRING_OS_ADD_DLL_DIRECTORY)
+    desc = LIB_DESCRIPTORS[name]
+    expected = desc.requires_add_dll_directory if is_supported_on_current_machine(desc) else False
+    assert expected == (name in LIBNAMES_REQUIRING_OS_ADD_DLL_DIRECTORY)
 
 
 @pytest.mark.parametrize("name", sorted(LIB_DESCRIPTORS))
 def test_requires_rtld_deepbind_match(name):
-    assert LIB_DESCRIPTORS[name].requires_rtld_deepbind == (name in LIBNAMES_REQUIRING_RTLD_DEEPBIND)
+    desc = LIB_DESCRIPTORS[name]
+    expected = desc.requires_rtld_deepbind if is_supported_on_current_machine(desc) else False
+    assert expected == (name in LIBNAMES_REQUIRING_RTLD_DEEPBIND)
 
 
 # ---------------------------------------------------------------------------