public abstract class

AbstractDOptimizer

extends AbstractPlugin
implements IDOptimizer
java.lang.Object
   ↳ com.pnfsoftware.jeb.core.AbstractPlugin
     ↳ com.pnfsoftware.jeb.core.units.code.android.ir.AbstractDOptimizer

Class Overview

Base class for dexdec (DEX decompiler) IR optimizer plugins. Those plugins can access and modify the intermediate representation of a method or group of methods being decompiled. They can be used to implement a wide range of optimizations, from trivial code clean-up to the most complex deobfuscation passes. Internally, dexdec uses IR optimizers to perform dead-code removal, variable substitutions, immediate propagation, restructuring, constant folding, arithmetic operation simplifications, deobfuscations such as control-flow unflattening, etc.

Optimizers are usually managed by master optimizers (also called orchestrators). Third-party optimizer plugins can be automatically registered when creating an orchestrator. Refer to createMasterOptimizer.

Life-cycle information:
- plugins are reused (i.e. the perform() method is called multiple times)
- thread-safety:
-- Python script plugins must be thread-safe: a plugin instance may be executed by multiple threads concurrently
-- Java plugins (including Java script plugins) are not required to be thread-safe: a plugin instance will not be executed by multiple threads concurrently

Summary

Fields
public CFG<IDInstruction> cfg Target method's IR CFG, set up for convenience (see getCfg())
public IDMethodContext ctx Target method's IR context
public List<IDMethodContext> ctxlist If the optimizer is a regular method optimizer (an optimizer targeting a single method), this field is null.
public IDexDecompilerUnit decomp Managing dex decompiler.
public IDexUnit dex Underlying dex code.
public Map<IDInstruction, Map<Integer, List<Integer>>> dict_du_chains DFA chain: simple def-use chains, holding block indices.
public Map<IDInstruction, Map<Integer, List<IDInstruction>>> dict_full_du_chains DFA chain: full def-use chains, holding instruction refs.
public Map<IDInstruction, Map<Integer, List<IDInstruction>>> dict_full_ud_chains DFA chain: full use-def chains, holding instruction refs.
public Map<IDInstruction, Map<Integer, List<Integer>>> dict_ud_chains DFA chain: simple use-def chains, holding block indices.
public IDGlobalContext g IR global context.
public static final ILogger logger Public logger accessible by the implementing optimizer.
public IJavaOperatorFactory of IR/AST operation factory reference (for convenience).
public IJavaTypeFactory tf IR/AST type factory reference (for convenience).
Public Constructors
AbstractDOptimizer()
Create a standard optimizer.
AbstractDOptimizer(DOptimizerType type)
Create an optimizer.
AbstractDOptimizer(DOptimizerType type, boolean collectionOptimizer)
Create an optimizer for a method or collection of methods.
AbstractDOptimizer(DOptimizerType type, String name)
Create an optimizer.
Public Methods
void assignLocalFields(IDMethodContext _ctx)
This convenience method can be used to assign the object's attributes (e.g.
String getName()
Retrieve the plugin name.
EditablePluginInformation getPluginInformation()
Retrieve basic information about the plugin, such as name, version, author, and organization.
double getPriority()
Get the optimizer priority.
DOptimizerType getType()
Get the optimizer type.
boolean isCollectionOptimizer()
Determine whether this optimizer performs on a single method or an a collection of methods.
boolean isEnabled()
Determine whether the optimizer is enabled or not.
abstract int perform()
An optimizer must implement this method.
final int perform(IDMethodContext ctx)
Run the optimizer on the provided target method.
final int performOnCollection(List<IDMethodContext> ctxlist)
Run the optimizer on the provided collection of methods.
void resetLocalFields()
Reset this object's attributes.
void setEnabled(boolean enabled)
Enable or disable this optimizer.
Protected Methods
void analyzeChains(boolean redo)
void checkInterrupted()
Verify if an interruption request was made by the managing decompiler.
int cleanGraph()
int cleanGraph(boolean doRemoveUnreachableBlocks, boolean doSimplifyJCondsAndSwitches)
boolean deleteUnreachableTrampoline(BasicBlock<IDInstruction> b)
boolean removeInstruction(BasicBlock<IDInstruction> bb, int index0, boolean updateSimpleChains)
Remove an instruction in a block.
void setCollectionOptimizer(boolean collectionOptimizer)
Set the optimizer target category: single method (usual), or collection of methods.To be used by the constructor.
void setName(String name)
Set the optimizer name.
void setPriority(double priority)
Set the optimizer priority.
void setType(DOptimizerType type)
Set the optimizer type.
[Expand]
Inherited Methods
From class com.pnfsoftware.jeb.core.AbstractPlugin
From class java.lang.Object
From interface com.pnfsoftware.jeb.core.IPlugin
From interface com.pnfsoftware.jeb.core.units.code.android.ir.IDOptimizer

Fields

public CFG<IDInstruction> cfg

Target method's IR CFG, set up for convenience (see getCfg())

public IDMethodContext ctx

Target method's IR context

public List<IDMethodContext> ctxlist

If the optimizer is a regular method optimizer (an optimizer targeting a single method), this field is null.
If the optimizer is a class optimizer, ctx and cfg will be initially set to null, and this field contains the list of IR method contexts available to the optimizer.

public IDexDecompilerUnit decomp

Managing dex decompiler.

public IDexUnit dex

Underlying dex code.

public Map<IDInstruction, Map<Integer, List<Integer>>> dict_du_chains

DFA chain: simple def-use chains, holding block indices.
analyzeChains(boolean) must be called first to initialize this convenience field.

public Map<IDInstruction, Map<Integer, List<IDInstruction>>> dict_full_du_chains

DFA chain: full def-use chains, holding instruction refs.
analyzeChains(boolean) must be called first to initialize this convenience field.

public Map<IDInstruction, Map<Integer, List<IDInstruction>>> dict_full_ud_chains

DFA chain: full use-def chains, holding instruction refs.
analyzeChains(boolean) must be called first to initialize this convenience field.

public Map<IDInstruction, Map<Integer, List<Integer>>> dict_ud_chains

DFA chain: simple use-def chains, holding block indices.
analyzeChains(boolean) must be called first to initialize this convenience field.

public IDGlobalContext g

IR global context.

public static final ILogger logger

Public logger accessible by the implementing optimizer. Writing to the logger should be favored over writing directly to stdout.

public IJavaOperatorFactory of

IR/AST operation factory reference (for convenience).

public IJavaTypeFactory tf

IR/AST type factory reference (for convenience).

Public Constructors

public AbstractDOptimizer ()

Create a standard optimizer.

public AbstractDOptimizer (DOptimizerType type)

Create an optimizer.

public AbstractDOptimizer (DOptimizerType type, boolean collectionOptimizer)

Create an optimizer for a method or collection of methods.

public AbstractDOptimizer (DOptimizerType type, String name)

Create an optimizer.

Public Methods

public void assignLocalFields (IDMethodContext _ctx)

This convenience method can be used to assign the object's attributes (e.g. g, ctx, cfg, etc.) from the values of the provided IR context.

public String getName ()

Retrieve the plugin name. Should be consistent with the value returned by getPluginInformation().getName().

public EditablePluginInformation getPluginInformation ()

Retrieve basic information about the plugin, such as name, version, author, and organization.

Returns
  • the plugin information

public double getPriority ()

Get the optimizer priority. A higher value means a higher priority. Priorities are used by optimizer orchestrators to determine in which order optimizers should be executed.

Returns
  • the default priority

public DOptimizerType getType ()

Get the optimizer type. Types are used by optimizer orchestrators to determine whether an optimizer should run.

public boolean isCollectionOptimizer ()

Determine whether this optimizer performs on a single method or an a collection of methods.

public boolean isEnabled ()

Determine whether the optimizer is enabled or not. This method is used by optimizer orchestrators to determine whether an optimizer can be scheduled for execution.

Returns
  • true if this optimizer is enabled

public abstract int perform ()

An optimizer must implement this method. This method is called by a master optimizer to perform the optimization on the selected target.

Note that the optimizer is responsible for returning a legal method context, e.g.: the method IR instructions must be consistent with the CFG; the CFG must adhere to certain rules (see cleanGraph); if the data flow analysis is no longer valid, it should be invalidated (see resetDFA); etc.

Returns
  • the number of optimizations performed, 0 if none

public final int perform (IDMethodContext ctx)

Run the optimizer on the provided target method.

For this method to be called by an orchestrator, isCollectionOptimizer() must return false.

Parameters
ctx a method context
Returns
  • number of optimizations performed

public final int performOnCollection (List<IDMethodContext> ctxlist)

Run the optimizer on the provided collection of methods.

For this method to be called by an orchestrator, isCollectionOptimizer() must return true.

Parameters
ctxlist a collection of method contexts
Returns
  • number of optimizations performed

public void resetLocalFields ()

Reset this object's attributes. Same as assignLocalFields(null).

public void setEnabled (boolean enabled)

Enable or disable this optimizer. This flag is checked by a master optimizer.

Protected Methods

protected void analyzeChains (boolean redo)

protected void checkInterrupted ()

Verify if an interruption request was made by the managing decompiler. This method may be called when potentially length computations are performed in a loop.

protected int cleanGraph ()

protected int cleanGraph (boolean doRemoveUnreachableBlocks, boolean doSimplifyJCondsAndSwitches)

protected boolean deleteUnreachableTrampoline (BasicBlock<IDInstruction> b)

Parameters
b the block must be an unreachable (no input) trampoline (single-instruction jump/jcc); if the block is the first block in the CFG, the method will fail

protected boolean removeInstruction (BasicBlock<IDInstruction> bb, int index0, boolean updateSimpleChains)

Remove an instruction in a block. Throws on error (the boolean return value does not indicate failure, be careful).

Parameters
bb input basic block
index0 index of the instruction to remove in this block
updateSimpleChains if true, simple chains are updated; all other chain information remain remain stale
Returns
  • true if the instruction was truly removed, false if it was removed and replaced by an unconditional jump to avoid creating an empty block

protected void setCollectionOptimizer (boolean collectionOptimizer)

Set the optimizer target category: single method (usual), or collection of methods.To be used by the constructor.

Parameters
collectionOptimizer true for a collection optimizer; false otherwise

protected void setName (String name)

Set the optimizer name. To be used by the constructor.

Parameters
name if null, a name will be auto-generated

protected void setPriority (double priority)

Set the optimizer priority. To be used by the constructor.

Parameters
priority the new priority (high means higher priority). When optimizers are managed and run by an orchestrator, the optimizers with a higher priority are run before those having a lower priority. The default priority is 0.

protected void setType (DOptimizerType type)

Set the optimizer type. To be used by the constructor.

Parameters
type if null, a standard optimizer is assumed