^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) kcov: code coverage for fuzzing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) ===============================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) kcov exposes kernel code coverage information in a form suitable for coverage-
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) guided fuzzing (randomized testing). Coverage data of a running kernel is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) exported via the "kcov" debugfs file. Coverage collection is enabled on a task
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) basis, and thus it can capture precise coverage of a single system call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) Note that kcov does not aim to collect as much coverage as possible. It aims
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) to collect more or less stable coverage that is function of syscall inputs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) To achieve this goal it does not collect coverage in soft/hard interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) and instrumentation of some inherently non-deterministic parts of kernel is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) disabled (e.g. scheduler, locking).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) kcov is also able to collect comparison operands from the instrumented code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) (this feature currently requires that the kernel is compiled with clang).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) Prerequisites
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) -------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) Configure the kernel with::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) CONFIG_KCOV=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) CONFIG_KCOV requires gcc 6.1.0 or later.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) If the comparison operands need to be collected, set::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) CONFIG_KCOV_ENABLE_COMPARISONS=y
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) Profiling data will only become accessible once debugfs has been mounted::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) mount -t debugfs none /sys/kernel/debug
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) Coverage collection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) The following program demonstrates coverage collection from within a test
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) program using kcov:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) #include <stdio.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) #include <stddef.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) #include <stdint.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) #include <stdlib.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) #include <sys/types.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) #include <sys/stat.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) #include <sys/ioctl.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) #include <sys/mman.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) #include <unistd.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) #include <fcntl.h>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) #define KCOV_INIT_TRACE _IOR('c', 1, unsigned long)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) #define KCOV_ENABLE _IO('c', 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) #define KCOV_DISABLE _IO('c', 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) #define COVER_SIZE (64<<10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) #define KCOV_TRACE_PC 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) #define KCOV_TRACE_CMP 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) int main(int argc, char **argv)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) int fd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) unsigned long *cover, n, i;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) /* A single fd descriptor allows coverage collection on a single
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) * thread.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) fd = open("/sys/kernel/debug/kcov", O_RDWR);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) if (fd == -1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) perror("open"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) /* Setup trace mode and trace size. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) perror("ioctl"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) /* Mmap buffer shared between kernel- and user-space. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) cover = (unsigned long*)mmap(NULL, COVER_SIZE * sizeof(unsigned long),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) if ((void*)cover == MAP_FAILED)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) perror("mmap"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) /* Enable coverage collection on the current thread. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) if (ioctl(fd, KCOV_ENABLE, KCOV_TRACE_PC))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) perror("ioctl"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) /* Reset coverage from the tail of the ioctl() call. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) __atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) /* That's the target syscal call. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) read(-1, NULL, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) /* Read number of PCs collected. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) for (i = 0; i < n; i++)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) printf("0x%lx\n", cover[i + 1]);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) /* Disable coverage collection for the current thread. After this call
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) * coverage can be enabled for a different thread.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) if (ioctl(fd, KCOV_DISABLE, 0))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) perror("ioctl"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) /* Free resources. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) if (munmap(cover, COVER_SIZE * sizeof(unsigned long)))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) perror("munmap"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) if (close(fd))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) perror("close"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) After piping through addr2line output of the program looks as follows::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) SyS_read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) fs/read_write.c:562
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) __fdget_pos
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) fs/file.c:774
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) __fget_light
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) fs/file.c:746
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) __fget_light
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) fs/file.c:750
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) __fget_light
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) fs/file.c:760
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) __fdget_pos
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) fs/file.c:784
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) SyS_read
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) fs/read_write.c:562
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) If a program needs to collect coverage from several threads (independently),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) it needs to open /sys/kernel/debug/kcov in each thread separately.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) The interface is fine-grained to allow efficient forking of test processes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) That is, a parent process opens /sys/kernel/debug/kcov, enables trace mode,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) mmaps coverage buffer and then forks child processes in a loop. Child processes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) only need to enable coverage (disable happens automatically on thread end).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) Comparison operands collection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) Comparison operands collection is similar to coverage collection:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) /* Same includes and defines as above. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) /* Number of 64-bit words per record. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) #define KCOV_WORDS_PER_CMP 4
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) * The format for the types of collected comparisons.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) *
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) * Bit 0 shows whether one of the arguments is a compile-time constant.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) * Bits 1 & 2 contain log2 of the argument size, up to 8 bytes.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) #define KCOV_CMP_CONST (1 << 0)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) #define KCOV_CMP_SIZE(n) ((n) << 1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) #define KCOV_CMP_MASK KCOV_CMP_SIZE(3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) int main(int argc, char **argv)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) int fd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) uint64_t *cover, type, arg1, arg2, is_const, size;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) unsigned long n, i;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) fd = open("/sys/kernel/debug/kcov", O_RDWR);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) if (fd == -1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) perror("open"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) perror("ioctl"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) * Note that the buffer pointer is of type uint64_t*, because all
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) * the comparison operands are promoted to uint64_t.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) cover = (uint64_t *)mmap(NULL, COVER_SIZE * sizeof(unsigned long),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) if ((void*)cover == MAP_FAILED)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) perror("mmap"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) /* Note KCOV_TRACE_CMP instead of KCOV_TRACE_PC. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) if (ioctl(fd, KCOV_ENABLE, KCOV_TRACE_CMP))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) perror("ioctl"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) __atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) read(-1, NULL, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) /* Read number of comparisons collected. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) for (i = 0; i < n; i++) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) type = cover[i * KCOV_WORDS_PER_CMP + 1];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) /* arg1 and arg2 - operands of the comparison. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) arg1 = cover[i * KCOV_WORDS_PER_CMP + 2];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) arg2 = cover[i * KCOV_WORDS_PER_CMP + 3];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) /* ip - caller address. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) ip = cover[i * KCOV_WORDS_PER_CMP + 4];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) /* size of the operands. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) size = 1 << ((type & KCOV_CMP_MASK) >> 1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) /* is_const - true if either operand is a compile-time constant.*/
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) is_const = type & KCOV_CMP_CONST;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) printf("ip: 0x%lx type: 0x%lx, arg1: 0x%lx, arg2: 0x%lx, "
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) "size: %lu, %s\n",
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) ip, type, arg1, arg2, size,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) is_const ? "const" : "non-const");
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) if (ioctl(fd, KCOV_DISABLE, 0))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) perror("ioctl"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) /* Free resources. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) if (munmap(cover, COVER_SIZE * sizeof(unsigned long)))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) perror("munmap"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) if (close(fd))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) perror("close"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) Note that the kcov modes (coverage collection or comparison operands) are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) mutually exclusive.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208) Remote coverage collection
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) --------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) With KCOV_ENABLE coverage is collected only for syscalls that are issued
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) from the current process. With KCOV_REMOTE_ENABLE it's possible to collect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) coverage for arbitrary parts of the kernel code, provided that those parts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) are annotated with kcov_remote_start()/kcov_remote_stop().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) This allows to collect coverage from two types of kernel background
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) threads: the global ones, that are spawned during kernel boot in a limited
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) number of instances (e.g. one USB hub_event() worker thread is spawned per
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) USB HCD); and the local ones, that are spawned when a user interacts with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) some kernel interface (e.g. vhost workers); as well as from soft
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) interrupts.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) To enable collecting coverage from a global background thread or from a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) softirq, a unique global handle must be assigned and passed to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) corresponding kcov_remote_start() call. Then a userspace process can pass
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) a list of such handles to the KCOV_REMOTE_ENABLE ioctl in the handles
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) array field of the kcov_remote_arg struct. This will attach the used kcov
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) device to the code sections, that are referenced by those handles.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) Since there might be many local background threads spawned from different
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) userspace processes, we can't use a single global handle per annotation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) Instead, the userspace process passes a non-zero handle through the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233) common_handle field of the kcov_remote_arg struct. This common handle gets
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234) saved to the kcov_handle field in the current task_struct and needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) passed to the newly spawned threads via custom annotations. Those threads
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) should in turn be annotated with kcov_remote_start()/kcov_remote_stop().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) Internally kcov stores handles as u64 integers. The top byte of a handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) is used to denote the id of a subsystem that this handle belongs to, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) the lower 4 bytes are used to denote the id of a thread instance within
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) that subsystem. A reserved value 0 is used as a subsystem id for common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242) handles as they don't belong to a particular subsystem. The bytes 4-7 are
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) currently reserved and must be zero. In the future the number of bytes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244) used for the subsystem or handle ids might be increased.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) When a particular userspace proccess collects coverage via a common
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) handle, kcov will collect coverage for each code section that is annotated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248) to use the common handle obtained as kcov_handle from the current
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) task_struct. However non common handles allow to collect coverage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) selectively from different subsystems.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) .. code-block:: c
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254) struct kcov_remote_arg {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255) __u32 trace_mode;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) __u32 area_size;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) __u32 num_handles;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258) __aligned_u64 common_handle;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) __aligned_u64 handles[0];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) #define KCOV_INIT_TRACE _IOR('c', 1, unsigned long)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) #define KCOV_DISABLE _IO('c', 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) #define KCOV_REMOTE_ENABLE _IOW('c', 102, struct kcov_remote_arg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266) #define COVER_SIZE (64 << 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) #define KCOV_TRACE_PC 0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) #define KCOV_SUBSYSTEM_COMMON (0x00ull << 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) #define KCOV_SUBSYSTEM_USB (0x01ull << 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) #define KCOV_SUBSYSTEM_MASK (0xffull << 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) #define KCOV_INSTANCE_MASK (0xffffffffull)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) static inline __u64 kcov_remote_handle(__u64 subsys, __u64 inst)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) if (subsys & ~KCOV_SUBSYSTEM_MASK || inst & ~KCOV_INSTANCE_MASK)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) return subsys | inst;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281) }
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) #define KCOV_COMMON_ID 0x42
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) #define KCOV_USB_BUS_NUM 1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) int main(int argc, char **argv)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) int fd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) unsigned long *cover, n, i;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) struct kcov_remote_arg *arg;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) fd = open("/sys/kernel/debug/kcov", O_RDWR);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293) if (fd == -1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294) perror("open"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) if (ioctl(fd, KCOV_INIT_TRACE, COVER_SIZE))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) perror("ioctl"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297) cover = (unsigned long*)mmap(NULL, COVER_SIZE * sizeof(unsigned long),
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) PROT_READ | PROT_WRITE, MAP_SHARED, fd, 0);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) if ((void*)cover == MAP_FAILED)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) perror("mmap"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) /* Enable coverage collection via common handle and from USB bus #1. */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) arg = calloc(1, sizeof(*arg) + sizeof(uint64_t));
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304) if (!arg)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) perror("calloc"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) arg->trace_mode = KCOV_TRACE_PC;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) arg->area_size = COVER_SIZE;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) arg->num_handles = 1;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) arg->common_handle = kcov_remote_handle(KCOV_SUBSYSTEM_COMMON,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) KCOV_COMMON_ID);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311) arg->handles[0] = kcov_remote_handle(KCOV_SUBSYSTEM_USB,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312) KCOV_USB_BUS_NUM);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) if (ioctl(fd, KCOV_REMOTE_ENABLE, arg))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) perror("ioctl"), free(arg), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315) free(arg);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) * Here the user needs to trigger execution of a kernel code section
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319) * that is either annotated with the common handle, or to trigger some
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) * activity on USB bus #1.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322) sleep(2);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) for (i = 0; i < n; i++)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326) printf("0x%lx\n", cover[i + 1]);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) if (ioctl(fd, KCOV_DISABLE, 0))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328) perror("ioctl"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) if (munmap(cover, COVER_SIZE * sizeof(unsigned long)))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) perror("munmap"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331) if (close(fd))
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332) perror("close"), exit(1);
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) return 0;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) }
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags