docs: sphinxify kasan.txt and move to dev-tools

No textual changes beyond formatting.
Acked-by: Andrey Ryabinin <aryabinin@virtuozzo.com>
Acked-by: Alexander Potapenko <glider@google.com>
Cc: Dmitry Vyukov <dvyukov@google.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/kasan.txt → Documentation/dev-tools/kasan.rst

-KernelAddressSanitizer (KASAN)
-==============================
+The Kernel Address Sanitizer (KASAN)
+====================================
 
-0. Overview
-===========
+Overview
+--------
 
 KernelAddressSANitizer (KASAN) is a dynamic memory error detector. It provides
 a fast and comprehensive solution for finding use-after-free and out-of-bounds
@@ -14,10 +14,10 @@ required for detection of out-of-bounds accesses to stack or global variables.
 
 Currently KASAN is supported only for x86_64 architecture.
 
-1. Usage
-========
+Usage
+-----
 
-To enable KASAN configure kernel with:
+To enable KASAN configure kernel with::
 
 	  CONFIG_KASAN = y
 
@@ -32,26 +32,28 @@ For better bug detection and nicer reporting, enable CONFIG_STACKTRACE.
 To disable instrumentation for specific files or directories, add a line
 similar to the following to the respective kernel Makefile:
 
-        For a single file (e.g. main.o):
+- For a single file (e.g. main.o)::
+
     KASAN_SANITIZE_main.o := n
 
-        For all files in one directory:
+- For all files in one directory::
+
     KASAN_SANITIZE := n
 
-1.1 Error reports
-=================
+Error reports
+~~~~~~~~~~~~~
 
-A typical out of bounds access report looks like this:
+A typical out of bounds access report looks like this::
 
-==================================================================
-BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3
-Write of size 1 by task modprobe/1689
-=============================================================================
-BUG kmalloc-128 (Not tainted): kasan error
------------------------------------------------------------------------------
+    ==================================================================
+    BUG: AddressSanitizer: out of bounds access in kmalloc_oob_right+0x65/0x75 [test_kasan] at addr ffff8800693bc5d3
+    Write of size 1 by task modprobe/1689
+    =============================================================================
+    BUG kmalloc-128 (Not tainted): kasan error
+    -----------------------------------------------------------------------------
 
-Disabling lock debugging due to kernel taint
-INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689
+    Disabling lock debugging due to kernel taint
+    INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689
      __slab_alloc+0x4b4/0x4f0
      kmem_cache_alloc_trace+0x10b/0x190
      kmalloc_oob_right+0x3d/0x75 [test_kasan]
@@ -60,26 +62,26 @@ INFO: Allocated in kmalloc_oob_right+0x3d/0x75 [test_kasan] age=0 cpu=0 pid=1689
      load_module+0x2cb3/0x3b20
      SyS_finit_module+0x76/0x80
      system_call_fastpath+0x12/0x17
-INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080
-INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720
-
-Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a  ........ZZZZZZZZ
-Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
-Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
-Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
-Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
-Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
-Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
-Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
-Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5  kkkkkkkkkkkkkkk.
-Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc                          ........
-Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a                          ZZZZZZZZ
-CPU: 0 PID: 1689 Comm: modprobe Tainted: G    B          3.18.0-rc1-mm1+ #98
-Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014
+    INFO: Slab 0xffffea0001a4ef00 objects=17 used=7 fp=0xffff8800693bd728 flags=0x100000000004080
+    INFO: Object 0xffff8800693bc558 @offset=1368 fp=0xffff8800693bc720
+
+    Bytes b4 ffff8800693bc548: 00 00 00 00 00 00 00 00 5a 5a 5a 5a 5a 5a 5a 5a  ........ZZZZZZZZ
+    Object ffff8800693bc558: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
+    Object ffff8800693bc568: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
+    Object ffff8800693bc578: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
+    Object ffff8800693bc588: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
+    Object ffff8800693bc598: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
+    Object ffff8800693bc5a8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
+    Object ffff8800693bc5b8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b  kkkkkkkkkkkkkkkk
+    Object ffff8800693bc5c8: 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b 6b a5  kkkkkkkkkkkkkkk.
+    Redzone ffff8800693bc5d8: cc cc cc cc cc cc cc cc                          ........
+    Padding ffff8800693bc718: 5a 5a 5a 5a 5a 5a 5a 5a                          ZZZZZZZZ
+    CPU: 0 PID: 1689 Comm: modprobe Tainted: G    B          3.18.0-rc1-mm1+ #98
+    Hardware name: QEMU Standard PC (i440FX + PIIX, 1996), BIOS rel-1.7.5-0-ge51488c-20140602_164612-nilsson.home.kraxel.org 04/01/2014
      ffff8800693bc000 0000000000000000 ffff8800693bc558 ffff88006923bb78
      ffffffff81cc68ae 00000000000000f3 ffff88006d407600 ffff88006923bba8
      ffffffff811fd848 ffff88006d407600 ffffea0001a4ef00 ffff8800693bc558
-Call Trace:
+    Call Trace:
      [<ffffffff81cc68ae>] dump_stack+0x46/0x58
      [<ffffffff811fd848>] print_trailer+0xf8/0x160
      [<ffffffffa00026a7>] ? kmem_cache_oob+0xc3/0xc3 [test_kasan]
@@ -101,20 +103,20 @@ Call Trace:
      [<ffffffff8110fd70>] ? m_show+0x240/0x240
      [<ffffffff81115f06>] SyS_finit_module+0x76/0x80
      [<ffffffff81cd3129>] system_call_fastpath+0x12/0x17
-Memory state around the buggy address:
+    Memory state around the buggy address:
      ffff8800693bc300: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
      ffff8800693bc380: fc fc 00 00 00 00 00 00 00 00 00 00 00 00 00 fc
      ffff8800693bc400: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
      ffff8800693bc480: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
      ffff8800693bc500: fc fc fc fc fc fc fc fc fc fc fc 00 00 00 00 00
->ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc
+    >ffff8800693bc580: 00 00 00 00 00 00 00 00 00 00 03 fc fc fc fc fc
                                                  ^
      ffff8800693bc600: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
      ffff8800693bc680: fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc fc
      ffff8800693bc700: fc fc fc fc fb fb fb fb fb fb fb fb fb fb fb fb
      ffff8800693bc780: 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
-==================================================================
+    ==================================================================
 
 The header of the report discribe what kind of bug happened and what kind of
 access caused it. It's followed by the description of the accessed slub object
@@ -137,8 +139,8 @@ In the report above the arrows point to the shadow byte 03, which means that
 the accessed address is partially accessible.
 
 
-2. Implementation details
-=========================
+Implementation details
+----------------------
 
 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
@@ -150,15 +152,15 @@ AddressSanitizer dedicates 1/8 of kernel memory to its shadow memory
 offset to translate a memory address to its corresponding shadow address.
 
 Here is the function which translates an address to its corresponding shadow
-address:
+address::
 
-static inline void *kasan_mem_to_shadow(const void *addr)
-{
+    static inline void *kasan_mem_to_shadow(const void *addr)
+    {
 	return ((unsigned long)addr >> KASAN_SHADOW_SCALE_SHIFT)
 		+ KASAN_SHADOW_OFFSET;
-}
+    }
 
-where KASAN_SHADOW_SCALE_SHIFT = 3.
+where ``KASAN_SHADOW_SCALE_SHIFT = 3``.
 
 Compile-time instrumentation used for checking memory accesses. Compiler inserts
 function calls (__asan_load*(addr), __asan_store*(addr)) before each memory

Documentation/dev-tools/tools.rst

@@ -18,3 +18,4 @@ whole; patches welcome!
    sparse
    kcov
    gcov
+   kasan

MAINTAINERS

@@ -6587,7 +6587,7 @@ L:	kasan-dev@googlegroups.com
 S:	Maintained
 F:	arch/*/include/asm/kasan.h
 F:	arch/*/mm/kasan_init*
-F:	Documentation/kasan.txt
+F:	Documentation/dev-tools/kasan.rst
 F:	include/linux/kasan*.h
 F:	lib/test_kasan.c
 F:	mm/kasan/