public abstract class

AbstractConverter

extends Object
implements IEConverter<InsnType extends IInstruction>
java.lang.Object
   ↳ com.pnfsoftware.jeb.core.units.code.asm.decompiler.AbstractConverter<InsnType extends com.pnfsoftware.jeb.core.units.code.IInstruction>

Class Overview

A skeleton for code converters. TODO: documentation + examples.

Summary

Fields
protected IERoutineContext ctx Per-routine data - works because convert() is not re-entrant (same found in X86ConvXxx helper classes).
protected boolean doNotGenerateNops
protected IEGlobalContext gCtx
protected IProcessor<InsnType extends IInstruction> proc
protected int regNormalBitsize
Protected Constructors
AbstractConverter(IProcessor<InsnType> proc, int regNormalBitsize)
Public Methods
IWildcardPrototype buildFailsafePrototype(IERoutineContext ctx, IEStatement stm)
Create a simple, failsafe prototype for the given routine.
IERoutineContext convert(INativeMethodItem routine)
Convert a routine.
final IERoutineContext convert(INativeMethodItem routine, boolean delayBuild)
Convert the blocks of the native routine's CFG after the other.
final List<IEStatement> convertBlockForTest(BasicBlock<InsnType> b)
Should be accessed externally for testing only.
List<IEGeneric> convertParameterExpressions(IWildcardPrototype prototype, int varArgCount)
Given a prototype, determine the list of IR expressions representing the input expressions (would also contain implicitly read registers).
List<IEGeneric> convertReturnExpressions(IWildcardPrototype prototype)
Given a prototype, determine the list of IR expressions representing the output expressions (would also contain spoiled registers, which are implicitly written).
IEGeneric convertReturnLocation(IWildcardPrototype prototype)
Given a prototype, determine the IR expression representing the return address location of a call to a method of said prototype.
IEMem createStackMemoryAccess(IEGeneric address, int bitsize)
The default implementation assumes a segment-less memory model (The EMem segment is set to null).
int defaultPCConversion(IERoutineContext ctx)
Convert PC-assignment to EJumpFar statements.
int determineStackPointerDeltaAfterIRCall(IWildcardPrototype prototype)
Given a prototype, determine the stack pointer delta (in bytes) after the ECall executed and returned.
int getAddressBitsize()
The default implementation returns the size of the program counter.
INativeDecompilerUnit<InsnType> getDecompiler()
Reserved.
IEGlobalContext getGlobalContext()
Retrieve the global program context.
int getProcessorMode(IEState state)
Retrieve the current processor mode relative to this EState.
int getRegisterBitsize()
The default implementation returns the address bitsize.
IEVar getReturnAddressRegister()
The default implementation considers that there is no specific Return Address Register.
void initializeStateRegisters(IEState state, Long optionalNativeProgramCounter)
The default implementation initializes and sets all physical registers declared by this converter to 0.
final int insertReturns(IERoutineContext _ctx)
This method introduces EReturn statements into the IR.
boolean isDoNotGenerateNops()
boolean resolveCustomCalls(INativeCodeUnit<?> pbcu, IERoutineContext ctx)
Implementations should be aggressive and fast: calls to this method should always be enclosed in a try-catch.
void setDecompiler(INativeDecompilerUnit<InsnType> decompiler)
Reserved.
void setDoNotGenerateNops(boolean doNotGenerateNops)
Protected Methods
abstract void convertBlock(BasicBlock<InsnType> b, List<IEStatement> interlist)
Convert a block.
boolean insertOptionalEntryPointTrampoline(IERoutineContext ctx, List<IEStatement> IRStatementList)
For native routines that have their entry point in-the-middle (ie, not at their lowest address), insert a synthetic IEJump as the first instruction of the converted method.
boolean isPCRightValueCompatibleReturnValue(BasicBlock<IEStatement> b, IEGeneric PCRightVal, IEGeneric expectedReturnAddress)
Can be overridden by implementors when complex return expression matching is needed.
void postBlockConversion(CFG<InsnType> cfg, BasicBlock<InsnType> b, List<IEStatement> interlist, int cnt)
This method is called after convertBlock(BasicBlock, List) is called.
BasicBlock<InsnType> preBlockConversion(CFG<InsnType> cfg, BasicBlock<InsnType> b, List<IEStatement> interlist)
This method is called before convertBlock(BasicBlock, List) is called.
void setCurrentContext(IERoutineContext ctx)
setup the helper converter classes
[Expand]
Inherited Methods
From class java.lang.Object
From interface com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEConverter

Fields

protected IERoutineContext ctx

Per-routine data - works because convert() is not re-entrant (same found in X86ConvXxx helper classes).
Should be set before converting a routine, and reset to null after it's done.

protected boolean doNotGenerateNops

protected IEGlobalContext gCtx

protected IProcessor<InsnType extends IInstruction> proc

protected int regNormalBitsize

Protected Constructors

protected AbstractConverter (IProcessor<InsnType> proc, int regNormalBitsize)

Public Methods

public 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 IERoutineContext convert (INativeMethodItem routine)

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

public final IERoutineContext convert (INativeMethodItem routine, boolean delayBuild)

Convert the blocks of the native routine's CFG after the other. The blocks' edges are not considered.

Parameters
routine the routine to be converted; must have a CodeRoutineItem#getData() 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 final List<IEStatement> convertBlockForTest (BasicBlock<InsnType> b)

Should be accessed externally for testing only.

public List<IEGeneric> convertParameterExpressions (IWildcardPrototype prototype, int varArgCount)

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

Used by ECall.

public List<IEGeneric> convertReturnExpressions (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 IEGeneric convertReturnLocation (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 IEMem createStackMemoryAccess (IEGeneric address, int bitsize)

The default implementation assumes a segment-less memory model (The EMem segment is set to null).

public int defaultPCConversion (IERoutineContext ctx)

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

Returns
  • the number of PC-conversions performed

public int determineStackPointerDeltaAfterIRCall (IWildcardPrototype prototype)

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.

public int getAddressBitsize ()

The default implementation returns the size of the program counter.

public INativeDecompilerUnit<InsnType> getDecompiler ()

Reserved.

public 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 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 int getRegisterBitsize ()

The default implementation returns the address bitsize.

public IEVar getReturnAddressRegister ()

The default implementation considers that there is no specific Return Address Register. Override if one exists.

Returns
  • can return null value if Processor does not use Return Address Register

public void initializeStateRegisters (IEState state, Long optionalNativeProgramCounter)

The default implementation initializes and sets all physical registers declared by this converter to 0.

Parameters
state input state to be initialized
optionalNativeProgramCounter optional current native PC

public final 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 boolean isDoNotGenerateNops ()

public 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

public void setDecompiler (INativeDecompilerUnit<InsnType> decompiler)

Reserved.

public void setDoNotGenerateNops (boolean doNotGenerateNops)

Protected Methods

protected abstract void convertBlock (BasicBlock<InsnType> b, List<IEStatement> interlist)

Convert a block.

Parameters
b block to be converted
interlist output list of converted IR statements

protected boolean insertOptionalEntryPointTrampoline (IERoutineContext ctx, List<IEStatement> IRStatementList)

For native routines that have their entry point in-the-middle (ie, not at their lowest address), insert a synthetic IEJump as the first instruction of the converted method.

By using this trick, we ensure that native routines that have their entry-point in the middle of their code can be converted to IR routines with an entry-point always set to offset 0 (the beginning of the IR code). The reason is that this helps with graph manipulation passes that come later on, in the AST phases.

Parameters
ctx translation context
IRStatementList global list of converted IR-statements, should be empty when this method is called
Returns
  • true if a trampoline was inserted, false if it was not needed (and therefore, not inserted)

protected boolean isPCRightValueCompatibleReturnValue (BasicBlock<IEStatement> b, IEGeneric PCRightVal, IEGeneric expectedReturnAddress)

Can be overridden by implementors when complex return expression matching is needed.

Parameters
b BasicBlock containing the PC assign instruction
PCRightVal right Value of the PC assign instruction
expectedReturnAddress Expected IEVar as per current Calling Convention
Returns
  • true if right value is equivalent to a return instruction

protected void postBlockConversion (CFG<InsnType> cfg, BasicBlock<InsnType> b, List<IEStatement> interlist, int cnt)

This method is called after convertBlock(BasicBlock, List) is called. The default implementation makes sure the block end is valid by inserting an IEJumpFar if it does not appear to be properly terminated.

Parameters
cfg the native CFG of the method being converted
b the native basic block that was just converted
interlist the current list of IR statements for the routine (not only for the provided block!); the last IR statements in that list are those of the routine that was just converted
cnt the number of IR statements that correspond to the conversion of the provided native block

protected BasicBlock<InsnType> preBlockConversion (CFG<InsnType> cfg, BasicBlock<InsnType> b, List<IEStatement> interlist)

This method is called before convertBlock(BasicBlock, List) is called. It can be overridden; sub-classes do not need to call the default implementation. The default returns the provided input block.

Parameters
cfg the CFG
b block about to be converted
Returns
  • the provided input block or a new block

protected void setCurrentContext (IERoutineContext ctx)

setup the helper converter classes