From c4ec5c316516c22578ac74a6d4fc8ecf9461ffc1 Mon Sep 17 00:00:00 2001 From: Julia Jiang Date: Fri, 26 Jan 2024 14:03:06 -0500 Subject: [PATCH] SWDEV-443289 - Update build HIP instructions Change-Id: Iaf198a43ea76cd5257201f648510260d3feb567c [ROCm/hip commit: b26160f70ed4bbc785f2b0376f619776f2ac595a] --- projects/hip/docs/developer_guide/build.md | 80 +++++++++------------- projects/hip/docs/user_guide/faq.md | 5 ++ 2 files changed, 37 insertions(+), 48 deletions(-) diff --git a/projects/hip/docs/developer_guide/build.md b/projects/hip/docs/developer_guide/build.md index 94e5f795b5..b13f6f0d5c 100755 --- a/projects/hip/docs/developer_guide/build.md +++ b/projects/hip/docs/developer_guide/build.md @@ -23,9 +23,9 @@ Install Nvidia driver and pre-build packages (see HIP Installation Guide at http ### Branch of repository Before get HIP source code, set the expected branch of repository at the variable `ROCM_BRANCH`. -For example, for ROCm6.0 release branch, set +For example, for ROCm 6.1 release branch, set ```shell -export ROCM_BRANCH=rocm-6.0.x +export ROCM_BRANCH=rocm-6.1.x ``` ROCm5.7 release branch, set @@ -37,15 +37,19 @@ Similiar format for future branches. `ROCM_PATH` is path where ROCM is installed. BY default `ROCM_PATH` is at `/opt/rocm`. -## Build HIP on AMD platform +## Build HIP ### Get HIP source code +A new repository 'hipother' is added in the ROCm 6.1 release, which is branched out from HIP. +The 'hipother'provides files required to support the HIP back-end implementation on some non-AMD platforms, like NVIDIA. + ```shell -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 +git clone -b "$ROCM_BRANCH" https://github.com/ROCm/clr.git +git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hip.git +git clone -b "$ROCM_BRANCH" https://github.com/ROCm/hipother.git +git clone -b "$ROCM_BRANCH" https://github.com/ROCm/HIPCC.git hipcc ``` ### Set the environment variables @@ -53,13 +57,15 @@ git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/HIPCC.git ```shell export CLR_DIR="$(readlink -f clr)" export HIP_DIR="$(readlink -f hip)" -export HIPCC_DIR="$(readlink -f HIPCC)" +export HIP_OTHER="$(readlink -f hipother)" +export HIPCC_DIR="$(readlink -f hipcc)" ``` Note, starting from ROCM 5.6 release, clr is a new repository including the previous ROCclr, HIPAMD and OpenCl repositories. ROCclr is defined on AMD platform that HIP uses Radeon Open Compute Common Language Runtime (ROCclr), which is a virtual device interface that HIP runtimes interact with different backends. -HIPAMD provides implementation specifically for AMD platform. +HIPAMD provides implementation specifically for the AMD platform. OpenCL provides headers that ROCclr runtime currently depends on. +hipother provides headers and implementation specifically for the non-AMD platform, like NVIDIA. ### Build the HIPCC runtime @@ -70,13 +76,15 @@ cmake .. make -j4 ``` -### Build HIP +### Build HIP on the AMD platform + +#### Build HIP runtime +Commands to build HIP runtime on the AMD platform are as following. The option 'HIP_PLATFORM=amd' should be defined. ```shell 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 ``` @@ -85,7 +93,7 @@ Note, if `CMAKE_INSTALL_PREFIX` is not specified, hip runtime will be installed By default, release version of HIP is built. -### Default paths and environment variables +#### Default paths and environment variables * By default HIP looks for HSA in `/hsa` (can be overridden by setting `HSA_PATH` environment variable). * By default HIP is installed into `/hip`. @@ -94,7 +102,7 @@ By default, release version of HIP is built. * Optionally, consider adding `/bin` to your `PATH` to make it easier to use the tools. * Optionally, set `HIPCC_VERBOSE=7` to output the command line for compilation. -### Generating profiling header after adding/changing a HIP API +#### Generate profiling header after adding/changing a HIP API When you add or change a HIP API, you must generate a new `hip_prof_str.h` header. ROCm tools like ROCProfiler and ROCTracer use this header to track HIP APIs. To generate the header after your change, use the tool `hip_prof_gen.py` present in `hipamd/src`. @@ -119,16 +127,16 @@ hip_prof_gen.py -v -p -t --priv /include/hip/hip_runtime_api.h \ /include/hip/amd_detail/hip_prof_str.h.new ``` -### Build HIP tests +#### Build HIP tests -HIP catch tests, with new architectured Catch2, are official seperated from HIP project, exist in HIP tests repository, can be built via the following instructions. +HIP catch tests, with the newly architectured Catch2, are officially separated from the HIP project. The HIP catch tests are moved to the HIP tests repository and can be built using the instructions in the following sections. -#### Get HIP tests source code +##### Get HIP tests source code ```shell git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip-tests.git ``` -#### Build HIP tests from source +##### Build HIP tests from source ```shell export HIPTESTS_DIR="$(readlink -f hip-tests)" @@ -156,9 +164,9 @@ cd $HIPTESTS_DIR/build/catch_tests/unit/texture ./TextureTest ``` -#### Build HIP Catch2 standalone test +##### Build HIP Catch2 standalone tests -HIP Catch2 supports build a standalone test, for example, +HIP Catch2 supports building standalone tests, for example, ```shell cd "$HIPTESTS_DIR" @@ -169,48 +177,24 @@ hipcc $HIPTESTS_DIR/catch/unit/memory/hipPointerGetAttributes.cc -I ./catch/incl All tests passed ``` -## Build HIP on NVIDIA platform +### Build HIP on the NVIDIA platform -### Get HIP source code - -```shell -git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/hip.git -git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/clr.git -git clone -b "$ROCM_BRANCH" https://github.com/ROCm-Developer-Tools/HIPCC.git -``` - -### Set the environment variables - -```shell -export HIP_DIR="$(readlink -f hip)" -export CLR_DIR="$(readlink -f hipamd)" -export HIPCC_DIR="$(readlink -f hipcc)" -``` - -### Build the HIPCC runtime - -```shell -cd "$HIPCC_DIR" -mkdir -p build; cd build -cmake .. -make -j4 -``` - -### Build HIP +#### Build HIP runtime +Commands to build HIP on the NVIDIA platform are as following. The options 'HIPNV_DIR=$HIP_OTHER/hipnv' and 'HIP_PLATFORM=nvidia' should be defined. ```shell cd "$CLR_DIR" mkdir -p build; cd build -cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install -DHIPCC_BIN_DIR=$HIPCC_DIR/build -DHIP_CATCH_TEST=0 -DCLR_BUILD_HIP=ON -DCLR_BUILD_OCL=OFF .. +cmake -DHIP_COMMON_DIR=$HIP_DIR -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 -DHIPNV_DIR=$HIP_OTHER/hipnv -DHIP_PLATFORM=nvidia .. make -j$(nproc) sudo make install ``` -### Build HIP tests +#### Build HIP tests Build HIP tests commands on NVIDIA platform are basically the same as AMD, except set `-DHIP_PLATFORM=nvidia`. ## Run HIP -Compile and run the [square sample](https://github.com/ROCm-Developer-Tools/hip-tests/tree/rocm-5.5.x/samples/0_Intro/square). +Compile and run the [square sample](https://github.com/ROCm/hip-tests/tree/rocm-6.0.x/samples/0_Intro/square). diff --git a/projects/hip/docs/user_guide/faq.md b/projects/hip/docs/user_guide/faq.md index e5a3656c49..0bb19f6e59 100644 --- a/projects/hip/docs/user_guide/faq.md +++ b/projects/hip/docs/user_guide/faq.md @@ -146,6 +146,10 @@ ROCclr (Radeon Open Compute Common Language Runtime) is a virtual device interfa ## What is HIPAMD? HIPAMD is a repository branched out from HIP, mainly the implementation for AMD GPU. +## What is hipother? +A new repository 'hipother' is added in the ROCm 6.1 release, which is branched out from HIP. +hipother supports the HIP back-end implementation on some non-AMD platforms, like NVIDIA. + ## Can I get HIP open source repository for Windows? No, there is no HIP repository open publicly on Windows. @@ -324,3 +328,4 @@ hipRuntimeGetVersion(&runtimeVersion); The version returned will always be greater than the versions in previous ROCm releases. Note: The version definition of HIP runtime is different from CUDA. On AMD platform, the function returns HIP runtime version, while on NVIDIA platform, it returns CUDA runtime version. And there is no mapping/correlation between HIP version and CUDA version. +