-
-
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. |
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 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 and numeric_indirect 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 and register_indirect 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:
|
Note that this configuration dictionary is used both by the Operand Set configuration and the configuration of specific operants for a specific instruction.
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 descriptor the byte code 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. |
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.