<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 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][2] to the `Cargo.toml` of your project and enable the feature
corresponding to the version of ROCm you have installed.
```toml
cubecl-hip-sys = { version = "6.3.1000", features = ["rocm__6_3_1"] }
```
If 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:
| 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:
| 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`:
```sh
# 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`:
```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