[sanitizer-coverage] better docs for -fsanitize-coverage=trace-bb

git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@266672 91177308-0d34-0410-b5e6-96231b3b80d8

diff --git a/docs/SanitizerCoverage.rst b/docs/SanitizerCoverage.rst
index 024511cf51c6e1e28f62db268ccb5a0e408c6f3c..d2dde000273a20d5d2e9362f17e32fd31c00caa9 100644 (file)
--- a/docs/SanitizerCoverage.rst
+++ b/docs/SanitizerCoverage.rst
@@ -286,10 +286,26 @@ These counters may also be used for in-process coverage-guided fuzzers. See
 
 Tracing basic blocks
 ====================
-An *experimental* feature to support basic block (or edge) tracing.
+Experimental support for basic block (or edge) tracing.
 With ``-fsanitize-coverage=trace-bb`` the compiler will insert
 ``__sanitizer_cov_trace_basic_block(s32 *id)`` before every function, basic block, or edge
 (depending on the value of ``-fsanitize-coverage=[func,bb,edge]``).
+Example:
+
+.. code-block:: console
+
+    % clang -g -fsanitize=address -fsanitize-coverage=edge,trace-bb foo.cc
+    % ASAN_OPTIONS=coverage=1 ./a.out
+
+This will produce two files after the process exit:
+`trace-points.PID.sancov` and `trace-events.PID.sancov`.
+The first file will contain a textual description of all the instrumented points in the program
+in the form that you can feed into llvm-symbolizer (e.g. `a.out 0x4dca89`), one per line.
+The second file will contain the actual execution trace as a sequence of 4-byte integers
+-- these integers are the indices into the array of instrumented points (the first file).
+
+Basic block tracing is currently supported only for single-threaded applications.
+
 
 Tracing PCs
 ===========