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]]
* [[#Virtual_operands|Virtual operands]]
* [[#Assertions|Assertions]]
* [[#Output_bit_pattern|The output bit pattern]]
* [[Description|An optional description line]]

To motivate with an example, let's consider the following hypothetical DIV instruction that could be added to the Symphony architecture:
<pre>
div %a(register), %b(register), %c:S16(immediate)
%bits = (0 - popcount(%c))
!assert %bits >> 63 == 1
01011100 0aaa0bbb cccccccc cccccccc
Signed DIV %b by %c and store the result in %a.
</pre>

=== Assembly format ===
<pre>
div %a(register), %b(register), %c:S16(immediate)
</pre>
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&nbsp;()</code> would match <code>function()</code> or <code>function&nbsp;()</code>, while the instruction <code>function&nbsp;&nbsp;()</code> (with two spaces) 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 <code>%</code> 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><nowiki>|</nowiki></code>) character.

=== Virtual operands ===
<pre>
%bits = 0 - popcount(%c)
</pre>
In addition to the operands included in the instruction syntax, additional "virtual" operands can be created to simplify instruction creation or, as in this example, to provide some minimal compile-time correctness guarantees.

==== Operators ====
The game provides a limited set of operators for the construction of virtual operands:
{| class="wikitable"
! Operator !! Description !! Example !! Result if %a = -30000, 16-bit
|-
| <code>+</code> || addition || <code>%a + 7</code> || -29993
|-
| <code>-</code> || subtraction || <code>%a - 7</code> || -20007
|-
| <code>*</code> || multiplication || <code>%a * 7</code> || -13392
|-
| <code>/</code> || division || <code>%a / 7</code> || -4285
|-
| <code>%</code> || modulo (remainder after division) || <code>%a % 7</code> || -5
|-
| <code>&</code> || bitwise AND || <code>%a & 7</code> || 0
|-
| <code><nowiki>|</nowiki></code> || bitwise OR || <code>%a <nowiki>|</nowiki> 7</code> || -29993
|-
| <code>^</code> || bitwise XOR || <code>%a ^ 7</code> || -29993
|-
| <code>&lt;&lt;</code> || logical shift left (LSL) || <code>%a &lt;&lt; 7</code> || 26624
|-
| <code>&gt;&gt;</code> || logical shift right (LSR) || <code>%a &gt;&gt; 7</code> || 277
|}

A notable omission is the lack of unary operators.  However, the two most common unary operations can be written using binary operators as follows:
{| class="wikitable"
! Operation !! Alternative
|-
| NOT %a || <code>(-1 ^ %a)</code>
|-
| -%a || <code>(0 - %a)</code>
|}

==== Operator precedence ====
The game only defines three precedence levels:
{| class="wikitable"
! Precedence !! Operators
|-
| Parenthesis || <code>()</code>
|-
| Multiplicative || <code>*</code>, <code>/</code>, <code>%</code>
|-
| Everything else || <code>+</code>, <code>-</code>, <code>&</code>, <code><nowiki>|</nowiki></code>, <code>^</code>, <code>&lt;&lt;</code>, <code>&gt;&gt;</code>
|}

==== Functions ====
The game also provides a handful of built-in functions for the construction of virtual operands:
{| class="wikitable"
! Function !! Description !! Example !! Result if %a = -30000, 16-bit
|-
| <code>asr</code> || arithmetic shift right (ASR) || <code>asr(%a, 7)</code> || -235
|-
| <code>log2</code> || base-2 logarithm if >0, -1 otherwise || <code>log2(%a)</code> || -1
|-
| <code>popcount</code> || number of <code>1</code>s in the base-2 representation || <code>popcount(%a)</code> || 6 ({{note}} currently reports 54 as of 0.1354.  Mask out high bits as needed for <64bit values.)
|-
| <code>trailing_zeros</code> || number of <code>0</code>s after the rightmost <code>1</code> in the base-2 representation || <code>trailing_zeros(%a)</code> || 4
|}

==== Operands ====
Virtual operands can refer to any operands from the instruction definition, as well as any virtual operands created on the preceding lines.

==== Assignment ====
The virtual operand being created - on the left of the equals (<code>=</code>) symbol - are written using the format <code>%name:size</code>, similar to instruction definition operands but lacking the fields specification.

==== Bit widths ====
Some operations (such as multiplication) will easily allow you to exceed the bit width of the virtual operand you're creating, or of the final output bytes.  The game will cause an error when that occurs.  Additionally, negative values are prone to being interpreted as 64-bit unsigned values (as 0f 0.1354 Beta) which can cause unexpected errors and odd-looking error messages.
When in doubt, mask out the result of your expressions to ensure they fit within the intended bit width, especially when working with signed values.