Interface IProcessor<InsnType extends IInstruction>
- Type Parameters:
InsnType
-
- All Known Implementing Classes:
AbstractProcessor
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 Summary
FieldsModifier and TypeFieldDescriptionstatic final int
Convenience constant.static final int
Convenience constant.static final int
Convenience constant.static final int
Convenience constant.static final int
Convenience constant.static final int
Convenience constant.static final int
Default processor mode constant (unknown or standard mode)static final int
Invalid processor mode, do not use -
Method Summary
Modifier and TypeMethodDescriptioncreateEntryPoint
(long address) Create an entry-point from a provided native address.createEntryPoint
(long address, int defaultMode) Create an entry-point from a provided native address.int
Get the default processor mode.Get the endianness this processor operates in.int
Retrieve the size of a General Purpose register, in bits.int
Retrieve the instruction alignment, in bytes.int
getMode()
Get the processor mode.int
Retrieve the size of the Program Counter register, in bits.getRegisterName
(long registerCode) Retrieve the string name of a register by its internal register code.Retrieve a code resolver.Get the list of valid modes that this processor supports.Retrieve a list of supported processor variants.getType()
Retrieve the processor type.Get the processor variant used by this object.boolean
isRISC()
Provide a hint about the instruction set architecture.parseAt
(byte[] bytes, int index, int end) Parse a single instruction.parseAt
(IVirtualMemory vm, long address) Parse a single instruction at the specified address in memory.parseWithContext
(IMachineContext context) Parse a single instruction given a machine context.void
setEndianness
(Endianness endianness) Set the endianness of this processor.void
setInstructionAlignment
(int align) Set the instruction alignment, in bytes.int
setMode
(int newMode) Set the processor mode.void
setVariant
(ProcessorVariant variant) Set the new variant used by this processor.
-
Field Details
-
MODE_INVALID
static final int MODE_INVALIDInvalid processor mode, do not use- See Also:
-
MODE_DEFAULT
static final int MODE_DEFAULTDefault processor mode constant (unknown or standard mode)- See Also:
-
MODE_8
static final int MODE_8Convenience constant. Processor mode constant for 8-bit processors- See Also:
-
MODE_16
static final int MODE_16Convenience constant. Processor mode constant for 16-bit processors- See Also:
-
MODE_32
static final int MODE_32Convenience constant. Processor mode constant for 32-bit processors- See Also:
-
MODE_64
static final int MODE_64Convenience constant. Processor mode constant for 64-bit processors- See Also:
-
MODE_128
static final int MODE_128Convenience constant. Processor mode constant for 128-bit processors- See Also:
-
MODE_256
static final int MODE_256Convenience constant. Processor mode constant for 256-bit processors- See Also:
-
-
Method Details
-
parseAt
Parse a single instruction.- Parameters:
bytes
- input code bufferindex
- where to parse in the input bufferend
- 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 errorRuntimeException
- on miscellaneous error
-
parseAt
Parse a single instruction at the specified address in memory.- Parameters:
vm
- the input virtual memoryaddress
- the address to read at, with permission ofread+write
- Returns:
- the instruction, never null. On parsing error, an exception is raised
- Throws:
ProcessorException
- on parsing errorRuntimeException
- on miscellaneous error
-
parseWithContext
Parse a single instruction given a machine context. The context provides access to at least:- memory data
- a register bank, including the program counter
- Parameters:
context
-- Returns:
- Throws:
ProcessorException
-
getType
ProcessorType getType()Retrieve the processor type. The type depends on the currentexecution 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
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 SeeMODE_Xxx
for common constants.- Returns:
- the processor mode, never
MODE_DEFAULT
(0)
-
setMode
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 valueMODE_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
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 aProcessorException
.- Parameters:
align
- the alignment, must be a strictly positive power of 2
-
getRegisterName
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 inregister 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
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
Create an entry-point from a provided native address.- Parameters:
address
- address of the instructiondefaultMode
- 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)
-