public interface

IEConverter

com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEConverter<InsnType extends com.pnfsoftware.jeb.core.units.code.IInstruction>
Known Indirect Subclasses

Class Overview

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 they should extend the AbstractConverter class instead.

Summary

Public Methods
abstract IWildcardPrototype buildFailsafePrototype(IERoutineContext ctx, IEStatement stm)
Create a simple, failsafe prototype for the given routine.
abstract IERoutineContext convert(INativeMethodItem routine)
Convert a routine.
abstract IERoutineContext convert(INativeMethodItem routine, boolean delayBuild)
Convert a native code routine to its initial intermediate representation.
abstract List<IEGeneric> convertParameterExpressions(IERoutineContext ctx, IWildcardPrototype prototype, INativeMethodItem targetRoutine, int addSlotCount)
Given a prototype, determine the list of IR expressions representing the input expressions (would also contain implicitly read registers).
abstract List<IEGeneric> convertReturnExpressions(IERoutineContext ctx, IWildcardPrototype prototype)
Given a prototype, determine the list of IR expressions representing the output expressions (would also contain spoiled registers, which are implicitly written).
abstract 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.
abstract IEMem createStackMemoryAccess(IEGeneric address, int bitsize)
Create an EMem using the adequate segment register (if any) for the current converter.
abstract int defaultPCConversion(IERoutineContext ctx)
Convert PC-assignment to EJumpFar statements.
abstract Integer determineStackPointerDeltaAfterIRCall(IWildcardPrototype prototype, int addSlotCount)
Given a prototype, determine the stack pointer delta (in bytes) after the ECall executed and returned.
abstract Integer determineStackPointerDeltaFromSimulation(SimulationPointInformation simuinfo)
This method attempts to provide the stack pointer delta resulting from the execution of a routine.
abstract String formatStatistics()
Generate statistics about this converter.
abstract int getAddressBitsize()
Get the size of a native address, in bits.
abstract INativeDecompilerUnit<InsnType> getDecompiler()
abstract 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).
abstract IEGlobalContext getGlobalContext()
Retrieve the global program context.
abstract long getNativeRegisterIdFromRegisterVariable(IEVar regVar, boolean shortForm)
abstract int getProcessorMode(IEState state)
Retrieve the current processor mode relative to this EState.
abstract IEVar getProgramCounter()
Retrieve the IR variable object that represents the program counter.
abstract IEPrototypeHandler getPrototypeHandler(IERoutineContext ctx)
Create an instance of a prototype handler.
abstract int getRegisterBitsize()
Get the size of a standard, general-purpose native register, in bits.
abstract IEVar getRegisterVariableFromNativeRegisterId(long nativeRegId)
Get the IR variable representing a native platform register.
abstract IEVar getReturnAddressRegister()
Retrieve the IR variable object that represents the return address register.
abstract IEVar getStackPointer()
Retrieve the IR variable object that represents the stack pointer.
abstract int getStackSlotSize()
Get the size of standard slot on the stack, in bytes.
abstract void initialize()
This method is called by the owner decompiler after the principal components of the lower-level code unit have been initialized.
abstract void initializeStateRegisters(IEState state, Long optionalNativeProgramCounter)
Initialize the registers of an IR execution state to safe defaults.
abstract int insertReturns(IERoutineContext ctx)
This method introduces EReturn statements into the IR.
abstract Boolean isSegmentEMemReferencingPrimaryMemory(IEMem e)
Determine if an EMem references bytes in the primary, unit-code managed virtual memory object, or some other memory object.
abstract boolean resolveCustomCalls(INativeCodeUnit<?> pbcu, IERoutineContext ctx)
Implementations should be aggressive and fast: calls to this method should always be enclosed in a try-catch.

Public Methods

public abstract 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

public abstract IERoutineContext convert (INativeMethodItem routine)

Convert a routine. Convenience method for convert(routine, false).

public abstract IERoutineContext convert (INativeMethodItem routine, boolean delayBuild)

Convert a native code routine to its initial intermediate representation. The initial IR consists only of EAssign, EJump, ENop and EUntranslatedInstruction 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
delayBuild if true, the IR validation and CFG building will not take place (in that case, getCfg() would return false)
Returns
  • the converted IR routine context

public abstract List<IEGeneric> convertParameterExpressions (IERoutineContext ctx, IWildcardPrototype prototype, INativeMethodItem targetRoutine, int addSlotCount)

Given a prototype, determine the list of IR expressions representing the input expressions (would also contain implicitly read registers).

Used by ECall.

Parameters
prototype mandatory prototype
targetRoutine (optional) may be null; if provided, can be used with addSlotCount (if non 0)
addSlotCount (optional) may be non-zero for a var-arg routine; the implementation should do its best to determine what are the additional (not specified in the prototype) parameters

public abstract List<IEGeneric> convertReturnExpressions (IERoutineContext ctx, IWildcardPrototype prototype)

Given a prototype, determine the list of IR expressions representing the output expressions (would also contain spoiled registers, which are implicitly written).

Used by ECall.

public abstract 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 ECall.

public abstract IEMem createStackMemoryAccess (IEGeneric address, int bitsize)

Create an EMem using the adequate segment register (if any) for the current converter.

public abstract int defaultPCConversion (IERoutineContext ctx)

Convert PC-assignment to EJumpFar statements. This method is a fail-safe converter for PC-assignments, and should be called as late as possible in the IR conversion phases.

Returns
  • the number of PC-conversions performed

public abstract Integer determineStackPointerDeltaAfterIRCall (IWildcardPrototype prototype, int addSlotCount)

Given a prototype, determine the stack pointer delta (in bytes) after the ECall 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 ECall.

Used by ECall.

Returns
  • null on error

public abstract 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

public abstract String formatStatistics ()

Generate statistics about this converter.

public abstract int getAddressBitsize ()

Get the size of a native address, in bits.

public abstract INativeDecompilerUnit<InsnType> getDecompiler ()

public abstract 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 EStandardCallSiteResolver.

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)

public abstract IEGlobalContext getGlobalContext ()

Retrieve the global program context. There is a single global context per decompiler, common to all ERoutineContext routine contexts.

Returns
  • the global context

public abstract long getNativeRegisterIdFromRegisterVariable (IEVar regVar, boolean shortForm)

Parameters
shortForm if true the value provided does not contain the converter-specific information present in the long form (used in particular by getRegisterName(long)), otherwise it is the long form
Returns
  • a native register id
Throws
DecompilerException if the conversion is not implemented

public abstract int getProcessorMode (IEState state)

Retrieve the current processor mode relative to this EState. A bit can be set in the EState to indicate the current mode (for example ARM Thumb Bit).

Parameters
state current state
Returns
  • processor mode: most often 16, 32 or 64 Bit

public abstract IEVar getProgramCounter ()

Retrieve the IR variable object that represents the program counter.

Returns
  • never null

public abstract IEPrototypeHandler getPrototypeHandler (IERoutineContext ctx)

Create an instance of a prototype handler.

public abstract int getRegisterBitsize ()

Get the size of a standard, general-purpose native register, in bits.

public abstract IEVar getRegisterVariableFromNativeRegisterId (long nativeRegId)

Get the IR variable representing a native platform register.

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 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).
Returns
  • a global EVar representing the register
Throws
DecompilerException if the conversion is not implemented

public abstract 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

public abstract IEVar getStackPointer ()

Retrieve the IR variable object that represents the stack pointer.

Returns
  • never null

public abstract int getStackSlotSize ()

Get the size of standard slot on the stack, in bytes.

public abstract 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.

public abstract void initializeStateRegisters (IEState 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

public abstract int insertReturns (IERoutineContext ctx)

This method introduces EReturn 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

public abstract Boolean isSegmentEMemReferencingPrimaryMemory (IEMem e)

Determine if an EMem references bytes in the primary, unit-code managed virtual memory object, or some other memory object.

Returns
  • 3-state result: true/false, null= cannot determine

public abstract boolean resolveCustomCalls (INativeCodeUnit<?> pbcu, 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