Patrick Lam (plam@sable.mcgill.ca)
Feng Qian (fqian@sable.mcgill.ca)
April 26, 2002
Soot supports the powerful, but initially confusing, notion of ``phase options''. This document will permit the reader to successfully use the Soot phase options.
Soot's execution is divided into a number of phases. Building the JimpleBody is a phase (called jb), and it has a number of subphases, like aggregation of stack variables (jb.asv).
Soot allows the user to specify options for each phase; these options will change the behaviour of the phase. This is specified by giving Soot the command-line option -p phase.name option:value. For instance, to instruct Soot to use original names in Jimple, we would invoke Soot like this:
[plam@cannanore test] java soot.Main foo -p jb use-original-names
Unless specified otherwise, all options are boolean; allowed values are ``true'' or ``false''. When an option is omitted, the default value is ``false''; specifying an option without a value is the same as saying ``true''.
All transformers accept the option ``disabled'', which, when set to true, causes the given transformer to not execute.
Soot transformers are expected to be classes extending either BodyTransformer or SceneTransformer. In either case, an internalTransform method on the transformer must be overridden to provide an implementation which carries out some transformation.
These transformers belong to a Pack. The Pack keeps a collection of transformers, and can execute them, in order, when called. To add a transformer to some Pack without modifying Soot itself, create your own class, which modifies the Packs as needed and then calls soot.Main.
The remainder of this document describes the various transformations belonging to the various Packs in Release 1 of Soot.
This phase is active during JimpleBody creation; Soot will always start by creating JimpleBody's from a method source - either coffi, for reading .class files, or the jimple parser, for reading .jimple files.
Phase name | jb |
Class name | soot.jimple.JimpleBody |
Phase name | jb.asv |
Class name | soot.jimple.toolkits.base.Aggregator |
This phase handles the aggregation of stack variables for Jimple. For a full description of aggregation, see [VRGH$^+$00]. Briefly, aggregation finds instances where some expression has a single use; it replaces the use with the expression itself.
This phase is deactivated by the `no-aggregating' option in the jb phase.
Phase name | jb.ulp |
Class name | soot.toolkits.scalar.LocalPacker |
This phase only executes when the `use-original-names' option is chosen for the `jb' phase. It unsplits the locals according to the original names found for them.
Phase name | jb.lns |
Class name | soot.jimple.toolkits.scalar.LocalNameStandardizer |
This phase assigns standard names to local variables. It only executes when `use-original-names' is not chosen.
Phase name | jb.cp |
Class name | soot.jimple.toolkits.scalar.CopyPropagator |
This phase provides a cascaded copy propagator. It is executed only when `no-cp' is not chosen in the `jb' phase.
If it encounters situations of the form: A: a = ...; B: ... x = a; C:... use (x); where a has only one definition, and x has only one definition (B), then it can propagate immediately without checking between B and C for redefinitions of a (namely A) because they cannot occur. In this case the propagator is global.
Otherwise, if a has multiple definitions then it only checks for redefinitions of constants and copies in extended basic blocks.
From bytecode, we get some number of declared locals; we call these ``regular locals''. In Jimple, we have converted the stack elements to locals. The new locals thus introduced are called ``stack locals''. These locals have names which usually begin with $.
The default behaviour in this phase is to propagate only on the `stack' locals.
Phase name | jb.dae |
Class name | soot.jimple.toolkits.scalar.DeadAssignmentEliminator |
This phase eliminates assignment statements (to locals) with no uses.
When Soot is given the -O command-line option, the JimpleOptimizationPack is applied to every JimpleBody in an application class. This section lists the default transformations in the JimpleOptimizationPack.
Phase name | jop.cse |
Class name | soot.jimple.toolkits.scalar.NaiveCommonSubexpressionElimination |
Runs an available expressions analysis on a body, then eliminates common subexpressions.
This implementation is especially slow, as it does not run on basic blocks. A better implementation (which wouldn't catch every single common subexpression, but would get most) would use basic blocks instead.
It is also slow because the flow universe is explicitly created; it need not be. A better implementation would implicitly compute the kill sets at every node.
Because of the current slowness, this transformation is not enabled in the default settings. To enable it, specify -p jop.cse disabled:false on the command line.
Phase name | jop.bcm |
Class name | soot.jimple.toolkits.scalar.pre.BusyCodeMotion |
Busy Code Motion is a straightforward implementation of Partial Redundancy Elimination. This implementation is not very aggressive. The Lazy Code Motion, described in section 3.3 is an improved version of the Busy Code Motion, and should be used instead of it.
Busy Code Motion is not enabled by default. To enable it, specify -p jop.bcm disabled:false on the command line.
Phase name | jop.lcm |
Class name | soot.jimple.toolkits.scalar.pre.LazyCodeMotion |
Lazy Code Motion is the enhanced version of the Busy Code Motion, a Partial Redundancy Eliminator. Before doing Partial Redundancy Elimination, this optimization performs loop inversion (turning while loops into do while loops inside an if statement). This allows the Partial Redundancy Eliminator to optimize loop invariants of while loops.
By default, this transformation is disabled. To enable it, specify -p jop.lcm disabled:false on the command line.
Phase name | jop.cp |
Class name | soot.jimple.toolkits.scalar.CopyPropagator |
See section 1.4 for a description of copy propagation.
The default behaviour here is to propagate on all locals.
Phase name | jop.cpf |
Class name | soot.jimple.toolkits.scalar.ConstantPropagatorAndFolder |
This phase does constant propagation and folding. Constant folding is the compile-time evaluation of constant expressions (i.e. 2 * 3).
Phase name | jop.cbf |
Class name | soot.jimple.toolkits.scalar.ConditionalBranchFolder |
Statically evaluates the condition-expression of Jimple IfStmts. If the condition is identically `true' or `false', changes the conditional branch instruction to a `goto' statement.
Phase name | jop.dae |
Class name | soot.jimple.toolkits.scalar.DeadAssignmentEliminator |
This phase eliminates assignment statements (to locals) with no uses. See section 1.5.
In this incarnation, the default value for only-stack-locals is false.
Phase names | jop.uce1, jop.uce2 |
Class name | soot.jimple.toolkits.scalar.UnreachableCodeEliminator |
Removes unreachable codes and empty traps.
Phase name | jop.ubf1, jop.ubf2 |
Class name | soot.jimple.toolkits.scalar.UnconditionalBranchFolder |
Removes unnecessary `goto' statements from a JimpleBody.
If a GotoStmt's target is the next instruction, then it is removed. If a GotoStmt x's target is another GotoStmt, with target y, then x's target can be changed to y's target.
If some IfStmt's target is a GotoStmt, then the IfStmt's target can be updated to the GotoStmt's target.
(These situations could result from other optimizations; after folding branches, we might generate more unreachable code.)
Phase name | jop.ule |
Class name | soot.jimple.toolkits.scalar.UnusedLocalEliminator |
Removes locals with no uses in the method body.
In whole-program mode, Soot will always apply the contents of the Whole-Jimple transformation pack to each method under analysis. This occurs after all Jimple bodies have been created. This pack is called wjtp. In an unmodified version of Soot, the only transformation in wjtp is the Spark pointer analysis kit. Spark has many options, which are listed at http://www.sable.mcgill.ca/soot/tutorial/phase-options/spark.ps.
To run optimizing transformations on the whole program, use the -W command-line option. This tells Soot that the whole-jimple optimization pack is to be applied (phase name wjop).
The default behaviour of this Pack has static method binding disabled and static inlining enabled. To reverse this, give the options -p wjop.smb disabled:false -p wjop.si disabled.
By default, static method binding and static inlining uses Class Hierarchy Analysis (CHA) to identify monomophic call sites. Changing the VTA-passes option can cause them to use Variable-Type Analysis (VTA) once or several times rather than CHA.
Phase name | wjop.smb |
Class name | soot.jimple.toolkits.invoke.StaticMethodBinder |
Static method binding uses CHA or VTA to statically bind monomorphic call sites. That is, smb takes the call graph returned by CHA or VTA; if the analysis result shows that any virtual invoke statement in the Jimple bodies actually only calls one method, then a static copy of the method is made, and the virtual invoke is changed to a static invoke.
Phase name | wjop.si |
Class name | soot.jimple.toolkits.invoke.StaticInliner |
The StaticInliner talkes an call graph returned by CHA or VTA and visits all call sites in the application in a bottom-up fashion, inlining invoke statements which is determined to be monomorphic by analysis result. Note that the modifier ``static'' is supposed to be compared to a (not-currently-implemented) profile-guided inliner.
The null pointer check analysis has the phase name jtp.npc. It has one phase option (aside from the default disabled option).
This is not a phase in the same sense as the others; notably, it does not belong to any Pack.
Phase name | Jimple.JasminClass |
Class name | soot.jimple.JasminClass |
This class is used in the generation of a jasmin file from a SootClass containing either Jimple or Grimp bodies.
For more detail about peepholes, see [VRGH$^+$00].
This document was generated using the LaTeX2HTML translator Version 2K.1beta (1.48)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html phase-options -split 0 -nonavigation -dir ./
The translation was initiated by Ondrej LHOTAK on 2002-06-13