https://github.com/tracel-ai/cubecl-hip-sys
Rust system bindings for AMD ROCm HIP runtime used by CubeCL
https://github.com/tracel-ai/cubecl-hip-sys
bindings hip rocm runtime rust
Last synced: 4 months ago
JSON representation
Rust system bindings for AMD ROCm HIP runtime used by CubeCL
- Host: GitHub
- URL: https://github.com/tracel-ai/cubecl-hip-sys
- Owner: tracel-ai
- License: apache-2.0
- Created: 2024-10-03T13:08:31.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-02-03T19:58:45.000Z (4 months ago)
- Last Synced: 2026-02-04T06:59:32.894Z (4 months ago)
- Topics: bindings, hip, rocm, runtime, rust
- Language: Rust
- Homepage: https://github.com/tracel-ai/cubecl
- Size: 265 KB
- Stars: 15
- Watchers: 2
- Forks: 10
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
CubeCL Rust system bindings for ROCm HIP
[](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)
---
This repository contains Rust bindings for AMD ROCm HIP runtime libraries (hiprtc, amdhip64) 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 following the [ROCm documentation][1]:
## Versioning Scheme
The crates in this repository follow the same versioning as HIP. Note that HIP version is somewhat different than ROCm version.
The patch number of HIP version is a monotonic number that uniquely identify the version of HIP.
Moreover we concatenate two additional digits to the HIP patch version in order to be able to release fixes for the same HIP patch
number.
For instance `7.0.5183100` represents the first release of the bindings for HIP `51831` of ROCm `7.0.x` and `7.0.5183101` represents the second release for these same bindings.
This versioning scheme is in place as of May 2025, any previous version of this crate followed a different versioning scheme based
on ROCm version instead of HIP.
Note also that multiple versions of ROCm can ship the same version of HIP.
## Usage
Add the crate [cubecl-hip-sys][2] to the `Cargo.toml` file of your project. Cargo will select the HIP version returned by
the `hipconfig` utility.
To specify a different version of HIP manually set the environment variable HIP_PATH to a valid HIP installation path. You can
verify that your system points to the expected version with the command `hipconfig --version`.
Remark: Don't set manually the `hip_xxx` feature for this crate. This is the responsibility of the `build.rs` script to set it
accordingly to your `hipconfig` output.
Here is the table of the available bindings versions, the deprecated ones could theoretically still be used but the versioning scheme was not stable.
| HIP Version | ROCm Version Range | Minimum crate version to use |
|:------------|:-------------------|------------------------------|
| 41134 | 6.2.2~6.2.4 | deprecated |
| 42131 | 6.3.0 | deprecated |
| 42133 | 6.3.1 | deprecated |
| 42134 | 6.3.2~6.3.4 | deprecated |
| 43482 | 6.4.0 | 6.4.4348201 |
| 43483 | 6.4.1 | 6.4.4348300 |
| 43484 | 6.4.2~6.4.3 | 6.4.4348400 |
| 51831 | 7.0.0~7.0.1 | 7.0.5183101 |
| 25424 | 7.1.0 | Not released (*) |
| 52802 | 7.1.1 | 7.1.5280200 |
(*) These HIP patch version seems wrong, see reported issue: https://github.com/ROCm/hip/issues/3881
## Running tests
To run tests you need to first meet the expectations for `Prerequisites` section.
Then execute the following xtask command:
```sh
# test ROCm bindings against the system default ROCm installation if found
cargo xtask test
# test a specific version that is not the default by providing a value for HIP_PATH using -p
cargo xtask test -p /opt/rocm-7.0.0
```
## Generate bindings for a given version of ROCm
1) To generate the bindings you first need to meet the expectations for `Prerequisites` section.
2) Make sure that `hipconfig` returns the path of the HIP version you want to wrap. Adapt the `HIP_PATH`
environment variable to point to the version you are interested in.
3) Generate the bindings using the dedicated xtask command `bindgen`:
```sh
cargo xtask bindgen
```
4) Declare a new `hip` feature in the `Cargo.toml` in `cubecl-hip-sys` crate with the format
`hip_`. You can retrieve the patch version with the command `hipconfig --version`.
For instance for a new HIP patch version which is `51831` add the following feature:
```toml
[features]
hip_51831 = []
```
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_51831")]
mod bindings_51831;
#[cfg(feature = "hip_51831")]
pub use bindings_51831::*;
```
5) Run the tests as explain in the previous section.
6) 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.
7) Note that the CI runner might need to be updated by an administrator so that the new HIP version is available
on the runner.
[1]: https://rocmdocs.amd.com/projects/install-on-linux/en/latest/install/detailed-install.html
[2]: https://crates.io/crates/cubecl-hip-sys