All Superinterfaces:
IInstructionOperand
All Known Subinterfaces:
IEAssign, IECall, IECompose, IECond, IEGroup, IEGroupElt, IEImm, IEJump, IEJumpFar, IEJumpWithOptionalCondition, IEMem, IENop, IEOperation, IERange, IEReturn, IESlice, IEStatement, IESwitch, IEUntranslatedInstruction, IEVar

@Ser public interface IEGeneric extends IInstructionOperand
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.

  • Method Details

    • getFlags

      int getFlags()
      Get the expression flags.

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

      Returns:
    • setFlags

      void setFlags(int newFlags)
      Set the expression's flags.
      Parameters:
      newFlags -
    • hasFlags

      boolean hasFlags(int checkedFlags)
      Check if this IRE contains the provided flags.
      Parameters:
      checkedFlags -
      Returns:
      true if all the checked flags are present
    • addFlags

      boolean addFlags(int addedFlags)
      Add flags to this IRE's flags list.
      Parameters:
      addedFlags -
      Returns:
      true if the flags were effectively changed (new additions were made); false otherwise
    • removeFlags

      void removeFlags(int removedFlags)
      Remove flags from this IRE's flags list.
      Parameters:
      removedFlags -
    • getBitsize

      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
    • getPriority

      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.)
      Returns:
    • getUsed

      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
    • getUsed

      default IdRanges getUsed()
      Convenience method to invoke getUsed(EDefUseInfo).
      Returns:
      an used id ranges object
    • getDefinedOrUsedAsDestination

      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
    • getExplicitlyUsed

      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
    • getExplicitlyUsed

      default IdRanges getExplicitlyUsed()
      Convenience method around getExplicitlyUsed(EDefUseInfo).
      Returns:
      an used id ranges object
    • accessesMemory

      boolean accessesMemory()
      Determine whether this IRE accesses memory.
      Returns:
      true if the expression reads or writes to memory
    • evaluate

      IEImm evaluate(EState state) throws EvaluationException
      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)
    • evaluateUnsignedLong

      long evaluateUnsignedLong(EState state) throws EvaluationException
      Evaluate the IRE as an unsigned long value. This convenience method will throw if the underlying immediate bit size exceeds 63 bits (unsigned value).
      Parameters:
      state -
      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)
    • evaluateAddress

      long evaluateAddress(EState state) throws EvaluationException
      Evaluate the IRE as a 64-bit address.
      Parameters:
      state -
      Returns:
      Throws:
      EvaluationException - thrown if the state is configured to hard-fail on errors (default)
    • replaceVar

      int replaceVar(IEVar var, IEGeneric repl) throws IllegalIntermediateExpressionException
      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.
      Parameters:
      var -
      repl -
      Returns:
      the number of instances replaced
      Throws:
      IllegalIntermediateExpressionException
    • collectSubExpressions

      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.

      Parameters:
      sink -
    • replaceSubExpression

      boolean replaceSubExpression(IEGeneric oldExp, IEGeneric newExp) throws IllegalIntermediateExpressionException
      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
      Throws:
      IllegalIntermediateExpressionException
    • updateTypes

      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
    • setType

      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
    • setType

      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
    • setType

      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
    • getType

      IWildcardType getType()
      Get the currently set intermediate-type.
      Returns:
    • safelyType

      IWildcardType safelyType(IWildcardTypeManager etypeman)
      Generate and assign a safe wildcard type to the expression if it doesn't already have one.
      Parameters:
      etypeman -
      Returns:
      the wildcard type, never null
    • getSafeType

      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.
      Parameters:
      etypeman -
      Returns:
      the wildcard type, never null
    • visitDepthPre

      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 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 -
      Returns:
    • visitDepthPre

      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 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 -
      parent -
      Returns:
    • visitDepthPre

      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 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
      parent -
      results -
      Returns:
      true if the visit was successful
    • visitDepthPost

      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.

      Parameters:
      visitor -
      Returns:
    • visitDepthPost

      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.

      Parameters:
      visitor -
      parent -
      Returns:
    • visitDepthPost

      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
      parent -
      results -
      Returns:
      true if the visit was successful
    • examine

      default 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
    • verify

      Verify the legality of this IR expression.
      Throws:
      IllegalIntermediateExpressionException - if the IRE is deemed invalid or illegal
    • duplicate

      IEGeneric duplicate()
      Clone (deep copy) the expression.
      Returns:
      the duplicate expression
    • copyProperties

      void copyProperties(IEGeneric srcExp)
      Copy the base properties from the provided IR source expression to this expression.
      Parameters:
      srcExp - source expression
    • generateC

      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)
    • part

      IEGeneric part(int cnt)
      Equivalent to slice(0, cnt)
      Parameters:
      cnt - wanted bit count
      Returns:
    • bit

      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`
    • slice

      IEGeneric slice(int begin)
      Equivalent to slice(begin, bitsize).
      Parameters:
      begin - start position
      Returns:
      the sliced IEGeneric
    • slice

      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:
      the sliced IEGeneric
    • slice

      IEGeneric slice(IERange r)
      Slice of an IEGeneric.
      Parameters:
      r -
      Returns:
    • msb

      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
    • lsb

      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
    • half

      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.
      Returns:
    • topHalf

      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.
      Returns:
    • zeroExtend

      IEGeneric zeroExtend(int newBitsize)
      Zero extend the current IEGeneric
      Parameters:
      newBitsize - must be superior to getBitsize()
    • signExtend

      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()
    • leftShift

      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:
      IEGeneric left shifted by the shift value
    • leftShift

      IEGeneric leftShift(int shift)
      left shift of an expression
      Parameters:
      shift - left shift value
      Returns:
      IEGeneric left shifted by the shift value
    • rightShift

      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:
      IEGeneric right shifted by the shift value
    • rightShift

      IEGeneric rightShift(int shift)
      right shift of an expression
      Parameters:
      shift - right shift value
      Returns:
      IEGeneric right shifted by the shift value
    • countSuccessiveBits

      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
      bitsize -
    • equalsEx

      boolean equalsEx(Object obj, boolean includeType)
      Same as #equals(Object) 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
    • isCompose

      default boolean isCompose()
      Returns:
      true if this IRE is an IECompose
    • asCompose

      default IECompose asCompose()
      Returns:
      this IRE as an IECompose
    • isCond

      default boolean isCond()
      Returns:
      true if this IRE is an IECond
    • asCond

      default IECond asCond()
      Returns:
      this IRE as an IECond
    • isGroup

      default boolean isGroup()
      Returns:
      true if this IRE is an IEGroup
    • asGroup

      default IEGroup asGroup()
      Returns:
      this IRE as an IEGroup
    • isGroupElt

      default boolean isGroupElt()
      Returns:
      true if this IRE is an IEGroupElt
    • asGroupElt

      default IEGroupElt asGroupElt()
      Returns:
      this IRE as an IEGroupElt
    • isImm

      default boolean isImm()
      Returns:
      true if this IRE is an IEImm
    • asImm

      default IEImm asImm()
      Returns:
      this IRE as an IEImm
    • isMem

      default boolean isMem()
      Returns:
      true if this IRE is an IEMem
    • asMem

      default IEMem asMem()
      Returns:
      this IRE as an IEMem
    • isOperation

      default boolean isOperation()
      Returns:
      true if this IRE is an IEOperation
    • isOperation

      default boolean isOperation(OperationType expectedOp)
      Parameters:
      expectedOp - an operator
      Returns:
      true if this IRE is an IEOperation using the provided operator
    • isOperation

      default boolean isOperation(OperationType... candidateOps)
      Parameters:
      candidateOps - a list of operators
      Returns:
      true if this IRE is an IEOperation using one of the candidate operators
    • isOperation

      default boolean isOperation(String name)
      Parameters:
      name - operation name
      Returns:
      true if this IRE is an IEOperation of the provided name
    • asOperation

      default IEOperation asOperation()
      Returns:
      this IRE as an IEOperation
    • isRange

      default boolean isRange()
      Returns:
      true if this IRE is an IERange
    • asRange

      default IERange asRange()
      Returns:
      this IRE as an IERange
    • isSlice

      default boolean isSlice()
      Returns:
      true if this IRE is a IESlice
    • isSlice

      default boolean isSlice(int wantedStart, int wantedEnd)
      Parameters:
      wantedStart -
      wantedEnd -
      Returns:
      true if this IRE is a IESlice of the provided range
    • asSlice

      default IESlice asSlice()
      Returns:
      this IRE as an IESlice
    • isVar

      default boolean isVar()
      Returns:
      true if this IRE is an IEVar
    • isVar

      default boolean isVar(int wantedVarId)
      Parameters:
      wantedVarId - variable id
      Returns:
      true if this IRE is an IEVar having the provided id
    • asVar

      default IEVar asVar()
      Returns:
      this IRE as an IEVar
    • isStatement

      default boolean isStatement()
      Returns:
      true if this IRE is an IEStatement
    • asStatement

      default IEStatement asStatement()
      Returns:
      this IRE as an IEStatement
    • findParent

      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
    • findParent

      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
    • find

      Couple<IEGeneric,IEGeneric> 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
    • findByType

      <T extends IEGeneric> T findByType(Class<T> clazz)
      Find the first child element by type.
      Type Parameters:
      T -
      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
    • findByType

      <T extends IEGeneric> T findByType(Class<T> clazz, int start)
      Find a child element by type.
      Type Parameters:
      T -
      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