Skip to content

feat(pathfinder): support SM-specific bitcode lookup - #3532

Open
xiakun-lu wants to merge 1 commit into
NVIDIA:mainfrom
xiakun-lu:pathfinder/bitcode-sm-arch
Open

xiakun-lu wants to merge 1 commit into
NVIDIA:mainfrom
xiakun-lu:pathfinder/bitcode-sm-arch

Conversation

@xiakun-lu

Copy link
Copy Markdown

Description

Related to #2200, #2201, and #2302.

NCCL and NVSHMEM installations that ship per-SM device bitcode need a way to select the file for a specific GPU target. Add the keyword-only sm_arch argument to find_bitcode_lib() and locate_bitcode_lib(). For example, find_bitcode_lib("nvshmem_device", sm_arch="100") looks for libnvshmem_device_sm_100.bc when the installation provides it.

Pathfinder owns the filename convention. A library can declare an exact SM filename or a template for SMs without an explicit entry. If the selected file is missing, lookup raises BitcodeLibNotFoundError. Calls that omit sm_arch continue to use the existing default filename and search order.

Validation

  • 26 focused bitcode lookup tests passed with the loader isolated on macOS.
  • 40 comparisons with main matched for default lookup, including relative roots, symlinked files, diagnostics, and caching.
  • Ruff, mypy, and git diff --check passed. The future NCCL wheel that ships per-SM files was not available for validation.

Checklist

  • I have read the Contributing Guidelines.
  • New or existing tests cover these changes.
  • The documentation is up to date with these changes.

Signed-off-by: Xiakun Lu <xiakunl@nvidia.com>
@github-actions github-actions Bot added the cuda.pathfinder Everything related to the cuda.pathfinder module label Nov 22, 2026
@coderabbitai

coderabbitai Bot commented Nov 22, 2026

Copy link
Copy Markdown

Explain Change →

No actionable comments were generated in the recent review.

Summary

Summary by CodeRabbit

  • New Features
    • Bitcode library lookup can now target a specific SM architecture, selecting an exact architecture match or a wildcard match. Filename templates can include the architecture, and omitting the architecture retains the default lookup.
  • Bug Fixes
    • Invalid architecture values and missing architecture-specific or default configurations now produce clear errors. Requested architectures do not silently fall back to the default library. Cached lookup results are kept distinct by architecture.

Bitcode metadata and lookup APIs now support optional SM architecture selection. Lookups choose exact architecture filenames before wildcard templates, validate architecture values, and report missing selected files. Tests cover selection, cache behavior, lookup errors, and existing search paths.

Changes: Bitcode library lookup

Layer / File(s) Summary
Configure and select architecture-specific filenames
cuda_pathfinder/cuda/pathfinder/_static_libs/find_bitcode_lib.py, cuda_pathfinder/tests/test_find_bitcode_lib.py
Metadata stores default, exact-architecture, and wildcard filename alternatives. _FindBitcodeLib validates sm_arch, prefers exact mappings, and uses wildcard templates when no exact mapping exists. Tests cover selection, precedence, missing configuration, and invalid values.
Expose architecture-aware lookup
cuda_pathfinder/cuda/pathfinder/_static_libs/find_bitcode_lib.py, cuda_pathfinder/tests/test_find_bitcode_lib.py
locate_bitcode_lib and find_bitcode_lib accept keyword-only sm_arch. Lookup diagnostics and search results use the selected filename. Existing search tests use explicit file paths, and new tests cover architecture-specific caching.

Possibly related issues

  • NVIDIA/cuda-python#3366: The PR adds a missing-file error path for SM-specific lookups, but does not clearly change the diagnostic directory listing reported to raise PermissionError.

Suggested labels: cuda.pathfinder, enhancement

Suggested reviewers: rwgk, abhilash1910

Change: Feature

Merge Risk: Minimal · up to 7da58

This change adds optional per-SM bitcode library lookup while leaving default lookups unchanged. No concrete defects were found, and tests cover selection, precedence, errors, and caching. The failing CI check concerns PR metadata (assignee, labels, milestone), not the code.

Security architecture risk: Minimal · up to 7da58

The optional GPU-target selector preserves existing lookup defaults and search locations. Validation, target-specific caching, and explicit missing-file failures establish no introduced security or failure-containment risk in the inspected change.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

  • inferred — The demonstrated exposure is selection of a bitcode path within the calling process's existing installation and environment context. The new argument changes the selected filename, not process privileges or configured search roots. Downstream loading or compilation may consume that path, but remote, tenant, or cross-service reachability is not established by the available evidence.

Security Findings and Attack Paths

  • inferred — The inspected change does not establish an introduced traversal or incompatible-default attack path: validation precedes formatting, the caller cannot supply a filename template through this API, and an explicit SM request fails when its selected file is absent instead of accepting the default file.

Trust Boundaries and Controls

  • inferred — Installation contents, environment-selected roots, and symlink targets remain trusted inputs to resolution; resolve_path is canonicalization, not a containment control. Authority to influence those inputs predates the PR. The new SM token does not itself confer that authority or permit path separators.

Resilience and Maintainability Implications

  • inferred — The existing functools.cache now distinguishes SM arguments, preventing one target's successful lookup from supplying another target's result. Exceptions are not memoized, so failed requests can retry; concurrent misses can repeat read-only work without sharing finder diagnostics. Successful paths retain the base's process-lifetime staleness behavior. No new persistent transition requires rollback or cleanup.
Finishing Touches

Fix failing CI checks

  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts
Recent review info

Run configuration

Commits

Reviewing files that changed from the base of the PR and between edf1b31 and 7da586a.

Files selected for processing: 2

  • cuda_pathfinder/cuda/pathfinder/_static_libs/find_bitcode_lib.py
  • cuda_pathfinder/tests/test_find_bitcode_lib.py

Included review availability: This review used your included allowance. Your plan provides up to 12 included reviews per hour; 11 remain after this review.

@github-actions

Copy link
Copy Markdown
Contributor

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cuda.pathfinder Everything related to the cuda.pathfinder module

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant