can: c_can_pci: fix null-pointer-deref in c_can_start() - set device pointer
[firefly-linux-kernel-4.4.55.git] / Documentation / kasan.txt
1 KernelAddressSanitizer (KASAN)
2 ==============================
3
4 0. Overview
5 ===========
6
7 KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides
8 a fast and comprehensive solution for finding use-after-free and out-of-bounds
9 bugs.
10
11 KASAN uses compile-time instrumentation for checking every memory access,
12 therefore you will need a GCC version 4.9.2 or later. GCC 5.0 or later is
13 required for detection of out-of-bounds accesses to stack or global variables.
14
15 Currently KASAN is supported only for x86_64 architecture and requires the
16 kernel to be built with the SLUB allocator.
17
18 1. Usage
19 ========
20
21 To enable KASAN configure kernel with:
22
23           CONFIG_KASAN = y
24
25 and choose between CONFIG_KASAN_OUTLINE and CONFIG_KASAN_INLINE. Outline and
26 inline are compiler instrumentation types. The former produces smaller binary
27 the latter is 1.1 - 2 times faster. Inline instrumentation requires a GCC
28 version 5.0 or later.
29
30 Currently KASAN works only with the SLUB memory allocator.
31 For better bug detection and nicer reporting, enable CONFIG_STACKTRACE.
32
33 To disable instrumentation for specific files or directories, add a line
34 similar to the following to the respective kernel Makefile:
35
36         For a single file (e.g. main.o):
37                 KASAN_SANITIZE_main.o := n
38
39         For all files in one directory:
40                 KASAN_SANITIZE := n
41
42 1.1 Error reports
43 =================
44
45 A typical out of bounds access report looks like this:
46
47 ==================================================================
48 BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3
49 Write of size 1 by task modprobe/1689
50 =============================================================================
51 BUG kmalloc-128 (Not tainted): kasan error
52 -----------------------------------------------------------------------------
53
54 Disabling lock debugging due to kernel taint
55 INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689
56  __slab_alloc+0x4b4/0x4f0
57  kmem_cache_alloc_trace+0x10b/0x190
58  kmalloc_oob_right+0x3d/0x75 [test_kasan]
59  init_module+0x9/0x47 [test_kasan]
60  do_one_initcall+0x99/0x200
61  load_module+0x2cb3/0x3b20
62  SyS_finit_module+0x76/0x80
63  system_call_fastpath+0x12/0x17
64 INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080
65 INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720
66
67 Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a  ........ZZZZZZZZ
68 Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
69 Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
70 Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
71 Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
72 Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
73 Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
74 Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
75 Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5  kkkkkkkkkkkkkkk.
76 Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc                          ........
77 Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a                          ZZZZZZZZ
78 CPU: 0 PID: 1689 Comm: modprobe Tainted: G    B          3.18.0-rc1-mm1+ #98
79 Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014
80  ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78
81  ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8
82  ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558
83 Call Trace:
84  [<ffffffff81cc68ae>] dump_stack+0x46/0x58
85  [<ffffffff811fd848>] print_trailer+0xf8/0x160
86  [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan]
87  [<ffffffff811ff0f5>] object_err+0x35/0x40
88  [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan]
89  [<ffffffff8120b9fa>] kasan_report_error+0x38a/0x3f0
90  [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40
91  [<ffffffff8120b344>] ? kasan_unpoison_shadow+0x14/0x40
92  [<ffffffff8120a79f>] ? kasan_poison_shadow+0x2f/0x40
93  [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan]
94  [<ffffffff8120a995>] __asan_store1+0x75/0xb0
95  [<ffffffffa0002601>] ? kmem_cache_oob+0x1d/0xc3 [test_kasan]
96  [<ffffffffa0002065>] ? kmalloc_oob_right+0x65/0x75 [test_kasan]
97  [<ffffffffa0002065>] kmalloc_oob_right+0x65/0x75 [test_kasan]
98  [<ffffffffa00026b0>] init_module+0x9/0x47 [test_kasan]
99  [<ffffffff810002d9>] do_one_initcall+0x99/0x200
100  [<ffffffff811e4e5c>] ? __vunmap+0xec/0x160
101  [<ffffffff81114f63>] load_module+0x2cb3/0x3b20
102  [<ffffffff8110fd70>] ? m_show+0x240/0x240
103  [<ffffffff81115f06>] SyS_finit_module+0x76/0x80
104  [<ffffffff81cd3129>] system_call_fastpath+0x12/0x17
105 Memory state around the buggy address:
106  ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
107  ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc
108  ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
109  ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
110  ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00
111 >ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc
112                                                  ^
113  ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
114  ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
115  ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb
116  ffff8800693bc780: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb
117  ffff8800693bc800: fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb fb
118 ==================================================================
119
120 The header of the report discribe what kind of bug happened and what kind of
121 access caused it. It's followed by the description of the accessed slub object
122 (see 'SLUB Debug output' section in Documentation/vm/slub.txt for details) and
123 the description of the accessed memory page.
124
125 In the last section the report shows memory state around the accessed address.
126 Reading this part requires some understanding of how KASAN works.
127
128 The state of each 8 aligned bytes of memory is encoded in one shadow byte.
129 Those 8 bytes can be accessible, partially accessible, freed or be a redzone.
130 We use the following encoding for each shadow byte: 0 means that all 8 bytes
131 of the corresponding memory region are accessible; number N (1 <= N <= 7) means
132 that the first N bytes are accessible, and other (8 - N) bytes are not;
133 any negative value indicates that the entire 8-byte word is inaccessible.
134 We use different negative values to distinguish between different kinds of
135 inaccessible memory like redzones or freed memory (see mm/kasan/kasan.h).
136
137 In the report above the arrows point to the shadow byte 03, which means that
138 the accessed address is partially accessible.
139
140
141 2. Implementation details
142 =========================
143
144 From a high level, our approach to memory error detection is similar to that
145 of kmemcheck: use shadow memory to record whether each byte of memory is safe
146 to access, and use compile-time instrumentation to check shadow memory on each
147 memory access.
148
149 AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory
150 (e.g. 16TB to cover 128TB on x86_64) and uses direct mapping with a scale and
151 offset to translate a memory address to its corresponding shadow address.
152
153 Here is the function which translates an address to its corresponding shadow
154 address:
155
156 static inline void *kasan_mem_to_shadow(const void *addr)
157 {
158         return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT)
159                 + KASAN_SHADOW_OFFSET;
160 }
161
162 where KASAN_SHADOW_SCALE_SHIFT = 3.
163
164 Compile-time instrumentation used for checking memory accesses. Compiler inserts
165 function calls (__asan_load*(addr), __asan_store*(addr)) before each memory
166 access of size 1, 2, 4, 8 or 16. These functions check whether memory access is
167 valid or not by checking corresponding shadow memory.
168
169 GCC 5.0 has possibility to perform inline instrumentation. Instead of making
170 function calls GCC directly inserts the code to check the shadow memory.
171 This option significantly enlarges kernel but it gives x1.1-x2 performance
172 boost over outline instrumented kernel.