cubecl-hip-sys 6.2.2003

Rust bindings for AMD ROCm HIP runtime libraries used by CubeCL.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129

<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>

[![Discord](https://img.shields.io/discord/1038839012602941528.svg?color=7289da&&logo=discord)](https://discord.gg/uPEBbYYDB6)
[![Current Crates.io Version](https://img.shields.io/crates/v/cubecl-hip-sys)](https://crates.io/crates/cubecl-hip-sys)
[![Minimum Supported Rust Version](https://img.shields.io/crates/msrv/cubecl-hip-sys)](https://crates.io/crates/cubecl-hip-sys)
[![Test Status](https://github.com/tracel-ai/cubecl-hip/actions/workflows/ci.yml/badge.svg)](https://github.com/tracel-ai/cubecl-hip/actions/workflows/ci.yml)
![license](https://shields.io/badge/license-MIT%2FApache--2.0-blue)

---

<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.
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         | Latest create version |
|:-------------|:------------|:---------------|:----------------------|
| 6.2.2        | rocm__6_2_2 | cubecl-hip-sys | 6.2.2003              |
| 6.2.4        | rocm__6_2_4 | cubecl-hip-sys | 6.2.4001              |

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`:

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

```sh
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 with `_` separator. For
instance for the version `6.2.4`:

```toml
[features]
rocm__6_2_4 = []
```

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

```toml
[features]
default = ["rocm__6_2_4"]
```

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 = "rocm__6_2_4")]
mod bindings_624;
#[cfg(feature = "rocm__6_2_4")]
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.

[1]: https://rocmdocs.amd.com/projects/install-on-linux/en/latest/install/detailed-install.html
[2]: https://crates.io/crates/cubecl-hip-sys