Editing Spec.isa (section)

== 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.