Interface IProcessor<InsnType extends IInstruction>

Type Parameters:
InsnType -
All Known Implementing Classes:
AbstractProcessor

@Ser public interface IProcessor<InsnType extends IInstruction>
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.

See Also:
  • Field Details

    • MODE_INVALID

      static final int MODE_INVALID
      Invalid processor mode, do not use
      See Also:
    • MODE_DEFAULT

      static final int MODE_DEFAULT
      Default processor mode constant (unknown or standard mode)
      See Also:
    • MODE_8

      static final int MODE_8
      Convenience constant. Processor mode constant for 8-bit processors
      See Also:
    • MODE_16

      static final int MODE_16
      Convenience constant. Processor mode constant for 16-bit processors
      See Also:
    • MODE_32

      static final int MODE_32
      Convenience constant. Processor mode constant for 32-bit processors
      See Also:
    • MODE_64

      static final int MODE_64
      Convenience constant. Processor mode constant for 64-bit processors
      See Also:
    • MODE_128

      static final int MODE_128
      Convenience constant. Processor mode constant for 128-bit processors
      See Also:
    • MODE_256

      static final int MODE_256
      Convenience constant. Processor mode constant for 256-bit processors
      See Also:
  • Method Details

    • parseAt

      InsnType parseAt(byte[] bytes, int index, int end) throws ProcessorException
      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
    • parseAt

      InsnType parseAt(IVirtualMemory vm, long address) throws ProcessorException
      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
    • parseWithContext

      InsnType parseWithContext(IMachineContext context) throws ProcessorException
      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).
      Parameters:
      context -
      Returns:
      Throws:
      ProcessorException
    • getType

      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.
      Returns:
    • getRegisterBank

      IRegisterBank getRegisterBank()
      Returns:
    • isRISC

      boolean isRISC()
      Provide a hint about the instruction set architecture.
      Returns:
    • getSupportedVariants

      Collection<ProcessorVariant> getSupportedVariants()
      Retrieve a list of supported processor variants.
      Returns:
    • getVariant

      ProcessorVariant getVariant()
      Get the processor variant used by this object.
      Returns:
    • setVariant

      void setVariant(ProcessorVariant variant) throws ProcessorException
      Set the new variant used by this processor.
      Parameters:
      variant -
      Throws:
      ProcessorException - if the variant is not supported
    • getDefaultMode

      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:
      the default processor mode, never MODE_DEFAULT (0)
    • getPCRegisterBitsize

      int getPCRegisterBitsize()
      Retrieve the size of the Program Counter register, in bits.
      Returns:
    • getGPRegisterBitsize

      int getGPRegisterBitsize()
      Retrieve the size of a General Purpose register, in bits.
      Returns:
    • getSupportedModes

      Collection<Integer> getSupportedModes()
      Get the list of valid modes that this processor supports.
      Returns:
    • getMode

      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:
      the processor mode, never MODE_DEFAULT (0)
    • setMode

      int setMode(int newMode) throws ProcessorException
      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
    • getEndianness

      Endianness getEndianness()
      Get the endianness this processor operates in.
      Returns:
    • setEndianness

      void setEndianness(Endianness endianness)
      Set the endianness of this processor.
      Parameters:
      endianness -
    • getInstructionAlignment

      int getInstructionAlignment()
      Retrieve the instruction alignment, in bytes.
      Returns:
      the instruction alignment, eg, 1, 2, 4, 8, etc.
    • setInstructionAlignment

      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
    • getRegisterName

      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)
    • getResolver

      ICodeResolver<InsnType> getResolver()
      Retrieve a code resolver. A resolver is optional; implementors may decide to not provide one, and return null.
      Returns:
      a resolver
    • createEntryPoint

      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)
    • createEntryPoint

      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)