# Class: com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.EEmulator

IR emulator, a controller for an [IR state](EState). 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](EState) to a constructor or use [#createStandard(IEGlobalContext)](#createStandard(IEGlobalContext)) to create a state and an emulator
 \- use the `settters` to customize the emulator.
 \- [#setup()](#setup()) it
 \- [#run()](#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
 
```

## Constructor: EEmulator
- parameter: `state`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState`


## Static Field: debugLogEnabled
Type: `boolean`

## Static Field: defaultAllowOpt
Type: `boolean`

Constant value: `false`

## Static Field: defaultExternsBase
Type: `long`

Constant value: `2046820352`

## Static Field: defaultExternsEnd
Type: `long`

Constant value: `2046885888`

## Static Field: defaultMaxIterCount
Type: `int`

Constant value: `10000`

## Static Field: defaultRecordMemoryWrites
Type: `boolean`

Constant value: `false`

## Static Field: defaultResetUnknownRegisters
Type: `boolean`

Constant value: `true`

## Static Field: defaultReturnAddr
Type: `long`

Constant value: `287454016`

## Static Field: defaultStackBase
Type: `long`

Constant value: `2113929216`

## Static Field: extraVerboseLogIR
Type: `boolean`

## Static Field: extraVerboseLogInsn
Type: `boolean`

## Method: addArgument
- parameter: `val`, type: `long`
- parameter: `t`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.INativeType`


## Method: addArgument
- parameter: `val`, type: `byte[]`
- parameter: `t`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.INativeType`


## Method: addArgument
- parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: clearArgument


## Method: commitMemoryChanges
- parameter: `commitModifiedPagesOnly`, type: `boolean`
- return type: `boolean`


## Method: condCreate
- parameter: `addr`, type: `long`
- parameter: `attr`, type: `int`
- return type: `int`


## Method: condDestroy
- parameter: `idx`, type: `int`
- return type: `boolean`


## Method: condSignal
- parameter: `idx`, type: `int`
- parameter: `broadcast`, type: `boolean`
- return type: `boolean`


## Method: condWait
- parameter: `idx`, type: `int`
- parameter: `mutexIdx`, type: `int`
- parameter: `maxIterNumber`, type: `long`
- return type: `int`

Description: 
parameter: idx: 
parameter: mutexIdx: 
parameter: maxIterNumber: 
return: 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

## Method: createPseudoRoutine
- parameter: `name`, type: `java.lang.String`
- return type: `long`


## Method: createPseudoRoutine
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- return type: `long`


## Method: currentRequestId
- return type: `long`


## Method: enableMultiThreading
- parameter: `initialProcessClientTag`, type: `java.lang.Object`
- parameter: `initialThreadClientTag`, type: `java.lang.Object`

Description: To be called before [#setup()](#setup()).
parameter: initialProcessClientTag: 
parameter: initialThreadClientTag: 

## Method: findRegisteredRoutine
- parameter: `name`, type: `java.lang.String`
- return type: `long`


## Method: findRegisteredRoutineByAddress
- parameter: `addr`, type: `long`
- return type: `java.lang.String`


## Method: getAddressSize
- return type: `int`


## Method: getGlobalContext
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEGlobalContext`


## Method: getIterationCount
- return type: `long`


## Method: getLastEvaluationResult
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: getMaxIterationCount
- return type: `long`


## Method: getMemory
- return type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory`


## Method: getMemoryChanges
- return type: `com.pnfsoftware.jeb.core.units.code.asm.memory.MemoryChanges`

Description: A convenience method to retrieve memory changes performed during emulation.
return: a changes object
throws: if the emulator's memory is not a shim

## Method: getMemoryWrites
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.MemoryWrites`


## Method: getPCAddress
- return type: `long`


## Method: getRegisterSize
- return type: `int`


## Method: getRegisterValue
- parameter: `regname`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: getReturnAddress
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: getReturnValue
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: getSPAddress
- return type: `long`


## Method: getStackSlotSize
- return type: `int`


## Method: getState
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState`


## Method: getTruncatedRegisterValue
- parameter: `regname`, type: `java.lang.String`
- return type: `long`


## Method: hooksEvaluateAt
- parameter: `addr`, type: `long`
- parameter: `hintNativeStm`, type: `com.pnfsoftware.jeb.core.units.code.IInstruction`
- return type: `java.lang.Boolean`

Description: 
parameter: addr: 
parameter: hintNativeStm: 
return: 

## Method: hooksEvaluateExternal
- parameter: `routineName`, type: `java.lang.String`
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- return type: `java.lang.Boolean`

Description: 
parameter: routineName: mandatory
parameter: routine: optional
return: 

## Method: hooksEvaluateSyscall
- parameter: `addr`, type: `long`
- parameter: `insn`, type: `com.pnfsoftware.jeb.core.units.code.IInstruction`
- return type: `boolean`


## Method: hooksEvaluateUntranslated
- parameter: `stm`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEUntranslatedInstruction`
- parameter: `insn`, type: `com.pnfsoftware.jeb.core.units.code.IInstruction`
- return type: `java.lang.Boolean`


## Method: isMainProcess
- return type: `boolean`


## Method: isPrimaryEmulator
- return type: `boolean`


## Method: log
- parameter: `format`, type: `java.lang.String`
- parameter: `args`, type: `java.lang.Object[]`


## Method: log
- parameter: `detail`, type: `int`
- parameter: `format`, type: `java.lang.String`
- parameter: `args`, type: `java.lang.Object[]`


## Method: monitorHLSpecial
- parameter: `code`, type: `int`
- parameter: `params`, type: `java.lang.Object[]`


## Method: mutexCreate
- parameter: `addr`, type: `long`
- parameter: `attr`, type: `int`
- return type: `int`


## Method: mutexDestroy
- parameter: `idx`, type: `int`
- return type: `boolean`


## Method: mutexGetOwnerTidx
- parameter: `idx`, type: `int`
- return type: `int`


## Method: mutexLock
- parameter: `idx`, type: `int`
- parameter: `tryLocking`, type: `boolean`
- return type: `int`

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

## Method: mutexUnlock
- parameter: `idx`, type: `int`
- return type: `boolean`


## Method: processCreate
- parameter: `pid`, type: `int`
- parameter: `startAddress`, type: `java.lang.Long`
- parameter: `regmap`, type: `java.util.Map<java.lang.String,com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm>`
- return type: `int`

Description: Fork a process and optionally start a new main thread in the forked process.
parameter: pid: new process wanted pid \(high\-level pid, not used directly by this emulator; the            emulator simply passes it along to its listener\)
parameter: startAddress: if non\-null, a main thread will be created
parameter: regmap: registers to be set in the new main thread
return: 

## Method: processCurrentIndex
- return type: `int`


## Method: processCurrentTag
- return type: `java.lang.Object`


## Method: processDestroy
- parameter: `pidx`, type: `int`
- return type: `boolean`


## Method: processStoredReturnAddress
- parameter: `entry`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.StorageEntry`
- return type: `boolean`

Description: ret\-addr on stack: pop and return
 ret\-addr in register: TBI

## Method: processStoredReturnAddress
- parameter: `entry`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.StorageEntry`
- parameter: `stkSlotAdj`, type: `int`
- return type: `boolean`

Description: ret\-addr on stack: pop and return
 ret\-addr in register: TBI

## Method: processTerminate
- parameter: `pidx`, type: `int`
- return type: `boolean`

Description: Mark the thread group and all the threads of the group: they will no longer be scheduled for execution.
parameter: pidx: process index
return: true if the process was marked for termination

## Method: readPointer
- parameter: `addr`, type: `long`
- return type: `java.lang.Long`

Description: Convenience method.
parameter: addr: 
return: 

## Method: readStorage
- parameter: `entry`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.StorageEntry`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: registerHooks
- parameter: `hooks`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.IEEmulatorHooks`


## Method: registerHooks
- parameter: `hooks`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.IEEmulatorHooks`
- parameter: `insertFirst`, type: `boolean`


## Method: registerRoutine
- parameter: `addr`, type: `long`
- parameter: `name`, type: `java.lang.String`
- return type: `long`


## Method: registerRoutine
- parameter: `addr`, type: `long`
- parameter: `name`, type: `java.lang.String`
- parameter: `overwrite`, type: `boolean`
- return type: `long`


## Method: registerRoutine
- parameter: `addr`, type: `long`
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- return type: `long`


## Method: registerRoutine
- parameter: `addr`, type: `long`
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- parameter: `overwrite`, type: `boolean`
- return type: `long`


## Method: run


## Method: setArguments
- parameter: `vals`, type: `java.util.Collection<com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm>`


## Method: setExternsRange
- parameter: `base`, type: `long`
- parameter: `end`, type: `long`

Description: Must be called before [#setup()](#setup()).
parameter: base: external memory range start
parameter: end: external memory range end

## Method: setGlobalRoutineEmulation
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`


## Method: setGlobalRoutineEmulation
- parameter: `routineAddress`, type: `long`
- parameter: `routinePrototype`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.IPrototypeItem`


## Method: setGlobalStubEmulation
- parameter: `pcStart`, type: `long`
- parameter: `pcStop`, type: `java.lang.Long`


## Method: setLastEvaluationResult
- parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: setPCAddress
- parameter: `nativeAddress`, type: `long`


## Method: setPerformFreshDecompilations
- parameter: `performFreshDecompilations`, type: `boolean`


## Method: setPreferredStackBase
- parameter: `address`, type: `long`

Description: Must be called before [#setup()](#setup()).
parameter: address: 

## Method: setPreferredTargetPrototype
- parameter: `proto`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.IPrototypeItem`


## Method: setRecordMemoryWrites
- parameter: `recordMemoryWrites`, type: `boolean`


## Method: setRegisterValue
- parameter: `regname`, type: `java.lang.String`
- parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: setResetUnknownRegisters
- parameter: `enabled`, type: `boolean`

Description: Must be called before [#setup()](#setup()).
parameter: enabled: 

## Method: setReturnAddress
- parameter: `retAddr`, type: `long`


## Method: setSPAddress
- parameter: `nativeAddress`, type: `long`


## Method: setStack
- parameter: `stackStart`, type: `long`
- parameter: `stackSize`, type: `int`
- parameter: `sp0`, type: `java.lang.Long`
- return type: `boolean`


## Method: setStubExecution
- parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext`
- parameter: `irStart`, type: `int`
- parameter: `irStop`, type: `int`


## Method: setStubExecution
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- parameter: `pcStart`, type: `long`
- parameter: `pcStop`, type: `long`


## Method: setTargetRoutine
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`


## Method: setTaskSupervisor
- parameter: `taskListener`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.EEmulator.ITaskSupervisor`


## Method: setup


## Method: swapHooks
- parameter: `currentHooks`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.IEEmulatorHooks`
- parameter: `replHooks`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.IEEmulatorHooks`
- return type: `boolean`


## Method: teardown

Description: Clean\-up temporary constructs built during [#setup()](#setup()).

## Method: threadCreate
- parameter: `threadClientTag`, type: `java.lang.Object`
- parameter: `routineAddress`, type: `long`
- parameter: `pseudoReturnAddress`, type: `long`
- parameter: `regmap`, type: `java.util.Map<java.lang.String,com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm>`
- return type: `int`


## Method: threadCurrentIndex
- return type: `int`


## Method: threadCurrentTag
- return type: `java.lang.Object`


## Method: threadDestroy
- parameter: `idx`, type: `int`
- return type: `boolean`


## Method: threadFreeze
- parameter: `idx`, type: `int`
- parameter: `frozen`, type: `boolean`
- return type: `boolean`


## Method: threadGetAssociatedVM
- parameter: `idx`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory`


## Method: threadIsTerminated
- parameter: `idx`, type: `int`
- return type: `boolean`


## Method: threadJoin
- parameter: `waitingToJoinOnThreadIdx`, type: `int`
- parameter: `addrRetValStorage`, type: `long`
- return type: `int`

Description: 
parameter: waitingToJoinOnThreadIdx: thread index to wait on
parameter: addrRetValStorage: address where the joined thread return value should be stored
return: negative: error occurred; 0=joining succeeded, current thread is now WAITING; 1=no         need to join, the target thread has already completed

## Method: threadReadRegister
- parameter: `idx`, type: `int`
- parameter: `registerName`, type: `java.lang.String`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: threadSleep
- parameter: `waitcnt`, type: `long`

Description: 
parameter: waitcnt: iteration count \(if negative or zero, this call is treated as a            [yield](#threadYields())\)

## Method: threadTerminate
- parameter: `idx`, type: `int`
- parameter: `retVal`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`
- return type: `boolean`


## Method: threadWriteRegister
- parameter: `idx`, type: `int`
- parameter: `registerName`, type: `java.lang.String`
- parameter: `value`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`


## Method: threadYields


## Method: unregisterHooks
- parameter: `hooks`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.IEEmulatorHooks`


## Method: updateSPAddress
- parameter: `delta`, type: `int`
- return type: `long`

Description: Update the stack pointer register.
parameter: delta: 
return: the updated SP value

## Method: writePointer
- parameter: `addr`, type: `long`
- parameter: `ptr`, type: `long`
- return type: `boolean`


## Method: writeStorage
- parameter: `entry`, type: `com.pnfsoftware.jeb.core.units.code.asm.type.StorageEntry`
- parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm`
- return type: `boolean`


## Static Method: createStandard
- parameter: `gctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEGlobalContext`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.EEmulator`

Description: Create an emulator as well as a standard [emulation state](EState) that will be controlled by the emulator. Set the standard maximum iteration count to `#defaultMaxIterCount`.
parameter: gctx: 
return: 

## Static Method: createStandard
- parameter: `gctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEGlobalContext`
- parameter: `maxIterationCount`, type: `int`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.EEmulator`

Description: Create an emulator as well as a standard [emulation state](EState) that will be controlled by the emulator.
parameter: gctx: 
parameter: maxIterationCount: 
return: 

## Static Method: retrievePrototype
- parameter: `decomp`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.INativeDecompilerContext`
- parameter: `routine`, type: `com.pnfsoftware.jeb.core.units.code.asm.items.INativeMethodItem`
- return type: `com.pnfsoftware.jeb.core.units.code.asm.type.IPrototypeItem`

Description: Convenience method used to verify whether or not an emulator object would be able to retrieve a target method prototype.
parameter: decomp: decompiler unit
parameter: routine: candidate target routine
return: the retrieved prototype that would be used by an emulator for the provided target         routine

