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