Author: jrose
Date: Tue Aug 21 20:03:39 2012
New Revision: 162336
URL: http://llvm.org/viewvc/llvm-project?rev=162336&view=rev
Log:
[analyzer] Document our debug checkers and ExprInspection's "builtins".
Added:
cfe/trunk/docs/analyzer/debug-checks.txt
Added: cfe/trunk/docs/analyzer/debug-checks.txt
URL:
http://llvm.org/viewvc/llvm-project/cfe/trunk/docs/analyzer/debug-checks.txt?rev=162336&view=auto
==============================================================================
--- cfe/trunk/docs/analyzer/debug-checks.txt (added)
+++ cfe/trunk/docs/analyzer/debug-checks.txt Tue Aug 21 20:03:39 2012
@@ -0,0 +1,68 @@
+The analyzer contains a number of checkers which can aid in debugging. Enable
them by using the "-analyzer-checker=" flag, followed by the name of the
checker.
+
+General Analysis Dumpers
+========================
+These checkers are used to dump the results of various infrastructural
analyses to stderr. Some checkers also have "view" variants, which will display
a graph using a 'dot' format viewer (such as Graphviz on OS X) instead.
+
+- debug.DumpCallGraph, debug.ViewCallGraph: Show the call graph generated for
the current translation unit. This is used to determine the order in which to
analyze functions when inlining is enabled.
+- debug.DumpCFG, debug.ViewCFG: Show the CFG generated for each top-level
function being analyzed.
+- debug.DumpDominators: Shows the dominance tree for the CFG of each top-level
function.
+- debug.DumpLiveVars: Show the results of live variable analysis for each
top-level function being analyzed.
+
+
+Path Tracking
+=============
+These checkers print information about the path taken by the analyzer engine.
+
+- debug.DumpCalls: Prints out every function or method call encountered during
a path traversal. This is indented to show the call stack, but does NOT do any
special handling of branches, meaning different paths could end up interleaved.
+- debug.DumpTraversal: Prints the name of each branch statement encountered
during a path traversal ("IfStmt", "WhileStmt", etc). Currently used to check
whether the analysis engine is doing BFS or DFS.
+
+
+State Checking
+==============
+These checkers will print out information about the analyzer state in the form
of analysis warnings. They are intended for use with the -verify functionality
in regression tests.
+
+- debug.TaintTest: Prints out the word "tainted" for every expression that
carries taint. At the time of this writing, taint was only introduced by the
checks under experimental.security.taint.TaintPropagation; this checker may
eventually move to the security.taint package.
+- debug.ExprInspection: Responds to certain function calls, which are modeled
after builtins. These function calls should affect the program state other than
the evaluation of their arguments; to use them, you will need to declare them
within your test file. The available functions are described below.
+
+(FIXME: debug.ExprInspection should probably be renamed, since it no longer
only inspects expressions.)
+
+
+ExprInspection checks
+---------------------
+
+// Prints TRUE if the argument is known to have a non-zero value,
+// FALSE if the argument is known to have a zero or null value, and
+// UNKNOWN if the argument isn't sufficiently constrained on this path.
+// You can use this to test other values by using expressions like "x == 5".
+// Note that this functionality is currently DISABLED in inlined functions,
+// since different calls to the same inlined function could provide different
+// information, making it difficult to write proper -verify directives.
+//
+// In C, the argument can be typed as 'int' or as '_Bool'.
+void clang_analyzer_eval(bool);
+
+
+// If a call occurs within an inlined function, prints TRUE or FALSE according
to
+// the value of its argument. If a call occurs outside an inlined function,
+// nothing is printed.
+//
+// The intended use of this checker is to assert that a function is inlined at
+// least once (by passing 'true' and expecting a warning), or to assert that a
+// function is never inlined (by passing 'false' and expecting no warning). The
+// argument is technically unnecessary but is intended to clarify intent.
+//
+// You might wonder why we can't print TRUE if a function is ever inlined and
+// FALSE if it is not. The problem is that any inlined function could
conceivably
+// also be analyzed as a top-level function (in which case both TRUE and FALSE
+// would be printed), depending on the value of the -analyzer-inlining option.
+//
+// In C, the argument can be typed as 'int' or as '_Bool'.
+void clang_analyzer_checkInlined(bool);
+
+
+Statistics
+==========
+The debug.Stats checker collects various information about the analysis, such
as how many blocks were reached and if the analyzer timed out. There is also an
additional -analyzer-stats flag, which enables various statistics within the
analyzer engine.
+
+(FIXME: We should probably just have the debug.Stats checker enabled when
-analyzer-stats is passed. We can't do the other way around because by the time
checkers are enabled it's a bit too late to start a timer.)
\ No newline at end of file
_______________________________________________
cfe-commits mailing list
[email protected]
http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits
