[PATCH v3 04/11] sampling-asan: Add README.md

[Sung-hun Kim]

Signed-off-by: Sung-hun Kim <sfoon.kim@samsung.com>
---
 sampling-asan/README.md | 88 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 sampling-asan/README.md

diff --git a/sampling-asan/README.md b/sampling-asan/README.md
new file mode 100644
index 0000000000..7f0c08bef1
--- /dev/null
+++ b/sampling-asan/README.md
@@ -0,0 +1,88 @@
+# Sampling-based address sanitization (sampling-asan)
+
+Author: Sung-hun Kim (sfoon.kim@samsung.com, sebuns@gmail.com)
+
+Date: 2025.02.24
+
+## Overview
+
+A sampling-asan module provides sampling-based address sanitization.
+Sampling-asan is highly inspired by [LLVM's gwp-asan](https://llvm.org/docs/GwpAsan.html).
+A memory allocation is sampled based on the sampling rate predefined
+by the user (or default). Each sampled memory allocation is tracked,
+and if a memory bug occurs in the tracked memory area, sampling-asan
+generates a bug report at the user defined path (by default, stderr).
+In this document, and all sampling-asan source codes, a prefix "samasan"
+is used to represent sampling-asan.
+
+## Preallocated memory pool
+
+Sampling-asan uses a preallocated memory pool to track memory
+allocation. The sizes of the memory pool and a memory block in the
+memory pool can be configured by environmental variables (see the
+"Configurable" section). Two memory blocks in the memory pool are
+separated by an area, namely a partition. Access to the partition is
+prohibited.
+
+An area which is practically allocated to the user is called a memory
+chunk. Normally, the user is allowed to access only a memory chunk.
+However, due to the constraint of memory management in the kernel,
+memory bugs may not be detected even if it accesses areas outside the
+memory chunk. But, if the area is modified, it can be detected on the
+free call.
+
+## Memory bugs
+
+Memory bugs which can be detected sampling-asan are listed below.
+
+- **INVALID_FREE**: The program tries to free an area that was not allocated before.
+- **DOUBLE_FREE**: The program tries to free a memory chunk that has already been freed.
+- **USE_AFTER_FREE**: The program tries to access a freed chunk.
+- **INVALID_ACCESS**: The program tries to access a prohibited area (e.g., partition).
+- **INVALID_WRITE**: The area outside the memory chunk is modified.
+- **OUT_OF_MEMORY_POOL**: An error occurrs outside the memory pool.
+
+## Configurables
+
+Sampling-asan configures sanitization configuration using environmental
+variables. Below is a list of configurables and their default values.
+
+- **SAMASAN_ENABLE=false**: It indicates whether the program uses sampling-asan or not.
+- **SAMASAN_SAMPLING_RATE=0.005**: It represents the sampling-rate used by sampling-asan.
+It can have a value between 0.0 and 1.0.
+- **SAMASAN_MAX_ON_GOING_ALLOCATIONS=100**: It means the maximum number of concurrent allocations.
+- **SAMASAN_MAX_ALLOC_SIZE=4096**: It means the maximum size of each allocation.
+An allocation can occupy up to 40,960 bytes.
+- **SAMASAN_OUTPUT_PATH=stderr**: It indicates the path of a bug report created when a memory bug occurs.
+- **SAMASAN_PARTITION_SIZE=4096**: It represents the size of a boundary area between two memory blocks.
+Sampling-asan cannot use this area for allocations.
+- **SAMASAN_PAUSE_ON_FORK=true**:  Sampling-asan synchronizes the memory pool when a child process is forked
+if this variable is true.
+- **SAMASAN_CHUNK_PICK=CENTER**: It indicates the picking tendency when allocating a memory chunk from a
+memory block. Sampling-asan supports LEFT, RIGHT, and CENTER picking
+tendencies.
+
+## How to use sampling-asan
+
+Run the program with sampling-asan using default configuration:
+
+    $ export LD_PRELOAD=/usr/lib/libc_malloc_debug.so.0
+    $ export MALLOC_SANITIZE_=sampling-asan
+    $ export SAMASAN_ENABLE=true
+    $ ./run_my_code
+
+Or,
+
+    $ export LD_PRELOAD=/usr/lib/libc_malloc_debug.so.0
+    $ export MALLOC_SANITIZE_=samasan
+    $ export SAMASAN_ENABLE=true
+    $ ./run_my_code
+
+In order to set the custom sampling-rate (e.g., using 0.01):
+
+    $ SAMASAN_SAMPLING_RATE=0.01 ./run_my_code
+
+In order to set the report path to /path/to/error-report.txt
+
+    $ SAMASAN_OUTPUT_PATH=/path/to/error-report.txt ./run_my_code
+
-- 
2.25.1