Documentation/dev-tools/kcov.rst

1 KCOV: code coverage for fuzzing
4 KCOV collects and exposes kernel code coverage information in a form suitable
5 for coverage-guided fuzzing. Coverage data of a running kernel is exported via
6 the ``kcov`` debugfs file. Coverage collection is enabled on a task basis, and
7 thus KCOV can capture precise coverage of a single system call.
9 Note that KCOV does not aim to collect as much coverage as possible. It aims
10 to collect more or less stable coverage that is a function of syscall inputs.
11 To achieve this goal, it does not collect coverage in soft/hard interrupts
12 (unless remove coverage collection is enabled, see below) and from some
15 Besides collecting code coverage, KCOV can also collect comparison operands.
18 Besides collecting coverage data from syscall handlers, KCOV can also collect
19 coverage for annotated parts of the kernel executing in background kernel
20 tasks or soft interrupts. See the "Remote coverage collection" section for
39 Coverage data only becomes accessible once debugfs has been mounted::
43 Coverage collection
46 The following program demonstrates how to use KCOV to collect coverage for a
76 	/* A single fd descriptor allows coverage collection on a single
90 	/* Enable coverage collection on the current thread. */
93 	/* Reset coverage from the tail of the ioctl() call. */
101 	/* Disable coverage collection for the current thread. After this call
102 	 * coverage can be enabled for a different thread.
131 If a program needs to collect coverage from several threads (independently),
136 mmaps coverage buffer, and then forks child processes in a loop. The child
137 processes only need to enable coverage (it gets disabled automatically when
143 Comparison operands collection is similar to coverage collection:
217 Note that the KCOV modes (collection of code coverage or comparison operands)
220 Remote coverage collection
223 Besides collecting coverage data from handlers of syscalls issued from a
224 userspace process, KCOV can also collect coverage for parts of the kernel
225 executing in other contexts - so-called "remote" coverage.
227 Using KCOV to collect remote coverage requires:
229 1. Modifying kernel code to annotate the code section from where coverage
233    process that collects coverage.
236 ``KCOV_REMOTE_ENABLE`` ioctl accept handles that identify particular coverage
240 KCOV supports collecting remote coverage from the following contexts:
281 In practice, any value can be used for common handle instance id if coverage
287 The following program demonstrates using KCOV to collect coverage from both
342 	/* Enable coverage collection via common handle and from USB bus #1. */