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  
interface EState.IHooks EState hooks interface and adapter (defaults return null= do nothing and proceed). 
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
int adjustVirtualPC(int delta)
int countFrames()
void enableMemoryWriteHitmap(boolean enabled, boolean recordBadWrites)
static CharSequence formatVars(Map<Integer, IEImm> vars, IERoutineContext ctx, Collection<Integer> includedIds, Collection<Integer> excludedIds)
static CharSequence formatVars(Map<Integer, IEImm> vars, IERoutineContext ctx)
IVirtualMemory getBadMemory()
Set the VM used to enable soft-fail mode.
int getEvaluationCount()
IEGlobalContext getGlobalContext()
EState.IHooks getHooks()
int getMaxEvaluationCount()
IVirtualMemory getMemory()
Map<Long, Integer> getMemoryWriteHitmap()
long getNativeStackEnd()
long getNativeStackStart()
IREmulator getPrimaryEmulator()
IEImm getProgramCounter()
Convenience method to read the PC.
IERoutineContext getRoutineContext()
long getSegmentBase(int 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 hasSegmentBase()
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 IREmulator, is responsible for adjusting the state), or simply skipped over (only the side-effects are applied).
boolean isRecordBadWrites()
boolean isSoftFailMode()
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()
void pushFrame()
boolean readMemory(long address, byte[] buffer)
Read memory bytes.
int readMemory2(long address, byte[] buffer)
Read memory bytes.
boolean removeValue(int id)
void setBadMemory(IVirtualMemory bad_vm)
boolean setDisabledHooks(boolean disabled)
void setExecuteSubRoutines(boolean executeSubRoutines)
void setHooks(EState.IHooks hooks)
void setMaxEvaluationCount(int maxEvalcnt)
void setMemory(IVirtualMemory vm)
void setNativeStackEnd(long nativeStackEnd)
void setNativeStackStart(long nativeStackStart)
void setPrimaryEmulator(IREmulator 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)
void setSoftFailMode(boolean enabled)
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.
[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 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 static CharSequence formatVars (Map<Integer, IEImm> vars, IERoutineContext ctx, Collection<Integer> includedIds, Collection<Integer> excludedIds)

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

public IVirtualMemory getBadMemory ()

Set the VM used to enable soft-fail mode.

public int getEvaluationCount ()

public IEGlobalContext getGlobalContext ()

public EState.IHooks getHooks ()

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

public long getNativeStackStart ()

public IREmulator 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)

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 hasSegmentBase ()

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 IREmulator, is responsible for adjusting the state), or simply skipped over (only the side-effects are applied).

public boolean isRecordBadWrites ()

public boolean isSoftFailMode ()

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

public void pushFrame ()

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 boolean removeValue (int id)

public void setBadMemory (IVirtualMemory bad_vm)

public boolean setDisabledHooks (boolean disabled)

public void setExecuteSubRoutines (boolean executeSubRoutines)

public void setHooks (EState.IHooks hooks)

public void setMaxEvaluationCount (int maxEvalcnt)

public void setMemory (IVirtualMemory vm)

public void setNativeStackEnd (long nativeStackEnd)

public void setNativeStackStart (long nativeStackStart)

public void setPrimaryEmulator (IREmulator 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)

public void setSoftFailMode (boolean enabled)

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.