About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / gcov.txt




Custom Search

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