Interface IEConverter<InsnType extends IInstruction>
- Type Parameters:
InsnType
-
- All Known Implementing Classes:
AbstractConverter
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.-
Method Summary
Modifier and TypeMethodDescriptionCreate a simple, failsafe prototype for the given routine.boolean
Determine if the decompilation pipeline is allowed to create moreIECall
instructions than those already provided by the converter, after the conversion-to-IR stage completed.convert
(INativeMethodItem routine) Convert a native code routine to its initial intermediate representation.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).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.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.createStackMemoryAccess
(IEGeneric address, int bitsize) Create an EMem using the adequate segment register (if any) for the current converter.void
customInitStateRegisters
(EState state, Long optionalNativeProgramCounter) Custom/specific initialization of registers prior to emulation.int
Convert PC-assignment toIEJumpFar
statements.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.determineStackPointerDeltaAfterIRCall
(IWildcardPrototype prototype, List<IWildcardType> varArgTypes) Determine the stack pointer delta (in bytes) after theIECall
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.This method attempts to provide the stack pointer delta resulting from the execution of a routine.evaluateUntranslatedIR
(IEUntranslatedInstruction insn, IERoutineContext ectx, EState state) Evaluate untranslated IR instructions.Generate statistics about this converter.generateASTForUntranslatedIR
(IEUntranslatedInstruction insn, IERoutineContext ectx, ICMethod cctx) Generate C statement from an untranslated IR instruction.int
Get the size of a native address, in bits.Retrieve a reference to the decompiler managing this converter.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).getFPRegister
(int index) Retrieve the IR variable object that represents the Floating-point register.Retrieve the global program context.getGPRegister
(int index) Retrieve the IR variable object that represents the General Purpose register.getInputVariableByIndex
(IERoutineContext ctx, int i) Retrieve the native code context that this converter should use.long
long
getNativeRegisterIdFromRegisterVariable
(IEVar regVar, boolean shortForm) Get the native platform register number or id (as defined in a register bank layout) corresponding to the providedIEVar
-register IR variable.getOutputVariableByIndex
(IERoutineContext ctx, int i) Retrieve the IR variable object that represents the program counter.Create an instance of a prototype handler.getRegister
(String name) getRegister
(String name, ELocation loc) Retrieve anIEVar
-register by its name.int
Get the size of a standard, general-purpose native register, in bits.getRegisterVariableFromNativeRegisterId
(long nativeRegId) getRegisterVariableFromNativeRegisterId
(long nativeRegId, ELocation loc) Get theIEVar
-register IR variable representing a native platform register number or id (as defined in a register bank layout).Retrieve the IR variable object that represents the return address register.getSlicedRegisterName
(String registerName, int bitstart, int bitend) Get the name of the slice of a physical register.Retrieve the IR variable object that represents the stack pointer.int
Get the size of standard slot on the stack, in bytes.int
getStateProcessorMode
(EState state) Retrieve the current processor mode relative to the providedEState
.getTempRegister
(int index) void
This method is called by the owner decompiler after the principal components of the lower-level code unit have been initialized.void
initializeStateRegisters
(EState state, Long optionalNativeProgramCounter) Initialize the registers of an IR execution state to safe defaults.int
This method introducesIEReturn
statements into the IR.Determine if anIEMem
references bytes in the primary, unit-code managed virtual memory object, or some other memory object.normalizeBranchingExpression
(IDFA<IEStatement> dfa, BasicBlock<IEStatement> b, IEGeneric callsite, IEGeneric expectedTarget) Normalize a branching expression.boolean
Implementations should be aggressive and fast: calls to this method should always be enclosed in a try-catch.long
sanitizeNativeAddress
(long address)
-
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:
-
getRegisterBitsize
int getRegisterBitsize()Get the size of a standard, general-purpose native register, in bits.- Returns:
-
getStackSlotSize
int getStackSlotSize()Get the size of standard slot on the stack, in bytes.- Returns:
-
getWildcardTypeManagerDefaultResolutionGroup
IWildcardType.Group getWildcardTypeManagerDefaultResolutionGroup()- Returns:
-
getRegister
Retrieve anIEVar
-register by its name.- Parameters:
name
- register nameloc
- optional IR statement location at which the conversion is taking place- Returns:
-
getRegister
- Parameters:
name
-- Returns:
-
getRegisterVariableFromNativeRegisterId
IEGeneric getRegisterVariableFromNativeRegisterId(long nativeRegId, ELocation loc) throws DecompilerException Get theIEVar
-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 theIProcessor
that this converter is relying on; the id may be a full id, that is, one supported byIInstructionOperandRegisterBased.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
SeegetRegisterVariableFromNativeRegisterId(long, ELocation)
. No location provided- Parameters:
nativeRegId
-- 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 providedIEVar
-register IR variable.- Parameters:
regVar
- a globalIEVar
-registershortForm
- if true the value provided does not contain the converter-specific information present in the long form (used in particular byIInstructionOperandRegisterBased.getRegisterName(long)
), otherwise it is the long form- Returns:
- a native register id
- Throws:
DecompilerException
- if the conversion failed
-
getNativeRegisterIdFromRegisterVariable
- Parameters:
regVar
-- Returns:
- Throws:
DecompilerException
- if the conversion failed
-
getSlicedRegisterName
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 registerbitstart
-bitend
-- Returns:
- null if the slice does not have a particular name
-
createStackMemoryAccess
Create an EMem using the adequate segment register (if any) for the current converter.- Parameters:
address
-bitsize
-- Returns:
-
sanitizeNativeAddress
long sanitizeNativeAddress(long address) - Parameters:
address
-- Returns:
-
isSegmentEMemReferencingPrimaryMemory
Determine if anIEMem
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
-
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 allroutine 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
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:
-
getFPRegister
Retrieve the IR variable object that represents the Floating-point register.- Parameters:
index
- register index- Returns:
-
getTempRegister
-
convert
Convert a native code routine to its initial intermediate representation. The initial IR consists only ofIEAssign
,IEJump
,IENop
andIEUntranslatedInstruction
statements. Each statement instruction must have asize
of 1. The resulting IR is verified and the initial IR-CFG created.- Parameters:
routine
- the routine to be converted; must have adata
definition- Returns:
- the converted IR routine context
-
getPrototypeHandler
Create an instance of a prototype handler.- Parameters:
ctx
-- Returns:
-
canCreateCalls
boolean canCreateCalls()Determine if the decompilation pipeline is allowed to create moreIECall
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:
-
convertReturnLocation
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
-prototype
-- Returns:
-
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
-prototype
-targetRoutine
-varArgTypes
-outSpoiled
-- 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
-prototype
- mandatory prototypetargetRoutine
- optionalvarArgTypes
- optional- Returns:
- a list of non-copy IEVars holding storage of input expressions
-
getInputVariableByIndex
- Parameters:
ctx
-i
-- Returns:
-
getOutputVariableByIndex
- Parameters:
ctx
-i
-- Returns:
-
determineStackPointerDeltaAfterIRCall
Integer determineStackPointerDeltaAfterIRCall(IWildcardPrototype prototype, List<IWildcardType> varArgTypes) Determine the stack pointer delta (in bytes) after theIECall
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 overIECall
.Used by
IECall
.- Parameters:
prototype
-varArgTypes
-- 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
-varArgTypes
-- Returns:
-
determineStackPointerDeltaFromSimulation
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
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
IECallsiteResolver
.- 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
Create a simple, failsafe prototype for the given routine.- Parameters:
ctx
- routine for which a failsafe prototype is to be generatedstm
- optional statement calling into the routine- Returns:
- a prototype object, should never be null
-
insertReturns
This method introducesIEReturn
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 objectb
- 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:
-
defaultPCConversion
Convert PC-assignment toIEJumpFar
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
-- Returns:
- the number of PC-conversions performed
-
resolveCustomCalls
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
-- Returns:
-
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 producesICCustomStatement
wrappingIEUntranslatedInstruction
.- Parameters:
insn
-ectx
-cctx
-- Returns:
-
evaluateUntranslatedIR
Evaluate untranslated IR instructions. This method is preferred to the internal evaluator, which currently throws by default when attempting to evaluate anIEUntranslatedInstruction
.The default implementation returns null.
- Parameters:
insn
-ectx
-state
-- Returns:
-
initializeStateRegisters
Initialize the registers of an IR execution state to safe defaults.- Parameters:
state
- input state to be initializedoptionalNativeProgramCounter
- optional current native PC
-
customInitStateRegisters
Custom/specific initialization of registers prior to emulation.- Parameters:
state
-optionalNativeProgramCounter
-
-
getStateProcessorMode
Retrieve the current processor mode relative to the providedEState
. Refer toIProcessor.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:
-