Spec.isa - Revision history

Gelthor: $ replaced with $start

2026-03-24T11:41:02Z

$ replaced with $start

← Older revision		Revision as of 11:41, 24 March 2026
Line 226:		Line 226:

	==== Instruction Address ====		==== Instruction Address ====
	The special ~~character~~ <code>$</code> returns the memory address of the start of the current instruction. This is useful for instructions such as relative jumps. If we assume <code>0b01000000</code> is the opcode for an absolute unconditional jump, we can use the following example to create a relative jump instruction without any additional hardware:		The special variable <code>$start</code> returns the memory address of the start of the current instruction. This is useful for instructions such as relative jumps. If we assume <code>0b01000000</code> is the opcode for an absolute unconditional jump, we can use the following example to create a relative jump instruction without any additional hardware:
	<pre>		<pre>
	jmp_rel %offset:S16(immediate)		jmp_rel %offset:S16(immediate)
Line 233:		Line 233:
	</pre>		</pre>
	{{note\|type=info\|This instruction only will only work with immediate values. If you try to use a register, you would get the register index - not its contents - added to the instruction address.}}		{{note\|type=info\|This instruction only will only work with immediate values. If you try to use a register, you would get the register index - not its contents - added to the instruction address.}}

			The special variable <code>$end</code> returns the memory address of the end of the current instruction.

	==== Bit slicing ====		==== Bit slicing ====

24.68.66.4: /* Assertions */

2026-02-04T23:40:21Z

Assertions

← Older revision		Revision as of 23:40, 4 February 2026
Line 256:		Line 256:
	</pre>		</pre>

	Assertions can be intermixed with [#~~Virtual_Operands~~\|virtual operands] and trigger an error if they are not true. Currently the only supported comparison operator is equals (<code>==</code>), although more comparisons are planned in future. After the comparison a string can be added to produce a more context-specific error message.		Assertions can be intermixed with [[#Virtual_operands\|virtual operands]] and trigger an error if they are not true. Currently the only supported comparison operator is equals (<code>==</code>), although more comparisons are planned in future. After the comparison a string can be added to produce a more context-specific error message.

	The full syntax is:		The full syntax is:

172.56.169.14: corrected note for block_comments copied from line_comments

2025-10-31T08:31:42Z

corrected note for block_comments copied from line_comments

← Older revision		Revision as of 08:31, 31 October 2025
Line 55:		Line 55:

	{{note\|type=info\|Any parenthesis style can be used for the list syntax: <code>[]</code>, <code>()</code> or <code>{}</code>. The closing parenthesis style must match the opening parenthesis (so <code>(]</code> would fail to parse).}}		{{note\|type=info\|Any parenthesis style can be used for the list syntax: <code>[]</code>, <code>()</code> or <code>{}</code>. The closing parenthesis style must match the opening parenthesis (so <code>(]</code> would fail to parse).}}
	{{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.}}		{{note\|type=warn\|While the compiler respects the <code>block_comments</code> setting, the syntax highlighter in the assembler window currently does not - not even the default tokens.}}

	== Fields ==		== Fields ==

216.19.182.134: /* Addendum: Masking */

2025-03-21T18:55:59Z

Addendum: Masking

← Older revision		Revision as of 18:55, 21 March 2025
Line 336:		Line 336:

	=== Addendum: Masking ===		=== Addendum: Masking ===
	On several occasions through this document, "~~just~~ mask it" has been noted as a solution to various bit width problems. While masking is a fairly common and well-known operation in computer programming, this section will describe it for the sake of completeness.		On several occasions through this document, "mask it out" has been noted as a solution to various bit width problems. While masking is a fairly common and well-known operation in computer programming, this section will describe it for the sake of completeness.

	There are several kinds of masking you hear of on occasion, with the most prominent by far being the ability to extract one or more individual bits from a larger number. This is performed by ANDing the value you want to extract the bits from with a ''mask'', which is a second number containing <code>1</code> in bit positions you wish to extract, and <code>0</code> elsewhere. For example, if we have the number <code>90</code> and wish to extract the bottom four bits, we can use the following code (in [[#Virtual_operands\|virtual operand]] syntax):		There are several kinds of masking you hear of on occasion, with the most prominent by far being the ability to extract one or more individual bits from a larger number. This is performed by ANDing the value you want to extract the bits from with a ''mask'', which is a second number containing <code>1</code> in bit positions you wish to extract, and <code>0</code> elsewhere. For example, if we have the number <code>90</code> and wish to extract the bottom four bits, we can use the following code (in [[#Virtual_operands\|virtual operand]] syntax):

216.19.182.134 at 18:55, 21 March 2025

2025-03-21T18:55:17Z

← Older revision		Revision as of 18:55, 21 March 2025
Line 197:		Line 197:
	\|}		\|}

	{{note\|type=warn\|Be cautious of unexpected bit width extension when using signed values. The parser is fairly good at doing the right thing, but it can occasionally get confused and sign extend to a full 64 bits. When in doubt, [[Addendum:_Masking\|mask]] it out!}}		{{note\|type=warn\|Be cautious of unexpected bit width extension when using signed values. The parser is fairly good at doing the right thing, but it can occasionally get confused and sign extend to a full 64 bits. When in doubt, [[#Addendum:_Masking\|mask]] it out!}}

	==== Operator precedence ====		==== Operator precedence ====
Line 220:		Line 220:
	\| <code>log2</code> \|\| floor of the base-2 logarithm if >0, -1 otherwise \|\| <code>log2(%a)</code> <br> <code>log2(%b)</code> \|\| -1 <br> 4		\| <code>log2</code> \|\| floor of the base-2 logarithm if >0, -1 otherwise \|\| <code>log2(%a)</code> <br> <code>log2(%b)</code> \|\| -1 <br> 4
	\|-		\|-
	\| <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. [[Addendum:_Masking\|~~Mask~~]] out high bits as needed for <64bit values.)		\| <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. [[#Addendum:_Masking\|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		\| <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
Line 249:		Line 249:
	==== Bit widths ====		==== 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 of 0.1354 Beta) which can cause unexpected errors and odd-looking error messages.		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 of 0.1354 Beta) which can cause unexpected errors and odd-looking error messages.
	When in doubt, [[Addendum:_Masking\|mask]] out the result of your expressions to ensure they fit within the intended bit width, especially when working with signed values.		When in doubt, [[#Addendum:_Masking\|mask]] out the result of your expressions to ensure they fit within the intended bit width, especially when working with signed values.

	=== Assertions ===		=== Assertions ===

216.19.182.134: /* An alternative */

2025-03-20T10:10:48Z

An alternative

← Older revision		Revision as of 10:10, 20 March 2025
Line 364:		Line 364:
	%masked = %value[7:4]		%masked = %value[7:4]
	</pre>		</pre>
	will also return the value 5 ~~without the~~ need to shift, as the bit slicing operator treats the lower bound as the LSB of the extracted value.		will also return the value 5. There is no need to shift in this case, as the bit slicing operator treats the lower bound as the LSB of the extracted value.

	==== Constructing a mask ====		==== Constructing a mask ====

216.19.182.134: /* An alternative */

2025-03-20T10:10:05Z

An alternative

← Older revision		Revision as of 10:10, 20 March 2025
Line 364:		Line 364:
	%masked = %value[7:4]		%masked = %value[7:4]
	</pre>		</pre>
	will also return the value 5, as the bit slicing operator treats the lower bound as the LSB of the extracted value.		will also return the value 5 without the need to shift, as the bit slicing operator treats the lower bound as the LSB of the extracted value.

	==== Constructing a mask ====		==== Constructing a mask ====

216.19.182.134: /* Addendum: Masking */

2025-03-20T10:07:57Z

Addendum: Masking

← Older revision		Revision as of 10:07, 20 March 2025
Line 338:		Line 338:
	On several occasions through this document, "just mask it" has been noted as a solution to various bit width problems. While masking is a fairly common and well-known operation in computer programming, this section will describe it for the sake of completeness.		On several occasions through this document, "just mask it" has been noted as a solution to various bit width problems. While masking is a fairly common and well-known operation in computer programming, this section will describe it for the sake of completeness.

	There are several kinds of masking you hear of on occasion, with the most prominent by far being the ability to extract one or more individual bits from a larger number. This is performed by ANDing the value you want to extract the bits from with a ''mask'', which is a second number containing <code>1</code> in bit positions you wish to extract, and <code>0</code> elsewhere. For example, if we have the number 90 and wish to extract the bottom four bits, we can use the following code (in [[Virtual_operands\|virtual operand] syntax):		There are several kinds of masking you hear of on occasion, with the most prominent by far being the ability to extract one or more individual bits from a larger number. This is performed by ANDing the value you want to extract the bits from with a ''mask'', which is a second number containing <code>1</code> in bit positions you wish to extract, and <code>0</code> elsewhere. For example, if we have the number <code>90</code> and wish to extract the bottom four bits, we can use the following code (in [[#Virtual_operands\|virtual operand]] syntax):
	<pre>		<pre>
	%value = 90		%value = 90

Altrag at 09:57, 19 February 2025

2025-02-19T09:57:24Z

← Older revision		Revision as of 09:57, 19 February 2025
Line 1:		Line 1:
	{{Breadcrumbs\|Alpha Branch/{{SUBPAGENAME}}		{{Breadcrumbs\|Alpha Branch/{{SUBPAGENAME}}}}
	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>.		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.}}		{{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.}}

Altrag at 09:57, 19 February 2025

2025-02-19T09:57:00Z

← Older revision		Revision as of 09:57, 19 February 2025
Line 1:		Line 1:
	{{Breadcrumbs\|Alpha Branch/~~Spec.isa~~}}		{{Breadcrumbs\|Alpha Branch/{{SUBPAGENAME}}
	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>.		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.}}		{{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.}}