Maddie's test ISA Version 1.0.2


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 disc 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 #28-31 (zero indexed) reserved for the
following special purposes, in order: disk index, stack pointer, program
counter, and interrupt register. 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: Upon power up, the first 512 words of disk are copied to main
memory. 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.

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 2 bit register in the CPU which stores the state of A and B, and is
updated by certain instructions.
When an activation flag is set, the corresponding condition bit must match its
condition flag in order for the instruction to be executed.

- 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
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 the current 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 before 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 RAM
010: R/W disk
011: R/W VRAM
100: R/W to serial port

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

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.