[cfe-commits] r162336 - /cfe/trunk/docs/analyzer/debug-checks.txt

[Anna Zaks]

On Aug 21, 2012, at 6:03 PM, Jordan Rose wrote:

> 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
> +---------------------
> +
 
Below, it's unclear which function you are talking about (function name is not included).  Looks like this is copy and paste from the docs.. Are comments intended to be here?

> +// 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);
> +

Same as above, no function name.

Also, an example would be helpful, just to underline that way one is supposed to use this is by including in the function body.

> +
> +// 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.)

I do not think it's a good idea. analyzer-stats is supposed to be a very light weight mechanism for collecting stats. We could even use it for performance measurement. We also do not want to perform extra analyzer work when it's enabled. For example, what if we want to collect stats on BugReporter internals? Stats checker is going to produce at least one warning per function, so it will be very different from the pure execution.

> \ No newline at end of file
> 
> 
> _______________________________________________
> cfe-commits mailing list
> cfe-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/cfe-commits