gcov: add gcov profiling infrastructure

Using gcov with the Linux kernel

================================

1. Introduction

2. Preparation

3. Customization

4. Files

5. Modules

6. Separated build and test machines

7. Troubleshooting

Appendix A: sample script: gather_on_build.sh

Appendix B: sample script: gather_on_test.sh

1. Introduction

===============

gcov profiling kernel support enables the use of GCC's coverage testing

tool gcov [1] with the Linux kernel. Coverage data of a running kernel

is exported in gcov-compatible format via the "gcov" debugfs directory.

To get coverage data for a specific file, change to the kernel build

directory and use gcov with the -o option as follows (requires root):

# cd /tmp/linux-out

# gcov -o /sys/kernel/debug/gcov/tmp/linux-out/kernel spinlock.c

This will create source code files annotated with execution counts

in the current directory. In addition, graphical gcov front-ends such

as lcov [2] can be used to automate the process of collecting data

for the entire kernel and provide coverage overviews in HTML format.

Possible uses:

* debugging (has this line been reached at all?)

* test improvement (how do I change my test to cover these lines?)

* minimizing kernel configurations (do I need this option if the

  associated code is never run?)

--

[1] http://gcc.gnu.org/onlinedocs/gcc/Gcov.html

[2] http://ltp.sourceforge.net/coverage/lcov.php

2. Preparation

==============

Configure the kernel with:

        CONFIG_DEBUGFS=y

        CONFIG_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 significantly

larger and run slower. Also CONFIG_GCOV_PROFILE_ALL may not be supported

on all architectures.

Profiling data will only become accessible once debugfs has been

mounted:

        mount -t debugfs none /sys/kernel/debug

3. Customization

================

To enable profiling for specific files or directories, add a line

similar 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_ALL

is specified, use:

                GCOV_PROFILE_main.o := n

        and:

                GCOV_PROFILE := n

Only files which are linked to the main kernel image or are compiled as

kernel modules are supported by this mechanism.

4. 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 when

                written to.

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

                The actual gcov data file as understood by the gcov

                tool. 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 gcov

                tool. This file is generated by gcc when compiling with

                option -ftest-coverage.

5. Modules

==========

Kernel modules may contain cleanup code which is only run during

module unload time. The gcov mechanism provides a means to collect

coverage data for such code by keeping a copy of the data associated

with the unloaded module. This data remains available through debugfs.

Once the module is loaded again, the associated coverage counters are

initialized with the data from its previous instantiation.

This behavior can be deactivated by specifying the gcov_persist kernel

parameter:

        gcov_persist=0

At run-time, a user can also choose to discard data for an unloaded

module by writing to its data file or the global reset file.

6. Separated build and test machines

====================================

The gcov kernel profiling infrastructure is designed to work out-of-the

box for setups where kernels are built and run on the same machine. In

cases where the kernel runs on a separate machine, special preparations

must be made, depending on where the gcov tool is used:

a) gcov is run on the TEST machine

The gcov tool version on the test machine must be compatible with the

gcc version used for kernel build. Also the following files need to be

copied 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 the

exact same file system location on the test machine as on the build

machine. If any of the path components is symbolic link, the actual

directory needs to be used instead (due to make's CURDIR handling).

b) gcov is run on the BUILD machine

The following files need to be copied after each test case from test

to 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. gcov

must 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

7. Troubleshooting

==================

Problem:  Compilation aborts during linker step.

Cause:    Profiling flags are specified for source files which are not

          linked to the main kernel or which are linked by a custom

          linker procedure.

Solution: Exclude affected source files from profiling by specifying

          GCOV_PROFILE := n or GCOV_PROFILE_basename.o := n in the

          corresponding Makefile.

Appendix A: gather_on_build.sh

==============================

Sample script to gather coverage meta files on the build machine

(see 6a):

#!/bin/bash

KSRC=$1

KOBJ=$2

DEST=$3

if [ -z "$KSRC" ] || [ -z "$KOBJ" ] || [ -z "$DEST" ]; then

  echo "Usage: $0 <ksrc directory> <kobj directory> <output.tar.gz>" >&2

  exit 1

fi

KSRC=$(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 [ $? -eq 0 ] ; then

  echo "$DEST successfully created, copy to test system and unpack with:"

  echo "  tar xfz $DEST -P"

else

  echo "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

DEST=$1

GCDA=/sys/kernel/debug/gcov

if [ -z "$DEST" ] ; then

  echo "Usage: $0 <output.tar.gz>" >&2

  exit 1

fi

find $GCDA -name '*.gcno' -o -name '*.gcda' | tar cfz $DEST -T -

if [ $? -eq 0 ] ; then

  echo "$DEST successfully created, copy to build system and unpack with:"

  echo "  tar xfz $DEST"

else

  echo "Could not create file $DEST"

fi

	EFI	EFI Partitioning (GPT) is enabled

	EIDE	EIDE/ATAPI support is enabled.

	FB	The frame buffer device is enabled.

	GCOV	GCOV profiling is enabled.

	HW	Appropriate hardware is enabled.

	IA-64	IA-64 architecture is enabled.

	IMA     Integrity measurement architecture is enabled.

			Format: off | on

			default: on

	gcov_persist=	[GCOV] When non-zero (default), profiling data for

			kernel modules is saved and remains accessible via

			debugfs, even when the module is unloaded/reloaded.

			When zero, profiling data is discarded and associated

			debugfs files are removed at module unload time.

	gdth=		[HW,SCSI]

			See header of drivers/scsi/gdth.c.

LDFLAGS_MODULE  =

CFLAGS_KERNEL	=

AFLAGS_KERNEL	=

CFLAGS_GCOV	= -fprofile-arcs -ftest-coverage

# Use LINUXINCLUDE when you must reference the include/ directory.

export HOSTCXX HOSTCXXFLAGS LDFLAGS_MODULE CHECK CHECKFLAGS

export KBUILD_CPPFLAGS NOSTDINC_FLAGS LINUXINCLUDE OBJCOPYFLAGS LDFLAGS

export KBUILD_CFLAGS CFLAGS_KERNEL CFLAGS_MODULE

export KBUILD_CFLAGS CFLAGS_KERNEL CFLAGS_MODULE CFLAGS_GCOV

export KBUILD_AFLAGS AFLAGS_KERNEL AFLAGS_MODULE

# When compiling out-of-tree modules, put MODVERDIR in the module

		\( -name '*.[oas]' -o -name '*.ko' -o -name '.*.cmd' \

		-o -name '.*.d' -o -name '.*.tmp' -o -name '*.mod.c' \

		-o -name '*.symtypes' -o -name 'modules.order' \

		-o -name 'Module.markers' -o -name '.tmp_*.o.*' \) \

		-type f -print | xargs rm -f

		-o -name 'Module.markers' -o -name '.tmp_*.o.*' \

		-o -name '*.gcno' \) -type f -print | xargs rm -f

# mrproper - Delete all generated files, including .config

#

	$(call cmd,rmfiles)

	@find $(KBUILD_EXTMOD) $(RCS_FIND_IGNORE) \

		\( -name '*.[oas]' -o -name '*.ko' -o -name '.*.cmd' \

		-o -name '.*.d' -o -name '.*.tmp' -o -name '*.mod.c' \) \

		-type f -print | xargs rm -f

		-o -name '.*.d' -o -name '.*.tmp' -o -name '*.mod.c' \

		-o -name '*.gcno' \) -type f -print | xargs rm -f

help:

	@echo  '  Building external modules.'

config HAVE_DEFAULT_NO_SPIN_MUTEXES

	bool

source "kernel/gcov/Kconfig"

#define __must_check		__attribute__((warn_unused_result))

#endif

#ifdef CONFIG_GCOV_KERNEL

# if __GNUC_MINOR__ < 4

#   error "GCOV profiling support for gcc versions below 3.4 not included"

# endif /* __GNUC_MINOR__ */

#endif /* CONFIG_GCOV_KERNEL */

/*

 * A trick to suppress uninitialized variable warning without generating any

 * code