https://github.com/yxsamliu created https://github.com/llvm/llvm-project/pull/200197
Add a section to HIPSupport.rst describing how to produce source-based code coverage reports for HIP device code on AMD GPUs: compile with -fprofile-instr-generate -fcoverage-mapping, extract the device ELF from the host binary's .hip_fatbin section, unbundle with clang-offload-bundler using the hip-amdgcn-amd-amdhsa--<arch> target ID, and run llvm-profdata / llvm-cov against the device object. >From 3d5457741c89bc62ad63c060ab6709c0ab452478 Mon Sep 17 00:00:00 2001 From: "Yaxun (Sam) Liu" <[email protected]> Date: Thu, 28 May 2026 10:36:57 -0400 Subject: [PATCH] [docs][HIP] Document source-based device code coverage workflow Add a section to HIPSupport.rst describing how to produce source-based code coverage reports for HIP device code on AMD GPUs: compile with -fprofile-instr-generate -fcoverage-mapping, extract the device ELF from the host binary's .hip_fatbin section, unbundle with clang-offload-bundler using the hip-amdgcn-amd-amdhsa--<arch> target ID, and run llvm-profdata / llvm-cov against the device object. --- clang/docs/HIPSupport.rst | 45 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/clang/docs/HIPSupport.rst b/clang/docs/HIPSupport.rst index 82070a4042679..66d63ab72701c 100644 --- a/clang/docs/HIPSupport.rst +++ b/clang/docs/HIPSupport.rst @@ -951,6 +951,51 @@ Open Questions / Future Developments 4. Offload support might be extended to cases where the ``parallel_policy`` is used for some or all targets. +Source-Based Code Coverage for Device Code +========================================== + +Clang supports source-based code coverage for HIP device code on AMD GPUs. +Device code is instrumented with the same ``-fprofile-instr-generate +-fcoverage-mapping`` flags used for host code; counters live in the device +binary, are written to a ``.profraw`` file at process exit, and can be +consumed by ``llvm-profdata`` and ``llvm-cov``. + +Example +------- + +Given a HIP program ``demo.hip``, the following commands produce an LCOV +report covering device code: + +.. code-block:: console + + $ clang++ -x hip demo.hip \ + --offload-arch=gfx1101 \ + -fprofile-instr-generate -fcoverage-mapping \ + -o demo + + $ llvm-objcopy --dump-section=.hip_fatbin=fatbin.bin demo + $ clang-offload-bundler --type=o --input=fatbin.bin \ + --output=device.gfx1101.o \ + --targets=hip-amdgcn-amd-amdhsa--gfx1101 --unbundle + + $ LLVM_PROFILE_FILE="cov.%p.profraw" ./demo + $ llvm-profdata merge -sparse -o cov.profdata cov.*.profraw + + $ llvm-cov report device.gfx1101.o -instr-profile=cov.profdata + $ llvm-cov show device.gfx1101.o -instr-profile=cov.profdata + $ llvm-cov export device.gfx1101.o -instr-profile=cov.profdata \ + -format=lcov > coverage.lcov + +The device ELF is extracted from the ``.hip_fatbin`` section of the host +binary and then unbundled with ``clang-offload-bundler``. The unbundle +target string uses the bundle ID ``hip-amdgcn-amd-amdhsa--<arch>``, +which is the offload kind (``hip``) followed by the standard +four-component target triple (``amdgcn-amd-amdhsa-``, with the empty +environment field giving the trailing dash) and then the target ID +(``<arch>``). See :doc:`ClangOffloadBundler` for the full bundle entry +ID grammar. ``llvm-cov`` is invoked against the device object because +the coverage mapping for device functions is emitted there. + SPIR-V Support on HIPAMD ToolChain ================================== _______________________________________________ cfe-commits mailing list [email protected] https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
