About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / gcov.txt




Custom Search

Based on kernel version 3.9. Page generated on 2013-05-02 23:07 EST.

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_DEBUG_FS=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	Problem:  Files copied from sysfs appear empty or incomplete.
192	Cause:    Due to the way seq_file works, some tools such as cp or tar
193	          may not correctly copy files from sysfs.
194	Solution: Use 'cat' to read .gcda files and 'cp -d' to copy links.
195	          Alternatively use the mechanism shown in Appendix B.
196	
197	
198	Appendix A: gather_on_build.sh
199	==============================
200	
201	Sample script to gather coverage meta files on the build machine
202	(see 6a):
203	#!/bin/bash
204	
205	KSRC=$1
206	KOBJ=$2
207	DEST=$3
208	
209	if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
210	  echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
211	  exit 1
212	fi
213	
214	KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
215	KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
216	
217	find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \
218	                 -perm /u+r,g+r | tar cfz $DEST -P -T -
219	
220	if [ $? -eq 0 ] ; then
221	  echo "$DEST successfully created, copy to test system and unpack with:"
222	  echo "  tar xfz $DEST -P"
223	else
224	  echo "Could not create file $DEST"
225	fi
226	
227	
228	Appendix B: gather_on_test.sh
229	=============================
230	
231	Sample script to gather coverage data files on the test machine
232	(see 6b):
233	
234	#!/bin/bash -e
235	
236	DEST=$1
237	GCDA=/sys/kernel/debug/gcov
238	
239	if [ -z "$DEST" ] ; then
240	  echo "Usage: $0 <output.tar.gz>" >&2
241	  exit 1
242	fi
243	
244	TEMPDIR=$(mktemp -d)
245	echo Collecting data..
246	find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \;
247	find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \;
248	find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \;
249	tar czf $DEST -C $TEMPDIR sys
250	rm -rf $TEMPDIR
251	
252	echo "$DEST successfully created, copy to build system and unpack with:"
253	echo "  tar xfz $DEST"
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog
Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.