System and Configuration
Checking the installation
AMDGPU.versioninfo() prints a full report of detected ROCm libraries, their versions, and the available devices. AMDGPU.functional() returns whether AMDGPU.jl can run at all, and AMDGPU.functional(component) queries an individual ROCm component (see FAQ for the component list). has_rocm_gpu() additionally requires that a GPU device is present.
AMDGPU.versioninfo Function
versioninfo(io::IO=stdout)Print a report of the AMDGPU.jl setup: detected ROCm libraries and their versions, tool paths, and the available GPU devices. Useful as a first diagnostic when something is missing or not working.
sourceAMDGPU.functional Function
functional() -> BoolReturns true if AMDGPU is nominally functional; "functional" currently means that HSA, HIP, lld, and device libraries are available (although it does not imply that usages of these components will be successful).
Packages may use the result of this query to determine whether it is safe to:
Use AMDGPU to compile code
Query devices, queues, and other runtime state
Launch compiled kernels on a device
Wait on launched kernels to complete
Utilize external ROCm libraries (rocBLAS et. al)
If the full compilation and launch pipeline is desired, then this query should be sufficient for most packages and applications. This query combines sub-queries of multiple components; a failing sub-query will propagate to a false return value. For more fine-grained queries, use functional(::Symbol).
This query should never throw.
sourcefunctional(component::Symbol) -> BoolReturns true if the ROCm component component is configured and expected to function correctly. Available component values are:
:hip- Queries HIP library availability:lld- Queries kernel linker (libamdgpu) availability:device_libs- Queries ROCm device libraries availability:rocblas- Queries rocBLAS library availability:rocsolver- Queries rocSOLVER library availability:rocsparse- Queries rocSPARSE library availability:rocrand- Queries rocRAND library availability:rocfft- Queries rocFFT library availability:hiptensor- Queries hipTENSOR library availability, whether every present device has an architecture supported by it, and whether it exports the C API (ROCm 7.2+) at a version at least that of the headers the bindings were generated from:MIOpen- Queries MIOpen library availability:all- Queries all above components
This query should never throw for valid component values.
AMDGPU.has_rocm_gpu Function
has_rocm_gpu() -> BoolReturn true if HIP is functional and at least one GPU device is present. Use this to guard code that specifically requires GPU hardware; for a general "can AMDGPU.jl run here" check prefer AMDGPU.functional.
Choosing the ROCm provider
By default the ROCm runtime and libraries are downloaded as artifacts. See Installation for using a local ROCm installation instead.
AMDGPU.set_rocm_version! Function
AMDGPU.set_rocm_version!([version::VersionNumber]; [local_rocm::Bool], [arch])Configure the active project to use a specific ROCm version from a specific source.
If local_rocm is set, the ROCm runtime and libraries will be used from the local system, otherwise they will be downloaded from an artifact source. In the case of a local ROCm, version informs AMDGPU.jl which version that is (this may be useful if auto-detection fails). In the case of artifact sources, version controls which version will be downloaded and used.
arch overrides the GPU architectures the artifact is selected for, given either as a single gfx target ("gfx942") or as a collection of them. It is only needed when the GPUs of the host cannot be detected, for example when preparing a depot on a machine without an AMD GPU, and has no effect when a local ROCm is used.
When not specifying any of the version, local_rocm or arch arguments, the default behavior will be used, which is to use the most recent compatible artifacts. Note that this will override any preferences that may be configured in a higher-up depot; to clear preferences nondestructively, use AMDGPU.reset_rocm_version! instead.
AMDGPU.reset_rocm_version! Function
AMDGPU.reset_rocm_version!()Reset the ROCm preferences in the active project to the default, which is to use the most recent compatible artifacts, unless a higher-up depot has configured a different preference. To force use of the default behavior for the local project, use AMDGPU.set_rocm_version! with no arguments.
Configuration preferences
Several behaviours are configured through Preferences.jl and persist across sessions (they are written to your project's LocalPreferences.toml):
| Preference | Set via | Effect |
|---|---|---|
nonblocking_synchronization | preference | Use non-blocking stream synchronization (default true); disable for slightly lower latency. See Streams. |
eager_gc | AMDGPU.eager_gc!(::Bool) | Trigger GC before allocations under memory pressure. See Memory Allocation and Intrinsics. |
hard_memory_limit | AMDGPU.hard_memory_limit!("8 GiB") | Hard cap on GPU memory, checked before every allocation. |
soft_memory_limit | AMDGPU.soft_memory_limit!("6 GiB") | Advisory limit for the memory pool. |
system_scope_fences | AMDGPU.system_scope_fences!(true) | Write back the GPU cache after every kernel (default "auto"), needed on the integrated GPU of Ryzen 7000/9000 CPUs. See FAQ. Takes effect after a restart. |
local | AMDGPU.set_rocm_version!(local_rocm=true) | Use a local ROCm installation instead of the artifacts. See Installation. Takes effect after a restart. |
version | AMDGPU.set_rocm_version!(v"10.1") | ROCm release the artifacts are taken from (default: the newest). Takes effect after a restart. |
arch | AMDGPU.set_rocm_version!(arch="gfx942") | GPU architectures to select the artifacts for, when they cannot be detected. Takes effect after a restart. |
The local, version and arch preferences belong to the ROCm_Runtime package, so in LocalPreferences.toml they go under [ROCm_Runtime] rather than [AMDGPU]. See Installation for setting them by hand.
Debugging kernel launches
Set the environment variable HIP_LAUNCH_BLOCKING=1 (or toggle AMDGPU.LAUNCH_BLOCKING[] = true at runtime) to make kernel launches synchronous. This makes errors surface at the offending launch rather than at a later synchronization point, which is invaluable when tracking down a crashing or misbehaving kernel.