The instruction set configuration file defines the instruction set and assembly language features used by BespokeASM to assemble machine code. This file can be written in either JSON or YAML format.

The purpose of this configuration file is to control how machine code is generated for a given instruction set. BespokeASM uses a fixed method for compiling machine code for any instruction. The standard form of an instruction is:

  MNEMONIC [OPERAND1[, OPERAND2[, ...]]]

Each instruction must have at least a mnemonic, and can optionally have one or more operands.

The machine code generated for an instruction consists of two parts: the instruction byte code and the argument values.

• Instruction Byte code: Indicates which instruction the CPU should execute. It is composed of values specific to the mnemonic and, optionally, each operand. The total size of the packed byte code (mnemonic plus operands) should match the instruction size of the target hardware.
• Argument values: These are parameters used by the instruction's microcode, such as immediate values or addresses. If multiple operands provide argument values, they are ordered according to the operand order in the instruction.

Both the instruction mnemonic and its operands can contribute to the byte code, but only operands can generate argument values.

For example, consider this assembly instruction:

  mov a,[$8000]      ; copy value at address $8000 into register A

In this case:

• The instgruction mnemonic mov, the operand a (the register A), and the operand [...] (an indirect value) each contribute to the instruction's overall byte code.
• The numeric value $8000 is the argument for the [...] operand and is placed after the instruction byte code in the final machine code.

The diagram below illustrates this. Here the machine code is for computer with an 8-bit data word using little-endian byte order:

    Byte 0    Byte 1   Byte 2
  ========== ======== ========
  01 001 110 00000000 10000000
  -- --- --- -----------------
   |  |   |          |
   |  |   |          +-- The second operand's argument value ($8000) in little-endian byte order
   |  |   +------------- The byte code 110 for the second operand ([...])
   |  +----------------- The byte code 001 for the first operand (register A)
   +-------------------- The byte code 01 for the mov mnemonic

In summary, two types of machine code are generated for each instruction:

• Instruction Byte code: Specifies the instruction to execute (often used to select a microcode sequence).
• Argument values: Data that the instruction operates on (e.g., the address for a jump instruction).

Throughout this documentation, "instruction byte code" and "argument value" are used as defined above. In BespokeASM, argument values are always emitted after the instruction's byte code. Operands can affect both the byte code and the argument values.

In BespokeASM, a "word" is a unit of data whose size matches the native data bit size of the target CPU. A word is what a memory address points to. For example:

• An "8-bit computer" has an 8-bit word size (1 byte).
• A 32-bit CPU has a 32-bit word size (4 bytes).

Bytecode is represented as a sequence of words, and each word is addressable. For a 32-bit CPU, address 0 points to the first 4-byte word, address 1 to the next, and so on.

The word size of the target CPU is a fundamental configuration in BespokeASM. It is set in the general section of the configuration file. The default word size is 8 bits, but this can be changed as needed.

A word segment is a subdivision of a word, representing the physical ordering of bits within that word. For example, a 16-bit computer might store its 16-bit words so that the first 8 bits are the least significant (little-endian segment order), and the last 8 bits are the most significant. This is distinct from the endianness of multi-word values (e.g., a 32-bit value on an 8-bit CPU). Word segments are rarely used in most CPUs, but may be needed for special cases, such as the bit layout of an EPROM.

In most cases, the word segment size equals the word size. However, if a word needs to be subdivided and reordered, the segment size can be smaller. The segment size must be less than or equal to the word size, and the word size must be evenly divisible by the segment size.

The word segment size is set in the general section of the configuration file. By default, it matches the word size. This feature is rarely needed, so the default is usually sufficient.

BespokeASM supports two concepts of endianness:

1. The order of words within a multi-word value (multi-word endianness)
2. The order of word segments within a word (intra-word endianness)

Multi-Word Endianness refers to the order of words in memory that together represent a multi-word value. For example, a 32-bit value 0x12345678 on an 8-bit CPU could be stored as:

  Address 0: 0x12
  Address 1: 0x34
  Address 2: 0x56
  Address 3: 0x78

(big-endian: most significant byte at the lowest address)

Or:

  Address 0: 0x78
  Address 1: 0x56
  Address 2: 0x34
  Address 3: 0x12

(little-endian: least significant byte at the lowest address)

If the CPU has 16-bit words, the same 32-bit value in little-endian would be:

  Address 0: 0x5678
  Address 1: 0x1234

Multi-word endianness is set in the general section of the configuration file. The default is big.

Intra-Word Endianness refers to the order of segments within a word. For example, a 16-bit word with 4-bit segments and a value of 0x1234:

• Big-endian: 0x1234 (most significant segment first)
• Little-endian: 0x3412 (least significant segment first)

The address and value of the word remain the same; only the order of segments within the word changes. Intra-word endianness is useful for matching the physical layout required by certain memory devices.

Intra-word endianness is set in the general section of the configuration file. The default is big. This feature is rarely needed, so the default is usually sufficient.

When string_byte_packing is enabled in the general section, quoted strings in .byte and .cstr data directives are packed tightly into words, rather than each character being placed in its own word. This feature is only available if word_size is a multiple of 8 and at least 16. If not set, the default behavior is to place each character in its own word.

For example, with word_size: 16 and string_byte_packing: true, the directive:

.cstr "Hello World"

will produce the following 16-bit words (big-endian):

0x4865, 0x6c6c, 0x6f20, 0x576f, 0x726c, 0x6400

If the string does not fill the last word, the value of string_byte_packing_fill (default 0) is used to pad the remaining bytes. For example, with word_size: 32, string_byte_packing: true, and string_byte_packing_fill: 0xFF:

.byte "Hello World"

will produce:

0x48656c6c, 0x6f20576f, 0x726c64FF

For .cstr, the configured cstr_terminator value is always appended to the string before packing and padding. If the terminator does not fill the last word, the remaining bytes are padded with string_byte_packing_fill.

For example, with word_size: 32, string_byte_packing: true, string_byte_packing_fill: 0xFF, and cstr_terminator: 0xAA:

.cstr "Hello World!"

will produce:

0x48656c6c, 0x6f20576f, 0x726c6421, 0xAAFFFFFF

If string_byte_packing is not enabled, the default behavior is to emit each character (and the terminator for .cstr) in its own word, regardless of string_byte_packing_fill.

The configuration has the following main sections:

The general section defines the general configuration of BespokeASM and various assembly language features. The general section is required. The supported options are:

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.

Compiler constants for numerical values can be defined for use in the instruction set. This subsection, identified by the constants key, contains a list of dictionaries with these keys:

Predefined data blocks can be used to reserve sections of memory for hardware features or 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. These are defined under the data key as a list of dictionaries:

A predefined memory zone can be defined in the predefined section under memory_zones, as a list of dictionaries:

The GLOBAL memory zone may be defined here by using the GLOBAL name. If defined, the origin value in the general settings is interpreted as an offset from the GLOBAL zone's start address. If not defined, a default GLOBAL zone is created.

Memory zones are where bytecode for code and data is assembled, while a data block is a preallocated block of bytecode.

Preprocessor macro symbols can be predefined in the predefined section under symbols, as a list of dictionaries:

The operand_sets section defines sets of operands for instructions. An operand set represents all possible operand values for a specific operand position and defines the byte code and argument values to be packed when forming machine code. Operand sets are defined separately from instructions to allow reuse. Each operand set consists of one 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 specifies the assembly behavior of a specific operand value. The key is the internal name of the operand value, and the value is a collection of configuration items:

Note: This configuration dictionary is used both by Operand Set configuration and by specific operands in other sections.

The instructions section defines supported instruction mnemonics. Each instruction definition consists of 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 strings and the values are dictionaries defining the instruction's arguments and byte code.

You can define alternative mnemonics (aliases) for an instruction using the aliases field in the instruction's configuration. Aliases are treated as first-class mnemonics: they are accepted in assembly source, generate the same code as the root mnemonic, and are included in language extension syntax highlighting. All aliases must be globally unique across all mnemonics and aliases in the configuration.

• The aliases field is a list of one or more alternative names for the instruction mnemonic.
• If aliases is not present, the instruction has no aliases.
• Aliases are not supported for macros (only for native instructions).

Example:

instructions:
  jsr:
    aliases: [call, jump_to_subroutine]
    bytecode:
      value: 42
      size: 8
  nop:
    bytecode:
      value: 0
      size: 8

In this example, jsr, call, and jump_to_subroutine are all valid mnemonics for the same instruction. Any of these can be used in assembly code, and they will generate the same machine code.

The operands configuration for an instruction requires at least one of operand_sets or specific_operands, or both.

Instruction macros are a way to make configurable sequences of instructions and then just just use a single instruction (macro) to insert that instruction sequence into the byte code. For example, if the ISA of the computer only has a single byte move instruction named mov, a two byte move instruction (macro) named mov2 can be constructed from the following sequence of instructions:

     mov [addr1],[addr2]
     mov [addr1+1],[addr2+1]

Then, the macro instruction mov2 [addr1],[addr2] can be defined such that it expands to this sequence.

BespokeASM enables the ability for instruction macros to be defined in the ISA configuration file. Once defined, the macro mnemonic can be used in the assembly code identically to native instruction mnemonics, with the only noticeable difference being that instruction macros generate more byte code than native instructions. What BespokeASM does here is essentially run a pre-assembler that expand a macro instruction into desired set of replacement instruction lines through a string parsing and replacement process. Then the constructed instruction lines are assembled with all the other instruction lines from the assembly code to generate the machine code.

Macros are defined in the macros section of the configuration file. The section is structured similar to the instructions section in that the section is a dictionary where the keys are the mnemonic of the macro and the value is a list of distinct configurations for that macro. A macro configuration list is a list of dictionaries. Each dictionary has two elements, operands and instructions.

The operands section is configured the same as the operands section for instructions is configured, however it is worth noting that since no byte code is emitted directly from a macro, any configuration provided for a macro's operand's byte code is ignored. The goal of the operand section for a macro is simply to define what the allowed types of operands are for a specific macro configurations.

The instructions section of a macro definition lists in order the instruction templates that will be used to compile the instruction sequence that the macro will be expanded into. Each instruction is written as is to be assembled, the macro mechanism essentially replaces the macro instruction in the assembly code with the assembly code listed in instructions. However, before doing so, certain tokens that may be present in the instruction section get replaced with finalized values. The tokens are of the form @YYY(x), where YYY is the token label, and x is an integer indicating what macro operand will be the source of its value. The first macro operand is represent by x being zero to 0, the second is 1, and so on. The following macro tokens are supported:

• @OP(x) - Generates a value based on the whole string of the x macro operand.
• @ARG(x) - Generates a value based on the argument numeric expression of the x macro operand
• @REG(x) - Generates a value based on the register label used in the x macro operand.

The specific value emitted by each macro token depends on the operand type that the x macro operand is configured to be in the operands section of this macro configuration. The following table lists what each macro token will generate for all supported operand types.

See the table in the original documentation for details on what each token emits for each operand type.

To illustrate how to configure an macro, the the following is a nominal configuration for the mov2 example discussed above:

macros:
  mov2:
    - operands:
        count: 2
        specific_operands:
          indirect_indirect:
            list:
              iaddr1:
                type: indirect_numeric
                argument:
                  size: 16
                  byte_align: true
              iaddr2:
                type: indirect_numeric
                argument:
                  size: 16
                  byte_align: true
      instructions:
        - "mov [@ARG(0)],[@ARG(1)]"
        - "mov [@ARG(0)+1],[@ARG(1)+1]"

• Macros cannot define labels or constants, nor use directives. However, they can use predefined labels and constants in expressions.
• The instructions listed in the instruction section of a given instance of a macro definition are tightly coupled to the operands types configured for the macro in the operands section. If the instructions do not match what the macro operands would provide, then errors would be generated during assembly. While operand_sets can be used to configure a macro's operands, care should be taken to ensure all operands listed in the operand set are consistent with each other in terms of how the macro instructions will use it. If operands are inconsistent, a different configuration for the macro should be created in the list of configurations for a given macro.

Example configuration files can be found in the examples directory of the BespokeASM repository.