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 | ||
4d8c1e05 | 25 | .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html |
2584bab2 JC |
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 | ||
2584bab2 JC |
37 | and to get coverage data for the entire kernel:: |
38 | ||
39 | CONFIG_GCOV_PROFILE_ALL=y | |
40 | ||
41 | Note that kernels compiled with profiling flags will be significantly | |
42 | larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported | |
43 | on all architectures. | |
44 | ||
45 | Profiling data will only become accessible once debugfs has been | |
46 | mounted:: | |
47 | ||
48 | mount -t debugfs none /sys/kernel/debug | |
49 | ||
50 | ||
51 | Customization | |
52 | ------------- | |
53 | ||
54 | To enable profiling for specific files or directories, add a line | |
55 | similar 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 | ||
65 | To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL | |
66 | is specified, use:: | |
67 | ||
68 | GCOV_PROFILE_main.o := n | |
69 | ||
70 | and:: | |
71 | ||
72 | GCOV_PROFILE := n | |
73 | ||
74 | Only files which are linked to the main kernel image or are compiled as | |
75 | kernel modules are supported by this mechanism. | |
76 | ||
77 | ||
78 | Files | |
79 | ----- | |
80 | ||
81 | The 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 | ||
100 | Modules | |
101 | ------- | |
102 | ||
103 | Kernel modules may contain cleanup code which is only run during | |
104 | module unload time. The gcov mechanism provides a means to collect | |
105 | coverage data for such code by keeping a copy of the data associated | |
106 | with the unloaded module. This data remains available through debugfs. | |
107 | Once the module is loaded again, the associated coverage counters are | |
108 | initialized with the data from its previous instantiation. | |
109 | ||
110 | This behavior can be deactivated by specifying the gcov_persist kernel | |
111 | parameter:: | |
112 | ||
113 | gcov_persist=0 | |
114 | ||
115 | At run-time, a user can also choose to discard data for an unloaded | |
116 | module by writing to its data file or the global reset file. | |
117 | ||
118 | ||
119 | Separated build and test machines | |
120 | --------------------------------- | |
121 | ||
122 | The gcov kernel profiling infrastructure is designed to work out-of-the | |
123 | box for setups where kernels are built and run on the same machine. In | |
124 | cases where the kernel runs on a separate machine, special preparations | |
125 | must be made, depending on where the gcov tool is used: | |
126 | ||
1446e322 WX |
127 | .. _gcov-test: |
128 | ||
2584bab2 JC |
129 | a) 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 | ||
1446e322 WX |
148 | .. _gcov-build: |
149 | ||
2584bab2 JC |
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 | ||
aa069a23 TV |
172 | Note on compilers |
173 | ----------------- | |
174 | ||
175 | GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with | |
176 | GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang. | |
177 | ||
4d8c1e05 | 178 | .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html |
aa069a23 TV |
179 | .. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html |
180 | ||
181 | Build differences between GCC and Clang gcov are handled by Kconfig. It | |
182 | automatically selects the appropriate gcov format depending on the detected | |
183 | toolchain. | |
184 | ||
185 | ||
2584bab2 JC |
186 | Troubleshooting |
187 | --------------- | |
188 | ||
189 | Problem | |
190 | Compilation aborts during linker step. | |
191 | ||
192 | Cause | |
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 | ||
197 | Solution | |
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 | ||
202 | Problem | |
203 | Files copied from sysfs appear empty or incomplete. | |
204 | ||
205 | Cause | |
206 | Due to the way seq_file works, some tools such as cp or tar | |
207 | may not correctly copy files from sysfs. | |
208 | ||
209 | Solution | |
0a464ea4 | 210 | Use ``cat`` to read ``.gcda`` files and ``cp -d`` to copy links. |
2584bab2 JC |
211 | Alternatively use the mechanism shown in Appendix B. |
212 | ||
213 | ||
214 | Appendix A: gather_on_build.sh | |
215 | ------------------------------ | |
216 | ||
217 | Sample script to gather coverage meta files on the build machine | |
1446e322 | 218 | (see :ref:`Separated build and test machines a. <gcov-test>`): |
57131dd3 JN |
219 | |
220 | .. code-block:: sh | |
2584bab2 JC |
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 | ||
247 | Appendix B: gather_on_test.sh | |
248 | ----------------------------- | |
249 | ||
250 | Sample script to gather coverage data files on the test machine | |
1446e322 | 251 | (see :ref:`Separated build and test machines b. <gcov-build>`): |
57131dd3 JN |
252 | |
253 | .. code-block:: sh | |
2584bab2 JC |
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" |