cubecl-hip-sys 6.2.4000

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:

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

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
cargo xtask test -v rocm_622

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.2.4:

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

3. Declare a new feature in the Cargo.toml of the corresponding crate cubecl-hip-sys with the format rocm_<version> where <version> is the ROCm version without any separator. For instance for the version 6.2.4:

[features]
rocm_624 = []

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

[features]
default = ["rocm_624"]

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 = "rocm_624")]
mod bindings_624;
#[cfg(feature = "rocm_624")]
pub use bindings_624::*;

6. Run the tests as explain in the previous section. Use the new feature you just created. Currently there is no test selection mechanism in place given a ROCm version. If there are errors you can use conditional attributes for now.

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.