Wed Jun 24 08:20:13 2020 UTC ()
New sentence, new line. Fix macro arguments. Improve Nd.
Remove superfluous Pp. Other minor cleanups.


(wiz)
diff -r1.1 -r1.2 src/share/man/man7/kernel_sanitizers.7
cvs diff -r1.1 -r1.2 src/share/man/man7/kernel_sanitizers.7 (expand / switch to unified diff)

--- src/share/man/man7/kernel_sanitizers.7 2020/06/23 16:08:46 1.1
+++ src/share/man/man7/kernel_sanitizers.7 2020/06/24 08:20:13 1.2
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: kernel_sanitizers.7,v 1.1 2020/06/23 16:08:46 maxv Exp $ 1.\" $NetBSD: kernel_sanitizers.7,v 1.2 2020/06/24 08:20:13 wiz Exp $
2.\" 2.\"
3.\" Copyright (c) 2020 The NetBSD Foundation, Inc. 3.\" Copyright (c) 2020 The NetBSD Foundation, Inc.
4.\" All rights reserved. 4.\" All rights reserved.
5.\" 5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation 6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Maxime Villard. 7.\" by Maxime Villard.
8.\" 8.\"
9.\" Redistribution and use in source and binary forms, with or without 9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions 10.\" modification, are permitted provided that the following conditions
11.\" are met: 11.\" are met:
12.\" 1. Redistributions of source code must retain the above copyright 12.\" 1. Redistributions of source code must retain the above copyright
13.\" notice, this list of conditions and the following disclaimer. 13.\" notice, this list of conditions and the following disclaimer.
14.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" 2. Redistributions in binary form must reproduce the above copyright
@@ -18,129 +18,136 @@ @@ -18,129 +18,136 @@
18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
28.\" POSSIBILITY OF SUCH DAMAGE. 28.\" POSSIBILITY OF SUCH DAMAGE.
29.\" 29.\"
30.Dd June 22, 2020 30.Dd June 22, 2020
31.Dt kernel_sanitizers 7 31.Dt KERNEL_SANITIZERS 7
32.Os 32.Os
33.Sh NAME 33.Sh NAME
34.Nm kernel_sanitizers 34.Nm kernel_sanitizers
35.Nd 35.Nd NetBSD Kernel Sanitizers
36.Nx 
37Kernel Sanitizers 
38.Sh DESCRIPTION 36.Sh DESCRIPTION
39Kernel Sanitizers are powerful kernel bug detection features that can 37Kernel Sanitizers are powerful kernel bug detection features that can
40automatically discover several classes of bugs at run time while the kernel 38automatically discover several classes of bugs at run time while the kernel
41executes. 39executes.
42.Pp 40.Pp
43.Nx 41.Nx
44supports four kernel sanitizers. 42supports four kernel sanitizers.
45They are not mutually compatible, and only one can be enabled at a time, via 43They are not mutually compatible, and only one can be enabled at a time, via
46compilation options. 44compilation options.
47.Sh KUBSAN 45.Sh KUBSAN
48Kernel Undefined Behavior Sanitizer, specializes in finding several types of 46Kernel Undefined Behavior Sanitizer, specializes in finding several types of
49undefined behaviors, such a misaligned accesses and integer overflows. 47undefined behaviors, such a misaligned accesses and integer overflows.
50.Ss Runtime cost 48.Ss Runtime cost
51Heavy runtime checks. 49Heavy runtime checks.
52.Ss Used components 50.Ss Used components
53Compiler instrumentation and an entirely MI runtime. 51Compiler instrumentation and an entirely MI runtime.
54.Ss Supported architectures 52.Ss Supported architectures
55aarch64 (gcc), amd64 (gcc). 53aarch64 (gcc), amd64 (gcc).
56[Theoretically supported on all other architectures with no MD change required] 54[Theoretically supported on all other architectures with no MD change required]
57.Ss Files 55.Ss Files
58.Pp 
59.Bl -tag -width XXXX -compact 56.Bl -tag -width XXXX -compact
60.It Pa src/common/lib/libc/misc/ 57.It Pa src/common/lib/libc/misc/
61Core KUBSAN code. MI. 58Core KUBSAN code.
 59MI.
62.El 60.El
63.Sh KASAN 61.Sh KASAN
64Kernel Address Sanitizer, specializes in finding memory corruptions such as 62Kernel Address Sanitizer, specializes in finding memory corruptions such as
65buffer overflows and use-after-frees. 63buffer overflows and use-after-frees.
66.Pp 
67.Ss Runtime cost 64.Ss Runtime cost
68Heavy runtime checks, and ~12.5% increase in memory consumption. 65Heavy runtime checks, and ~12.5% increase in memory consumption.
69.Ss Used components 66.Ss Used components
70Shadow memory, compiler instrumentation, special kernel wrappers, and 67Shadow memory, compiler instrumentation, special kernel wrappers, and
71light MD infrastructure. 68light MD infrastructure.
72.Ss Supported architectures 69.Ss Supported architectures
73aarch64 (gcc), amd64 (gcc, llvm). 70aarch64 (gcc), amd64 (gcc, llvm).
74.Pp 71.Pp
75KASAN is made of six sub-features that perform memory validation: 72KASAN is made of six sub-features that perform memory validation:
76.Bd -literal 73.Bd -literal
77 +-----------------------------------------------------+ 74 +-----------------------------------------------------+
78 | SUPPORTED SUB-FEATURE | 75 | SUPPORTED SUB-FEATURE |
79+---------+------+-------+---------+-----------+---------+------+ 76+---------+------+-------+---------+-----------+---------+------+
80| PORT | HEAP | STACK | ATOMICS | BUS_SPACE | BUS_DMA | VLAs | 77| PORT | HEAP | STACK | ATOMICS | BUS_SPACE | BUS_DMA | VLAs |
81+---------+------+-------+---------+-----------+---------+------+ 78+---------+------+-------+---------+-----------+---------+------+
82| amd64 | Yes | Yes | Yes | Yes | Yes | Yes | 79| amd64 | Yes | Yes | Yes | Yes | Yes | Yes |
83+---------+------+-------+---------+-----------+---------+------+ 80+---------+------+-------+---------+-----------+---------+------+
84| aarch64 | Yes | Yes | Yes | No | Yes | Yes | 81| aarch64 | Yes | Yes | Yes | No | Yes | Yes |
85+---------+------+-------+---------+-----------+---------+------+ 82+---------+------+-------+---------+-----------+---------+------+
86.Ed 83.Ed
87.Pp 84.Pp
88An architecture is allowed to have only partial support. 85An architecture is allowed to have only partial support.
89.Ss Files 86.Ss Files
90.Bl -tag -width XXXX -compact 87.Bl -tag -width XXXX -compact
91.It Pa src/sys/kern/subr_asan.c 88.It Pa src/sys/kern/subr_asan.c
92Core KASAN code. MI. 89Core KASAN code.
 90MI.
93.It Pa src/sys/sys/asan.h 91.It Pa src/sys/sys/asan.h
94Main KASAN header. MI. 92Main KASAN header.
 93MI.
95.It Pa src/sys/arch/{port}/include/asan.h 94.It Pa src/sys/arch/{port}/include/asan.h
96Port-specific KASAN code. MD. 95Port-specific KASAN code.
 96MD.
97.El 97.El
98.Pp 98.Pp
99Each new port of KASAN should respect the existing naming conventions, and 99Each new port of KASAN should respect the existing naming conventions, and
100should introduce only one MD header file. 100should introduce only one MD header file.
101.Sh KCSAN 101.Sh KCSAN
102Kernel Concurrency Sanitizer, specializes in finding memory races. 102Kernel Concurrency Sanitizer, specializes in finding memory races.
103.Ss Runtime cost 103.Ss Runtime cost
104Medium runtime checks. 104Medium runtime checks.
105.Ss Used components 105.Ss Used components
106Compiler instrumentation, special kernel wrappers, and light MD infrastructure. 106Compiler instrumentation, special kernel wrappers, and light MD infrastructure.
107.Ss Supported architectures 107.Ss Supported architectures
108amd64 (gcc). 108amd64 (gcc).
109.Ss Files 109.Ss Files
110.Bl -tag -width XXXX -compact 110.Bl -tag -width XXXX -compact
111.It Pa src/sys/kern/subr_csan.c 111.It Pa src/sys/kern/subr_csan.c
112Core KCSAN code. MI. 112Core KCSAN code.
 113MI.
113.It Pa src/sys/sys/csan.h 114.It Pa src/sys/sys/csan.h
114Main KCSAN header. MI. 115Main KCSAN header.
 116MI.
115.It Pa src/sys/arch/{port}/include/csan.h 117.It Pa src/sys/arch/{port}/include/csan.h
116Port-specific KCSAN code. MD. 118Port-specific KCSAN code.
 119MD.
117.El 120.El
118.Pp 121.Pp
119Each new port of KCSAN should respect the existing naming conventions, and 122Each new port of KCSAN should respect the existing naming conventions, and
120should introduce only one MD header file. 123should introduce only one MD header file.
121.Sh KMSAN 124.Sh KMSAN
122Kernel Memory Sanitizer, specializes in finding uninitialized memory. 125Kernel Memory Sanitizer, specializes in finding uninitialized memory.
123.Ss Runtime cost 126.Ss Runtime cost
124Heavy runtime checks, and ~100% increase in memory consumption. 127Heavy runtime checks, and ~100% increase in memory consumption.
125.Ss Used components 128.Ss Used components
126Shadow memory, compiler instrumentation, special kernel wrappers, and heavy MD 129Shadow memory, compiler instrumentation, special kernel wrappers, and heavy MD
127infrastructure. 130infrastructure.
128.Ss Supported architectures 131.Ss Supported architectures
129amd64 (llvm). 132amd64 (llvm).
130.Ss Files 133.Ss Files
131.Bl -tag -width XXXX -compact 134.Bl -tag -width XXXX -compact
132.It Pa src/sys/kern/subr_msan.c 135.It Pa src/sys/kern/subr_msan.c
133Core KMSAN code. MI. 136Core KMSAN code.
 137MI.
134.It Pa src/sys/sys/msan.h 138.It Pa src/sys/sys/msan.h
135Main KMSAN header. MI. 139Main KMSAN header.
 140MI.
136.It Pa src/sys/arch/{port}/include/msan.h 141.It Pa src/sys/arch/{port}/include/msan.h
137Port-specific KMSAN code. MD. 142Port-specific KMSAN code.
 143MD.
138.El 144.El
139.Pp 145.Pp
140Each new port of KMSAN should respect the existing naming conventions, and 146Each new port of KMSAN should respect the existing naming conventions, and
141should introduce only one MD header file. 147should introduce only one MD header file.
142.Sh AUTHORS 148.Sh AUTHORS
 149.An -nosplit
143Support for KUBSAN was developed by 150Support for KUBSAN was developed by
144.An Kamil Rytarowski . 151.An Kamil Rytarowski .
145Support for KASAN, KCSAN and KMSAN was developed by 152Support for KASAN, KCSAN and KMSAN was developed by
146.An Maxime Villard . 153.An Maxime Villard .