前提条件

Building HIP from Source — HIP 6.0.32831 Documentation (amd.com)

从源代码构建HIP（Heterogeneous-Compute Interface for Portability）涉及一些先决条件。HIP代码可以在使用HIP-Clang编译器的AMD ROCm平台上开发，也可以在安装了nvcc的NVIDIA CUDA平台上开发。在构建和运行HIP之前，请确保平台上的驱动程序和预构建包已正确安装。

使用包管理器安装ROCm包或预构建的二进制包。更多关于安装ROCm的信息，请参考ROCm安装指南，网址为：https://rocm.docs.amd.com。

sudo apt install mesa-common-dev  
sudo apt install clang  
sudo apt install comgr  
sudo apt-get -y install rocm-dkms  
sudo apt-get install -y libelf-dev

这些命令将安装一些基础的开发工具、Clang编译器、COMGR编译器运行时库以及ROCm内核模块。

仓库分支

在获取HIP源代码之前，需要在变量ROCM_BRANCH中设置预期的仓库分支。例如，对于ROCm 6.0发布分支，执行以下命令：

export ROCM_BRANCH=rocm-6.0.x

对于ROCm 5.7发布分支，执行：

export ROCM_BRANCH=rocm-5.7.x

未来新分支的格式与此类似。

ROCM_PATH是ROCm的安装路径。默认情况下，ROCM_PATH是/opt/rocm。

在AMD平台上构建HIP

获取HIP源代码

git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/clr.git  
git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip.git  
git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/HIPCC.git

或者从github上获取相应版本release源码包。

设置环境变量

export CLR_DIR="$(readlink -f clr)"  
export HIP_DIR="$(readlink -f hip)"  
export HIPCC_DIR="$(readlink -f HIPCC)"

• readlink -f clr：

  • readlink 是一个Unix/Linux命令，用于显示符号链接指向的真实路径。
  • -f 选项告诉 readlink 命令解析所有遇到的符号链接，并返回最终的真实路径。
  • clr 是要查询的符号链接。这条命令会返回 clr 符号链接指向的真实文件或目录的完整路径。

• export CLR_DIR="$(...)"：

  • export 是一个shell命令，用于设置或导出环境变量，这样该变量就可以被子进程访问。
  • CLR_DIR 是要设置的环境变量名。
  • $(...) 是命令替换的语法。它会执行括号内的命令，并替换为命令的输出。所以，$(readlink -f clr) 会被替换为 clr 符号链接的真实路径。

export CLR_DIR="$(readlink -f clr)"  命令的作用是获取 clr 符号链接的真实路径，并将这个路径赋值给环境变量 CLR_DIR，然后导出这个环境变量，以便其他进程可以使用它。

例如，如果 clr 是一个指向 /home/user/some_directory/clr 的符号链接，那么执行这条命令后，CLR_DIR 环境变量就会被设置为 /home/user/some_directory/clr，并且这个变量可以被当前shell及其子进程访问。

注意，从ROCm 5.6版本开始，clr是一个新的仓库，包含了之前的ROCclr、HIPAMD和OpenCl仓库。在AMD平台上，HIP使用Radeon Open Compute Common Language Runtime（ROCclr），这是一个虚拟设备接口，HIP运行时通过它与不同的后端进行交互。HIPAMD为AMD平台提供了特定的实现。OpenCL提供了ROCclr运行时当前所依赖的头文件。

构建HIPCC运行时

cd "$HIPCC_DIR"  
mkdir -p build; cd build  
cmake ..  
make -j4

构建HIP

cd "$CLR_DIR"  
mkdir -p build; cd build  
cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=amd -DCMAKE_PREFIX_PATH="/opt/rocm/" -DCMAKE_INSTALL_PREFIX=$PWD/install -DHIPCC_BIN_DIR=$HIPCC_DIR/build -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF ..  
  
make -j$(nproc)  
sudo make install

注意，如果没有指定CMAKE_INSTALL_PREFIX，HIP运行时将被安装到<ROCM_PATH>/hip。默认情况下，构建的是HIP的发布版本。

在执行 CMake 配置过程中，编译器试图包含 C++ 标准库中的 <cmath> 头文件，但却没有找到。出现这个问题的原因可能是因为 C++ 标准库没有被正确安装或者编译器没有正确地设置来找到它们。

在Ubuntu系统上，C++ 标准库通常随编译器自带，例如GCC/G++或Clang。要查看这些标准库文件的路径，可以使用编译器的内置选项来显示包含路径。以下是如何为G++和Clang执行此操作的示例：

对于G++：

运行以下命令以显示G++搜索头文件的路径：

echo | g++ -v -x c++ -E -

在输出中搜索 #include <...> search starts here: 这一行；列出的路径就是G++用来搜索包括C++标准库在内的所有头文件的路径。

对于Clang：

执行类似的命令以显示Clang搜索头文件的路径：

echo | clang -v -x c++ -E -

同样，在输出中搜索 #include <...> search starts here: 这一行；列出的路径就是Clang搜索头文件的路径。

CMake 在使用ROCM安装的 clang 编译器，需要确保它被正确配置且对应版本的 C++ 标准库路径包含在其搜索路径内。可以通过更新 CMAKE_CXX_FLAGS 来包含标准库头文件路径。

检查CMake脚本是否正确设置了`include_directories`或`target_include_directories`。如果有控制CMake脚本的权限，确保包含C++标准库头文件的目录被正确添加到包含路径中。

默认路径和环境变量

默认情况下，HIP会在<ROCM_PATH>/hsa路径下寻找HSA（可以通过设置HSA_PATH环境变量来覆盖）。

HIP默认会被安装到<ROCM_PATH>/hip路径下。

HIP默认会在<ROCM_PATH>/llvm/bin路径下寻找clang编译器（可以通过设置HIP_CLANG_PATH环境变量来覆盖）。

HIP默认会在<ROCM_PATH>/lib路径下寻找设备库（可以通过设置DEVICE_LIB_PATH环境变量来覆盖）。

可选操作：考虑将<ROCM_PATH>/bin添加到PATH中，这样可以更方便地使用相关工具。

可选操作：设置HIPCC_VERBOSE=7以输出编译时的命令行。

添加/修改HIP API后生成性能分析头文件

当添加或修改HIP API时，必须生成一个新的hip_prof_str.h头文件。ROCm工具（如ROCProfiler和ROCTracer）使用这个头文件来跟踪HIP API。在做出更改后，使用位于hipamd/src目录下的hip_prof_gen.py工具来生成头文件。

使用方法：

hip_prof_gen.py [-v] <输入HIP API .h 文件> <已修补的源码路径> <之前的输出> [<输出>]

标志：

-v - 详细消息
-r - 递归处理源目录
-t - API类型匹配检查
--priv - 私有API检查
-e - 出错时退出模式
-p - HIP_INIT_API宏修补模式
示例用法：

hip_prof_gen.py -v -p -t --priv <hip>/include/hip/hip_runtime_api.h \  
<hipamd>/src <hipamd>/include/hip/amd_detail/hip_prof_str.h \  
<hipamd>/include/hip/amd_detail/hip_prof_str.h.new

上面的命令会读取<hip>/include/hip/hip_runtime_api.h文件，并在<hipamd>/src目录中查找源文件，然后使用这些信息来生成新的性能分析头文件。旧的头文件是<hipamd>/include/hip/amd_detail/hip_prof_str.h，而新的头文件会被保存到<hipamd>/include/hip/amd_detail/hip_prof_str.h.new。

构建HIP测试

HIP的Catch测试，采用新架构的Catch2，已经正式从HIP项目中独立出来，存在于HIP测试仓库中，可以按照以下步骤进行构建。

获取HIP测试源代码

git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip-tests.git

从源代码构建HIP测试

export HIPTESTS_DIR="$(readlink -f hip-tests)"  
cd "$HIPTESTS_DIR"  
mkdir -p build; cd build  
cmake ../catch -DHIP_PLATFORM=amd -DHIP_PATH=$CLR_DIR/build/install # 或者HIP安装的任何路径，例如，/opt/rocm  
make -j$(nproc) build_tests # 构建测试  
cd build/catch_tests && ctest # 运行所有测试

HIP Catch测试会在$HIPTESTS_DIR/build文件夹下构建。注意，当使用ctest时，可以使用不同的ctest选项，例如，运行所有包含关键词hipMemset的测试：

ctest -R hipMemset

使用以下选项会在测试失败时打印失败信息：

ctest --output-on-failure

更多信息请参考：https://cmake.org/cmake/help/v3.5/manual/ctest.1.html。

要运行任何单个Catch测试，例如：

cd $HIPTESTS_DIR/build/catch_tests/unit/texture  
./TextureTest

构建HIP Catch2独立测试

HIP Catch2支持构建独立测试，例如：

cd "$HIPTESTS_DIR"  
hipcc $HIPTESTS_DIR/catch/unit/memory/hipPointerGetAttributes.cc -I ./catch/include ./catch/hipTestMain/standalone_main.cc -I ./catch/external/Catch2 -o hipPointerGetAttributes  
./hipPointerGetAttributes

...

All tests passed

运行HIP

编译和运行hip-tests/samples/0_Intro/square at rocm-6.0.x · ROCm/hip-tests · GitHub