public class

EState

extends Object
java.lang.Object
   ↳ com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState

Class Overview

An IR machine state object, onto which stand-alone evaluations or full emulation can be performed.

Summary

Nested Classes
class EState.Frame  
Constants
int MEMREAD_BADDATA
int MEMREAD_FAILED
int MEMREAD_OK
int POLICY_MEMWRITE_BADHIT_DEFAULT
int POLICY_MEMWRITE_BADHIT_FORCE_NO_RECORDING
int POLICY_MEMWRITE_BADHIT_FORCE_RECORDING
int POLICY_MEMWRITE_BADHIT_NEED_STACK_ADDRESS
Public Constructors
EState(IEGlobalContext gctx)
Create a state object with a fresh VM, set up according to the providing context properties.
EState(Endianness end)
Create an empty state object with no VM, empty global vars, no local vars.
EState(EState src)
Copy constructor.
EState(EState src, boolean duplicateMemory)
Copy constructor.
Public Methods
void addHooks(IEStateHooks hooks)
int adjustVirtualPC(int delta)
int countFrames()
void enableMemoryWriteHitmap(boolean enabled, boolean recordBadWrites)
String formatVars(boolean skipZeroRegs)
static CharSequence formatVars(Map<Integer, IEImm> vars, IEGlobalContext gctx, IERoutineContext ctx, Collection<Integer> includedIds, Collection<Integer> excludedIds, boolean skipZeroRegs)
static CharSequence formatVars(Map<Integer, IEImm> vars, IEGlobalContext gctx, IERoutineContext ctx)
IVirtualMemory getBadMemory()
Retrieve the optional 'bad data' VM.
int getEvaluationCount()
IEGlobalContext getGlobalContext()
int getMaxEvaluationCount()
IVirtualMemory getMemory()
Map<Long, Integer> getMemoryWriteHitmap()
long getNativeStackEnd()
Retrieve the optional high-address (exclusive) for the native stack of the current frame.
long getNativeStackStart()
Retrieve the optional low-address for the native stack of the current frame.
EEmulator getPrimaryEmulator()
IEImm getProgramCounter()
Convenience method to read the PC.
IERoutineContext getRoutineContext()
long getSegmentBase(int segment)
Retrieve the memory address associated with a segment.
IEImm getStackPointer()
Convenience method to read the SP.
IEImm getValue(int id)
Retrieve the value of a variable.
IEImm getValue(IEVar var)
Retrieve the value of a variable.
long getValueAsLong(int id)
Convenience method used to retrieve the value of an initialized variable as a long.
Long getValueAsLongSafe(int id)
Convenience method used to retrieve the value of a variable as a long object.
long getValueAsUnsignedLong(int id)
Convenience method used to retrieve the value of a variable as a long object.
IEImm getValueSafe(IEVar var)
Retrieve the value of a variable.
IEImm getValueSafe(int id)
Retrieve the value of a variable.
Map<Integer, IEImm> getVariables()
int getVirtualPC()
boolean hasBadValue(int id)
Determine whether the provided variable is currently set to BAD.
boolean hasSegmentBases()
boolean hasValue(int id)
Determine whether the provided variable is defined (i.e., not unknown, not set to BAD).
boolean incrementEvaluationCount()
boolean isBigEndian()
boolean isDisabledHooks()
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).
boolean isRecordBadWrites()
boolean isSoftFailMode()
Determine whether the soft-fail mode is used to track 'bad data' read attempts.
int mergeWith(EState state, IMergeController mergeController, Set<Integer> removals, Set<Integer> additions)
Merge the provided output state with this input state.
int mergeWithOld(EState state, Collection<Integer> removeMerges, boolean mergeOutputAbsentFromInput, Collection<Integer> preventMerges, Collection<Integer> discrepancies)
Merge the provided output state with this input state.
EState.Frame popFrame()
Restore the current values of PC, variables, and native stack boundaries by popping the top-level frame.
void pushFrame()
Save a frame that will contain the current virtual PC, variables, and native stack boundaries.
boolean readMemory(long address, byte[] buffer)
Read memory bytes.
int readMemory2(long address, byte[] buffer)
Read memory bytes.
void removeHooks(IEStateHooks hooks)
boolean removeValue(int id)
void setBadMemory(IVirtualMemory bad_vm)
Set a specific VM used to contain information about areas of memory that are known to contain 'bad' data.
boolean setDisabledHooks(boolean disabled)
void setExecuteSubRoutines(boolean executeSubRoutines)
void setMaxEvaluationCount(int maxEvalcnt)
void setMemory(IVirtualMemory vm)
void setNativeStackEnd(long nativeStackEnd)
Set the high-address (exclusive) for the native stack of the current frame.
void setNativeStackStart(long nativeStackStart)
Set the low-address for the native stack of the current frame.
void setPrimaryEmulator(EEmulator primaryEmulator)
void setProgramCounter(IEImm val)
Convenience method to write the PC.
void setRecordBadWrites(boolean recordBadWrites)
void setRoutineContext(IERoutineContext ectx)
void setSegmentBase(int segment, long base)
Set the memory address associated with a segment.
void setSegmentMapping(String segmentName, int segmentValue, long baseAddress)
Convenience routine.
void setSoftFailMode(boolean enabled)
Enable or disable the soft-fail mode.
void setStackPointer(IEImm val)
Convenience method to write the SP.
void setValue(IEVar var, IEImm val)
Set a variable to a defined value or the BAD value.
void setValue(int id, long val)
Set a variable to a defined value.
void setValue(IEVar var, long val)
Set a variable to a defined value.
void setVariables(Map<Integer, IEImm> vars)
Replace the variables of this state by another set of variables.
void setVirtualPC(int virtualPC)
String toString()
boolean writeMemory(long address, byte[] buffer)
Write memory bytes to specific (defined) values.
boolean writeMemoryBad(long address, int bitsize, int policy)
Specify a range of memory bytes known to contain BAD data.
boolean writeMemoryBad(long address, int bitsize)
Specify a range of memory bytes known to contain BAD data.
synchronized boolean writeMemoryInt(long address, int val)
Write a 32-bit value to memory.
synchronized boolean writeMemoryLong(long address, long val)
Write a 64-bit value to memory.
synchronized boolean writeMemoryPointer(long address, long val)
Write a pointer (address) to memory.
synchronized boolean writeMemoryShort(long address, short val)
Write a 16-bit value to memory.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int MEMREAD_BADDATA

Constant Value: -2 (0xfffffffe)

public static final int MEMREAD_FAILED

Constant Value: -1 (0xffffffff)

public static final int MEMREAD_OK

Constant Value: 0 (0x00000000)

public static final int POLICY_MEMWRITE_BADHIT_DEFAULT

Constant Value: 0 (0x00000000)

public static final int POLICY_MEMWRITE_BADHIT_FORCE_NO_RECORDING

Constant Value: 2 (0x00000002)

public static final int POLICY_MEMWRITE_BADHIT_FORCE_RECORDING

Constant Value: 1 (0x00000001)

public static final int POLICY_MEMWRITE_BADHIT_NEED_STACK_ADDRESS

Constant Value: 3 (0x00000003)

Public Constructors

public EState (IEGlobalContext gctx)

Create a state object with a fresh VM, set up according to the providing context properties.

public EState (Endianness end)

Create an empty state object with no VM, empty global vars, no local vars.

public EState (EState src)

Copy constructor.

public EState (EState src, boolean duplicateMemory)

Copy constructor. The VM may be optionally duplicated.

Public Methods

public void addHooks (IEStateHooks hooks)

public int adjustVirtualPC (int delta)

Parameters
delta increment to be added to the current virtual PC
Returns
  • the next virtual PC

public int countFrames ()

public void enableMemoryWriteHitmap (boolean enabled, boolean recordBadWrites)

public String formatVars (boolean skipZeroRegs)

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

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

public IVirtualMemory getBadMemory ()

Retrieve the optional 'bad data' VM. See setBadMemory(IVirtualMemory).

public int getEvaluationCount ()

public IEGlobalContext getGlobalContext ()

public int getMaxEvaluationCount ()

public IVirtualMemory getMemory ()

public Map<Long, Integer> getMemoryWriteHitmap ()

Returns
  • a byte-address map: address to evalcnt (internal iteration count) of the last recorded write at that address.

public long getNativeStackEnd ()

Retrieve the optional high-address (exclusive) for the native stack of the current frame.

Returns
  • an address, -1 if none

public long getNativeStackStart ()

Retrieve the optional low-address for the native stack of the current frame.

Returns
  • an address, -1 if none

public EEmulator getPrimaryEmulator ()

public IEImm getProgramCounter ()

Convenience method to read the PC. Will throw on error. A global context must have been set.

public IERoutineContext getRoutineContext ()

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

public IEImm getStackPointer ()

Convenience method to read the SP. Will throw on error. A global context must have been set.

public IEImm getValue (int id)

Retrieve the value of a variable.

Returns
  • the value; if the value is unknown or BAD, an evaluation exception is raised

public IEImm getValue (IEVar var)

Retrieve the value of a variable.

Returns
  • the value; if the value is unknown or BAD, an evaluation exception is raised

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

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

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

public IEImm getValueSafe (IEVar var)

Retrieve the value of a variable.

Returns
  • the value; null indicates either unknown or BAD

public IEImm getValueSafe (int id)

Retrieve the value of a variable.

Returns
  • the value; null indicates either unknown or BAD

public Map<Integer, IEImm> getVariables ()

public int getVirtualPC ()

public boolean hasBadValue (int id)

Determine whether the provided variable is currently set to BAD.

public boolean hasSegmentBases ()

public boolean hasValue (int id)

Determine whether the provided variable is defined (i.e., not unknown, not set to BAD).

public boolean incrementEvaluationCount ()

public boolean isBigEndian ()

public boolean isDisabledHooks ()

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).

public boolean isRecordBadWrites ()

public boolean isSoftFailMode ()

Determine whether the soft-fail mode is used to track 'bad data' read attempts.

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

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

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)

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).

public boolean readMemory (long address, byte[] buffer)

Read memory bytes.

Returns
  • success indicator

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.

Returns

public void removeHooks (IEStateHooks hooks)

public boolean removeValue (int id)

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

public boolean setDisabledHooks (boolean disabled)

public void setExecuteSubRoutines (boolean executeSubRoutines)

public void setMaxEvaluationCount (int maxEvalcnt)

public void setMemory (IVirtualMemory vm)

public void setNativeStackEnd (long nativeStackEnd)

Set the high-address (exclusive) for the native stack of the current frame.

public void setNativeStackStart (long nativeStackStart)

Set the low-address for the native stack of the current frame.

public void setPrimaryEmulator (EEmulator primaryEmulator)

public void setProgramCounter (IEImm val)

Convenience method to write the PC. Will throw on error. A global context must have been set.

public void setRecordBadWrites (boolean recordBadWrites)

public void setRoutineContext (IERoutineContext ectx)

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

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

Convenience routine.

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.

public void setStackPointer (IEImm val)

Convenience method to write the SP. Will throw on error. A global context must have been set.

public void setValue (IEVar var, IEImm val)

Set a variable to a defined value or the BAD value.

Parameters
val a value; null indicates the explicit BAD value

public void setValue (int id, long val)

Set a variable to a defined value.

Parameters
id the positive id of a global context variable

public void setValue (IEVar var, long val)

Set a variable to a defined value.

public void setVariables (Map<Integer, IEImm> vars)

Replace the variables of this state by another set of variables.

public void setVirtualPC (int virtualPC)

public String toString ()

public boolean writeMemory (long address, byte[] buffer)

Write memory bytes to specific (defined) values.

public boolean writeMemoryBad (long address, int bitsize, int policy)

Specify a range of memory bytes known to contain BAD data.

Parameters
policy one of POLICY_MEMWRITE_BADHIT_xxx

public boolean writeMemoryBad (long address, int bitsize)

Specify a range of memory bytes known to contain BAD data.

public synchronized boolean writeMemoryInt (long address, int val)

Write a 32-bit value to memory. Uses the VM-provided endianness attribute for encoding.

Returns
  • success indicator

public synchronized boolean writeMemoryLong (long address, long val)

Write a 64-bit value to memory. Uses the VM-provided endianness attribute for encoding.

Returns
  • success indicator

public synchronized boolean writeMemoryPointer (long address, long val)

Write a pointer (address) to memory. Uses the VM-provided endianness attribute for encoding.

Returns
  • success indicator

public synchronized boolean writeMemoryShort (long address, short val)

Write a 16-bit value to memory. Uses the VM-provided endianness attribute for encoding.

Returns
  • success indicator