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