~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/dev-tools/kmsan.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/dev-tools/kmsan.rst (Version linux-6.12-rc7) and /Documentation/dev-tools/kmsan.rst (Version linux-6.2.16)


  1 .. SPDX-License-Identifier: GPL-2.0                 1 .. SPDX-License-Identifier: GPL-2.0
  2 .. Copyright (C) 2022, Google LLC.                  2 .. Copyright (C) 2022, Google LLC.
  3                                                     3 
  4 ===============================                !!   4 ===================================
  5 Kernel Memory Sanitizer (KMSAN)                !!   5 The Kernel Memory Sanitizer (KMSAN)
  6 ===============================                !!   6 ===================================
  7                                                     7 
  8 KMSAN is a dynamic error detector aimed at fin      8 KMSAN is a dynamic error detector aimed at finding uses of uninitialized
  9 values. It is based on compiler instrumentatio      9 values. It is based on compiler instrumentation, and is quite similar to the
 10 userspace `MemorySanitizer tool`_.                 10 userspace `MemorySanitizer tool`_.
 11                                                    11 
 12 An important note is that KMSAN is not intende     12 An important note is that KMSAN is not intended for production use, because it
 13 drastically increases kernel memory footprint      13 drastically increases kernel memory footprint and slows the whole system down.
 14                                                    14 
 15 Usage                                              15 Usage
 16 =====                                              16 =====
 17                                                    17 
 18 Building the kernel                                18 Building the kernel
 19 -------------------                                19 -------------------
 20                                                    20 
 21 In order to build a kernel with KMSAN you will     21 In order to build a kernel with KMSAN you will need a fresh Clang (14.0.6+).
 22 Please refer to `LLVM documentation`_ for the      22 Please refer to `LLVM documentation`_ for the instructions on how to build Clang.
 23                                                    23 
 24 Now configure and build the kernel with CONFIG     24 Now configure and build the kernel with CONFIG_KMSAN enabled.
 25                                                    25 
 26 Example report                                     26 Example report
 27 --------------                                     27 --------------
 28                                                    28 
 29 Here is an example of a KMSAN report::             29 Here is an example of a KMSAN report::
 30                                                    30 
 31   ============================================     31   =====================================================
 32   BUG: KMSAN: uninit-value in test_uninit_kmsa     32   BUG: KMSAN: uninit-value in test_uninit_kmsan_check_memory+0x1be/0x380 [kmsan_test]
 33    test_uninit_kmsan_check_memory+0x1be/0x380      33    test_uninit_kmsan_check_memory+0x1be/0x380 mm/kmsan/kmsan_test.c:273
 34    kunit_run_case_internal lib/kunit/test.c:33     34    kunit_run_case_internal lib/kunit/test.c:333
 35    kunit_try_run_case+0x206/0x420 lib/kunit/te     35    kunit_try_run_case+0x206/0x420 lib/kunit/test.c:374
 36    kunit_generic_run_threadfn_adapter+0x6d/0xc     36    kunit_generic_run_threadfn_adapter+0x6d/0xc0 lib/kunit/try-catch.c:28
 37    kthread+0x721/0x850 kernel/kthread.c:327        37    kthread+0x721/0x850 kernel/kthread.c:327
 38    ret_from_fork+0x1f/0x30 ??:?                    38    ret_from_fork+0x1f/0x30 ??:?
 39                                                    39 
 40   Uninit was stored to memory at:                  40   Uninit was stored to memory at:
 41    do_uninit_local_array+0xfa/0x110 mm/kmsan/k     41    do_uninit_local_array+0xfa/0x110 mm/kmsan/kmsan_test.c:260
 42    test_uninit_kmsan_check_memory+0x1a2/0x380      42    test_uninit_kmsan_check_memory+0x1a2/0x380 mm/kmsan/kmsan_test.c:271
 43    kunit_run_case_internal lib/kunit/test.c:33     43    kunit_run_case_internal lib/kunit/test.c:333
 44    kunit_try_run_case+0x206/0x420 lib/kunit/te     44    kunit_try_run_case+0x206/0x420 lib/kunit/test.c:374
 45    kunit_generic_run_threadfn_adapter+0x6d/0xc     45    kunit_generic_run_threadfn_adapter+0x6d/0xc0 lib/kunit/try-catch.c:28
 46    kthread+0x721/0x850 kernel/kthread.c:327        46    kthread+0x721/0x850 kernel/kthread.c:327
 47    ret_from_fork+0x1f/0x30 ??:?                    47    ret_from_fork+0x1f/0x30 ??:?
 48                                                    48 
 49   Local variable uninit created at:                49   Local variable uninit created at:
 50    do_uninit_local_array+0x4a/0x110 mm/kmsan/k     50    do_uninit_local_array+0x4a/0x110 mm/kmsan/kmsan_test.c:256
 51    test_uninit_kmsan_check_memory+0x1a2/0x380      51    test_uninit_kmsan_check_memory+0x1a2/0x380 mm/kmsan/kmsan_test.c:271
 52                                                    52 
 53   Bytes 4-7 of 8 are uninitialized                 53   Bytes 4-7 of 8 are uninitialized
 54   Memory access of size 8 starts at ffff888083     54   Memory access of size 8 starts at ffff888083fe3da0
 55                                                    55 
 56   CPU: 0 PID: 6731 Comm: kunit_try_catch Taint     56   CPU: 0 PID: 6731 Comm: kunit_try_catch Tainted: G    B       E     5.16.0-rc3+ #104
 57   Hardware name: QEMU Standard PC (i440FX + PI     57   Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS 1.14.0-2 04/01/2014
 58   ============================================     58   =====================================================
 59                                                    59 
 60 The report says that the local variable ``unin     60 The report says that the local variable ``uninit`` was created uninitialized in
 61 ``do_uninit_local_array()``. The third stack t     61 ``do_uninit_local_array()``. The third stack trace corresponds to the place
 62 where this variable was created.                   62 where this variable was created.
 63                                                    63 
 64 The first stack trace shows where the uninit v     64 The first stack trace shows where the uninit value was used (in
 65 ``test_uninit_kmsan_check_memory()``). The too     65 ``test_uninit_kmsan_check_memory()``). The tool shows the bytes which were left
 66 uninitialized in the local variable, as well a     66 uninitialized in the local variable, as well as the stack where the value was
 67 copied to another memory location before use.      67 copied to another memory location before use.
 68                                                    68 
 69 A use of uninitialized value ``v`` is reported     69 A use of uninitialized value ``v`` is reported by KMSAN in the following cases:
 70                                                    70 
 71  - in a condition, e.g. ``if (v) { ... }``;        71  - in a condition, e.g. ``if (v) { ... }``;
 72  - in an indexing or pointer dereferencing, e.     72  - in an indexing or pointer dereferencing, e.g. ``array[v]`` or ``*v``;
 73  - when it is copied to userspace or hardware,     73  - when it is copied to userspace or hardware, e.g. ``copy_to_user(..., &v, ...)``;
 74  - when it is passed as an argument to a funct     74  - when it is passed as an argument to a function, and
 75    ``CONFIG_KMSAN_CHECK_PARAM_RETVAL`` is enab     75    ``CONFIG_KMSAN_CHECK_PARAM_RETVAL`` is enabled (see below).
 76                                                    76 
 77 The mentioned cases (apart from copying data t     77 The mentioned cases (apart from copying data to userspace or hardware, which is
 78 a security issue) are considered undefined beh     78 a security issue) are considered undefined behavior from the C11 Standard point
 79 of view.                                           79 of view.
 80                                                    80 
 81 Disabling the instrumentation                      81 Disabling the instrumentation
 82 -----------------------------                      82 -----------------------------
 83                                                    83 
 84 A function can be marked with ``__no_kmsan_che     84 A function can be marked with ``__no_kmsan_checks``. Doing so makes KMSAN
 85 ignore uninitialized values in that function a     85 ignore uninitialized values in that function and mark its output as initialized.
 86 As a result, the user will not get KMSAN repor     86 As a result, the user will not get KMSAN reports related to that function.
 87                                                    87 
 88 Another function attribute supported by KMSAN      88 Another function attribute supported by KMSAN is ``__no_sanitize_memory``.
 89 Applying this attribute to a function will res     89 Applying this attribute to a function will result in KMSAN not instrumenting
 90 it, which can be helpful if we do not want the     90 it, which can be helpful if we do not want the compiler to interfere with some
 91 low-level code (e.g. that marked with ``noinst     91 low-level code (e.g. that marked with ``noinstr`` which implicitly adds
 92 ``__no_sanitize_memory``).                         92 ``__no_sanitize_memory``).
 93                                                    93 
 94 This however comes at a cost: stack allocation     94 This however comes at a cost: stack allocations from such functions will have
 95 incorrect shadow/origin values, likely leading     95 incorrect shadow/origin values, likely leading to false positives. Functions
 96 called from non-instrumented code may also rec     96 called from non-instrumented code may also receive incorrect metadata for their
 97 parameters.                                        97 parameters.
 98                                                    98 
 99 As a rule of thumb, avoid using ``__no_sanitiz     99 As a rule of thumb, avoid using ``__no_sanitize_memory`` explicitly.
100                                                   100 
101 It is also possible to disable KMSAN for a sin    101 It is also possible to disable KMSAN for a single file (e.g. main.o)::
102                                                   102 
103   KMSAN_SANITIZE_main.o := n                      103   KMSAN_SANITIZE_main.o := n
104                                                   104 
105 or for the whole directory::                      105 or for the whole directory::
106                                                   106 
107   KMSAN_SANITIZE := n                             107   KMSAN_SANITIZE := n
108                                                   108 
109 in the Makefile. Think of this as applying ``_    109 in the Makefile. Think of this as applying ``__no_sanitize_memory`` to every
110 function in the file or directory. Most users     110 function in the file or directory. Most users won't need KMSAN_SANITIZE, unless
111 their code gets broken by KMSAN (e.g. runs at     111 their code gets broken by KMSAN (e.g. runs at early boot time).
112                                                   112 
113 KMSAN checks can also be temporarily disabled  << 
114 ``kmsan_disable_current()`` and ``kmsan_enable << 
115 ``kmsan_enable_current()`` call must be preced << 
116 ``kmsan_disable_current()`` call; these call p << 
117 be careful with these calls, keeping the regio << 
118 ways to disable instrumentation, where possibl << 
119                                                << 
120 Support                                           113 Support
121 =======                                           114 =======
122                                                   115 
123 In order for KMSAN to work the kernel must be     116 In order for KMSAN to work the kernel must be built with Clang, which so far is
124 the only compiler that has KMSAN support. The     117 the only compiler that has KMSAN support. The kernel instrumentation pass is
125 based on the userspace `MemorySanitizer tool`_    118 based on the userspace `MemorySanitizer tool`_.
126                                                   119 
127 The runtime library only supports x86_64 at th    120 The runtime library only supports x86_64 at the moment.
128                                                   121 
129 How KMSAN works                                   122 How KMSAN works
130 ===============                                   123 ===============
131                                                   124 
132 KMSAN shadow memory                               125 KMSAN shadow memory
133 -------------------                               126 -------------------
134                                                   127 
135 KMSAN associates a metadata byte (also called     128 KMSAN associates a metadata byte (also called shadow byte) with every byte of
136 kernel memory. A bit in the shadow byte is set    129 kernel memory. A bit in the shadow byte is set iff the corresponding bit of the
137 kernel memory byte is uninitialized. Marking t    130 kernel memory byte is uninitialized. Marking the memory uninitialized (i.e.
138 setting its shadow bytes to ``0xff``) is calle    131 setting its shadow bytes to ``0xff``) is called poisoning, marking it
139 initialized (setting the shadow bytes to ``0x0    132 initialized (setting the shadow bytes to ``0x00``) is called unpoisoning.
140                                                   133 
141 When a new variable is allocated on the stack,    134 When a new variable is allocated on the stack, it is poisoned by default by
142 instrumentation code inserted by the compiler     135 instrumentation code inserted by the compiler (unless it is a stack variable
143 that is immediately initialized). Any new heap    136 that is immediately initialized). Any new heap allocation done without
144 ``__GFP_ZERO`` is also poisoned.                  137 ``__GFP_ZERO`` is also poisoned.
145                                                   138 
146 Compiler instrumentation also tracks the shado    139 Compiler instrumentation also tracks the shadow values as they are used along
147 the code. When needed, instrumentation code in    140 the code. When needed, instrumentation code invokes the runtime library in
148 ``mm/kmsan/`` to persist shadow values.           141 ``mm/kmsan/`` to persist shadow values.
149                                                   142 
150 The shadow value of a basic or compound type i    143 The shadow value of a basic or compound type is an array of bytes of the same
151 length. When a constant value is written into     144 length. When a constant value is written into memory, that memory is unpoisoned.
152 When a value is read from memory, its shadow m    145 When a value is read from memory, its shadow memory is also obtained and
153 propagated into all the operations which use t    146 propagated into all the operations which use that value. For every instruction
154 that takes one or more values the compiler gen    147 that takes one or more values the compiler generates code that calculates the
155 shadow of the result depending on those values    148 shadow of the result depending on those values and their shadows.
156                                                   149 
157 Example::                                         150 Example::
158                                                   151 
159   int a = 0xff;  // i.e. 0x000000ff               152   int a = 0xff;  // i.e. 0x000000ff
160   int b;                                          153   int b;
161   int c = a | b;                                  154   int c = a | b;
162                                                   155 
163 In this case the shadow of ``a`` is ``0``, sha    156 In this case the shadow of ``a`` is ``0``, shadow of ``b`` is ``0xffffffff``,
164 shadow of ``c`` is ``0xffffff00``. This means     157 shadow of ``c`` is ``0xffffff00``. This means that the upper three bytes of
165 ``c`` are uninitialized, while the lower byte     158 ``c`` are uninitialized, while the lower byte is initialized.
166                                                   159 
167 Origin tracking                                   160 Origin tracking
168 ---------------                                   161 ---------------
169                                                   162 
170 Every four bytes of kernel memory also have a     163 Every four bytes of kernel memory also have a so-called origin mapped to them.
171 This origin describes the point in program exe    164 This origin describes the point in program execution at which the uninitialized
172 value was created. Every origin is associated     165 value was created. Every origin is associated with either the full allocation
173 stack (for heap-allocated memory), or the func    166 stack (for heap-allocated memory), or the function containing the uninitialized
174 variable (for locals).                            167 variable (for locals).
175                                                   168 
176 When an uninitialized variable is allocated on    169 When an uninitialized variable is allocated on stack or heap, a new origin
177 value is created, and that variable's origin i    170 value is created, and that variable's origin is filled with that value. When a
178 value is read from memory, its origin is also     171 value is read from memory, its origin is also read and kept together with the
179 shadow. For every instruction that takes one o    172 shadow. For every instruction that takes one or more values, the origin of the
180 result is one of the origins corresponding to     173 result is one of the origins corresponding to any of the uninitialized inputs.
181 If a poisoned value is written into memory, it    174 If a poisoned value is written into memory, its origin is written to the
182 corresponding storage as well.                    175 corresponding storage as well.
183                                                   176 
184 Example 1::                                       177 Example 1::
185                                                   178 
186   int a = 42;                                     179   int a = 42;
187   int b;                                          180   int b;
188   int c = a + b;                                  181   int c = a + b;
189                                                   182 
190 In this case the origin of ``b`` is generated     183 In this case the origin of ``b`` is generated upon function entry, and is
191 stored to the origin of ``c`` right before the    184 stored to the origin of ``c`` right before the addition result is written into
192 memory.                                           185 memory.
193                                                   186 
194 Several variables may share the same origin ad    187 Several variables may share the same origin address, if they are stored in the
195 same four-byte chunk. In this case every write    188 same four-byte chunk. In this case every write to either variable updates the
196 origin for all of them. We have to sacrifice p    189 origin for all of them. We have to sacrifice precision in this case, because
197 storing origins for individual bits (and even     190 storing origins for individual bits (and even bytes) would be too costly.
198                                                   191 
199 Example 2::                                       192 Example 2::
200                                                   193 
201   int combine(short a, short b) {                 194   int combine(short a, short b) {
202     union ret_t {                                 195     union ret_t {
203       int i;                                      196       int i;
204       short s[2];                                 197       short s[2];
205     } ret;                                        198     } ret;
206     ret.s[0] = a;                                 199     ret.s[0] = a;
207     ret.s[1] = b;                                 200     ret.s[1] = b;
208     return ret.i;                                 201     return ret.i;
209   }                                               202   }
210                                                   203 
211 If ``a`` is initialized and ``b`` is not, the     204 If ``a`` is initialized and ``b`` is not, the shadow of the result would be
212 0xffff0000, and the origin of the result would    205 0xffff0000, and the origin of the result would be the origin of ``b``.
213 ``ret.s[0]`` would have the same origin, but i    206 ``ret.s[0]`` would have the same origin, but it will never be used, because
214 that variable is initialized.                     207 that variable is initialized.
215                                                   208 
216 If both function arguments are uninitialized,     209 If both function arguments are uninitialized, only the origin of the second
217 argument is preserved.                            210 argument is preserved.
218                                                   211 
219 Origin chaining                                   212 Origin chaining
220 ~~~~~~~~~~~~~~~                                   213 ~~~~~~~~~~~~~~~
221                                                   214 
222 To ease debugging, KMSAN creates a new origin     215 To ease debugging, KMSAN creates a new origin for every store of an
223 uninitialized value to memory. The new origin     216 uninitialized value to memory. The new origin references both its creation stack
224 and the previous origin the value had. This ma    217 and the previous origin the value had. This may cause increased memory
225 consumption, so we limit the length of origin     218 consumption, so we limit the length of origin chains in the runtime.
226                                                   219 
227 Clang instrumentation API                         220 Clang instrumentation API
228 -------------------------                         221 -------------------------
229                                                   222 
230 Clang instrumentation pass inserts calls to fu    223 Clang instrumentation pass inserts calls to functions defined in
231 ``mm/kmsan/nstrumentation.c`` into the kernel     224 ``mm/kmsan/nstrumentation.c`` into the kernel code.
232                                                   225 
233 Shadow manipulation                               226 Shadow manipulation
234 ~~~~~~~~~~~~~~~~~~~                               227 ~~~~~~~~~~~~~~~~~~~
235                                                   228 
236 For every memory access the compiler emits a c    229 For every memory access the compiler emits a call to a function that returns a
237 pair of pointers to the shadow and origin addr    230 pair of pointers to the shadow and origin addresses of the given memory::
238                                                   231 
239   typedef struct {                                232   typedef struct {
240     void *shadow, *origin;                        233     void *shadow, *origin;
241   } shadow_origin_ptr_t                           234   } shadow_origin_ptr_t
242                                                   235 
243   shadow_origin_ptr_t __msan_metadata_ptr_for_    236   shadow_origin_ptr_t __msan_metadata_ptr_for_load_{1,2,4,8}(void *addr)
244   shadow_origin_ptr_t __msan_metadata_ptr_for_    237   shadow_origin_ptr_t __msan_metadata_ptr_for_store_{1,2,4,8}(void *addr)
245   shadow_origin_ptr_t __msan_metadata_ptr_for_    238   shadow_origin_ptr_t __msan_metadata_ptr_for_load_n(void *addr, uintptr_t size)
246   shadow_origin_ptr_t __msan_metadata_ptr_for_    239   shadow_origin_ptr_t __msan_metadata_ptr_for_store_n(void *addr, uintptr_t size)
247                                                   240 
248 The function name depends on the memory access    241 The function name depends on the memory access size.
249                                                   242 
250 The compiler makes sure that for every loaded     243 The compiler makes sure that for every loaded value its shadow and origin
251 values are read from memory. When a value is s    244 values are read from memory. When a value is stored to memory, its shadow and
252 origin are also stored using the metadata poin    245 origin are also stored using the metadata pointers.
253                                                   246 
254 Handling locals                                   247 Handling locals
255 ~~~~~~~~~~~~~~~                                   248 ~~~~~~~~~~~~~~~
256                                                   249 
257 A special function is used to create a new ori    250 A special function is used to create a new origin value for a local variable and
258 set the origin of that variable to that value:    251 set the origin of that variable to that value::
259                                                   252 
260   void __msan_poison_alloca(void *addr, uintpt    253   void __msan_poison_alloca(void *addr, uintptr_t size, char *descr)
261                                                   254 
262 Access to per-task data                           255 Access to per-task data
263 ~~~~~~~~~~~~~~~~~~~~~~~                           256 ~~~~~~~~~~~~~~~~~~~~~~~
264                                                   257 
265 At the beginning of every instrumented functio    258 At the beginning of every instrumented function KMSAN inserts a call to
266 ``__msan_get_context_state()``::                  259 ``__msan_get_context_state()``::
267                                                   260 
268   kmsan_context_state *__msan_get_context_stat    261   kmsan_context_state *__msan_get_context_state(void)
269                                                   262 
270 ``kmsan_context_state`` is declared in ``inclu    263 ``kmsan_context_state`` is declared in ``include/linux/kmsan.h``::
271                                                   264 
272   struct kmsan_context_state {                    265   struct kmsan_context_state {
273     char param_tls[KMSAN_PARAM_SIZE];             266     char param_tls[KMSAN_PARAM_SIZE];
274     char retval_tls[KMSAN_RETVAL_SIZE];           267     char retval_tls[KMSAN_RETVAL_SIZE];
275     char va_arg_tls[KMSAN_PARAM_SIZE];            268     char va_arg_tls[KMSAN_PARAM_SIZE];
276     char va_arg_origin_tls[KMSAN_PARAM_SIZE];     269     char va_arg_origin_tls[KMSAN_PARAM_SIZE];
277     u64 va_arg_overflow_size_tls;                 270     u64 va_arg_overflow_size_tls;
278     char param_origin_tls[KMSAN_PARAM_SIZE];      271     char param_origin_tls[KMSAN_PARAM_SIZE];
279     depot_stack_handle_t retval_origin_tls;       272     depot_stack_handle_t retval_origin_tls;
280   };                                              273   };
281                                                   274 
282 This structure is used by KMSAN to pass parame    275 This structure is used by KMSAN to pass parameter shadows and origins between
283 instrumented functions (unless the parameters     276 instrumented functions (unless the parameters are checked immediately by
284 ``CONFIG_KMSAN_CHECK_PARAM_RETVAL``).             277 ``CONFIG_KMSAN_CHECK_PARAM_RETVAL``).
285                                                   278 
286 Passing uninitialized values to functions         279 Passing uninitialized values to functions
287 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~         280 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
288                                                   281 
289 Clang's MemorySanitizer instrumentation has an    282 Clang's MemorySanitizer instrumentation has an option,
290 ``-fsanitize-memory-param-retval``, which make    283 ``-fsanitize-memory-param-retval``, which makes the compiler check function
291 parameters passed by value, as well as functio    284 parameters passed by value, as well as function return values.
292                                                   285 
293 The option is controlled by ``CONFIG_KMSAN_CHE    286 The option is controlled by ``CONFIG_KMSAN_CHECK_PARAM_RETVAL``, which is
294 enabled by default to let KMSAN report uniniti    287 enabled by default to let KMSAN report uninitialized values earlier.
295 Please refer to the `LKML discussion`_ for mor    288 Please refer to the `LKML discussion`_ for more details.
296                                                   289 
297 Because of the way the checks are implemented     290 Because of the way the checks are implemented in LLVM (they are only applied to
298 parameters marked as ``noundef``), not all par    291 parameters marked as ``noundef``), not all parameters are guaranteed to be
299 checked, so we cannot give up the metadata sto    292 checked, so we cannot give up the metadata storage in ``kmsan_context_state``.
300                                                   293 
301 String functions                                  294 String functions
302 ~~~~~~~~~~~~~~~~                                  295 ~~~~~~~~~~~~~~~~
303                                                   296 
304 The compiler replaces calls to ``memcpy()``/``    297 The compiler replaces calls to ``memcpy()``/``memmove()``/``memset()`` with the
305 following functions. These functions are also     298 following functions. These functions are also called when data structures are
306 initialized or copied, making sure shadow and     299 initialized or copied, making sure shadow and origin values are copied alongside
307 with the data::                                   300 with the data::
308                                                   301 
309   void *__msan_memcpy(void *dst, void *src, ui    302   void *__msan_memcpy(void *dst, void *src, uintptr_t n)
310   void *__msan_memmove(void *dst, void *src, u    303   void *__msan_memmove(void *dst, void *src, uintptr_t n)
311   void *__msan_memset(void *dst, int c, uintpt    304   void *__msan_memset(void *dst, int c, uintptr_t n)
312                                                   305 
313 Error reporting                                   306 Error reporting
314 ~~~~~~~~~~~~~~~                                   307 ~~~~~~~~~~~~~~~
315                                                   308 
316 For each use of a value the compiler emits a s    309 For each use of a value the compiler emits a shadow check that calls
317 ``__msan_warning()`` in the case that value is    310 ``__msan_warning()`` in the case that value is poisoned::
318                                                   311 
319   void __msan_warning(u32 origin)                 312   void __msan_warning(u32 origin)
320                                                   313 
321 ``__msan_warning()`` causes KMSAN runtime to p    314 ``__msan_warning()`` causes KMSAN runtime to print an error report.
322                                                   315 
323 Inline assembly instrumentation                   316 Inline assembly instrumentation
324 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~                   317 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
325                                                   318 
326 KMSAN instruments every inline assembly output    319 KMSAN instruments every inline assembly output with a call to::
327                                                   320 
328   void __msan_instrument_asm_store(void *addr,    321   void __msan_instrument_asm_store(void *addr, uintptr_t size)
329                                                   322 
330 , which unpoisons the memory region.              323 , which unpoisons the memory region.
331                                                   324 
332 This approach may mask certain errors, but it     325 This approach may mask certain errors, but it also helps to avoid a lot of
333 false positives in bitwise operations, atomics    326 false positives in bitwise operations, atomics etc.
334                                                   327 
335 Sometimes the pointers passed into inline asse    328 Sometimes the pointers passed into inline assembly do not point to valid memory.
336 In such cases they are ignored at runtime.        329 In such cases they are ignored at runtime.
337                                                   330 
338                                                   331 
339 Runtime library                                   332 Runtime library
340 ---------------                                   333 ---------------
341                                                   334 
342 The code is located in ``mm/kmsan/``.             335 The code is located in ``mm/kmsan/``.
343                                                   336 
344 Per-task KMSAN state                              337 Per-task KMSAN state
345 ~~~~~~~~~~~~~~~~~~~~                              338 ~~~~~~~~~~~~~~~~~~~~
346                                                   339 
347 Every task_struct has an associated KMSAN task    340 Every task_struct has an associated KMSAN task state that holds the KMSAN
348 context (see above) and a per-task counter dis !! 341 context (see above) and a per-task flag disallowing KMSAN reports::
349                                                   342 
350   struct kmsan_context {                          343   struct kmsan_context {
351     ...                                           344     ...
352     unsigned int depth;                        !! 345     bool allow_reporting;
353     struct kmsan_context_state cstate;            346     struct kmsan_context_state cstate;
354     ...                                           347     ...
355   }                                               348   }
356                                                   349 
357   struct task_struct {                            350   struct task_struct {
358     ...                                           351     ...
359     struct kmsan_context kmsan;                   352     struct kmsan_context kmsan;
360     ...                                           353     ...
361   }                                               354   }
362                                                   355 
363 KMSAN contexts                                    356 KMSAN contexts
364 ~~~~~~~~~~~~~~                                    357 ~~~~~~~~~~~~~~
365                                                   358 
366 When running in a kernel task context, KMSAN u    359 When running in a kernel task context, KMSAN uses ``current->kmsan.cstate`` to
367 hold the metadata for function parameters and     360 hold the metadata for function parameters and return values.
368                                                   361 
369 But in the case the kernel is running in the i    362 But in the case the kernel is running in the interrupt, softirq or NMI context,
370 where ``current`` is unavailable, KMSAN switch    363 where ``current`` is unavailable, KMSAN switches to per-cpu interrupt state::
371                                                   364 
372   DEFINE_PER_CPU(struct kmsan_ctx, kmsan_percp    365   DEFINE_PER_CPU(struct kmsan_ctx, kmsan_percpu_ctx);
373                                                   366 
374 Metadata allocation                               367 Metadata allocation
375 ~~~~~~~~~~~~~~~~~~~                               368 ~~~~~~~~~~~~~~~~~~~
376                                                   369 
377 There are several places in the kernel for whi    370 There are several places in the kernel for which the metadata is stored.
378                                                   371 
379 1. Each ``struct page`` instance contains two     372 1. Each ``struct page`` instance contains two pointers to its shadow and
380 origin pages::                                    373 origin pages::
381                                                   374 
382   struct page {                                   375   struct page {
383     ...                                           376     ...
384     struct page *shadow, *origin;                 377     struct page *shadow, *origin;
385     ...                                           378     ...
386   };                                              379   };
387                                                   380 
388 At boot-time, the kernel allocates shadow and     381 At boot-time, the kernel allocates shadow and origin pages for every available
389 kernel page. This is done quite late, when the    382 kernel page. This is done quite late, when the kernel address space is already
390 fragmented, so normal data pages may arbitrari    383 fragmented, so normal data pages may arbitrarily interleave with the metadata
391 pages.                                            384 pages.
392                                                   385 
393 This means that in general for two contiguous     386 This means that in general for two contiguous memory pages their shadow/origin
394 pages may not be contiguous. Consequently, if     387 pages may not be contiguous. Consequently, if a memory access crosses the
395 boundary of a memory block, accesses to shadow    388 boundary of a memory block, accesses to shadow/origin memory may potentially
396 corrupt other pages or read incorrect values f    389 corrupt other pages or read incorrect values from them.
397                                                   390 
398 In practice, contiguous memory pages returned     391 In practice, contiguous memory pages returned by the same ``alloc_pages()``
399 call will have contiguous metadata, whereas if    392 call will have contiguous metadata, whereas if these pages belong to two
400 different allocations their metadata pages can    393 different allocations their metadata pages can be fragmented.
401                                                   394 
402 For the kernel data (``.data``, ``.bss`` etc.)    395 For the kernel data (``.data``, ``.bss`` etc.) and percpu memory regions
403 there also are no guarantees on metadata conti    396 there also are no guarantees on metadata contiguity.
404                                                   397 
405 In the case ``__msan_metadata_ptr_for_XXX_YYY(    398 In the case ``__msan_metadata_ptr_for_XXX_YYY()`` hits the border between two
406 pages with non-contiguous metadata, it returns    399 pages with non-contiguous metadata, it returns pointers to fake shadow/origin regions::
407                                                   400 
408   char dummy_load_page[PAGE_SIZE] __attribute_    401   char dummy_load_page[PAGE_SIZE] __attribute__((aligned(PAGE_SIZE)));
409   char dummy_store_page[PAGE_SIZE] __attribute    402   char dummy_store_page[PAGE_SIZE] __attribute__((aligned(PAGE_SIZE)));
410                                                   403 
411 ``dummy_load_page`` is zero-initialized, so re    404 ``dummy_load_page`` is zero-initialized, so reads from it always yield zeroes.
412 All stores to ``dummy_store_page`` are ignored    405 All stores to ``dummy_store_page`` are ignored.
413                                                   406 
414 2. For vmalloc memory and modules, there is a     407 2. For vmalloc memory and modules, there is a direct mapping between the memory
415 range, its shadow and origin. KMSAN reduces th    408 range, its shadow and origin. KMSAN reduces the vmalloc area by 3/4, making only
416 the first quarter available to ``vmalloc()``.     409 the first quarter available to ``vmalloc()``. The second quarter of the vmalloc
417 area contains shadow memory for the first quar    410 area contains shadow memory for the first quarter, the third one holds the
418 origins. A small part of the fourth quarter co    411 origins. A small part of the fourth quarter contains shadow and origins for the
419 kernel modules. Please refer to ``arch/x86/inc    412 kernel modules. Please refer to ``arch/x86/include/asm/pgtable_64_types.h`` for
420 more details.                                     413 more details.
421                                                   414 
422 When an array of pages is mapped into a contig    415 When an array of pages is mapped into a contiguous virtual memory space, their
423 shadow and origin pages are similarly mapped i    416 shadow and origin pages are similarly mapped into contiguous regions.
424                                                   417 
425 References                                        418 References
426 ==========                                        419 ==========
427                                                   420 
428 E. Stepanov, K. Serebryany. `MemorySanitizer:     421 E. Stepanov, K. Serebryany. `MemorySanitizer: fast detector of uninitialized
429 memory use in C++                                 422 memory use in C++
430 <https://static.googleusercontent.com/media/re    423 <https://static.googleusercontent.com/media/research.google.com/en//pubs/archive/43308.pdf>`_.
431 In Proceedings of CGO 2015.                       424 In Proceedings of CGO 2015.
432                                                   425 
433 .. _MemorySanitizer tool: https://clang.llvm.o    426 .. _MemorySanitizer tool: https://clang.llvm.org/docs/MemorySanitizer.html
434 .. _LLVM documentation: https://llvm.org/docs/    427 .. _LLVM documentation: https://llvm.org/docs/GettingStarted.html
435 .. _LKML discussion: https://lore.kernel.org/a    428 .. _LKML discussion: https://lore.kernel.org/all/20220614144853.3693273-1-glider@google.com/
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php