Skip to content

Latest commit

 

History

History
executable file
·
216 lines (157 loc) · 6.73 KB

build.md

File metadata and controls

executable file
·
216 lines (157 loc) · 6.73 KB

Building HIP from Source

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 or pre-built binary packages using the package manager. Refer to the ROCm Installation Guide at https://rocm.docs.amd.com for more information on installing ROCm.

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

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 ROCM_BRANCH. For example, for ROCm6.0 release branch, set

export ROCM_BRANCH=rocm-6.0.x

ROCm5.7 release branch, set

export ROCM_BRANCH=rocm-5.7.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 "$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

Set the environment variables

export CLR_DIR="$(readlink -f clr)"
export HIP_DIR="$(readlink -f hip)"
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. OpenCL provides headers that ROCclr runtime currently depends on.

Build the HIPCC runtime

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

Build 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

Note, if CMAKE_INSTALL_PREFIX is not specified, hip runtime will be installed to <ROCM_PATH>/hip. By default, release version of HIP is built.

Default paths and environment variables

  • By default HIP looks for HSA in <ROCM_PATH>/hsa (can be overridden by setting HSA_PATH environment variable).
  • By default HIP is installed into <ROCM_PATH>/hip.
  • By default HIP looks for clang in <ROCM_PATH>/llvm/bin (can be overridden by setting HIP_CLANG_PATH environment variable)
  • By default HIP looks for device library in <ROCM_PATH>/lib (can be overridden by setting DEVICE_LIB_PATH environment variable).
  • Optionally, consider adding <ROCM_PATH>/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

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.

Usage:

hip_prof_gen.py [-v] <input HIP API .h file> <patched srcs path> <previous output> [<output>]

Flags:

  • -v - verbose messages
  • -r - process source directory recursively
  • -t - API types matching check
  • --priv - private API check
  • -e - on error exit mode
  • -p - HIP_INIT_API macro patching mode

Example Usage:

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

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.

Get HIP tests source code

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

Build HIP tests from source

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 # or any path where HIP is installed, for example, /opt/rocm.
make -j$(nproc) build_tests # build tests
cd build/catch_tests && ctest # to run all tests.

HIP catch tests are built under the folder $HIPTESTS_DIR/build. Note that when using ctest, you can use different ctest options, for example, to run all tests with the keyword hipMemset,

ctest -R hipMemset

Use the below option will print test failures for failed tests,

ctest --output-on-failure

For more information, refer to https://cmake.org/cmake/help/v3.5/manual/ctest.1.html.

To run any single catch test, the following is an example,

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

Build HIP Catch2 standalone test

HIP Catch2 supports build a standalone test, for example,

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

Build HIP on NVIDIA platform

Get HIP source code

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

export HIP_DIR="$(readlink -f hip)"
export CLR_DIR="$(readlink -f hipamd)"
export HIPCC_DIR="$(readlink -f hipcc)"

Build the HIPCC runtime

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

Build HIP

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 ..
make -j$(nproc)
sudo make install

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.