<div align="center">
<img src="https://raw.githubusercontent.com/tracel-ai/cubecl-hip/main/assets/CubeCL.webp" width="256px"/>
<h1>CubeCL Rust bindings for ROCm HIP</h1>
[](https://discord.gg/uPEBbYYDB6)
[](https://crates.io/crates/cubecl-hip-sys)
[](https://crates.io/crates/cubecl-hip-sys)
[](https://github.com/tracel-ai/cubecl-hip/actions/workflows/ci.yml)
---
<br/>
</div>
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][1]:
## Versioning Scheme
The crates in this repository follow the versioning conventions outlined below:
- The latest 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 for the same ROCm version.
### Example:
The `cubecl-hip-sys` version `6.2.4000` represents the first release with ROCm `6.2.4`.
If a fix is required and the ROCm version remains `6.2.4`, the `cubecl-hip-sys` version is incremented to `6.2.4001`.
## Usage
Add the crate [cubecl-hip-sys][2] to the `Cargo.toml` file of your project and enable the feature
corresponding to the version of ROCm you have installed.
If no feature is provided then the build script will attempt to find the default ROCm version installed on your system.
Read the `warning` messages in the build output to learn about the script behavior.
```toml
cubecl-hip-sys = { version = "6.3.1000", features = ["rocm__6_3_1"] }
```
If you installed a newer ROCm version that is not yet supported by this crate 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:
| 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 |
| 6.3.1 | rocm__6_3_1 | cubecl-hip-sys |
| 6.3.2 | rocm__6_3_2 | cubecl-hip-sys |
Here is a table of the libraries covered by each crate:
| 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 by providing the version of ROCm to test, for instance `-v 6.2.2`:
```sh
# test ROCm bindings againt the system default ROCm installation if found
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`:
```sh
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.
```toml
[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.
```toml
[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`.
```toml
[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:
```rs
#[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.
[1]: https://rocmdocs.amd.com/projects/install-on-linux/en/latest/install/detailed-install.html
[2]: https://crates.io/crates/cubecl-hip-sys