Running CSI: Additional Comments and Suggestions

CSI Guide

Additional Comments and Suggestions

The following are some suggestions regarding ways things could go wrong while trying to run the CSI compiler, and some additional information about command-line options.

A standard compilation of csi-cc should provide, in addition to the source file being compiled and any other required compilation options for that file:

A schema indicating what type of tracing to enable for each function
An optimization level for coverage-based tracing (see below for defaults, and the Coverage Optimization page for details on flags)

For example, to gather call-site coverage for all functions using basic level 1 optimization, the command would be
csi-cc --trace=cc.schema -csi-opt=1 <input file>
while gathering call-site coverage using one of the fully-optimal instrumentors (longer compile times,but less instrumentation required) would be
csi-cc --trace=cc.schema -csi-opt=3 -opt-style=lemon <input file>

It’s fine to symlink to the csi-cc file, but you shouldn’t copy it out. You can move the entire CSI directory as required, but the relative path between the Release directory and the Tools directory (and all files inside them) must be the same, or things won’t work.

If you get an error like
Error opening '/.../csi/Release/libCSI.so': libLLVM-3.X.so: cannot open shared object file: No such file or directory
this means that the LLVM version you built with (see building notes on LLVM_CONFIG) does not match the one in your PATH.

The full list of CSI-specific options is as follows

USAGE: csi-cc [options] <inputs>

COMMON OPTIONS:
  --trace=<file>          Use <file> as the input file for the tracing schemes.
                          If this option is not given, the scheme is read from
                          stdin.
  -csi-opt=<arg>          Use <arg> as the optimization level for CSI
                          instrumentation passes.  Legal values are <0,1,2,3>.
                          (Default: 2)
  -opt-style=<arg>        Use <arg> as the style for CSI optimization level 2 or
                          3.
                          Legal values for level 2: <simple,local,local-prepass>
                          (Default for level 2: local-prepass)
                          Legal values for level 3: <gams,lemon>
                          (Default for level 3: gams, if installed)
  --silent                Do not print pass-specific warnings during
                          instrumentation
  
  --help                  Display this help message and exit
  --help-clang            Display additional options (clang's help message) and
                          exit

OPTIONS FOR DEVELOPMENT OF CSI:
  -debug-pass=<arg>       Enable printing of extremely verbose debug messages
                          for the pass specified as <arg>.  This should
                          generally not be used unless debugging instrumentors.
                          <arg> can be any of the supported instrumentors or
                          'all' (which enables debugging for all passes).
                          Legal values are
                          <all,prep,bbc,cc,fc,pt,coverage-optimization>.
                          This option is only available if LLVM is built with
                          assertions enabled.
  -verify-results         Enables additional verification of computed results
                          during instrumentation.  For example, this ensures
                          that all coverage sets are verified during
                          optimization.  This is an expensive operation.
  -no-filter              Do not filter tracing schemes.  All schemes provided
                          will be used verbatim for functions to which they
                          match.
  -no-heuristics          Do not use heuristics to improve coverage optimization
                          performance.  Presently, this has little-to-no impact
                          on performance in most cases, but should generally
                          only be used for debugging instrumentors.
  -log-stats              Logs various statistics about coverage optimization
                          sets to stdout.  Presently, this is used for research
                          experiments.

LESS COMMON OPTIONS:
  --indirect-style=<arg>  Use the provided style for creating indirect
                          functions, which enables custimization of
                          instrumentation.  Current styles are {std, ifunc}.
                          (Default: std)
  -path-array-size <arg>  Use <arg> as the size of path tracing arrays
                          (Default: 10)
  -hash-size <arg>        Use <arg> as the maximum-size function (in number of
                          acyclic paths) to instrument for path tracing
                          (Default: ULONG_MAX/2+1)
  -complete-exe           Optimize coverage instrumentation further such that
                          accurate coverage information is only guaranteed for
                          complete function executions.  This can potentially
                          improve instrumentation efficiency, but may lose
                          information; thus, it should not be used in normal
                          circumstances.

ENVIRONMENT VARIABLES:
  PT_ARRAY_SIZE           See -path-array-size (above).  Flags have precedence.
  PT_HASH_SIZE            See -hash-size (above).  Flags have precedence.
  CSI_SILENT              Enables or disables the printing of instrumentation
                          warnings.
                          See --silent (above).  Flags have precedence.

← Prev

Contents