1 files changed, 38 insertions, 2 deletions

diff --git a/gcc/doc/analyzer.texi b/gcc/doc/analyzer.texi
index 755db7c..87a2a40 100644
--- a/gcc/doc/analyzer.texi
+++ b/gcc/doc/analyzer.texi
@@ -432,7 +432,7 @@ binop_svalue (mult_expr, initial_svalue(‘size_t’, decl_region(frame_region(â
 @subsection Analyzer Paths
 
 We need to explain to the user what the problem is, and to persuade them
-that there really is a problem.  Hence having a @code{diagnostic_path}
+that there really is a problem.  Hence having a @code{diagnostics::paths::path}
 isn't just an incidental detail of the analyzer; it's required.
 
 Paths ought to be:
@@ -491,7 +491,7 @@ and notes if it is infeasible.
 
 The above gives us a shortest feasible @code{exploded_path} through the
 @code{exploded_graph} (a list of @code{exploded_edge *}).  We use this
-@code{exploded_path} to build a @code{diagnostic_path} (a list of
+@code{exploded_path} to build a @code{diagnostics::paths::path} (a list of
 @strong{events} for the diagnostic subsystem) - specifically a
 @code{checker_path}.
 
@@ -619,6 +619,25 @@ python-xdot)
 @item @code{-fdump-analyzer-exploded-nodes-2}
 which dumps a @file{SRC.eg.txt} file containing the full @code{exploded_graph}.
 
+@item @code{-fdiagnostics-add-output=experimental-html:show-state-diagrams=yes}
+which writes out the diagnostics in HTML form, and generates SVG state
+diagrams visualizing the state of memory at each event (inspired by the
+"ddd" debugger).  These can be seen by pressing 'j' and 'k' to single-step
+forward and backward through events.  Note that these SVG diagrams are
+created from an intermediate SARIF directed graph representation generated from
+@code{program_state} objects.  The SARIF representation can be easier to
+read - for example, rather than storing the contents of memory via byte
+offsets, it uses fields for structs and element indexes for arrays,
+recursively.  However it is a different representation, and thus bugs could
+be hidden by this transformation.  Generating the SVG diagrams requires
+an invocation of "dot" per event, so it noticeably slows down diagnostic
+emission, hence the opt-in command-line flag.  The SARIF and ``dot''
+representations can be seen by @code{__analyzer_dump_xml} and
+@code{__analyzer_dump_dot} below (writing them to stderr), or by adding
+@code{show-state-diagrams-sarif=yes} and
+@code{show-state-diagrams-dot-src=yes} to the html sink, which shows
+them within the generated HTML next to the generated SVG.
+
 @end itemize
 
 Assuming that you have the
@@ -688,6 +707,15 @@ extern void __analyzer_dump_capacity (const void *ptr);
 will emit a warning describing the capacity of the base region of
 the region pointed to by the 1st argument.
 
+@item __analyzer_dump_dot
+@smallexample
+__analyzer_dump_dot ();
+@end smallexample
+
+will dump GraphViz .dot source to stderr reaches the call in its
+traversal of the source.  This .dot source implements a diagram
+describing the analyzer’s state.
+
 @item __analyzer_dump_escaped
 @smallexample
 extern void __analyzer_dump_escaped (void);
@@ -764,6 +792,14 @@ will emit a warning describing the state of the 2nd argument
 a name matching the 1st argument (which must be a string literal).
 This is for use when debugging, and may be of use in DejaGnu tests.
 
+@item __analyzer_dump_sarif
+@smallexample
+__analyzer_dump_sarif ();
+@end smallexample
+
+will dump the copious information about the analyzer's state each time it
+reaches the call in its traversal of the source.
+
 @item __analyzer_eval
 @smallexample
 __analyzer_eval (expr);