From 5a2d48117dfd6cb73a0983f45cf78cf0367fe2fa Mon Sep 17 00:00:00 2001 From: Maneesh Gupta Date: Mon, 12 Jun 2017 11:19:55 +0530 Subject: [PATCH] Update directed tests README.md Change-Id: I395245454d376508f04e5a4a62c8933895cb3867 [ROCm/hip commit: b850a08d99184610f930e98d2370bc7a4c89f253] --- projects/hip/tests/README.md | 86 +++++++++++++++++++++++++++--------- 1 file changed, 64 insertions(+), 22 deletions(-) diff --git a/projects/hip/tests/README.md b/projects/hip/tests/README.md index cb41cc10cd..27cde7c534 100644 --- a/projects/hip/tests/README.md +++ b/projects/hip/tests/README.md @@ -1,39 +1,78 @@ # HIP testing environment. -This document explains how to use the HIP CMAKE testing environment. +This document explains how to use the HIP CMAKE testing environment. +We make use of the HIT Integrated Tester (HIT) framework to automatically find and add test cases to the CMAKE testing environment. ### Quickstart -Usage : + +HIP unit tests are integrated into the top-level cmake project. The tests depend upon the installed version of HIP. +Typical usage (paths relative to top of the HIP repo): ``` $ mkdir build $ cd build -$ cmake ../src +$ cmake .. -DCMAKE_INSTALL_PREFIX=$PWD/install $ make +$ make install +$ make build_tests $ make test ``` ### How to add a new test -The tests/src/runtimeApi/memory/hipMemtest.cpp file contains a simple unit test and is a good starting point for other tests. -Copy this to a new test name and modify tests/src/CMakefiles.txt to add the test to the build environment. - -Recent versions of the test infrastructure use a hierarchy of folders. Each folder contains src and CMakefiles.txt file. -See the CMakefiles.txt files for description of the intended purpose for each sub-directory. +The test infrastructure use a hierarchy of folders. So add the new test to the appropriate folder. +The tests/src/runtimeApi/memory/hipMemset.cpp file contains a simple unit test and is a good starting point for other tests. +Copy this to a new test name and modify it. -#### Edit CMakefiles.txt: -// Example: +### HIP Integrated Tester (HIT) + +The HIT framework sutomatically finds and adds test cases to the CMAKE testing environment. It achives this by parsing all files in the tests/src folder. +The parser looks for a code block similar to the one below. ``` -# Build the test executable: -build_hip_executable (hipMemset hipMemset.cpp) - - -# This runs the tests with the specified command-line testing. -# Multiple make_test may be specified. -make_test(hipMemset " ") +/* HIT_START + * BUILD: %t %s ../../test_common.cpp + * RUN: %t + * //Small copy + * RUN: %t -N 10 --memsetval 0x42 + * // Oddball size + * RUN: %t -N 10013 --memsetval 0x5a + * // Big copy + * RUN: %t -N 256M --memsetval 0xa6 + * HIT_END + */ ``` +In the above, BUILD commands provide instructions on how to build the test case while RUN commands provide instructions on how to execute the test case. -It is recommended to place the build and run steps adjacent in the CMakefiles.txt. +#### BUILD command + +The supported syntax for the BUILD command is: +``` +BUILD: %t %s HIPCC_OPTIONS HCC_OPTIONS NVCC_OPTIONS EXCLUDE_HIP_PLATFORM +``` +%s: refers to current source file name. Additional source files needed for the test can be specified by name (including relative path). +%t: refers to target executable named derived by removing the extension from the current source file. Alternatively a target executable name can be specified. +HIPCC_OPTIONS: All options specified after this delimiter are passed to hipcc on both HCC and NVCC platforms. +HCC_OPTIONS: All options specified after this delimiter are passed to hipcc on HCC platform only. +NVCC_OPTIONS: All options specified after this delimiter are passed to hipcc on NVCC platform only. +EXCLUDE_HIP_PLATFORM: This can be used to exclude a test case from HCC, NVCC or both platforms. + + +#### RUN command + +The supported syntax for the RUN command is: +``` +RUN: %t EXCLUDE_HIP_PLATFORM +``` +%t: refers to target executable named derived by removing the extension from the current source file. Alternatively a target executable name can be specified. +EXCLUDE_HIP_PLATFORM: This can be used to exclude a test case from HCC, NVCC or both platforms. Note that if the test has been excluded for a specific platform in the BUILD command, it is automatically excluded from the RUN command as well for the same platform. + + +#### RUN_NAMED command + +When using the RUN command, HIT will squash and append the arguments specified to the test executable name to generate the CMAKE test name. Sometimes we might want to specify a more descriptive name. The RUN_NAMED command is used for that. The supported syntax for the RUN_NAMED command is: +``` +RUN: %t CMAKE_TEST_NAME EXCLUDE_HIP_PLATFORM +``` ### Running tests: @@ -43,11 +82,14 @@ ctest ### Run subsets of all tests: ``` -# Run one test on the commandline (obtain commandline parms from CMakefiles.tst) -./hipMemset +# Run one test on the commandline +./directed_tests/runtime/memory/hipMemset -# Run all the memory tests: +# Run all the hipMemcpy tests: ctest -R Memcpy + +# Run all tests in a specific folder: +ctest -R memory ``` @@ -55,7 +97,7 @@ ctest -R Memcpy Find the test and commandline that fail: -(From the test build directory, perhaps hip/tests/build) +(From the build directory, perhaps hip/build) grep -IR hipMemcpy-modes -IR ../tests/ ../tests/src/runtimeApi/memory/hipMemcpy.cpp: * RUN_NAMED: %t hipMemcpy-modes --tests 0x1