Comgr: add support for coverage collection (llvm#2088)

Author: ronlieb

amd/comgr/CMakeLists.txt

@@ -265,6 +265,27 @@ if (CMAKE_SIZEOF_VOID_P EQUAL 4)
   set_target_properties(amd_comgr PROPERTIES OUTPUT_NAME "amd_comgr32")
 endif()
 
+option(LLVM_BUILD_INSTRUMENTED_COVERAGE "Build LLVM and tools with Code Coverage instrumentation" Off)
+mark_as_advanced(LLVM_BUILD_INSTRUMENTED_COVERAGE)
+if(LLVM_BUILD_INSTRUMENTED_COVERAGE)
+  if(NOT LLVM_PROFILE_MERGE_POOL_SIZE)
+    # A pool size of 1-2 is probably sufficient on an SSD. 3-4 should be fine
+    # for spinning disks. Anything higher may only help on slower mediums.
+    set(LLVM_PROFILE_MERGE_POOL_SIZE "4")
+  endif()
+  if(NOT LLVM_PROFILE_FILE_PATTERN)
+    if(NOT LLVM_PROFILE_DATA_DIR)
+      file(TO_NATIVE_PATH "${LLVM_BINARY_DIR}/profiles" LLVM_PROFILE_DATA_DIR)
+    endif()
+    file(TO_NATIVE_PATH "${LLVM_PROFILE_DATA_DIR}/%${LLVM_PROFILE_MERGE_POOL_SIZE}m.profraw" LLVM_PROFILE_FILE_PATTERN)
+  endif()
+  set(INSTRUMENTED_COVERAGE_FLAGS -O0 -fprofile-instr-generate=${LLVM_PROFILE_FILE_PATTERN} -fcoverage-mapping)
+  list(APPEND AMD_COMGR_PRIVATE_COMPILE_OPTIONS ${INSTRUMENTED_COVERAGE_FLAGS})
+  list(APPEND AMD_COMGR_PUBLIC_COMPILE_OPTIONS ${INSTRUMENTED_COVERAGE_FLAGS})
+  list(APPEND AMD_COMGR_PRIVATE_LINKER_OPTIONS ${INSTRUMENTED_COVERAGE_FLAGS} -L${LLVM_LIBRARY_DIRS})
+  list(APPEND AMD_COMGR_PUBLIC_LINKER_OPTIONS ${INSTRUMENTED_COVERAGE_FLAGS} -L${LLVM_LIBRARY_DIRS})
+endif()
+
 target_compile_options(amd_comgr
   PRIVATE "${AMD_COMGR_PRIVATE_COMPILE_OPTIONS}")
 target_compile_definitions(amd_comgr

amd/comgr/README.md

@@ -20,68 +20,67 @@ branch. LLVM should be built with at least
 
 An example `bash` session to build Comgr on Linux using GNUMakefiles is:
 
-    $ LLVM_PROJECT=~/llvm-project
-    $ DEVICE_LIBS=~/llvm-project/amd/device-libs
-    $ COMGR=~/llvm-project/amd/comgr
-    $ mkdir -p "$LLVM_PROJECT/build"
-    $ cd "$LLVM_PROJECT/build"
+    $ LLVM_PROJECT=~/llvm-project/build
+    $ DEVICE_LIBS=~/llvm-project/amd/device-libs/build
+    $ mkdir -p "$LLVM_PROJECT"
+    $ cd "$LLVM_PROJECT"
     $ cmake \
         -DCMAKE_BUILD_TYPE=Release \
         -DLLVM_ENABLE_PROJECTS="llvm;clang;lld" \
         -DLLVM_TARGETS_TO_BUILD="AMDGPU;X86" \
         ../llvm
     $ make
-    $ mkdir -p "$DEVICE_LIBS/build"
-    $ cd "$DEVICE_LIBS/build"
+    $ mkdir -p "$DEVICE_LIBS"
+    $ cd "$DEVICE_LIBS"
     $ cmake \
         -DCMAKE_BUILD_TYPE=Release \
-        -DCMAKE_PREFIX_PATH="$LLVM_PROJECT/build" \
+        -DCMAKE_PREFIX_PATH="$LLVM_PROJECT" \
         ..
     $ make
-    $ mkdir -p "$COMGR/build"
-    $ cd "$COMGR/build"
+    $ cd ~/llvm-project/amd/comgr
+    $ mkdir -p build; cd build;
     $ cmake \
         -DCMAKE_BUILD_TYPE=Release \
-        -DCMAKE_PREFIX_PATH="$LLVM_PROJECT/build;$DEVICE_LIBS/build" \
+        -DCMAKE_PREFIX_PATH="$LLVM_PROJECT;$DEVICE_LIBS" \
         ..
     $ make
     $ make test
 
 The equivalent on Windows in `cmd.exe` using Visual Studio project files is:
 
-    > set LLVM_PROJECT="%HOMEPATH%\llvm-project"
-    > set DEVICE_LIBS="%HOMEPATH%\llvm-project\amd\device-libs"
-    > set COMGR="%HOMEPATH%\llvm-project\amd\comgr"
-    > mkdir "%LLVM_PROJECT%\build"
-    > cd "%LLVM_PROJECT%\build"
+    > set LLVM_PROJECT="%HOMEPATH%\llvm-project\build"
+    > set DEVICE_LIBS="%HOMEPATH%\llvm-project\amd\device-libs\build"
+    > mkdir "%LLVM_PROJECT%"
+    > cd "%LLVM_PROJECT%"
     > cmake ^
         -DLLVM_ENABLE_PROJECTS="llvm;clang;lld" ^
         -DLLVM_TARGETS_TO_BUILD="AMDGPU;X86" ^
         ..\llvm
     > msbuild /p:Configuration=Release ALL_BUILD.vcxproj
-    > mkdir "%DEVICE_LIBS%\build"
-    > cd "%DEVICE_LIBS%\build"
+    > mkdir "%DEVICE_LIBS%"
+    > cd "%DEVICE_LIBS%"
     > cmake ^
-        -DCMAKE_PREFIX_PATH="%LLVM_PROJECT%\build" ^
+        -DCMAKE_PREFIX_PATH="%LLVM_PROJECT%" ^
         ..
     > msbuild /p:Configuration=Release ALL_BUILD.vcxproj
-    > mkdir "%COMGR%\build"
-    > cd "%COMGR%\build"
+    > cd "%HOMEPATH%\llvm-project\amd\comgr"
+    > mkdir build
+    > cd build
     > cmake ^
-        -DCMAKE_PREFIX_PATH="%LLVM_PROJECT%\build;%DEVICE_LIBS%\build" ^
+        -DCMAKE_PREFIX_PATH="%LLVM_PROJECT%;%DEVICE_LIBS%" ^
         ..
     > msbuild /p:Configuration=Release ALL_BUILD.vcxproj
     > msbuild /p:Configuration=Release RUN_TESTS.vcxproj
 
-Optionally,
+**ASAN support:** Optionally,
 [AddressSanitizer](https://github.com/google/sanitizers/wiki/AddressSanitizer)
 may be enabled during development via `-DADDRESS_SANITIZER=On` during the Comgr
 `cmake` step.
 
-Comgr can be built as a static library by passing
+**Static Comgr:** Comgr can be built as a static library by passing
 `-DCOMGR_BUILD_SHARED_LIBS=OFF` during the Comgr `cmake` step.
 
-To enable SPIRV support, checkout
+**SPIRV Support:** To enable SPIRV support, checkout
 [SPIRV-LLVM-Translator](https://github.com/ROCm/SPIRV-LLVM-Translator) in
 `llvm/projects` or `llvm/tools` and build using the above instructions, with the
 exception that the `-DCMAKE_PREFIX_PATH` for llvm-project must be an install
@@ -92,6 +91,37 @@ Comgr SPIRV-related APIs can be disabled by passing
 `-DCOMGR_DISABLE_SPIRV=1` during the Comgr `cmake` step. This removes any
 dependency on LLVM SPIRV libraries or the llvm-spirv tool.
 
+**Code Coverage Instrumentation:** Comgr supports source-based [code coverage
+via clang](https://clang.llvm.org/docs/SourceBasedCodeCoverage.html), and
+leverages the same CMake variables as
+[LLVM](https://www.llvm.org/docs/CMake.html#llvm-related-variables)
+(LLVM_BUILD_INSTRUMENTED_COVERAGE, etc.).
+
+Example of insturmenting with covereage, generating profiles, and creating an
+HTML for investigation:
+
+    $ cmake -DCMAKE_STRIP="" -DLLVM_PROFILE_DATA_DIR=`pwd`/profiles \
+        -DLLVM_BUILD_INSTRUMENTED_COVERAGE=On \
+        -DCMAKE_CXX_COMPILER="$LLVM_PROJECT/bin/clang++" \
+        -DCMAKE_C_COMPILER="$LLVM_PROJECT/bin/clang" \
+        -DCMAKE_BUILD_TYPE=Release \
+        -DCMAKE_PREFIX_PATH="$LLVM_PROJECT;$DEVICE_LIBS" ..
+    $ make -j
+    $ make test test-lit
+    $ cd profiles
+    # Manually aggregate the data and create text report.
+    $ $LLVM_PROJECT/bin/llvm-profdata merge -sparse *.profraw -o \
+        comgr_test.profdata # merge and index data
+    $ $LLVM_PROJECT/bin/llvm-cov report ../libamd_comgr.so \
+        -instr-profile=comgr_test.profdata \
+        -ignore-filename-regex="[cl].*/include/*" # show test report without \
+        includes
+    # Or use python script to aggregate the data and create html report.
+    $ $LLVM_PROJECT/../llvm/utils/prepare-code-coverage-artifact.py \
+        --preserve-profiles $LLVM_PROJECT/bin/llvm-profdata \
+        $LLVM_PROJECT/bin/llvm-cov . html ../libamd_comgr.so \
+        # create html report
+
 Depending on the Code Object Manager
 ------------------------------------
 

amd/comgr/docs/ReleaseNotes.md

@@ -60,9 +60,10 @@ Comgr Testing, Debugging, and Logging Updates
 ---------------------------------------------
 - Removed HIP\_PATH and ROCM\_PATH environment variables. These were used for
 now-removed Comgr actions, such as \*COMPILE\_SOURCE\_TO\_FATBIN.
-- Added a new Comgr LIT testing infrastrucutre, which can be found in
+- Added a new Comgr LIT testing infrastructure, which can be found in
 amd/comgr/test-lit. This will allow us to write more in-depth and targeted
 tests.
+- Added support for source-based code coverage. See README.md for more details.
 
 New Targets
 -----------