[clang] 529f098 - [NFC][DFSan] Update DataFlowSanitizer user docs for -dfsan-conditional-callbacks, added in https://reviews.llvm.org/D116207

[Andrew Browne via cfe-commits]

Author: Andrew Browne
Date: 2022-01-13T10:05:45-08:00
New Revision: 529f098789d334de9cd06e913ad9525719fa0774

URL: https://github.com/llvm/llvm-project/commit/529f098789d334de9cd06e913ad9525719fa0774
DIFF: https://github.com/llvm/llvm-project/commit/529f098789d334de9cd06e913ad9525719fa0774.diff

LOG: [NFC][DFSan] Update DataFlowSanitizer user docs for -dfsan-conditional-callbacks, added in https://reviews.llvm.org/D116207

Reviewed By: morehouse

Differential Revision: https://reviews.llvm.org/D117177

Added: 
    

Modified: 
    clang/docs/DataFlowSanitizer.rst

Removed: 
    


################################################################################
diff  --git a/clang/docs/DataFlowSanitizer.rst b/clang/docs/DataFlowSanitizer.rst
index cce50dc913185..b4136a935dd28 100644
--- a/clang/docs/DataFlowSanitizer.rst
+++ b/clang/docs/DataFlowSanitizer.rst
@@ -214,6 +214,25 @@ labels of just ``v1`` and ``v2``.
   void __dfsan_mem_transfer_callback(dfsan_label *Start, size_t Len);
   void __dfsan_cmp_callback(dfsan_label CombinedLabel);
 
+* ``-dfsan-conditional-callbacks`` -- An experimental feature that inserts
+  callbacks for control flow conditional expressions.
+  This can be used to find where tainted values can control execution.
+
+  In addition to this compilation flag, a callback handler must be registered
+  using ``dfsan_set_conditional_callback(my_callback);``, where my_callback is
+  a function with a signature matching
+  ``void my_callback(dfsan_label l, dfsan_origin o);``.
+  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 only be called when a tainted value reaches a conditional
+  expression for control flow (such as an if's condition).
+  The callback will be skipped for conditional expressions inside signal
+  handlers, as this is prone to deadlock. Tainted values used in conditional
+  expressions inside signal handlers will instead be aggregated via bitwise
+  or, and can be accessed using
+  ``dfsan_label dfsan_get_labels_in_signal_conditional();``.
+
 * ``-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