201 lines
5.1 KiB
Markdown
201 lines
5.1 KiB
Markdown
# Cardiograph Mark I — simulator for an imaginary computer
|
||
|
||
Cardiograph is an imaginary computer. It has three main components:
|
||
|
||
1. the CPU, *Card* (short for 'Completely Analogue Risc Machine')
|
||
2. an input-output processor, *IO*
|
||
3. a display, *Graph*
|
||
|
||
## Simulator
|
||
|
||
### Dependencies
|
||
|
||
- Node.js
|
||
|
||
|
||
### Quick examples
|
||
|
||
Assemble and run:
|
||
```./assembler.js -i <source.asm> | ./cardiograph.js```
|
||
|
||
Assemble to a file:
|
||
```./assembler.js -i <source.asm> -o <machinecode.out>```
|
||
|
||
Run from a file:
|
||
```./cardiograph.js -i <machinecode.out>```
|
||
|
||
|
||
### Assembler: assembler.js
|
||
|
||
```
|
||
Usage: ./assembler.js [-a] -i <input-file> [-o <output-file>]
|
||
|
||
-a, --annotate Output code with debugging annotations
|
||
-i, --in <file> Assembly-language input
|
||
-o, --out <file> Machine-code output
|
||
```
|
||
|
||
- If an output file is not provided, the output is printed to stdout
|
||
|
||
- If the `annotate` flag is not set, the machine code is returned as a string of space-separated decimal numbers
|
||
|
||
|
||
### Simulator: cardiograph.js
|
||
|
||
```
|
||
Usage: ./cardiograph.js [-i <file>]
|
||
|
||
-i, --in <file> Machine-code input
|
||
```
|
||
|
||
- If an input file is not provided, the input is read from stdin
|
||
|
||
|
||
## CPU
|
||
|
||
### Registers and Flags
|
||
|
||
There are three registers:
|
||
|
||
1. **A**, an 8-bit accumulator
|
||
2. **IP**, an 8-bit instruction pointer (aka program counter)
|
||
3. **flags**, a 4-bit flag register
|
||
|
||
The four flags are **O**verflow, **N**egative, **Z**ero, and **C**arry.
|
||
|
||
(Overflow is the high bit and carry is the low bit.)
|
||
|
||
In decimal:
|
||
|
||
| O | N | Z | C |
|
||
|---|---|---|---|
|
||
| 3 | 2 | 1 | 0 |
|
||
|
||
|
||
### Instruction set
|
||
|
||
#### Operations
|
||
|
||
```
|
||
Hex Mnem. Operand Effect
|
||
|
||
00 END (ignored) Halt CPU
|
||
01 STO literal # mem[lit#] = A
|
||
02 STO address mem[mem[addr]] = A
|
||
03 LDA literal # A = lit#
|
||
04 LDA address A = addr
|
||
05 ADD literal # A = A + lit#
|
||
06 ADD address A = A + mem[addr]
|
||
07 SUB literal # A = A - lit#
|
||
08 SUB address A = A - mem[addr]
|
||
09 HOP literal # If A == lit#, skip next op (IP += 4)
|
||
0A HOP address If A == mem[addr], skip next instruction (IP += 4)
|
||
0B JMP literal # IP = lit#
|
||
0C JMP address IP = mem[addr]
|
||
0D FTG literal # Toggle flag, where flag number == lit#
|
||
0E FHP literal # Skip next op if flag is set, where flag number == lit#
|
||
0F NOP (ignored) None
|
||
```
|
||
|
||
- Instructions are two bytes long:
|
||
one byte for the opcode, one for the operand
|
||
|
||
|
||
#### Effects on memory, flags, registers
|
||
|
||
```
|
||
op mem flags IP
|
||
|
||
END +2
|
||
NOP +2
|
||
|
||
STO w +2
|
||
LDA r NZ +2
|
||
ADD ONZC +2
|
||
SUB ONZC +2
|
||
HOP +2/+4
|
||
JMP arg
|
||
FTG ONZC +2
|
||
FHP ONZC +2/+4
|
||
|
||
STO r,w +2
|
||
LDA r,r NZ +2
|
||
ADD r ONZC +2
|
||
SUB r ONZC +2
|
||
HOP r +2/+4
|
||
JMP r arg
|
||
FTG r ONZC +2
|
||
FHP r ONZC +2/+4
|
||
```
|
||
|
||
### Start-up
|
||
|
||
When starting up, the CPU executes a `JMP $FF`.
|
||
|
||
Put differently: it starts executing instructions at the address contained in `$FF`.
|
||
|
||
<mark>TODO: currently the simulator doesn't actually do this</mark>
|
||
|
||
|
||
### Assembly language
|
||
|
||
ADD $01 ; comments follow a `;`
|
||
|
||
ADD $FF ; this is direct addressing
|
||
ADD ($CC) ; this is indirect addressing
|
||
|
||
END ; END and NOP don't require operands
|
||
; (the assembler will fill in a default value of 0)
|
||
|
||
@subroutine ; create a label
|
||
ADD $01 ; (it must be on the line before the code it names)
|
||
ADD $02
|
||
|
||
JMP @subroutine ; use a label as operand
|
||
; the label will be replaced with
|
||
; the address of the label
|
||
|
||
#foo $FF ; define a constant
|
||
; (must be defined before it is referenced)
|
||
|
||
ADD #foo ; use a constant as an operand
|
||
|
||
LDA * ; `*` is a special label referencing the memory address
|
||
; where the current line will be stored after assembly
|
||
|
||
- Prefix hexadecimal numbers with `$` (or `0x`)
|
||
- Prefix binary numbers with `0b`
|
||
- Whitespace is ignored
|
||
|
||
## Cardiograph memory map
|
||
|
||
| Address | Used for... |
|
||
|----------|-----------------------------------------------|
|
||
| 00 to 19 | display (5x5) |
|
||
| 1A | pointer to display memory |
|
||
| 1B | keypad: value of latest key pressed |
|
||
| 1C | reserved for future use (bank switching flag) |
|
||
| 1D | initial IP |
|
||
| 1D to FE | free |
|
||
| FF | * ROM (unwriteable) pointer to initial IP |
|
||
|
||
\* Not implemented yet
|
||
|
||
|
||
## Cardiograph peripherals
|
||
|
||
### Keypad
|
||
|
||
The value of the latest keypress on a hex keypad is stored at `$1B`.
|
||
|
||
The keypad uses the same layout as the COSMAC VIP (and CHIP-8). The CPU simulator maps those keys onto a Qwerty set:
|
||
|
||
`1` `2` `3` `C` = `1` `2` `3` `4`
|
||
`4` `5` `6` `D` = `Q` `W` `E` `R`
|
||
`7` `8` `9` `E` = `A` `S` `D` `F`
|
||
`A` `0` `B` `F` = `Z` `X` `C` `V`
|
||
|
||
The arrow keys are also mapped onto the hex keypad:
|
||
|
||
` ` `5` ` ` = ` ` `↑` ` `
|
||
`7` `8` `9` = `←` `↓` `→` |