-
-
Notifications
You must be signed in to change notification settings - Fork 5
Instruction Set Configuration File
The instruction set configuration file enables you to define the instruction set and assembly language features that will be used by BespokeASM to assemble byte code. This configuration file can be made using JSON or YAML.
The purpose of this configuration file is to control how machine code should be compiled for the instruction set. BespokeASM has a fix method for compiling machine for for any given instruction. The standard form or an instruction is:
MNEMONIC [OPERAND1[, OPERAND2[, ...]]]
Here, each instruction must be composed of at least a mnemonic, and can optionally have 1 or more operands.
The machine code generated for an instruction is composed of first byte code, then argument values. The byte code represents the value that will be used by a CPU's instruction register to indicate what instruction the CPU is executing. The byte code is composed of values specific to the mnemonic and optionally for each operand. The size of the packed byte code for a mnemonic and its operands should be the same as the instruction size of the hardware running this machine cod. The argument values are used by the that instruction as parameters. If more than one operand has an argument value to be placed in the machine code, then the argument values will be ordered in the same order as the operands. The instruction mnemonic and each of the operands can generate values to be packed into the byte code of an instruction, while only operands can generate argument values in byte code.
As an illustrative example, consider this assembly instruction:
mov a,[$8000] ; copy value at address $8000 into register A
In this case, the mnemonic mov
and the operands a
(for register A
) and [...]
(for an indirect value) all generate values that will be used to form the instruction's to form the instruction's byte code. The $8000
numeric value is the argument to the [...]
operand and follows the instruction byte code when forming the total machine code. The diagram below illustrated this.
Byte 0 Byte 1 Byte 2
========== ======== ========
01 001 110 00000000 10000000
-- --- --- -----------------
| | | |
| | | +- The second operand's argument value of $8000 in little endian format
| | +------------ The byte code 110 indicating the second operand ([...])
| +---------------- The byte code 001 indicating the first operand (register A)
+------------------- The byte code 01 indicating the mov mnemonic
The configuration has the following main sections:
The general
section defines the general configuration of BespokeASM and various assembly language features. The supported options are:
Option Key | Value Type | Description |
---|---|---|
address_size |
integer | The number of bits that is required to represent a memory address. |
endian |
string |
(Optional) Defines of the endianness of multibyte values. Allowed values are big and little . If not present, this option defaults to big . |
registers |
list[string] | (Optional) A list of register labels that will be used in this instruction set. Anything that is declared as a register label cannot be used as a constant or address label, and anything not declared as a register label cannot be used an a register operand. If not present, no register labels are defined. |
min_version |
string | (Optional) The minimum version of BespokeASM that this instruction set configuration file will work with. If provided, BespokeASM will also do a counter-minimum version check to make sure this instruction set configuration file has the schema it is expecting. |
identifier |
dictionary |
(Optional) Configures name and version information for the assembly language defined by this configuration file. This field is used both by language extension generation and source code language requirements. Contains the following key/value items:
|
origin |
integer |
(Optional) Defines the starting origin address for byte code generated with this configuration file. The starting origin defaults to an address of 0 if this option is not present. This setting can be overridden in code with the .org directive. |
Both compiler constants and memory blocks can be defined in the ISA configuration file, and the labels defined with these entities can be used in code compiled with the ISA configuration file. This section is identified with the predefined
key and contains a dictionary with the following key/values.
Define compiler constants for numerical values that are often used for the instruction set the configuration file pertains to.
This subsection of predefined
is identified with the constants
key, and contains a list of dictionaries with the following keys/values:
Option Key | Value Type | Description |
---|---|---|
name |
string | The label string that this constant value will be assigned to. This case sensitive label string then can be used at compile time to reference the assigned integer value. |
value |
integer | The integer value that will be assigned to this constant. |
Memory blocks can be predefined. These can be used to represent sections in memory that pertain to certain hardware features of the system that the instruction set pertains to, or can be used to reserve sections of memory for common uses, such as buffers. BespokeASM will generate an error if the addresses of compiled code or data should ever overlap with predefined memory blocks.
This subsection of predefined
is identified with the memory
key, and contains a list of dictionaries with the following keys/values:
Option Key | Value Type | Description |
---|---|---|
name |
string | The label string that the first address value in this memory block will be assigned to. This case sensitive label string them can be used at compile time to reference the assigned address value. |
address |
integer | The start address of the memory block |
size |
integer | The number of bytes associated with this memory block. Should be at least 1. |
value |
integer |
(Optional) The byte value this memory block will be filled with when the BespokeASM generates a binary image for compiled code. If not present, the default value of 0 is used. |
The operand_sets
section allows you to define sets of operands for instructions. A operand set is intend to represent all of the possible operand values for a specific operand position, and defines the byte code and argument values that will be packed when forming the instructions machine code. Operand sets are defined separate from the instruction as to enable an operand set being used by more than one instruction. An operand set consists of 1 or more distinct operands.
The operand_set section is a dictionary, where the dictionary key is the name for the operand set, and the value is the configuration of that operand set. The name of the operand set is only use internally within this configuration file and does not directly impact the assembly language that is derived from this configuration file.
Each item listed in the operand_sets
consists of a single element titled operand_values
, which contains a dictionary that configures each of the operand variants in this operand set.
The operand configuration dictionary is used to specify the assembly behavior of a specific operand value. In this dictionary, the key is the internal name of the operand value item used within this configuration file, and the value is a collection of operand configuration items defined in the table below:
Option Key | Value Type | Description |
---|---|---|
type |
string | Specifies one of the operand types and operand addressing modes supported by BespokeASM. The allowed values are:
|
bytecode |
dictionary |
(Optional) A dictionary that configures the byte code associated with this operand. If not present this operand will not generate any byte code. This dictionary contains the following keys:
|
argument |
dictionary | Configures how the operand argument will be emitted into the machine code. Must be present for the numeric , numeric_indirect , enumeration , and numeric_enumeration operand types. Ignored for all other types.The dictionary contains the following keys:
|
register |
string | The assembly code representation of the register value to be used for this operand. Must be one of the register values listed in the registers list of the general section. Must be present for the register , register_indirect , and indirect_indexed_register operand types, ignore for all other operand types. |
offset |
dictionary | Configures the offset value that is optional for the register_indirect operand type. Ignored for all other types. If not present, then no offset is enabled, and no argument value will be emitted in the machine code. If offset values are enabled, this operand will generate an argument value in the machine code equal to the offset value specified in the assembly code. The compiler will still permit not specifying an offset for a register_indirect instruction configured to enabled offsets. In this case, the offset of zero is implied and will be emitted as the argument value.The dictionary contains the following keys:
|
index_operands |
dictionary | Configures the allowed offset operands for the indirect_indexed_register operand type. Contains a dictionary, where the key is an internal name for each offset operand option, and the value is an operand configuration formatted the same as described in this table. When compiling, BespokeASM will attempt to match one operand listed in index_operands . Note that the byte code of the matched index operand will be appended to this operand's configured byte code to form the overall byte code for this operand. If the matched index operand generates an argument, that will be appended to this operand's arguments, if any. |
Note that this configuration dictionary is used both by the Operand Set configuration and the configuration of specific operands in various aspects of the configuration file.
The instructions
section is where the supported instruction mnemonics are defined. An instruction definition is comprised or three parts: the mnemonic, the instruction arguments, and the instruction byte code. This section is a key/value dictionary where the keys are the mnemonic string name of the instruction and the value is another dictionary that defines the instructions arguments configuration and byte code.
Option Key | Value Type | Description |
---|---|---|
byte_code |
dictionary | A dictionary that describes the base byte code for this instruction that should be emitted to indicate the instruction. The key and values that must be present are:
|
operands |
dictionary | A dictionary that configures the set of operands that are allowed for this instruction mnemonic. The key and values that are used in this dictionary are described in the table below. If not present, then the instruction mnemonic is assumed to have no operands. |
variants |
list |
(Optional) This options allows the specification of one or more alternative configurations for the mnemonic. This is useful when a different instruction byte code prefix should be emitted for a certain operand signature. The value of this key is a list, and each list element is another instruction configuration with byte_code and operands as specified above. Variant configurations are processed if the operands do not match the main configurations, and then each variant configuration is processed in order present in the list, using the first match found to generate the byte code. |
The operands
configuration of a specific instruction requires at least one of the operand_sets
or the specific_operands
configuration, and can also have both.
Option Key | Value Type | Description |
---|---|---|
count |
integer | The number of operands this mnemonic must have. |
operand_sets |
dictionary |
(Optional) Present if operand sets are used to configure the operands of the mnemonic. Contains the following keys and values:
|
specific_operands |
dictionary |
(Optional) A dictionary of specific operand combination configurations that are allowed when assembling this instruction. Takes precedence over the operand combinations allowed in the operand_sets configuration for this instruction when both configure the same operand combination. The keys of this dictionary are arbitrary strings used internally to identify a specific operand configuration, and the values are the keys' operand configuration. Each operand configuration is a dictionary that contains the following keys and values:
|
Example configuration files can be found in the examples
directory of the BespokeASM repository.