Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 2757aafa authored by Jonathan Corbet's avatar Jonathan Corbet
Browse files

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



No textual changes beyond formatting.

Acked-by: default avatarAndrey Ryabinin <aryabinin@virtuozzo.com>
Acked-by: default avatarAlexander Potapenko <glider@google.com>
Cc: Dmitry Vyukov <dvyukov@google.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 2584bab2
Loading
Loading
Loading
Loading
+173 −0
Original line number Diff line number Diff line
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,16 +32,18 @@ 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
@@ -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,7 +152,7 @@ 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)
    {
@@ -158,7 +160,7 @@ 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
+1 −0
Original line number Diff line number Diff line
@@ -18,3 +18,4 @@ whole; patches welcome!
   sparse
   kcov
   gcov
   kasan
+1 −1
Original line number Diff line number Diff line
@@ -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/