cubecl-hip-sys 0.0.6

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


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

| Version | Feature  | Crates         |
|:--------|:---------|:---------------|
| 6.2.2   | rocm_622 | cubecl-hip-sys |

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 and provide the feature that corresponds to your
ROCm installation. For instance for the version `6.2.2`:

```sh
cargo xtask test --features rocm_622
```

## 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.2`:

```sh
cargo xtask bindgen -c cubecl-hip-sys -v 6.2.2
```

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

```toml
[features]
rocm_622 = []
```

4) 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_622")]
mod bindings_622;
#[cfg(feature = "rocm_622")]
pub use bindings_622::*;
```

5) 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.


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.

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