public interface

IEGeneric

implements IInstructionOperand
com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric
Known Indirect Subclasses

Class Overview

Base interface for IR expressions (IRE) used by JEB's native decompilation engine, gendec. They can be statements or non-statements.

Refer to sub-interfaces. Refer to IEStatement for statements.

Summary

Public Methods
abstract boolean accessesMemory()
Determine whether this IRE accesses memory.
abstract boolean addFlags(int addedFlags)
Add flags to this IRE's flags list.
abstract IECompose asCompose()
abstract IECond asCond()
abstract IEGroup asGroup()
abstract IEGroupElt asGroupElt()
abstract IEImm asImm()
abstract IEMem asMem()
abstract IEOperation asOperation()
abstract IERange asRange()
abstract IESlice asSlice()
abstract IEStatement asStatement()
abstract IEVar asVar()
abstract IEGeneric bit(int pos)
Retrieve a one bit value at the pos position
abstract void collectSubExpressions(Collection<IEGeneric> sink)
Perform a shallow collection of the sub-expressions of this expression.
abstract void copyProperties(IEGeneric srcExp)
Copy the base properties from the provided IR source expression to this expression.
abstract IECond countSuccessiveBits(boolean ones, boolean fromMsb, int bitsize)
Count successive bits in an integer, starting from MSB or LSB.
abstract IEGeneric duplicate()
Clone (deep copy) the expression.
abstract boolean equalsEx(Object obj, boolean includeType)
Same as #equals() with the possibility to exclude the type from the comparison.
abstract IEImm evaluate(EState state)
Evaluate the IRE.
abstract long evaluateAddress(EState state)
Evaluate the IRE as a 64-bit address.@return
abstract long evaluateUnsignedLong(EState state)
Evaluate the IRE as an unsigned long value.
abstract boolean examine(Predicate<IEGeneric> tester)
Visit the constituents of this expression, and check if one of them is passing the provided test.
abstract Couple<IEGenericIEGeneric> find(IEGeneric elt, int start, int comparisonMethod, IEGeneric thisParent)
Find the parent of the the provided child element.
abstract <T extends IEGeneric> T findByType(Class<T> clazz, int start)
Find a child element by type.
abstract <T extends IEGeneric> T findByType(Class<T> clazz)
Find the first child element by type.
abstract IEGeneric findParent(IEGeneric elt, int start)
Find the parent of the the provided child element.
abstract IEGeneric findParent(IEGeneric elt)
Find the parent of the first instance of the provided child element.
abstract ICElement generateC(IERoutineContext ectx, ICMethod cctx)
Generate the C abstract syntax tree portion for this expression.
abstract int getBitsize()
Get the size, in bits, of the IR expression.
abstract void getDefinedOrUsedAsDestination(EDefUseInfo defuse)
For non-statements only.
abstract void getExplicitlyUsed(EDefUseInfo defuse)
Get a list of variable or variable bits 'explicitly used' (read) by the instruction.
abstract IdRanges getExplicitlyUsed()
Convenience method around #getExplictlyUsed(EDefUseInfo).
abstract int getFlags()
Get the expression flags.
abstract int getPriority()
Get the base priority level of the expression.
abstract IWildcardType getSafeType(IWildcardTypeManager etypeman)
Generate a safe wildcard type for the expression, if it doesn't already have one.
abstract void getSubExpressions(List<IEGeneric> list)
This method is deprecated. use collectSubExpressions(Collection) instead
abstract IWildcardType getType()
Get the currently set intermediate-type.
abstract IdRanges getUsed()
Convenience method to invoke getUsed(EDefUseInfo).
abstract void getUsed(EDefUseInfo defuse)
Retrieve the variables or variable bits 'used' (read) by the instruction.
abstract IEGeneric half()
Retrieve the lower half-part of this IRE.
abstract boolean hasFlags(int checkedFlags)
Check if this IRE contains the provided flags.
abstract boolean isCompose()
abstract boolean isCond()
abstract boolean isGroup()
abstract boolean isGroupElt()
abstract boolean isImm()
abstract boolean isMem()
abstract boolean isOperation(String name)
abstract boolean isOperation()
abstract boolean isOperation(OperationType... candidateOps)
abstract boolean isOperation(OperationType expectedOp)
abstract boolean isRange()
abstract boolean isSlice()
abstract boolean isSlice(int wantedStart, int wantedEnd)
abstract boolean isStatement()
abstract boolean isVar()
abstract boolean isVar(int wantedVarId)
abstract IEGeneric leftShift(int shift)
left shift of an expression
abstract IEGeneric leftShift(int shift, int bitsize)
left shift of an expression, with an optional slice(int, int)
abstract IEGeneric lsb()
Return the least significant bit (lsb) of an expression.
abstract IEGeneric msb()
Return the most significant bit (msb) of an expression.
abstract IEGeneric part(int cnt)
Equivalent to slice(0, cnt)
abstract void removeFlags(int removedFlags)
Remove flags from this IRE's flags list.
abstract boolean replaceSubExpression(IEGeneric oldExp, IEGeneric newExp)
Shallow replacement, by reference.
abstract int replaceVar(IEVar var, IEGeneric repl)
Deep replace.
abstract IEGeneric rightShift(int shift)
right shift of an expression
abstract IEGeneric rightShift(int shift, int bitsize)
right shift of an expression, with an optional slice(int, int)
abstract IWildcardType safelyType(IWildcardTypeManager etypeman)
Generate and assign a safe wildcard type to the expression if it doesn't already have one.
abstract void setFlags(int newFlags)
Set the expression's flags.
abstract boolean setType(IWildcardType newType, ETypeInfo ti, boolean forceUpdate)
Set a pre-propagation intermediate-type.
abstract boolean setType(IWildcardType newType, ETypeInfo ti)
Set a pre-propagation intermediate-type.
abstract boolean setType(IWildcardType type)
Set a pre-propagation intermediate-type.
abstract IEGeneric signExtend(int newBitsize)
Sign extend the current IEGeneric.
abstract IEGeneric slice(IERange r)
Slice of an IEGeneric.
abstract IEGeneric slice(int begin)
Equivalent to slice(begin, bitsize).
abstract IEGeneric slice(int begin, int end)
Slice of an IEGeneric.
abstract IEGeneric topHalf()
Retrieve the top half-part of this IRE.
abstract void updateTypes(ETypeInfo ti)
Deep update the types of the constituents of this IRE, update the IRE type as well the direct constituents if needed.
abstract void verify()
Verify the legality of this IR expression.
abstract boolean visitDepthPost(IEVisitor visitor, IEGeneric parent)
Depth-first search, post-order visit of an expression tree or sub-tree.
abstract boolean visitDepthPost(IEVisitor visitor, IEGeneric parent, EVisitResults results)
Depth-first search, post-order visit of an expression tree or sub-tree.
abstract boolean visitDepthPost(IEVisitor visitor)
Depth-first search, post-order visit of an expression tree or sub-tree.
abstract boolean visitDepthPre(IEVisitor visitor, IEGeneric parent)
Depth-first search, pre-order visit of an expression tree or sub-tree.
abstract boolean visitDepthPre(IEVisitor visitor)
Depth-first search, pre-order visit of an expression tree or sub-tree.
abstract boolean visitDepthPre(IEVisitor visitor, IEGeneric parent, EVisitResults results)
Depth-first search, pre-order visit of an expression tree or sub-tree.
abstract IEGeneric zeroExtend(int newBitsize)
Zero extend the current IEGeneric
[Expand]
Inherited Methods
From interface com.pnfsoftware.jeb.core.units.code.IInstructionOperand

Public Methods

public abstract boolean accessesMemory ()

Determine whether this IRE accesses memory.

Returns
  • true if the expression reads or writes to memory

public abstract boolean addFlags (int addedFlags)

Add flags to this IRE's flags list.

Returns
  • true if the flags were effectively changed (new additions were made); false otherwise

public abstract IECompose asCompose ()

Returns

public abstract IECond asCond ()

Returns

public abstract IEGroup asGroup ()

Returns

public abstract IEGroupElt asGroupElt ()

Returns

public abstract IEImm asImm ()

Returns

public abstract IEMem asMem ()

Returns

public abstract IEOperation asOperation ()

Returns

public abstract IERange asRange ()

Returns

public abstract IESlice asSlice ()

Returns

public abstract IEStatement asStatement ()

Returns

public abstract IEVar asVar ()

Returns

public abstract IEGeneric bit (int pos)

Retrieve a one bit value at the pos position

Parameters
pos bit position to be retrieved
Returns
  • IEGeneric of size 1 with bit at position `pos`

public abstract void collectSubExpressions (Collection<IEGeneric> sink)

Perform a shallow collection of the sub-expressions of this expression. All collected expressions are directly rooted in this IRE (i.e. their parent is this IR expression).

This method appends to the provided sink (existing elements are not cleared). The current element (this) is not appended; only the sub-expressions are considered.

public abstract void copyProperties (IEGeneric srcExp)

Copy the base properties from the provided IR source expression to this expression.

Parameters
srcExp source expression

public abstract IECond countSuccessiveBits (boolean ones, boolean fromMsb, int bitsize)

Count successive bits in an integer, starting from MSB or LSB.

Parameters
ones true if '1's should be counted, false for '0's
fromMsb true if count should start from MSB, false from LSB

public abstract IEGeneric duplicate ()

Clone (deep copy) the expression.

Returns
  • the duplicate expression

public abstract boolean equalsEx (Object obj, boolean includeType)

Same as #equals() with the possibility to exclude the type from the comparison.

Parameters
obj object to compare
includeType true to include the type in the equality test
Returns
  • true if equal

public abstract IEImm evaluate (EState state)

Evaluate the IRE.

Parameters
state IR state (input and output)
Returns
  • the evaluation if the IRE; null if the state is configured to soft-fail on errors
Throws
EvaluationException thrown if the state is configured to hard-fail on errors (default)

public abstract long evaluateAddress (EState state)

Evaluate the IRE as a 64-bit address.@return

Throws
EvaluationException thrown if the state is configured to hard-fail on errors (default)

public abstract long evaluateUnsignedLong (EState state)

Evaluate the IRE as an unsigned long value. This convenience method will throw if the underlying immediate bit size exceeds 63 bits (unsigned value).

Returns
  • the evaluation if the IRE, as an unsigned value, if meaningful; the state is also updated
Throws
EvaluationException thrown if the state is configured to hard-fail on errors (default)

public abstract boolean examine (Predicate<IEGeneric> tester)

Visit the constituents of this expression, and check if one of them is passing the provided test.

Parameters
tester a predicate object examining the IEGeneric elements of this expression
Returns
  • true if a constituent passed the test; false if none passed the test

public abstract Couple<IEGenericIEGeneric> find (IEGeneric elt, int start, int comparisonMethod, IEGeneric thisParent)

Find the parent of the the provided child element.

Parameters
elt an IR element; if the element is this, the method will return null
start count of instances of elt that should be skipped before returning the parent element; this is useful is the element provided may not be unique within the tree (e.g. IEVar)
comparisonMethod 0= identity, 1= equality, 2= type-less equality
thisParent optional parent of this IR element
Returns
  • if found, the pair (parent, element) parent; else, null

public abstract T findByType (Class<T> clazz, int start)

Find a child element by type.

Parameters
clazz type of the element to be found; careful, if the type is the one of this, then this object will be returned
start count of matched elements that should be skipped before returning the element
Returns
  • the element or null

public abstract T findByType (Class<T> clazz)

Find the first child element by type.

Parameters
clazz type of the element to be found; careful, if the type is the one of this, then this object will be returned
Returns
  • the element or null

public abstract IEGeneric findParent (IEGeneric elt, int start)

Find the parent of the the provided child element. The comparison is done by identity.

Parameters
elt an IR element; if the element is this, the method will return null
start count of instances of elt that should be skipped before returning the parent element; this is useful is the element provided may not be unique within the tree (e.g. IEVar)
Returns
  • the parent or null

public abstract IEGeneric findParent (IEGeneric elt)

Find the parent of the first instance of the provided child element. The comparison is done by identity.

Parameters
elt an IR element; if the element is this, the method will return null
Returns
  • the parent or null

public abstract ICElement generateC (IERoutineContext ectx, ICMethod cctx)

Generate the C abstract syntax tree portion for this expression.

Parameters
ectx IR routine context
cctx C routine local context
Returns
  • the C AST element (may contain sub-elements)

public abstract int getBitsize ()

Get the size, in bits, of the IR expression. It is illegal to query The bitsize of some expressions.

Returns
  • the size in bits

public abstract void getDefinedOrUsedAsDestination (EDefUseInfo defuse)

For non-statements only. Assuming 'this' is a destination value, extract the variable or variable bits that are used and defined by it.

Parameters
defuse sink - both the `def` and `use` field may be modified

public abstract void getExplicitlyUsed (EDefUseInfo defuse)

Get a list of variable or variable bits 'explicitly used' (read) by the instruction. This method is inherently deep.

Parameters
defuse sink - only the `use` field is modified

public abstract IdRanges getExplicitlyUsed ()

Convenience method around #getExplictlyUsed(EDefUseInfo).

Returns
  • an used id ranges object

public abstract int getFlags ()

Get the expression flags.

The flags are defined in the sub-interfaces. They do not overlap.

public abstract int getPriority ()

Get the base priority level of the expression. Higher number correlates to lower priority; 0 means "no priority". (Therefore, the highest priority level is 1.)

public abstract IWildcardType getSafeType (IWildcardTypeManager etypeman)

Generate a safe wildcard type for the expression, if it doesn't already have one. If generated, the type is NOT assigned to the IR expression.

Returns
  • the wildcard type, never null

public abstract void getSubExpressions (List<IEGeneric> list)

This method is deprecated.
use collectSubExpressions(Collection) instead

Shallow collection of this expression's constituents, in evaluation order. Appends to `list` (existing elements are not cleared). The current element (this) is not appended, only the descendants are considered.

Parameters
list non-null output list

public abstract IWildcardType getType ()

Get the currently set intermediate-type.

public abstract IdRanges getUsed ()

Convenience method to invoke getUsed(EDefUseInfo).

Returns
  • an used id ranges object

public abstract void getUsed (EDefUseInfo defuse)

Retrieve the variables or variable bits 'used' (read) by the instruction. This method is inherently deep.

Note that some IRE may implicitly use variables, such as some ECall, PC-assigns, UntranslatedInstruction. This method returns those implicit uses.

Parameters
defuse sink - only the `use` field is modified

public abstract IEGeneric half ()

Retrieve the lower half-part of this IRE. If the IRE does not have an even count of bits N, then the lowest CEIL(N/2) bits are returned.

public abstract boolean hasFlags (int checkedFlags)

Check if this IRE contains the provided flags.

Returns
  • true if all the checked flags are present

public abstract boolean isCompose ()

Returns

public abstract boolean isCond ()

Returns
  • true if this IRE is an IECond

public abstract boolean isGroup ()

Returns

public abstract boolean isGroupElt ()

Returns

public abstract boolean isImm ()

Returns
  • true if this IRE is an IEImm

public abstract boolean isMem ()

Returns
  • true if this IRE is an IEMem

public abstract boolean isOperation (String name)

Parameters
name operation name
Returns
  • true if this IRE is an IEOperation of the provided name

public abstract boolean isOperation ()

Returns

public abstract boolean isOperation (OperationType... candidateOps)

Parameters
candidateOps a list of operators
Returns
  • true if this IRE is an IEOperation using one of the candidate operators

public abstract boolean isOperation (OperationType expectedOp)

Parameters
expectedOp an operator
Returns
  • true if this IRE is an IEOperation using the provided operator

public abstract boolean isRange ()

Returns

public abstract boolean isSlice ()

Returns

public abstract boolean isSlice (int wantedStart, int wantedEnd)

Returns
  • true if this IRE is a IESlice of the provided range

public abstract boolean isStatement ()

Returns

public abstract boolean isVar ()

Returns
  • true if this IRE is an IEVar

public abstract boolean isVar (int wantedVarId)

Parameters
wantedVarId variable id
Returns
  • true if this IRE is an IEVar having the provided id

public abstract IEGeneric leftShift (int shift)

left shift of an expression

Parameters
shift left shift value
Returns

public abstract IEGeneric leftShift (int shift, int bitsize)

left shift of an expression, with an optional slice(int, int)

Parameters
shift left shift value
bitsize bitsize of the final IEGeneric. Note that the condition (bitSize - shift < currentBitSize) must be respected.
Returns

public abstract IEGeneric lsb ()

Return the least significant bit (lsb) of an expression. No duplicate is done, it is up to caller to duplicate current IEGeneric if needed.

Returns
  • the least significant bit

public abstract IEGeneric msb ()

Return the most significant bit (msb) of an expression. No duplicate is done, it is up to caller to duplicate current IEGeneric if needed.

Returns
  • the most significant bit

public abstract IEGeneric part (int cnt)

Equivalent to slice(0, cnt)

Parameters
cnt wanted bit count

public abstract void removeFlags (int removedFlags)

Remove flags from this IRE's flags list.

public abstract boolean replaceSubExpression (IEGeneric oldExp, IEGeneric newExp)

Shallow replacement, by reference. Only the first occurrence is replaced.

Be careful when replacing immediates or variables. Unexpected behaviors may happen if the expression contains multiple instances of the same imm or var.

Parameters
oldExp the expression to be replaced
newExp the new expression, whose type must be consistent with the expression replaced
Returns
  • success indicator

public abstract int replaceVar (IEVar var, IEGeneric repl)

Deep replace. All matching variables are replaced. The implementation is responsible for duplicating the IR expressions, to ensure that the resulting statement or group of statement does not contain duplicate references to mutable objects.

Returns
  • the number of instances replaced

public abstract IEGeneric rightShift (int shift)

right shift of an expression

Parameters
shift right shift value
Returns

public abstract IEGeneric rightShift (int shift, int bitsize)

right shift of an expression, with an optional slice(int, int)

Parameters
shift right shift value
bitsize bitsize of the final IEGeneric. Note that the condition (bitSize < currentBitSize) must be respected.
Returns

public abstract IWildcardType safelyType (IWildcardTypeManager etypeman)

Generate and assign a safe wildcard type to the expression if it doesn't already have one.

Returns
  • the wildcard type, never null

public abstract void setFlags (int newFlags)

Set the expression's flags.

public abstract boolean setType (IWildcardType newType, ETypeInfo ti, boolean forceUpdate)

Set a pre-propagation intermediate-type. Does not propagate/update type in the super- or sub-expression.

Parameters
newType the new type; may be null
ti optional type-setting information structure, contains information about how many types were set, the list of type conflicts, etc.
forceUpdate true to force a type update even if the new type is less speciialized (has a lesser score) than the currently existing type
Returns
  • true if a type was set correctly, or unchanged; false if the type was not set, eg because of a conflict with the current type

public abstract boolean setType (IWildcardType newType, ETypeInfo ti)

Set a pre-propagation intermediate-type. Does not propagate/update type in the super- or sub-expression. Not forced.

Parameters
newType the new type; may be null
ti optional type-setting information structure, contains information about how many types were set, the list of type conflicts, etc.
Returns
  • true if a type was set correctly, or unchanged; false if the type was not set, eg because of a conflict with the current type

public abstract boolean setType (IWildcardType type)

Set a pre-propagation intermediate-type. Does not propagate/update type in the super- or sub-expression.

Parameters
type the new type; may be null
Returns
  • true if a type was set correctly, or unchanged; false if the type was not set, eg because of a conflict with the current type

public abstract IEGeneric signExtend (int newBitsize)

Sign extend the current IEGeneric. This method will create a valid IEGeneric (meaning IEGeneric will not have duplicates id - in particular, in the form C(x, x.msb()?ones():zeros()) where x will be present in base value and msb predicate)

Parameters
newBitsize must be superior to getBitsize()

public abstract IEGeneric slice (IERange r)

Slice of an IEGeneric.

public abstract IEGeneric slice (int begin)

Equivalent to slice(begin, bitsize).

Parameters
begin start position
Returns

public abstract IEGeneric slice (int begin, int end)

Slice of an IEGeneric.

Parameters
begin start (inclusive) position
end end (exclusive) position. Note that the conditions (end <= bitsize AND begin < end) must be respected
Returns

public abstract IEGeneric topHalf ()

Retrieve the top half-part of this IRE. If the IRE does not have an even count of bits N, then the highest FLOOR(N/2) bits are returned.

public abstract void updateTypes (ETypeInfo ti)

Deep update the types of the constituents of this IRE, update the IRE type as well the direct constituents if needed. Not forced. When this method is called, it is the responsibility to verify that the constituent IREs are typeable, and if not, to make them typeable (eg, EImm updates, EVar copies, etc.).

Parameters
ti optional type information object; provides access to a wildcard type manager, and used to record typing conflicts

public abstract void verify ()

Verify the legality of this IR expression.

Throws
IllegalIntermediateExpressionException if the IRE is deemed invalid or illegal

public abstract boolean visitDepthPost (IEVisitor visitor, IEGeneric parent)

Depth-first search, post-order visit of an expression tree or sub-tree. 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.

public abstract boolean visitDepthPost (IEVisitor visitor, IEGeneric parent, EVisitResults results)

Depth-first search, post-order visit of an expression tree or sub-tree. 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.

Parameters
visitor the visitor object
Returns
  • true if the visit was successful

public abstract boolean visitDepthPost (IEVisitor visitor)

Depth-first search, post-order visit of an expression tree or sub-tree. 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.

public abstract boolean visitDepthPre (IEVisitor visitor, IEGeneric parent)

Depth-first search, pre-order visit of an expression tree or sub-tree. The node being visited may be replaced, but the client code is responsible for EVisitResults#setReplacedNode(IEGeneric) 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.

public abstract boolean visitDepthPre (IEVisitor visitor)

Depth-first search, pre-order visit of an expression tree or sub-tree. The node being visited may be replaced, but the client code is responsible for EVisitResults#setReplacedNode(IEGeneric) 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.

public abstract boolean visitDepthPre (IEVisitor visitor, IEGeneric parent, EVisitResults results)

Depth-first search, pre-order visit of an expression tree or sub-tree. The node being visited may be replaced, but the client code is responsible for EVisitResults#setReplacedNode(IEGeneric) 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.

Parameters
visitor the visitor object
Returns
  • true if the visit was successful

public abstract IEGeneric zeroExtend (int newBitsize)

Zero extend the current IEGeneric

Parameters
newBitsize must be superior to getBitsize()