Skip to content

Improve amdgpu docs: Mention device-libs and xnack #149990

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bors merged 1 commit into from
Dec 15, 2025
+9 −4
Merged

Improve amdgpu docs: Mention device-libs and xnack #149990

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 9 additions & 4 deletions src/doc/rustc/src/platform-support/amdgcn-amd-amdhsa.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,8 @@ The format of binaries is a linked ELF.

Binaries must be built with no-std.
They can use `core` and `alloc` (`alloc` only if an allocator is supplied).
At least one function needs to use the `"gpu-kernel"` calling convention and should be marked with `no_mangle` for simplicity.
Functions using the `"gpu-kernel"` calling convention are kernel entrypoints and can be used from the host runtime.
At least one function should use the `"gpu-kernel"` calling convention and should be marked with `no_mangle` or `export_name`.
Functions using the `"gpu-kernel"` calling convention are kernel entrypoints and can be launched from the host runtime.

## Building the target

Expand All @@ -34,6 +34,9 @@ The generations are exposed as different target-cpus in the backend.
As there are many, Rust does not ship pre-compiled libraries for this target.
Therefore, you have to build your own copy of `core` by using `cargo -Zbuild-std=core` or similar.

An allocator and `println!()` support is provided by the [`amdgpu-device-libs`] crate.
Both features rely on the [HIP] runtime.

To build a binary, create a no-std library:
```rust,ignore (platform-specific)
// src/lib.rs
Expand Down Expand Up @@ -65,13 +68,16 @@ lto = true

The target-cpu must be from the list [supported by LLVM] (or printed with `rustc --target amdgcn-amd-amdhsa --print target-cpus`).
The GPU version on the current system can be found e.g. with [`rocminfo`].
For a GPU series that has xnack support but the target GPU has not, the `-xnack-support` target-feature needs to be enabled.
I.e. if the ISA info as printed with [`rocminfo`] says something about `xnack-`, e.g. `gfx1010:xnack-`, add `-Ctarget-feature=-xnack-support` to the rustflags.

Example `.cargo/config.toml` file to set the target and GPU generation:
```toml
# .cargo/config.toml
[build]
target = "amdgcn-amd-amdhsa"
rustflags = ["-Ctarget-cpu=gfx1100"]
# Add "-Ctarget-feature=-xnack-support" for xnack- GPUs (see above)

[unstable]
build-std = ["core"] # Optional: "alloc"
Expand All @@ -85,8 +91,6 @@ Example code on how to load a compiled binary and run it is available in [ROCm e

On Linux, binaries can also run through the HSA runtime as implemented in [ROCR-Runtime].

<!-- Mention an allocator once a suitable one exists for amdgpu -->

<!--
## Testing

Expand All @@ -109,3 +113,4 @@ More information can be found on the [LLVM page for amdgpu].
[LLVM page for amdgpu]: https://llvm.org/docs/AMDGPUUsage.html
[`rocminfo`]: https://github.com/ROCm/rocminfo
[ROCm examples]: https://github.com/ROCm/rocm-examples/tree/ca8ef5b6f1390176616cd1c18fbc98785cbc73f6/HIP-Basic/module_api
[`amdgpu-device-libs`]: https://crates.io/crates/amdgpu-device-libs
Loading