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.

Machine Code Compilation

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 

Configuration Sections

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.
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: name - The name of the assembly language. Should not contain spaces, but hyphens and underscores are OK. version - The version of the assembly language. Should be expressed as a semantic version, e.g. "0.1.3". extension - (Optional) The file extension (not including the period) used to identify source files containing this assembly language. Defaults to asm. BespokeASM will compile any text, but this extension is used primarily by language extensions to identify specific assembly language versions.

Operand Sets

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.

Operand Configuration Dictionary

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: numeric - The Immediate addressing mode. indirect_numeric - The Indirect addressing mode. register - The Register addressing mode. indirect_register - The Indirect Register addressing mode indirect_indexed_register - The Indirect Indexed Register addressing mode. empty - Used to indicate byte code that should be emitted when no operand is present. This enables instructions that can have a variant behavior for a "no operand" case. This type of operand can only be used with operands configured under the specific_operands Instruction Operands Configuration.
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: value - integer - The value of the byte code size - integer - The bit size of the byte code. The value will be masked to this bit size.
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: size - integer - The bit size for the operand argument. The emitted value will be masked to this bit size. byte_align - boolean - Indicates whether the argument value should be aligned to the next whole byte, or can be packed immediately after the prior section's last bit. endian - string - (Optional) The endianness that should be used for this argument. If not present, the default endianness configured in the general section will be used.
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: size - integer - The bit size for the operand offset. The emitted value will be masked to this bit size. byte_align - boolean - Indicates whether the offset value should be aligned to the next whole byte, or can be packed immediately after the prior section's last bit. endian - string - (Optional) The endianness that should be used for this offset. If not present, the default endianness configured in the general section will be used.
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 operants for a specific instruction.

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
byte_code	dictionary	A dictionary that descriptor the byte code prefix that should be emitted to indicate the instruction. The key and values that must be present are: value - The value of the byte code size - The bit size of the byte code. The value will be masked to this bit size. endian - (Optional) The endian of the instruction prefix byte code. Useful only if the instruction byte code bits size is greater than 8. Defaults to the general endian setting.
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.

Instruction Operands Configuration

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: list - A list of names for the operand sets to be used as the operand options for this instruction. Must have count number of items in the list, and the position in the list pertains to the position of the operand. disallowed_pairs - (Optional) A list of operand name tuples that represents combinations of operands from the configured operand sets that the compiler should not permit. The operand name is the key names of the operand_values dictionary for a given operand set. The tuple is expressed as a python-style list. For example, [a, b] is used to indicate a disallowed operand set for a mnemonic with two operands where the unallowed operand tuple is a from the first operand set in combination with b from the second operand set. reverse_argument_order - (Optional) A boolean that indicates whether the machine code for the arguments should be emitted in reverse order. This is useful when it is more convenient for the microcode to process the last argument first, and then continued reverse order for the rest. Affects all operand combinations for the operand_sets, but only has any real impact for instruction operands that need 2 or more arguments emitted. Defaults to false if not present.
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: list - A dictionary of specific operand configurations. The key is an arbitrary string to internally identify the specific operand, and the value is an operand configuration formatted the same as Operand Configuration Dictionary. reverse_argument_order - (Optional) A boolean that indicates whether the machine code for the arguments of this specific operand configuration should be emitted in reverse order. This is useful when it is more convenient for the microcode to process the last argument first, and then continued reverse order for the rest. Only has any real impact for instruction operands that need 2 or more arguments emitted. Defaults to false if not present.

Examples

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