Commit 0295fd5d authored by Andrey Konovalov's avatar Andrey Konovalov Committed by Linus Torvalds

kasan: various fixes in documentation

[akpm@linux-foundation.org: coding-style fixes]
Signed-off-by: default avatarAndrey Konovalov <andreyknvl@google.com>
Cc: Andrey Ryabinin <ryabinin.a.a@gmail.com>
Cc: Dmitry Vyukov <dvyukov@google.com>
Cc: Alexander Potapenko <glider@google.com>
Cc: Konstantin Serebryany <kcc@google.com>
Signed-off-by: default avatarAndrew Morton <akpm@linux-foundation.org>
Signed-off-by: default avatarLinus Torvalds <torvalds@linux-foundation.org>
parent 25add7ec
Kernel address sanitizer KernelAddressSanitizer (KASAN)
================ ==============================
0. Overview 0. Overview
=========== ===========
Kernel Address sanitizer (KASan) is a dynamic memory error detector. It provides KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides
a fast and comprehensive solution for finding use-after-free and out-of-bounds a fast and comprehensive solution for finding use-after-free and out-of-bounds
bugs. bugs.
KASan uses compile-time instrumentation for checking every memory access, KASAN uses compile-time instrumentation for checking every memory access,
therefore you will need a gcc version of 4.9.2 or later. KASan could detect out therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is
of bounds accesses to stack or global variables, but only if gcc 5.0 or later was required for detection of out-of-bounds accesses to stack or global variables.
used to built the kernel.
Currently KASan is supported only for x86_64 architecture and requires that the Currently KASAN is supported only for x86_64 architecture and requires the
kernel be built with the SLUB allocator. kernel to be built with the SLUB allocator.
1. Usage 1. Usage
========= ========
To enable KASAN configure kernel with: To enable KASAN configure kernel with:
CONFIG_KASAN = y CONFIG_KASAN = y
and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline/inline and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and
is compiler instrumentation types. The former produces smaller binary the inline are compiler instrumentation types. The former produces smaller binary
latter is 1.1 - 2 times faster. Inline instrumentation requires a gcc version the latter is 1.1 - 2 times faster. Inline instrumentation requires a GCC
of 5.0 or later. version 5.0 or later.
Currently KASAN works only with the SLUB memory allocator. Currently KASAN works only with the SLUB memory allocator.
For better bug detection and nicer report, enable CONFIG_STACKTRACE and put For better bug detection and nicer report, enable CONFIG_STACKTRACE and put
...@@ -42,7 +41,7 @@ similar to the following to the respective kernel Makefile: ...@@ -42,7 +41,7 @@ similar to the following to the respective kernel Makefile:
KASAN_SANITIZE := n KASAN_SANITIZE := n
1.1 Error reports 1.1 Error reports
========== =================
A typical out of bounds access report looks like this: A typical out of bounds access report looks like this:
...@@ -119,14 +118,16 @@ Memory state around the buggy address: ...@@ -119,14 +118,16 @@ Memory state around the buggy address:
ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb
================================================================== ==================================================================
First sections describe slub object where bad access happened. The header of the report discribe what kind of bug happened and what kind of
See 'SLUB Debug output' section in Documentation/vm/slub.txt for details. access caused it. It's followed by the description of the accessed slub object
(see 'SLUB Debug output' section in Documentation/vm/slub.txt for details) and
the description of the accessed memory page.
In the last section the report shows memory state around the accessed address. In the last section the report shows memory state around the accessed address.
Reading this part requires some more understanding of how KASAN works. Reading this part requires some understanding of how KASAN works.
Each 8 bytes of memory are encoded in one shadow byte as accessible, The state of each 8 aligned bytes of memory is encoded in one shadow byte.
partially accessible, freed or they can be part of a redzone. Those 8 bytes can be accessible, partially accessible, freed or be a redzone.
We use the following encoding for each shadow byte: 0 means that all 8 bytes We use the following encoding for each shadow byte: 0 means that all 8 bytes
of the corresponding memory region are accessible; number N (1 <= N <= 7) means of the corresponding memory region are accessible; number N (1 <= N <= 7) means
that the first N bytes are accessible, and other (8 - N) bytes are not; that the first N bytes are accessible, and other (8 - N) bytes are not;
...@@ -139,7 +140,7 @@ the accessed address is partially accessible. ...@@ -139,7 +140,7 @@ the accessed address is partially accessible.
2. Implementation details 2. Implementation details
======================== =========================
From a high level, our approach to memory error detection is similar to that From a high level, our approach to memory error detection is similar to that
of kmemcheck: use shadow memory to record whether each byte of memory is safe of kmemcheck: use shadow memory to record whether each byte of memory is safe
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment