From: Jordan Rose Date: Wed, 22 Aug 2012 01:03:39 +0000 (+0000) Subject: [analyzer] Document our debug checkers and ExprInspection's "builtins". X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a779e273b1bcd6e0af08234cc3d956220db4c5f4;p=clang [analyzer] Document our debug checkers and ExprInspection's "builtins". git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@162336 91177308-0d34-0410-b5e6-96231b3b80d8 --- diff --git a/docs/analyzer/debug-checks.txt b/docs/analyzer/debug-checks.txt new file mode 100644 index 0000000000..7d71ac0b55 --- /dev/null +++ b/docs/analyzer/debug-checks.txt @@ -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