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