From 9a175e1654552dd0adaf675405e2d8ccefd29c34 Mon Sep 17 00:00:00 2001 From: ROCm CI Service Account <66695075+rocm-ci@users.noreply.github.com> Date: Fri, 11 Mar 2022 16:59:44 +0530 Subject: [PATCH] SWDEV-324824 - Split HIP install to two documents (#2546) Change-Id: Idb3b40167cd9c8dd8fde254e00f7891af04811a8 Co-authored-by: Julia Jiang --- INSTALL.md | 158 ++++++------------------------------- docs/markdown/hip_build.md | 137 ++++++++++++++++++++++++++++++++ 2 files changed, 160 insertions(+), 135 deletions(-) create mode 100755 docs/markdown/hip_build.md diff --git a/INSTALL.md b/INSTALL.md index 0aecb06384..6d40178cc8 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -2,65 +2,34 @@ -- [Installing pre-built packages](#installing-pre-built-packages) +- [Install HIP](#installing-hip) * [Prerequisites](#prerequisites) * [AMD Platform](#amd-platform) * [NVIDIA Platform](#nvidia-platform) -- [Building HIP from source on AMD platform](#building-hip-from-source-on-amd-platform) - * [Get HIP source code](#get-hip-source-code) - * [Set the environment variables](#set-the-environment-variables) - * [Build HIP](#build-hip) - * [Default paths and environment variables](#default-paths-and-environment-variables) -- [Building HIP from source on NVIDIA platform](#building-hip-from-source-on-NVIDIA-platform) - * [Get HIP source code](#get-hip-source-code) - * [Set the environment variables](#set-the-environment-variables) - * [Build HIP](#build-hip) - [Verify your installation](#verify-your-installation) +- [How to build HIP from source](#how-to-build-hip-from-source) -# Installing pre-built packages +# Install HIP -HIP can be easily installed using pre-built binary packages using the package manager for your platform. +HIP can be installed either on AMD ROCm platform with HIP-Clang compiler, or a CUDA platform with nvcc installed. + +Note: The version definition for the HIP runtime is different from CUDA. Users can use hipRuntimeGerVersion function, on the AMD platform it returns the HIP runtime version, while on the NVIDIA platform, it returns the CUDA runtime version. There is no mapping or correlation between the HIP version and CUDA version. ## Prerequisites -HIP code can be developed either on AMD ROCm platform using HIP-Clang compiler, or a CUDA platform with nvcc installed. +On AMD platform, see Prerequisite Actions in ROCm_Installation_Guide (https://docs.amd.com/) for the release. +On NVIDIA platform, check system requirements in NVIDIA CUDA Installation Guide at https://docs.nvidia.com/cuda/cuda-installation-guide-linux/. + ## AMD Platform -ROCM_PATH is path where ROCM is installed. BY default ROCM_PATH is /opt/rocm. -``` -sudo apt install mesa-common-dev -sudo apt install clang -sudo apt install comgr -sudo apt-get -y install rocm-dkms -``` -Public link for Rocm installation -https://rocmdocs.amd.com/en/latest/Installation_Guide/Installation-Guide.html -HIP-Clang is the compiler for compiling HIP programs on AMD platform. +HIP is part of ROCM packages, it will be automatically installed following the ROCm Installation Guide on AMD public documentation site (https://docs.amd.com/) for the coresponding ROCm release. + +By default, HIP is installed into /opt/rocm/hip. -HIP-Clang can be built manually: -``` -git clone -b amd-stg-open https://github.com/RadeonOpenCompute/llvm-project.git -cd llvm-project -mkdir -p build && cd build -cmake -DCMAKE_INSTALL_PREFIX=/llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_ASSERTIONS=1 -DLLVM_TARGETS_TO_BUILD="AMDGPU;X86" -DLLVM_ENABLE_PROJECTS="clang;lld;compiler-rt" ../llvm -make -j -sudo make install -``` -Rocm device library can be manually built as following, -``` -export PATH=/llvm/bin:$PATH -git clone -b amd-stg-open https://github.com/RadeonOpenCompute/ROCm-Device-Libs.git -cd ROCm-Device-Libs -mkdir -p build && cd build -CC=clang CXX=clang++ cmake -DLLVM_DIR=/llvm -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_WERROR=1 -DLLVM_ENABLE_ASSERTIONS=1 -DCMAKE_INSTALL_PREFIX= .. -make -j -sudo make install -``` ## NVIDIA Platform -HIP-nvcc is the compiler for HIP program compilation on NVIDIA platform. * Install Nvidia Driver ``` @@ -70,107 +39,26 @@ sudo reboot Or download the latest cuda-toolkit at https://developer.nvidia.com/cuda-downloads The driver will be installed automatically. -* Add the ROCm package server to your system as per the OS-specific guide available [here](https://rocm.github.io/ROCmInstall.html#installing-from-amd-rocm-repositories). -* Install the "hip-runtime-nvidia" and "hip-dev" package. This will install CUDA SDK and the HIP porting layer. +* Add the ROCm package server to your system as per the OS-specific guide in ROCm Installation Guide (https://docs.amd.com/) for the release. +* Install the "hip-runtime-nvidia" and "hip-dev" package. This will install CUDA SDK and the HIP porting layer. ``` apt-get install hip-runtime-nvidia hip-dev ``` -* Default paths and environment variables: - * By default HIP looks for CUDA SDK in /usr/local/cuda (can be overriden by setting CUDA_PATH env variable). - * By default HIP is installed into /hip (can be overridden by setting HIP_PATH environment variable). - * Optionally, consider adding /bin to your path to make it easier to use the tools. +* Default paths: + * By default HIP looks for CUDA SDK in /usr/local/cuda. + * By default HIP is installed into /opt/rocm/hip. + * Optionally, consider adding /opt/rocm/bin to your path to make it easier to use the tools. -# Building HIP from source on AMD platform - - -## Get HIP source code - -``` -git clone -b develop https://github.com/ROCm-Developer-Tools/hipamd.git -git clone -b develop https://github.com/ROCm-Developer-Tools/hip.git -git clone -b develop https://github.com/ROCm-Developer-Tools/ROCclr.git -git clone -b develop https://github.com/RadeonOpenCompute/ROCm-OpenCL-Runtime.git -``` - -## Set the environment variables - -``` -export HIPAMD_DIR="$(readlink -f hipamd)" -export HIP_DIR="$(readlink -f hip)" -export ROCclr_DIR="$(readlink -f ROCclr)" -export OPENCL_DIR="$(readlink -f ROCm-OpenCL-Runtime)" -``` - -ROCclr is defined on AMD platform that HIP use Radeon Open Compute Common Language Runtime (ROCclr), which is a virtual device interface that HIP runtimes interact with different backends. -See https://github.com/ROCm-Developer-Tools/ROCclr - -HIPAMD repository provides implementation specifically for AMD platform. -See https://github.com/ROCm-Developer-Tools/hipamd - -## Build HIP - -``` -cd "$HIPAMD_DIR" -mkdir -p build; cd build -cmake -DHIP_COMMON_DIR=$HIP_DIR -DAMD_OPENCL_PATH=$OPENCL_DIR -DROCCLR_PATH=$ROCCLR_DIR -DCMAKE_PREFIX_PATH="/" -DCMAKE_INSTALL_PREFIX=$PWD/install .. -make -j$(nproc) -sudo make install -``` - -Note: If you don't specify CMAKE_INSTALL_PREFIX, hip runtime will be installed to "/hip". -By default, release version of AMDHIP is built. - -## 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 (can be overridden by setting HIP_PATH environment variable). - * By default HIP looks for clang in /llvm/bin (can be overridden by setting HIP_CLANG_PATH environment variable) - * By default HIP looks for device library in /lib (can be overridden by setting DEVICE_LIB_PATH environment variable). - * 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. - -After installation, make sure HIP_PATH is pointed to /where/to/install/hip - - -# Building HIP from source on NVIDIA platform - - -## Get HIP source code - -``` -git clone -b develop https://github.com/ROCm-Developer-Tools/hip.git -git clone -b develop https://github.com/ROCm-Developer-Tools/hipamd.git -``` - -## Set the environment variables - -``` -export HIP_DIR="$(readlink -f hip)" -export HIPAMD_DIR="$(readlink -f hipamd)" -``` - -## Build HIP - -``` -cd "$HIPAMD_DIR" -mkdir -p build; cd build -cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install .. -make -j$(nproc) -sudo make install -``` - # Verify your installation Run hipconfig (instructions below assume default installation path) : ```shell -/bin/hipconfig --full -``` -or - -```shell -$PWD/install/bin/hipconfig --full +/opt/rocm/bin/hipconfig --full ``` -Compile and run the [square sample](https://github.com/ROCm-Developer-Tools/HIP/tree/rocm-4.5.x/samples/0_Intro/square). +# How to build HIP from source + +Developers can build HIP from source on either AMD or NVIDIA platforms, see detail instructions at [building HIP] (docs/markdown/hip_build.md). + diff --git a/docs/markdown/hip_build.md b/docs/markdown/hip_build.md new file mode 100755 index 0000000000..d61103aed2 --- /dev/null +++ b/docs/markdown/hip_build.md @@ -0,0 +1,137 @@ +## Table of Contents + + + +- [Prerequisites](#Prerequisites) +- [Build HIP on AMD platform](#build-hip-on-amd-platform) + * [Get HIP source code](#get-hip-source-code) + * [Set the environment variables](#set-the-environment-variables) + * [Build HIP](#build-hip) + * [Default paths and environment variables](#default-paths-and-environment-variables) +- [Build HIP on NVIDIA platform](#build-hip-on-NVIDIA-platform) + * [Get HIP source code](#get-hip-source-code) + * [Set the environment variables](#set-the-environment-variables) + * [Build HIP](#build-hip) +- [Run HIP](#run-hip) + + +# Prerequisites + +HIP code can be developed either on AMD ROCm platform using HIP-Clang compiler, or a CUDA platform with nvcc installed. +Before build and run HIP, make sure drivers and pre-build packages are installed properly on the platform. + +## AMD platform +Install ROCm packages (see ROCm Installation Guide on AMD public documentation site (https://docs.amd.com/)) or install pre-built binary packages using the package manager, + +``` +sudo apt install mesa-common-dev +sudo apt install clang +sudo apt install comgr +sudo apt-get -y install rocm-dkms +``` + + +## NVIDIA platform + +Install Nvidia driver and pre-build packages (see HIP Installation Guide at https://docs.amd.com/ for the release) + +## Branch of repository + +Before get HIP source code, set the expected branch of repository at the variable HIP_BRANCH. +For example, for ROCm5.0 release branch, set +``` +export HIP_BRANCH=rocm-5.0.x +``` + +ROCm5.1 release branch, set +``` +export HIP_BRANCH=rocm-5.1.x +``` +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 + + +## Get HIP source code + +``` +git clone -b $HIP_BRANCH https://github.com/ROCm-Developer-Tools/hipamd.git +git clone -b $HIP_BRANCH https://github.com/ROCm-Developer-Tools/hip.git +git clone -b $HIP_BRANCH https://github.com/ROCm-Developer-Tools/ROCclr.git +git clone -b $HIP_BRANCH https://github.com/RadeonOpenCompute/ROCm-OpenCL-Runtime.git +``` + +## Set the environment variables + +``` +export HIPAMD_DIR="$(readlink -f hipamd)" +export HIP_DIR="$(readlink -f hip)" +export ROCclr_DIR="$(readlink -f ROCclr)" +export OPENCL_DIR="$(readlink -f ROCm-OpenCL-Runtime)" +``` + +ROCclr is defined on AMD platform that HIP use Radeon Open Compute Common Language Runtime (ROCclr), which is a virtual device interface that HIP runtimes interact with different backends. +See https://github.com/ROCm-Developer-Tools/ROCclr + +HIPAMD repository provides implementation specifically for AMD platform. +See https://github.com/ROCm-Developer-Tools/hipamd + +## Build HIP + +``` +cd "$HIPAMD_DIR" +mkdir -p build; cd build +cmake -DHIP_COMMON_DIR=$HIP_DIR -DAMD_OPENCL_PATH=$OPENCL_DIR -DROCCLR_PATH=$ROCCLR_DIR -DCMAKE_PREFIX_PATH="/" -DCMAKE_INSTALL_PREFIX=$PWD/install .. +make -j$(nproc) +sudo make install +``` + +Note: If you don't specify CMAKE_INSTALL_PREFIX, hip runtime will be installed to "/hip". +By default, release version of AMDHIP is built. + +## 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 (can be overridden by setting HIP_PATH environment variable). + * By default HIP looks for clang in /llvm/bin (can be overridden by setting HIP_CLANG_PATH environment variable) + * By default HIP looks for device library in /lib (can be overridden by setting DEVICE_LIB_PATH environment variable). + * 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. + +After make install command, make sure HIP_PATH is pointed to $PWD/install/hip. + + +# Build HIP on NVIDIA platform + + +## Get HIP source code + +``` +git clone -b $HIP_BRANCH https://github.com/ROCm-Developer-Tools/hip.git +git clone -b $HIP_BRANCH https://github.com/ROCm-Developer-Tools/hipamd.git +``` + +## Set the environment variables + +``` +export HIP_DIR="$(readlink -f hip)" +export HIPAMD_DIR="$(readlink -f hipamd)" +``` + +## Build HIP + +``` +cd "$HIPAMD_DIR" +mkdir -p build; cd build +cmake -DHIP_COMMON_DIR=$HIP_DIR -DHIP_PLATFORM=nvidia -DCMAKE_INSTALL_PREFIX=$PWD/install .. +make -j$(nproc) +sudo make install +``` + +# Run HIP + +Compile and run the [square sample](https://github.com/ROCm-Developer-Tools/HIP/tree/rocm-5.0.x/samples/0_Intro/square). +