1# Coverage support for Xen
2
3Coverage support allows you to get coverage information from Xen execution.
4You can see how many times a line is executed.
5
6Some compilers have specific options that enable the collection of this
7information. Every basic block in the code will be instrumented by the compiler
8to compute these statistics. It should not be used in production as it slows
9down your hypervisor.
10
11## Enable coverage
12
13Test coverage support can be turned on compiling Xen with the `CONFIG_GCOV`
14option set to `y`.
15
16Change your `.config` or run `make -C xen menuconfig`.
17
18## Extract coverage data
19
20To extract data you use a simple utility called `xencov`.
21It allows you to do 2 operations:
22
23* `xencov read` extract data
24* `xencov reset` reset all coverage counters
25
26Another utility (`xencov_split`) is used to split extracted data file into
27files needed by userspace tools.
28
29## Split coverage data
30
31Once you extracted data from Xen, it is time to create files which the coverage
32tools can understand. To do it you need to run `xencov_split` utility.
33
34The utility just takes an input file and splits the blob into gcc .gcda files
35in the same directory that you execute the script. As file names are generated
36relative to the current directory, it could be a good idea to run the script
37from `/` on your build machine.
38
39Code for splitting the blob is put in another utility for some reason:
40* It is simpler to maintain a high level script than a C program;
41* You don't need to execute on the Xen host so you just need to copy the file to
42  your development box (you usually need development files anyway).
43
44## Possible use
45
46**This section is just an example on how to use these tools!**
47
48This example assumes you compiled Xen from `~/xen-unstable` and installed into
49the host. **Consider that if you even recompile Xen you are not able to use
50blob extracted from xencov!**
51
52* Ensure the `lcov` package is installed
53* From the Xen host machine extract the coverage blob
54
55        cd /root
56        xencov read coverage.dat
57
58* Copy the extracted blob to your dev machine
59
60        cd ~
61        scp root@myhost:coverage.dat
62
63* Extract the coverage information
64
65        (cd / && xencov_split ~/coverage.dat)
66
67* Produce coverage html output
68
69        cd ~/xen-unstable
70        rm -rf cov.info cov
71        geninfo -o cov.info xen
72        mkdir cov
73        genhtml -o cov cov.info
74
75* See output in a browser
76
77        firefox cov/index.html
78