[ROCm] Harden HIP version for native library naming and selection

[sstamenk]

Summary

Use the HIP version consistently when naming and selecting ROCm-backend native libraries.

ROCm distribution releases and HIP versions can diverge. The rocm portion of the filename remains the backend identifier, while its numeric suffix now consistently represents the HIP major and minor version at both build time and runtime.

ROCm release metadata remains useful for CI package selection and support diagnostics, but it no longer controls native-library naming or selection.

Changes

Build and packaging

• Keep the existing HIP backend names: COMPUTE_BACKEND=hip and BUILD_HIP.
• Detect the build-time HIP version with hipconfig --version.
• Fail clearly when hipconfig is missing, fails, or returns an unparseable version.
• Name native libraries using the HIP major/minor shortcode:
  • HIP 7.14 → libbitsandbytes_rocm714
  • HIP 10.14 → libbitsandbytes_rocm1014
• Replace the CMake ROCM_VERSION override with HIP_VERSION.
• Accept dotted or compact HIP_VERSION values, for example 7.14, 7.14.1, or 714.
• Require ROCM_PATH for Windows HIP builds.
• Warn before falling back to /opt/rocm on Linux.
• Require hipBLASLt for supported HIP builds and remove the CMake NO_HIPBLASLT build path.
• Validate RUNNER_OS and the dotted ROCm SDK release passed to the CI build script.
• Keep CI’s ROCM_VERSION as SDK/package metadata used for container selection, package installation, and architecture coverage.
• Collect ROCm-backend artifacts independently of the ROCm release/HIP suffix and fail if no matching native library was built.

Runtime library selection

• Use torch.version.hip for ROCm-backend library selection.
• Do not infer or select a native library from torch.version.rocm.
• Discover packaged libraries using strict filename matching.
• Support compact HIP tags with one-digit majors 6–9 and reserved two-digit majors beginning with 1–5.
• Accept dotted or compact values for both BNB_ROCM_VERSION and BNB_CUDA_VERSION.
• Retain BNB_ROCM_VERSION for compatibility; its value selects a HIP-version suffix.
• Warn when an override for the opposite backend is set.
• Select packaged binaries in this order:
  1. exact version;
  2. newest older binary from the same major;
  3. oldest newer binary from the same major;
  4. for the ROCm backend only, repeat the older-first policy across HIP major versions.
• Keep CUDA fallback restricted to the same major version.
• Emit a stronger warning for HIP cross-major fallback because ABI and packaged GPU-architecture compatibility are not guaranteed.

Diagnostics and documentation

• Report CUDA, ROCm, and HIP metadata separately.
• Treat torch.version.rocm as informational metadata and use it only for support diagnostics.
• Treat ROCm 6.3 and older as unsupported; source builds require ROCm 6.4 or newer.
• Document that prebuilt Linux binaries currently begin at ROCm 6.4.4.
• Clarify that rocm identifies the backend while the numeric filename suffix represents HIP major/minor.
• Document fallback ordering and dotted/compact override formats.
• Consolidate CUDA and HIP selection, override, invalid-format, and wrong-backend test coverage.

Validation

• pytest -q tests/test_cuda_setup_evaluator.py — 21 passed
• Ruff lint and formatting checks pass for all modified Python files
• bash -n .github/scripts/build-rocm.sh
• Invalid CI OS and ROCm SDK-version inputs are rejected
• HIP CMake configuration succeeds with the wheel-installed HIP 7.15 SDK
• Automatic detection produces the rocm715 suffix
• Dotted and compact overrides both produce the expected rocm714 suffix
• Invalid HIP_VERSION values fail configuration
• Required hipBLASLt package discovery succeeds
• git diff --check

Compatibility

• There is no backend rename: downstream builds continue to use -DCOMPUTE_BACKEND=hip.
• The native-library prefix remains libbitsandbytes_rocm.
• The CMake filename override is now -DHIP_VERSION=... instead of -DROCM_VERSION=....
• The runtime environment override remains BNB_ROCM_VERSION.
• ROCm cross-major fallback remains best-effort and emits a compatibility warning.

[sstamenk]

Providing a table with various scenarios to better understand the logic. The library is named at build time and looked up by name at runtime. If the names don't match, loading fails.

	Runtime: torch.version.rocm available (new PyTorch) → looks for _rocm71	Runtime: only torch.version.hip (older PyTorch) → looks for _rocm64	Runtime: BNB_ROCM_VERSION=71 → looks for _rocm71
Build: .info/version exists → builds _rocm71	✅ Loads	❌ Fails - rebuild with -DROCM_VERSION=64 or BNB_ROCM_VERSION=71	✅ Loads
Build: -DROCM_VERSION=71 → builds _rocm71	✅ Loads	❌ Fails - rebuild with -DROCM_VERSION=64 or BNB_ROCM_VERSION=71	✅ Loads
Build: hipconfig fallback → builds _rocm64	❌ Fails - rebuild with -DROCM_VERSION=71 or run with BNB_ROCM_VERSION=64	✅ Loads (both wrong but agree)	❌ Fails - override points to 71 but lib is 64

When both -DROCM_VERSION and BNB_ROCM_VERSION are listed as fixes, BNB_ROCM_VERSION is preferred as it doesn't require a rebuild.

In most cases we will hit the first scenario, and everything will be fine. Going forward the ROCm version will become even more common. If for some reason, there is a mismatch in version the user can always override them with either -DROCM_VERSION or BNB_ROCM_VERSION.

Going forward the hip version fallback can be entirely removed once a few versions pass and it is no longer needed for compatibility.

[github-actions]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[sstamenk]

#1889 should address issues seen when using TheRock builds (712 -> 82), this is something I have missed.

@matthewdouglas We might want to hold off a bit on the CMake changes for a later date. The PR changes to the backend naming from hip to rocm people to switch to rocm when building the source and the fallback logic adds a lot of code for not much gain. As long as both runtime look up and build time look up check the HIP version, there shouldn't be an issue in naming. If you want, I can make a separate PR with the unit test changes only or modify this one to just have those changes.

[matthewdouglas]

@sstamenk I agree, let's do any changes (ie rename backend hip -> rocm) on the CMake side separately. I'm going to merge #1889. I'm OK either way if you want to update this PR or just open a new one.

I'm curious, what version of PyTorch adds torch.version.rocm?

[sstamenk]

@matthewdouglas It's available from version 2.10 https://github.com/pytorch/pytorch/blob/release/2.10/tools/generate_torch_version.py#L122

Windows only recently made it possible to do ROCm version lookup during build time (previously only HIP version was available via hipconfig), newer versions of ROCm have the $ROCM_PATH/.info/version file which has the ROCm version so waiting a bit is probably the right move so we can avoid the fallback and just use the ROCm version in the future.

[sstamenk]

I've decided to revive this PR after some issues were raised with library detection during testing of one of the upcoming ROCm releases. I've updated the PR description to match the current behavior.

[matthewdouglas]

LGTM, thanks!