Documentation/dev-tools/gcov.rst

   1 Using gcov with the Linux kernel
   2 ================================
   3
   4 gcov profiling kernel support enables the use of GCC's coverage testing
   5 tool gcov_ with the Linux kernel. Coverage data of a running kernel
   6 is exported in gcov-compatible format via the "gcov" debugfs directory.
   7 To get coverage data for a specific file, change to the kernel build
   8 directory and use gcov with the ``-o`` option as follows (requires root)::
   9
  10     # cd /tmp/linux-out
  11     # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c
  12
  13 This will create source code files annotated with execution counts
  14 in the current directory. In addition, graphical gcov front-ends such
  15 as lcov_ can be used to automate the process of collecting data
  16 for the entire kernel and provide coverage overviews in HTML format.
  17
  18 Possible uses:
  19
  20 * debugging (has this line been reached at all?)
  21 * test improvement (how do I change my test to cover these lines?)
  22 * minimizing kernel configurations (do I need this option if the
  23   associated code is never run?)
  24
  25 .. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html
  26 .. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
  27
  28
  29 Preparation
  30 -----------
  31
  32 Configure the kernel with::
  33
  34         CONFIG_DEBUG_FS=y
  35         CONFIG_GCOV_KERNEL=y
  36
  37 select the gcc's gcov format, default is autodetect based on gcc version::
  38
  39         CONFIG_GCOV_FORMAT_AUTODETECT=y
  40
  41 and to get coverage data for the entire kernel::
  42
  43         CONFIG_GCOV_PROFILE_ALL=y
  44
  45 Note that kernels compiled with profiling flags will be significantly
  46 larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported
  47 on all architectures.
  48
  49 Profiling data will only become accessible once debugfs has been
  50 mounted::
  51
  52         mount -t debugfs none /sys/kernel/debug
  53
  54
  55 Customization
  56 -------------
  57
  58 To enable profiling for specific files or directories, add a line
  59 similar to the following to the respective kernel Makefile:
  60
  61 - For a single file (e.g. main.o)::
  62
  63         GCOV_PROFILE_main.o := y
  64
  65 - For all files in one directory::
  66
  67         GCOV_PROFILE := y
  68
  69 To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL
  70 is specified, use::
  71
  72         GCOV_PROFILE_main.o := n
  73
  74 and::
  75
  76         GCOV_PROFILE := n
  77
  78 Only files which are linked to the main kernel image or are compiled as
  79 kernel modules are supported by this mechanism.
  80
  81
  82 Files
  83 -----
  84
  85 The gcov kernel support creates the following files in debugfs:
  86
  87 ``/sys/kernel/debug/gcov``
  88         Parent directory for all gcov-related files.
  89
  90 ``/sys/kernel/debug/gcov/reset``
  91         Global reset file: resets all coverage data to zero when
  92         written to.
  93
  94 ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda``
  95         The actual gcov data file as understood by the gcov
  96         tool. Resets file coverage data to zero when written to.
  97
  98 ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno``
  99         Symbolic link to a static data file required by the gcov
 100         tool. This file is generated by gcc when compiling with
 101         option ``-ftest-coverage``.
 102
 103
 104 Modules
 105 -------
 106
 107 Kernel modules may contain cleanup code which is only run during
 108 module unload time. The gcov mechanism provides a means to collect
 109 coverage data for such code by keeping a copy of the data associated
 110 with the unloaded module. This data remains available through debugfs.
 111 Once the module is loaded again, the associated coverage counters are
 112 initialized with the data from its previous instantiation.
 113
 114 This behavior can be deactivated by specifying the gcov_persist kernel
 115 parameter::
 116
 117         gcov_persist=0
 118
 119 At run-time, a user can also choose to discard data for an unloaded
 120 module by writing to its data file or the global reset file.
 121
 122
 123 Separated build and test machines
 124 ---------------------------------
 125
 126 The gcov kernel profiling infrastructure is designed to work out-of-the
 127 box for setups where kernels are built and run on the same machine. In
 128 cases where the kernel runs on a separate machine, special preparations
 129 must be made, depending on where the gcov tool is used:
 130
 131 a) gcov is run on the TEST machine
 132
 133     The gcov tool version on the test machine must be compatible with the
 134     gcc version used for kernel build. Also the following files need to be
 135     copied from build to test machine:
 136
 137     from the source tree:
 138       - all C source files + headers
 139
 140     from the build tree:
 141       - all C source files + headers
 142       - all .gcda and .gcno files
 143       - all links to directories
 144
 145     It is important to note that these files need to be placed into the
 146     exact same file system location on the test machine as on the build
 147     machine. If any of the path components is symbolic link, the actual
 148     directory needs to be used instead (due to make's CURDIR handling).
 149
 150 b) gcov is run on the BUILD machine
 151
 152     The following files need to be copied after each test case from test
 153     to build machine:
 154
 155     from the gcov directory in sysfs:
 156       - all .gcda files
 157       - all links to .gcno files
 158
 159     These files can be copied to any location on the build machine. gcov
 160     must then be called with the -o option pointing to that directory.
 161
 162     Example directory setup on the build machine::
 163
 164       /tmp/linux:    kernel source tree
 165       /tmp/out:      kernel build directory as specified by make O=
 166       /tmp/coverage: location of the files copied from the test machine
 167
 168       [user@build] cd /tmp/out
 169       [user@build] gcov -o /tmp/coverage/tmp/out/init main.c
 170
 171
 172 Troubleshooting
 173 ---------------
 174
 175 Problem
 176     Compilation aborts during linker step.
 177
 178 Cause
 179     Profiling flags are specified for source files which are not
 180     linked to the main kernel or which are linked by a custom
 181     linker procedure.
 182
 183 Solution
 184     Exclude affected source files from profiling by specifying
 185     ``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the
 186     corresponding Makefile.
 187
 188 Problem
 189     Files copied from sysfs appear empty or incomplete.
 190
 191 Cause
 192     Due to the way seq_file works, some tools such as cp or tar
 193     may not correctly copy files from sysfs.
 194
 195 Solution
 196     Use ``cat``' to read ``.gcda`` files and ``cp -d`` to copy links.
 197     Alternatively use the mechanism shown in Appendix B.
 198
 199
 200 Appendix A: gather_on_build.sh
 201 ------------------------------
 202
 203 Sample script to gather coverage meta files on the build machine
 204 (see 6a):
 205
 206 .. code-block:: sh
 207
 208     #!/bin/bash
 209
 210     KSRC=$1
 211     KOBJ=$2
 212     DEST=$3
 213
 214     if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
 215       echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
 216       exit 1
 217     fi
 218
 219     KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
 220     KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
 221
 222     find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \
 223                      -perm /u+r,g+r | tar cfz $DEST -P -T -
 224
 225     if [ $? -eq 0 ] ; then
 226       echo "$DEST successfully created, copy to test system and unpack with:"
 227       echo "  tar xfz $DEST -P"
 228     else
 229       echo "Could not create file $DEST"
 230     fi
 231
 232
 233 Appendix B: gather_on_test.sh
 234 -----------------------------
 235
 236 Sample script to gather coverage data files on the test machine
 237 (see 6b):
 238
 239 .. code-block:: sh
 240
 241     #!/bin/bash -e
 242
 243     DEST=$1
 244     GCDA=/sys/kernel/debug/gcov
 245
 246     if [ -z "$DEST" ] ; then
 247       echo "Usage: $0 <output.tar.gz>" >&2
 248       exit 1
 249     fi
 250
 251     TEMPDIR=$(mktemp -d)
 252     echo Collecting data..
 253     find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \;
 254     find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \;
 255     find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \;
 256     tar czf $DEST -C $TEMPDIR sys
 257     rm -rf $TEMPDIR
 258
 259     echo "$DEST successfully created, copy to build system and unpack with:"
 260     echo "  tar xfz $DEST"