public interface

IEStatement

implements IResizableInstruction IEGeneric
com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStatement
Known Indirect Subclasses

Class Overview

Base class for all IR statements. Statements are specialized expressions. The most common statement is IEAssign. Additional statements introduced as the IR gets optimized and refined are: IENop, IECall, IEReturn, IEJump, and IEJumpFar, IESwitch and the almighty IEUntranslatedInstruction.

Summary

Constants
int FLAG_LIKELY_EPILOGUE This instruction has been identified as being part of an epilogue stub.
int FLAG_LIKELY_PROLOGUE This instruction has been identified as being part of a prologue stub.
int FLAG_OPT_BLOCK_PROPAGATION Statement having this flag cannot be propagated, i.e.
int FLAG_OPT_BLOCK_SUBSTITUTIONS Statement having this flag cannot be the recipient of substituted expressions propagated by an expression optimizer.
Public Methods
abstract void addLowerLevelAddress(long address)
Add another native instruction address mapping to this IR statement.
abstract void addLowerLevelAddresses(Collection<Long> addresses)
Add a collection of native instructions addresses mapping to this IR statement.
abstract IEAssign asAssign()
abstract IECall asCall()
abstract IEJump asJump()
abstract IEJumpFar asJumpFar()
abstract IENop asNop()
abstract IEReturn asReturn()
abstract IESwitch asSwitch()
abstract IEUntranslatedInstruction asUntranslated()
abstract void collectSubExpressions(Collection<IEGeneric> sink, Boolean usedOnly)
Perform a shallow collection of the sub-expressions of this statement.
abstract void collectSubExpressions(Collection<IEGeneric> sink)
Perform a shallow collection of the sub-expressions of this expression.
abstract void collectUsedExpressions(Collection<Couple<IEGenericIEGeneric>> sink)
Perform a shallow collection of the first-level expressions used by this statement.
abstract void copyLowerLevelAddresses(IEStatement srcStm)
Copy (add) the native addresses of the instruction to this statement's mapping.
abstract void copyProperties(IEStatement srcStm)
Copy over the generic statement properties of the source statement onto this statement.
abstract boolean equalsEx(Object obj, boolean includeType, boolean includeContext, boolean includeSize)
Same as #equals() with the possibility to exclude some properties from the comparison.
abstract boolean equalsEx(Object obj, boolean includeType, boolean includeContext)
Same as #equals() with the possibility to exclude some properties from the comparison.
abstract ICStatement generateC(IERoutineContext ectx, ICMethod cctx)
Generate the C abstract syntax tree portion for this expression.
abstract IERoutineContext getContext()
Get the decompiled routine context that owns this statement.
abstract void getDefUse(EDefUseInfo defuse)
A variant of getDefUse(java.util.List, java.util.List, Object) used to retrieve the range of vbits defined and used by the statement.
abstract EDefUseInfo getDefUseInfo(long instructionAddress, int flags)
Determine the variables defined and used by the instruction.
abstract Collection<Long> getLowerLevelAddresses()
abstract Long getPrimaryLowerLevelAddress()
abstract Integer getSPDelta()
Retrieve the optional stack-pointer delta indicator.
abstract boolean isAssign()
abstract boolean isAssignTo(int dstVarid)
abstract boolean isAssignTo(IEVar dst)
abstract boolean isAssignToVar()
abstract boolean isCall()
abstract boolean isConditionalJump()
Determine if this IR is a conditional IEJump, i.e.
abstract boolean isConditionalJumpFar()
abstract boolean isJump()
abstract boolean isJumpFar()
abstract boolean isNop()
abstract boolean isReturn()
abstract boolean isSwitch()
abstract boolean isUnconditionalJump()
Determine if this IR is a simple goto, that is, an unconditional IEJump, i.e.
abstract boolean isUnconditionalJumpFar()
abstract boolean isUntranslatedInstruction()
abstract void postUpdateTypes(ETypeInfo ti)
Called once by the normalizer component in later stages.
abstract void preUpdateTypes(ETypeInfo ti)
Called once by the type setter component during the typing stage, before propagating all types to the IR elements.
abstract void removeLowerLevelAddress(long address)
Remove a native instruction address from the list of mappings.
abstract int replaceDefinedVar(IEVar var, IEGeneric repl)
Replace (deep) the variables that are defined by this statement.
abstract int replaceUsedVar(IEVar var, IEGeneric repl)
Replace (deep) the variables that are defined by this statement.
abstract int replaceVar(IEVar var, IEGeneric repl, boolean doNotReplaceDefinedVariables)
Deep replace.
abstract void resetLowerLevelAddress()
Reset the current mapping for native instruction addresses for this statement.
abstract void resetLowerLevelAddresses()
Reset the current mapping for native instruction addresses for this statement.
abstract void setLowerLevelAddress(long address)
Reset the current mapping and add a single native instruction address mapping to this IR statement.
abstract void setLowerLevelAddresses(Collection<Long> addresses)
Reset the current mapping and add a collection of native instructions addresses mapping to this IR statement.
abstract void setPrimaryLowerLevelAddress(long addr)
abstract void setSPDelta(Integer delta)
Set an optional stack-pointer delta indicator.
abstract boolean visitInstruction(IEVisitor visitor)
Depth-first search, pre-order visit of this statement.
abstract boolean visitInstruction(IEVisitor visitor, boolean skipAssignmentDestination)
Depth-first search, pre-order visit of this statement.
abstract boolean visitInstructionPostOrder(IEVisitor visitor, boolean skipAssignmentDestination)
Depth-first search, post-order visit of this statement.
abstract IEStatement withLowerLevelAddress(long address)
abstract IEStatement withLowerLevelAddresses(Collection<Long> addresses)
abstract boolean writesMemory()
Retrieve an indication regarding whether this statement writes to memory.
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.core.units.code.IInstruction
From interface com.pnfsoftware.jeb.core.units.code.IInstructionOperand
From interface com.pnfsoftware.jeb.core.units.code.IResizableInstruction
From interface com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric

Constants

public static final int FLAG_LIKELY_EPILOGUE

This instruction has been identified as being part of an epilogue stub.

A routine's epilogue is a small instruction stub responsible for restoring registers previously saved by the prologue as well as freeing space that may have been allocated on the stack.

Constant Value: 8 (0x00000008)

public static final int FLAG_LIKELY_PROLOGUE

This instruction has been identified as being part of a prologue stub.

A routine's prologue is a small instruction stub responsible for saving registers that need to be preserved as well as allocating some space on the stack.

Constant Value: 4 (0x00000004)

public static final int FLAG_OPT_BLOCK_PROPAGATION

Statement having this flag cannot be propagated, i.e. they cannot be the source (replacement) expression in substituted expressions.

Note: even in aggressive mode, this flag is NOT ignored.

In the example below, r0 in instruction A will not be propagated to B.

 A) r0 = r1      <---- flagged
 ...
 B) r4 = .... + r0 + ...
 

Constant Value: 1 (0x00000001)

public static final int FLAG_OPT_BLOCK_SUBSTITUTIONS

Statement having this flag cannot be the recipient of substituted expressions propagated by an expression optimizer.

Note: even in aggressive mode, this flag is NOT ignored.

In the example below, r0 in instruction A could be (under conditions) substituted in instruction B. However, if instruction B has FLAG_OPT_BLOCK_SUBSTITUTIONS set, that candidate substitution will be prevented, regardless of other factors.

 A) r0 = r1
 ...
 B) r4 = .... + r0 + ...      <---- flagged
 
Note that this flag does not prevent the statement itself to be the source of a substitution. (To prevent that, use FLAG_OPT_BLOCK_PROPAGATION.)

In the example below, r0 of A can be propagated to B (with A ending up discarded), even though A is flagged.

 A) r0 = r1                   <---- flagged
 ...
 B) r4 = .... + r0 + ...
 

Constant Value: 2 (0x00000002)

Public Methods

public abstract void addLowerLevelAddress (long address)

Add another native instruction address mapping to this IR statement.

public abstract void addLowerLevelAddresses (Collection<Long> addresses)

Add a collection of native instructions addresses mapping to this IR statement.

public abstract IEAssign asAssign ()

public abstract IECall asCall ()

public abstract IEJump asJump ()

public abstract IEJumpFar asJumpFar ()

public abstract IENop asNop ()

public abstract IEReturn asReturn ()

public abstract IESwitch asSwitch ()

public abstract IEUntranslatedInstruction asUntranslated ()

public abstract void collectSubExpressions (Collection<IEGeneric> sink, Boolean usedOnly)

Perform a shallow collection of the sub-expressions of this statement. All collected expressions are directly rooted in this IRE (i.e. their parent is this IR expression).

Parameters
sink recipient (elements are appended)
usedOnly if null: all top-level elements are collected (same as collectSubExpressions(Collection)); else:
- if false: only defined (written) top-level sub-expressions are collected
- if true: only used (read) top-level sub-expressions are collected

public abstract void collectSubExpressions (Collection<IEGeneric> sink)

Perform a shallow collection of the sub-expressions of this expression. All collected expressions are directly rooted in this IRE (i.e. their parent is this IR expression).

This method appends to the provided sink (existing elements are not cleared). The current element (this) is not appended; only the sub-expressions are considered.

public abstract void collectUsedExpressions (Collection<Couple<IEGenericIEGeneric>> sink)

Perform a shallow collection of the first-level expressions used by this statement. Invoking this method is not the same as calling collectSubExpressions(sink, true)! This method examines top-level defined (written) expressions that are EMem; the memory reference of those EMems are returned. Therefore, not all values returned by this method are directly rooted in this IRE. It is for that reasons that this method returns a collection of tuples (parent, expression) instead of a simple collection of expressions.

Parameters
sink a collection of tuples (parent, expression)

public abstract void copyLowerLevelAddresses (IEStatement srcStm)

Copy (add) the native addresses of the instruction to this statement's mapping. Watch out! The current statement's mapping is not reset before copying.

public abstract void copyProperties (IEStatement srcStm)

Copy over the generic statement properties of the source statement onto this statement. Only generic (common) properties should be ported. The context is not copied over. Some properties are overwritten, others are completed (augmented).

Parameters
srcStm source statement

public abstract boolean equalsEx (Object obj, boolean includeType, boolean includeContext, boolean includeSize)

Same as #equals() with the possibility to exclude some properties from the comparison.

Parameters
obj object to compare
includeType true to include the type in the equality test
includeContext true to include the statement's bound IR context in the equality check
includeSize true to include the statement's size in the equality check
Returns
  • true if equal

public abstract boolean equalsEx (Object obj, boolean includeType, boolean includeContext)

Same as #equals() with the possibility to exclude some properties from the comparison.

Parameters
obj object to compare
includeType true to include the type in the equality test
includeContext true to include the statement's bound IR context in the equality check
Returns
  • true if equal

public abstract ICStatement generateC (IERoutineContext ectx, ICMethod cctx)

Generate the C abstract syntax tree portion for this expression.

Parameters
ectx IR routine context
cctx C routine local context
Returns
  • the C AST element (may contain sub-elements)

public abstract IERoutineContext getContext ()

Get the decompiled routine context that owns this statement.

public abstract void getDefUse (EDefUseInfo defuse)

A variant of getDefUse(java.util.List, java.util.List, Object) used to retrieve the range of vbits defined and used by the statement.

public abstract EDefUseInfo getDefUseInfo (long instructionAddress, int flags)

Determine the variables defined and used by the instruction. This method is an extended version of getDefUse(List, List, Object).@return

Parameters
instructionAddress address of the instruction
flags see DefUseInfo.XXX static final flags

public abstract Collection<Long> getLowerLevelAddresses ()

Returns
  • the returned collection does not contain duplicates; the first entry is the primary lower-level address (if there are multiple native addresses mapping to this IR statement, getLowerLevelAddresses() would return 2+ entries)

public abstract Long getPrimaryLowerLevelAddress ()

Returns
  • the primary native address; null if this IR does not contain lower-mapping information

public abstract Integer getSPDelta ()

Retrieve the optional stack-pointer delta indicator. The SP delta represents the native delta in bytes, relative to SP0 (stack pointer at the underlying native routine entry-point), before the closest matching native instruction is executed.

Returns
  • optional native SP delta

public abstract boolean isAssign ()

public abstract boolean isAssignTo (int dstVarid)

public abstract boolean isAssignTo (IEVar dst)

public abstract boolean isAssignToVar ()

public abstract boolean isCall ()

public abstract boolean isConditionalJump ()

Determine if this IR is a conditional IEJump, i.e. getCondition() is not null.

public abstract boolean isConditionalJumpFar ()

public abstract boolean isJump ()

public abstract boolean isJumpFar ()

public abstract boolean isNop ()

public abstract boolean isReturn ()

public abstract boolean isSwitch ()

public abstract boolean isUnconditionalJump ()

Determine if this IR is a simple goto, that is, an unconditional IEJump, i.e. getCondition() is null.

public abstract boolean isUnconditionalJumpFar ()

public abstract boolean isUntranslatedInstruction ()

public abstract void postUpdateTypes (ETypeInfo ti)

Called once by the normalizer component in later stages. Implementations may perform IRE replacement, unlike updateTypes's.

Parameters
ti optional type information object that will collect the operation's result

public abstract void preUpdateTypes (ETypeInfo ti)

Called once by the type setter component during the typing stage, before propagating all types to the IR elements. Implementations may perform IRE replacement, unlike updateTypes's.

Parameters
ti optional type information object that will collect the operation's result

public abstract void removeLowerLevelAddress (long address)

Remove a native instruction address from the list of mappings.

public abstract int replaceDefinedVar (IEVar var, IEGeneric repl)

Replace (deep) the variables that are defined by this statement.

public abstract int replaceUsedVar (IEVar var, IEGeneric repl)

Replace (deep) the variables that are defined by this statement.

Parameters
var the IEVar to be replaced
repl the replacement expression
Returns
  • the number of replacements
Throws
IllegalIntermediateExpressionException if an illegal replacement was attempted

public abstract int replaceVar (IEVar var, IEGeneric repl, boolean doNotReplaceDefinedVariables)

Deep replace. Specialized version allows used-vars replacement only. The implementation is responsible for IRE duplication before statements, to ensure that the resulting statement or group of statement does not contain duplicate references to mutable objects.

Parameters
var the IEVar to be replaced
repl the replacement expression
Returns
  • the number of replacements
Throws
IllegalIntermediateExpressionException if an illegal replacement was attempted

public abstract void resetLowerLevelAddress ()

Reset the current mapping for native instruction addresses for this statement.

public abstract void resetLowerLevelAddresses ()

Reset the current mapping for native instruction addresses for this statement.

public abstract void setLowerLevelAddress (long address)

Reset the current mapping and add a single native instruction address mapping to this IR statement. Watch out! A statement should at least have one associated native address.

public abstract void setLowerLevelAddresses (Collection<Long> addresses)

Reset the current mapping and add a collection of native instructions addresses mapping to this IR statement. Watch out! A statement should at least have one associated native address.

public abstract void setPrimaryLowerLevelAddress (long addr)

public abstract void setSPDelta (Integer delta)

Set an optional stack-pointer delta indicator. The SP delta represents the native delta in bytes, relative to SP0 (stack pointer at the underlying native routine entry-point), before the closest matching native instruction is executed.

Parameters
delta optional native SP delta

public abstract boolean visitInstruction (IEVisitor visitor)

Depth-first search, pre-order visit of this statement. The node being visited may be replaced, but the client code is responsible for EVisitResults#setReplacedNode(IEGeneric) notifying the visitor.

Pre-order visits offer more options than post order visits: the visitor may decide to skip children; to skip the destination of assignments. However, replacement of nodes requires additional code to register the new node. Conversely, post-order visits do not offer any specific option, but provide the simplest way to replace nodes.

Parameters
visitor the visitor object
Returns
  • true if the visit was successful

public abstract boolean visitInstruction (IEVisitor visitor, boolean skipAssignmentDestination)

Depth-first search, pre-order visit of this statement. The node being visited may be replaced, but the client code is responsible for EVisitResults#setReplacedNode(IEGeneric) notifying the visitor.

Pre-order visits offer more options than post order visits: the visitor may decide to skip children; to skip the destination of assignments. However, replacement of nodes requires additional code to register the new node. Conversely, post-order visits do not offer any specific option, but provide the simplest way to replace nodes.

Parameters
visitor the visitor object
skipAssignmentDestination true if the destination of an assignment (if this statement is an EAssign) should not be visited
Returns
  • true if the visit was successful

public abstract boolean visitInstructionPostOrder (IEVisitor visitor, boolean skipAssignmentDestination)

Depth-first search, post-order visit of this statement. The node being visited may be replaced without notifying the visitor.

Pre-order visits offer more options than post order visits: the visitor may decide to skip children; to skip the destination of assignments. However, replacement of nodes requires additional code to register the new node. Conversely, post-order visits do not offer any specific option, but provide the simplest way to replace nodes.

Parameters
visitor the visitor object
skipAssignmentDestination true if the destination of an assignment (if this statement is an EAssign) should not be visited
Returns
  • true if the visit was successful

public abstract IEStatement withLowerLevelAddress (long address)

public abstract IEStatement withLowerLevelAddresses (Collection<Long> addresses)

public abstract boolean writesMemory ()

Retrieve an indication regarding whether this statement writes to memory.