|
| 1 | +# `amdgcn-amd-amdhsa` |
| 2 | + |
| 3 | +**Tier: 3** |
| 4 | + |
| 5 | +AMD GPU target for compute/HSA (Heterogeneous System Architecture). |
| 6 | + |
| 7 | +## Target maintainers |
| 8 | + |
| 9 | +- [@Flakebi](https://github.com/Flakebi) |
| 10 | + |
| 11 | +## Requirements |
| 12 | + |
| 13 | +AMD GPUs can be targeted via cross-compilation. |
| 14 | +Supported GPUs depend on the LLVM version that is used by Rust. |
| 15 | +In general, most GPUs starting from gfx7 (Sea Islands/CI) are supported as compilation targets, though older GPUs are not supported by the latest host runtime. |
| 16 | +Details about supported GPUs can be found in [LLVM’s documentation] and [ROCm documentation]. |
| 17 | + |
| 18 | +Binaries can be loaded by [HIP] or by the HSA runtime implemented in [ROCR-Runtime]. |
| 19 | +The format of binaries is a linked ELF. |
| 20 | + |
| 21 | +Binaries must be built with no-std. |
| 22 | +They can use `core` and `alloc` (`alloc` only if an allocator is supplied). |
| 23 | +At least one function needs to use the `"gpu-kernel"` calling convention and should be marked with `no_mangle` for simplicity. |
| 24 | +Functions using the `"gpu-kernel"` calling convention are kernel entrypoints and can be used from the host runtime. |
| 25 | + |
| 26 | +## Building the target |
| 27 | + |
| 28 | +The target is included in rustc. |
| 29 | + |
| 30 | +## Building Rust programs |
| 31 | + |
| 32 | +The amdgpu target supports many hardware generations, which need different binaries. |
| 33 | +The generations are exposed as different target-cpus in the backend. |
| 34 | +As there are many, Rust does not ship pre-compiled libraries for this target. |
| 35 | +Therefore, you have to build your own copy of `core` by using `cargo -Zbuild-std=core` or similar. |
| 36 | + |
| 37 | +To build a binary, create a no-std library: |
| 38 | +```rust,ignore (platform-specific) |
| 39 | +// src/lib.rs |
| 40 | +#![feature(abi_gpu_kernel)] |
| 41 | +#![no_std] |
| 42 | +
|
| 43 | +#[panic_handler] |
| 44 | +fn panic(_: &core::panic::PanicInfo) -> ! { |
| 45 | + loop {} |
| 46 | +} |
| 47 | +
|
| 48 | +#[no_mangle] |
| 49 | +pub extern "gpu-kernel" fn kernel(/* Arguments */) { |
| 50 | + // Code |
| 51 | +} |
| 52 | +``` |
| 53 | + |
| 54 | +Build the library as `cdylib`: |
| 55 | +```toml |
| 56 | +# Cargo.toml |
| 57 | +[lib] |
| 58 | +crate-type = ["cdylib"] |
| 59 | + |
| 60 | +[profile.dev] |
| 61 | +lto = true # LTO must be explicitly enabled for now |
| 62 | +[profile.release] |
| 63 | +lto = true |
| 64 | +``` |
| 65 | + |
| 66 | +The target-cpu must be from the list [supported by LLVM] (or printed with `rustc --target amdgcn-amd-amdhsa --print target-cpus`). |
| 67 | +The GPU version on the current system can be found e.g. with [`rocminfo`]. |
| 68 | + |
| 69 | +Example `.cargo/config.toml` file to set the target and GPU generation: |
| 70 | +```toml |
| 71 | +# .cargo/config.toml |
| 72 | +[build] |
| 73 | +target = "amdgcn-amd-amdhsa" |
| 74 | +rustflags = ["-Ctarget-cpu=gfx1100"] |
| 75 | + |
| 76 | +[unstable] |
| 77 | +build-std = ["core"] # Optional: "alloc" |
| 78 | +``` |
| 79 | + |
| 80 | +## Running Rust programs |
| 81 | + |
| 82 | +To run a binary on an AMD GPU, a host runtime is needed. |
| 83 | +On Linux and Windows, [HIP] can be used to load and run binaries. |
| 84 | +Example code on how to load a compiled binary and run it is available in [ROCm examples]. |
| 85 | + |
| 86 | +On Linux, binaries can also run through the HSA runtime as implemented in [ROCR-Runtime]. |
| 87 | + |
| 88 | +<!-- Mention an allocator once a suitable one exists for amdgpu --> |
| 89 | + |
| 90 | +<!-- |
| 91 | +## Testing |
| 92 | +
|
| 93 | +Does the target support running binaries, or do binaries have varying |
| 94 | +expectations that prevent having a standard way to run them? If users can run |
| 95 | +binaries, can they do so in some common emulator, or do they need native |
| 96 | +hardware? Does the target support running the Rust testsuite? |
| 97 | +
|
| 98 | +--> |
| 99 | + |
| 100 | +## Additional information |
| 101 | + |
| 102 | +More information can be found on the [LLVM page for amdgpu]. |
| 103 | + |
| 104 | +[LLVM’s documentation]: https://llvm.org/docs/AMDGPUUsage.html#processors |
| 105 | +[ROCm documentation]: https://rocmdocs.amd.com |
| 106 | +[HIP]: https://rocm.docs.amd.com/projects/HIP/ |
| 107 | +[ROCR-Runtime]: https://github.com/ROCm/ROCR-Runtime |
| 108 | +[supported by LLVM]: https://llvm.org/docs/AMDGPUUsage.html#processors |
| 109 | +[LLVM page for amdgpu]: https://llvm.org/docs/AMDGPUUsage.html |
| 110 | +[`rocminfo`]: https://github.com/ROCm/rocminfo |
| 111 | +[ROCm examples]: https://github.com/ROCm/rocm-examples/tree/ca8ef5b6f1390176616cd1c18fbc98785cbc73f6/HIP-Basic/module_api |
0 commit comments