SHENZHEN-IO is an interactive circuit building and programming puzzle game with a programmable microcontroller called the MC6000, it has an extremely simple instruction set and no memory besides 2 registers that can only store numbers from -999 to 999.

Each instruction consists of a label, condition, instruction, and comment:

foo: +mov 50 x2 # puts 50 to XBus 2

Conditions can either be +, -, or blank and control if the instruction should execute after a comparison. Labels are optional and used to tell where the jmp instruction should jump to, this is just sugar to make things easier to keep track of. Registers consist of acc, bak, and 6 virtual registers coresponding to the 6 I/O ports on the MC6000. The game comes with a more in-depth manual with a language specification here:

The first step to implementing this in actual hardware is to lay out the machine code:


000acc 001dat 010p0 011p1
100x0 101x1 110x2 111x3

You may notice the lack of the register null which does nothing when you write to it and returns 0 when you read from it. I did not include it because it can simply be replaced with the literal 0 except when writing to it with MOV, because of this I added the flag E to the instruction SLX which when 1 will eat a value from the bus and do nothing with it.

Condition codes

00always execute
01only execute on - flag
10only execute on + flag
11only execute once

Internally there are two execution flags, + and - which are set by the test instructions TEQ, TGT, TLT, TCP. Every instruction but TCP sets the flags in a differential as in only either + or - can be true at the same time but TCP will disable both flags when both operands are equal.

Because I want to reduce instruction size I've made it so only the first operand of test instructions can be immediate values, because of this things have to be shifted around when assembling:

TGT acc 69 -> TLT 69 acc
TEQ 69 69 -> TST 1 0
TCP acc 42 -> TPC 42 acc

You may notice I've added 2 extra test instructions: TST and TPC.
TST takes 2 operands, + and - and sets the coresponding flags directly, this is always emitted when both operands of a test instruction are immediates.
TPC is the same as TCP but with the operands reversed, this happens when the second operand is an immediate.

Register/Immediate values

10000000 reg Regsiter
immediate Immediate

Immediate values can range from -999 to 999 and are encoded with two's complement and because it doesn't completely fill the 11 bits (0 - 2048) we can store a register number without adding an extra bit to signal whether or not it's a register. To easily tell the difference between the two you simply check if the first 8 bits are 10000000 which means it's <= -1017.

Register/Select values

1 reg Regsiter
0 imm Selection

Register/Digit values

1 reg Regsiter
0 immediate Digit

Register/Digit values work similarly to Register/Immediate values but store single digits from 0 to 9 but requires a flag to differentiate registers from immediates. If the digit is out of bounds it should be encoded as 0b1111 which will be interpreted as a no-op.


cond 000 R/I arg reg MOV
cond 010 00 line JMP
cond 010 01 R/I sleep amount SLP
cond 010 10E xpin SLX
cond 010 11 R/I value ADD
cond 011 00 reg SUB
cond 011 01 R/I value MUL
cond 011 110 NOT
cond 011 100 R/S selection DGT
cond 011 101 R/D value R/S selection DST
cond 100 R/I arg reg TEQ
cond 101 R/I arg reg TGT
cond 110 R/I arg reg TLT
cond 111 R/I arg reg TCP
cond 001 R/I arg reg TPC
cond 011 111 +- TST

Using this layout I made an assembler and disassembler in Dart: