The Design and Implementation of the FreeBSD Operating System, Second Edition
Now available: The Design and Implementation of the FreeBSD Operating System (Second Edition)


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]

FreeBSD/Linux Kernel Cross Reference
sys/Documentation/gcov.txt

Version: -  FREEBSD  -  FREEBSD-13-STABLE  -  FREEBSD-13-0  -  FREEBSD-12-STABLE  -  FREEBSD-12-0  -  FREEBSD-11-STABLE  -  FREEBSD-11-0  -  FREEBSD-10-STABLE  -  FREEBSD-10-0  -  FREEBSD-9-STABLE  -  FREEBSD-9-0  -  FREEBSD-8-STABLE  -  FREEBSD-8-0  -  FREEBSD-7-STABLE  -  FREEBSD-7-0  -  FREEBSD-6-STABLE  -  FREEBSD-6-0  -  FREEBSD-5-STABLE  -  FREEBSD-5-0  -  FREEBSD-4-STABLE  -  FREEBSD-3-STABLE  -  FREEBSD22  -  l41  -  OPENBSD  -  linux-2.6  -  MK84  -  PLAN9  -  xnu-8792 
SearchContext: -  none  -  3  -  10 

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

Cache object: 1ea196cf3c6fdeba69b2f35bc59b61ee


[ source navigation ] [ diff markup ] [ identifier search ] [ freetext search ] [ file search ] [ list types ] [ track identifier ]


This page is part of the FreeBSD/Linux Linux Kernel Cross-Reference, and was automatically generated using a modified version of the LXR engine.