public interface

IERoutineContext

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

Class Overview

TODO: clarified terminology - copies / duplicates / pairs/mergers, truncated/fractions, etc.

Summary

Constants
String CFGTAG_FINAL
String CFGTAG_FINAL_PRENORM
String CFGTAG_SYMBOLICALLY_SIMPLIFIED
String CFGTAG_TYPED
String CFGTAG_UNFLATTENED
Public Methods
abstract void acquireNativeItem(INativeItem t)
abstract boolean addNote(String note)
abstract CFG<IEStatement> buildCfg(List<IEStatement> statements, AddressConversionLists updatedConvlists, boolean subroutineCallNotBreaking)
Build an IR-CFG from a list of statements.
abstract CFG<IEStatement> buildDefaultCfg(List<IEStatement> statements)
Build an IR-CFG using the provided list of statements, and set the resulting CFG as the default one for this converted routine.
abstract EState buildEmptyState()
Initialize a state to emulate this routine.
abstract Long convertIntermediateOffset(int offset, boolean logConversionErrors)
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 Long convertNativeAddress(long address, boolean logConversionErrors)
abstract EVarCopyFinder copyFinder(RoutineIOSlot slot, 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 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 offset, 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 AddressConversionLists getAddressConversionLists()
abstract CFG<IEStatement> getCfg()
abstract IEConverter<?> getConverter()
abstract Set<Integer> getCopiesOfVariable(int varid)
Get the set of all variables that are copies or partial copies of the provided input id.
abstract Set<Integer> getCopiesUsingVariable(int varid)
Get the set of all variables making use of the provided variable.
abstract Object getData(Object key)
Retrieve a piece of transient data.
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 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 EVars 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 offset)
Retrieve a stack reference, ie a pointer to stack-memory variable.
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 EVar-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 boolean isAllowUnsafeAnalysis()
abstract void log(String format, Object... args)
abstract void logUnsafeOpt(String format, Object... args)
abstract void registerAdditionalConvertedAddress(long nativeAddress, int expectedOffset)
Register an additional converted address.
abstract void registerConvertedAddress(long nativeAddress, int intermediateOffset)
abstract void registerConvertedAddressRange(long nativeAddress, int intermediateOffset, int interOffsetEnd)
abstract boolean removeNote(String note)
abstract IEGeneric retrieveVariableForRegister(IEGeneric reg, Collection<Integer> filters, boolean createIfNotFound)
abstract void setCfg(CFG<IEStatement> cfg, Map<Integer, Long> interToNative, Map<Long, Integer> nativeToInter)
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, AddressConversionLists conversionLists, boolean verifyStatements, boolean replaceLeftAssignSlices, boolean assignLowerLevelAddresses, boolean buildCfg)
Set the converted list of raw IR-statements.
abstract void setStatements(List<IEStatement> statements)
Set the converted list of raw IR-statements.
abstract void setTypeForSame(IEGeneric exp, IWildcardType type)
abstract void updateConvertedAddress(int irOffset, long nativeAddress)
abstract boolean usesCopyVars()

Constants

public static final String CFGTAG_FINAL

Constant Value: "final"

public static final String CFGTAG_FINAL_PRENORM

Constant Value: "finalPrenorm"

public static final String CFGTAG_SYMBOLICALLY_SIMPLIFIED

Constant Value: "symbolicallySimplified"

public static final String CFGTAG_TYPED

Constant Value: "typed"

public static final String CFGTAG_UNFLATTENED

Constant Value: "unflattened"

Public Methods

public abstract void acquireNativeItem (INativeItem t)

public abstract boolean addNote (String note)

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

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
updatedConvlists IR<>Native conversion lists to be used when building the CFG; if null, the ones currently stored in the context will be used
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> buildDefaultCfg (List<IEStatement> statements)

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

Parameters
statements input list of IEStatements
Returns
  • the newly created (now default) CFG

public abstract EState buildEmptyState ()

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

public abstract Long convertIntermediateOffset (int offset, boolean logConversionErrors)

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 Long convertNativeAddress (long address, boolean logConversionErrors)

public abstract EVarCopyFinder copyFinder (RoutineIOSlot slot, 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 EVar-register
hi an EVar-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 EVar-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 EVar-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 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 offset, IWildcardType type)

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

Parameters
offset stack offset

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

public abstract CFG<IEStatement> getCfg ()

public abstract IEConverter<?> getConverter ()

public abstract Set<Integer> getCopiesOfVariable (int varid)

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.

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

public abstract Set<Integer> getCopiesUsingVariable (int varid)

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.

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 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 EVar-register id)

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

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 EVar-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 EVar is global and non-typeable. A mirror EVar is local and typeable.

Parameters
reg a register EVar - the method will throw if not
Returns
  • the mirror EVar, 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 EVars 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 offset)

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

Parameters
offset 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 EVar-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 boolean isAllowUnsafeAnalysis ()

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

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

public abstract void registerAdditionalConvertedAddress (long nativeAddress, int expectedOffset)

Register an additional converted address. An existing native->offset entry for the provided native address must exist. An additional offset->native entry will be added.

public abstract void registerConvertedAddress (long nativeAddress, int intermediateOffset)

public abstract void registerConvertedAddressRange (long nativeAddress, int intermediateOffset, int interOffsetEnd)

public abstract boolean removeNote (String note)

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

Parameters
reg a physical reg EVar or slice of physical register EVar
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, Map<Integer, Long> interToNative, Map<Long, Integer> nativeToInter)

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, AddressConversionLists conversionLists, boolean verifyStatements, boolean replaceLeftAssignSlices, boolean assignLowerLevelAddresses, boolean buildCfg)

Set the converted list of raw IR-statements.

Parameters
statements a list of statements coming out of a converter
conversionLists if non-null, address conversion lists are being assigned
verifyStatements optional
replaceLeftAssignSlices optional
assignLowerLevelAddresses optional
buildCfg optional

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 setTypeForSame (IEGeneric exp, IWildcardType type)

public abstract void updateConvertedAddress (int irOffset, long nativeAddress)

public abstract boolean usesCopyVars ()