Getting Started: Running an Analysis

In the following we describe how PhASAR can be used to perform data-flow analyses.

Choosing an existing analysis

PhASAR's built-in analyses can be selected using the -D or --analysis command-line option. Note: more than one analysis can be selected to be executed on the code under analysis. Example:

$ phasar-llvm -m module.ll -D IFDSSolverTest 
$ phasar-llvm -m module.ll -D IFDSUninitializedVariables

If no analysis is selected only the call-graph and other supported data structures are created. If a call using "-D None" fails, there is definitely an error within the code or project under analysis or within the PhASAR framework (which is obviously worse). In either way please report the errors with the target code that triggers those errors.

Currently the following built-in analyses are available in PhASAR:

DataFlowAnalysisType	Parameter
DataFlowAnalysisType::IFDSConstAnalysis	"IFDSConstAnalysis"
DataFlowAnalysisType::IFDSLinearConstantAnalysis	"IFDSLinearConstantAnalysis"
DataFlowAnalysisType::IFDSSolverTest	"IFDSSolverTest"
DataFlowAnalysisType::IFDSTaintAnalysis	"IFDSTaintAnalysis"
DataFlowAnalysisType::IFDSTypeAnalysis	"IFDSTypeAnalysis"
DataFlowAnalysisType::IFDSUninitializedVariables	"IFDSUninitializedVariables"
DataFlowAnalysisType::IDELinearConstantAnalysis	"IDELinearConstantAnalysis"
DataFlowAnalysisType::IDESolverTest	"IDESolverTest"
DataFlowAnalysisType::IDETaintAnalysis	"IDETaintAnalysis"
DataFlowAnalysisType::IDETypeStateAnalysis	"IDETypeStateAnalysis"
DataFlowAnalysisType::IntraMonoFullConstantPropagation	"IntraMonoFullConstantPropagation"
DataFlowAnalysisType::IntraMonoSolverTest	"IntraMonoSolverTest"
DataFlowAnalysisType::InterMonoSolverTest	"InterMonoSolverTest"
DataFlowAnalysisType::InterMonoTaintAnalysis	"InterMonoTaintAnalysis"
DataFlowAnalysisType::Plugin	"Plugin"
DataFlowAnalysisType::None	"None"

Command line interface

PhASAR provides a stable command line interface (CLI). The help command displays all the parameters supported by PhASAR.

$ phasar-llvm --help 

outputs:

PhASAR v0120
A LLVM-based static analysis framework

Allowed options:

Command-line options:
  -v [ --version ]                      Print PhASAR version
  -h [ --help ]                         Print help message
  --more-help                           Print more help
  -c [ --config ] arg                   Path to the configuration file, options
                                        can be specified as 'parameter = 
                                        option'
  -s [ --silent ]                       Suppress any non-result output

Configuration file options:
  -m [ --module ] arg                   Path to the module(s) under analysis
  -E [ --entry-points ] arg             Set the entry point(s) to be used
  -O [ --output ] arg (=results.json)   Filename for the results
  -D [ --data-flow-analysis ] arg       Set the analysis to be run
  --analysis-strategy arg (=WPA)
  --analysis-config arg                 Set the analysis's configuration (if 
                                        required)
  -P [ --pointer-analysis ] arg (=CFLAnders)
                                        Set the points-to analysis to be used 
                                        (CFLSteens, CFLAnders)
  -C [ --call-graph-analysis ] arg (=OTF)
                                        Set the call-graph algorithm to be used
                                        (NORESOLVE, CHA, RTA, DTA, VTA, OTF)
  -H [ --classhierarchy-analysis ]      Class-hierarchy analysis
  -S [ --statistical-analysis ]         Statistics
  -M [ --mwa ]                          Enable Modulewise-program analysis mode
  -R [ --printedgerec ]                 Print exploded-super-graph edge 
                                        recorder
  -L [ --log ]                          Enable logging
  --emit-ir                             Emit preprocessed and annotated IR of 
                                        analysis target
  --emit-raw-results                    Emit unprocessed/raw solver results
  --emit-text-report                    Emit textual report of solver results
  --emit-graphical-report               Emit graphical report of solver results
  --emit-esg-as-dot                     Emit the Exploded super-graph (ESG) as 
                                        DOT graph
  --emit-th-as-text                     Emit the type hierarchy as text
  --emit-th-as-dot                      Emit the type hierarchy as DOT graph
  --emit-cg-as-text                     Emit the call graph as text
  --emit-cg-as-dot                      Emit the call graph as DOT graph
  --emit-pta-as-text                    Emit the points-to information as text
  --emit-pta-as-dot                     Emit the points-to information as DOT 
                                        graph
  --right-to-ludicrous-speed            Uses ludicrous speed (shared memory 
                                        parallelism) whenever possible
  --analysis-plugin arg                 Analysis plugin(s) (absolute path to 
                                        the shared object file(s))
  --callgraph-plugin arg                ICFG plugin (absolute path to the 
                                        shared object file)
  -I [ --project-id ] arg (=default-phasar-project)
                                        Project Id used for the database
  -A [ --pamm-out ] arg (=PAMM_data.json)
                                        Filename for PAMM's gathered data

Running an analysis

The analysis on PhASAR runs on LLVM IR code rather than the source code. In order to run some analysis on your code, you need to translate it into LLVM IR code.

In order to translate a short C/C++ code into the LLVM IR, you can use the LLVM compiler tool chain. The following command calls the clang compiler to emit the LLVM IR code from c++ code.

$ clang++ -emit-llvm -S -fno-discard-value-names main.cpp

After running this command a file named main.ll can be found within the current directory.

The file to be analyzed by our framework can be specified using the -m flag. PhASAR starts the analysis at the very first instruction of the main() function by default.

An example call to an analysis is:

$ phasar-llvm -m path/to/your/main.ll -D IFDSSolverTest

In the case of analyzing a complex project you can use WLLVM tool that is explained on the Whole Program Analysis (using WLLVM) page.

You can find some concrete examples of the whole process of running some analysis on some code, in more details, here.