Editing Spec.isa

{{Breadcrumbs|Alpha Branch}}
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 <code>spec.isa</code>.
{{note|type=info|Stuffe has released a utility to parse, compile, decompile and perform other operations on ISA specifications here: https://github.com/Stuffe/isa_spec.}}

An ISA specification file consists of several sections, delimited by section headers enclosed in square brackets (<code>[]</code>).

== Settings ==
The <code>[settings]</code> section defines several configuration properties for your ISA:

=== name ===
<pre>
name = "Architecture name"
name = architecture_name
</pre>
Names the architecture this ISA specifies.  It can be either a string or an identifier.

=== variant ===
<pre>
variant = "Architecture variant"
</pre>
Additional text that can be used to describe the ISA.

=== endianness ===
Defines the byte order of the instructions.
<pre>
endianness = big
endianness = little
</pre>
The default is big endian.

For example, if we have an instruction defined as <code>11110000 00001111</code> then:
* <code>big</code> endian will encode the instruction as <code>240 15</code>.
* <code>little</code> endian will encode the same instruction as <code>15 240</code>.
(as shown in, for example, the {{Component|ROM||alpha}} component)

{{note|type=info|The ROM component has it's own endianness flag, which can reverse the byte order again.  This is straightforward if your instruction width happens to match the ROM's bit width, but can be confusing if the widths differ.}}

=== 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.
<pre>
line_comments = "#"
line_comments = [";", "//"]
</pre>
The default line_comments value is <code>[";", "//"]</code>.
{{note|type=info|Any parenthesis style cam be used for the list syntax: <code>[]</code>, <code>()</code> or <code>{}</code>.}}
{{note|type=warn|While the compiler respects the <code>line_comments</code> 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).
<pre>
block_comments = {"/*":"*/"}
</pre>
The default block_comments value is <code>{"/*":"*/}</code>.
{{note|type=info|Any parenthesis style cam be used for the list syntax: <code>[]</code>, <code>()</code> or <code>{}</code>.}}
{{note|type=warn|While the compiler respects the <code>line_comments</code> setting, the syntax highlighter in the assembler window currently does not - not even the default tokens.}}

== Fields ==
The <code>[fields]</code> 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:
<pre>
register
r0 000
r1 001
r2 010
r3 011
r4 100
r5 101
in 110
out 110
</pre>
Here we can see a couple of features:
* Names are arbitrary.  <code>r0</code> through <code>r5</code> are considered registers only by convention, while <code>in</code> and <code>out</code> follow an entirely different naming scheme within the same <code>register</code> field.
* Value repetition is allowed.  <code>in</code> and <code>out</code> both have the same value of <code>110</code>.
* Completion is not required.  <code>111</code> is 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:
<pre>
condition_code
eq 0000
ne 0001
cs 0010
hs 0010
</pre>
(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 <code>register</code>, 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 <code>aarch64.isa</code>:
pound
"#" 0
"" 0
The features this time are:
* <code>"literal"</code> syntax to require a literal string be included in your instructions.
* <code>""</code> to allow an empty string, effectively making this field optional.
In this instance, the <code>pound</code> field is used for immediate values, allowing the player to write either <code>#37</code> or just <code>37</code> to describe the immediate value 37.

=== Reserved field names ===
There are two reserved names:
* <code>label</code> references labels within the assembler (eg: <code>mylabel:</code>).
* <code>immediate</code> references immediate values (eg: <code>37</code>).

== Instructions ==

The <code>[instructions]</code> section is where we finally define the instructions themselves.  Instructions are separated by a blank line and each consists of several lines:
* [[#Assembly_format|The assembly format]]
* [[#Assignments_and_assertions|Assignments and assertions]]
* [[#Output_bit_pattern|The output bit pattern]]
* An optional description line.

To motivate with an example, let's consider the following instruction definition from the Symphony architecture:
<pre>
add %a(register), %b(register), %c(immediate)
01000100 0aaa0bbb cccccccc cccccccc
ADD %b and %c and store the result in %a.
</pre>

=== 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 <code>function ()</code> would match <code>function()</code> or <code>function()</code>, while the instruction <code>function  ()</code> will only match the latter, enforcing the space between the word "function" and the following parenthesis.

==== Literals ====
"<code>add</code>" 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 (<code>,</code>) are also literals.
{{note|type=info|The digraph <code>%%</code> must be used if you wish to use a literal <code>%</code> symbol in your assembly syntax, as <code>%</code> is a special character in the ISA language itself.}}
{{note|type=warn|The game does not currently prevent you from using your line or block comment tokens as literals.  However, they will be treated as comment tokens by the assembler and will prevent the instruction from functioning.}}

==== Operands ====
Operands start with the % prefix and are written in the form <code>%name:size(fields)</code>.
* <code>name</code> is any identifier.  These are typically kept short for convenience such as <code>%a</code> or <code>%imm</code>, but in principle can be any length.
* <code>size</code> is either <code>S</code> or <code>U</code> for signed and unsigned values, respectively, followed by a size in bits.  For example <code>S32</code> or <code>U3</code>.  The default is <code>U64</code>, and the size cannot currently exceed 64 bits.
* <code>fields</code> is a list of one or more fields created in the [[#Fields|prior section]] (or the reserved fields).  The list is delimited by the pipe (<code>|</code>) character.