Patrick Lam (plam@sable.mcgill.ca)
Feng Qian (fqian@sable.mcgill.ca)
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, give an alternate implementation of soot.PackAdjuster which modifies Packs as needed. If you include this PackAdjuster in your CLASSPATH before the default implementation, yours will be called by Java instead of Soot's do-nothing implementation..
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.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. There are no transformations in this pack in an unmodified version of Soot.
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.
Phase name | wjop.smb |
Class name | soot.jimple.toolkits.invoke.StaticMethodBinder |
Static method binding uses an InvokeGraph to statically bind monomorphic call sites. That is, smb takes a whole application and an InvokeGraph; if the InvokeGraph 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 takes an InvokeGraph and visits all callsites in the application in a bottom-up fashion, inlining invoke statments which the InvokeGraph declares to be monomorphic. Note that the modifier ``static'' is supposed to be compared to a (not-currently- implemented) profile-guided inliner.
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 99.2beta6 (1.42)
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 foo
The translation was initiated by Patrick LAM on 2000-03-16