gcov: add gcov profiling infrastructure
[linux-2.6.git] / Documentation / gcov.txt
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_DEBUGFS=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
192 Appendix A: gather_on_build.sh
193 ==============================
194
195 Sample script to gather coverage meta files on the build machine
196 (see 6a):
197
198 #!/bin/bash
199
200 KSRC=$1
201 KOBJ=$2
202 DEST=$3
203
204 if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
205   echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
206   exit 1
207 fi
208
209 KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
210 KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
211
212 find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \
213                  -perm /u+r,g+r | tar cfz $DEST -P -T -
214
215 if [ $? -eq 0 ] ; then
216   echo "$DEST successfully created, copy to test system and unpack with:"
217   echo "  tar xfz $DEST -P"
218 else
219   echo "Could not create file $DEST"
220 fi
221
222
223 Appendix B: gather_on_test.sh
224 =============================
225
226 Sample script to gather coverage data files on the test machine
227 (see 6b):
228
229 #!/bin/bash
230
231 DEST=$1
232 GCDA=/sys/kernel/debug/gcov
233
234 if [ -z "$DEST" ] ; then
235   echo "Usage: $0 <output.tar.gz>" >&2
236   exit 1
237 fi
238
239 find $GCDA -name '*.gcno' -o -name '*.gcda' | tar cfz $DEST -T -
240
241 if [ $? -eq 0 ] ; then
242   echo "$DEST successfully created, copy to build system and unpack with:"
243   echo "  tar xfz $DEST"
244 else
245   echo "Could not create file $DEST"
246 fi