[clang] [DFSan] Add missing documentation for -dfsan-reaches-function-callbacks. (PR #84218)

[Andrew Browne via cfe-commits]

https://github.com/browneee created https://github.com/llvm/llvm-project/pull/84218

None

>From f23dd8ed555c57a37957a12fcb81bd383bc69254 Mon Sep 17 00:00:00 2001
From: Andrew Browne <browneee at google.com>
Date: Wed, 6 Mar 2024 18:00:27 +0000
Subject: [PATCH] [DFSan] Add missing documentation for
 -dfsan-reaches-function-callbacks.

---
 clang/docs/DataFlowSanitizer.rst | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/clang/docs/DataFlowSanitizer.rst b/clang/docs/DataFlowSanitizer.rst
index a18b8ed1948f33..9b21068d8d75f3 100644
--- a/clang/docs/DataFlowSanitizer.rst
+++ b/clang/docs/DataFlowSanitizer.rst
@@ -233,6 +233,30 @@ labels of just ``v1`` and ``v2``.
   or, and can be accessed using
   ``dfsan_label dfsan_get_labels_in_signal_conditional();``.
 
+* ``-dfsan-reaches-function-callbacks`` -- An experimental feature that inserts
+  callbacks for data entering a function.
+
+  In addition to this compilation flag, a callback handler must be registered
+  using ``dfsan_set_reaches_function_callback(my_callback);``, where my_callback is
+  a function with a signature matching
+  ``void my_callback(dfsan_label label, dfsan_origin origin,
+                     const char *file, unsigned int line,
+                     const char *function);``
+  This signature is the same when origin tracking is disabled - in this case
+  the dfsan_origin passed in it will always be 0.
+
+  The callback will be called when a tained value reach stack/registers
+  in the context of a function. Tainted values can reach a function:
+    * via the arguments of the function
+    * via the return value of a call that occurs in the function
+    * via the loaded value of a load that occurs in the function
+
+  The callback will be skipped for conditional expressions inside signal
+  handlers, as this is prone to deadlock. Tainted values reaching functions
+  inside signal handlers will instead be aggregated via bitwise or, and can
+  be accessed using
+  ``dfsan_label dfsan_get_labels_in_signal_reaches_function()``.
+
 * ``-dfsan-track-origins`` -- Controls how to track origins. When its value is
   0, the runtime does not track origins. When its value is 1, the runtime tracks
   origins at memory store operations. When its value is 2, the runtime tracks