Class EState
java.lang.Object
com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState
An IR machine state object, onto which
stand-alone evaluations
or full emulation
can be performed.-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
An emulated stack frame.static interface
Pointer sanitizer interface, used to generate a valid address from a pointer value. -
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final int
static final int
static final int
static final int
static final int
static final int
static final int
-
Constructor Summary
ConstructorsConstructorDescriptionEState
(IEGlobalContext gctx) Create a state object with a fresh VM, set up according to the providing context properties.Copy constructor.Copy constructor.EState
(Endianness end) Create an empty state object with no VM, empty global vars, no local vars. -
Method Summary
Modifier and TypeMethodDescriptionint
adjustVirtualPC
(int delta) int
void
enableMemoryWriteHitmap
(boolean enabled, boolean recordBadWrites) formatVars
(boolean skipZeroRegs) static CharSequence
formatVars
(Map<Integer, IEImm> vars, IEGlobalContext gctx, IERoutineContext ctx) static CharSequence
formatVars
(Map<Integer, IEImm> vars, IEGlobalContext gctx, IERoutineContext ctx, Collection<Integer> includedIds, Collection<Integer> excludedIds, boolean skipZeroRegs) long
generateAddressFromPointer
(long pointer) Retrieve the optional 'bad data' VM.int
int
long
Retrieve the optional high-address (exclusive) for the native stack of the current frame.long
Retrieve the optional low-address for the native stack of the current frame.Convenience method to read the PC.long
getSegmentBase
(int segment) Retrieve the memory address associated with a segment.Convenience method to read the SP.getValue
(int id) Retrieve the value of a variable.Retrieve the value of a variable.long
getValueAsLong
(int id) Convenience method used to retrieve the value of an initialized variable as a 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.getValueSafe
(int id) Retrieve the value of a variable.getValueSafe
(IEVar var) Retrieve the value of a variable.int
boolean
hasBadValue
(int id) Determine whether the provided variable is currently set to BAD.boolean
boolean
hasValue
(int id) Determine whether the provided variable is defined (i.e., not unknown, not set to BAD).boolean
boolean
boolean
boolean
Determine whether call-to-sub PC-assigns are truly evaluated (the state controller, such as theEEmulator
, is responsible for adjusting the state), or simply skipped over (only the side-effects are applied).boolean
boolean
boolean
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.popFrame()
Restore the current values of PC, variables, and native stack boundaries by popping the top-level frame.void
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
registerHooks
(IEStateHooks hooks, boolean insertFirst) 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
void
setMemoryAutoAllocOnWrite
(boolean enabled) 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
setPointerSanitizer
(EState.PointerSanitizer pointerSanitizer) void
setPrimaryEmulator
(EEmulator primaryEmulator) void
setProgramCounter
(IEImm val) Convenience method to write the PC.void
setRecordBadWrites
(boolean recordBadWrites) void
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
(int id, long val) Set a variable to a defined value.void
Set a variable to a defined value.void
Set a variable to a defined value or the BAD value.void
setVariables
(Map<Integer, IEImm> vars) Replace the variables of this state by another set of variables.void
setVirtualPC
(int virtualPC) toString()
void
unregisterHooks
(IEStateHooks hooks) boolean
writeMemory
(long address, byte[] buffer) Write memory bytes to specific (defined) values.boolean
writeMemoryBad
(long address, int bitsize) Specify a range of memory bytes known to contain BAD data.boolean
writeMemoryBad
(long address, int bitsize, int policy) Specify a range of memory bytes known to contain BAD data.boolean
writeMemoryInt
(long address, int val) Write a 32-bit value to memory.boolean
writeMemoryLong
(long address, long val) Write a 64-bit value to memory.boolean
writeMemoryPointer
(long address, long val) Write a pointer (address) to memory.boolean
writeMemoryShort
(long address, short val) Write a 16-bit value to memory.
-
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
Create a state object with a fresh VM, set up according to the providing context properties.- Parameters:
gctx
-
-
EState
Create an empty state object with no VM, empty global vars, no local vars.- Parameters:
end
-
-
EState
Copy constructor.- Parameters:
src
-
-
EState
Copy constructor. The VM may be optionally duplicated.- Parameters:
src
-duplicateMemory
-
-
-
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
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 theEEmulator
, 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
-
getRoutineContext
-
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
- Returns:
- a byte-address map: address to evalcnt (internal iteration count) of the last recorded write at that address.
-
setPrimaryEmulator
-
getPrimaryEmulator
-
registerHooks
-
unregisterHooks
-
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 statemergeController
- optional controller, will useStandardMergeController
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 keptmergeOutputAbsentFromInput
- 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 parameterpreventMerges
- optional input collection of registers that cannot be merged; disregarded if `mergeOutputAbsentFromInput` is falsediscrepancies
- optional output collection of mismatched registers (discrepancies)- Returns:
- the number of merges performed + discrepancies found
-
isBigEndian
public boolean isBigEndian() -
getVariables
-
setVariables
Replace the variables of this state by another set of variables.- Parameters:
vars
-
-
getValueSafe
Retrieve the value of a variable.- Parameters:
var
-- Returns:
- the value; null indicates either unknown or BAD
-
getValueSafe
Retrieve the value of a variable.- Parameters:
id
- variable id- Returns:
- the value; null indicates either unknown or BAD
-
getValue
Retrieve the value of a variable.- Parameters:
var
-- Returns:
- the value; if the value is unknown or BAD, an evaluation exception is raised
-
getValue
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 aEvaluationException
if the variable is uninitialized or BAD.- Parameters:
id
- variable id- Returns:
- the value
-
getValueAsLongSafe
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 aEvaluationException
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 variableval
-
-
setValue
Set a variable to a defined value.- Parameters:
var
-val
-
-
setValue
Set a variable to a defined value or the BAD value.- Parameters:
var
-val
- a value; null indicates the explicit BAD value
-
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
Convenience method to read the PC. Will throw on error. A global context must have been set.- Returns:
-
setProgramCounter
Convenience method to write the PC. Will throw on error. A global context must have been set.- Parameters:
val
-
-
getStackPointer
Convenience method to read the SP. Will throw on error. A global context must have been set.- Returns:
-
setStackPointer
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 registerbase
- 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
Convenience routine. -
getMemory
-
setMemory
-
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. SeesetBadMemory(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
Retrieve the optional 'bad data' VM. SeesetBadMemory(IVirtualMemory)
.- Returns:
-
setBadMemory
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() -
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 asreadMemory(long, byte[])
, but provide a finer result when in soft-fail mode.- Parameters:
address
-buffer
-- Returns:
- either
MEMREAD_OK
,MEMREAD_FAILED
, orMEMREAD_BADDATA
(on soft-fail mode only)
-
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 ofPOLICY_MEMWRITE_BADHIT_xxx
- Returns:
-
toString
-
formatVars
-
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) -
setPointerSanitizer
-
getPointerSanitizer
-
generateAddressFromPointer
public long generateAddressFromPointer(long pointer)
-