Unrolled build for #149990

Rollup merge of #149990 - Flakebi:improve-amdgpu-docs, r=ehuss

Improve amdgpu docs: Mention device-libs and xnack

Mention amdgpu-device-libs for allocator and println support and mention the necessary target flag for GPUs from some some series without xnack support.

For the last half year, there were no major changes in the amdgpu-device-libs crate (in fact, there was no need to update the crate), so I believe it is stable enough to mention it here.

The xnack-support flag is something I stumbled upon recently, when more complex printlns failed on a certain GPU.

Tracking issue: #135024

Author: rust-timer

src/doc/rustc/src/platform-support/amdgcn-amd-amdhsa.md

@@ -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
 
@@ -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
@@ -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"
@@ -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
 
@@ -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