rocm-sys 0.1.0

ROCm system bindings configured by release version
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

# `rocm-sys`


FFI bindings to C for ROCm, explicitly checks for correct ROCm versions and function calls are guarnateed to be safe provided their prerequisites defined by AMDs documentation.

## Disclaimer


This project is not affiliated with, endorsed by, or sponsored by Advanced Micro Devices, Inc. (AMD).

ROCm and AMD are trademarks of Advanced Micro Devices, Inc.

## Usage


This is a very unsafe and low-level API. For a safer API, use `rocmarc`.

```rust
let mut count = -1;

unsafe {
    hipGetDeviceCount(&mut count);
}

println!("device count = {count}");
```

* This will output `device count = -1` or `device count = 0` on failure or `device count = N` where `N >= 1` on success
* All `hip*` functions return a `hipError_t`

## Dynamic Loading vs Static Linking


The API is the same regardless of whether you use dynamic loading or static linking, but the functionality is different. If building for a generic target, use dynamic loading. If running on the build machine, static linking is faster.

|                          | Dynamic | Static |
|--------------------------|---------|--------|
| Runtime Checks           | Y       | N      |
| Portable Across Hardware | Y       | N      |
| Compile-Time Linking     | N       | Y      |

To enable dynamic loading, enable the cargo feature `dynamic-loading`.

When using static linking, all functions are just `extern "C"` functions wrapped in `extern "Rust"` functions with some compile-time ROCm version checks when applicable.

### Linker Errors


When using static linking, a linker error may occur when a function is linked which is not available in the installed ROCm version. Most likely, this is a result of a function being removed in a recent ROCm release or an incorrect feature check.

## Assumptions


This crate tries to assume as little about the target as possible.

- If `dynamic-loading` feature is disabled, the target is assumed to be the build machine
- The size of a Rust `usize` should be equal to the size of a C `size_t`
- `hipGetDeviceProperties` and `hipChooseDevice` are only correct profided `hipDeviceProp_tR0600` = `hipDeviceProp_t`

Try to avoid these. Device properties may get patched in the future.

## Maintenance


All functions are hand-written (albeit using a macro) and types are auto-generated using bindgen.

Functions must be hand-written because they have version checks which bindgen doesnt make automatically. The API is as close to the C API as possible (template functions make this hard).

This is maintained separately from `rocmarc` because functions are all hand-written.