Copyright (c) 2018 Anton Lindqvist <anton@openbsd.org>
Permission to use, copy, modify, and distribute this software for any
purpose with or without fee is hereby granted, provided that the above
copyright notice and this permission notice appear in all copies.
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.Dd November 16, 2018 .Dt KCOV 4 .Os .Sh NAME .Nm kcov .Nd kernel code coverage tracing .Sh SYNOPSIS .Cd options KCOV
p n sys/kcov.h .Sh DESCRIPTION The .Nm driver implements collection of code coverage inside the kernel. It can be enabled on a per process basis from userland, allowing the kernel program counter to be collected during syscalls triggered by the same process. The collected coverage can be accessed by mapping the device using .Xr mmap 2 .
p By default, .Nm is not enabled but requires the compile-time configuration .Cd makeoptions KCOV .Cd options KCOV to be present, see .Xr options 4 .
p The following .Xr ioctl 2 calls are provided: l -tag -width 4n t Dv KCOV_IOC_SETBUFSIZE Fa uint64_t *nentries Allocate a coverage buffer with a capacity of .Fa nentries . The buffer can be accessed using .Xr mmap 2 whereas the returned pointer must be interpreted as an array of .Vt kcov_int_t entries. Note that kcov_int_t is volatile. The first entry contains the number of entries in the array, excluding the first entry. t Dv KCOV_IOC_ENABLE Fa void Enable code coverage tracing for the current thread. t Dv KCOV_IOC_DISABLE Fa void Disable code coverage tracing for the current thread. .El .Sh FILES l -tag -width /dev/kcov -compact t Pa /dev/kcov Default device node. .El .Sh EXAMPLES In the following example, the .Xr read 2 syscall is traced and the coverage displayed, which in turn can be passed to .Xr addr2line 1 in order to translate the kernel program counter into the file name and line number it corresponds to. d -literal #include <err.h> #include <fcntl.h> #include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <sys/ioccom.h> #include <sys/ioctl.h> #include <sys/mman.h> #include <sys/kcov.h> int main(void) { kcov_int_t *cover, i, n; kcov_int_t size = 1024 * 100; int fd; fd = open("/dev/kcov", O_RDWR); if (fd == -1) err(1, "open"); if (ioctl(fd, KCOV_IOC_SETBUFSIZE, &size) == -1) err(1, "ioctl: KCOV_IOC_SETBUFSIZE"); cover = mmap(NULL, size * KCOV_ENTRY_SIZE, PROT_READ | PROT_WRITE, MAP_PRIVATE, fd, 0); if (cover == MAP_FAILED) err(1, "mmap"); if (ioctl(fd, KCOV_IOC_ENABLE) == -1) err(1, "ioctl: KCOV_IOC_ENABLE"); __atomic_store_n(&cover[0], 0, __ATOMIC_RELAXED); read(-1, NULL, 0); /* syscall paths to be traced */ n = __atomic_load_n(&cover[0], __ATOMIC_RELAXED); if (ioctl(fd, KCOV_IOC_DISABLE) == -1) err(1, "ioctl: KCOV_IOC_DISABLE"); for (i = 0; i < cover[0]; i++) printf("%p\en", (void *)cover[i + 1]); if (munmap(cover, size * KCOV_ENTRY_SIZE) == -1) err(1, "munmap"); close(fd); return 0; } .Ed .Sh SEE ALSO .Xr options 4 .Sh HISTORY The .Nm driver was initially developed in Linux. A driver based on the same concept was then implemented in .Nx 9 . .Sh AUTHORS .An Siddharth Muralee Aq Mt siddharth.muralee@gmail.com