From 6e6cc27c73eba6d6c03d0d20a6c55b38a4b6c9d2 Mon Sep 17 00:00:00 2001
From: Chris Freehill <Chris.Freehill@amd.com>
Date: Mon, 28 Sep 2020 17:38:35 -0500
Subject: [PATCH] Add README for rocrtst

Change-Id: Icd43a243ccfc9caf5ade3cd0e7ffc00e251fc0a2


[ROCm/ROCR-Runtime commit: 2b41fb9fdc8e1fcdbef78393c2b5e3dd95abcd18]
---
 projects/rocr-runtime/rocrtst/README.md | 101 ++++++++++++++++++++++++
 1 file changed, 101 insertions(+)
 create mode 100644 projects/rocr-runtime/rocrtst/README.md

diff --git a/projects/rocr-runtime/rocrtst/README.md b/projects/rocr-runtime/rocrtst/README.md
new file mode 100644
index 0000000000..92d9f409ea
--- /dev/null
+++ b/projects/rocr-runtime/rocrtst/README.md
@@ -0,0 +1,101 @@
+# Building rocrtst
+
+## Library dependencies
+rocrtst needs hwloc and libnuma to build and run. On Debian systems, for example, you would need to get them like so:
+```sh
+sudo apt-get install libhwloc-dev libnuma-dev
+```
+## CMake option values
+When building rocrtst, several cmake command line options are available--some mandatory, some optional. These are described here:
+  * TARGET_DEVICES=<string>
+    * Optional
+    * semi-colon separated list of gpus to build kernels for; e.g. "gfx908;gfx900;...".
+    * Default: the list of devices that is used is specified in the CMakeLists.txt file, and includes the all the currently supported targets.
+  * ROCRTST_BLD_TYPE=<debug|release>
+    * Optional
+    * Build a debug or release build
+    * Default: Build the debug version
+  * CMAKE_PREFIX_PATH=<"ROCR root path; LLVM root path">
+    * Required
+    * Where to find ROCr and LLVM. The ROCr root path is typically something like /opt/rocm. The LLVM directory is typically something like /opt/rocm/llvm
+  * CMAKE_INSTALL_PREFIX="<Root path where rocrtst should be installed>"
+    * Optional
+    * Where to install rocrtst
+  * CPACK_PACKAGING_INSTALL_PREFIX="<path where to install>"
+    * Optional
+    * Where to install rocrtst within DEB/RPM packages
+  * CPACK_GENERATOR=<list of package generators>
+    * Optional
+    * List of CPack build generators to use; e.g. "DEB;RPM"
+  * ROCM_PATCH_VERSION=<string>
+    * Optional
+    * ROCm patch version used in package name
+  * ROCM_DIR=<ROCm path>
+    * Required
+    * ROCm root directory
+  * LLVM_DIR="<clang location>"
+    * Required
+    * Location of clang executable
+  * OPENCL_DIR=<location of OpenCL root>
+    * Required
+    * Location where OpenCL root resides
+  * EMULATOR_BUILD=<true|false>
+    * Optional
+    * If EMULATOR_BUILD is defined, rocrtst will avoid tests that typically run too long on an HW emulator, or use a scaled-down version of the test.
+
+## Steps to build
+```sh
+mkdir build
+cd build
+# See description of these options above.
+# The values for these options are examples. They should be tailored
+# for your system.
+cmake -DTARGET_DEVICES=$GPU_LIST \
+  -DROCRTST_BLD_TYPE=$ROCRTST_BUILD_TYPE \
+  -DCMAKE_PREFIX_PATH="$PACKAGE_ROOT;$PACKAGE_ROOT/llvm" \
+  -DCMAKE_INSTALL_PREFIX="$ROCM_INSTALL_PATH" \
+  -DCPACK_PACKAGING_INSTALL_PREFIX="$ROCM_INSTALL_PATH" \
+  -DCPACK_GENERATOR="DEB;RPM" \
+  -DROCM_PATCH_VERSION=$ROCM_LIBPATCH_VERSION \
+  -DROCM_DIR=$PACKAGE_ROOT \
+  -DLLVM_DIR="$PACKAGE_ROOT/llvm/bin" \
+  -DOPENCL_DIR=$PACKAGE_ROOT \
+  -DEMULATOR_BUILD=$EMULATOR_BUILD \
+      ..
+# Build rocrtst executable
+make
+# Build rocrtst kernels
+make rocrtst_kernels
+```
+## Running rocrtst
+rocrtst needs to be able to find the ROCr library. This can be through ldconfig method or by setting LD_LIBRARY_PATH to have the ROCr library directory.
+When rocrtst is built, there is one rocrtst executable, and several symlinks pointing to that executable, one from each asic sub-directory. For example, for gfx900, we would see the following:
+```sh
+cd <rocrtst bin root>/gfx900
+ls -l rocrtst
+lrwxrwxrwx 1 user user 12 Sep 28 17:23 rocrtst64 -> ../rocrtst64
+```
+To run rocrtst, we should call the ASIC specific symlink. This allows the asic-specific kernels to be found.
+
+rocrtst is a Google Test ("gtest") based program and accepts gtest options. Additionally, there are some rocrtst specfic options. All of these options can be seen by using the "-h" option:
+```sh
+$ <rocrtst bin>/gfx900 $ ./rocrtst64 -h
+<GTest option descrption>
+Optional RocRTst Arguments:
+--iterations, -i <number of iterations to execute>; override default, which varies for each test
+--rocrtst_help, -r print this help message
+--verbosity, -v <verbosity level>
+  Verbosity levels:
+   0    -- minimal; just summary information
+   1    -- intermediate; show intermediate values such as intermediate perf. data
+   2    -- progress; show progress displays
+   >= 3 -- more debug output
+--monitor_verbosity, -m <monitor verbosity level>
+  Monitor Verbosity levels:
+   0    -- don't read or print out any GPU monitor information;
+   1    -- print out all available monitor information before the first test and after each test
+   >= 2 -- print out even more monitor information (test specific)
+
+```
+
+