.\"	$NetBSD: kernel_sanitizers.7,v 1.6 2020/07/12 13:40:44 skrll Exp $
.\"
.\" Copyright (c) 2020 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This code is derived from software contributed to The NetBSD Foundation
.\" by Maxime Villard.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd July 12, 2020
.Dt KERNEL_SANITIZERS 7
.Os
.Sh NAME
.Nm kernel_sanitizers
.Nd NetBSD Kernel Sanitizers
.Sh DESCRIPTION
Kernel Sanitizers are powerful kernel bug detection features that can
automatically discover several classes of bugs at run time while the kernel
executes.
.Pp
.Nx
supports four kernel sanitizers.
They are not mutually compatible, and only one can be enabled at a time, via
compilation options.
.Sh KUBSAN
Kernel Undefined Behavior Sanitizer, specializes in finding several types of
undefined behaviors, such a misaligned accesses and integer overflows.
.Ss Runtime cost
Heavy runtime checks.
.Ss Used components
Compiler instrumentation and an entirely MI runtime.
.Ss Supported architectures
aarch64 (gcc), amd64 (gcc), arm (gcc).
[Theoretically supported on all other architectures with no MD change required]
.Ss Files
.Bl -tag -width XXXX -compact
.It Pa src/common/lib/libc/misc/ubsan.c
Core KUBSAN code.
MI.
.El
.Sh KASAN
Kernel Address Sanitizer, specializes in finding memory corruptions such as
buffer overflows and use-after-frees.
.Ss Runtime cost
Heavy runtime checks, and ~12.5% increase in memory consumption.
.Ss Used components
Shadow memory, compiler instrumentation, special kernel wrappers, and
light MD infrastructure.
.Ss Supported architectures
aarch64 (gcc), amd64 (gcc, llvm), arm (gcc).
.Pp
KASAN is made of six sub-features that perform memory validation:
.Bd -literal
          +-----------------------------------------------------+
          |                SUPPORTED SUB-FEATURE                |
+---------+------+-------+---------+-----------+---------+------+
|  PORT   | HEAP | STACK | ATOMICS | BUS_SPACE | BUS_DMA | VLAs |
+---------+------+-------+---------+-----------+---------+------+
| amd64   | Yes  | Yes   | Yes     | Yes       | Yes     | Yes  |
+---------+------+-------+---------+-----------+---------+------+
| aarch64 | Yes  | Yes   | Yes     | No        | Yes     | Yes  |
+---------+------+-------+---------+-----------+---------+------+
| arm     | Yes  | Yes   | Yes     | No        | Yes     | Yes  |
+---------+------+-------+---------+-----------+---------+------+
.Ed
.Pp
An architecture is allowed to have only partial support.
.Ss Files
.Bl -tag -width XXXX -compact
.It Pa src/sys/kern/subr_asan.c
Core KASAN code.
MI.
.It Pa src/sys/sys/asan.h
Main KASAN header.
MI.
.It Pa src/sys/arch/{port}/include/asan.h
Port-specific KASAN code.
MD.
.El
.Pp
Each new port of KASAN should respect the existing naming conventions, and
should introduce only one MD header file.
.Sh KCSAN
Kernel Concurrency Sanitizer, specializes in finding memory races.
.Ss Runtime cost
Medium runtime checks.
.Ss Used components
Compiler instrumentation, special kernel wrappers, and light MD infrastructure.
.Ss Supported architectures
amd64 (gcc).
.Ss Files
.Bl -tag -width XXXX -compact
.It Pa src/sys/kern/subr_csan.c
Core KCSAN code.
MI.
.It Pa src/sys/sys/csan.h
Main KCSAN header.
MI.
.It Pa src/sys/arch/{port}/include/csan.h
Port-specific KCSAN code.
MD.
.El
.Pp
Each new port of KCSAN should respect the existing naming conventions, and
should introduce only one MD header file.
.Sh KMSAN
Kernel Memory Sanitizer, specializes in finding uninitialized memory.
.Ss Runtime cost
Heavy runtime checks, and ~200% increase in memory consumption.
.Ss Used components
Double shadow memory, compiler instrumentation, special kernel wrappers, and
heavy MD infrastructure.
.Ss Supported architectures
amd64 (llvm).
.Ss Files
.Bl -tag -width XXXX -compact
.It Pa src/sys/kern/subr_msan.c
Core KMSAN code.
MI.
.It Pa src/sys/sys/msan.h
Main KMSAN header.
MI.
.It Pa src/sys/arch/{port}/include/msan.h
Port-specific KMSAN code.
MD.
.El
.Pp
Each new port of KMSAN should respect the existing naming conventions, and
should introduce only one MD header file.
.Sh AUTHORS
.An -nosplit
Support for KUBSAN was developed by
.An Kamil Rytarowski .
Support for KASAN, KCSAN and KMSAN was developed by
.An Maxime Villard .
Support for KASAN on ARM was developed by
.An Nick Hudson .