Maddie's test ISA Version 1.0.10


Table of contents:
1 - Overview
2 - Instruction conditions
3 - Instruction categories
4 - Instruction descriptions


- Overview:
The numbers: 16 bit words, 2-word fixed instruction length, 32 16-bit registers,
65535 main memory and VRAM addresses each, 2^32 max disk addresses.

Features: All instructions can have conditional execution attached.
Hardware and software interrupts are toggleable. Serial port I/O intended for
interfacing with STDIN/STDOUT on simulated versions. Load/Store architecture.

Registers: 32 registers, with registers #29-31 (zero indexed) reserved for the
following special purposes, in order: disk index, stack pointer, program
counter. The program counter is freely readable, but
only modifiable through instructions in the control flow category. There is
also a 2 bit flags register for storing the condition flags.

Behaviours: The only statefulness not directly controlled by programs is the
interrupt toggle. Numbers are read as big endian. Hardware interrupts jump to
zero, and push the prior program counter to the stack. Unknown opcodes are
treated as a halt. The program counter increments by 2 after every instruction
except control flow, with no alignment checks.

Versioning: The versioning of this ISA follows semantic versioning, although
given how many breaking changes it is likely to go though, the major version
number may get very high.

Notes for reading: In the description of a bit or collection of bits for an
instruction, anything following a tag such as (A=1) means that any behaviours
described between that tag and the next tag, or end of line, are only followed
when the condition in the tag is met. If no conditions are met, no additional
behaviour is to occur.


- Instruction Conditions:
ABab----|--------|--------|--------
AB = Activation Flags
ab = Condition Flags

There is a single 2-bit register in the CPU
(A=1) The instruction will only execute if the first bit in that register
matches a.
(B=1) The instruction will only execute if the second bit in that register
matches b.
- Instruction Categories:
----XXXX|--------|--------|---------
XXXX=
0000: Halt
0001: Arithmetic
0010: Logical
0011: Condition Check
0100: Control Flow
0101: Memory Access
0110: Immediate Value
1111: No-op

Halt:
----0000|--------|--------|---------
Halts the processor.

Arithmetic:
----0001|SCFIXXXX|--------|---------
S: Input is (S=0) unsigned, (S=1) signed using 2's complement
C: (C=1) Update the specified condition flag upon overflow or division by 0
F: Specifies (F=0) flag A or (F=1) flag B
I: (I=1) Invert the result

XXXX=
0000: Addition
0001: Subtraction
0010: Multiplication
0011: Integer Division

Logical:
----0010|ZFRIXXXX|--------|--------
Z: (Z=1) Update the specified condition flag if the result is zero
F: Specifies (F=0) flag A or (F=1) flag B
R: (I=1) Invert the flag write
I: (I=1) Invert the result, acts before the zero check

XXXX=
0000: AND
0001: OR
0010: XOR

Condition check:
----0011|FIXX----|--------|--------
F: Specifies (F=0) flag A or (F=1) flag B
I: (I=0) Normal write, (I=1) inverted write

XX=
00: Equal
01: Less than
10: Greater than

Control flow:
----0100|JSPITT--|--------|--------
J: (J=0) Jump to the described address, (J=1) Add the described value to the
program counter
S: (S=1) Push what would have been the next address to the stack
P: (P=1) Pop from the stack and use the stack value instead of a register
value
I: (I=1) If interrupts are enabled, jump to 0. This overrides J and P,
preventing the pop from occuring. Note that if interrupts are disabled then J
and P will work normally.

TT=
0x: No additional effect
10: Toggle interrupts off
11: Toggle interrupts on, both of these operations act after the condition
check for I=1

Memory access:
----0101|AXXX----|--------|--------
A: (A=0) Read/pop, (A=1) Write/push

XXX=
000: Pop/push to stack
001: Read/write main memory
010: R/W disk
011: R/W VRAM
100: R/W to serial port, using only the lower 8 bits of a value, setting the
upper 8 bits to 0 on a read.

Immediate value:
----0110|RRRRR---|xxxxxxxx|xxxxxxxx
Writes the value denoted by x's to the register of index RRRRR


-Instruction descriptions:
--------|--------|11111222|2233333-
11111: Operand 1
22222: Operand 2
33333: Operand 3

Arithmetic:
Addition, subtraction, multiplications, and integer division all take 3
operands, and operate on the described registers in the order of 3 = 1 (+-x/) 2
Division by 0 is a no-op except for optionally setting a condition flag

Logical:
All logical operations take 3 operands, and operate on the described registers
in the order 3 = 1 (OP) 2

Condition check:
Takes 2 operands, and performs the described check in the order of 1 (<,=,>) 2

Control flow:
Takes 1 operand, describing the register of the address/value to be used,
which is ignored if using a stack value

Memory access:
Takes 2 operands, the first describes the register to write from/read to, and
the second describing the register containing the target memory address.
When reading/writing to disk, the address is further offset by the disk index
register multiplied by 2^16

Immediate value:
Already fully described above.