From 5671314b106e4fec52293b48d106f7206bef5e4a Mon Sep 17 00:00:00 2001
From: n loewen <nick@nloewen.com>
Date: Tue, 29 Aug 2023 09:26:09 -0400
Subject: [PATCH] (docs) readme - Add intro + re-arrange, to clarify
 relationship between Cardiograph and its constituent parts

---
 readme.md | 105 +++++++++++++++++++++++++++++-------------------------
 1 file changed, 56 insertions(+), 49 deletions(-)

diff --git a/readme.md b/readme.md
index 3c02095..f0555c9 100644
--- a/readme.md
+++ b/readme.md
@@ -1,24 +1,32 @@
 # Cardiograph Mark I — simulator for an imaginary computer
 
-## Dependencies
+Cardiograph is an imaginary computer. It has three main components:
 
-- Node.js
+1. the CPU, *Card* (short for 'Completely Analogue Risc Machine')
+2. an input-output processor, *IO*
+3. a display, *Graph*
 
-## Run
+## Simulator
 
-### Assembler
+### Run assembler
 
 ```./assembler.js source_code.asm [output.txt]```
 
 By default, the output is written to `out.txt`. It is saved as a string of space-separated decimal numbers.
 
 
-### Simulator
+### Run simulator
 
 ```./cardiograph.js < machine_code.txt```
 
+### Dependencies
 
-## Registers and Flags
+- Node.js
+
+
+## CPU
+
+### Registers and Flags
 
 - `A` - accumulator
 - `IP` - instruction pointer (aka program counter)
@@ -31,9 +39,9 @@ By default, the output is written to `out.txt`. It is saved as a string of space
     - (bitwise, `0000 = ONZC`)
 
 
-## Instruction set
+### Instruction set
 
-### Operations 
+#### Operations 
 
 ```
 Hex   Mnem.  Operand      Effect
@@ -60,7 +68,7 @@ Hex   Mnem.  Operand      Effect
   one byte for the opcode, one for the operand    
 
 
-### Effects on memory, flags, registers
+#### Effects on memory, flags, registers
 
 ```
 op   mem  flags  IP
@@ -87,50 +95,13 @@ FTG  r    ONZC   +2
 FHP  r    ONZC   +2/+4
 ```
 
-
-## CPU start-up
+### Start-up
 
 When starting up, the CPU executes a `JMP $FF`.
 
 Put differently: it starts executing instructions at the address contained in `$FF`.
 
-## Cardiograph memory map
-
-- `00-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-FE` - free
-- `FF   ` - ROM (unwriteable) pointer to initial IP (not yet implemented)
-
-## 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
-
-hex pad    simulator
-```
-
-The arrow keys are also mapped onto the hex keypad:
-
-```
-   5           ↑
- 7 8 9       ← ↓ →
-
-hex pad    simulator
-```
-
-## Assembly language
+### Assembly language
 
     ADD $01         ; comments follow a `;`
 
@@ -157,4 +128,40 @@ hex pad    simulator
                     ; where the current line will be stored after assembly
 
 - Hexadecimal numbers are preceded by a `$`
-- Whitespace is ignored
\ No newline at end of file
+- Whitespace is ignored
+
+## Cardiograph memory map
+
+- `00-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-FE` - free
+- `FF   ` - ROM (unwriteable) pointer to initial IP (not yet implemented)
+
+## 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
+
+hex pad    simulator
+```
+
+The arrow keys are also mapped onto the hex keypad:
+
+```
+   5           ↑
+ 7 8 9       ← ↓ →
+
+hex pad    simulator
+```
\ No newline at end of file