[sancov] Document -fsanitize-coverage=stack-depth

Add documentation to detail the behaviors of the stack-depth tracer,
including the new -fsanitize-coverage-stack-depth-callback-min=N
argument.

Author: kees

clang/docs/SanitizerCoverage.rst

@@ -385,6 +385,46 @@ Users need to implement a single function to capture the CF table at startup:
     // the collected control flow.
   }
 
+Tracing Stack Depth
+===================
+
+With ``-fsanitize-coverage=stack-depth`` the compiler will track how much
+stack space has been used for a function call chain. Leaf functions are
+not included in this tracing.
+
+The maximum depth of a function call graph is stored in the thread-local
+``__sancov_lowest_stack`` variable. Instrumentation is inserted in each
+non-leaf function to check the stack pointer against this variable, and
+if it is lower, store the current stack pointer. This effectively does:
+
+.. code-block:: c++
+
+  thread_local __sancov_lowest_stack;
+
+  if (stack_pointer < __sancov_lowest_stack)
+    __sancov_lowest_stack = stack_pointer;
+
+If ``-fsanitize-coverage-stack-depth-callback-min=N`` is also used,
+the tracking is delegated to a callback, ``__sanitize_cov_stack_depth``,
+instead of adding instrumentation to update ``__sancov_lowest_stack``.
+The ``N`` of the argument is used to determine which functions to
+instrument. Only functions using ``N`` bytes or more of stack space
+will be instrumented to call the tracing callback. In the case of a
+dynamically sized stack, the callback is unconditionally added.
+
+The callback takes no arguments and is responsible for determining
+the stack pointer and doing any needed comparisons and storage. The
+prototype is:
+
+.. code-block:: c++
+
+  extern "C"
+  void __sanitize_cov_stack_depth(void);
+
+Note that, currently, dynamically sized stacks are not tracked by
+instrumentation correctly, as it is inserted too early. This means
+that only constant sized stack allocations are currently tracked.
+
 Gated Trace Callbacks
 =====================