-
-
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 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 . |
The argument_config
section allows you to configure any number of argument types that can be used as arguments in instructions. What gets defined here is how an argument gets converted into byte code. This section is a key/value dictionary where the keys are the arbitrary name of the argument type and the value is another dictionary that defines the argument type's configuration. The options that may be used to define an argument types configuration are:
Option Key | Value Type | Description |
---|---|---|
type |
string | Specifies one of the argument types supported by BespokeASM. See table below for the enumeration of supported argument types. |
byte_align |
boolean | Specifies whether the bits of this argument should be packed immediately following the bits of this instruction's previous part (typically, the instruction code itself), or whether this arguments bits should start at the next byte boundary. |
bit_size |
integer | The number of bits that should be emitted for this argument. If the value generated for this argument is larger than the specified bit size allows, the value to be masked to the least significant bits. |
endian |
string |
(Optional) Defines of the endianness of multibyte values for this argument. Allowed values are big and little . If not present, this option defaults to the general endianness setting from the general section of the configuration file. |
The supported types of arguments are:
Argument Type | Description |
---|---|
numeric |
Any value that can be directly resolved to a constant number value at compile time. Can be an actual number value, a label, or constant. |
expression |
Any mathematical expression that can be resolved to a constant number value at compile time. Can be composed of on or more numeric type values and the operators + , - , * , and \ . Parenthesis ( and ) can be used to set the precedence order of operations. |
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 |
---|---|---|
arguments |
list |
(Optional) An ordered list of argument_config keys that represent arguments that the mnemonic supports. If not present, the instruction is assumed to have no arguments, which can also be represented by an empty list. |
byte_code |
dictionary | A dictionary that descriptor the byte code that should be emitted to indicate the instruction. The values that must be present in this dictionary are defined below |
The dictionary entries that must be present to configure the byte_code
dictionary of the instruction configuration are:
Key | Value Type | Description |
---|---|---|
value |
integer | The value of the instruction byte code |
size |
integer | The number of bits that should be used to represent the value. If the value is larger than what is permitted by the number of bits, then the value emitted is masked to the lest significant bits. |
BespokeASM will generate the byte code for any given instruction using the following steps:
- For a new instruction, start at the next whole byte.
- Emit the instruction byte code bits as configured in the
instructions
section - Emit the argument byte code bits in order of each argument as configured for each argument type
Currently there is no way to alter the this order of byte code generation.
The following example instruction set configuration is for Ben Eater's SAP-1 Breadboard CPU.
general:
address_size: 4
endian: big
argument_config:
integer:
type: numeric
byte_align: false
bit_size: 4
address:
type: numeric
byte_align: false
bit_size: 4
instructions:
nop:
byte_code:
value: 0
size: 4
lda:
arguments:
- address
byte_code:
value: 1
size: 4
add:
arguments:
- address
byte_code:
value: 2
size: 4
sub:
arguments:
- address
byte_code:
value: 3
size: 4
sta:
arguments:
- address
byte_code:
value: 4
size: 4
ldi:
arguments:
- integer
byte_code:
value: 5
size: 4
jmp:
arguments:
- address
byte_code:
value: 6
size: 4
jc:
arguments:
- address
byte_code:
value: 7
size: 4
jz:
arguments:
- address
byte_code:
value: 8
size: 4
out:
byte_code:
value: 14
size: 4
hlt:
byte_code:
value: 15
size: 4