public interface

IERoutineContext

implements IOptimizerTarget
com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext

Class Overview

Routine (local) IR context. Every method being decompiled is having an associated IR context. The routine context is also a factory for local IR objects, such as IR statements.

Summary

Public Methods
abstract void acquireNativeItem(INativeItem t)
abstract boolean addNote(String note)
abstract CFG<IEStatement> buildCfg(List<IEStatement> statements, boolean subroutineCallNotBreaking, boolean assignToContext)
Build an IR-CFG from a list of statements.
abstract CFG<IEStatement> buildCfg(List<IEStatement> statements)
Build an IR-CFG using the provided list of statements, and set the resulting CFG as the current CFG for this converted routine.
abstract EState buildEmptyState()
Initialize a state to emulate this routine.
abstract Long convertIntermediateOffset(int offset)
Conversion FROM IR offset TO native address.
abstract Long convertNativeAddress(long address)
Conversion FROM native address to IR offset.
abstract EVarCopyFinder copyFinder(StorageEntry entry, Collection<Integer> filters, Long irOffset)
abstract IEVar copyPairOfVariables(IEVar lo, IEVar hi)
Create a copy variable for a pair of variable.
abstract Couple<IEVarIEVar> copyTruncatedVariable(IEVar var, int lowPartBitsize)
Create a truncated copy of a variable.
abstract IEVar copyVariable(IEVar var)
Create the copy of a variable.
abstract IEAssign createAssign(IEGeneric dst, IEGeneric src)
abstract IEAssign createAssignIf(IEAssign assignTpl, IEGeneric predicate)
abstract IEAssign createBranchAssign(IEGeneric dst, IEGeneric src, boolean subroutineCall)
abstract IECall createBuiltinMethodCall(String name, IEGeneric retexp, IEGeneric... argexps)
Create a Call to a built-in method reference.
abstract IECall createCall(IEGeneric callsite, IEGeneric retloc, List<IEGeneric> returns, List<IEGeneric> params, int stackPointerDelta, List<IEGeneric> spoiledExpressions, IWildcardPrototype prototype)
abstract IECall createCall(IEGeneric callsite, List<IEVar> targetCandidates, IWildcardPrototype prototype, List<IWildcardType> varArgTypes, boolean failsafePrototype)
abstract IECompose createCompose(Collection<IEGeneric> elts)
Create a composition.
abstract IECompose createCompose(IEGeneric... elts)
Create a composition.
abstract IECond createCond(IEGeneric p, IEGeneric a, IEGeneric b)
abstract IEOperation createConversionOperation(OperationType convOperator, IEGeneric src, int dstSize)
Create a conversion operation: an integer truncation, integer extension (zero or signed), float truncation or extension, float-to-int and int-to-float conversion.
abstract IEGroupElt createGroupElt(IEGroup collection, IEGeneric index)
abstract IEImm createImm(double v)
abstract IEImm createImm(long v, int bitsize)
abstract IEImm createImm(BigInteger v, int bitsize)
abstract IEImm createImm(float v)
abstract IEImm createImm(byte[] v, int bitsize)
abstract IEImm createImm(String v, int bitsize)
abstract IEJump createJump(int branchAddress, IEGeneric condition)
abstract IEJump createJump(int branchAddress)
abstract IEJumpFar createJumpFar(IEGeneric jumpSite, IEGeneric condition)
abstract IEJumpFar createJumpFar(IEGeneric jumpSite)
abstract IEMem createMem(IEGeneric segment, IEGeneric opaddr, int bitsize)
abstract IEMem createMem(IEGeneric opaddr, int bitsize)
abstract IENop createNop()
abstract IENop createNop(IEStatement template)
abstract IEOperation createOperation(FunctionOptype functionOptype, IEGeneric... opnds)
abstract IEOperation createOperation(OperationType optype, IEGeneric op1)
abstract IEOperation createOperation(OperationType optype, IEGeneric op1, IEGeneric op2)
abstract IEOperation createResizeOperation(IEGeneric opnd, int bitsize, boolean signed)
Create a resize operation operation: truncation, zero-extension, or sign-extension.
abstract IEReturn createReturn(IEGeneric value)
abstract IEReturn createReturn(List<IEGeneric> values)
abstract IEReturn createReturn()
abstract IEVar createStackReference(long stkVarOffset)
Retrieve or create a stack reference, ie a pointer to stack-memory variable.
abstract IEVar createStackReference(long stkVarOffset, IWildcardType type)
Retrieve or create a stack reference, ie a pointer to stack-memory variable.
abstract IESwitch createSwitch(IEGeneric controlExpression, int defaultAddress)
abstract IEVar createSymbolForField(INativeFieldItem variable)
abstract IEVar createSymbolForGlobalVariable(INativeDataItem variable)
abstract IEVar createSymbolForRoutine(INativeMethodItem routine)
abstract IEUntranslatedInstruction createUntranslatedInstruction(long nativeAddress, String nativeMnemonic, IEGeneric... irOperands)
abstract IEVar createVar(String name, int bitsize)
Create or retrieve a special routine-scope variable.
abstract IEVar createVirtualVar(String name, int bitsize)
Create or retrieve a virtual routine-scope variable.
abstract CFG<IEStatement> getCfg()
abstract IEConverter<?> getConverter()
abstract Set<Integer> getCopiesOfVariable(int id)
Get the set of all variables that are copies or partial copies of the provided input id.
abstract Set<Integer> getCopiesUsingVariable(int id)
Get the set of all variables making use of the provided variable.
abstract Object getData(Object key)
Retrieve a piece of transient data.
abstract INativeDecompilerContext getDecompiler()
Convenience method to retrieve a reference to the decompiler that owns this context.
abstract List<IEVar> getDuplicatesForRegister(int regId)
Retrieve the list of duplicates (mirror, secondary dups) associated to a register.
abstract IEGlobalContext getGlobalContext()
abstract IEGeneric getInputVariableForRegister(IDFA<IEStatement> dfa, long nativeRegId)
abstract IEGeneric getInputVariableForRegister(IDFA<IEStatement> dfa, IEVar reg)
abstract List<Long> getIntermediateOffsetsMappingToNativeAddress(long address)
abstract List<Long> getIntermediateOffsetsMappingToNativeAddresses(Collection<Long> addresses)
abstract Collection<IEVar> getMemoryVariables()
Retrieve the list of memory variables used by this context: stack variables and global variables.
abstract INativeContext getNativeContext()
abstract List<String> getNotes()
abstract IEGeneric getOutputVariableForRegister(IDFA<IEStatement> dfa, long exitAddress, int nativeRegId)
abstract IEGeneric getOutputVariableForRegister(IDFA<IEStatement> dfa, long exitAddress, IEVar reg)
abstract IEVar getProgramCounter()
Convenience method.
abstract int getProgramCounterId()
Convenience method.
abstract IWildcardPrototype getPrototype()
Convenience method.
abstract IEVar getRegisterMirror(IEVar reg)
Retrieve or create the mirror - that is, the first full copy, in the [IDL_MIRROR, IDL_MIRROR_END[ range - of the provided register.
abstract INativeMethodItem getRoutine()
abstract List<IEGeneric> getRoutineInputVariables()
Retrieve the IR expressions holding the routine's parameters.
abstract Collection<IEVar> getRoutineVariablesInRange(int idStart, int idEnd)
abstract VarSrc getSourceForVariable(int id)
abstract IEStackManager getStackManager()
Retrieve the manager for local IEVars representing physical stack variables (in the general sense, ie memory slots).
abstract IEVar getStackPointer()
Convenience method.
abstract int getStackPointerId()
Convenience method.
abstract IEVar getStackReference(long stkVarOffset)
Retrieve a stack reference, i.e.
abstract IEVar getStackVariable(int offset)
Retrieve the stack variable at the provided offset.
abstract Collection<IEVar> getStackVariables()
Retrieve the list of memory stack variables used by this context.
abstract Collection<IEVar> getStackVariables(int offsetStart, int offsetEnd)
Retrieve all defined stack variables whose (starting) offset are included in the provided range.
abstract List<IEStatement> getStatements()
Retrieve the raw list of converted IR-statements.
abstract Integer getUnderlyingRegisterId(int varid)
Retrieve the id of the underlying IEVar-register used to hold this variable.
abstract IEVar getVariableById(int id)
Retrieve a variable (routine-scope or global-scope) by id.
abstract IEVar getVariableByName(String name)
Retrieve a routine-scope variable by name.
abstract IWildcardTypeManager getWildcardTypeManager()
abstract void invalidateDataFlowAnalysis()
Invalidate all data flow analysis for the IR-CFG managed by this context.
abstract boolean isAllowUnsafeAnalysis()
abstract void log(String format, Object... args)
abstract void logUnsafeOpt(String format, Object... args)
abstract boolean removeNote(String note)
abstract IEVar removeStackReference(long stkVarOffset)
Remove a stack reference.
abstract IEGeneric retrieveVariableForRegister(IEGeneric reg, Collection<Integer> filters, boolean createIfNotFound)
abstract void setCfg(CFG<IEStatement> cfg)
abstract void setData(Object key, Object value)
Store a piece of transient data.
abstract void setPrototype(IWildcardPrototype prototype)
Convenience method.
abstract void setRoutine(INativeMethodItem routine)
abstract void setStatements(List<IEStatement> statements)
Set the converted list of raw IR-statements.
abstract void setStatements(List<IEStatement> statements, boolean verifyStatements, boolean replaceLeftAssignSlices, boolean buildCfg)
Set the converted list of raw IR-statements.
abstract void setTypeForSame(IEGeneric exp, IWildcardType type)
abstract boolean usesCopyVars()
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.core.units.code.asm.decompiler.opt.IOptimizerTarget

Public Methods

public abstract void acquireNativeItem (INativeItem t)

public abstract boolean addNote (String note)

public abstract CFG<IEStatement> buildCfg (List<IEStatement> statements, boolean subroutineCallNotBreaking, boolean assignToContext)

Build an IR-CFG from a list of statements. The first statement is the input statement. Note that the resulting CFG may not contain all provided IR statements; only reachable IR statements are present. The resulting CFG is gap-less.

Parameters
statements list of statements
subroutineCallNotBreaking if true, IECall-like statements do not necessarily break a basic block (to be used solely in latest pipeline stages)
Returns
  • a CFG; note that getCfg() is not updated; to update the CFG reference stored in this context, use setCfg()

public abstract CFG<IEStatement> buildCfg (List<IEStatement> statements)

Build an IR-CFG using the provided list of statements, and set the resulting CFG as the current CFG for this converted routine. The current conversion lists will be used.

Parameters
statements input list of IEStatements
Returns
  • the newly created CFG

public abstract EState buildEmptyState ()

Initialize a state to emulate this routine. The variables map is uninitialized.

public abstract Long convertIntermediateOffset (int offset)

Conversion FROM IR offset TO native address.

Parameters
offset IR offset
Returns
  • physical address or null on error

public abstract Long convertNativeAddress (long address)

Conversion FROM native address to IR offset. The IR offset is an int, but returned as a long to conveniently manipulate it with IInstruction.

Parameters
address physical address
Returns
  • IR offset or null on error

public abstract EVarCopyFinder copyFinder (StorageEntry entry, Collection<Integer> filters, Long irOffset)

public abstract IEVar copyPairOfVariables (IEVar lo, IEVar hi)

Create a copy variable for a pair of variable.

Not all variables can be copied. Currently, copies are limited to registers variables.

Parameters
lo an IEVar-register
hi an IEVar-register

public abstract Couple<IEVarIEVar> copyTruncatedVariable (IEVar var, int lowPartBitsize)

Create a truncated copy of a variable.

Not all variables can be copied. Currently, copies are limited to registers variables.

Parameters
var an IEVar-register
Returns
  • null on error, else, a tuple containing the copy variables: low part (truncated LSB), and high part (remainder MSB)

public abstract IEVar copyVariable (IEVar var)

Create the copy of a variable.

Not all variables can be copied. Currently, copies are limited to registers variables.

Parameters
var an IEVar-register
Returns
  • null on error, else, the copied variable

public abstract IEAssign createAssign (IEGeneric dst, IEGeneric src)

public abstract IEAssign createAssignIf (IEAssign assignTpl, IEGeneric predicate)

public abstract IEAssign createBranchAssign (IEGeneric dst, IEGeneric src, boolean subroutineCall)

public abstract IECall createBuiltinMethodCall (String name, IEGeneric retexp, IEGeneric... argexps)

Create a Call to a built-in method reference.

Parameters
name built-in method name, supported values: strcpy, memcpy, memset
retexp the optional return value
argexps the list of IR arguments
Returns
  • a call IR expression, null on error

public abstract IECall createCall (IEGeneric callsite, IEGeneric retloc, List<IEGeneric> returns, List<IEGeneric> params, int stackPointerDelta, List<IEGeneric> spoiledExpressions, IWildcardPrototype prototype)

public abstract IECall createCall (IEGeneric callsite, List<IEVar> targetCandidates, IWildcardPrototype prototype, List<IWildcardType> varArgTypes, boolean failsafePrototype)

public abstract IECompose createCompose (Collection<IEGeneric> elts)

Create a composition.

Parameters
elts at least two elements, from lowest-significant to highest-significant

public abstract IECompose createCompose (IEGeneric... elts)

Create a composition.

Parameters
elts at least two elements, from lowest-significant to highest-significant

public abstract IECond createCond (IEGeneric p, IEGeneric a, IEGeneric b)

public abstract IEOperation createConversionOperation (OperationType convOperator, IEGeneric src, int dstSize)

Create a conversion operation: an integer truncation, integer extension (zero or signed), float truncation or extension, float-to-int and int-to-float conversion.

Parameters
convOperator one of for which isConversion() returns true (eg, CAST, CAST_S, FP2FP, FP2INT, INT2FP)
src operand to be extended, truncated, or converted
dstSize resulting bitsize
Returns
  • the operation IRE

public abstract IEGroupElt createGroupElt (IEGroup collection, IEGeneric index)

public abstract IEImm createImm (double v)

public abstract IEImm createImm (long v, int bitsize)

public abstract IEImm createImm (BigInteger v, int bitsize)

public abstract IEImm createImm (float v)

public abstract IEImm createImm (byte[] v, int bitsize)

public abstract IEImm createImm (String v, int bitsize)

public abstract IEJump createJump (int branchAddress, IEGeneric condition)

public abstract IEJump createJump (int branchAddress)

public abstract IEJumpFar createJumpFar (IEGeneric jumpSite, IEGeneric condition)

public abstract IEJumpFar createJumpFar (IEGeneric jumpSite)

public abstract IEMem createMem (IEGeneric segment, IEGeneric opaddr, int bitsize)

public abstract IEMem createMem (IEGeneric opaddr, int bitsize)

public abstract IENop createNop ()

public abstract IENop createNop (IEStatement template)

public abstract IEOperation createOperation (FunctionOptype functionOptype, IEGeneric... opnds)

public abstract IEOperation createOperation (OperationType optype, IEGeneric op1)

public abstract IEOperation createOperation (OperationType optype, IEGeneric op1, IEGeneric op2)

public abstract IEOperation createResizeOperation (IEGeneric opnd, int bitsize, boolean signed)

Create a resize operation operation: truncation, zero-extension, or sign-extension.

Parameters
opnd the source to be extended (dstSize > srcSize) or truncated (dstSize < srcSize)
bitsize the destination size; should be different than the source's
signed for extensions, else N/A
Returns
  • the operation IRE

public abstract IEReturn createReturn (IEGeneric value)

public abstract IEReturn createReturn (List<IEGeneric> values)

public abstract IEReturn createReturn ()

public abstract IEVar createStackReference (long stkVarOffset)

Retrieve or create a stack reference, ie a pointer to stack-memory variable.

Parameters
stkVarOffset stack offset

public abstract IEVar createStackReference (long stkVarOffset, IWildcardType type)

Retrieve or create a stack reference, ie a pointer to stack-memory variable.

Parameters
stkVarOffset stack offset
type optional type

public abstract IESwitch createSwitch (IEGeneric controlExpression, int defaultAddress)

public abstract IEVar createSymbolForField (INativeFieldItem variable)

public abstract IEVar createSymbolForGlobalVariable (INativeDataItem variable)

public abstract IEVar createSymbolForRoutine (INativeMethodItem routine)

public abstract IEUntranslatedInstruction createUntranslatedInstruction (long nativeAddress, String nativeMnemonic, IEGeneric... irOperands)

public abstract IEVar createVar (String name, int bitsize)

Create or retrieve a special routine-scope variable. The variable id is in the [SPECIAL, SPECIAL_END] range.

Clients should avoid using this method. Non-stack routine-scope variables created by third-party code should generally be in the VIRTUAL range. See the createVirtualVar(String, int) method.

public abstract IEVar createVirtualVar (String name, int bitsize)

Create or retrieve a virtual routine-scope variable. The variable id is in the [VIRTUAL, VIRTUAL_END] range.

public abstract CFG<IEStatement> getCfg ()

public abstract IEConverter<?> getConverter ()

public abstract Set<Integer> getCopiesOfVariable (int id)

Get the set of all variables that are copies or partial copies of the provided input id. The input id may be of a copy variable itself, in which case, this method is equivalent as retrieving the copies of its source.

The copies returned is a list of vars entirely contained in the input var.

Parameters
id input id
Returns
  • a set of id, including self if it was a copy

public abstract Set<Integer> getCopiesUsingVariable (int id)

Get the set of all variables making use of the provided variable.

The copies returned is a list of vars whose overlap with the input var is non-null.

Parameters
id input id
Returns
  • a set of id, including self if it was a copy

public abstract Object getData (Object key)

Retrieve a piece of transient data.

public abstract INativeDecompilerContext getDecompiler ()

Convenience method to retrieve a reference to the decompiler that owns this context. That is, the decompiler that owns the IR converter that originally created this IR context).

Returns

public abstract List<IEVar> getDuplicatesForRegister (int regId)

Retrieve the list of duplicates (mirror, secondary dups) associated to a register.

Parameters
regId id of a register-EVar
Returns
  • a list (possibly empty), or null if the id was not a legal register-EVar id

public abstract IEGlobalContext getGlobalContext ()

public abstract IEGeneric getInputVariableForRegister (IDFA<IEStatement> dfa, long nativeRegId)

Parameters
nativeRegId the id of a native register (per the processor's register bank definition; do not confuse this with IEVar-register id)

public abstract IEGeneric getInputVariableForRegister (IDFA<IEStatement> dfa, IEVar reg)

public abstract List<Long> getIntermediateOffsetsMappingToNativeAddress (long address)

public abstract List<Long> getIntermediateOffsetsMappingToNativeAddresses (Collection<Long> addresses)

public abstract Collection<IEVar> getMemoryVariables ()

Retrieve the list of memory variables used by this context: stack variables and global variables.

public abstract INativeContext getNativeContext ()

public abstract List<String> getNotes ()

public abstract IEGeneric getOutputVariableForRegister (IDFA<IEStatement> dfa, long exitAddress, int nativeRegId)

Parameters
nativeRegId the id of a native register (per the processor's register bank definition; do not confuse this with IEVar-register id)

public abstract IEGeneric getOutputVariableForRegister (IDFA<IEStatement> dfa, long exitAddress, IEVar reg)

public abstract IEVar getProgramCounter ()

Convenience method.

public abstract int getProgramCounterId ()

Convenience method.

public abstract IWildcardPrototype getPrototype ()

Convenience method.

public abstract IEVar getRegisterMirror (IEVar reg)

Retrieve or create the mirror - that is, the first full copy, in the [IDL_MIRROR, IDL_MIRROR_END[ range - of the provided register.

Note: A register IEVar is global and non-typeable. A mirror IEVar is local and typeable.

Parameters
reg a register IEVar - the method will throw if not
Returns
  • the mirror IEVar, never null

public abstract INativeMethodItem getRoutine ()

public abstract List<IEGeneric> getRoutineInputVariables ()

Retrieve the IR expressions holding the routine's parameters. May be used only after a decompilation has fully completed.

public abstract Collection<IEVar> getRoutineVariablesInRange (int idStart, int idEnd)

public abstract VarSrc getSourceForVariable (int id)

Parameters
id a copy-var id
Returns
  • the source or null (only copy-var have sources)

public abstract IEStackManager getStackManager ()

Retrieve the manager for local IEVars representing physical stack variables (in the general sense, ie memory slots).

public abstract IEVar getStackPointer ()

Convenience method.

public abstract int getStackPointerId ()

Convenience method.

public abstract IEVar getStackReference (long stkVarOffset)

Retrieve a stack reference, i.e. a pointer to stack-memory variable.

Parameters
stkVarOffset stack offset
Returns
  • a local symbol var, null if none

public abstract IEVar getStackVariable (int offset)

Retrieve the stack variable at the provided offset.

public abstract Collection<IEVar> getStackVariables ()

Retrieve the list of memory stack variables used by this context.

public abstract Collection<IEVar> getStackVariables (int offsetStart, int offsetEnd)

Retrieve all defined stack variables whose (starting) offset are included in the provided range. Note that the last variable may span outside the range.

Parameters
offsetEnd must be greater than the start value

public abstract List<IEStatement> getStatements ()

Retrieve the raw list of converted IR-statements. Beware: this list gets stale very quickly, as the decompiler deals with and optimizes an IR-CFG (initially built from this list), instead.

Returns
  • the initial IR-statements raw list

public abstract Integer getUnderlyingRegisterId (int varid)

Retrieve the id of the underlying IEVar-register used to hold this variable.

Parameters
varid a variable id, which may or not be a register var
Returns
  • an id, null if the input variable does not originate from a register, or if it does not fit on a single physical register (which means that if the input varid is for a copy of a pair of registers, this method will return null)

public abstract IEVar getVariableById (int id)

Retrieve a variable (routine-scope or global-scope) by id.

Parameters
id var id
Returns
  • the variable or null

public abstract IEVar getVariableByName (String name)

Retrieve a routine-scope variable by name.

Parameters
name var name
Returns
  • the variable or null

public abstract IWildcardTypeManager getWildcardTypeManager ()

public abstract void invalidateDataFlowAnalysis ()

Invalidate all data flow analysis for the IR-CFG managed by this context. Convenience method.

public abstract boolean isAllowUnsafeAnalysis ()

public abstract void log (String format, Object... args)

public abstract void logUnsafeOpt (String format, Object... args)

public abstract boolean removeNote (String note)

public abstract IEVar removeStackReference (long stkVarOffset)

Remove a stack reference.

public abstract IEGeneric retrieveVariableForRegister (IEGeneric reg, Collection<Integer> filters, boolean createIfNotFound)

Parameters
reg a physical reg IEVar or slice of physical register IEVar
filters list of candidates matching var ids
createIfNotFound create a copy if not found
Returns
  • a copy of the physical input

public abstract void setCfg (CFG<IEStatement> cfg)

public abstract void setData (Object key, Object value)

Store a piece of transient data.

public abstract void setPrototype (IWildcardPrototype prototype)

Convenience method.

public abstract void setRoutine (INativeMethodItem routine)

public abstract void setStatements (List<IEStatement> statements)

Set the converted list of raw IR-statements. A list of statements can only be assigned once, else this method will throw IllegalStateException (however, this method may be called with the current list).

Parameters
statements a list of statements coming out of a converter

public abstract void setStatements (List<IEStatement> statements, boolean verifyStatements, boolean replaceLeftAssignSlices, boolean buildCfg)

Set the converted list of raw IR-statements.

Parameters
statements a list of statements coming out of a converter
verifyStatements optional
replaceLeftAssignSlices optional
buildCfg optional

public abstract void setTypeForSame (IEGeneric exp, IWildcardType type)

public abstract boolean usesCopyVars ()