Notice: The sofya tools currently have a bug that requires the use of the [-tag tag] option when using the instrumentation and execution tracing tools described here.
To run the instrumentor to instrument a class for structural event dispatch, use the following command:
java sofya.ed.cfInstrumentor [-tag tag] <-<E|X|C|B>|-branch>
<classname|jarfile|listfile> [classname|jarfile ...]
tag parameter can be used to specify a database tag associated
with the control flow and map files required by the instrumentor
(see information on the CFG builder). If you did
not specify a tag to the CFG builder when constructing the control flow graphs
for the classes you intend to instrument, you do not need to use this
The first required parameter specifies either basic block instrumentation or branch instrumentation. To instrument basic blocks, any combination of the characters E, X, C, and B can be specified, where E specifies virtual entry blocks, X specifies virtual exit blocks, C specifies call blocks, and B specifies all other basic blocks. Entry and exit blocks do not correspond to actual code, but rather provide information about entry to and exit from methods. Branch instrumentation is not parameterized, though branch types can be filtered at runtime (this is discussed under running the event dispatcher).
When specifying a single class for instrumentation, the rules regarding inclusion of the .class extension are the same as for the CFG builder. However, the instrumentor exhibits additional behaviors with respect to the format of the class name. If an absolute path is given, the instrumentation will be directly applied to the given classfile, at the classfile's current location. If the class is loaded from the classpath, the resulting instrumented classfile will be placed in the working directory from which the instrumentor is run.
The instrumentor also accepts jar files and program list files to specify the classes to be instrumented. Program list files are automatically found in the database, using the tag if one is specified. Any necessary path information should be provided when passing a jar file as an argument. When a jar file is passed as an argument on the command line, every class in the jar is instrumented. The preferred way to include classes in a jar file is to include the jar file in a program list file and supply the program list file as an argument instead, as a program list file permits you to exclude classes in the jar from processing. Any number of specific classes, jar files, and program list files can be passed to the instrumentor, though supplying a single program list file is the expected typical use.
It should be noted that if you change the type of instrumentation, you should also remove
the bootstrap.jar file that is created during the trace generation phase by the event
dispatcher framework. See the notes within the
Running the instrumentor as described in Getting Started instruments class files for observation of basic block coverage events. The full usage for the instrumentor is the following:
java sofya.ed.cfInstrumentor [-tag tag] <-<B|E|X|C>|-branch> [-t
<norm|junit|seq>[,junit]] [-port port] [-so] <classname|jarfile|listfile>
-t parameter is used to change the inserted instrumentation
to target different mechanisms for observing events. Currently,
the following values for this parameter are available:
norm: The default, this instrumentation supports dispatch of coverage event streams. Sequence event streams cannot be dispatched using this instrumentation.
seq: This instrumentation enables dispatch of sequence event streams. Coverage event streams can also be collected, but less efficiently.
junit: This instrumentation enables dispatch of event streams through the
JUnitframework during execution of a
JUnittest suite. Event streams can be dispatched from classes containing this instrumentation only by using the
junit.textui.SelectiveTestRunner; regular event dispatchers will not operate on this instrumentation. This value is actually a modifier that can be combined with
seqto allow dispatch of either of those respective types of event streams from the execution of a
JUnittest suite. When used alone,
junitis equivalent to
norm,junit, enabling dispatch of coverage event streams from JUnit tests.
If the event dispatcher reports an error about being unable to bind to a socket,
-port parameter can be used to change the socket used by the
instrumentation. If you specify a custom port during instrumentation, you must
specify the same port to the event dispatcher when you run the instrumented class.
-so parameter is used to instruct the instrumentor to only insert
into a class the instrumentation necessary to establish the connection between a
subject and the event dispatcher. If you want to instrument certain classes, but
not the class that is the entry point for the application, you will want
to use this option on the class that is the entry point (the class containing the
main method). This is most often useful for test driver classes that
execute instrumented classes, but that are themselves not of interest for
instrumentation or event dispatch.
The principle class for dispatching structural event streams is the
ProgramEventDispatcher. This class is not directly executable,
however the "tracer" classes in the
ed package of
Σοφία are classes that generate trace files using the
ProgramEventDispatcher. For structural tracing, these consist of
BBTracer (basic block coverage traces),
BBSequenceTracer (basic block sequence traces),
BranchTracer (branch coverage traces),
BranchSequenceTracer (branch sequence traces). These classes
serve as example implementations using the structural event dispatcher,
and, with the assistance of the
TraceHandler, can be used without
modification to create trace-based analyses.
BBTracer to collect a basic block coverage
trace of the execution of an instrumented program, make sure the main class
of the program can be found on your Java classpath. Then run the
java sofya.ed.BBTracer -<E|X|C|B> <classname>
The first parameter functions the same way as described for the instrumentor, where any combination of the given values can be specified. Only blocks of the selected types will be included in the generated trace file, where E specifies virtual entry blocks, X specifies virtual exit blocks, C specifies call blocks, and B specifies all other basic blocks. For performance reasons, the typical usage is to trace all of the block types for which instrumentation was inserted. However, this filtering capability provides the opportunity to instrument a program for multiple types of blocks and then select only the block types of interest to a particular analysis when collecting traces. Note that if a block type is requested that was not specified during instrumentation, information about those blocks will not appear in the generated trace.
classname argument should be the fully qualified name of
the main class for the program, and should not include the
By default, the tracer will create a file named "instout.tr" in the database directory which contains the trace information. Each time the tracer is run it will overwrite this file, unless otherwise specified (see below), so it is the responsibility of the user to store the file somewhere permanent, if desired. The trace file can be viewed using the TraceViewer.
The basic usage for the other tracers is essentially the same. In the case of the branch tracers, the branch types that can be selected are as follows:
throws" instructions, if any.
As with the basic block tracers, these options can be combined in any way.
There are additional options available for controlling the behavior of
the various tracers. The
classes will be used to describe these options. The same options apply
The full usage for
BBTracer is the following:
java sofya.ed.BBTracer [-port n] [-cp path] [-i] [-tl num_secs] [-at] [-o output_file] [-trname trace_name] -<E|X|C|B> <classfileName> <arguments>
Instructs the tracer to listen for the instrumentation connection on port number n.
Causes the tracer to set the CLASSPATH for the subject program to path.
Enables piping of
stdin to the subject
program. Programs requiring user input will deadlock if this option is not enabled.
Instructs the tracer to kill the subject after num_secs if it has not yet terminated. This option should be used instead of sending a kill signal to the tracer, as it enables the tracer to perform cleanup and generate the trace file for the subject program up to the point it was terminated.
Causes the tracer to append the current trace to the existing trace file of the same name, if it already exists.
Instructs the tracer to name the trace file trace_name. The .tr extension should be omitted.
Causes the tracer to redirect the subject program's output
to output_file. Both
stderr are redirected
to the specified file.
Specifies the block types to be included in the generated trace. All permutations are allowed.
An explaination of branch tracing report output resulting from using
sofya.ed.BranchTracer can be found in the
Branch Tracing Interpretation
section of the manual.
The sequence tracers are used to collect traces recording the full sequence of program entities executed during a program run, in the order observed. A program must be instrumented for sequence tracing to use this tracer; a program instrumented for coverage tracing will not work. This tracer produces a trace file in the database directory named "instout.seq" that is readable without the use of a viewer. These tracers provide the following additional options:
Causes the tracer to insert data at the start of the trace file, before any trace data.
Causes the tracer to append data at the end of the trace file, after any trace data.
Instructs the tracer to transmit the trace
-post data) through a socket
to the port used by a DAG builder to perform dynamic impact analysis.
Note that by default the
BBSequenceTracer writes entry
and exit block events to the trace file in a format specifically
designed for use in a particular type of DAG construction for impact
analysis. New filters can be written to generate trace files in other
formats. Finally, be aware that the trace files generated by this tracer can
be extremely large.