# Interface: com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStatement Base class for all IR statements. Statements are specialized expressions. The most common statement is [IEAssign](IEAssign). Additional statements introduced as the IR gets optimized and refined are: [IENop](IENop), [IECall](IECall), [IEReturn](IEReturn), [IEJump](IEJump), and [IEJumpFar](IEJumpFar), [IESwitch](IESwitch) and the almighty [IEUntranslatedInstruction](IEUntranslatedInstruction). ## Static Field: FLAG_LIKELY_EPILOGUE Type: `int` Constant value: `8` Description: This instruction has been identified as being part of an epilogue stub. A routine's epilogue is a small instruction stub responsible for restoring registers previously saved by the prologue as well as freeing space that may have been allocated on the stack. ## Static Field: FLAG_LIKELY_PROLOGUE Type: `int` Constant value: `4` Description: This instruction has been identified as being part of a prologue stub. A routine's prologue is a small instruction stub responsible for saving registers that need to be preserved as well as allocating some space on the stack. **Implementation note:** currently, instructions flagged as such are likely to be `STACK_VAR=REG_TO_SAVE` assignments. ## Static Field: FLAG_OPT_BLOCK_PROPAGATION Type: `int` Constant value: `1` Description: Statement having this flag cannot be propagated, i.e. they cannot be the source \(replacement\) expression in substituted expressions. Note: even in [aggressive](OptimizerMode#AGGRESSIVE) mode, this flag is NOT ignored. In the example below, r0 in instruction A will not be propagated to B. ``` A) r0 = r1 <---- flagged ... B) r4 = .... + r0 + ... ``` ## Static Field: FLAG_OPT_BLOCK_SUBSTITUTIONS Type: `int` Constant value: `2` Description: Statement having this flag cannot be the recipient of substituted expressions propagated by an expression optimizer. Note: even in [aggressive](OptimizerMode#AGGRESSIVE) mode, this flag is NOT ignored. In the example below, r0 in instruction A could be \(under conditions\) substituted in instruction B. However, if instruction B has [#FLAG_OPT_BLOCK_SUBSTITUTIONS](#FLAG_OPT_BLOCK_SUBSTITUTIONS) set, that candidate substitution will be prevented, regardless of other factors. ``` A) r0 = r1 ... B) r4 = .... + r0 + ... <---- flagged ``` Note that this flag does not prevent the statement itself to be the source of a substitution. \(To prevent that, use [#FLAG_OPT_BLOCK_PROPAGATION](#FLAG_OPT_BLOCK_PROPAGATION).\) In the example below, r0 of A can be propagated to B \(with A ending up discarded\), even though A is flagged. ``` A) r0 = r1 <---- flagged ... B) r4 = .... + r0 + ... ``` ## Method: addLowerLevelAddress - parameter: `address`, type: `long` Description: Add another native instruction address mapping to this IR statement. parameter: address: ## Method: addLowerLevelAddresses - parameter: `addresses`, type: `java.util.Collection` Description: Add a collection of native instructions addresses mapping to this IR statement. parameter: addresses: ## Method: asAssign - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEAssign` ## Method: asCall - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IECall` ## Method: asJump - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEJump` ## Method: asJumpFar - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEJumpFar` ## Method: asNop - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IENop` ## Method: asReturn - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEReturn` ## Method: asSwitch - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IESwitch` ## Method: asUntranslated - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEUntranslatedInstruction` ## Method: collectSubExpressions - parameter: `sink`, type: `java.util.Collection` - parameter: `usedOnly`, type: `java.lang.Boolean` Description: Perform a shallow collection of the sub\-expressions of this statement. All collected expressions are directly rooted in this IRE \(i.e. their parent is this IR expression\). parameter: sink: recipient \(elements are appended\) parameter: usedOnly: if null: all top\-level elements are collected \(same as [#collectSubExpressions(Collection)](#collectSubExpressions(Collection))\); else: \- if false: only defined \(written\) top\-level sub\-expressions are collected \- if true: only used \(read\) top\-level sub\-expressions are collected ## Method: collectSubExpressions - parameter: `sink`, type: `java.util.Collection` ## Method: collectUsedExpressions - parameter: `sink`, type: `java.util.Collection>` Description: Perform a shallow collection of the first\-level expressions *used* by this statement. Invoking this method is not the same as calling `collectSubExpressions(sink, true)`\! This method examines top\-level defined \(written\) expressions that are `EMem`; the memory reference of those EMems are returned. Therefore, not all values returned by this method are directly rooted in this IRE. It is for that reasons that this method returns a collection of tuples \(parent, expression\) instead of a simple collection of expressions. parameter: sink: a collection of tuples \(parent, expression\) ## Method: copyLowerLevelAddresses - parameter: `srcStm`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStatement` Description: Copy \(add\) the native addresses of the instruction to this statement's mapping. Watch out\! The current statement's mapping is not reset before copying. parameter: srcStm: ## Method: copyProperties - parameter: `srcStm`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStatement` Description: Copy over the generic statement properties of the source statement onto this statement. Only generic \(common\) properties should be ported. The [context](#getContext()) is not copied over. Some properties are overwritten, others are completed \(augmented\). parameter: srcStm: source statement ## Method: equalsEx - parameter: `obj`, type: `java.lang.Object` - parameter: `includeType`, type: `boolean` - parameter: `includeContext`, type: `boolean` - return type: `boolean` Description: Same as [Object#equals(Object)](Object#equals(Object)) with the possibility to exclude some properties from the comparison. parameter: obj: object to compare parameter: includeType: true to include the type in the equality test parameter: includeContext: true to include the statement's [bound IR context](IERoutineContext) in the equality check return: true if equal ## Method: equalsEx - parameter: `obj`, type: `java.lang.Object` - parameter: `includeType`, type: `boolean` - parameter: `includeContext`, type: `boolean` - parameter: `includeSize`, type: `boolean` - return type: `boolean` Description: Same as [Object#equals(Object)](Object#equals(Object)) with the possibility to exclude some properties from the comparison. parameter: obj: object to compare parameter: includeType: true to include the type in the equality test parameter: includeContext: true to include the statement's [bound IR context](IERoutineContext) in the equality check parameter: includeSize: true to include the statement's size in the equality check return: true if equal ## Method: generateC - 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` ## Method: getContext - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext` Description: Get the decompiled routine context that owns this statement. return: ## Method: getDefUse - parameter: `defuse`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EDefUseInfo` Description: A variant of [#getDefUse(java.util.List, java.util.List, Object)](#getDefUse(java.util.List, java.util.List, Object)) used to retrieve the range of vbits defined and used by the statement. parameter: defuse: ## Method: getDefUseInfo - parameter: `instructionAddress`, type: `long` - parameter: `flags`, type: `int` - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EDefUseInfo` ## Method: getLowerLevelAddresses - return type: `java.util.Collection` Description: return: the returned collection does not contain duplicates; the first entry is the primary lower\-level address \(if there are multiple native addresses mapping to this IR statement, [#getLowerLevelAddresses()](#getLowerLevelAddresses()) would return 2\+ entries\) ## Method: getPrimaryLowerLevelAddress - return type: `java.lang.Long` Description: return: the primary native address; null if this IR does not contain lower\-mapping information ## Method: getSPDelta - return type: `java.lang.Integer` Description: Retrieve the optional stack\-pointer delta indicator. The SP delta represents the native delta in bytes, relative to SP0 \(stack pointer at the underlying native routine entry\-point\), before the closest matching native instruction is executed. return: optional native SP delta ## Method: isAssign - return type: `boolean` ## Method: isAssignTo - parameter: `dst`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar` - return type: `boolean` ## Method: isAssignTo - parameter: `dstVarid`, type: `int` - return type: `boolean` ## Method: isAssignToVar - return type: `boolean` ## Method: isCall - return type: `boolean` ## Method: isConditionalJump - return type: `boolean` Description: Determine if this IR is a conditional [IEJump](IEJump), i.e. [IEJump#getCondition()](IEJump#getCondition()) is not null. return: ## Method: isConditionalJumpFar - return type: `boolean` ## Method: isJump - return type: `boolean` ## Method: isJumpFar - return type: `boolean` ## Method: isNop - return type: `boolean` ## Method: isReturn - return type: `boolean` ## Method: isSwitch - return type: `boolean` ## Method: isUnconditionalJump - return type: `boolean` Description: Determine if this IR is a simple `goto`, that is, an unconditional [IEJump](IEJump), i.e. [IEJump#getCondition()](IEJump#getCondition()) is null. return: ## Method: isUnconditionalJumpFar - return type: `boolean` ## Method: isUntranslatedInstruction - return type: `boolean` ## Method: postUpdateTypes - parameter: `ti`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.ETypeInfo` Description: Called once by the normalizer component in later stages. Implementations may perform IRE replacement, unlike [updateTypes's](#updateTypes(ETypeInfo)). parameter: ti: optional type information object that will collect the operation's result ## Method: preUpdateTypes - parameter: `ti`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.ETypeInfo` Description: Called once by the type setter component during the typing stage, before propagating all types to the IR elements. Implementations may perform IRE replacement, unlike [updateTypes's](#updateTypes(ETypeInfo)). parameter: ti: optional type information object that will collect the operation's result ## Method: removeLowerLevelAddress - parameter: `address`, type: `long` Description: Remove a native instruction address from the list of mappings. parameter: address: ## Method: replaceDefinedVar - parameter: `var`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar` - parameter: `repl`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric` - return type: `int` Description: Replace \(deep\) the variables that are defined by this statement. parameter: var: parameter: repl: return: ## Method: replaceUsedVar - parameter: `var`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar` - parameter: `repl`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric` - return type: `int` Description: Replace \(deep\) the variables that are defined by this statement. parameter: var: the IEVar to be replaced parameter: repl: the replacement expression return: the number of replacements throws: if an illegal replacement was attempted ## Method: replaceVar - parameter: `var`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar` - parameter: `repl`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric` - parameter: `doNotReplaceDefinedVariables`, type: `boolean` - return type: `int` Description: Deep replace. Specialized version allows used\-vars replacement only. The implementation is responsible for IRE duplication before statements, to ensure that the resulting statement or group of statement does not contain duplicate references to mutable objects. parameter: var: the IEVar to be replaced parameter: repl: the replacement expression parameter: doNotReplaceDefinedVariables: return: the number of replacements throws: if an illegal replacement was attempted ## Method: resetLowerLevelAddress Description: Reset the current mapping for native instruction addresses for this statement. ## Method: resetLowerLevelAddresses Description: Reset the current mapping for native instruction addresses for this statement. ## Method: setLowerLevelAddress - parameter: `address`, type: `long` Description: Reset the current mapping and add a single native instruction address mapping to this IR statement. Watch out\! A statement should at least have one associated native address. parameter: address: ## Method: setLowerLevelAddresses - parameter: `addresses`, type: `java.util.Collection` Description: Reset the current mapping and add a collection of native instructions addresses mapping to this IR statement. Watch out\! A statement should at least have one associated native address. parameter: addresses: ## Method: setPrimaryLowerLevelAddress - parameter: `addr`, type: `long` ## Method: setSPDelta - parameter: `delta`, type: `java.lang.Integer` Description: Set an optional stack\-pointer delta indicator. The SP delta represents the native delta in bytes, relative to SP0 \(stack pointer at the underlying native routine entry\-point\), before the closest matching native instruction is executed. parameter: delta: optional native SP delta ## Method: visitInstruction - parameter: `visitor`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVisitor` - return type: `boolean` Description: Depth\-first search, pre\-order visit of this statement. The node being visited may be replaced, but the client code is responsible for `setReplacedNode` notifying the visitor. Pre\-order visits offer more options than post order visits: the visitor may decide to skip children; to skip the destination of assignments. However, replacement of nodes requires additional code to register the new node. Conversely, post\-order visits do not offer any specific option, but provide the simplest way to replace nodes. parameter: visitor: the visitor object return: true if the visit was successful ## Method: visitInstruction - parameter: `visitor`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVisitor` - parameter: `skipAssignmentDestination`, type: `boolean` - return type: `boolean` Description: Depth\-first search, pre\-order visit of this statement. The node being visited may be replaced, but the client code is responsible for `setReplacedNode` notifying the visitor. Pre\-order visits offer more options than post order visits: the visitor may decide to skip children; to skip the destination of assignments. However, replacement of nodes requires additional code to register the new node. Conversely, post\-order visits do not offer any specific option, but provide the simplest way to replace nodes. parameter: visitor: the visitor object parameter: skipAssignmentDestination: true if the destination of an assignment \(if this statement is an EAssign\) should not be visited return: true if the visit was successful ## Method: visitInstructionPostOrder - parameter: `visitor`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVisitor` - parameter: `skipAssignmentDestination`, type: `boolean` - return type: `boolean` Description: Depth\-first search, post\-order visit of this statement. The node being visited may be replaced without notifying the visitor. Pre\-order visits offer more options than post order visits: the visitor may decide to skip children; to skip the destination of assignments. However, replacement of nodes requires additional code to register the new node. Conversely, post\-order visits do not offer any specific option, but provide the simplest way to replace nodes. parameter: visitor: the visitor object parameter: skipAssignmentDestination: true if the destination of an assignment \(if this statement is an EAssign\) should not be visited return: true if the visit was successful ## Method: withLowerLevelAddress - parameter: `address`, type: `long` - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStatement` ## Method: withLowerLevelAddresses - parameter: `addresses`, type: `java.util.Collection` - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStatement` ## Method: writesMemory - return type: `boolean` Description: Retrieve an indication regarding whether this statement writes to memory. return: