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 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.
abstract IERoutineContext convert(INativeMethodItem routine)
Convert a native code routine to its initial intermediate representation.
abstract 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).
abstract 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.
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 void customInitStateRegisters(EState state, Long optionalNativeProgramCounter)
Custom/specific initialization of registers prior to emulation.
abstract int defaultPCConversion(IERoutineContext ctx)
Convert PC-assignment to IEJumpFar statements.
abstract 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.
abstract Integer determineStackPointerDeltaAfterIRCall(IWildcardPrototype prototype, List<IWildcardType> varArgTypes)
Determine the stack pointer delta (in bytes) after the IECall 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 IEImm evaluateUntranslatedIR(IEUntranslatedInstruction insn, IERoutineContext ectx, EState state)
Evaluate untranslated IR instructions.
abstract String formatStatistics()
Generate statistics about this converter.
abstract ICStatement generateASTForUntranslatedIR(IEUntranslatedInstruction insn, IERoutineContext ectx, ICMethod cctx)
Generate C statement from an untranslated IR instruction.
abstract int getAddressBitsize()
Get the size of a native address, in bits.
abstract INativeDecompilerContext getDecompiler()
Retrieve a reference to the decompiler managing this converter.
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 IEVar getFPRegister(int index)
Retrieve the IR variable object that represents the Floating-point register.
abstract IEVar getGPRegister(int index)
Retrieve the IR variable object that represents the General Purpose register.
abstract IEGlobalContext getGlobalContext()
Retrieve the global program context.
abstract IEVar getInputVariableByIndex(IERoutineContext ctx, int i)
abstract INativeContext getNativeContext()
Retrieve the native code context that this converter should use.
abstract long getNativeRegisterIdFromRegisterVariable(IEVar regVar, boolean shortForm)
Get the native platform register number or id (as defined in a register bank layout) corresponding to the provided IEVar-register IR variable.
abstract long getNativeRegisterIdFromRegisterVariable(IEVar regVar)
abstract IEVar getOutputVariableByIndex(IERoutineContext ctx, int i)
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 IEGeneric getRegister(String name, ELocation loc)
Retrieve an IEVar-register by its name.
abstract IEGeneric getRegister(String name)
abstract int getRegisterBitsize()
Get the size of a standard, general-purpose native register, in bits.
abstract IEGeneric getRegisterVariableFromNativeRegisterId(long nativeRegId)
abstract IEGeneric getRegisterVariableFromNativeRegisterId(long nativeRegId, ELocation loc)
Get the IEVar-register IR variable representing a native platform register number or id (as defined in a register bank layout).
abstract IEVar getReturnAddressRegister()
Retrieve the IR variable object that represents the return address register.
abstract String getSlicedRegisterName(String registerName, int bitstart, int bitend)
Get the name of the slice of a physical 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 int getStateProcessorMode(EState state)
Retrieve the current processor mode relative to the provided EState.
abstract IEVar getTempRegister(int index)
abstract IWildcardType.Group getWildcardTypeManagerDefaultResolutionGroup()
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(EState state, Long optionalNativeProgramCounter)
Initialize the registers of an IR execution state to safe defaults.
abstract int insertReturns(IERoutineContext ctx)
This method introduces IEReturn statements into the IR.
abstract Boolean isSegmentEMemReferencingPrimaryMemory(IEMem e)
Determine if an IEMem references bytes in the primary, unit-code managed virtual memory object, or some other memory object.
abstract IEGeneric normalizeBranchingExpression(IDFA<IEStatement> dfa, BasicBlock<IEStatement> b, IEGeneric callsite, IEGeneric expectedTarget)
Normalize a branching expression.
abstract boolean resolveCustomCalls(IERoutineContext ctx)
Implementations should be aggressive and fast: calls to this method should always be enclosed in a try-catch.
abstract long sanitizeNativeAddress(long address)

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

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

public abstract 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
prototype mandatory prototype
targetRoutine optional
varArgTypes optional
Returns
  • a list of non-copy IEVars holding storage of input expressions

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

Returns
  • a list of non-copy IEVars holding storage of output expressions

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 IECall.

public abstract IEMem createStackMemoryAccess (IEGeneric address, int bitsize)

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

public abstract void customInitStateRegisters (EState state, Long optionalNativeProgramCounter)

Custom/specific initialization of registers prior to emulation.

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

Returns
  • the number of PC-conversions performed

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

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

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

public abstract String formatStatistics ()

Generate statistics about this converter.

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

public abstract int getAddressBitsize ()

Get the size of a native address, in bits.

public abstract INativeDecompilerContext getDecompiler ()

Retrieve a reference to the decompiler managing this converter.

Returns

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

public abstract IEVar getFPRegister (int index)

Retrieve the IR variable object that represents the Floating-point register.

Parameters
index register index

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

public abstract IEGlobalContext getGlobalContext ()

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

Returns
  • the global context

public abstract IEVar getInputVariableByIndex (IERoutineContext ctx, int i)

public abstract INativeContext getNativeContext ()

Retrieve the native code context that this converter should use.

Returns
  • never null

public abstract long getNativeRegisterIdFromRegisterVariable (IEVar regVar, boolean shortForm)

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 getRegisterName(long)), otherwise it is the long form
Returns
  • a native register id
Throws
DecompilerException if the conversion failed

public abstract long getNativeRegisterIdFromRegisterVariable (IEVar regVar)

Throws
DecompilerException if the conversion failed

public abstract IEVar getOutputVariableByIndex (IERoutineContext ctx, int i)

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

public abstract IEGeneric getRegister (String name)

public abstract int getRegisterBitsize ()

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

public abstract IEGeneric getRegisterVariableFromNativeRegisterId (long nativeRegId)

Returns
Throws
DecompilerException if the conversion failed

public abstract IEGeneric getRegisterVariableFromNativeRegisterId (long nativeRegId, ELocation loc)

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 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
Throws
DecompilerException if the conversion failed

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 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
Returns
  • null if the slice does not have a particular name

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 int getStateProcessorMode (EState state)

Retrieve the current processor mode relative to the provided EState. Refer to getMode() for the semantics of mode.

Parameters
state optional IR state
Returns
  • the processor mode (most often 8, 16, 32 or 64)

public abstract IEVar getTempRegister (int index)

public abstract IWildcardType.Group getWildcardTypeManagerDefaultResolutionGroup ()

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 (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

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

public abstract Boolean isSegmentEMemReferencingPrimaryMemory (IEMem e)

Determine if an IEMem 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 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

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

public abstract long sanitizeNativeAddress (long address)