1.. SPDX-License-Identifier: CC-BY-4.0 2 3Code Coverage 4============= 5 6Xen can be compiled with coverage support. When configured, Xen will record 7the coverage of its own basic blocks. Being a piece of system software rather 8than a userspace, it can't automatically write coverage out to the filesystem, 9so some extra steps are required to collect and process the data. 10 11.. warning:: 12 13 ARM doesn't currently boot when the final binary exceeds 2MB in size, 14 and the coverage build tends to exceed this limit. 15 16 17Compiling Xen 18------------- 19 20Coverage support is dependent on the compiler and toolchain used. As Xen 21isn't a userspace application, it can't use the compiler supplied library, and 22instead has to provide some parts of the implementation itself. 23 24For x86, coverage support was introduced with GCC 3.4 or later, and Clang 3.9 25or later, and Xen is compatible with these. However, the compiler internal 26formats do change occasionally, and this may involve adjustments to Xen. 27While we do our best to keep up with these changes, Xen may not be compatible 28with bleeding edge compilers. 29 30To build with coverage support, enable ``CONFIG_COVERAGE`` in Kconfig. The 31build system will automatically select the appropriate format based on the 32compiler in use. 33 34The resulting binary will record its own coverage while running. 35 36 37Accessing the raw coverage data 38------------------------------- 39 40The ``SYSCTL_coverage_op`` hypercall is used to interact with the coverage 41data. A dom0 userspace helper, ``xenconv`` is provided as well, which thinly 42wraps this hypercall. 43 44The ``read`` subcommand can be used to obtain the raw coverage data:: 45 46 [root@host ~]# xencov read > coverage.dat 47 48This is toolchain-specific data and needs to be fed back to the appropriate 49programs to post-process. 50 51Alternatively, the ``reset`` subcommand can be used reset all counters back to 520:: 53 54 [root@host ~]# xencov reset 55 56 57GCC coverage 58------------ 59 60A build using GCC's coverage will result in ``*.gcno`` artefact for every 61object file. The raw coverage data needs splitting to form the matching 62``*.gcda`` files. 63 64An example of how to view the data is as follows. It uses ``lcov`` which is a 65graphical frontend to ``gcov``. 66 67* Obtain the raw coverage data from the test host, and pull it back to the 68 build working tree. 69* Use ``xencov_split`` to extract the ``*.gcda`` files. Note that full build 70 paths are used by the tools, so splitting needs to output relative to ``/``. 71* Use ``geninfo`` to post-process the raw data. 72* Use ``genhtml`` to render the results as HTML. 73* View the results in a browser. 74 75:: 76 77 xen.git/xen$ ssh root@host xencov read > coverage.dat 78 xen.git/xen$ ../tools/xencov_split coverage.dat --output-dir=/ 79 xen.git/xen$ geninfo . -o cov.info 80 xen.git/xen$ genhtml cov.info -o cov/ 81 xen.git/xen$ $BROWSER cov/index.html 82 83Clang coverage 84-------------- 85 86An example of how to view the data is as follows. 87 88* Obtain the raw coverage data from the test host, and pull it back to the 89 build working tree. 90* Use ``llvm-profdata`` to post-process the raw data. 91* Use ``llvm-cov show`` in combination with ``xen-syms`` from the build to 92 render the results as HTML. 93* View the results in a browser. 94 95:: 96 97 xen.git/xen$ ssh root@host xencov read > xen.profraw 98 xen.git/xen$ llvm-profdata merge xen.profraw -o xen.profdata 99 xen.git/xen$ llvm-cov show -format=html -output-dir=cov/ xen-syms -instr-profile=xen.profdata 100 xen.git/xen$ $BROWSER cov/index.html 101 102Full documentation on Clang's coverage capabilities can be found at: 103https://clang.llvm.org/docs/SourceBasedCodeCoverage.html 104