Package com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir

Class EState

java.lang.Object
com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState
public class EState extends Object
An IR machine state object, onto which stand-alone evaluations or full emulation can be performed.

  • Field Details

    • MEMREAD_OK

      public static final int MEMREAD_OK
      See Also:

    • MEMREAD_FAILED

      public static final int MEMREAD_FAILED
      See Also:

    • MEMREAD_BADDATA

      public static final int MEMREAD_BADDATA
      See Also:

    • POLICY_MEMWRITE_BADHIT_DEFAULT

      public static final int POLICY_MEMWRITE_BADHIT_DEFAULT
      See Also:

    • POLICY_MEMWRITE_BADHIT_FORCE_RECORDING

      public static final int POLICY_MEMWRITE_BADHIT_FORCE_RECORDING
      See Also:

    • POLICY_MEMWRITE_BADHIT_FORCE_NO_RECORDING

      public static final int POLICY_MEMWRITE_BADHIT_FORCE_NO_RECORDING
      See Also:

    • POLICY_MEMWRITE_BADHIT_NEED_STACK_ADDRESS

      public static final int POLICY_MEMWRITE_BADHIT_NEED_STACK_ADDRESS
      See Also:

  • Constructor Details

    • EState

      public EState(IEGlobalContext gctx)
      Create a state object with a fresh VM, set up according to the providing context properties.
      Parameters:
      gctx -

    • EState

      public EState(Endianness end)
      Create an empty state object with no VM, empty global vars, no local vars.
      Parameters:
      end -

    • EState

      public EState(EState src, boolean duplicateMemory)
      Copy constructor.
      Parameters:
      src -

    • EState

      public EState(EState src, boolean duplicateMemory, boolean copyHooks)
      Copy constructor. The VM may be optionally duplicated.
      Parameters:
      src -
      duplicateMemory - if true, the VM for the state is a deep copy of the current provided state's; else, the VM of the new state will be the same as the provided state's
      copyHooks - if true, the new state will receive a copy of the provided state's hooks; else, the new state will have an empty hooks list

  • Method Details

    • pushFrame

      public void pushFrame()
      Save a frame that will contain the current virtual PC, variables, and native stack boundaries. The value of the PC is reset to 0, the variable slate is a copy of the previous variable slate, and the native stack boundaries are reset.

      This method used to provide support for the execution of IR sub-routines (IECall emulation).

    • popFrame

      public EState.Frame popFrame()
      Restore the current values of PC, variables, and native stack boundaries by popping the top-level frame.
      Returns:
      the previous frame, or null on error (if the stack frame was empty)

    • countFrames

      public int countFrames()

    • setExecuteSubRoutines

      public void setExecuteSubRoutines(boolean executeSubRoutines)

    • isExecuteSubRoutines

      public boolean isExecuteSubRoutines()
      Determine whether call-to-sub PC-assigns are truly evaluated (the state controller, such as the EEmulator, is responsible for adjusting the state), or simply skipped over (only the side-effects are applied).
      Returns:

    • adjustVirtualPC

      public int adjustVirtualPC(int delta)
      Parameters:
      delta - increment to be added to the current virtual PC
      Returns:
      the next virtual PC

    • setVirtualPC

      public void setVirtualPC(int virtualPC)

    • getVirtualPC

      public int getVirtualPC()

    • setRoutineContext

      public void setRoutineContext(IERoutineContext ectx)

    • getRoutineContext

      public IERoutineContext getRoutineContext()

    • getGlobalContext

      public IEGlobalContext getGlobalContext()

    • setMaxEvaluationCount

      public void setMaxEvaluationCount(int maxEvalcnt)

    • getMaxEvaluationCount

      public int getMaxEvaluationCount()

    • incrementEvaluationCount

      public boolean incrementEvaluationCount()

    • getEvaluationCount

      public int getEvaluationCount()

    • enableMemoryWriteHitmap

      public void enableMemoryWriteHitmap(boolean enabled, boolean recordBadWrites)

    • setRecordBadWrites

      public void setRecordBadWrites(boolean recordBadWrites)

    • isRecordBadWrites

      public boolean isRecordBadWrites()

    • getMemoryWriteHitmap

      public Map<Long,Integer> getMemoryWriteHitmap()
      Returns:
      a byte-address map: address to evalcnt (internal iteration count) of the last recorded write at that address.

    • setPrimaryEmulator

      public void setPrimaryEmulator(EEmulator primaryEmulator)

    • getPrimaryEmulator

      public EEmulator getPrimaryEmulator()

    • registerHooks

      public void registerHooks(IEStateHooks hooks, boolean insertFirst)

    • unregisterHooks

      public void unregisterHooks(IEStateHooks hooks)

    • setDisabledHooks

      public boolean setDisabledHooks(boolean disabled)

    • isDisabledHooks

      public boolean isDisabledHooks()

    • mergeWith

      public int mergeWith(EState state, IMergeController mergeController, Set<Integer> removals, Set<Integer> additions)
      Merge the provided output state with this input state. Memories are not merged.
      Parameters:
      state - input state
      mergeController - optional controller, will use StandardMergeController if none is provided
      Returns:
      the number of discrepancies and extra mergers performed

    • mergeWithOld

      public int mergeWithOld(EState state, Collection<Integer> removeMerges, boolean mergeOutputAbsentFromInput, Collection<Integer> preventMerges, Collection<Integer> discrepancies)
      Merge the provided output state with this input state. Memories are not merged.
      Parameters:
      state - second state (the output), to be merged with `this` (the input)
      removeMerges - optional collection of input-state variables that should be removed, if they were not present in the input state; if this parameter is null, all input-state only (ie, not present in the output-state) variables will be kept
      mergeOutputAbsentFromInput - if true, variables present in the output state, but not present in the input state, will be added (merged into) the input state, unless they're listed in the `preventMerges` collection parameter
      preventMerges - optional input collection of registers that cannot be merged; disregarded if `mergeOutputAbsentFromInput` is false
      discrepancies - optional output collection of mismatched registers (discrepancies)
      Returns:
      the number of merges performed + discrepancies found

    • isBigEndian

      public boolean isBigEndian()

    • getVariables

      public Map<Integer,IEImm> getVariables()

    • setVariables

      public void setVariables(Map<Integer,IEImm> vars)
      Replace the variables of this state by another set of variables.
      Parameters:
      vars -

    • getValueSafe

      public IEImm getValueSafe(IEVar var)
      Retrieve the value of a variable.
      Parameters:
      var -
      Returns:
      the value; null indicates either unknown or BAD

    • getValueSafe

      public IEImm getValueSafe(int id)
      Retrieve the value of a variable.
      Parameters:
      id - variable id
      Returns:
      the value; null indicates either unknown or BAD

    • getValue

      public IEImm getValue(IEVar var)
      Retrieve the value of a variable.
      Parameters:
      var -
      Returns:
      the value; if the value is unknown or BAD, an evaluation exception is raised

    • getValue

      public IEImm getValue(int id)
      Retrieve the value of a variable.
      Parameters:
      id - variable id
      Returns:
      the value; if the value is unknown or BAD, an evaluation exception is raised

    • getValueAsLong

      public long getValueAsLong(int id)
      Convenience method used to retrieve the value of an initialized variable as a long. This method throws a EvaluationException if the variable is uninitialized or BAD.
      Parameters:
      id - variable id
      Returns:
      the value

    • getValueAsLongSafe

      public Long getValueAsLongSafe(int id)
      Convenience method used to retrieve the value of a variable as a long object. This method returns null if the variable is uninitialized or BAD.
      Parameters:
      id - variable id
      Returns:
      the value or null

    • getValueAsUnsignedLong

      public long getValueAsUnsignedLong(int id)
      Convenience method used to retrieve the value of a variable as a long object. This method throws a EvaluationException if the variable is uninitialized or BAD.
      Parameters:
      id - variable id
      Returns:
      the value

    • setValue

      public void setValue(int id, long val)
      Set a variable to a defined value.
      Parameters:
      id - the positive id of a global context variable
      val -

    • setValue

      public void setValue(IEVar var, long val)
      Set a variable to a defined value.
      Parameters:
      var -
      val -

    • setValue

      public void setValue(IEVar var, IEImm val)
      Set a variable to a defined value or the BAD value.
      Parameters:
      var -
      val - a value; null indicates the explicit BAD value

    • setValue

      public void setValue(IEGeneric dst, IEImm val)
      Set a variable or the slice of a variable to the provided value.
      Parameters:
      dst - a var or the slice of a var
      val - the value to be set (which bitsize must be the same as dst's), cannot be null

    • removeValue

      public boolean removeValue(int id)

    • hasValue

      public boolean hasValue(int id)
      Determine whether the provided variable is defined (i.e., not unknown, not set to BAD).
      Parameters:
      id -
      Returns:

    • hasBadValue

      public boolean hasBadValue(int id)
      Determine whether the provided variable is currently set to BAD.
      Parameters:
      id -
      Returns:

    • getProgramCounter

      public IEImm getProgramCounter()
      Convenience method to read the PC. Will throw on error. A global context must have been set.
      Returns:

    • setProgramCounter

      public void setProgramCounter(IEImm val)
      Convenience method to write the PC. Will throw on error. A global context must have been set.
      Parameters:
      val -

    • getStackPointer

      public IEImm getStackPointer()
      Convenience method to read the SP. Will throw on error. A global context must have been set.
      Returns:

    • setStackPointer

      public void setStackPointer(IEImm val)
      Convenience method to write the SP. Will throw on error. A global context must have been set.
      Parameters:
      val -

    • hasSegmentBases

      public boolean hasSegmentBases()

    • setSegmentBase

      public void setSegmentBase(int segment, long base)
      Set the memory address associated with a segment.
      Parameters:
      segment - the value of a segment register
      base - the base memory address associated with the segment

    • getSegmentBase

      public long getSegmentBase(int segment)
      Retrieve the memory address associated with a segment.
      Parameters:
      segment - the value of a segment register
      Returns:
      the base memory address associated with the segment; 0 if none

    • setSegmentMapping

      public void setSegmentMapping(String segmentName, int segmentValue, long baseAddress)
      Convenience routine.

    • getMemory

      public IVirtualMemory getMemory()

    • setMemory

      public void setMemory(IVirtualMemory vm)

    • setNativeStackStart

      public void setNativeStackStart(long nativeStackStart)
      Set the low-address for the native stack of the current frame.
      Parameters:
      nativeStackStart -

    • getNativeStackStart

      public long getNativeStackStart()
      Retrieve the optional low-address for the native stack of the current frame.
      Returns:
      an address, -1 if none

    • setNativeStackEnd

      public void setNativeStackEnd(long nativeStackEnd)
      Set the high-address (exclusive) for the native stack of the current frame.
      Parameters:
      nativeStackEnd -

    • getNativeStackEnd

      public long getNativeStackEnd()
      Retrieve the optional high-address (exclusive) for the native stack of the current frame.
      Returns:
      an address, -1 if none

    • setSoftFailMode

      public void setSoftFailMode(boolean enabled)
      Enable or disable the soft-fail mode. In soft-fail mode, a 'bad data' memory is used to track VM-read attempts to memory areas known to contain 'bad' data. See setBadMemory(IVirtualMemory) for details.
      Parameters:
      enabled -

    • isSoftFailMode

      public boolean isSoftFailMode()
      Determine whether the soft-fail mode is used to track 'bad data' read attempts.
      Returns:

    • getBadMemory

      public IVirtualMemory getBadMemory()
      Retrieve the optional 'bad data' VM. See setBadMemory(IVirtualMemory).
      Returns:

    • setBadMemory

      public void setBadMemory(IVirtualMemory bad_vm)
      Set a specific VM used to contain information about areas of memory that are known to contain 'bad' data. The term here may be understood as existing data in memory whose value is stale or incorrect. It is not recommended to write to this VM directly. Its use is internal to this class.

      Note that this method is low-level. A higher-level way to set a bad memory is to enable soft-fail mode.

      Parameters:
      bad_vm - optional memory object

    • setMemoryAutoAllocOnWrite

      public void setMemoryAutoAllocOnWrite(boolean enabled)

    • isMemoryAutoAllocOnWrite

      public boolean isMemoryAutoAllocOnWrite()

    • allocateMemory

      public long allocateMemory(long address, int size, int protection)

    • freeMemory

      public boolean freeMemory(long address, int size)

    • readMemory

      public boolean readMemory(long address, byte[] buffer)
      Read memory bytes.
      Parameters:
      address -
      buffer -
      Returns:
      success indicator

    • readMemory2

      public int readMemory2(long address, byte[] buffer)
      Read memory bytes. Same as readMemory(long, byte[]), but provide a finer result when in soft-fail mode.
      Parameters:
      address -
      buffer -
      Returns:
      either MEMREAD_OK, MEMREAD_FAILED, or MEMREAD_BADDATA (on soft-fail mode only)

    • writeMemoryByte

      public boolean writeMemoryByte(long address, byte val)

    • writeMemoryShort

      public boolean writeMemoryShort(long address, short val)
      Write a 16-bit value to memory. Uses the VM-provided endianness attribute for encoding.
      Parameters:
      address -
      val -
      Returns:
      success indicator

    • writeMemoryInt

      public boolean writeMemoryInt(long address, int val)
      Write a 32-bit value to memory. Uses the VM-provided endianness attribute for encoding.
      Parameters:
      address -
      val -
      Returns:
      success indicator

    • writeMemoryLong

      public boolean writeMemoryLong(long address, long val)
      Write a 64-bit value to memory. Uses the VM-provided endianness attribute for encoding.
      Parameters:
      address -
      val -
      Returns:
      success indicator

    • writeMemoryPointer

      public boolean writeMemoryPointer(long address, long val)
      Write a pointer (address) to memory. Uses the VM-provided endianness attribute for encoding.
      Parameters:
      address -
      val -
      Returns:
      success indicator

    • writeMemory

      public boolean writeMemory(long address, byte[] buffer)
      Write memory bytes to specific (defined) values.
      Parameters:
      address -
      buffer -
      Returns:

    • writeMemoryBad

      public boolean writeMemoryBad(long address, int bitsize)
      Specify a range of memory bytes known to contain BAD data.
      Parameters:
      address -
      bitsize -
      Returns:

    • writeMemoryBad

      public boolean writeMemoryBad(long address, int bitsize, int policy)
      Specify a range of memory bytes known to contain BAD data.
      Parameters:
      address -
      bitsize -
      policy - one of POLICY_MEMWRITE_BADHIT_xxx
      Returns:

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • formatVars

      public String formatVars(boolean skipZeroRegs)

    • formatVars

      public static CharSequence formatVars(Map<Integer,IEImm> vars, IEGlobalContext gctx, IERoutineContext ctx)

    • formatVars

      public static CharSequence formatVars(Map<Integer,IEImm> vars, IEGlobalContext gctx, IERoutineContext ctx, Collection<Integer> includedIds, Collection<Integer> excludedIds, boolean skipZeroRegs)

    • saveState

      public EState.StateInfo saveState()

    • forkState

      public EState.StateInfo forkState(boolean lightFork)
      Parameters:
      lightFork - a light fork does not duplicate the VM (which means it can be used for thread creation inside an existing process)
      Returns:

    • loadState

      public void loadState(EState.StateInfo info)