CubeCL Rust bindings for ROCm HIP

---

This repository contains Rust bindings for AMD ROCm HIP runtime libraries used by CubeCL.

⚠️ Notes

These bindings are unsafe as they are just the raw bindings generated by bindgen with no improvements.

Limitations

• Works only on Linux
• Bindings generated for AMD GPUs only

Prerequisites

Install ROCm in the default directory under /opt following the ROCm documentation:

Versioning Scheme

The crates in this repository follow the versioning conventions outlined below:

• The default supported ROCm version of the crates is used as the base version.
• The patch version of the ROCm release is multiplied by 1000, allowing multiple revisions of a crate that defaults to the same ROCm version.

Example:

The cubecl-hip-sys version 6.2.4000 represents the first release with ROCm 6.2.4 as the default. If a fix is required and the default ROCm version remains 6.2.4, the cubecl-hip-sys version is incremented to 6.2.4001.

Usage

Add the crate cubecl-hip-sys to the Cargo.toml of your project and enable the feature corresponding to the version of ROCm you have installed. If you no feature corresponds to your ROCm installation then read the next section to learn how to generate and submit new bindings for your version.

Next you need to point out where you installed ROCm so that rustc can link to your ROCM libraries. To do so set the variable ROCM_PATH, or HIP_PATH or the more specific CUBECL_ROCM_PATH to its installation base directory, it is often /opt/rocm.

Here is the table of currently available bindings:

ROCm Version	Feature	Crates
6.2.2	rocm__6_2_2	cubecl-hip-sys
6.2.4	rocm__6_2_4	cubecl-hip-sys
6.3.0	rocm__6_3_0	cubecl-hip-sys

Here is a table of the libraries covered by each crate:

Crate	ROCm libraries
cubecl-hip-sys	hiprtc, amdhip64

Running tests

To run tests you need to first meet the expectations for both Prerequisites and Usage sections.

Then execute the following xtask command. If you want to test against a different version of ROCm than the default one, use the -v <version>, for instance -v 6.2.2:

# test default ROCm bindings
cargo xtask test
# test a specific version that is not the default
cargo xtask test -v 6.2.2

Important: always make sure that ROCm environment variable (see Usage) points to a version that matches the tested version.

Generate bindings for a given version of ROCm

1. To generate the bindings you need to first meet the expectations for both Prerequisites and Usage sections.

2. Generate the bindings using the dedicated xtask command bindgen. For instance, to generate the bindings for the crate cubecl-hip-sys and the ROCm version 6.3.0:

cargo xtask bindgen -c cubecl-hip-sys -v 6.3.0

3. If the HIP bindings patch version has changed, declare a new hip feature in the Cargo.toml of the corresponding crate cubecl-hip-sys with the format hip_<patch_version>. For instance the version 6.3.0 has a new HIP patch version which is 42131. Is the patch version did not change then skip this step.

[features]
hip_42131 = []

4. Declare a new rocm feature in the Cargo.toml of the corresponding crate cubecl-hip-sys with the format rocm__<version> where <version> is the ROCm version with _ separator and add a dependency on its corresponding HIP bindings patch version. Note that sometimes the HIP bindings are not changed between two version of ROCm, in this case reuse the already existing hip feature.

[features]
rocm__6_3_0 = [ "hip_42131" ]

4. Replace the default feature in the Cargo.toml file be the latest one, in this case rocm__6_3_0.

[features]
default = ["rocm__6_3_0"]

5. Add the generated bindings module to the file crates/cubecl-hip-sys/src/bindings/mod.rs conditionally to the new feature you just declared as well as the re-exports:

#[cfg(feature = "hip_42131")]
mod bindings_42131;
#[cfg(feature = "hip_42131")]
pub use bindings_42131::*;

6. Run the tests as explain in the previous section using the new feature you just created.

7. Open a pull request with the modifications, do not forget to add the new generated bindings file in the crates/cubecl-hip-sys/src/bindings/ directory.

8. Note that the CI runner might need to be updated by an administrator to install the new version of ROCm.