blob: 7b727783db7ed4f87a7c68b44b52054c62f48e85 [file] [log] [blame]
Peter Oberparleiter2521f2c2009-06-17 16:28:08 -07001Using 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
Marton Nemeth3c78f5d2009-07-22 22:44:23 +020050 CONFIG_DEBUG_FS=y
Peter Oberparleiter2521f2c2009-06-17 16:28:08 -070051 CONFIG_GCOV_KERNEL=y
52
Frantisek Hrbata17c568d2013-11-12 15:11:27 -080053select the gcc's gcov format, default is autodetect based on gcc version:
54
55 CONFIG_GCOV_FORMAT_AUTODETECT=y
56
Peter Oberparleiter2521f2c2009-06-17 16:28:08 -070057and 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
Peter Oberparleiter972c71a2009-06-30 11:41:20 -0700195Problem: 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
Peter Oberparleiter2521f2c2009-06-17 16:28:08 -0700201
202Appendix A: gather_on_build.sh
203==============================
204
205Sample script to gather coverage meta files on the build machine
206(see 6a):
Peter Oberparleiter2521f2c2009-06-17 16:28:08 -0700207#!/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
Peter Oberparleiter972c71a2009-06-30 11:41:20 -0700238#!/bin/bash -e
Peter Oberparleiter2521f2c2009-06-17 16:28:08 -0700239
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
Peter Oberparleiter972c71a2009-06-30 11:41:20 -0700248TEMPDIR=$(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
Peter Oberparleiter2521f2c2009-06-17 16:28:08 -0700255
Peter Oberparleiter972c71a2009-06-30 11:41:20 -0700256echo "$DEST successfully created, copy to build system and unpack with:"
257echo " tar xfz $DEST"