DCPU-16 Specification
Copyright 1985 Mojang
Version 1.7
=== SUMMARY ====================================================================
* 16 bit words
* 0x10000 words of ram
* 8 registers (A, B, C, X, Y, Z, I, J)
* program counter (PC)
* stack pointer (SP)
* extra/excess (EX)
* interrupt address (IA)
In this document, anything within [brackets] is shorthand for "the value of the
RAM at the location of the value inside the brackets". For example, SP means
stack pointer, but [SP] means the value of the RAM at the location the stack
pointer is pointing at.
Whenever the CPU needs to read a word, it reads [PC], then increases PC by one.
Shorthand for this is [PC++]. In some cases, the CPU will modify a value before
reading it, in this case the shorthand is [++PC].
For stability and to reduce bugs, it's strongly suggested all multi-word
operations use little endian in all DCPU-16 programs, wherever possible.
=== INSTRUCTIONS ===============================================================
Instructions are 1-3 words long and are fully defined by the first word.
In a basic instruction, the lower five bits of the first word of the instruction
are the opcode, and the remaining eleven bits are split into a five bit value b
and a six bit value a.
b is always handled by the processor after a, and is the lower five bits.
In bits (in LSB-0 format), a basic instruction has the format: aaaaaabbbbbooooo
In the tables below, C is the time required in cycles to look up the value, or
perform the opcode, VALUE is the numerical value, NAME is the mnemonic, and
DESCRIPTION is a short text that describes the opcode or value.
--- Values: (5/6 bits) ---------------------------------------------------------
C | VALUE | DESCRIPTION
---+-----------+----------------------------------------------------------------
0 | 0x00-0x07 | register (A, B, C, X, Y, Z, I or J, in that order)
0 | 0x08-0x0f | [register]
1 | 0x10-0x17 | [register + next word]
0 | 0x18 | (PUSH / [--SP]) if in b, or (POP / [SP++]) if in a
0 | 0x19 | [SP] / PEEK
1 | 0x1a | [SP + next word] / PICK n
0 | 0x1b | SP
0 | 0x1c | PC
0 | 0x1d | EX
1 | 0x1e | [next word]
1 | 0x1f | next word (literal)
0 | 0x20-0x3f | literal value 0xffff-0x1e (-1..30) (literal) (only for a)
--+-----------+----------------------------------------------------------------
* "next word" means "[PC++]". Increases the word length of the instruction by 1.
* By using 0x18, 0x19, 0x1a as PEEK, POP/PUSH, and PICK there's a reverse stack
starting at memory location 0xffff. Example: "SET PUSH, 10", "SET X, POP"
* Attempting to write to a literal value fails silently
--- Basic opcodes (5 bits) ----------------------------------------------------
C | VAL | NAME | DESCRIPTION
---+------+----------+---------------------------------------------------------
- | 0x00 | n/a | special instruction - see below
1 | 0x01 | SET b, a | sets b to a
2 | 0x02 | ADD b, a | sets b to b+a, sets EX to 0x0001 if there's an overflow,
| | | 0x0 otherwise
2 | 0x03 | SUB b, a | sets b to b-a, sets EX to 0xffff if there's an underflow,
| | | 0x0 otherwise
2 | 0x04 | MUL b, a | sets b to b*a, sets EX to ((b*a)>>16)&0xffff (treats b,
| | | a as unsigned)
2 | 0x05 | MLI b, a | like MUL, but treat b, a as signed
3 | 0x06 | DIV b, a | sets b to b/a, sets EX to ((b<<16)/a)&0xffff. if a==0,
| | | sets b and EX to 0 instead. (treats b, a as unsigned)
3 | 0x07 | DVI b, a | like DIV, but treat b, a as signed. Rounds towards 0
3 | 0x08 | MOD b, a | sets b to b%a. if a==0, sets b to 0 instead.
3 | 0x09 | MDI b, a | like MOD, but treat b, a as signed. (MDI -7, 16 == -7)
1 | 0x0a | AND b, a | sets b to b&a
1 | 0x0b | BOR b, a | sets b to b|a
1 | 0x0c | XOR b, a | sets b to b^a
1 | 0x0d | SHR b, a | sets b to b>>>a, sets EX to ((b<<16)>>a)&0xffff
| | | (logical shift)
1 | 0x0e | ASR b, a | sets b to b>>a, sets EX to ((b<<16)>>>a)&0xffff
| | | (arithmetic shift) (treats b as signed)
1 | 0x0f | SHL b, a | sets b to b<>16)&0xffff
2+| 0x10 | IFB b, a | performs next instruction only if (b&a)!=0
2+| 0x11 | IFC b, a | performs next instruction only if (b&a)==0
2+| 0x12 | IFE b, a | performs next instruction only if b==a
2+| 0x13 | IFN b, a | performs next instruction only if b!=a
2+| 0x14 | IFG b, a | performs next instruction only if b>a
2+| 0x15 | IFA b, a | performs next instruction only if b>a (signed)
2+| 0x16 | IFL b, a | performs next instruction only if b