docs: sphinixfy gcov.txt and move to dev-tools

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

tool gcov_ 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):

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

as lcov_ can be used to automate the process of collecting data

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

Possible uses:

* 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

.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html

.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php

2. Preparation

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

Preparation

-----------

Configure the kernel with:

Configure the kernel with::

        CONFIG_DEBUG_FS=y

        CONFIG_GCOV_KERNEL=y

select the gcc's gcov format, default is autodetect based on gcc version:

select the gcc's gcov format, default is autodetect based on gcc version::

        CONFIG_GCOV_FORMAT_AUTODETECT=y

and to get coverage data for the entire kernel:

and to get coverage data for the entire kernel::

        CONFIG_GCOV_PROFILE_ALL=y

on all architectures.

Profiling data will only become accessible once debugfs has been

mounted:

mounted::

        mount -t debugfs none /sys/kernel/debug

3. Customization

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

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):

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

	GCOV_PROFILE_main.o := y

        For all files in one directory:

- For all files in one directory::

	GCOV_PROFILE := y

To exclude files from being profiled even when CONFIG_GCOV_PROFILE_ALL

is specified, use:

is specified, use::

	GCOV_PROFILE_main.o := n

        and:

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

========

Files

-----

The gcov kernel support creates the following files in debugfs:

        /sys/kernel/debug/gcov

``/sys/kernel/debug/gcov``

	Parent directory for all gcov-related files.

        /sys/kernel/debug/gcov/reset

``/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

``/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

``/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.

        option ``-ftest-coverage``.

5. Modules

==========

Modules

-------

Kernel modules may contain cleanup code which is only run during

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

initialized with the data from its previous instantiation.

This behavior can be deactivated by specifying the gcov_persist kernel

parameter:

parameter::

        gcov_persist=0

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

6. Separated build and test machines

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

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

    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:

    Example directory setup on the build machine::

      /tmp/linux:    kernel source tree

      /tmp/out:      kernel build directory as specified by make O=

      [user@build] gcov -o /tmp/coverage/tmp/out/init main.c

7. Troubleshooting

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

Troubleshooting

---------------

Problem

    Compilation aborts during linker step.

Problem:  Compilation aborts during linker step.

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

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

Solution

    Exclude affected source files from profiling by specifying

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

    corresponding Makefile.

Problem:  Files copied from sysfs appear empty or incomplete.

Cause:    Due to the way seq_file works, some tools such as cp or tar

Problem

    Files copied from sysfs appear empty or incomplete.

Cause

    Due to the way seq_file works, some tools such as cp or tar

    may not correctly copy files from sysfs.

Solution: Use 'cat' to read .gcda files and 'cp -d' to copy links.

Solution

    Use ``cat``' to read ``.gcda`` files and ``cp -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):

(see 6a)::

    #!/bin/bash

    KSRC=$1

Appendix B: gather_on_test.sh

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

-----------------------------

Sample script to gather coverage data files on the test machine

(see 6b):

(see 6b)::

    #!/bin/bash -e

   coccinelle

   sparse

   kcov

   gcov

M:	Peter Oberparleiter <oberpar@linux.vnet.ibm.com>

S:	Maintained

F:	kernel/gcov/

F:	Documentation/gcov.txt

F:	Documentation/dev-tools/gcov.rst

GDT SCSI DISK ARRAY CONTROLLER DRIVER

M:	Achim Leubner <achim_leubner@adaptec.com>