Merge branch 'topic/cs46xx-drop-fw' into for-next
[platform/adaptation/renesas_rcar/renesas_kernel.git] / Documentation / gcov.txt
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"