public interface

IProcessor

com.pnfsoftware.jeb.core.units.code.asm.processor.IProcessor<InsnType extends com.pnfsoftware.jeb.core.units.code.IInstruction>
Known Indirect Subclasses

Class Overview

Definition of a simple machine code processor or microcontroller. It is recommended that implementors extend AbstractProcessor instead of implementing this interface from scratch.

The "processor mode" indicates the current operating size of the processor. (In several cases, it matches the size in bits of a general-purpose register, as well as the size of the program counter - there are exceptions to this rule though.)

Implementations may or may not support safe concurrent operation.

Summary

Constants
int MODE_128 Convenience constant.
int MODE_16 Convenience constant.
int MODE_256 Convenience constant.
int MODE_32 Convenience constant.
int MODE_64 Convenience constant.
int MODE_8 Convenience constant.
int MODE_DEFAULT Default processor mode constant (unknown or standard mode)
int MODE_INVALID Invalid processor mode, do not use
Public Methods
abstract CodePointer createEntryPoint(long address)
Create an entry-point from a provided native address.
abstract CodePointer createEntryPoint(long address, int defaultMode)
Create an entry-point from a provided native address.
abstract int getDefaultMode()
Get the default processor mode.
abstract Endianness getEndianness()
Get the endianness this processor operates in.
abstract int getGPRegisterBitsize()
Retrieve the size of a General Purpose register, in bits.
abstract int getInstructionAlignment()
Retrieve the instruction alignment, in bytes.
abstract int getMode()
Get the processor mode.
abstract int getPCRegisterBitsize()
Retrieve the size of the Program Counter register, in bits.
abstract IRegisterBank getRegisterBank()
abstract String getRegisterName(long registerCode)
Retrieve the string name of a register by its internal register code.
abstract ICodeResolver<InsnType> getResolver()
Retrieve a code resolver.
abstract Collection<Integer> getSupportedModes()
Get the list of valid modes that this processor supports.
abstract Collection<ProcessorVariant> getSupportedVariants()
Retrieve a list of supported processor variants.
abstract ProcessorType getType()
Retrieve the processor type.
abstract ProcessorVariant getVariant()
Get the processor variant used by this object.
abstract boolean isRISC()
Provide a hint about the instruction set architecture.
abstract InsnType parseAt(byte[] bytes, int index, int end)
Parse a single instruction.
abstract InsnType parseAt(IVirtualMemory vm, long address)
Parse a single instruction at the specified address in memory.
abstract InsnType parseWithContext(IMachineContext context)
Parse a single instruction given a machine context.
abstract void setEndianness(Endianness endianness)
Set the endianness of this processor.
abstract void setInstructionAlignment(int align)
Set the instruction alignment, in bytes.
abstract int setMode(int newMode)
Set the processor mode.
abstract void setVariant(ProcessorVariant variant)
Set the new variant used by this processor.

Constants

public static final int MODE_128

Convenience constant. Processor mode constant for 128-bit processors

Constant Value: 128 (0x00000080)

public static final int MODE_16

Convenience constant. Processor mode constant for 16-bit processors

Constant Value: 16 (0x00000010)

public static final int MODE_256

Convenience constant. Processor mode constant for 256-bit processors

Constant Value: 256 (0x00000100)

public static final int MODE_32

Convenience constant. Processor mode constant for 32-bit processors

Constant Value: 32 (0x00000020)

public static final int MODE_64

Convenience constant. Processor mode constant for 64-bit processors

Constant Value: 64 (0x00000040)

public static final int MODE_8

Convenience constant. Processor mode constant for 8-bit processors

Constant Value: 8 (0x00000008)

public static final int MODE_DEFAULT

Default processor mode constant (unknown or standard mode)

Constant Value: 0 (0x00000000)

public static final int MODE_INVALID

Invalid processor mode, do not use

Constant Value: -1 (0xffffffff)

Public Methods

public abstract CodePointer createEntryPoint (long address)

Create an entry-point from a provided native address.

Parameters
address address of the instruction
Returns
  • the entry point (careful! may contain an address different -adjusted- than the input parameter)

public abstract CodePointer createEntryPoint (long address, int defaultMode)

Create an entry-point from a provided native address.

Parameters
address address of the instruction
defaultMode default processor mode if it cannot be determined by address
Returns
  • the entry point (careful! may contain an address different -adjusted- than the input parameter)

public abstract int getDefaultMode ()

Get the default processor mode. The mode indicates the current operating size of the processor. Typically, this represents the size in bits of general purpose (GP) registers, as well as the size of the program counter (PC).

Returns

public abstract Endianness getEndianness ()

Get the endianness this processor operates in.

public abstract int getGPRegisterBitsize ()

Retrieve the size of a General Purpose register, in bits.

public abstract int getInstructionAlignment ()

Retrieve the instruction alignment, in bytes.

Returns
  • the instruction alignment, eg, 1, 2, 4, 8, etc.

public abstract int getMode ()

Get the processor mode. Typically, the processor mode is a size in bits that indicates how instructions are parsed and/or the size of general-purpose registers used for arithmetic operations and/or how memory slots are addressed are accessed. Typical processor modes are 8-, 16-, 32- or 64- bits). Note: A 'processor mode' could have a different semantic, but anything non-standard is unlikely to be understood by client code. This function will never return 0 See MODE_Xxx for common constants.

Returns

public abstract int getPCRegisterBitsize ()

Retrieve the size of the Program Counter register, in bits.

public abstract IRegisterBank getRegisterBank ()

public abstract String getRegisterName (long registerCode)

Retrieve the string name of a register by its internal register code.

Parameters
registerCode register code used by this processor object as well as generated instruction and operand objects. Not to be confused with standardized register indices defined in register bank objects
Returns
  • a name or null (on error or if the implementation is not provided)

public abstract ICodeResolver<InsnType> getResolver ()

Retrieve a code resolver. A resolver is optional; implementors may decide to not provide one, and return null.

Returns
  • a resolver

public abstract Collection<Integer> getSupportedModes ()

Get the list of valid modes that this processor supports.

public abstract Collection<ProcessorVariant> getSupportedVariants ()

Retrieve a list of supported processor variants.

public abstract ProcessorType getType ()

Retrieve the processor type. The type depends on the current execution mode. A processor class may implement several modes, mapping to various processor types.

public abstract ProcessorVariant getVariant ()

Get the processor variant used by this object.

public abstract boolean isRISC ()

Provide a hint about the instruction set architecture.

public abstract InsnType parseAt (byte[] bytes, int index, int end)

Parse a single instruction.

Parameters
bytes input code buffer
index where to parse in the input buffer
end exclusive end offset in the buffer: if parsing at the given index offset requires bytes past the end offset, an exception is raised
Returns
  • the instruction, never null - on parsing error, an exception is raised
Throws
ProcessorException on parsing error
RuntimeException on miscellaneous error

public abstract InsnType parseAt (IVirtualMemory vm, long address)

Parse a single instruction at the specified address in memory.

Parameters
vm the input virtual memory
address the address to read at, with permission of read+write
Returns
  • the instruction, never null. On parsing error, an exception is raised
Throws
ProcessorException on parsing error
RuntimeException on miscellaneous error

public abstract InsnType parseWithContext (IMachineContext context)

Parse a single instruction given a machine context. The context provides access to at least:

  • memory data
  • a register bank, including the program counter
When using this method, other settings determined by this interface, such as the processor mode or endianness, can be disregarded: the context has higher priority. However, an implementor is allowed to raise a processor exception if mismatches are detected (typically, the endianness).@return

public abstract void setEndianness (Endianness endianness)

Set the endianness of this processor.

public abstract void setInstructionAlignment (int align)

Set the instruction alignment, in bytes. The implementation may decide to enforce alignment, or ignore it. If alignment is enforced, attempting to parse an unaligned instruction should raise a ProcessorException.

Parameters
align the alignment, must be a strictly positive power of 2

public abstract int setMode (int newMode)

Set the processor mode. Implementors may override this class, if they have other/better/proper ways to determine the processor operating mode. In that case, the mode provided by this method may be regarded as a hint - or disregarded entirely.

Parameters
newMode the mode, the value MODE_DEFAULT (0) can be provided to revert to the default processor mode
Returns
  • the previous processor mode
Throws
ProcessorException if the mode is not supported

public abstract void setVariant (ProcessorVariant variant)

Set the new variant used by this processor.

Throws
ProcessorException if the variant is not supported