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

[Expand]
Inherited Constants
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.
public IDexDecompilerUnit decomp Managing dex decompiler.
public IDexUnit dex Underlying dex code.
public IDFA3<IDInstruction, BasicBlock<IDInstruction>> dfa The data flow analysis object is initially UNINITIALIZED.
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.
Set<String> getTags()
Get the optimizer tags.
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 addTag(String tag)
IDFA3<IDInstruction, BasicBlock<IDInstruction>> analyzeChains()
Retrieve and set the dfa field, a data flow analysis object for cfg.
IDFA3<IDInstruction, BasicBlock<IDInstruction>> analyzeChains(boolean redo)
Retrieve and set the dfa field, a data flow analysis object for cfg.
void checkInterrupted()
Verify if an interruption request was made by the managing decompiler.
int cleanGraph()
Perform clean-up after a change in CFG structure.
int cleanGraph(boolean doRemoveUnreachableBlocks, boolean doSimplifyJCondsAndSwitches)
Perform clean-up after a change in CFG structure.
boolean deleteUnreachableTrampoline(BasicBlock<IDInstruction> b)
This method is deprecated. use removeUnreachableTrampoline(CFG, BasicBlock)
boolean removeInstruction(BasicBlock<IDInstruction> b, int idx)
This method is deprecated. use removeInstruction(BasicBlock, int)
void removeTag(String tag)
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 IDFA3<IDInstruction, BasicBlock<IDInstruction>> dfa

The data flow analysis object is initially UNINITIALIZED. To initialize one, call analyzeChains(boolean).

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.

Parameters
_ctx an 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 Set<String> getTags ()

Get the optimizer tags. An optimizer may have 0, 1, or more tags. A tag is a non-null, non-empty string.

Returns
  • a collection of tags; may be empty (tags are optional), but never null

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 addTag (String tag)

protected IDFA3<IDInstruction, BasicBlock<IDInstruction>> analyzeChains ()

Retrieve and set the dfa field, a data flow analysis object for cfg.

Returns
  • the DFA, also available as a protected field dfa

protected IDFA3<IDInstruction, BasicBlock<IDInstruction>> analyzeChains (boolean redo)

Retrieve and set the dfa field, a data flow analysis object for cfg.

Parameters
redo if true, a new object will be generated; otherwise, a previously generated DFA object may be returned
Returns
  • the DFA, also available as a protected field dfa

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 ()

Perform clean-up after a change in CFG structure. This method will remove unreachable blocks and simplify conditional jumps and switches.

Returns
  • the number of clean-up operations performed

protected int cleanGraph (boolean doRemoveUnreachableBlocks, boolean doSimplifyJCondsAndSwitches)

Perform clean-up after a change in CFG structure. Convenience method.

Parameters
doRemoveUnreachableBlocks if true, will call removeUnreachableBlocks(IDMethodContext)
doSimplifyJCondsAndSwitches if true, will call simplifyJCondsAndSwitches(IDMethodContext)
Returns
  • the number of clean-up operations performed

protected boolean deleteUnreachableTrampoline (BasicBlock<IDInstruction> b)

This method is deprecated.
use removeUnreachableTrampoline(CFG, BasicBlock)

Remove an unreachable trampoline block (ending on a JCOND or JUMP).

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
Returns
  • true if the block was removed

protected boolean removeInstruction (BasicBlock<IDInstruction> b, int idx)

This method is deprecated.
use removeInstruction(BasicBlock, int)

Remove an instruction in a block. Throws on error (watch out: the boolean return value does not indicate failure).

Parameters
b basic block
idx index of the instruction to remove in this block
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 removeTag (String tag)

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