# Class: com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState An IR machine state object, onto which [stand\-alone evaluations](IEGeneric#evaluate(EState)) or [full emulation](EEmulator) can be performed. ## Constructor: EState - parameter: `gctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEGlobalContext` Description: Create a state object with a fresh VM, set up according to the providing context properties. parameter: gctx: ## Constructor: EState - parameter: `end`, type: `com.pnfsoftware.jeb.util.io.Endianness` Description: Create an empty state object with no VM, empty global vars, no local vars. parameter: end: ## Constructor: EState - parameter: `src`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState` - parameter: `duplicateMemory`, type: `boolean` Description: Copy constructor. parameter: src: ## Constructor: EState - parameter: `src`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState` - parameter: `duplicateMemory`, type: `boolean` - parameter: `copyHooks`, type: `boolean` Description: Copy constructor. The VM may be optionally duplicated. parameter: src: parameter: duplicateMemory: if true, the VM for the state is a deep copy of the current provided state's; else, the VM of the new state will be the same as the provided state's parameter: copyHooks: if true, the new state will receive a copy of the provided state's hooks; else, the new state will have an empty hooks list ## Static Field: MEMREAD_BADDATA Type: `int` Constant value: `-2` ## Static Field: MEMREAD_FAILED Type: `int` Constant value: `-1` ## Static Field: MEMREAD_OK Type: `int` Constant value: `0` ## Static Field: POLICY_MEMWRITE_BADHIT_DEFAULT Type: `int` Constant value: `0` ## Static Field: POLICY_MEMWRITE_BADHIT_FORCE_NO_RECORDING Type: `int` Constant value: `2` ## Static Field: POLICY_MEMWRITE_BADHIT_FORCE_RECORDING Type: `int` Constant value: `1` ## Static Field: POLICY_MEMWRITE_BADHIT_NEED_STACK_ADDRESS Type: `int` Constant value: `3` ## Method: adjustVirtualPC - parameter: `delta`, type: `int` - return type: `int` Description: parameter: delta: increment to be added to the current virtual PC return: the next virtual PC ## Method: allocateMemory - parameter: `address`, type: `long` - parameter: `size`, type: `int` - parameter: `protection`, type: `int` - return type: `long` Description: parameter: address: base address, page\-aligned parameter: size: size will be rounded to a page \(ceil\) parameter: protection: return: \-1 on error ## Method: countFrames - return type: `int` ## Method: enableMemoryWriteHitmap - parameter: `enabled`, type: `boolean` - parameter: `recordBadWrites`, type: `boolean` ## Method: forkState - parameter: `lightFork`, type: `boolean` - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState.StateInfo` Description: parameter: lightFork: a light fork does not duplicate the VM \(which means it can be used for thread creation inside an existing process\) return: ## Method: formatVars - parameter: `skipZeroRegs`, type: `boolean` - return type: `java.lang.String` ## Method: freeMemory - parameter: `address`, type: `long` - parameter: `size`, type: `int` - return type: `boolean` ## Method: getBadMemory - return type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory` Description: Retrieve the optional 'bad data' VM. See [EState#setBadMemory(IVirtualMemory)](EState#setBadMemory(IVirtualMemory)). return: ## Method: getEvaluationCount - return type: `int` ## Method: getGlobalContext - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEGlobalContext` ## Method: getMaxEvaluationCount - return type: `int` ## Method: getMemory - return type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory` ## Method: getMemoryReadCount - return type: `long` ## Method: getMemoryWriteCount - return type: `long` ## Method: getMemoryWriteHitmap - return type: `java.util.Map` Description: return: a byte\-address map: address to evalcnt \(internal iteration count\) of the last recorded write at that address. ## Method: getNativeStackEnd - return type: `long` Description: Retrieve the optional high\-address \(exclusive\) for the native stack of the current frame. return: an address, \-1 if none ## Method: getNativeStackStart - return type: `long` Description: Retrieve the optional low\-address for the native stack of the current frame. return: an address, \-1 if none ## Method: getPrimaryEmulator - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.EEmulator` ## Method: getProgramCounter - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Convenience method to read the PC. Will throw on error. A global context must have been set. return: ## Method: getRoutineContext - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext` ## Method: getSegmentBase - parameter: `segment`, type: `int` - return type: `long` Description: Retrieve the memory address associated with a segment. parameter: segment: the value of a segment register return: the base memory address associated with the segment; 0 if none ## Method: getStackPointer - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Convenience method to read the SP. Will throw on error. A global context must have been set. return: ## Method: getValue - parameter: `var`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar` - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Retrieve the value of a variable. parameter: var: return: the value; if the value is unknown or BAD, an evaluation exception is raised ## Method: getValue - parameter: `id`, type: `int` - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Retrieve the value of a variable. parameter: id: variable id return: the value; if the value is unknown or BAD, an evaluation exception is raised ## Method: getValueAsLong - parameter: `id`, type: `int` - return type: `long` Description: Convenience method used to retrieve the value of an initialized variable as a long. This method throws a [EvaluationException](EvaluationException) if the variable is uninitialized or BAD. parameter: id: variable id return: the value ## Method: getValueAsLongSafe - parameter: `id`, type: `int` - return type: `java.lang.Long` Description: 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. parameter: id: variable id return: the value or null ## Method: getValueAsUnsignedLong - parameter: `id`, type: `int` - return type: `long` Description: Convenience method used to retrieve the value of a variable as a long object. This method throws a [EvaluationException](EvaluationException) if the variable is uninitialized or BAD. parameter: id: variable id return: the value ## Method: getValueSafe - parameter: `var`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar` - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Retrieve the value of a variable. parameter: var: return: the value; null indicates either unknown or BAD ## Method: getValueSafe - parameter: `id`, type: `int` - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Retrieve the value of a variable. parameter: id: variable id return: the value; null indicates either unknown or BAD ## Method: getVariables - return type: `java.util.Map` ## Method: getVirtualPC - return type: `int` ## Method: hasBadValue - parameter: `id`, type: `int` - return type: `boolean` Description: Determine whether the provided variable is currently set to BAD. parameter: id: return: ## Method: hasSegmentBases - return type: `boolean` ## Method: hasValue - parameter: `id`, type: `int` - return type: `boolean` Description: Determine whether the provided variable is defined \(i.e., not unknown, not set to BAD\). parameter: id: return: ## Method: incrementEvaluationCount - return type: `boolean` ## Method: isBigEndian - return type: `boolean` ## Method: isDisabledHooks - return type: `boolean` ## Method: isExecuteSubRoutines - return type: `boolean` Description: Determine whether call\-to\-sub PC\-assigns are truly evaluated \(the state controller, such as the [EEmulator](EEmulator), is responsible for adjusting the state\), or simply skipped over \(only the side\-effects are applied\). return: ## Method: isMemoryAutoAllocOnWrite - return type: `boolean` ## Method: isMemoryBypassProtection - return type: `boolean` ## Method: isRecordBadWrites - return type: `boolean` ## Method: isSoftFailMode - return type: `boolean` Description: Determine whether the soft\-fail mode is used to track 'bad data' read attempts. return: ## Method: loadState - parameter: `info`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState.StateInfo` ## Method: mergeWith - parameter: `state`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState` - parameter: `mergeController`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IMergeController` - parameter: `removals`, type: `java.util.Set` - parameter: `additions`, type: `java.util.Set` - return type: `int` Description: Merge the provided output state with this input state. Memories are not merged. parameter: state: input state parameter: mergeController: optional controller, will use [StandardMergeController](StandardMergeController) if none is provided return: the number of discrepancies and extra mergers performed ## Method: mergeWithOld - parameter: `state`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState` - parameter: `removeMerges`, type: `java.util.Collection` - parameter: `mergeOutputAbsentFromInput`, type: `boolean` - parameter: `preventMerges`, type: `java.util.Collection` - parameter: `discrepancies`, type: `java.util.Collection` - return type: `int` Description: Merge the provided output state with this input state. Memories are not merged. parameter: state: second state \(the output\), to be merged with \`this\` \(the input\) parameter: 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 parameter: 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 parameter: preventMerges: optional input collection of registers that cannot be merged; disregarded if \`mergeOutputAbsentFromInput\` is false parameter: discrepancies: optional output collection of mismatched registers \(discrepancies\) return: the number of merges performed \+ discrepancies found ## Method: popFrame - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState.Frame` Description: Restore the current values of PC, variables, and native stack boundaries by popping the top\-level frame. return: the previous frame, or null on error \(if the stack frame was empty\) ## Method: pushFrame Description: 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](IECall) emulation\). ## Method: readMemory - parameter: `address`, type: `long` - parameter: `buffer`, type: `byte[]` - return type: `boolean` Description: Read memory bytes. parameter: address: parameter: buffer: return: success indicator ## Method: readMemory2 - parameter: `address`, type: `long` - parameter: `buffer`, type: `byte[]` - return type: `int` Description: Read memory bytes. Same as [#readMemory(long, byte[])](#readMemory(long, byte[])), but provide a finer result when in soft\-fail mode. parameter: address: parameter: buffer: return: either [#MEMREAD_OK](#MEMREAD_OK), [#MEMREAD_FAILED](#MEMREAD_FAILED), or [#MEMREAD_BADDATA](#MEMREAD_BADDATA) \(on soft\-fail mode only\) ## Method: registerHooks - parameter: `hooks`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStateHooks` - parameter: `insertFirst`, type: `boolean` ## Method: removeValue - parameter: `id`, type: `int` - return type: `boolean` ## Method: saveState - return type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.EState.StateInfo` ## Method: setBadMemory - parameter: `bad_vm`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory` Description: 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](#setSoftFailMode(boolean)) mode. parameter: bad_vm: optional memory object ## Method: setDisabledHooks - parameter: `disabled`, type: `boolean` - return type: `boolean` ## Method: setExecuteSubRoutines - parameter: `executeSubRoutines`, type: `boolean` ## Method: setMaxEvaluationCount - parameter: `maxEvalcnt`, type: `int` ## Method: setMemory - parameter: `vm`, type: `com.pnfsoftware.jeb.core.units.code.asm.memory.IVirtualMemory` ## Method: setMemoryAutoAllocOnWrite - parameter: `enabled`, type: `boolean` ## Method: setMemoryBypassProtection - parameter: `bypass`, type: `boolean` ## Method: setNativeStackEnd - parameter: `nativeStackEnd`, type: `long` Description: Set the high\-address \(exclusive\) for the native stack of the current frame. parameter: nativeStackEnd: ## Method: setNativeStackStart - parameter: `nativeStackStart`, type: `long` Description: Set the low\-address for the native stack of the current frame. parameter: nativeStackStart: ## Method: setPrimaryEmulator - parameter: `primaryEmulator`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.emulator.EEmulator` ## Method: setProgramCounter - parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Convenience method to write the PC. Will throw on error. A global context must have been set. parameter: val: ## Method: setRecordBadWrites - parameter: `recordBadWrites`, type: `boolean` ## Method: setRoutineContext - parameter: `ectx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext` ## Method: setSegmentBase - parameter: `segment`, type: `int` - parameter: `base`, type: `long` Description: Set the memory address associated with a segment. parameter: segment: the value of a segment register parameter: base: the base memory address associated with the segment ## Method: setSegmentMapping - parameter: `segmentName`, type: `java.lang.String` - parameter: `segmentValue`, type: `int` - parameter: `baseAddress`, type: `long` Description: Convenience routine. ## Method: setSoftFailMode - parameter: `enabled`, type: `boolean` Description: 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)](#setBadMemory(IVirtualMemory)) for details. parameter: enabled: ## Method: setStackPointer - parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Convenience method to write the SP. Will throw on error. A global context must have been set. parameter: val: ## Method: setValue - parameter: `id`, type: `int` - parameter: `val`, type: `long` Description: Set a variable to a defined value. parameter: id: the positive id of a global context variable parameter: val: ## Method: setValue - parameter: `var`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar` - parameter: `val`, type: `long` Description: Set a variable to a defined value. parameter: var: parameter: val: ## Method: setValue - parameter: `var`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEVar` - parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Set a variable to a defined value or the BAD value. parameter: var: parameter: val: a value; null indicates the explicit BAD value ## Method: setValue - parameter: `dst`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEGeneric` - parameter: `val`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEImm` Description: Set a variable or the slice of a variable to the provided value. parameter: dst: a var or the slice of a var parameter: val: the value to be set \(which bitsize must be the same as dst's\), cannot be null ## Method: setVariables - parameter: `vars`, type: `java.util.Map` Description: Replace the variables of this state by another set of variables. parameter: vars: ## Method: setVirtualPC - parameter: `virtualPC`, type: `int` ## Method: toString - return type: `java.lang.String` ## Method: unregisterHooks - parameter: `hooks`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.ir.IEStateHooks` ## Method: writeMemory - parameter: `address`, type: `long` - parameter: `buffer`, type: `byte[]` - return type: `boolean` Description: Write memory bytes to specific \(defined\) values. parameter: address: parameter: buffer: return: ## Method: writeMemoryBad - parameter: `address`, type: `long` - parameter: `bitsize`, type: `int` - return type: `boolean` Description: Specify a range of memory bytes known to contain BAD data. parameter: address: parameter: bitsize: return: ## Method: writeMemoryBad - parameter: `address`, type: `long` - parameter: `bitsize`, type: `int` - parameter: `policy`, type: `int` - return type: `boolean` Description: Specify a range of memory bytes known to contain BAD data. parameter: address: parameter: bitsize: parameter: policy: one of `POLICY_MEMWRITE_BADHIT_xxx` return: ## Method: writeMemoryByte - parameter: `address`, type: `long` - parameter: `val`, type: `byte` - return type: `boolean` ## Method: writeMemoryInt - parameter: `address`, type: `long` - parameter: `val`, type: `int` - return type: `boolean` Description: Write a 32\-bit value to memory. Uses the VM\-provided endianness attribute for encoding. parameter: address: parameter: val: return: success indicator ## Method: writeMemoryLong - parameter: `address`, type: `long` - parameter: `val`, type: `long` - return type: `boolean` Description: Write a 64\-bit value to memory. Uses the VM\-provided endianness attribute for encoding. parameter: address: parameter: val: return: success indicator ## Method: writeMemoryPointer - parameter: `address`, type: `long` - parameter: `val`, type: `long` - return type: `boolean` Description: Write a pointer \(address\) to memory. Uses the VM\-provided endianness attribute for encoding. parameter: address: parameter: val: return: success indicator ## Method: writeMemoryShort - parameter: `address`, type: `long` - parameter: `val`, type: `short` - return type: `boolean` Description: Write a 16\-bit value to memory. Uses the VM\-provided endianness attribute for encoding. parameter: address: parameter: val: return: success indicator ## Static Method: formatVars - parameter: `vars`, type: `java.util.Map` - parameter: `gctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEGlobalContext` - parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext` - return type: `java.lang.CharSequence` ## Static Method: formatVars - parameter: `vars`, type: `java.util.Map` - parameter: `gctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IEGlobalContext` - parameter: `ctx`, type: `com.pnfsoftware.jeb.core.units.code.asm.decompiler.IERoutineContext` - parameter: `includedIds`, type: `java.util.Collection` - parameter: `excludedIds`, type: `java.util.Collection` - parameter: `skipZeroRegs`, type: `boolean` - return type: `java.lang.CharSequence`