[PATCH v3 08/11] manual: Add descriptions for sampling-asan in the manual

[Sung-hun Kim]

This patch includes following changes:

 * A new section "Memory Debugging" is added as a part of Chapter 3
   "Virtual Memory Allocation And Paging".
 * A description for a newly added tunable "libc.malloc.malloc_sanitize"
   is added.

The new section can be extended to include other memory debugging features.
But for now, brief description of address sanitization and full description
of sampling-asan are added.

Signed-off-by: Sung-hun Kim <sfoon.kim@samsung.com>
---
 manual/memory.texi   | 141 +++++++++++++++++++++++++++++++++++++++++++
 manual/tunables.texi |  13 ++++
 2 files changed, 154 insertions(+)

diff --git a/manual/memory.texi b/manual/memory.texi
index 6a70168e61..0515703bfc 100644
--- a/manual/memory.texi
+++ b/manual/memory.texi
@@ -19,6 +19,7 @@ and allocation of real memory.
 * Resizing the Data Segment::   @code{brk}, @code{sbrk}
 * Memory Protection::           Controlling access to memory regions.
 * Locking Pages::               Preventing page faults
+* Memory Debugging::                Debugging wrong memory allocation/free/accesses.
 @end menu
 
 Memory mapped I/O is not discussed in this chapter.  @xref{Memory-mapped I/O}.
@@ -3632,8 +3633,148 @@ calls can fail, so there are no specific @code{errno} values.
 
 @end deftypefun
 
+@node Memory Debugging
+@section Memory Debugging
+
+You can meet memory-related bugs, such as dangling pointers, whenever
+you write the code.
+This is because the nature of the C launguage enforces the
+responsibility of managing the lifecycle of allocated memory objects
+to authors.
+
+@node Address Sanitization Overview
+@subsection Address Sanitization Overview
+
+AddressSanitizer
+(@pxref{Instrumentation Options,, Program Instrumentation Options, gcc, Using GCC})
+is commonly used to detect a subset (but most of) of memory bugs at
+the expense of runtime overhead.
+AddressSanitizer instruments memory access code and hooks memory
+allocation and deallocation to track memory states.
+Memory states are stored in a separate metadata area known as shadow
+memory.
+AddressSanitizer uses shadow memory for detecting memory bugs, such as
+accessing a freed memory object.
+
+
+@node Sampling-based Address Sanitization
+@subsection Sampling-based Address Sanitization
+
+While AddressSanitizer provides a comprehensive method to detect memory
+bugs, its impact on performance makes developers to hesitate using
+it for bug detection.
+Sampling-asan offers an alternative way to this case by significanlty
+reducing runtime overhead through a sampling-based approach.
+Sampling-asan randomly selects memory allocations for sanitization.
+For each allocation, it "tosses a coin" to decide whether to sample it.
+If the allocation is selected for sampling, sampling-asan forwards it
+to the internal memory allocator.
+The internal memory allocator in sampling-asan uses a preallocated
+memory pool and a metadata area.
+The state of each entry in the preallocated memory pool and the call
+stacks of allocation/deallocation of the memory object are recorded in
+the metadata area.
+
+Sampling-asan leverages the OS kernel's memory protection mechanism,
+particularly the segmentation violation signal (@code{SIGSEGV}), to
+detect memory bugs.
+When a @code{SIGSEGV} is raised, the registered signal handler
+diagnoses the kind of the memory bug.
+Then, it emits a bug report and determines to keep the application
+running or not depending on the configuration.
+
+Note that, unlike AdderssSanitizer, sampling-asan can detect memory bugs
+on heap only.
+
+
+@node How to Use Sampling-asan
+@subsection How to Use Sampling-asan
+
+Currently, sampling-asan is served as a backend for
+@code{libc_malloc_debug.so}.
+The @code{glibc.malloc.malloc_sanitize} tunable determines which backend
+is used to @code{malloc} sanitization.
+For now, only sampling-asan can be used for this purpose (use
+@code{MALLOC_SANITIZE_} as an alias of
+@code{glibc.malloc_malloc_sanitize}.).
+
+Sampling-asan provides configurable options via environment variables.
+Below is a list of configurable options and their descriptions
+(note that every configurable options have SAMASAN_ as a prefix):
+
+@table @code
+@item SAMASAN_ENABLE
+Enable sampling-asan.
+You can use "true", "yes", "enable", and "on" to activate it;
+other values disable it (default: false).
+
+@item SAMASAN_MAX_ALLOC_SIZE
+Set the upper limit of the sanitized allocation size in bytes
+(default: 4096).
+Allocations larger than this limits fall back to the normal
+@code{malloc} call.
+
+@item SAMASAN_MAX_ON_GOING_ALLOCATIONS
+Set the maximum number of concurrent sanitized allocations
+(default: 100).
+Once this limit is reached, further allocations are not sanitized.
+They fall back to the normal @code{malloc} call.
+The size of the preallocated memory pool is decided by this value
+and the SAMASAN_PARTITION_SIZE setting.
+
+@item SAMASAN_SAMPLING_RATE
+Set the sampling rate (default: 0.005).
+You should use a floating point number between 0 to 1.0.
+For example, if a sampling rate is 0.005, five calls out of every
+thousand calls are sampled statistically.
+
+@item SAMASAN_OUTPUT_PATH
+Set the output path for a bug report (default: @code{stderr}).
+You should use an absolute path like "/tmp/bug-report".
+
+@item SAMASAN_PARTITION_SIZE
+Set the size of a partition in bytes (default: 4096).
+A partition is a protected memory area and does not allow any access
+on it.
+Two partitions enclose a memory block in the preallocated memory pool.
+The total number of partitions is calculated as
+SAMASAN_MAX_ON_GOING_ALLOCATIONS + 1.
+If zero is given, partitions are not allocated.
+
+@item SAMASAN_PAUSE_ON_FORK
+Decide to pause sampling-asan when a new process is forked or not.
+You can use "true", "yes", "enable", and "on" (default is "true").
+Other values disable this configuration.
+
+@item SAMASAN_CHUNK_PICK
+Specify a chunk area with in a memory block to be used.
+You can use "LEFT", "CENTER", and "RIGHT" (default: "CENTER").
+If you specify "LEFT", sampling-asan allocates a memory chunk
+at the leftmost in the selected memory block.
+Other values will cause sampling-asan initialization to fail.
+
+@item SAMASAN_CONTINUE_ON_CRASH
+Determine whether the application continues running after detecting
+a memory bug (default: false).
+In production environments, developers may prefer to keep the
+application running even after detecting a memory bug.
+If you set this value to true, sampling-asan does not terminate the
+application if the detected bug is recoverable.
+
+@end table
+
+Here is a simple example of how to use sampling-asan.
 
+@smallexample
+  $ export SAMASAN_ENABLE=true
+  $ export SAMASAN_MAX_ON_GOING_ALLOCATIONS=100
+  $ export SAMASAN_OUTPUT_PATH=/tmp/bug-report
+  $ LD_PRELOAD=/usr/lib/libc_malloc_debug.so MALLOC_SANITIZE_=sampling-asan
+    <your program>
+@end smallexample
 
+You can find the bug report at @code{/tmp/bug-report} when a memory
+bug is occurred.
 
 @ignore
 @c This was never actually implemented.  -zw
diff --git a/manual/tunables.texi b/manual/tunables.texi
index e4592e23cc..aaa7d9601e 100644
--- a/manual/tunables.texi
+++ b/manual/tunables.texi
@@ -45,6 +45,7 @@ glibc.mem.tagging: 0 (min: 0, max: 255)
 glibc.elision.tries: 3 (min: 0, max: 2147483647)
 glibc.elision.enable: 0 (min: 0, max: 1)
 glibc.malloc.hugetlb: 0x0 (min: 0x0, max: 0xffffffffffffffff)
+glibc.malloc.malloc_sanitize:
 glibc.cpu.x86_rep_movsb_threshold: 0x2000 (min: 0x100, max: 0xffffffffffffffff)
 glibc.malloc.mxfast: 0x0 (min: 0x0, max: 0xffffffffffffffff)
 glibc.rtld.dynamic_sort: 2 (min: 1, max: 2)
@@ -294,6 +295,18 @@ supported ones.  If provided value is invalid, @code{MAP_HUGETLB} will not
 be used.
 @end deftp
 
+@deftp Tunable glibc.malloc.malloc_sanitize
+This tunable configures the backend used for sanitizing @code{malloc}.
+It requires a string specified with @code{=} (e.g.,
+@code{glibc.malloc.malloc_sanitize=sampling-asan}).
+Currently, sampling-asan is only available as a sanitization backend.
+You can use @code{MALLOC_SANITIZE_} as an alias of this tunable.
+
+Sanitization refers to various methods used to verify whether a function
+has executed correctly or not. In this context, we focus solely on address
+sanitization as the sanitization method to keep clarity and simplicity.
+@end deftp
+
 @node Dynamic Linking Tunables
 @section Dynamic Linking Tunables
 @cindex dynamic linking tunables
-- 
2.25.1