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: https://github.com/linux-test-project/lcov
  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 Module specific configs
  79 -----------------------
  80
  81 Gcov kernel configs for specific modules are described below:
  82
  83 CONFIG_GCOV_PROFILE_RDS:
  84         Enables GCOV profiling on RDS for checking which functions or
  85         lines are executed. This config is used by the rds selftest to
  86         generate coverage reports. If left unset the report is omitted.
  87
  88
  89 Files
  90 -----
  91
  92 The gcov kernel support creates the following files in debugfs:
  93
  94 ``/sys/kernel/debug/gcov``
  95         Parent directory for all gcov-related files.
  96
  97 ``/sys/kernel/debug/gcov/reset``
  98         Global reset file: resets all coverage data to zero when
  99         written to.
 100
 101 ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda``
 102         The actual gcov data file as understood by the gcov
 103         tool. Resets file coverage data to zero when written to.
 104
 105 ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno``
 106         Symbolic link to a static data file required by the gcov
 107         tool. This file is generated by gcc when compiling with
 108         option ``-ftest-coverage``.
 109
 110
 111 Modules
 112 -------
 113
 114 Kernel modules may contain cleanup code which is only run during
 115 module unload time. The gcov mechanism provides a means to collect
 116 coverage data for such code by keeping a copy of the data associated
 117 with the unloaded module. This data remains available through debugfs.
 118 Once the module is loaded again, the associated coverage counters are
 119 initialized with the data from its previous instantiation.
 120
 121 This behavior can be deactivated by specifying the gcov_persist kernel
 122 parameter::
 123
 124         gcov_persist=0
 125
 126 At run-time, a user can also choose to discard data for an unloaded
 127 module by writing to its data file or the global reset file.
 128
 129
 130 Separated build and test machines
 131 ---------------------------------
 132
 133 The gcov kernel profiling infrastructure is designed to work out-of-the
 134 box for setups where kernels are built and run on the same machine. In
 135 cases where the kernel runs on a separate machine, special preparations
 136 must be made, depending on where the gcov tool is used:
 137
 138 .. _gcov-test:
 139
 140 a) gcov is run on the TEST machine
 141
 142     The gcov tool version on the test machine must be compatible with the
 143     gcc version used for kernel build. Also the following files need to be
 144     copied from build to test machine:
 145
 146     from the source tree:
 147       - all C source files + headers
 148
 149     from the build tree:
 150       - all C source files + headers
 151       - all .gcda and .gcno files
 152       - all links to directories
 153
 154     It is important to note that these files need to be placed into the
 155     exact same file system location on the test machine as on the build
 156     machine. If any of the path components is symbolic link, the actual
 157     directory needs to be used instead (due to make's CURDIR handling).
 158
 159 .. _gcov-build:
 160
 161 b) gcov is run on the BUILD machine
 162
 163     The following files need to be copied after each test case from test
 164     to build machine:
 165
 166     from the gcov directory in sysfs:
 167       - all .gcda files
 168       - all links to .gcno files
 169
 170     These files can be copied to any location on the build machine. gcov
 171     must then be called with the -o option pointing to that directory.
 172
 173     Example directory setup on the build machine::
 174
 175       /tmp/linux:    kernel source tree
 176       /tmp/out:      kernel build directory as specified by make O=
 177       /tmp/coverage: location of the files copied from the test machine
 178
 179       [user@build] cd /tmp/out
 180       [user@build] gcov -o /tmp/coverage/tmp/out/init main.c
 181
 182
 183 Note on compilers
 184 -----------------
 185
 186 GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with
 187 GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang.
 188
 189 .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
 190 .. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html
 191
 192 Build differences between GCC and Clang gcov are handled by Kconfig. It
 193 automatically selects the appropriate gcov format depending on the detected
 194 toolchain.
 195
 196
 197 Troubleshooting
 198 ---------------
 199
 200 Problem
 201     Compilation aborts during linker step.
 202
 203 Cause
 204     Profiling flags are specified for source files which are not
 205     linked to the main kernel or which are linked by a custom
 206     linker procedure.
 207
 208 Solution
 209     Exclude affected source files from profiling by specifying
 210     ``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the
 211     corresponding Makefile.
 212
 213 Problem
 214     Files copied from sysfs appear empty or incomplete.
 215
 216 Cause
 217     Due to the way seq_file works, some tools such as cp or tar
 218     may not correctly copy files from sysfs.
 219
 220 Solution
 221     Use ``cat`` to read ``.gcda`` files and ``cp -d`` to copy links.
 222     Alternatively use the mechanism shown in Appendix B.
 223
 224
 225 Appendix A: gather_on_build.sh
 226 ------------------------------
 227
 228 Sample script to gather coverage meta files on the build machine
 229 (see :ref:`Separated build and test machines a. <gcov-test>`):
 230
 231 .. code-block:: sh
 232
 233     #!/bin/bash
 234
 235     KSRC=$1
 236     KOBJ=$2
 237     DEST=$3
 238
 239     if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
 240       echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
 241       exit 1
 242     fi
 243
 244     KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
 245     KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
 246
 247     find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \
 248                      -perm /u+r,g+r | tar cfz $DEST -P -T -
 249
 250     if [ $? -eq 0 ] ; then
 251       echo "$DEST successfully created, copy to test system and unpack with:"
 252       echo "  tar xfz $DEST -P"
 253     else
 254       echo "Could not create file $DEST"
 255     fi
 256
 257
 258 Appendix B: gather_on_test.sh
 259 -----------------------------
 260
 261 Sample script to gather coverage data files on the test machine
 262 (see :ref:`Separated build and test machines b. <gcov-build>`):
 263
 264 .. code-block:: sh
 265
 266     #!/bin/bash -e
 267
 268     DEST=$1
 269     GCDA=/sys/kernel/debug/gcov
 270
 271     if [ -z "$DEST" ] ; then
 272       echo "Usage: $0 <output.tar.gz>" >&2
 273       exit 1
 274     fi
 275
 276     TEMPDIR=$(mktemp -d)
 277     echo Collecting data..
 278     find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \;
 279     find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \;
 280     find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \;
 281     tar czf $DEST -C $TEMPDIR sys
 282     rm -rf $TEMPDIR
 283
 284     echo "$DEST successfully created, copy to build system and unpack with:"
 285     echo "  tar xfz $DEST"