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

Interface IEConverter<InsnType extends IInstruction>

Type Parameters:
InsnType - native instruction type handled by this converter
All Known Implementing Classes:
AbstractConverter
@Ser public interface IEConverter<InsnType extends IInstruction>
Definition of an IR expression converter, used by the generic decompiler to convert native machine code to an intermediate representation. Decompiler plugins are discouraged from implementing this interface on their own; they should extend the AbstractConverter class instead.

  • Method Details

    • initialize

      void initialize()
      This method is called by the owner decompiler after the principal components of the lower-level code unit have been initialized. Initialization requiring, e.g. access to the type manager, should be performed here instead of within the constructor.

    • getAddressBitsize

      int getAddressBitsize()
      Get the size of a native address, in bits.
      Returns:
      the native address size, in bits

    • getRegisterBitsize

      int getRegisterBitsize()
      Get the size of a standard, general-purpose native register, in bits.
      Returns:
      the general-purpose register size, in bits

    • getStackSlotSize

      int getStackSlotSize()
      Get the size of a standard slot on the stack, in bytes.
      Returns:
      the stack slot size, in bytes

    • getWildcardTypeManagerDefaultResolutionGroup

      IWildcardType.Group getWildcardTypeManagerDefaultResolutionGroup()
      Get the wildcard type resolution group to use by default.
      Returns:
      the default wildcard type resolution group

    • getRegister

      IEGeneric getRegister(String name, ELocation loc)
      Retrieve an IEVar-register by its name.
      Parameters:
      name - register name
      loc - optional IR statement location at which the conversion is taking place
      Returns:
      the register expression, or null if no such register exists

    • getRegister

      IEGeneric getRegister(String name)
      Retrieve an IEVar-register by its name, without conversion location information.
      Parameters:
      name - register name
      Returns:
      the register expression, or null if no such register exists

    • getRegisterVariableFromNativeRegisterId

      IEGeneric getRegisterVariableFromNativeRegisterId(long nativeRegId, ELocation loc) throws DecompilerException
      Get the IEVar-register IR variable representing a native platform register number or id (as defined in a register bank layout).
      Parameters:
      nativeRegId - a native register id, used by the IProcessor that this converter is relying on; the id may be a full id, that is, one supported by IInstructionOperandRegisterBased.getRegisterName(long), or a short-form of it (eg, the default X86 Processor module uses short-form 0 for the eAX register, that is the first GP register whose size matches the current processor mode).
      loc - optional IR statement location at which the conversion is taking place
      Returns:
      a global IEVar-register
      Throws:
      DecompilerException - if the conversion failed

    • getRegisterVariableFromNativeRegisterId

      IEGeneric getRegisterVariableFromNativeRegisterId(long nativeRegId) throws DecompilerException
      See getRegisterVariableFromNativeRegisterId(long, ELocation). No location provided
      Parameters:
      nativeRegId - native register id or number
      Returns:
      a global IEVar-register
      Throws:
      DecompilerException - if the conversion failed

    • getNativeRegisterIdFromRegisterVariable

      long getNativeRegisterIdFromRegisterVariable(IEVar regVar, boolean shortForm) throws DecompilerException
      Get the native platform register number or id (as defined in a register bank layout) corresponding to the provided IEVar-register IR variable.
      Parameters:
      regVar - a global IEVar-register
      shortForm - if true the value provided does not contain the converter-specific information present in the long form (used in particular by IInstructionOperandRegisterBased.getRegisterName(long)), otherwise it is the long form
      Returns:
      a native register id
      Throws:
      DecompilerException - if the conversion failed

    • getNativeRegisterIdFromRegisterVariable

      long getNativeRegisterIdFromRegisterVariable(IEVar regVar) throws DecompilerException
      Same as getNativeRegisterIdFromRegisterVariable(IEVar, false).
      Parameters:
      regVar - a global IEVar-register
      Returns:
      a native register id
      Throws:
      DecompilerException - if the conversion failed

    • getSlicedRegisterName

      String getSlicedRegisterName(String registerName, int bitstart, int bitend)
      Get the name of the slice of a physical register. The slice name may be an official name or a convenience name decided by the converter.
      Parameters:
      registerName - full name of a physical register
      bitstart - slice start bit
      bitend - slice end bit
      Returns:
      null if the slice does not have a particular name

    • createStackMemoryAccess

      IEMem createStackMemoryAccess(IEGeneric address, int bitsize)
      Create an EMem using the adequate segment register (if any) for the current converter.
      Parameters:
      address - stack memory address expression
      bitsize - access size, in bits
      Returns:
      a stack memory access expression

    • sanitizeNativeAddress

      long sanitizeNativeAddress(long address)
      Normalize a native address for this converter.
      Parameters:
      address - a native address
      Returns:
      the normalized native address

    • isSegmentEMemReferencingPrimaryMemory

      Boolean isSegmentEMemReferencingPrimaryMemory(IEMem e)
      Determine if an IEMem references bytes in the primary, unit-code managed virtual memory object, or some other memory object.
      Parameters:
      e - memory expression to examine
      Returns:
      3-state result: true/false, null= cannot determine

    • getNativeContext

      INativeContext getNativeContext()
      Retrieve the native code context that this converter should use.
      Returns:
      never null

    • getDecompiler

      INativeDecompilerContext getDecompiler()
      Retrieve a reference to the decompiler managing this converter.
      Returns:
      a reference to a decompiler (likely, a INativeDecompilerUnit), or null

    • getGlobalContext

      IEGlobalContext getGlobalContext()
      Retrieve the global program context. There is a single global context per decompiler, common to all routine contexts.
      Returns:
      the global context

    • getProgramCounter

      IEVar getProgramCounter()
      Retrieve the IR variable object that represents the program counter.
      Returns:
      never null

    • getStackPointer

      IEVar getStackPointer()
      Retrieve the IR variable object that represents the stack pointer.
      Returns:
      never null

    • getReturnAddressRegister

      IEVar getReturnAddressRegister()
      Retrieve the IR variable object that represents the return address register.
      Returns:
      can return null value if Processor does not use Return Address Register

    • getGPRegister

      IEVar getGPRegister(int index)
      Retrieve the IR variable object that represents the General Purpose register.
      Parameters:
      index - register index (eg 0 for x86 eax, ARM R0, Arm64 X0...)
      Returns:
      the general-purpose register variable, or null if unavailable

    • getFPRegister

      IEVar getFPRegister(int index)
      Retrieve the IR variable object that represents the Floating-point register.
      Parameters:
      index - register index
      Returns:
      the floating-point register variable, or null if unavailable

    • getTempRegister

      IEVar getTempRegister(int index)
      Retrieve a temporary register variable.
      Parameters:
      index - temporary register index
      Returns:
      the temporary register variable, or null if unavailable

    • convert

      IERoutineContext convert(INativeMethodItem routine)
      Convert a native code routine to its initial intermediate representation. The initial IR consists only of IEAssign, IEJump, IENop and IEUntranslatedInstruction statements. Each statement instruction must have a size of 1. The resulting IR is verified and the initial IR-CFG created.
      Parameters:
      routine - the routine to be converted; must have a data definition
      Returns:
      the converted IR routine context

    • getPrototypeHandler

      IEPrototypeHandler getPrototypeHandler(IERoutineContext ctx)
      Create an instance of a prototype handler.
      Parameters:
      ctx - routine context
      Returns:
      a prototype handler

    • canCreateCalls

      boolean canCreateCalls()
      Determine if the decompilation pipeline is allowed to create more IECall instructions than those already provided by the converter, after the conversion-to-IR stage completed.

      Most decompiler plugins will want to return true. Decompiler plugins that do not implement full support for ECall creation (e.g. convertReturnExpressions, convertParameterExpressions, convertReturnLocation, etc.) in pipeline stages may want to return false.

      Returns:
      true if the pipeline may create additional calls

    • convertReturnLocation

      IEGeneric convertReturnLocation(IERoutineContext ctx, IWildcardPrototype prototype)
      Given a prototype, determine the IR expression representing the return address location of a call to a method of said prototype.

      Used by IECall.

      Parameters:
      ctx - routine context
      prototype - call prototype
      Returns:
      the return address location expression, or null if unavailable

    • convertReturnExpressions

      List<IEGeneric> convertReturnExpressions(IERoutineContext ctx, IWildcardPrototype prototype, INativeMethodItem targetRoutine, List<IWildcardType> varArgTypes, List<IEGeneric> outSpoiled)
      Given a prototype, determine the list of IR expressions representing the output expressions. Spoiled register expressions can also be returned.

      Used by IECall.

      Parameters:
      ctx - routine context
      prototype - call prototype
      targetRoutine - optional target routine
      varArgTypes - optional variable argument types
      outSpoiled - optional sink for spoiled register expressions
      Returns:
      a list of non-copy IEVars holding storage of output expressions

    • convertParameterExpressions

      List<IEGeneric> convertParameterExpressions(IERoutineContext ctx, IWildcardPrototype prototype, INativeMethodItem targetRoutine, List<IWildcardType> varArgTypes)
      Given a prototype, determine the list of IR expressions representing the input expressions (would also contain implicitly read registers).

      Used by IECall.

      Parameters:
      ctx - routine context
      prototype - mandatory prototype
      targetRoutine - optional
      varArgTypes - optional
      Returns:
      a list of non-copy IEVars holding storage of input expressions

    • getInputVariableByIndex

      IEVar getInputVariableByIndex(IERoutineContext ctx, int i)
      Retrieve an input variable by index.
      Parameters:
      ctx - routine context
      i - input variable index
      Returns:
      the input variable, or null if unavailable

    • getOutputVariableByIndex

      IEVar getOutputVariableByIndex(IERoutineContext ctx, int i)
      Retrieve an output variable by index.
      Parameters:
      ctx - routine context
      i - output variable index
      Returns:
      the output variable, or null if unavailable

    • determineStackPointerDeltaAfterIRCall

      Integer determineStackPointerDeltaAfterIRCall(IWildcardPrototype prototype, List<IWildcardType> varArgTypes)
      Determine the stack pointer delta (in bytes) after the IECall executed and returned.
      Careful: "IR-Call" and the "native-call" may not have the same structure; it depends on how the conversion of "native-call" is implemented, and therefore is converter-dependent. The SP delta returned by this method is the one after an execution over IECall.

      Used by IECall.

      Parameters:
      prototype - call prototype
      varArgTypes - optional variable argument types
      Returns:
      null on error

    • determineStackBytesUsedByCall

      Integer determineStackBytesUsedByCall(IWildcardPrototype prototype, List<IWildcardType> varArgTypes)
      Determine the amount of bytes that were pushed on the stack before calling the routine with the provided prototype and optional additional slots. That should include all routine parameters pushed on the stack as well as the return address bytes as well, if it is located on the stack (per the provided calling convention).

      Used by IECall.

      Parameters:
      prototype - call prototype
      varArgTypes - optional variable argument types
      Returns:
      the number of stack bytes used by the call, or null on error

    • determineStackPointerDeltaFromSimulation

      Integer determineStackPointerDeltaFromSimulation(SimulationPointInformation simuinfo)
      This method attempts to provide the stack pointer delta resulting from the execution of a routine. The provided state is the current execution state right after the call or jump to the under-examination routine has occurred.
      Parameters:
      simuinfo - state of IR execution; PC is assumed to be on the target routine entry-point
      Returns:
      null on error, otherwise, the SP delta after the routine has executed and returned to the caller

    • getDefaultBranchToRoutineSideEffects

      IEBranchDetails getDefaultBranchToRoutineSideEffects(INativeMethodItem optionalRoutine)
      This heuristic does a best-effort determination of the side-effects resulting by calling a sub routine (used/defined registers, stack delta). Implementors should not attempt to do complex determination (eg, involving IR processing) in this method; the result provided by this method is meant to augment PC-assignments in earlier phases of the decompilation pipeline.

      Used by call-site resolution heuristics.

      Parameters:
      optionalRoutine - the optional target routine; if provided, the implementation may use that information to provide more accurate results
      Returns:
      a branch details object (never null)

    • buildFailsafePrototype

      IWildcardPrototype buildFailsafePrototype(IERoutineContext ctx, IEStatement stm)
      Create a simple, failsafe prototype for the given routine.
      Parameters:
      ctx - routine for which a failsafe prototype is to be generated
      stm - optional statement calling into the routine
      Returns:
      a prototype object, should never be null

    • insertReturns

      int insertReturns(IERoutineContext ctx)
      This method introduces IEReturn statements into the IR. Must be performed only after prototype discovery is completed.

      Data chains: not used, may be invalidated; in the latter case, this method is responsible for recalculating them.

      Parameters:
      ctx - the routine context
      Returns:
      the number of insertions performed

    • normalizeBranchingExpression

      IEGeneric normalizeBranchingExpression(IDFA<IEStatement> dfa, BasicBlock<IEStatement> b, IEGeneric callsite, IEGeneric expectedTarget)
      Normalize a branching expression.
      Parameters:
      dfa - a DFA object
      b - basic block whose last instruction is a branching statement (e.g. EAssign to PC, ECall, EJumpFar, etc.)
      callsite - the callsite of the branching statement targeted by the basic block `b`
      expectedTarget - optional
      Returns:
      the normalized branching expression

    • defaultPCConversion

      int defaultPCConversion(IERoutineContext ctx)
      Convert PC-assignment to IEJumpFar statements. This method is a fail-safe converter for PC-assignments, and should be called as late as possible in the IR conversion phases. After executing this method, the CFG should no longer contain PC-assignments.
      Parameters:
      ctx - routine context
      Returns:
      the number of PC-conversions performed

    • resolveCustomCalls

      boolean resolveCustomCalls(IERoutineContext ctx)
      Implementations should be aggressive and fast: calls to this method should always be enclosed in a try-catch.

      TODO: MOVE to the CBDU

      Parameters:
      ctx - routine context
      Returns:
      true if custom call resolution changed the routine

    • generateASTForUntranslatedIR

      ICStatement generateASTForUntranslatedIR(IEUntranslatedInstruction insn, IERoutineContext ectx, ICMethod cctx)
      Generate C statement from an untranslated IR instruction. This method is preferred to the internal generator, which produces ICCustomStatement wrapping IEUntranslatedInstruction.
      Parameters:
      insn - untranslated IR instruction
      ectx - IR routine context
      cctx - C method context
      Returns:
      the generated C statement, or null to use the default generator

    • evaluateUntranslatedIR

      IEImm evaluateUntranslatedIR(IEUntranslatedInstruction insn, IERoutineContext ectx, EState state)
      Evaluate untranslated IR instructions. This method is preferred to the internal evaluator, which currently throws by default when attempting to evaluate an IEUntranslatedInstruction.

      The default implementation returns null.

      Parameters:
      insn - untranslated IR instruction
      ectx - IR routine context
      state - current evaluation state
      Returns:
      the evaluated immediate value, or null if no value can be produced

    • initializeStateRegisters

      void initializeStateRegisters(EState state, Long optionalNativeProgramCounter)
      Initialize the registers of an IR execution state to safe defaults.
      Parameters:
      state - input state to be initialized
      optionalNativeProgramCounter - optional current native PC

    • customInitStateRegisters

      void customInitStateRegisters(EState state, Long optionalNativeProgramCounter)
      Custom/specific initialization of registers prior to emulation.
      Parameters:
      state - input state to customize
      optionalNativeProgramCounter - optional current native PC

    • getStateProcessorMode

      int getStateProcessorMode(EState state)
      Retrieve the current processor mode relative to the provided EState. Refer to IProcessor.getMode() for the semantics of mode.
      Parameters:
      state - optional IR state
      Returns:
      the processor mode (most often 8, 16, 32 or 64)

    • formatStatistics

      String formatStatistics()
      Generate statistics about this converter.
      Returns:
      formatted converter statistics