# 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` - return type: `java.util.List` 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` - parameter: `outSpoiled`, type: `java.util.List` - return type: `java.util.List` 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` - 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` - 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` - parameter: `b`, type: `com.pnfsoftware.jeb.core.units.code.asm.cfg.BasicBlock` - 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