]>
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 | |
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) |
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. |