Instruction set

This is the instruction set for the DCPU-16 assembly language, conforming to Version 1.7 of the specification published by Notch.

Mnemonics

Basic Instructions

Instruction	Behavior	EX register usage	Base cycle cost	See also
SET B, A	Set Stores the value of A in B.	None	1
ADD B, A	Add Stores the value of B+A in B.	EX = 0x1 if B+A > 0xffff, 0 otherwise	2
SUB B, A	Subtract Stores the value of B−A in B.	EX = 0xffff if A > B, 0 otherwise	2
MUL B, A	Multiply Stores the value of B*A in B.	EX = the upper 16 bits of B*A	2
MLI B, A	Multiply Inverse Stores the value of B*A in B, where A and B are treated as signed.	EX = the upper 16 bits of B*A	2
DIV B, A	Divide Stores the value of B/A in B. Sets B to 0 if A is 0 (not an error).	EX = 0 if A is 0, or the lower 16 bits of B/A otherwise.	3
DVI B, A	Divide Inverse Stores the value of B/A in B, where A and B are treated as signed. Sets B to 0 if A is 0 (not an error). Rounds the result towards 0.	EX = 0 if A is 0, or the lower 16 bits of B/A otherwise.	3
MOD B, A	Modulo Stores the remainder of B/A in B. Sets B to 0 if A is 0 (not an error).	None	3
MDI B, A	Modulo Inverse Stores the remainder of B/A in B, where A and B are treated as signed. Sets B to 0 if A is 0 (not an error).	None	3
AND B, A	AND Stores bitwise AND of B and A in B.	None	1	boolean algebra
BOR B, A	Bitwise OR Stores bitwise OR of B and A in B.	None	1	boolean algebra
XOR B, A	Exclusive-OR Stores bitwise EXCLUSIVE OR of B and A in B.	None	1	boolean algebra
SHR B, A	Shift Right Shifts B to the right by A bits.	EX = the lower A bits of B that were shifted out	1	boolean algebra
ASR B, A	Arithmetic Shift Right Shifts B to the right by A bits. B is treated as signed.	EX = the lower A bits of B that were shifted out	1	boolean algebra
SHL B, A	Shift Left Shifts B to the left by A bits.	EX = the upper A bits of B that were shifted out	1	boolean algebra
IFE B, A	If Equal Perform the next instruction if B is equal to A.	None	2*	control flow
IFN B, A	If Not Equal Perform the next instruction if B is not equal to A.	None	2*	control flow
IFG B, A	If Greater Perform the next instruction if B is strictly greater than A.	None	2*	control flow
IFA B, A	If After Perform the next instruction if B is strictly greater than A. A and B are treated as signed.	None	2*	control flow
IFL B, A	If Less Perform the next instruction if B is strictly less than A.	None	2*	control flow
IFU B, A	If Under Perform the next instruction if B is strictly less than A. A and B are treated as signed.	None	2*	control flow
IFB B, A	If Bits[/If Blank] Perform the next instruction if B&A is not zero. In other words, if B and A have any of the same bits set, perform the next instruction.	None	2*	control flow
IFC B, A	If Clear Perform the next instruction if B&A is zero. In other words, if B and A have any of the same bits set, omit the next instruction.	None	2*	control flow
ADX B, A	Add EX Stores the value of A+B+EX in B.	On overflow, set EX to 0x0001. Otherwise, set EX to 0.	3
SBX B, A	Subtract [with] EX Stores the value of A−B+EX in B.	On underflow, set EX to 0xffff. Otherwise, set EX to 0.	3
STI B, A	Set-Increment Stores A in B, then increases I and J by 1.	None	2
STD B, A	Set-Decrement Stores A in B, then decreases I and J by 1.	None	2

* Conditional instructions have a base cost of two, plus a cost of one cycle for every additional conditional skipped.

Special Instructions

Instruction	Behavior	Base cycle cost	See also
JSR A	Jump Subroutine Stores the address of the next instruction on the stack and begins the subroutine located at A.	3	control flow
INT A	Interrupt Triggers an interrupt from software with message A.	4	interrupt
IAG A	Interrupt Address Get Sets A to IA.	1	interrupt
IAS A	Interrupt Address Set Sets IA to A.	1	interrupt
RFI A	Return From Interrupt Disables interrupt queueing, pops A from the stack, then pops PC from the stack.	3	interrupt
IAQ A	Interrupt Address Queue If A is nonzero, interrupts will be added to the queue instead of triggered. If A is zero, interrupts will be triggered as normal again.	2	interrupt
HWN A	Hardware Number Sets A to the number of hardware devices.	2
HWQ A	Hardware Query Sets A, B, C, X and Y registers to information about hardware A. A+(B<<16) is the 32-bit hardware ID. C is the hardware version. X+(Y<<16) is the 32-bit manufacturer code.	4
HWI A	Hardware Interrupt Sends an interrupt to hardware A.	4*	interrupt

* HWI has a base cost of four, plus however long the hardware device takes to return control to the processor.

Addressing Modes

Name	Example	Description	See Also
Immediate	SET A, 42	Uses a literal number as the source of an operation. Using it as the destination fails silently.
Register	SET A, B	Uses a register as the source or destination.	registers
Memory	SET [0x100], [0x100+I]	Uses a memory location as the source or destination. The location can be either a literal number, a general purpose register, or the sum of the two.
PEEK	SET A, PEEK	Uses the location in memory pointed to by the stack pointer as the source or destination. The stack pointer itself is left unmodified.	stack
PICK	SET A, PICK 1	Uses the location in memory pointed to by the stack pointer, plus the argument to PICK, as the source or destination. The stack pointer itself is left unmodified.	stack
PUSH	SET PUSH, 10	First, decrements the stack pointer by 1. Then, uses the new memory location pointed to by SP. ("Pushing" a new value onto the stack.)	stack
POP	SET A, POP	First, uses the location pointed to by SP. Then, increments the stack pointer by 1. ("Popping" a value off the stack.)	stack

Machine Code Format

A DCPU-16 instruction may be one, two, or three 16-bit words long. Of these, the first word is the most important and complex. It has three sections, including a five-bit numerical opcode:

(MSB)
a
a
a   The source argument (6 bits) - the location specified here is usually
a   not modified.
a
a

b
b   The destination argument (5 bits) - where the result is placed.
b   For special instructions, this is the five-bit numerical opcode.
b
b

o
o   The numerical opcode (5 bits).
o   For special instructions, this is always zero; the special instruction
o   opcode is stored in b.
o
(LSB)

For example, SET is a basic instruction with the format

aaaaaa bbbbb 00001

However, JSR is a special instruction with the format

aaaaaa 00001 00000

The six-bit a section specifies the source argument, and the DCPU always handles it before the b section. The source argument is used as an input, and is usually not modified by the instruction. (Exceptions: HWN, HWQ, IAG, and possibly HWI.) It is interpreted as follows:

Source argument (a section)

Value (Hex)	Value (Binary)	Assembly syntax	Description	Added cost (cycles and words RAM)
0x00 to 0x07	0b00 0000 to 0b00 0111	register	Literal value of register: A, B, C, X, Y, Z, I, J, in that order	0
0x08 to 0x0f	0b00 1000 to 0b00 1111	[register]	Value stored in memory at address register: A, B, C, X, Y, Z, I, J, in that order.	0
0x10 to 0x17	0b01 0000 to 0b01 0111	[register + next_word]	Value stored in memory at address offset register + next_word. register is A, B, C, X, Y, Z, I, J, in that order	1
0x18	0b01 1000	POP	Pops a value from the stack. I.e., fetches the value at the top of the stack, and increments SP, moving the stack pointer towards the end of addressable memory.	0
0x19	0b01 1001	PEEK	Peeks at the value at the top of the stack. I.e., fetches a value pointed to by SP without modifying SP.	0
0x1a	0b01 1010	PICK next_word	Picks a value in the stack. I.e., fetches a value at depth next_word from the stack, without modifying SP.	1
0x1b	0b01 1011	SP	Literal value of the SP register.	0
0x1c	0b01 1100	PC	Literal value of the PC register.	0
0x1d	0b01 1101	EX	Literal value of the EX register.	0
0x1e	0b01 1110	[next_word]	The value stored in memory at address next_word.	1
0x1f	0b01 1111	next_word	The literal value of next_word.	1
0x20 to 0x3f	0b10 0000 to 0b11 1111	small_literal_value	The literal value of small_literal_value, ranging from -1 to 30.	0

If the instruction is not a special instruction, the five-bit b section is treated as the destination argument. It is usually modified by the instruction (with the notable exception of conditional instructions) and is thus used both as an input and as an output. It is interpreted similar to the a section, with the following differences:

• Instead of interpreting 0x18 as POP, the DCPU interprets it as PUSH
• Small literal values must be stored in an additional word at the end of the instruction.
• Writing to a literal value fails silently.

Therefore, the b section is interpreted as follows (differences with the a section highlighted):

Destination argument (b section)

Value (Hex)	Value (Binary)	Assembly syntax	Description	Added cost (cycles and words RAM)
0x00 to 0x07	0b0 0000 to 0b0 0111	register	Literal value of register: A, B, C, X, Y, Z, I, J, in that order	0
0x08 to 0x0f	0b0 1000 to 0b0 1111	[register]	Value stored in memory at address register: A, B, C, X, Y, Z, I, J, in that order.	0
0x10 to 0x17	0b1 0000 to 0b1 0111	[register + next_word]	Value stored in memory at address offset register + next_word. register is A, B, C, X, Y, Z, I, J, in that order	1
0x18	0b1 1000	PUSH	Pushes a value onto the stack. I.e., fetches the value at the top of the stack, and decrements SP, moving the stack pointer towards the beginning of addressable memory.	0
0x19	0b1 1001	PEEK	Peeks at the value at the top of the stack. I.e., fetches a value pointed to by SP without modifying SP.	0
0x1a	0b1 1010	PICK next_word	Picks a value in the stack. I.e., fetches a value at depth next_word from the stack, without modifying SP.	1
0x1b	0b1 1011	SP	Literal value of the SP register.	0
0x1c	0b1 1100	PC	Literal value of the PC register.	0
0x1d	0b1 1101	EX	Literal value of the EX register.	0
0x1e	0b1 1110	[next_word]	The value stored in memory at address next_word.	1
0x1f	0b1 1111	next_word	The literal value of next_word.	1
(Small literal values only for a section)

If only one argument requires an extra word, the instruction is two words long. If both require an extra word, the a section is given the second word, and the b section is given the third word. The additional cycle cost of the arguments is equal to the number of additional words they require.

The total cycle cost of the instruction is equal to the base cost of the instruction, plus the additional cycle cost of the arguments.

See also

• Early versions of the DCPU-16

References

• DCPU-16 1.7 specification (Copyright 2012 Mojang)