|
| 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 | +The default binary format is ELF. |
| 15 | +Binaries can be loaded by the HSA runtime implemented in [ROCR-Runtime]. |
| 16 | + |
| 17 | +Binaries must be built with no-std. |
| 18 | +They can use `core` and `alloc` (`alloc` only if an allocator is supplied). |
| 19 | +At least one function needs to use the `"amdgpu-kernel"` calling convention. |
| 20 | +These functions can be used as kernel entrypoints in HSA. |
| 21 | + |
| 22 | +## Building the target |
| 23 | + |
| 24 | +The target is included in rustc. |
| 25 | + |
| 26 | +## Building Rust programs |
| 27 | + |
| 28 | +The amdgpu target supports many hardware generations, which need different binaries. |
| 29 | +The generations are all exposed as different target-cpus in the backend. |
| 30 | +As there are many, Rust does not ship pre-compiled libraries for this target. |
| 31 | +Therefore, you have to build your own copy of `core` by using `cargo -Zbuild-std=core` or similar. |
| 32 | + |
| 33 | +To build a binary that can be loaded with HSA, create a no-std library: |
| 34 | +```rust,ignore (platform-specific) |
| 35 | +// src/lib.rs |
| 36 | +#![feature(abi_amdgpu_kernel)] |
| 37 | +#![no_std] |
| 38 | +
|
| 39 | +#[panic_handler] |
| 40 | +fn panic(_: &core::panic::PanicInfo) -> ! { |
| 41 | + loop {} |
| 42 | +} |
| 43 | +
|
| 44 | +#[no_mangle] |
| 45 | +pub extern "amdgpu-kernel" fn kernel(/* Arguments */) { |
| 46 | + // Code |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +Build the library as `cdylib`: |
| 51 | +```toml |
| 52 | +# Cargo.toml |
| 53 | +[lib] |
| 54 | +crate-type = ["cdylib"] |
| 55 | + |
| 56 | +[profile.dev] |
| 57 | +lto = true # LTO must be explicitly enabled for now |
| 58 | +[profile.release] |
| 59 | +lto = true |
| 60 | +``` |
| 61 | + |
| 62 | +The target-cpu must be from the list [supported by LLVM] (or printed with `rustc --target amdgcn-amd-amdhsa --print target-cpus`). |
| 63 | +The GPU version on the current system can be found e.g. with [`rocminfo`]. |
| 64 | + |
| 65 | +Example `.cargo/config.toml` file to set the target and GPU generation: |
| 66 | +```toml |
| 67 | +# .cargo/config.toml |
| 68 | +[build] |
| 69 | +target = "amdgcn-amd-amdhsa" |
| 70 | +rustflags = ["-Ctarget-cpu=gfx1100"] |
| 71 | + |
| 72 | +[unstable] |
| 73 | +build-std = ["core"] # Optional: "alloc" |
| 74 | +``` |
| 75 | + |
| 76 | +<!-- Mention an allocator once a suitable one exists for amdgpu --> |
| 77 | + |
| 78 | +<!-- Mention HSA bindings once they work |
| 79 | +
|
| 80 | +## Testing |
| 81 | +
|
| 82 | +Does the target support running binaries, or do binaries have varying |
| 83 | +expectations that prevent having a standard way to run them? If users can run |
| 84 | +binaries, can they do so in some common emulator, or do they need native |
| 85 | +hardware? Does the target support running the Rust testsuite? |
| 86 | +
|
| 87 | +--> |
| 88 | + |
| 89 | +## Additional information |
| 90 | + |
| 91 | +More information can be found on the [LLVM page for amdgpu] |
| 92 | + |
| 93 | +[ROCR-Runtime]: https://github.com/ROCm/ROCR-Runtime |
| 94 | +[supported by LLVM]: https://llvm.org/docs/AMDGPUUsage.html#processors |
| 95 | +[LLVM page for amdgpu]: https://llvm.org/docs/AMDGPUUsage.html |
| 96 | +[`rocminfo`]: https://github.com/ROCm/rocminfo |
0 commit comments