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
  53and to get coverage data for the entire kernel:
  54
  55        CONFIG_GCOV_PROFILE_ALL=y
  56
  57Note that kernels compiled with profiling flags will be significantly
  58larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported
  59on all architectures.
  60
  61Profiling data will only become accessible once debugfs has been
  62mounted:
  63
  64        mount -t debugfs none /sys/kernel/debug
  65
  66
  673. Customization
  68================
  69
  70To enable profiling for specific files or directories, add a line
  71similar 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
  79To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL
  80is specified, use:
  81
  82                GCOV_PROFILE_main.o := n
  83        and:
  84                GCOV_PROFILE := n
  85
  86Only files which are linked to the main kernel image or are compiled as
  87kernel modules are supported by this mechanism.
  88
  89
  904. Files
  91========
  92
  93The 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
 1125. Modules
 113==========
 114
 115Kernel modules may contain cleanup code which is only run during
 116module unload time. The gcov mechanism provides a means to collect
 117coverage data for such code by keeping a copy of the data associated
 118with the unloaded module. This data remains available through debugfs.
 119Once the module is loaded again, the associated coverage counters are
 120initialized with the data from its previous instantiation.
 121
 122This behavior can be deactivated by specifying the gcov_persist kernel
 123parameter:
 124
 125        gcov_persist=0
 126
 127At run-time, a user can also choose to discard data for an unloaded
 128module by writing to its data file or the global reset file.
 129
 130
 1316. Separated build and test machines
 132====================================
 133
 134The gcov kernel profiling infrastructure is designed to work out-of-the
 135box for setups where kernels are built and run on the same machine. In
 136cases where the kernel runs on a separate machine, special preparations
 137must be made, depending on where the gcov tool is used:
 138
 139a) gcov is run on the TEST machine
 140
 141The gcov tool version on the test machine must be compatible with the
 142gcc version used for kernel build. Also the following files need to be
 143copied from build to test machine:
 144
 145from the source tree:
 146  - all C source files + headers
 147
 148from the build tree:
 149  - all C source files + headers
 150  - all .gcda and .gcno files
 151  - all links to directories
 152
 153It is important to note that these files need to be placed into the
 154exact same file system location on the test machine as on the build
 155machine. If any of the path components is symbolic link, the actual
 156directory needs to be used instead (due to make's CURDIR handling).
 157
 158b) gcov is run on the BUILD machine
 159
 160The following files need to be copied after each test case from test
 161to build machine:
 162
 163from the gcov directory in sysfs:
 164  - all .gcda files
 165  - all links to .gcno files
 166
 167These files can be copied to any location on the build machine. gcov
 168must then be called with the -o option pointing to that directory.
 169
 170Example 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
 1807. Troubleshooting
 181==================
 182
 183Problem:  Compilation aborts during linker step.
 184Cause:    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.
 187Solution: Exclude affected source files from profiling by specifying
 188          GCOV_PROFILE := n or GCOV_PROFILE_basename.o := n in the
 189          corresponding Makefile.
 190
 191Problem:  Files copied from sysfs appear empty or incomplete.
 192Cause:    Due to the way seq_file works, some tools such as cp or tar
 193          may not correctly copy files from sysfs.
 194Solution: Use 'cat' to read .gcda files and 'cp -d' to copy links.
 195          Alternatively use the mechanism shown in Appendix B.
 196
 197
 198Appendix A: gather_on_build.sh
 199==============================
 200
 201Sample script to gather coverage meta files on the build machine
 202(see 6a):
 203#!/bin/bash
 204
 205KSRC=$1
 206KOBJ=$2
 207DEST=$3
 208
 209if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then


	
	< to;ocumentation/gcov.txt#L207" id="L207" class="2ine" name="L111"> 111 112 113 114 115 116 117 118 119  20iiniti2lized w;$KS$? -eq 0quoef="Documentation/gcov.txt#L210" id="L2 h class="liine" name="L21">  21T
  22di. Mo222="Documesg"  h"Do xfz ]; th -Pquot; cumentation/gcov.txt#L210" id="L2 h  class="line" name="L23">  23
param2ter:
  24#
  25#     2  gcovficumentation/gcov.txt#L206" id="L206 class="liine" name="L26">  26

  27TAt ru22f="Documentation/gcov.txt#L198" id="L192 class="liine" name="L28">  28imodul22x A: gather_onBtest.sh
  29a
 130 131 132  23
 134 135 136 137 138 139 140
	
	< to;ocumentation/gcov.txt#L207" id="L207" class="2ine" name="L141"> 141 142 143 144 145 146 147 148 149 150 151 152 153 154
 

 id="content" name="footer">
g fioriginal LX
 ioftwd runa hrefumentatioourcefonet/coverage/lcoprojLX
 communityme f,ism.
lxr@rnel .nome f.
 id="cotent" name="subfooter">
lxr.rnel .no kinds fhosfying tumentatioourcefowww.redpill-rnepro.no">Redpilll. Cpro ASme f,ieans tors coL Covecturnl href witopeI need tsTML e d (e.ce====5.
 id="cont/bodycot/href