Preparation¶

Configure the kernel with:

CONFIG_DEBUG_FS=yCONFIG_GCOV_KERNEL=y

and to get coverage data for the entire kernel:

CONFIG_GCOV_PROFILE_ALL=y

Note that kernels compiled with profiling flags will be significantlylarger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supportedon all architectures.

Profiling data will only become accessible once debugfs has beenmounted:

mount -t debugfs none /sys/kernel/debug

Customization¶

To enable profiling for specific files or directories, add a linesimilar to the following to the respective kernel Makefile:

• For a single file (e.g. main.o):

  GCOV_PROFILE_main.o := y

• For all files in one directory:

  GCOV_PROFILE := y

To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALLis specified, use:

GCOV_PROFILE_main.o := n

and:

GCOV_PROFILE := n

Only files which are linked to the main kernel image or are compiled askernel modules are supported by this mechanism.

Files¶

The gcov kernel support creates the following files in debugfs:

/sys/kernel/debug/gcov

Parent directory for all gcov-related files.

/sys/kernel/debug/gcov/reset

Global reset file: resets all coverage data to zero whenwritten to.

/sys/kernel/debug/gcov/path/to/compile/dir/file.gcda

The actual gcov data file as understood by the gcovtool. Resets file coverage data to zero when written to.

/sys/kernel/debug/gcov/path/to/compile/dir/file.gcno

Symbolic link to a static data file required by the gcovtool. This file is generated by gcc when compiling withoption-ftest-coverage.

Modules¶

Kernel modules may contain cleanup code which is only run duringmodule unload time. The gcov mechanism provides a means to collectcoverage data for such code by keeping a copy of the data associatedwith the unloaded module. This data remains available through debugfs.Once the module is loaded again, the associated coverage counters areinitialized with the data from its previous instantiation.

This behavior can be deactivated by specifying the gcov_persist kernelparameter:

gcov_persist=0

At run-time, a user can also choose to discard data for an unloadedmodule by writing to its data file or the global reset file.

Separated build and test machines¶

The gcov kernel profiling infrastructure is designed to work out-of-thebox for setups where kernels are built and run on the same machine. Incases where the kernel runs on a separate machine, special preparationsmust be made, depending on where the gcov tool is used:

1. gcov is run on the TEST machine

   The gcov tool version on the test machine must be compatible with thegcc version used for kernel build. Also the following files need to becopied from build to test machine:

   from the source tree:

   • all C source files + headers

   from the build tree:

   • all C source files + headers
   • all .gcda and .gcno files
   • all links to directories

   It is important to note that these files need to be placed into theexact same file system location on the test machine as on the buildmachine. If any of the path components is symbolic link, the actualdirectory needs to be used instead (due to make’s CURDIR handling).

2. gcov is run on the BUILD machine

   The following files need to be copied after each test case from testto build machine:

   from the gcov directory in sysfs:

   • all .gcda files
   • all links to .gcno files

   These files can be copied to any location on the build machine. gcovmust then be called with the -o option pointing to that directory.

   Example directory setup on the build machine:

   /tmp/linux:    kernel source tree/tmp/out:      kernel build directory as specified by make O=/tmp/coverage: location of the files copied from the test machine[user@build] cd /tmp/out[user@build] gcov -o /tmp/coverage/tmp/out/init main.c

Note on compilers¶

GCC and LLVM gcov tools are not necessarily compatible. Usegcov to work withGCC-generated .gcno and .gcda files, and usellvm-cov for Clang.

Build differences between GCC and Clang gcov are handled by Kconfig. Itautomatically selects the appropriate gcov format depending on the detectedtoolchain.

Troubleshooting¶

Problem

Compilation aborts during linker step.

Cause

Profiling flags are specified for source files which are notlinked to the main kernel or which are linked by a customlinker procedure.

Solution

Exclude affected source files from profiling by specifyingGCOV_PROFILE:=n orGCOV_PROFILE_basename.o:=n in thecorresponding Makefile.

Problem

Files copied from sysfs appear empty or incomplete.

Cause

Due to the way seq_file works, some tools such as cp or tarmay not correctly copy files from sysfs.

Solution

Usecat to read.gcda files andcp-d to copy links.Alternatively use the mechanism shown in Appendix B.

Appendix A: gather_on_build.sh¶

Sample script to gather coverage meta files on the build machine(see 6a):

#!/bin/bashKSRC=$1KOBJ=$2DEST=$3if[ -z"$KSRC"]||[ -z"$KOBJ"]||[ -z"$DEST"];thenecho"Usage:$0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2exit1fiKSRC=$(cd$KSRC;printf"all:\n\t@echo \${CURDIR}\n"| make -f -)KOBJ=$(cd$KOBJ;printf"all:\n\t@echo \${CURDIR}\n"| make -f -)find$KSRC$KOBJ\( -name'*.gcno' -o -name'*.[ch]' -o -type l\) -a\                 -perm /u+r,g+r| tar cfz$DEST -P -T -if[$? -eq0];thenecho"$DEST successfully created, copy to test system and unpack with:"echo"  tar xfz$DEST -P"elseecho"Could not create file$DEST"fi

Appendix B: gather_on_test.sh¶

Sample script to gather coverage data files on the test machine(see 6b):

#!/bin/bash -eDEST=$1GCDA=/sys/kernel/debug/gcovif[ -z"$DEST"];thenecho"Usage:$0 <output.tar.gz>" >&2exit1fiTEMPDIR=$(mktemp -d)echo Collecting data..find$GCDA -type d -exec mkdir -p$TEMPDIR/\{\}\;find$GCDA -name'*.gcda' -exec sh -c'cat < $0 > '$TEMPDIR'/$0'{}\;find$GCDA -name'*.gcno' -exec sh -c'cp -d $0 '$TEMPDIR'/$0'{}\;tar czf$DEST -C$TEMPDIR sysrm -rf$TEMPDIRecho"$DEST successfully created, copy to build system and unpack with:"echo"  tar xfz$DEST"