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: https://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 and to get coverage data for the entire kernel::
  38
  39         CONFIG_GCOV_PROFILE_ALL=y
  40
  41 Note that kernels compiled with profiling flags will be significantly
  42 larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported
  43 on all architectures.
  44
  45 Profiling data will only become accessible once debugfs has been
  46 mounted::
  47
  48         mount -t debugfs none /sys/kernel/debug
  49
  50
  51 Customization
  52 -------------
  53
  54 To enable profiling for specific files or directories, add a line
  55 similar to the following to the respective kernel Makefile:
  56
  57 - For a single file (e.g. main.o)::
  58
  59         GCOV_PROFILE_main.o := y
  60
  61 - For all files in one directory::
  62
  63         GCOV_PROFILE := y
  64
  65 To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL
  66 is specified, use::
  67
  68         GCOV_PROFILE_main.o := n
  69
  70 and::
  71
  72         GCOV_PROFILE := n
  73
  74 Only files which are linked to the main kernel image or are compiled as
  75 kernel modules are supported by this mechanism.
  76
  77
  78 Files
  79 -----
  80
  81 The gcov kernel support creates the following files in debugfs:
  82
  83 ``/sys/kernel/debug/gcov``
  84         Parent directory for all gcov-related files.
  85
  86 ``/sys/kernel/debug/gcov/reset``
  87         Global reset file: resets all coverage data to zero when
  88         written to.
  89
  90 ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda``
  91         The actual gcov data file as understood by the gcov
  92         tool. Resets file coverage data to zero when written to.
  93
  94 ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno``
  95         Symbolic link to a static data file required by the gcov
  96         tool. This file is generated by gcc when compiling with
  97         option ``-ftest-coverage``.
  98
  99
 100 Modules
 101 -------
 102
 103 Kernel modules may contain cleanup code which is only run during
 104 module unload time. The gcov mechanism provides a means to collect
 105 coverage data for such code by keeping a copy of the data associated
 106 with the unloaded module. This data remains available through debugfs.
 107 Once the module is loaded again, the associated coverage counters are
 108 initialized with the data from its previous instantiation.
 109
 110 This behavior can be deactivated by specifying the gcov_persist kernel
 111 parameter::
 112
 113         gcov_persist=0
 114
 115 At run-time, a user can also choose to discard data for an unloaded
 116 module by writing to its data file or the global reset file.
 117
 118
 119 Separated build and test machines
 120 ---------------------------------
 121
 122 The gcov kernel profiling infrastructure is designed to work out-of-the
 123 box for setups where kernels are built and run on the same machine. In
 124 cases where the kernel runs on a separate machine, special preparations
 125 must be made, depending on where the gcov tool is used:
 126
 127 .. _gcov-test:
 128
 129 a) gcov is run on the TEST machine
 130
 131     The gcov tool version on the test machine must be compatible with the
 132     gcc version used for kernel build. Also the following files need to be
 133     copied from build to test machine:
 134
 135     from the source tree:
 136       - all C source files + headers
 137
 138     from the build tree:
 139       - all C source files + headers
 140       - all .gcda and .gcno files
 141       - all links to directories
 142
 143     It is important to note that these files need to be placed into the
 144     exact same file system location on the test machine as on the build
 145     machine. If any of the path components is symbolic link, the actual
 146     directory needs to be used instead (due to make's CURDIR handling).
 147
 148 .. _gcov-build:
 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 Note on compilers
 173 -----------------
 174
 175 GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with
 176 GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang.
 177
 178 .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
 179 .. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html
 180
 181 Build differences between GCC and Clang gcov are handled by Kconfig. It
 182 automatically selects the appropriate gcov format depending on the detected
 183 toolchain.
 184
 185
 186 Troubleshooting
 187 ---------------
 188
 189 Problem
 190     Compilation aborts during linker step.
 191
 192 Cause
 193     Profiling flags are specified for source files which are not
 194     linked to the main kernel or which are linked by a custom
 195     linker procedure.
 196
 197 Solution
 198     Exclude affected source files from profiling by specifying
 199     ``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the
 200     corresponding Makefile.
 201
 202 Problem
 203     Files copied from sysfs appear empty or incomplete.
 204
 205 Cause
 206     Due to the way seq_file works, some tools such as cp or tar
 207     may not correctly copy files from sysfs.
 208
 209 Solution
 210     Use ``cat`` to read ``.gcda`` files and ``cp -d`` to copy links.
 211     Alternatively use the mechanism shown in Appendix B.
 212
 213
 214 Appendix A: gather_on_build.sh
 215 ------------------------------
 216
 217 Sample script to gather coverage meta files on the build machine
 218 (see :ref:`Separated build and test machines a. <gcov-test>`):
 219
 220 .. code-block:: sh
 221
 222     #!/bin/bash
 223
 224     KSRC=$1
 225     KOBJ=$2
 226     DEST=$3
 227
 228     if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
 229       echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
 230       exit 1
 231     fi
 232
 233     KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
 234     KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
 235
 236     find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \
 237                      -perm /u+r,g+r | tar cfz $DEST -P -T -
 238
 239     if [ $? -eq 0 ] ; then
 240       echo "$DEST successfully created, copy to test system and unpack with:"
 241       echo "  tar xfz $DEST -P"
 242     else
 243       echo "Could not create file $DEST"
 244     fi
 245
 246
 247 Appendix B: gather_on_test.sh
 248 -----------------------------
 249
 250 Sample script to gather coverage data files on the test machine
 251 (see :ref:`Separated build and test machines b. <gcov-build>`):
 252
 253 .. code-block:: sh
 254
 255     #!/bin/bash -e
 256
 257     DEST=$1
 258     GCDA=/sys/kernel/debug/gcov
 259
 260     if [ -z "$DEST" ] ; then
 261       echo "Usage: $0 <output.tar.gz>" >&2
 262       exit 1
 263     fi
 264
 265     TEMPDIR=$(mktemp -d)
 266     echo Collecting data..
 267     find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \;
 268     find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \;
 269     find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \;
 270     tar czf $DEST -C $TEMPDIR sys
 271     rm -rf $TEMPDIR
 272
 273     echo "$DEST successfully created, copy to build system and unpack with:"
 274     echo "  tar xfz $DEST"