From 14a136c3e2170654c112d7e6eb30fc77fe83d18f Mon Sep 17 00:00:00 2001
From: ROCm CI Service Account <66695075+rocm-ci@users.noreply.github.com>
Date: Wed, 15 Jun 2022 06:19:09 +0530
Subject: [PATCH] SWDEV-329687 - add instructions on building hip tests (#2737)

Change-Id: I0f3567ee5f3170c5d50d39caa3ce3f40a9d152f7
---
 docs/markdown/hip_build.md | 82 +++++++++++++++++++++++++++++++++++---
 1 file changed, 77 insertions(+), 5 deletions(-)

diff --git a/docs/markdown/hip_build.md b/docs/markdown/hip_build.md
index d61103aed2..17bc1af955 100755
--- a/docs/markdown/hip_build.md
+++ b/docs/markdown/hip_build.md
@@ -8,10 +8,12 @@
   * [Set the environment variables](#set-the-environment-variables)
   * [Build HIP](#build-hip)
   * [Default paths and environment variables](#default-paths-and-environment-variables)
+  * [Build HIP Tests](#build-hip-tests)
 - [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)
+  * [Build HIP tests](#build-hip-tests)
 - [Run HIP](#run-hip)
 <!-- tocstop -->
 
@@ -30,7 +32,6 @@ 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)
@@ -61,7 +62,6 @@ ROCM_PATH is path where ROCM is installed. BY default ROCM_PATH is at /opt/rocm.
 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
@@ -69,8 +69,6 @@ git clone -b $HIP_BRANCH https://github.com/RadeonOpenCompute/ROCm-OpenCL-Runtim
 ```
 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.
@@ -84,7 +82,7 @@ See https://github.com/ROCm-Developer-Tools/hipamd
 ```
 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="<ROCM_PATH>/" -DCMAKE_INSTALL_PREFIX=$PWD/install ..
+cmake -DHIP_COMMON_DIR=$HIP_DIR -DCMAKE_PREFIX_PATH="<ROCM_PATH>/" -DCMAKE_INSTALL_PREFIX=$PWD/install ..
 make -j$(nproc)
 sudo make install
 ```
@@ -103,6 +101,77 @@ By default, release version of AMDHIP is built.
 
 After make install command, make sure HIP_PATH is pointed to $PWD/install/hip.
 
+## Build HIP tests
+
+### Build HIP directed tests
+Developers can build HIP directed tests right after build HIP commands,
+
+```
+sudo make install
+make -j$(nproc) build_tests
+```
+By default, all HIP directed tests will be built and generated under the folder $HIPAMD_DIR/build/directed_tests.
+Take HIP directed device APIs tests, as an example, all available test applications will have executable files generated under,
+$HIPAMD_DIR/build/directed_tests/runtimeApi/device.
+
+Run all HIP directed_tests, use the command,
+
+```
+ctest
+```
+Or
+```
+make test
+```
+
+Build and run a single directed test, use the follow command as an example,
+
+```
+make directed_tests.texture.hipTexObjPitch
+cd $HIPAMD_DIR/build/directed_tests/texcture
+./hipTexObjPitch
+```
+Please note, the integrated HIP directed tests, will be deprecated in future release.
+
+
+### Build HIP catch tests
+
+After build and install HIP commands, catch tests can be built via the following instructions,
+
+```
+cd "$HIP_DIR"
+mkdir -p build; cd build
+export HIP_PATH=$HIPAMD_DIR/build
+cmake  ../tests/catch/ -DHIP_PLATFORM=amd
+make -j$(nproc) build_tests
+ctest # run tests
+```
+
+HIP catch tests are built under the folder $HIP_DIR/build.
+
+To run a single catch test, the following is an example,
+
+```
+cd $HIP_DIR/build/unit/texture
+./TextureTest
+```
+
+### Build HIP Catch2 standalone test
+
+HIP Catch2 supports build a standalone test, for example,
+
+```
+export PATH=$HIP_DIR/bin:$PATH
+export HIP_PATH=$HIPAMD_DIR/build/install
+
+hipcc $HIP_DIR/tests/catch/unit/memory/hipPointerGetAttributes.cc -I ./tests/catch/include ./tests/catch/hipTestMain/standalone_main.cc -I ./tests/catch/external/Catch2 -g -o hipPointerGetAttributes
+./hipPointerGetAttributes
+...
+
+All tests passed
+```
+
+HIP catch tests, especially new architectured Catch2, will be official HIP tests in the repository and can be built alone as with the instructions shown above.
 
 # Build HIP on NVIDIA platform
 
@@ -131,6 +200,9 @@ 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](https://github.com/ROCm-Developer-Tools/HIP/tree/rocm-5.0.x/samples/0_Intro/square).