# Interface: com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEConverter

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](AbstractConverter) class instead.

## Method: buildFailsafePrototype
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- parameter: `stm`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStatement`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardPrototype`

Description: Create a simple, failsafe prototype for the given routine.
parameter: ctx: routine for which a failsafe prototype is to be generated
parameter: stm: optional statement calling into the routine
return: a prototype object, should never be null

## Method: canCreateCalls
- return type: `boolean`

Description: Determine if the decompilation pipeline is allowed to create more [IECall](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](#convertReturnExpressions(IERoutineContext, IWildcardPrototype, INativeMethodItem, List, List)), [convertParameterExpressions](#convertParameterExpressions(IERoutineContext, IWildcardPrototype, INativeMethodItem, List)), [convertReturnLocation](#convertReturnLocation(IERoutineContext, IWildcardPrototype)), etc.\) in pipeline stages may want to return false.
return: 

## Method: convert
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`

Description: Convert a native code routine to its initial intermediate representation. The initial IR consists only of [IEAssign](IEAssign), [IEJump](IEJump), [IENop](IENop) and [IEUntranslatedInstruction](IEUntranslatedInstruction) statements. Each statement instruction must have a [size](IEStatement#getSize()) of 1. The resulting IR is verified and the initial IR\-CFG created.
parameter: routine: the routine to be converted; must have a [data](INativeMethodItem#getData()) definition
return: the converted IR routine context

## Method: convertParameterExpressions
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- parameter: `prototype`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardPrototype`
- parameter: `targetRoutine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- parameter: `varArgTypes`, type: `java.util.List<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardType>`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric>`

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

 Used by [IECall](IECall).
parameter: ctx: 
parameter: prototype: mandatory prototype
parameter: targetRoutine: optional
parameter: varArgTypes: optional
return: a list of non\-copy IEVars holding storage of input expressions

## Method: convertReturnExpressions
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- parameter: `prototype`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardPrototype`
- parameter: `targetRoutine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- parameter: `varArgTypes`, type: `java.util.List<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardType>`
- parameter: `outSpoiled`, type: `java.util.List<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric>`
- return type: `java.util.List<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric>`

Description: Given a prototype, determine the list of IR expressions representing the output expressions. Spoiled register expressions can also be returned. 

 Used by [IECall](IECall).
parameter: ctx: 
parameter: prototype: 
parameter: targetRoutine: 
parameter: varArgTypes: 
parameter: outSpoiled: 
return: a list of non\-copy IEVars holding storage of output expressions

## Method: convertReturnLocation
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- parameter: `prototype`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardPrototype`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric`

Description: Given a prototype, determine the IR expression representing the return address **location** of a call to a method of said prototype. 

 Used by [IECall](IECall).
parameter: ctx: 
parameter: prototype: 
return: 

## Method: createStackMemoryAccess
- parameter: `address`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric`
- parameter: `bitsize`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEMem`

Description: Create an EMem using the adequate segment register \(if any\) for the current converter.
parameter: address: 
parameter: bitsize: 
return: 

## Method: customInitStateRegisters
- parameter: `state`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState`
- parameter: `optionalNativeProgramCounter`, type: `java.lang.Long`

Description: Custom/specific initialization of registers prior to emulation.
parameter: state: 
parameter: optionalNativeProgramCounter: 

## Method: defaultPCConversion
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- return type: `int`

Description: Convert PC\-assignment to [IEJumpFar](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.
parameter: ctx: 
return: the number of PC\-conversions performed

## Method: determineStackBytesUsedByCall
- parameter: `prototype`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardPrototype`
- parameter: `varArgTypes`, type: `java.util.List<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardType>`
- return type: `java.lang.Integer`

Description: 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](IECall).
parameter: prototype: 
parameter: varArgTypes: 
return: 

## Method: determineStackPointerDeltaAfterIRCall
- parameter: `prototype`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardPrototype`
- parameter: `varArgTypes`, type: `java.util.List<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardType>`
- return type: `java.lang.Integer`

Description: Determine the stack pointer delta \(in bytes\) after the [IECall](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](IECall). 

 Used by [IECall](IECall).
parameter: prototype: 
parameter: varArgTypes: 
return: null on error

## Method: determineStackPointerDeltaFromSimulation
- parameter: `simuinfo`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.SimulationPointInformation`
- return type: `java.lang.Integer`

Description: 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.
parameter: simuinfo: state of IR execution; PC is assumed to be on the target routine entry\-point
return: null on error, otherwise, the SP delta after the routine has executed and returned to         the caller

## Method: evaluateUntranslatedIR
- parameter: `insn`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEUntranslatedInstruction`
- parameter: `ectx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- parameter: `state`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`

Description: Evaluate untranslated IR instructions. This method is preferred to the internal evaluator, which currently throws by default when attempting to evaluate an [IEUntranslatedInstruction](IEUntranslatedInstruction). 

 The default implementation returns null.
parameter: insn: 
parameter: ectx: 
parameter: state: 
return: 

## Method: formatStatistics
- return type: `java.lang.String`

Description: Generate statistics about this converter.
return: 

## Method: generateASTForUntranslatedIR
- parameter: `insn`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEUntranslatedInstruction`
- parameter: `ectx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- parameter: `cctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ast.ICMethod`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ast.ICStatement`

Description: Generate C statement from an untranslated IR instruction. This method is preferred to the internal generator, which produces [ICCustomStatement](ICCustomStatement) wrapping [IEUntranslatedInstruction](IEUntranslatedInstruction).
parameter: insn: 
parameter: ectx: 
parameter: cctx: 
return: 

## Method: getAddressBitsize
- return type: `int`

Description: Get the size of a native address, in bits.
return: 

## Method: getDecompiler
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.INativeDecompilerContext`

Description: Retrieve a reference to the decompiler managing this converter.
return: a reference to a decompiler \(likely, a [INativeDecompilerUnit](INativeDecompilerUnit)\), or null

## Method: getDefaultBranchToRoutineSideEffects
- parameter: `optionalRoutine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEBranchDetails`

Description: 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](IECallsiteResolver).
parameter: optionalRoutine: the optional target routine; if provided, the implementation may use            that information to provide more accurate results
return: a branch details object \(never null\)

## Method: getFPRegister
- parameter: `index`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`

Description: Retrieve the IR variable object that represents the Floating\-point register.
parameter: index: register index
return: 

## Method: getGPRegister
- parameter: `index`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`

Description: Retrieve the IR variable object that represents the General Purpose register.
parameter: index: register index \(eg 0 for x86 eax, ARM R0, Arm64 X0...\)
return: 

## Method: getGlobalContext
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEGlobalContext`

Description: Retrieve the global program context. There is a single global context per decompiler, common to all [routine contexts](IERoutineContext).
return: the global context

## Method: getInputVariableByIndex
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- parameter: `i`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`

Description: 
parameter: ctx: 
parameter: i: 
return: 

## Method: getNativeContext
- return type: `com.pnfsoftware.jeb.core.units.code.asm.INativeContext`

Description: Retrieve the native code context that this converter should use.
return: never null

## Method: getNativeRegisterIdFromRegisterVariable
- parameter: `regVar`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`
- parameter: `shortForm`, type: `boolean`
- return type: `long`

Description: Get the native platform register number or id \(as defined in a register bank layout\) corresponding to the provided [IEVar](IEVar)\-register IR variable.
parameter: regVar: a global [IEVar](IEVar)\-register
parameter: shortForm: if true the value provided does not contain the converter\-specific            information present in the long form \(used in particular by            [IInstructionOperandRegisterBased#getRegisterName(long)](IInstructionOperandRegisterBased#getRegisterName(long))\), otherwise it is            the long form
return: a native register id
throws: if the conversion failed

## Method: getNativeRegisterIdFromRegisterVariable
- parameter: `regVar`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`
- return type: `long`

Description: Same as [getNativeRegisterIdFromRegisterVariable\(IEVar, false\)](#getNativeRegisterIdFromRegisterVariable(IEVar, boolean)).
parameter: regVar: 
return: 
throws: if the conversion failed

## Method: getOutputVariableByIndex
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- parameter: `i`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`

Description: 
parameter: ctx: 
parameter: i: 
return: 

## Method: getProgramCounter
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`

Description: Retrieve the IR variable object that represents the program counter.
return: never null

## Method: getPrototypeHandler
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEPrototypeHandler`

Description: Create an instance of a prototype handler.
parameter: ctx: 
return: 

## Method: getRegister
- parameter: `name`, type: `java.lang.String`
- parameter: `loc`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.ELocation`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric`

Description: Retrieve an [IEVar](IEVar)\-register by its name.
parameter: name: register name
parameter: loc: optional IR statement location at which the conversion is taking place
return: 

## Method: getRegister
- parameter: `name`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric`

Description: 
parameter: name: 
return: 

## Method: getRegisterBitsize
- return type: `int`

Description: Get the size of a standard, general\-purpose native register, in bits.
return: 

## Method: getRegisterVariableFromNativeRegisterId
- parameter: `nativeRegId`, type: `long`
- parameter: `loc`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.ELocation`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric`

Description: Get the [IEVar](IEVar)\-register IR variable representing a native platform register number or id \(as defined in a register bank layout\).
parameter: nativeRegId: a native register id, used by the [IProcessor](IProcessor) that this converter            is relying on; the id may be a full id, that is, one supported by            [IInstructionOperandRegisterBased#getRegisterName(long)](IInstructionOperandRegisterBased#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\).
parameter: loc: optional IR statement location at which the conversion is taking place
return: a global [IEVar](IEVar)\-register
throws: if the conversion failed

## Method: getRegisterVariableFromNativeRegisterId
- parameter: `nativeRegId`, type: `long`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric`

Description: See [#getRegisterVariableFromNativeRegisterId(long, ELocation)](#getRegisterVariableFromNativeRegisterId(long, ELocation)). No location provided
parameter: nativeRegId: 
return: a global [IEVar](IEVar)\-register
throws: if the conversion failed

## Method: getReturnAddressRegister
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`

Description: Retrieve the IR variable object that represents the return address register.
return: can return null value if Processor does not use Return Address Register

## Method: getSlicedRegisterName
- parameter: `registerName`, type: `java.lang.String`
- parameter: `bitstart`, type: `int`
- parameter: `bitend`, type: `int`
- return type: `java.lang.String`

Description: 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.
parameter: registerName: full name of a physical register
parameter: bitstart: 
parameter: bitend: 
return: null if the slice does not have a particular name

## Method: getStackPointer
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`

Description: Retrieve the IR variable object that represents the stack pointer.
return: never null

## Method: getStackSlotSize
- return type: `int`

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

## Method: getStateProcessorMode
- parameter: `state`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState`
- return type: `int`

Description: Retrieve the current processor mode relative to the provided [EState](EState). Refer to [IProcessor#getMode()](IProcessor#getMode()) for the semantics of mode.
parameter: state: optional IR state
return: the processor mode \(most often 8, 16, 32 or 64\)

## Method: getTempRegister
- parameter: `index`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar`


## Method: getWildcardTypeManagerDefaultResolutionGroup
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IWildcardType.Group`

Description: 
return: 

## Method: initialize

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

## Method: initializeStateRegisters
- parameter: `state`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState`
- parameter: `optionalNativeProgramCounter`, type: `java.lang.Long`

Description: Initialize the registers of an IR execution state to safe defaults.
parameter: state: input state to be initialized
parameter: optionalNativeProgramCounter: optional current native PC

## Method: insertReturns
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- return type: `int`

Description: This method introduces [IEReturn](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.
parameter: ctx: the routine context
return: the number of insertions performed

## Method: isSegmentEMemReferencingPrimaryMemory
- parameter: `e`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEMem`
- return type: `java.lang.Boolean`

Description: Determine if an [IEMem](IEMem) references bytes in the primary, unit\-code managed virtual memory object, or some other memory object.
return: 3\-state result: true/false, null= cannot determine

## Method: normalizeBranchingExpression
- parameter: `dfa`, type: `com.pnfsoftware.jeb.core.units.code.IDFA<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStatement>`
- parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.asm.cfg.BasicBlock<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStatement>`
- parameter: `callsite`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric`
- parameter: `expectedTarget`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric`

Description: Normalize a branching expression.
parameter: dfa: a DFA object
parameter: b: basic block whose last instruction is a branching statement \(e.g. EAssign to PC,            ECall, EJumpFar, etc.\)
parameter: callsite: the callsite of the branching statement targeted by the basic block \`b\`
parameter: expectedTarget: optional
return: 

## Method: resolveCustomCalls
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- return type: `boolean`

Description: Implementations should be aggressive and fast: calls to this method should always be enclosed in a try\-catch. 

 TODO: MOVE to the CBDU
parameter: ctx: 
return: 

## Method: sanitizeNativeAddress
- parameter: `address`, type: `long`
- return type: `long`

Description: 
parameter: address: 
return: 

