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