Interface IERoutineContext

All Superinterfaces:
IOptimizerTarget

@Ser public interface IERoutineContext extends IOptimizerTarget
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.
  • Method Details

    • isAllowUnsafeAnalysis

      boolean isAllowUnsafeAnalysis()
    • getRoutine

      INativeMethodItem getRoutine()
    • setRoutine

      void setRoutine(INativeMethodItem routine)
    • getPrototype

      IWildcardPrototype getPrototype()
      Convenience method.
      Returns:
    • setPrototype

      void setPrototype(IWildcardPrototype prototype)
      Convenience method.
      Parameters:
      prototype -
    • getGlobalContext

      IEGlobalContext getGlobalContext()
    • getConverter

      IEConverter<?> getConverter()
    • getDecompiler

      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:
      a reference to a decompiler (likely, a INativeDecompilerUnit), or null
    • getNativeContext

      INativeContext getNativeContext()
    • getWildcardTypeManager

      IWildcardTypeManager getWildcardTypeManager()
    • getStackManager

      IEStackManager getStackManager()
      Retrieve the manager for local IEVars representing physical stack variables (in the general sense, ie memory slots).
      Returns:
    • getProgramCounter

      IEVar getProgramCounter()
      Convenience method.
      Returns:
    • getProgramCounterId

      int getProgramCounterId()
      Convenience method.
      Returns:
    • getStackPointer

      IEVar getStackPointer()
      Convenience method.
      Returns:
    • getStackPointerId

      int getStackPointerId()
      Convenience method.
      Returns:
    • setStatements

      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
    • setStatements

      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
    • buildCfg

      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
    • buildCfg

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

      void invalidateDataFlowAnalysis()
      Invalidate all data flow analysis for the IR-CFG managed by this context. Convenience method.
    • convertNativeAddress

      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
    • convertIntermediateOffset

      Long convertIntermediateOffset(int offset)
      Conversion FROM IR offset TO native address.
      Parameters:
      offset - IR offset
      Returns:
      physical address or null on error
    • getIntermediateOffsetsMappingToNativeAddress

      List<Long> getIntermediateOffsetsMappingToNativeAddress(long address)
    • getIntermediateOffsetsMappingToNativeAddresses

      List<Long> getIntermediateOffsetsMappingToNativeAddresses(Collection<Long> addresses)
    • getStatements

      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
    • getCfg

      CFG<IEStatement> getCfg()
    • setCfg

      void setCfg(CFG<IEStatement> cfg)
    • buildEmptyState

      EState buildEmptyState()
      Initialize a state to emulate this routine. The variables map is uninitialized.
      Returns:
    • createAssign

      IEAssign createAssign(IEGeneric dst, IEGeneric src)
    • createBranchAssign

      IEAssign createBranchAssign(IEGeneric dst, IEGeneric src, boolean subroutineCall)
    • createAssignIf

      IEAssign createAssignIf(IEAssign assignTpl, IEGeneric predicate)
    • createSwitch

      IESwitch createSwitch(IEGeneric controlExpression, int defaultAddress)
    • createJump

      IEJump createJump(int branchAddress)
    • createJump

      IEJump createJump(int branchAddress, IEGeneric condition)
    • createJumpFar

      IEJumpFar createJumpFar(IEGeneric jumpSite)
    • createJumpFar

      IEJumpFar createJumpFar(IEGeneric jumpSite, IEGeneric condition)
    • createNop

      IENop createNop()
    • createNop

      IENop createNop(IEStatement template)
    • createReturn

      IEReturn createReturn()
    • createReturn

      IEReturn createReturn(IEGeneric value)
    • createReturn

      IEReturn createReturn(List<IEGeneric> values)
    • createCall

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

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

      IEUntranslatedInstruction createUntranslatedInstruction(long nativeAddress, String nativeMnemonic, IEGeneric... irOperands)
    • createMem

      IEMem createMem(IEGeneric opaddr, int bitsize)
    • createMem

      IEMem createMem(IEGeneric segment, IEGeneric opaddr, int bitsize)
    • createOperation

      IEOperation createOperation(OperationType optype, IEGeneric op1)
    • createOperation

      IEOperation createOperation(OperationType optype, IEGeneric op1, IEGeneric op2)
    • createOperation

      IEOperation createOperation(FunctionOptype functionOptype, IEGeneric... opnds)
    • createResizeOperation

      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
    • createConversionOperation

      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 OperationType.isConversion() returns true (eg, OperationType.CAST, OperationType.CAST_S, OperationType.FP2FP, OperationType.FP2INT, OperationType.INT2FP)
      src - operand to be extended, truncated, or converted
      dstSize - resulting bitsize
      Returns:
      the operation IRE
    • createImm

      IEImm createImm(long v, int bitsize)
    • createImm

      IEImm createImm(byte[] v, int bitsize)
    • createImm

      IEImm createImm(BigInteger v, int bitsize)
    • createImm

      IEImm createImm(String v, int bitsize)
    • createImm

      IEImm createImm(float v)
    • createImm

      IEImm createImm(double v)
    • createCompose

      IECompose createCompose(IEGeneric... elts)
      Create a composition.
      Parameters:
      elts - at least two elements, from lowest-significant to highest-significant
      Returns:
    • createCompose

      IECompose createCompose(Collection<IEGeneric> elts)
      Create a composition.
      Parameters:
      elts - at least two elements, from lowest-significant to highest-significant
      Returns:
    • createCond

      IECond createCond(IEGeneric p, IEGeneric a, IEGeneric b)
    • createGroupElt

      IEGroupElt createGroupElt(IEGroup collection, IEGeneric index)
    • createVar

      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.

      Parameters:
      name -
      bitsize -
      Returns:
    • createVirtualVar

      IEVar createVirtualVar(String name, int bitsize)
      Create or retrieve a virtual routine-scope variable. The variable id is in the [VIRTUAL, VIRTUAL_END] range.
      Parameters:
      name -
      bitsize -
      Returns:
    • getStackReference

      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
    • removeStackReference

      IEVar removeStackReference(long stkVarOffset)
      Remove a stack reference.
      Parameters:
      stkVarOffset -
      Returns:
    • createStackReference

      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
      Returns:
    • createStackReference

      IEVar createStackReference(long stkVarOffset)
      Retrieve or create a stack reference, ie a pointer to stack-memory variable.
      Parameters:
      stkVarOffset - stack offset
      Returns:
    • getVariableByName

      IEVar getVariableByName(String name)
      Retrieve a routine-scope variable by name.
      Parameters:
      name - var name
      Returns:
      the variable or null
    • getVariableById

      IEVar getVariableById(int id)
      Retrieve a variable (routine-scope or global-scope) by id.
      Parameters:
      id - var id
      Returns:
      the variable or null
    • getRoutineVariablesInRange

      Collection<IEVar> getRoutineVariablesInRange(int idStart, int idEnd)
      Parameters:
      idStart -
      idEnd -
      Returns:
    • getStackVariables

      Collection<IEVar> getStackVariables()
      Retrieve the list of memory stack variables used by this context.
      Returns:
    • getStackVariable

      IEVar getStackVariable(int offset)
      Retrieve the stack variable at the provided offset.
      Parameters:
      offset -
      Returns:
    • getStackVariables

      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:
      offsetStart -
      offsetEnd - must be greater than the start value
      Returns:
    • getMemoryVariables

      Collection<IEVar> getMemoryVariables()
      Retrieve the list of memory variables used by this context: stack variables and global variables.
      Returns:
    • createSymbolForRoutine

      IEVar createSymbolForRoutine(INativeMethodItem routine)
    • createSymbolForField

      IEVar createSymbolForField(INativeFieldItem variable)
    • createSymbolForGlobalVariable

      IEVar createSymbolForGlobalVariable(INativeDataItem variable)
    • usesCopyVars

      boolean usesCopyVars()
      Returns:
    • getDuplicatesForRegister

      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
    • getUnderlyingRegisterId

      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)
    • getRegisterMirror

      IEVar getRegisterMirror(IEVar reg)
      Retrieve or create the mirror - that is, the first full copy, in the [IEVar.IDL_MIRROR, IEVar.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
    • copyVariable

      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
    • copyTruncatedVariable

      Couple<IEVar,IEVar> 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
      lowPartBitsize -
      Returns:
      null on error, else, a tuple containing the copy variables: low part (truncated LSB), and high part (remainder MSB)
    • copyPairOfVariables

      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
      Returns:
    • copyFinder

      EVarCopyFinder copyFinder(StorageEntry entry, Collection<Integer> filters, Long irOffset)
    • getSourceForVariable

      VarSrc getSourceForVariable(int id)
      Parameters:
      id - a copy-var id
      Returns:
      the source or null (only copy-var have sources)
    • getCopiesOfVariable

      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
    • getCopiesUsingVariable

      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
    • retrieveVariableForRegister

      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
    • getInputVariableForRegister

      IEGeneric getInputVariableForRegister(IDFA<IEStatement> dfa, long nativeRegId)
      Parameters:
      dfa -
      nativeRegId - the id of a native register (per the processor's register bank definition; do not confuse this with IEVar-register id)
      Returns:
    • getInputVariableForRegister

      IEGeneric getInputVariableForRegister(IDFA<IEStatement> dfa, IEVar reg)
      Parameters:
      dfa -
      reg -
      Returns:
    • getOutputVariableForRegister

      IEGeneric getOutputVariableForRegister(IDFA<IEStatement> dfa, long exitAddress, int nativeRegId)
      Parameters:
      dfa -
      exitAddress -
      nativeRegId - the id of a native register (per the processor's register bank definition; do not confuse this with IEVar-register id)
      Returns:
    • getOutputVariableForRegister

      IEGeneric getOutputVariableForRegister(IDFA<IEStatement> dfa, long exitAddress, IEVar reg)
      Parameters:
      dfa -
      exitAddress -
      reg -
      Returns:
    • getRoutineInputVariables

      List<IEGeneric> getRoutineInputVariables()
      Retrieve the IR expressions holding the routine's parameters. May be used only after a decompilation has fully completed.
      Returns:
    • setTypeForSame

      void setTypeForSame(IEGeneric exp, IWildcardType type)
    • acquireNativeItem

      void acquireNativeItem(INativeItem t)
      Parameters:
      t -
    • log

      void log(String format, Object... args)
    • logUnsafeOpt

      void logUnsafeOpt(String format, Object... args)
    • setData

      void setData(Object key, Object value)
      Store a piece of transient data.
      Parameters:
      key -
      value -
    • getData

      Object getData(Object key)
      Retrieve a piece of transient data.
      Parameters:
      key -
      Returns:
    • addNote

      boolean addNote(String note)
      Parameters:
      note -
      Returns:
    • removeNote

      boolean removeNote(String note)
      Parameters:
      note -
      Returns:
    • getNotes

      List<String> getNotes()
      Returns:
    • createBuiltinMethodCall

      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