Commit | Line | Data |
---|---|---|
2584bab2 JC |
1 | Using gcov with the Linux kernel |
2 | ================================ | |
3 | ||
4 | gcov profiling kernel support enables the use of GCC's coverage testing | |
5 | tool gcov_ with the Linux kernel. Coverage data of a running kernel | |
6 | is exported in gcov-compatible format via the "gcov" debugfs directory. | |
7 | To get coverage data for a specific file, change to the kernel build | |
8 | directory 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 | ||
13 | This will create source code files annotated with execution counts | |
14 | in the current directory. In addition, graphical gcov front-ends such | |
15 | as lcov_ can be used to automate the process of collecting data | |
16 | for the entire kernel and provide coverage overviews in HTML format. | |
17 | ||
18 | Possible 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: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html | |
26 | .. _lcov: http://ltp.sourceforge.net/coverage/lcov.php | |
27 | ||
28 | ||
29 | Preparation | |
30 | ----------- | |
31 | ||
32 | Configure the kernel with:: | |
33 | ||
34 | CONFIG_DEBUG_FS=y | |
35 | CONFIG_GCOV_KERNEL=y | |
36 | ||
37 | select the gcc's gcov format, default is autodetect based on gcc version:: | |
38 | ||
39 | CONFIG_GCOV_FORMAT_AUTODETECT=y | |
40 | ||
41 | and to get coverage data for the entire kernel:: | |
42 | ||
43 | CONFIG_GCOV_PROFILE_ALL=y | |
44 | ||
45 | Note that kernels compiled with profiling flags will be significantly | |
46 | larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported | |
47 | on all architectures. | |
48 | ||
49 | Profiling data will only become accessible once debugfs has been | |
50 | mounted:: | |
51 | ||
52 | mount -t debugfs none /sys/kernel/debug | |
53 | ||
54 | ||
55 | Customization | |
56 | ------------- | |
57 | ||
58 | To enable profiling for specific files or directories, add a line | |
59 | similar to the following to the respective kernel Makefile: | |
60 | ||
61 | - For a single file (e.g. main.o):: | |
62 | ||
63 | GCOV_PROFILE_main.o := y | |
64 | ||
65 | - For all files in one directory:: | |
66 | ||
67 | GCOV_PROFILE := y | |
68 | ||
69 | To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL | |
70 | is specified, use:: | |
71 | ||
72 | GCOV_PROFILE_main.o := n | |
73 | ||
74 | and:: | |
75 | ||
76 | GCOV_PROFILE := n | |
77 | ||
78 | Only files which are linked to the main kernel image or are compiled as | |
79 | kernel modules are supported by this mechanism. | |
80 | ||
81 | ||
82 | Files | |
83 | ----- | |
84 | ||
85 | The gcov kernel support creates the following files in debugfs: | |
86 | ||
87 | ``/sys/kernel/debug/gcov`` | |
88 | Parent directory for all gcov-related files. | |
89 | ||
90 | ``/sys/kernel/debug/gcov/reset`` | |
91 | Global reset file: resets all coverage data to zero when | |
92 | written to. | |
93 | ||
94 | ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda`` | |
95 | The actual gcov data file as understood by the gcov | |
96 | tool. Resets file coverage data to zero when written to. | |
97 | ||
98 | ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno`` | |
99 | Symbolic link to a static data file required by the gcov | |
100 | tool. This file is generated by gcc when compiling with | |
101 | option ``-ftest-coverage``. | |
102 | ||
103 | ||
104 | Modules | |
105 | ------- | |
106 | ||
107 | Kernel modules may contain cleanup code which is only run during | |
108 | module unload time. The gcov mechanism provides a means to collect | |
109 | coverage data for such code by keeping a copy of the data associated | |
110 | with the unloaded module. This data remains available through debugfs. | |
111 | Once the module is loaded again, the associated coverage counters are | |
112 | initialized with the data from its previous instantiation. | |
113 | ||
114 | This behavior can be deactivated by specifying the gcov_persist kernel | |
115 | parameter:: | |
116 | ||
117 | gcov_persist=0 | |
118 | ||
119 | At run-time, a user can also choose to discard data for an unloaded | |
120 | module by writing to its data file or the global reset file. | |
121 | ||
122 | ||
123 | Separated build and test machines | |
124 | --------------------------------- | |
125 | ||
126 | The gcov kernel profiling infrastructure is designed to work out-of-the | |
127 | box for setups where kernels are built and run on the same machine. In | |
128 | cases where the kernel runs on a separate machine, special preparations | |
129 | must be made, depending on where the gcov tool is used: | |
130 | ||
131 | a) gcov is run on the TEST machine | |
132 | ||
133 | The gcov tool version on the test machine must be compatible with the | |
134 | gcc version used for kernel build. Also the following files need to be | |
135 | copied from build to test machine: | |
136 | ||
137 | from the source tree: | |
138 | - all C source files + headers | |
139 | ||
140 | from the build tree: | |
141 | - all C source files + headers | |
142 | - all .gcda and .gcno files | |
143 | - all links to directories | |
144 | ||
145 | It is important to note that these files need to be placed into the | |
146 | exact same file system location on the test machine as on the build | |
147 | machine. If any of the path components is symbolic link, the actual | |
148 | directory needs to be used instead (due to make's CURDIR handling). | |
149 | ||
150 | b) 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 | ||
172 | Troubleshooting | |
173 | --------------- | |
174 | ||
175 | Problem | |
176 | Compilation aborts during linker step. | |
177 | ||
178 | Cause | |
179 | Profiling flags are specified for source files which are not | |
180 | linked to the main kernel or which are linked by a custom | |
181 | linker procedure. | |
182 | ||
183 | Solution | |
184 | Exclude affected source files from profiling by specifying | |
185 | ``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the | |
186 | corresponding Makefile. | |
187 | ||
188 | Problem | |
189 | Files copied from sysfs appear empty or incomplete. | |
190 | ||
191 | Cause | |
192 | Due to the way seq_file works, some tools such as cp or tar | |
193 | may not correctly copy files from sysfs. | |
194 | ||
195 | Solution | |
196 | Use ``cat``' to read ``.gcda`` files and ``cp -d`` to copy links. | |
197 | Alternatively use the mechanism shown in Appendix B. | |
198 | ||
199 | ||
200 | Appendix A: gather_on_build.sh | |
201 | ------------------------------ | |
202 | ||
203 | Sample script to gather coverage meta files on the build machine | |
57131dd3 JN |
204 | (see 6a): |
205 | ||
206 | .. code-block:: sh | |
2584bab2 JC |
207 | |
208 | #!/bin/bash | |
209 | ||
210 | KSRC=$1 | |
211 | KOBJ=$2 | |
212 | DEST=$3 | |
213 | ||
214 | if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then | |
215 | echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2 | |
216 | exit 1 | |
217 | fi | |
218 | ||
219 | KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) | |
220 | KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -) | |
221 | ||
222 | find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \ | |
223 | -perm /u+r,g+r | tar cfz $DEST -P -T - | |
224 | ||
225 | if [ $? -eq 0 ] ; then | |
226 | echo "$DEST successfully created, copy to test system and unpack with:" | |
227 | echo " tar xfz $DEST -P" | |
228 | else | |
229 | echo "Could not create file $DEST" | |
230 | fi | |
231 | ||
232 | ||
233 | Appendix B: gather_on_test.sh | |
234 | ----------------------------- | |
235 | ||
236 | Sample script to gather coverage data files on the test machine | |
57131dd3 JN |
237 | (see 6b): |
238 | ||
239 | .. code-block:: sh | |
2584bab2 JC |
240 | |
241 | #!/bin/bash -e | |
242 | ||
243 | DEST=$1 | |
244 | GCDA=/sys/kernel/debug/gcov | |
245 | ||
246 | if [ -z "$DEST" ] ; then | |
247 | echo "Usage: $0 <output.tar.gz>" >&2 | |
248 | exit 1 | |
249 | fi | |
250 | ||
251 | TEMPDIR=$(mktemp -d) | |
252 | echo Collecting data.. | |
253 | find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \; | |
254 | find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \; | |
255 | find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \; | |
256 | tar czf $DEST -C $TEMPDIR sys | |
257 | rm -rf $TEMPDIR | |
258 | ||
259 | echo "$DEST successfully created, copy to build system and unpack with:" | |
260 | echo " tar xfz $DEST" |