gcov.rst 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270
  1. Using gcov with the Linux kernel
  2. ================================
  3. gcov profiling kernel support enables the use of GCC's coverage testing
  4. tool gcov_ with the Linux kernel. Coverage data of a running kernel
  5. is exported in gcov-compatible format via the "gcov" debugfs directory.
  6. To get coverage data for a specific file, change to the kernel build
  7. directory and use gcov with the ``-o`` option as follows (requires root)::
  8. # cd /tmp/linux-out
  9. # gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c
  10. This will create source code files annotated with execution counts
  11. in the current directory. In addition, graphical gcov front-ends such
  12. as lcov_ can be used to automate the process of collecting data
  13. for the entire kernel and provide coverage overviews in HTML format.
  14. Possible uses:
  15. * debugging (has this line been reached at all?)
  16. * test improvement (how do I change my test to cover these lines?)
  17. * minimizing kernel configurations (do I need this option if the
  18. associated code is never run?)
  19. .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
  20. .. _lcov: http://ltp.sourceforge.net/coverage/lcov.php
  21. Preparation
  22. -----------
  23. Configure the kernel with::
  24. CONFIG_DEBUG_FS=y
  25. CONFIG_GCOV_KERNEL=y
  26. and to get coverage data for the entire kernel::
  27. CONFIG_GCOV_PROFILE_ALL=y
  28. Note that kernels compiled with profiling flags will be significantly
  29. larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported
  30. on all architectures.
  31. Profiling data will only become accessible once debugfs has been
  32. mounted::
  33. mount -t debugfs none /sys/kernel/debug
  34. Customization
  35. -------------
  36. To enable profiling for specific files or directories, add a line
  37. similar to the following to the respective kernel Makefile:
  38. - For a single file (e.g. main.o)::
  39. GCOV_PROFILE_main.o := y
  40. - For all files in one directory::
  41. GCOV_PROFILE := y
  42. To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL
  43. is specified, use::
  44. GCOV_PROFILE_main.o := n
  45. and::
  46. GCOV_PROFILE := n
  47. Only files which are linked to the main kernel image or are compiled as
  48. kernel modules are supported by this mechanism.
  49. Files
  50. -----
  51. The gcov kernel support creates the following files in debugfs:
  52. ``/sys/kernel/debug/gcov``
  53. Parent directory for all gcov-related files.
  54. ``/sys/kernel/debug/gcov/reset``
  55. Global reset file: resets all coverage data to zero when
  56. written to.
  57. ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda``
  58. The actual gcov data file as understood by the gcov
  59. tool. Resets file coverage data to zero when written to.
  60. ``/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno``
  61. Symbolic link to a static data file required by the gcov
  62. tool. This file is generated by gcc when compiling with
  63. option ``-ftest-coverage``.
  64. Modules
  65. -------
  66. Kernel modules may contain cleanup code which is only run during
  67. module unload time. The gcov mechanism provides a means to collect
  68. coverage data for such code by keeping a copy of the data associated
  69. with the unloaded module. This data remains available through debugfs.
  70. Once the module is loaded again, the associated coverage counters are
  71. initialized with the data from its previous instantiation.
  72. This behavior can be deactivated by specifying the gcov_persist kernel
  73. parameter::
  74. gcov_persist=0
  75. At run-time, a user can also choose to discard data for an unloaded
  76. module by writing to its data file or the global reset file.
  77. Separated build and test machines
  78. ---------------------------------
  79. The gcov kernel profiling infrastructure is designed to work out-of-the
  80. box for setups where kernels are built and run on the same machine. In
  81. cases where the kernel runs on a separate machine, special preparations
  82. must be made, depending on where the gcov tool is used:
  83. a) gcov is run on the TEST machine
  84. The gcov tool version on the test machine must be compatible with the
  85. gcc version used for kernel build. Also the following files need to be
  86. copied from build to test machine:
  87. from the source tree:
  88. - all C source files + headers
  89. from the build tree:
  90. - all C source files + headers
  91. - all .gcda and .gcno files
  92. - all links to directories
  93. It is important to note that these files need to be placed into the
  94. exact same file system location on the test machine as on the build
  95. machine. If any of the path components is symbolic link, the actual
  96. directory needs to be used instead (due to make's CURDIR handling).
  97. b) gcov is run on the BUILD machine
  98. The following files need to be copied after each test case from test
  99. to build machine:
  100. from the gcov directory in sysfs:
  101. - all .gcda files
  102. - all links to .gcno files
  103. These files can be copied to any location on the build machine. gcov
  104. must then be called with the -o option pointing to that directory.
  105. Example directory setup on the build machine::
  106. /tmp/linux: kernel source tree
  107. /tmp/out: kernel build directory as specified by make O=
  108. /tmp/coverage: location of the files copied from the test machine
  109. [user@build] cd /tmp/out
  110. [user@build] gcov -o /tmp/coverage/tmp/out/init main.c
  111. Note on compilers
  112. -----------------
  113. GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with
  114. GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang.
  115. .. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html
  116. .. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html
  117. Build differences between GCC and Clang gcov are handled by Kconfig. It
  118. automatically selects the appropriate gcov format depending on the detected
  119. toolchain.
  120. Troubleshooting
  121. ---------------
  122. Problem
  123. Compilation aborts during linker step.
  124. Cause
  125. Profiling flags are specified for source files which are not
  126. linked to the main kernel or which are linked by a custom
  127. linker procedure.
  128. Solution
  129. Exclude affected source files from profiling by specifying
  130. ``GCOV_PROFILE := n`` or ``GCOV_PROFILE_basename.o := n`` in the
  131. corresponding Makefile.
  132. Problem
  133. Files copied from sysfs appear empty or incomplete.
  134. Cause
  135. Due to the way seq_file works, some tools such as cp or tar
  136. may not correctly copy files from sysfs.
  137. Solution
  138. Use ``cat`` to read ``.gcda`` files and ``cp -d`` to copy links.
  139. Alternatively use the mechanism shown in Appendix B.
  140. Appendix A: gather_on_build.sh
  141. ------------------------------
  142. Sample script to gather coverage meta files on the build machine
  143. (see 6a):
  144. .. code-block:: sh
  145. #!/bin/bash
  146. KSRC=$1
  147. KOBJ=$2
  148. DEST=$3
  149. if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then
  150. echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2
  151. exit 1
  152. fi
  153. KSRC=$(cd $KSRC; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
  154. KOBJ=$(cd $KOBJ; printf "all:\n\t@echo \${CURDIR}\n" | make -f -)
  155. find $KSRC $KOBJ \( -name '*.gcno' -o -name '*.[ch]' -o -type l \) -a \
  156. -perm /u+r,g+r | tar cfz $DEST -P -T -
  157. if [ $? -eq 0 ] ; then
  158. echo "$DEST successfully created, copy to test system and unpack with:"
  159. echo " tar xfz $DEST -P"
  160. else
  161. echo "Could not create file $DEST"
  162. fi
  163. Appendix B: gather_on_test.sh
  164. -----------------------------
  165. Sample script to gather coverage data files on the test machine
  166. (see 6b):
  167. .. code-block:: sh
  168. #!/bin/bash -e
  169. DEST=$1
  170. GCDA=/sys/kernel/debug/gcov
  171. if [ -z "$DEST" ] ; then
  172. echo "Usage: $0 <output.tar.gz>" >&2
  173. exit 1
  174. fi
  175. TEMPDIR=$(mktemp -d)
  176. echo Collecting data..
  177. find $GCDA -type d -exec mkdir -p $TEMPDIR/\{\} \;
  178. find $GCDA -name '*.gcda' -exec sh -c 'cat < $0 > '$TEMPDIR'/$0' {} \;
  179. find $GCDA -name '*.gcno' -exec sh -c 'cp -d $0 '$TEMPDIR'/$0' {} \;
  180. tar czf $DEST -C $TEMPDIR sys
  181. rm -rf $TEMPDIR
  182. echo "$DEST successfully created, copy to build system and unpack with:"
  183. echo " tar xfz $DEST"