mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
274 lines
7.9 KiB
274 lines
7.9 KiB
Using gcov with the Linux kernel |
|
================================ |
|
|
|
gcov profiling kernel support enables the use of GCC's coverage testing |
|
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):: |
|
|
|
# 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_ 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?) |
|
|
|
.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html |
|
.. _lcov: http://ltp.sourceforge.net/coverage/lcov.php |
|
|
|
|
|
Preparation |
|
----------- |
|
|
|
Configure the kernel with:: |
|
|
|
CONFIG_DEBUG_FS=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 |
|
|
|
|
|
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. |
|
|
|
|
|
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``. |
|
|
|
|
|
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. |
|
|
|
|
|
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: |
|
|
|
.. _gcov-test: |
|
|
|
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). |
|
|
|
.. _gcov-build: |
|
|
|
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 |
|
|
|
|
|
Note on compilers |
|
----------------- |
|
|
|
GCC and LLVM gcov tools are not necessarily compatible. Use gcov_ to work with |
|
GCC-generated .gcno and .gcda files, and use llvm-cov_ for Clang. |
|
|
|
.. _gcov: https://gcc.gnu.org/onlinedocs/gcc/Gcov.html |
|
.. _llvm-cov: https://llvm.org/docs/CommandGuide/llvm-cov.html |
|
|
|
Build differences between GCC and Clang gcov are handled by Kconfig. It |
|
automatically selects the appropriate gcov format depending on the detected |
|
toolchain. |
|
|
|
|
|
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. |
|
|
|
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. |
|
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 :ref:`Separated build and test machines a. <gcov-test>`): |
|
|
|
.. code-block:: sh |
|
|
|
#!/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 :ref:`Separated build and test machines b. <gcov-build>`): |
|
|
|
.. code-block:: sh |
|
|
|
#!/bin/bash -e |
|
|
|
DEST=$1 |
|
GCDA=/sys/kernel/debug/gcov |
|
|
|
if [ -z "$DEST" ] ; then |
|
echo "Usage: $0 <output.tar.gz>" >&2 |
|
exit 1 |
|
fi |
|
|
|
TEMPDIR=$(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 sys |
|
rm -rf $TEMPDIR |
|
|
|
echo "$DEST successfully created, copy to build system and unpack with:" |
|
echo " tar xfz $DEST"
|
|
|