Crafting CMakeLists.txt: Examples for CMAKE_HIP_ARCHITECTURES

Purpose

• By specifying the architectures, you ensure your code compiles and runs correctly on the targeted hardware.
• Controls which AMD GPU architectures your project generates device code for when using the HIP (Heterogeneous Interface for Programming) programming model.

Availability

• Primarily used when the HIP language is enabled (as opposed to using C++ with HIP libraries).
• Introduced in CMake version 3.21.

Behavior

• If you don't set CMAKE_HIP_ARCHITECTURES explicitly, CMake will:
  • Use the architectures reported by the rocm_agent_enumerator tool (if available).
  • Otherwise, it will default to a compiler-chosen subset of supported architectures.
• CMake interprets these names based on the value of another variable, CMAKE_HIP_PLATFORM. This platform variable defines the underlying system where HIP is running (e.g., linux, windows).
• Stores a semicolon-separated list of GPU architecture names.

Setting the Variable

• You can provide the list of architectures during CMake configuration using the -DCMAKE_HIP_ARCHITECTURES option on the command line:

  cmake -DCMAKE_HIP_ARCHITECTURES="gfx908;gfx1030" your_project_directory
  

  This sets the variable to target the gfx908 and gfx1030 architectures.

Internal Use

• CMAKE_HIP_ARCHITECTURES initializes a CMake property named HIP_ARCHITECTURES on all targets in your project. This property is used internally by CMake to determine the compilation flags for each architecture.

• If you're unsure about the available architectures, consult your ROCm documentation for supported GPUs.
• Explicitly setting CMAKE_HIP_ARCHITECTURES gives you fine-grained control over which architectures your code targets.

---

Example 1: Setting Architectures on the Command Line

# CMakeLists.txt

# This assumes you know the architectures you want to target
set(HIP_ARCHITECTURES "gfx803;gfx900")

# Create an executable target
add_executable(my_hip_program main.hip)

# HIP-specific compilation flags (optional)
target_compile_features(my_hip_program PRIVATE HIP)

In this example:

• The target_compile_features line (optional) ensures HIP-specific compilation flags are used (adjust based on your project's needs).
• We create an executable target named my_hip_program that compiles the main.hip file.
• We define the HIP_ARCHITECTURES variable directly in our CMakeLists.txt file, targeting gfx803 and gfx900 architectures.

# CMakeLists.txt

# Let CMake choose the architectures by default
if(NOT DEFINED CMAKE_HIP_ARCHITECTURES)
  # Optional: Provide a hint for CMake's default selection
  set(CMAKE_HIP_ARCHITECTURES_DEFAULT "gfx906;gfx1030")
endif()

# Create an executable target
add_executable(my_hip_program main.hip)

# HIP-specific compilation flags (optional)
target_compile_features(my_hip_program PRIVATE HIP)

• We proceed to create the executable target and add compilation flags as before.
• We check if CMAKE_HIP_ARCHITECTURES is already defined. If not, we provide an optional default set of architectures using CMAKE_HIP_ARCHITECTURES_DEFAULT. This can be helpful when you're unsure of the exact architectures or want users to configure them at build time.

---

Environment Variables

• CUDA_VISIBLE_DEVICES
  If your project interacts with both CUDA and HIP code, you can use CUDA_VISIBLE_DEVICES to control which GPUs are visible to the system at runtime. This can indirectly impact HIP code execution by limiting the available hardware.
  • However, this approach has limitations:
    • It doesn't directly influence the build process or code generation.
    • If you need to target specific architectures during compilation, it wouldn't be suitable.

Build System Flags

• Target-Specific Compilation
  If your build system allows for target-specific compilation options, you might be able to configure different targets for different architecture groups. This could involve creating separate build configurations or using conditional compilation within your source code.
  • This approach requires modifying your build system, which might not be ideal for portable projects using CMake.

• In some cases, HIP provides runtime APIs for querying available architectures. You could potentially use this information within your code to adapt to the available hardware.
  • This method is generally less flexible for build-time configuration and might introduce runtime overhead.