Instruction Set Configuration File

Description

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:

general

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.

argument_config

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 resolved to a constant number value at compile time. Can be an actual number value, a label, or constant.

instructions

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.

Byte Code Generation

BespokeASM will generate the byte code for any given instruction using the following steps:

1. For a new instruction, start at the next whole byte.
2. Emit the instruction byte code bits as configured in the instructions section
3. 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.

Example

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