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

Class EEmulator

java.lang.Object
com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.EEmulator
public class EEmulator extends Object
IR emulator, a controller for an IR state. Also referred to as a "processor emulator", because this object is used to control the emulation of processor instructions converted to intermediate code.

How to use:
- pass an existing EState to a constructor or use createStandard(IEGlobalContext) to create a state and an emulator
- use the settters to customize the emulator.
- setup() it
- run() it

Three modes of execution:
1- IR routine emulation
2- IR routine-supported stub emulation
3- Global routine emulation (disregarding routines), a generalized variant of 2, suitable for full program emulation
4- Global stub emulation

The full mode supports multi-threading and multi-processing (thread groups). 

 default memory addresses (can be changed):
   baseAddressForExterns  0x7A00_0000
   defaultStackBase       0x7E00_0000
   defaultReturnAddr      0x1122_3340

  • Field Details

    • debugLogEnabled

      public static boolean debugLogEnabled

    • extraVerboseLogInsn

      public static boolean extraVerboseLogInsn

    • extraVerboseLogIR

      public static boolean extraVerboseLogIR

    • defaultMaxIterCount

      public static final int defaultMaxIterCount
      See Also:

    • defaultAllowOpt

      public static final boolean defaultAllowOpt
      See Also:

    • defaultStackBase

      public static final long defaultStackBase
      See Also:

    • defaultResetUnknownRegisters

      public static final boolean defaultResetUnknownRegisters
      See Also:

    • defaultReturnAddr

      public static final long defaultReturnAddr
      See Also:

    • defaultRecordMemoryWrites

      public static final boolean defaultRecordMemoryWrites
      See Also:

    • defaultExternsBase

      public static final long defaultExternsBase
      See Also:

    • defaultExternsEnd

      public static final long defaultExternsEnd
      See Also:

  • Constructor Details

    • EEmulator

      public EEmulator(EState state)

  • Method Details

    • log

      public void log(String format, Object... args)

    • log

      public void log(int detail, String format, Object... args)

    • createStandard

      public static EEmulator createStandard(IEGlobalContext gctx)
      Create an emulator as well as a standard emulation state that will be controlled by the emulator. Set the standard maximum iteration count to 10000.
      Parameters:
      gctx -
      Returns:

    • createStandard

      public static EEmulator createStandard(IEGlobalContext gctx, int maxIterationCount)
      Create an emulator as well as a standard emulation state that will be controlled by the emulator.
      Parameters:
      gctx -
      maxIterationCount -
      Returns:

    • getGlobalContext

      public IEGlobalContext getGlobalContext()

    • getRegisterSize

      public int getRegisterSize()

    • getAddressSize

      public int getAddressSize()

    • getStackSlotSize

      public int getStackSlotSize()

    • setRecordMemoryWrites

      public void setRecordMemoryWrites(boolean recordMemoryWrites)

    • setResetUnknownRegisters

      public void setResetUnknownRegisters(boolean enabled)
      Must be called before setup().
      Parameters:
      enabled -

    • setPreferredStackBase

      public void setPreferredStackBase(long address)
      Must be called before setup().
      Parameters:
      address -

    • setExternsRange

      public void setExternsRange(long base, long end)
      Must be called before setup().
      Parameters:
      address -

    • setPerformFreshDecompilations

      public void setPerformFreshDecompilations(boolean performFreshDecompilations)

    • setStubExecution

      public void setStubExecution(IERoutineContext ctx, int irStart, int irStop)

    • setStubExecution

      public void setStubExecution(INativeMethodItem routine, long pcStart, long pcStop)

    • setTargetRoutine

      public void setTargetRoutine(INativeMethodItem routine)

    • setPreferredTargetPrototype

      public void setPreferredTargetPrototype(IPrototypeItem proto)

    • setGlobalRoutineEmulation

      public void setGlobalRoutineEmulation(INativeMethodItem routine)

    • setGlobalRoutineEmulation

      public void setGlobalRoutineEmulation(long routineAddress, IPrototypeItem routinePrototype)

    • setGlobalStubEmulation

      public void setGlobalStubEmulation(long pcStart, Long pcStop)

    • setReturnAddress

      public void setReturnAddress(long retAddr)

    • clearArgument

      public void clearArgument()

    • addArgument

      public void addArgument(long val, INativeType t)

    • addArgument

      public void addArgument(byte[] val, INativeType t)

    • addArgument

      public void addArgument(IEImm val)

    • setArguments

      public void setArguments(Collection<IEImm> vals)

    • retrievePrototype

      public static IPrototypeItem retrievePrototype(INativeDecompilerContext decomp, INativeMethodItem routine)
      Convenience method used to verify whether or not an emulator object would be able to retrieve a target method prototype.
      Parameters:
      decomp - decompiler unit
      routine - candidate target routine
      Returns:
      the retrieved prototype that would be used by an emulator for the provided target routine

    • setup

      public void setup()

    • setStack

      public boolean setStack(long stackStart, int stackSize, Long sp0)

    • teardown

      public void teardown()
      Clean-up temporary constructs built during setup().

    • isPrimaryEmulator

      public boolean isPrimaryEmulator()

    • getState

      public EState getState()

    • getMemory

      public IVirtualMemory getMemory()

    • getMemoryChanges

      public MemoryChanges getMemoryChanges() throws UnsupportedOperationException
      A convenience method to retrieve memory changes performed during emulation.
      Returns:
      a changes object
      Throws:
      UnsupportedOperationException - if the emulator's memory is not a shim

    • getSPAddress

      public long getSPAddress()

    • setSPAddress

      public void setSPAddress(long nativeAddress)

    • updateSPAddress

      public long updateSPAddress(int delta)
      Update the stack pointer register.
      Parameters:
      delta -
      Returns:
      the updated SP value

    • getPCAddress

      public long getPCAddress()

    • setPCAddress

      public void setPCAddress(long nativeAddress)

    • getMaxIterationCount

      public long getMaxIterationCount()

    • getIterationCount

      public long getIterationCount()

    • run

      public void run() throws EvaluationException
      Throws:
      EvaluationException

    • setLastEvaluationResult

      public void setLastEvaluationResult(IEImm val)

    • getLastEvaluationResult

      public IEImm getLastEvaluationResult()

    • findRegisteredRoutine

      public long findRegisteredRoutine(String name)

    • findRegisteredRoutineByAddress

      public String findRegisteredRoutineByAddress(long addr)

    • createPseudoRoutine

      public long createPseudoRoutine(String name)

    • createPseudoRoutine

      public long createPseudoRoutine(INativeMethodItem routine)

    • registerRoutine

      public long registerRoutine(long addr, String name)

    • registerRoutine

      public long registerRoutine(long addr, String name, boolean overwrite)

    • registerRoutine

      public long registerRoutine(long addr, INativeMethodItem routine)

    • registerRoutine

      public long registerRoutine(long addr, INativeMethodItem routine, boolean overwrite)

    • currentRequestId

      public final long currentRequestId()

    • hooksEvaluateAt

      public Boolean hooksEvaluateAt(long addr, IInstruction hintNativeStm)
      Parameters:
      addr -
      hintNativeStm -
      Returns:

    • hooksEvaluateExternal

      public Boolean hooksEvaluateExternal(String routineName, INativeMethodItem routine)
      Parameters:
      routineName - mandatory
      routine - optional
      Returns:

    • hooksEvaluateUntranslated

      public Boolean hooksEvaluateUntranslated(IEUntranslatedInstruction stm, IInstruction insn)

    • hooksEvaluateSyscall

      public boolean hooksEvaluateSyscall(long addr, IInstruction insn)

    • monitorHLSpecial

      public void monitorHLSpecial(int code, Object... params)

    • readStorage

      public IEImm readStorage(StorageEntry entry)

    • writeStorage

      public boolean writeStorage(StorageEntry entry, IEImm val)

    • processStoredReturnAddress

      public boolean processStoredReturnAddress(StorageEntry entry)
      ret-addr on stack: pop and return
      ret-addr in register: TBI

    • processStoredReturnAddress

      public boolean processStoredReturnAddress(StorageEntry entry, int stkSlotAdj)
      ret-addr on stack: pop and return
      ret-addr in register: TBI

    • readPointer

      public Long readPointer(long addr)
      Convenience method.
      Parameters:
      addr -
      Returns:

    • writePointer

      public boolean writePointer(long addr, long ptr)

    • getMemoryWrites

      public MemoryWrites getMemoryWrites()

    • getReturnValue

      public IEImm getReturnValue()

    • getReturnAddress

      public IEImm getReturnAddress()

    • getRegisterValue

      public IEImm getRegisterValue(String regname)

    • setRegisterValue

      public void setRegisterValue(String regname, IEImm val)

    • getTruncatedRegisterValue

      public long getTruncatedRegisterValue(String regname)

    • commitMemoryChanges

      public boolean commitMemoryChanges(boolean commitModifiedPagesOnly)

    • registerHooks

      public void registerHooks(IEEmulatorHooks hooks)

    • registerHooks

      public void registerHooks(IEEmulatorHooks hooks, boolean insertFirst)

    • unregisterHooks

      public void unregisterHooks(IEEmulatorHooks hooks)

    • swapHooks

      public boolean swapHooks(IEEmulatorHooks currentHooks, IEEmulatorHooks replHooks)

    • isMainProcess

      public boolean isMainProcess()

    • enableMultiThreading

      public void enableMultiThreading(Object initialProcessClientTag, Object initialThreadClientTag)
      To be called before setup().
      Parameters:
      initialProcessClientTag -
      initialThreadClientTag -

    • processCurrentIndex

      public int processCurrentIndex()

    • processCurrentTag

      public Object processCurrentTag()

    • processCreate

      public int processCreate(int pid, Long startAddress, Map<String,IEImm> regmap)
      Fork a process and optionally start a new main thread in the forked process.
      Parameters:
      pid - new process wanted pid (high-level pid, not used directly by this emulator; the emulator simply passes it along to its listener)
      startAddress - if non-null, a main thread will be created
      regmap - registers to be set in the new main thread
      Returns:

    • processTerminate

      public boolean processTerminate(int pidx)
      Mark the thread group and all the threads of the group: they will no longer be scheduled for execution.
      Parameters:
      pidx -
      exitCode - exit status code
      Returns:

    • processDestroy

      public boolean processDestroy(int pidx)

    • threadCurrentIndex

      public int threadCurrentIndex()

    • threadCurrentTag

      public Object threadCurrentTag()

    • threadCreate

      public int threadCreate(Object threadClientTag, long routineAddress, long pseudoReturnAddress, Map<String,IEImm> regmap)

    • threadTerminate

      public boolean threadTerminate(int idx, IEImm retVal)

    • threadIsTerminated

      public boolean threadIsTerminated(int idx)

    • threadDestroy

      public boolean threadDestroy(int idx)

    • threadGetAssociatedVM

      public IVirtualMemory threadGetAssociatedVM(int idx)

    • threadReadRegister

      public IEImm threadReadRegister(int idx, String registerName)

    • threadWriteRegister

      public IEImm threadWriteRegister(int idx, String registerName, IEImm value)

    • threadFreeze

      public boolean threadFreeze(int idx, boolean frozen)

    • threadJoin

      public int threadJoin(int waitingToJoinOnThreadIdx, long addrRetValStorage)
      Parameters:
      addrRetValStorage -
      waitingToJoinOnIdx -
      Returns:
      negative: error occurred; 0=joining succeeded, current thread is now WAITING; 1=no need to join, the target thread has already completed

    • threadSleep

      public void threadSleep(long waitcnt)
      Parameters:
      waitcnt - iteration count (if negative or zero, this call is treated as a yield)

    • threadYields

      public void threadYields()

    • mutexCreate

      public int mutexCreate(long addr, int attr)

    • mutexDestroy

      public boolean mutexDestroy(int idx)

    • mutexGetOwnerTidx

      public int mutexGetOwnerTidx(int idx)

    • mutexLock

      public int mutexLock(int idx, boolean tryLocking)
      Parameters:
      idx - mutex index
      tryLocking - true to attempt locking (will return 2 if the mutex is already locked)
      Returns:
      negative: error; 0= lock acquired; 1= lock in-use, thread was moved to WAITING state; 2= lock in-use, bailing

    • mutexUnlock

      public boolean mutexUnlock(int idx)

    • condCreate

      public int condCreate(long addr, int attr)

    • condDestroy

      public boolean condDestroy(int idx)

    • condSignal

      public boolean condSignal(int idx, boolean broadcast)

    • condWait

      public int condWait(int idx, int mutexIdx, long maxIterNumber)
      Parameters:
      idx -
      mutexIdx -
      maxIterNumber -
      Returns:
      negative: error occurred (e.g. the cond-var does not exist; the mutex was not acquired); 0=first call, mutex unlocked, thread is now WAITING; 1=second call, mutex re-locked; 2=second call, mutex re-locked, timeout ellapsed cond var was not signaled

    • setTaskSupervisor

      public void setTaskSupervisor(EEmulator.ITaskSupervisor taskListener)