[clang] [rtsan] Update docs to include run-time flags (PR #110296)

[Chris Apple via cfe-commits]

https://github.com/cjappl created https://github.com/llvm/llvm-project/pull/110296

None

>From 128f414de9f19596e81db6afe5e1d0b166888775 Mon Sep 17 00:00:00 2001
From: Chris Apple <cja-private at pm.me>
Date: Fri, 27 Sep 2024 09:40:11 -0700
Subject: [PATCH] [rtsan] Update docs to include run-time flags

---
 clang/docs/RealtimeSanitizer.rst | 69 ++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)

diff --git a/clang/docs/RealtimeSanitizer.rst b/clang/docs/RealtimeSanitizer.rst
index 5e281a2a357907..bddf39ecaf1c5a 100644
--- a/clang/docs/RealtimeSanitizer.rst
+++ b/clang/docs/RealtimeSanitizer.rst
@@ -84,6 +84,75 @@ non-zero exit code.
     #14 0x0001958960dc  (<unknown module>)
     #15 0x2f557ffffffffffc  (<unknown module>)
 
+Run-time flags
+--------------
+
+RealtimeSanitizer supports a number of run-time flags, which can be specified in the ``RTSAN_OPTIONS`` environment variable:
+
+.. code-block:: console
+
+   % RTSAN_OPTIONS=option_1=true:path_option_2="/some/file.txt" ./a.out
+   ...
+
+Or at compiler time by overloading the symbol ``__rtsan_default_options``:
+
+.. code-block:: c
+
+  extern "C" const char *__rtsan_default_options() {
+    return "symbolize=false:abort_on_error=0:log_to_syslog=0";
+  }
+
+You can see all sanitizer options (some of which are unsupported) by using the ``help`` flag:
+
+.. code-block:: console
+
+   % RTSAN_OPTIONS=help=true ./a.out
+
+A **partial** list of flags RealtimeSanitizer respects:
+
+.. list-table:: Run-time Flags
+   :widths: 20 10 10 70
+   :header-rows: 1
+
+   * - Flag name
+     - Default value
+     - Type
+     - Short description
+   * - ``halt_on_error``
+     - ``true``
+     - boolean
+     - Exit after first reported error. If false (continue after a detected error), deduplicates error stacks so errors appear only once.
+   * - ``print_stats_on_exit``
+     - ``false``
+     - boolean
+     - Print stats on exit. Includes total and unique errors.
+   * - ``color``
+     - ``"auto"``
+     - string
+     - Colorize reports: (always|never|auto).
+   * - ``fast_unwind_on_fatal``
+     - ``false``
+     - boolean
+     - If available, use the fast frame-pointer-based unwinder on detected errors. If true, ensure the code under test has been compiled with frame pointers with ``-fno-omit-frame-pointers`` or similar.
+   * - ``abort_on_error``
+     - OS dependent
+     - boolean
+     - If true, the tool calls abort() instead of _exit() after printing the error report. On some OSes (OSX, for exmple) this is beneficial because a better stack trace is emitted on crash.
+   * - ``symbolize``
+     - ``true``
+     - boolean
+     - If set, use the symbolizer to turn virtual addresses to file/line locations. If false, can greatly speed up the error reporting.
+
+
+Some issues with flags can be debugged using the ``verbosity=$NUM`` flag:
+
+.. code-block:: console
+
+   % RTSAN_OPTIONS=verbosity=1:misspelled_flag=true ./a.out
+   WARNING: found 1 unrecognized flag(s):
+   misspelled_flag
+   ...
+
 Disabling
 ---------