[mirror_ubuntu-hirsute-kernel.git] / Documentation / dev-tools / kcov.rst

kcov: code coverage for fuzzing
===============================

kcov exposes kernel code coverage information in a form suitable for coverage-
guided fuzzing (randomized testing). Coverage data of a running kernel is
exported via the "kcov" debugfs file. Coverage collection is enabled on a task
basis, and thus it can capture precise coverage of a single system call.

Note that kcov does not aim to collect as much coverage as possible. It aims
to collect more or less stable coverage that is function of syscall inputs.
To achieve this goal it does not collect coverage in soft/hard interrupts
and instrumentation of some inherently non-deterministic parts of kernel is
disabled (e.g. scheduler, locking).

kcov is also able to collect comparison operands from the instrumented code
(this feature currently requires that the kernel is compiled with clang).

Prerequisites
-------------

Configure the kernel with::

        CONFIG_KCOV=y

CONFIG_KCOV requires gcc built on revision 231296 or later.

If the comparison operands need to be collected, set::

	CONFIG_KCOV_ENABLE_COMPARISONS=y

Profiling data will only become accessible once debugfs has been mounted::

        mount -t debugfs none /sys/kernel/debug

Coverage collection
-------------------
The following program demonstrates coverage collection from within a test
program using kcov:

.. code-block:: c

    #include <stdio.h>
    #include <stddef.h>
    #include <stdint.h>
    #include <stdlib.h>
    #include <sys/types.h>
    #include <sys/stat.h>
    #include <sys/ioctl.h>
    #include <sys/mman.h>
    #include <unistd.h>
    #include <fcntl.h>

    #define KCOV_INIT_TRACE			_IOR('c', 1, unsigned long)
    #define KCOV_ENABLE			_IO('c', 100)
    #define KCOV_DISABLE			_IO('c', 101)
    #define COVER_SIZE			(64<<10)

    #define KCOV_TRACE_PC  0
    #define KCOV_TRACE_CMP 1

    int main(int argc, char **argv)
    {
	int fd;
	unsigned long *cover, n, i;

	/* A single fd descriptor allows coverage collection on a single
	 * thread.
	 */
	fd = open("/sys/kernel/debug/kcov", O_RDWR);
	if (fd == -1)
		perror("open"), exit(1);
	/* Setup trace mode and trace size. */
	if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE))
		perror("ioctl"), exit(1);
	/* Mmap buffer shared between kernel- and user-space. */
	cover = (unsigned long*)mmap(NULL, COVER_SIZE * sizeof(unsigned long),
				     PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
	if ((void*)cover == MAP_FAILED)
		perror("mmap"), exit(1);
	/* Enable coverage collection on the current thread. */
	if (ioctl(fd, KCOV_ENABLE, KCOV_TRACE_PC))
		perror("ioctl"), exit(1);
	/* Reset coverage from the tail of the ioctl() call. */
	__atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED);
	/* That's the target syscal call. */
	read(-1, NULL, 0);
	/* Read number of PCs collected. */
	n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED);
	for (i = 0; i < n; i++)
		printf("0x%lx\n", cover[i + 1]);
	/* Disable coverage collection for the current thread. After this call
	 * coverage can be enabled for a different thread.
	 */
	if (ioctl(fd, KCOV_DISABLE, 0))
		perror("ioctl"), exit(1);
	/* Free resources. */
	if (munmap(cover, COVER_SIZE * sizeof(unsigned long)))
		perror("munmap"), exit(1);
	if (close(fd))
		perror("close"), exit(1);
	return 0;
    }

After piping through addr2line output of the program looks as follows::

    SyS_read
    fs/read_write.c:562
    __fdget_pos
    fs/file.c:774
    __fget_light
    fs/file.c:746
    __fget_light
    fs/file.c:750
    __fget_light
    fs/file.c:760
    __fdget_pos
    fs/file.c:784
    SyS_read
    fs/read_write.c:562

If a program needs to collect coverage from several threads (independently),
it needs to open /sys/kernel/debug/kcov in each thread separately.

The interface is fine-grained to allow efficient forking of test processes.
That is, a parent process opens /sys/kernel/debug/kcov, enables trace mode,
mmaps coverage buffer and then forks child processes in a loop. Child processes
only need to enable coverage (disable happens automatically on thread end).

Comparison operands collection
------------------------------
Comparison operands collection is similar to coverage collection:

.. code-block:: c

    /* Same includes and defines as above. */

    /* Number of 64-bit words per record. */
    #define KCOV_WORDS_PER_CMP 4

    /*
     * The format for the types of collected comparisons.
     *
     * Bit 0 shows whether one of the arguments is a compile-time constant.
     * Bits 1 & 2 contain log2 of the argument size, up to 8 bytes.
     */

    #define KCOV_CMP_CONST          (1 << 0)
    #define KCOV_CMP_SIZE(n)        ((n) << 1)
    #define KCOV_CMP_MASK           KCOV_CMP_SIZE(3)

    int main(int argc, char **argv)
    {
	int fd;
	uint64_t *cover, type, arg1, arg2, is_const, size;
	unsigned long n, i;

	fd = open("/sys/kernel/debug/kcov", O_RDWR);
	if (fd == -1)
		perror("open"), exit(1);
	if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE))
		perror("ioctl"), exit(1);
	/*
	* Note that the buffer pointer is of type uint64_t*, because all
	* the comparison operands are promoted to uint64_t.
	*/
	cover = (uint64_t *)mmap(NULL, COVER_SIZE * sizeof(unsigned long),
				     PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
	if ((void*)cover == MAP_FAILED)
		perror("mmap"), exit(1);
	/* Note KCOV_TRACE_CMP instead of KCOV_TRACE_PC. */
	if (ioctl(fd, KCOV_ENABLE, KCOV_TRACE_CMP))
		perror("ioctl"), exit(1);
	__atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED);
	read(-1, NULL, 0);
	/* Read number of comparisons collected. */
	n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED);
	for (i = 0; i < n; i++) {
		type = cover[i * KCOV_WORDS_PER_CMP + 1];
		/* arg1 and arg2 - operands of the comparison. */
		arg1 = cover[i * KCOV_WORDS_PER_CMP + 2];
		arg2 = cover[i * KCOV_WORDS_PER_CMP + 3];
		/* ip - caller address. */
		ip = cover[i * KCOV_WORDS_PER_CMP + 4];
		/* size of the operands. */
		size = 1 << ((type & KCOV_CMP_MASK) >> 1);
		/* is_const - true if either operand is a compile-time constant.*/
		is_const = type & KCOV_CMP_CONST;
		printf("ip: 0x%lx type: 0x%lx, arg1: 0x%lx, arg2: 0x%lx, "
			"size: %lu, %s\n",
			ip, type, arg1, arg2, size,
		is_const ? "const" : "non-const");
	}
	if (ioctl(fd, KCOV_DISABLE, 0))
		perror("ioctl"), exit(1);
	/* Free resources. */
	if (munmap(cover, COVER_SIZE * sizeof(unsigned long)))
		perror("munmap"), exit(1);
	if (close(fd))
		perror("close"), exit(1);
	return 0;
    }

Note that the kcov modes (coverage collection or comparison operands) are
mutually exclusive.
Commit	Line	Data
5c9a8750 DV	1	kcov: code coverage for fuzzing
	2	===============================
	3
	4	kcov exposes kernel code coverage information in a form suitable for coverage-
	5	guided fuzzing (randomized testing). Coverage data of a running kernel is
	6	exported via the "kcov" debugfs file. Coverage collection is enabled on a task
	7	basis, and thus it can capture precise coverage of a single system call.
	8
	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 function of syscall inputs.
	11	To achieve this goal it does not collect coverage in soft/hard interrupts
	12	and instrumentation of some inherently non-deterministic parts of kernel is
8a1115ff	13	disabled (e.g. scheduler, locking).
5c9a8750	14
c512ac01 VC	15	kcov is also able to collect comparison operands from the instrumented code
	16	(this feature currently requires that the kernel is compiled with clang).
	17
	18	Prerequisites
	19	-------------
5c9a8750	20
758f726e	21	Configure the kernel with::
5c9a8750 DV	22
	23	CONFIG_KCOV=y
	24
	25	CONFIG_KCOV requires gcc built on revision 231296 or later.
c512ac01 VC	26
	27	If the comparison operands need to be collected, set::
	28
	29	CONFIG_KCOV_ENABLE_COMPARISONS=y
	30
758f726e	31	Profiling data will only become accessible once debugfs has been mounted::
5c9a8750 DV	32
	33	mount -t debugfs none /sys/kernel/debug
	34
c512ac01 VC	35	Coverage collection
	36	-------------------
	37	The following program demonstrates coverage collection from within a test
	38	program using kcov:
57131dd3 JN	39
57131dd3 JN	40	.. code-block:: c
758f726e JC	41
	42	#include <stdio.h>
	43	#include <stddef.h>
	44	#include <stdint.h>
	45	#include <stdlib.h>
	46	#include <sys/types.h>
	47	#include <sys/stat.h>
	48	#include <sys/ioctl.h>
	49	#include <sys/mman.h>
	50	#include <unistd.h>
	51	#include <fcntl.h>
	52
	53	#define KCOV_INIT_TRACE _IOR('c', 1, unsigned long)
	54	#define KCOV_ENABLE _IO('c', 100)
	55	#define KCOV_DISABLE _IO('c', 101)
	56	#define COVER_SIZE (64<<10)
	57
c512ac01 VC	58	#define KCOV_TRACE_PC 0
	59	#define KCOV_TRACE_CMP 1
	60
758f726e JC	61	int main(int argc, char **argv)
758f726e JC	62	{
5c9a8750 DV	63	int fd;
	64	unsigned long *cover, n, i;
	65
	66	/* A single fd descriptor allows coverage collection on a single
	67	* thread.
	68	*/
	69	fd = open("/sys/kernel/debug/kcov", O_RDWR);
	70	if (fd == -1)
	71	perror("open"), exit(1);
	72	/* Setup trace mode and trace size. */
	73	if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE))
	74	perror("ioctl"), exit(1);
	75	/* Mmap buffer shared between kernel- and user-space. */
	76	cover = (unsigned long)mmap(NULL, COVER_SIZE sizeof(unsigned long),
	77	PROT_READ \| PROT_WRITE, MAP_SHARED, fd, 0);
	78	if ((void*)cover == MAP_FAILED)
	79	perror("mmap"), exit(1);
	80	/* Enable coverage collection on the current thread. */
c512ac01	81	if (ioctl(fd, KCOV_ENABLE, KCOV_TRACE_PC))
5c9a8750 DV	82	perror("ioctl"), exit(1);
	83	/* Reset coverage from the tail of the ioctl() call. */
	84	__atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED);
	85	/* That's the target syscal call. */
	86	read(-1, NULL, 0);
	87	/* Read number of PCs collected. */
	88	n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED);
	89	for (i = 0; i < n; i++)
	90	printf("0x%lx\n", cover[i + 1]);
	91	/* Disable coverage collection for the current thread. After this call
	92	* coverage can be enabled for a different thread.
	93	*/
	94	if (ioctl(fd, KCOV_DISABLE, 0))
	95	perror("ioctl"), exit(1);
	96	/* Free resources. */
	97	if (munmap(cover, COVER_SIZE * sizeof(unsigned long)))
	98	perror("munmap"), exit(1);
	99	if (close(fd))
	100	perror("close"), exit(1);
	101	return 0;
758f726e JC	102	}
	103
	104	After piping through addr2line output of the program looks as follows::
	105
	106	SyS_read
	107	fs/read_write.c:562
	108	__fdget_pos
	109	fs/file.c:774
	110	__fget_light
	111	fs/file.c:746
	112	__fget_light
	113	fs/file.c:750
	114	__fget_light
	115	fs/file.c:760
	116	__fdget_pos
	117	fs/file.c:784
	118	SyS_read
	119	fs/read_write.c:562
5c9a8750 DV	120
	121	If a program needs to collect coverage from several threads (independently),
	122	it needs to open /sys/kernel/debug/kcov in each thread separately.
	123
	124	The interface is fine-grained to allow efficient forking of test processes.
	125	That is, a parent process opens /sys/kernel/debug/kcov, enables trace mode,
	126	mmaps coverage buffer and then forks child processes in a loop. Child processes
	127	only need to enable coverage (disable happens automatically on thread end).
c512ac01 VC	128
	129	Comparison operands collection
	130	------------------------------
	131	Comparison operands collection is similar to coverage collection:
	132
	133	.. code-block:: c
	134
	135	/* Same includes and defines as above. */
	136
	137	/* Number of 64-bit words per record. */
	138	#define KCOV_WORDS_PER_CMP 4
	139
	140	/*
	141	* The format for the types of collected comparisons.
	142	*
	143	* Bit 0 shows whether one of the arguments is a compile-time constant.
	144	* Bits 1 & 2 contain log2 of the argument size, up to 8 bytes.
	145	*/
	146
	147	#define KCOV_CMP_CONST (1 << 0)
	148	#define KCOV_CMP_SIZE(n) ((n) << 1)
	149	#define KCOV_CMP_MASK KCOV_CMP_SIZE(3)
	150
	151	int main(int argc, char **argv)
	152	{
	153	int fd;
	154	uint64_t *cover, type, arg1, arg2, is_const, size;
	155	unsigned long n, i;
	156
	157	fd = open("/sys/kernel/debug/kcov", O_RDWR);
	158	if (fd == -1)
	159	perror("open"), exit(1);
	160	if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE))
	161	perror("ioctl"), exit(1);
	162	/*
	163	* Note that the buffer pointer is of type uint64_t*, because all
	164	* the comparison operands are promoted to uint64_t.
	165	*/
	166	cover = (uint64_t )mmap(NULL, COVER_SIZE sizeof(unsigned long),
	167	PROT_READ \| PROT_WRITE, MAP_SHARED, fd, 0);
	168	if ((void*)cover == MAP_FAILED)
	169	perror("mmap"), exit(1);
	170	/* Note KCOV_TRACE_CMP instead of KCOV_TRACE_PC. */
	171	if (ioctl(fd, KCOV_ENABLE, KCOV_TRACE_CMP))
	172	perror("ioctl"), exit(1);
	173	__atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED);
	174	read(-1, NULL, 0);
	175	/* Read number of comparisons collected. */
	176	n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED);
	177	for (i = 0; i < n; i++) {
	178	type = cover[i * KCOV_WORDS_PER_CMP + 1];
	179	/* arg1 and arg2 - operands of the comparison. */
	180	arg1 = cover[i * KCOV_WORDS_PER_CMP + 2];
	181	arg2 = cover[i * KCOV_WORDS_PER_CMP + 3];
	182	/* ip - caller address. */
	183	ip = cover[i * KCOV_WORDS_PER_CMP + 4];
	184	/* size of the operands. */
	185	size = 1 << ((type & KCOV_CMP_MASK) >> 1);
	186	/* is_const - true if either operand is a compile-time constant.*/
	187	is_const = type & KCOV_CMP_CONST;
	188	printf("ip: 0x%lx type: 0x%lx, arg1: 0x%lx, arg2: 0x%lx, "
	189	"size: %lu, %s\n",
	190	ip, type, arg1, arg2, size,
	191	is_const ? "const" : "non-const");
192	}
193	if (ioctl(fd, KCOV_DISABLE, 0))
194	perror("ioctl"), exit(1);
195	/* Free resources. */
196	if (munmap(cover, COVER_SIZE * sizeof(unsigned long)))
197	perror("munmap"), exit(1);
198	if (close(fd))
199	perror("close"), exit(1);
200	return 0;
201	}
202
203	Note that the kcov modes (coverage collection or comparison operands) are
204	mutually exclusive.