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

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

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

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

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

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)

    {

		+ 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

   sparse

   kcov

   gcov

   kasan

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/