IEConverter
| com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEConverter<InsnType extends com.pnfsoftware.jeb.core.units.code.IInstruction> |
 Known Indirect Subclasses
AbstractConverter<InsnType extends IInstruction>
|
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 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)
The reverse operation of
getRegisterVariableFromNativeRegisterId(long). | ||||||||||
| 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 |
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 |
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 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)
The reverse operation of getRegisterVariableFromNativeRegisterId(long).
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.
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 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 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