# 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 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: true if the pipeline may create additional calls

## 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: routine context
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: routine context
parameter: prototype: call prototype
parameter: targetRoutine: optional target routine
parameter: varArgTypes: optional variable argument types
parameter: outSpoiled: optional sink for spoiled register expressions
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: routine context
parameter: prototype: call prototype
return: the return address location expression, or null if unavailable

## 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: stack memory address expression
parameter: bitsize: access size, in bits
return: a stack memory access expression

## 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: input state to customize
parameter: optionalNativeProgramCounter: optional current native PC

## 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: routine context
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: call prototype
parameter: varArgTypes: optional variable argument types
return: the number of stack bytes used by the call, or null on error

## 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: call prototype
parameter: varArgTypes: optional variable argument types
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: untranslated IR instruction
parameter: ectx: IR routine context
parameter: state: current evaluation state
return: the evaluated immediate value, or null if no value can be produced

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

Description: Generate statistics about this converter.
return: formatted converter statistics

## 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: untranslated IR instruction
parameter: ectx: IR routine context
parameter: cctx: C method context
return: the generated C statement, or null to use the default generator

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

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

## 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 call\-site resolution heuristics.
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: the floating\-point register variable, or null if unavailable

## 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: the general\-purpose register variable, or null if unavailable

## 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: Retrieve an input variable by index.
parameter: ctx: routine context
parameter: i: input variable index
return: the input variable, or null if unavailable

## 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: a global [IEVar](IEVar)\-register
return: a native register id
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: Retrieve an output variable by index.
parameter: ctx: routine context
parameter: i: output variable index
return: the output variable, or null if unavailable

## 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: routine context
return: a prototype handler

## 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: the register expression, or null if no such register exists

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

Description: Retrieve an [IEVar](IEVar)\-register by its name, without conversion location information.
parameter: name: register name
return: the register expression, or null if no such register exists

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

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

## 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: native register id or number
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: slice start bit
parameter: bitend: slice end bit
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 a standard slot on the stack, in bytes.
return: the stack slot size, in bytes

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

Description: Retrieve a temporary register variable.
parameter: index: temporary register index
return: the temporary register variable, or null if unavailable

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

Description: Get the wildcard type resolution group to use by default.
return: the default wildcard type resolution group

## 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.
parameter: e: memory expression to examine
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: the normalized branching expression

## 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: routine context
return: true if custom call resolution changed the routine

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

Description: Normalize a native address for this converter.
parameter: address: a native address
return: the normalized native address

