gcov.rst (8137B)
1Using gcov with the Linux kernel 2================================ 3 4gcov profiling kernel support enables the use of GCC's coverage testing 5tool gcov_ with the Linux kernel. Coverage data of a running kernel 6is exported in gcov-compatible format via the "gcov" debugfs directory. 7To get coverage data for a specific file, change to the kernel build 8directory 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 13This will create source code files annotated with execution counts 14in the current directory. In addition, graphical gcov front-ends such 15as lcov_ can be used to automate the process of collecting data 16for the entire kernel and provide coverage overviews in HTML format. 17 18Possible 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 29Preparation 30----------- 31 32Configure the kernel with:: 33 34 CONFIG_DEBUG_FS=y 35 CONFIG_GCOV_KERNEL=y 36 37and to get coverage data for the entire kernel:: 38 39 CONFIG_GCOV_PROFILE_ALL=y 40 41Note that kernels compiled with profiling flags will be significantly 42larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported 43on all architectures. 44 45Profiling data will only become accessible once debugfs has been 46mounted:: 47 48 mount -t debugfs none /sys/kernel/debug 49 50 51Customization 52------------- 53 54To enable profiling for specific files or directories, add a line 55similar 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 65To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL 66is specified, use:: 67 68 GCOV_PROFILE_main.o := n 69 70and:: 71 72 GCOV_PROFILE := n 73 74Only files which are linked to the main kernel image or are compiled as 75kernel modules are supported by this mechanism. 76 77 78Files 79----- 80 81The 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 100Modules 101------- 102 103Kernel modules may contain cleanup code which is only run during 104module unload time. The gcov mechanism provides a means to collect 105coverage data for such code by keeping a copy of the data associated 106with the unloaded module. This data remains available through debugfs. 107Once the module is loaded again, the associated coverage counters are 108initialized with the data from its previous instantiation. 109 110This behavior can be deactivated by specifying the gcov_persist kernel 111parameter:: 112 113 gcov_persist=0 114 115At run-time, a user can also choose to discard data for an unloaded 116module by writing to its data file or the global reset file. 117 118 119Separated build and test machines 120--------------------------------- 121 122The gcov kernel profiling infrastructure is designed to work out-of-the 123box for setups where kernels are built and run on the same machine. In 124cases where the kernel runs on a separate machine, special preparations 125must be made, depending on where the gcov tool is used: 126 127.. _gcov-test: 128 129a) 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 150b) 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 172Note on compilers 173----------------- 174 175GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with 176GCC-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 181Build differences between GCC and Clang gcov are handled by Kconfig. It 182automatically selects the appropriate gcov format depending on the detected 183toolchain. 184 185 186Troubleshooting 187--------------- 188 189Problem 190 Compilation aborts during linker step. 191 192Cause 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 197Solution 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 202Problem 203 Files copied from sysfs appear empty or incomplete. 204 205Cause 206 Due to the way seq_file works, some tools such as cp or tar 207 may not correctly copy files from sysfs. 208 209Solution 210 Use ``cat`` to read ``.gcda`` files and ``cp -d`` to copy links. 211 Alternatively use the mechanism shown in Appendix B. 212 213 214Appendix A: gather_on_build.sh 215------------------------------ 216 217Sample 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 247Appendix B: gather_on_test.sh 248----------------------------- 249 250Sample 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"