The ISA ("Instruction Set Architecture") specification is the language used to define assembly instructions in Turing Complete. ISA specifications are stored alongside schematics in the player's save folder, with the name spec.isa.
An ISA specification file consists of several sections, delimited by section headers enclosed in square brackets ([]).
Settings
The [settings] section defines several configuration properties for your ISA:
name
name = "Architecture name" name = architecture_name
Names the architecture this ISA specifies. It can be either a string or an identifier.
variant
variant = "Architecture variant"
Additional text that can be used to describe the ISA.
endianness
Defines the byte order of the instructions.
endianness = big endianness = little
The default is big endian.
For example, if we have an instruction defined as 11110000 00001111 then:
bigendian will encode the instruction as240 15.littleendian will encode the same instruction as15 240.
(as shown in, for example, the ROM component)
line_comments
Specifies the tokens used to mark the start of a single-line comment. Single-line comments start at the given token and consume the remainder of the line.
line_comments = "#" line_comments = [";", "//"]
The default line_comments value is [";", "//"].
[], () or {}.line_comments setting, the syntax highlighter in the assembler window currently only recognizes the default tokens.block_comments
Specifies the tokens used to mark the start and end of a block comment. Block comments start at the first token and consume everything up to the final token. This includes line breaks as well as additional block comment start tokens (preventing block comments from being nested).
block_comments = {"/*":"*/"}
The default block_comments value is {"/*":"*/}.
[], () or {}.line_comments setting, the syntax highlighter in the assembler window currently does not - not even the default tokens.Fields
The [fields] section defines different types of fields that can be included in the instruction definitions, as well as what values they can have. Fields are separated by blank lines, and each field starts with a field name on the first line followed by one or more allowable field values. Values are bit patterns and all values within a field must have the same bit length.
Example 1 - Overture
The Overture specification provides a good starting example:
register r0 000 r1 001 r2 010 r3 011 r4 100 r5 101 in 110 out 110
Here we can see a couple of features:
- Names are arbitrary.
r0throughr5are considered registers only by convention, whileinandoutfollow an entirely different naming scheme within the sameregisterfield. - Value repetition is allowed.
inandoutboth have the same value of110. - Completion is not required.
111is not assigned to any label.
Example 2 - aarch64
Also note that the field name itself is arbitrary. We can take an excerpt from https://github.com/Stuffe/isa_spec/blob/main/spec_lib/aarch64/aarch64.isa as an example:
condition_code eq 0000 ne 0001 cs 0010 hs 0010
(In this case, all 16 values are included in the ISA itself, and has been truncated here for the sake of brevity.)
We can see a couple of other features in this example:
- The field name is not
register, as noted. - The field is four bits wide rather than three. In principle, the fields can be any width desired (greater than zero).
Example 3 - aarch64, again
A final example from the same aarch64.isa:
pound
"#" 0
"" 0
The features this time are:
"literal"syntax to require a literal string be included in your instructions.""to allow an empty string, effectively making this field optional.
In this instance, the pound field is used for immediate values, allowing the player to write either #37 or just 37 to describe the immediate value 37.
Reserved field names
There are two reserved names:
labelreferences labels within the assembler (eg:mylabel:).immediatereferences immediate values (eg:37).
Instructions
The [instructions] section is where we finally define the instructions themselves. Instructions are separated by a blank line and each consists of several lines:
- The assembly format
- Assignments and assertions
- The output bit pattern
- An optional description line.
To motivate with an example, let's consider the following instruction definition from the Symphony architecture:
add %a(register), %b(register), %c(immediate) 01000100 0aaa0bbb cccccccc cccccccc ADD %b and %c and store the result in %a.
Assembly format
The assembly format is a string of whitespace-delimited tokens, which come in two flavors: literals and operands.
Whitespace
Whitespace can be either tabs or spaces. If a single whitespace character is used, the space will be optional in the resulting assembly language. If the whitespace character is instead followed by another space (
Note: note: not a tab), the assembler will require whitespace between the tokens. For example, an instruction like function () would match function() or function(), while the instruction function () will only match the latter, enforcing the space between the word "function" and the following parenthesis.
Literals
"add" in the motivating example is a literal. The user must type this exactly in order for the instruction to be matched. Of particular note however is that the commas (,) are also literals.
%% must be used if you wish to use a literal % symbol in your assembly syntax, as % is a special character in the ISA language itself.Operands
Operands start with the % prefix and are written in the form %name:size(fields).
nameis any identifier. These are typically kept short for convenience such as%aor%imm, but in principle can be any length.sizeis eitherSorUfor signed and unsigned values, respectively, followed by a size in bits. For exampleS32orU3. The default isU64, and the size cannot currently exceed 64 bits.fieldsis a list of one or more fields created in the prior section (or the reserved fields). The list is delimited by the pipe (|) character.