Use hipconfig in build script (#19)

* Use hipconfig to get the ROCm and HIP installation paths

* Simplify HIP version detection by using hipconfig as source of truth

* Rename build_script.rs to hipconfig.rs

Author: syl20bnr

Cargo.lock

@@ -1,26 +1,27 @@
 [workspace]
-    # Try
-    # require version 2 to avoid "feature" additiveness for dev-dependencies
-    # https://doc.rust-lang.org/cargo/reference/resolver.html#feature-resolver-version-2
-    resolver = "2"
+# Try
+# require version 2 to avoid "feature" additiveness for dev-dependencies
+# https://doc.rust-lang.org/cargo/reference/resolver.html#feature-resolver-version-2
+resolver = "2"
 
-    members = ["crates/*", "xtask"]
+members = ["crates/*", "xtask"]
 
-    [workspace.package]
-        edition = "2021"
-        license = "MIT OR Apache-2.0"
-        readme  = "README.md"
-        version = "6.4.0"
+[workspace.package]
+edition = "2021"
+license = "MIT OR Apache-2.0"
+readme  = "README.md"
+version = "6.4.43482"
 
-    [workspace.dependencies]
-        bindgen = "0.70.1"
-        libc    = "0.2.159"
-        log     = "0.4.22"
-        rstest  = "0.2.1"
-        strum   = {version = "0.26.3", features = ["derive"]}
+[workspace.dependencies]
+bindgen = "0.70.1"
+libc    = "0.2.159"
+log     = "0.4.22"
+regex   = "1.11.1"
+rstest  = "0.25.0"
+strum   = {version = "0.26.3", features = ["derive"]}
 
-        ### For xtask crate ###
-        tracel-xtask = {version = "=1.1.8"}
+### For xtask crate ###
+tracel-xtask = {version = "=1.1.8"}
 
 [profile.dev]
-    debug = 0 # Speed up compilation time and not necessary.
+debug = 0 # Speed up compilation time and not necessary.

Cargo.toml

@@ -14,7 +14,7 @@
 <br/>
 </div>
 
-This repository contains Rust bindings for AMD ROCm HIP runtime libraries used by CubeCL.
+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.
@@ -26,107 +26,79 @@ These bindings are unsafe as they are just the raw bindings generated by bindgen
 
 ## Prerequisites
 
-Install ROCm in the default directory under `/opt` following the [ROCm documentation][1]:
+Install ROCm 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.
+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 indentify the version of HIP.
 
-### Example:
+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.
 
-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`.
+Note also that multiple versions of ROCm can ship the same version of HIP.
 
-## Usage
+### Example:
 
-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.
+The `cubecl-hip-sys` version `6.4.43482` represents the HIP with the same version `6.4.43482`.
 
-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.
+## Usage
 
-```toml
-cubecl-hip-sys = { version = "6.3.1000", features = ["rocm__6_3_1"] }
-```
+Add the crate [cubecl-hip-sys][2] to the `Cargo.toml` file of your project. If no feature is set then cargo will select the HIP
+version returned by the `hipconfig` utility.
 
-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.
+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`.
 
-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`.
+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 currently available bindings:
 
-| ROCm Version | Feature     | Crates         |
-|:-------------|:------------|:---------------|
-| 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 |
-| 6.3.3        | rocm__6_3_3 | cubecl-hip-sys |
-| 6.3.4        | rocm__6_3_4 | cubecl-hip-sys |
-| 6.4.0        | rocm__6_4_0 | cubecl-hip-sys |
-
-Here is a table of the libraries covered by each crate:
-
-| Crate          | ROCm libraries   |
-|:---------------|:-----------------|
-| cubecl-hip-sys | hiprtc, amdhip64 |
+| HIP Version | Corresponding ROCm Version Range |
+|:------------|:---------------------------------|
+| 41134       | 6.2.2~6.2.4                      |
+| 42131       | 6.3.0                            |
+| 42133       | 6.3.1                            |
+| 42134       | 6.3.2~6.3.4                      |
+| 43482       | 6.4.0                            |
 
 ## Running tests
 
-To run tests you need to first meet the expectations for both `Prerequisites` and `Usage`
-sections.
+To run tests you need to first meet the expectations for `Prerequisites` section.
 
-Then execute the following xtask command by providing the version of ROCm to test, for instance `-v 6.2.2`:
+Then execute the following xtask command:
 
 ```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
+# test a specific version that is not the default by providing a value for HIP_PATH using -p
+xtask test -p /opt/rocm-6.3.0
 ```
 
-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.
+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.
 
-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`:
+3) Generate the bindings using the dedicated xtask command `bindgen`:
 
 ```sh
-cargo xtask bindgen -c cubecl-hip-sys -v 6.3.0
+cargo xtask bindgen
 ```
 
-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.
+4) Declare a new `hip` feature in the `Cargo.toml` in `cubecl-hip-sys` crate with the format
+`hip_<patch_version>`. You can retrieve the patch version with the command `hipconfig --version`.
+For instance for a new HIP patch version which is `42131` add the following feature:
 
 ```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) Add the generated bindings module to the file `crates/cubecl-hip-sys/src/bindings/mod.rs`
+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
@@ -136,12 +108,13 @@ mod bindings_42131;
 pub use bindings_42131::*;
 ```
 
-5) Run the tests as explain in the previous section using the new feature you just created.
+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 to install the new version of ROCm.
+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

README.md

@@ -1,38 +1,31 @@
 [package]
-    authors           = ["Tracel Technologies Inc."]
-    categories        = ["external-ffi-bindings"]
-    description       = "Rust bindings for AMD ROCm HIP runtime libraries used by CubeCL."
-    edition.workspace = true
-    keywords          = ["cubecl", "ROCm", "HIP", "API", "bindings"]
-    license.workspace = true
-    name              = "cubecl-hip-sys"
-    readme.workspace  = true
-    repository        = "https://github.com/tracel-ai/cubecl-hip/tree/main/crates/cubecl-hip-sys"
-    rust-version      = "1.81"
-    version.workspace = true
+authors           = ["Tracel Technologies Inc."]
+categories        = ["external-ffi-bindings"]
+description       = "Rust bindings for AMD ROCm HIP runtime libraries used by CubeCL."
+edition.workspace = true
+keywords          = ["cubecl", "ROCm", "HIP", "API", "bindings"]
+license.workspace = true
+name              = "cubecl-hip-sys"
+readme.workspace  = true
+repository        = "https://github.com/tracel-ai/cubecl-hip/tree/main/crates/cubecl-hip-sys"
+rust-version      = "1.81"
+version.workspace = true
 
 [features]
-    default = []
-
-    # ROCm versions
-    rocm__6_2_2 = ["hip_41134"]
-    rocm__6_2_4 = ["hip_41134"]
-    rocm__6_3_0 = ["hip_42131"]
-    rocm__6_3_1 = ["hip_42133"]
-    rocm__6_3_2 = ["hip_42134"]
-    rocm__6_3_3 = ["hip_42134"]
-    rocm__6_3_4 = ["hip_42134"]
-    rocm__6_4_0 = ["hip_43482"]
-
-    # HIP versions
-    hip_41134 = []
-    hip_42131 = []
-    hip_42133 = []
-    hip_42134 = []
-    hip_43482 = []
+default = []
+# supported HIP patch versions
+hip_41134 = []
+hip_42131 = []
+hip_42133 = []
+hip_42134 = []
+hip_43482 = []
 
 [dependencies]
-    libc = {workspace = true}
+libc = {workspace = true}
+regex = {workspace = true}
 
 [dev-dependencies]
-    rstest = {workspace = true}
+rstest = {workspace = true}
+
+[build-dependencies]
+regex = {workspace = true}