Commit very old modifications to architecture spec

.gitmodules

@@ -1,3 +1,3 @@
 [submodule "src/argparser"]
-	path = src/opter
+	path = micro/opter
 	url = https://git.nloewen.com/n/argv-parser.git

docs/architecture-specification.md

@@ -0,0 +1,110 @@
+# [DRAFT] Specification for the _Cardiograph Architecture_
+
+## CPU
+
+### Registers
+
+There are four 8-bit registers:
+
+1. **A**, the accumulator (and the only general-purpose register)
+2. **H**, an index register for 16-bit addressing
+3. **IP**, the instruction pointer (aka program counter)
+4. **IOD**, the ID of the current I/O device
+5. **Status**
+
+#### Status register
+
+The *high byte* holds the state of the four Sense Switches. (TODO: is this easy enough to do in hardware?)
+
+The *low byte* holds four flags:  
+
+- IO **E**rror
+- **N**egative
+- **Z**ero
+- **C**arry
+
+These are all addressed by number:*
+
+| S1 | S2 | S3 | S4 | |  E |  N |  Z |  C |
+|----|----|----|----|-|----|----|----|----|
+| 80 | 40 | 20 | 10 | | 08 | 04 | 02 | 01 |
+
+\* (Because the core instruction set doesn't include bitwise operations)
+
+### Instruction set
+
+- Instructions are two bytes long:
+  one byte for the opcode, one for the operand
+
+- Opcode format is ```GGMM OOOO``` — **G**roup, **M**ode, **O**peration
+
+|       | 0       | 1       | 2       | 3       | 4       | 5       | 6       | 7       | | 8         | 9         | A         | B         | C         | D         | E        | F         |
+|-------|---------|---------|---------|---------|---------|---------|---------|---------|-|-----------|-----------|-----------|-----------|-----------|-----------|----------|-----------|
+| **0** | NOP     | HLT     |         |         |         |         |         |         | |           |           |           |           |           |           |          |           |
+| **5** | LDA #   | STA #   | ADD #   | SUB #   | JMP #   | SEQ #   | SFL #   | TGF #   | | _MUL #_   | _DIV #_   | _SLT #_   | _SGT #_   | _NOT #_   | _AND #_   | _OR #_   | _XOR #_   |
+| **6** | LDA ind | STA ind | ADD ind | SUB ind | JMP ind | SEQ ind | SFL ind | TGF ind | | _MUL ind_ | _DIV ind_ | _SLT ind_ | _SGT ind_ | _NOT ind_ | _AND ind_ | _OR ind_ | _XOR ind_ |
+| **9** | DEV #   | INP #   | OUT #   | NXT     |         |         |         |         | |           |           |           |           |           |           |          |           |
+| **A** | DEV ind | INP ind | OUT ind | NXT     |         |         |         |         | |           |           |           |           |           |           |          |           |
+| **F** | _RSL A_ | _RSR A_ | _ASL A_ | _ASR A_ |         |         |         |         | |           |           |           |           |           |           |          |           |
+
+<mark>LDH, LDH, STH, STH</mark>
+
+Operations in italics are extensions to the core set of operations.
+
+High byte reference:
+
+| g, m | bin  | hex |
+|------|------|-----|
+| 0, 0 | 0000 | 0   |
+| 1, 1 | 0101 | 5   |
+| 1, 2 | 0110 | 6   |
+| 2, 1 | 1001 | 9   |
+| 2, 2 | 1010 | A   |
+| 3, 3 | 1111 | F   |
+
+Brief legend for mnemonics:
+
+- RSL/RSR: Ring Shift Left/Right
+- HLT/HGT: Jump Less/Greater Than
+- DEV: select IO device
+- NXT: "next" - move to next line / card
+
+TODO: format/document better:
+
+1. core computational operations: low nibbles of 0x, 5x, 6x
+2. arithmetic extension (optional): MUL, DIV
+3. IO extension (optional): 9x, Ax
+4. bitwise arithmetic extension (optional): NOT, AND, OR, XOR and RSL, RSR, ASL, ASR
+5. control flow extension (optional): JLT, JGT
+
+- The mainframe system implements at least 1, 2, and 3
+- The microprocessor trainer implements 1
+- (see note dated 2023-09-24)
+
+
+### Connections (pinout)
+
+<mark>TBC</mark>
+
+| name      | in/out? | description   |
+|-----------|---------|---------------|
+| RST       | in      | *reset*       |
+| VCC       | in      | *power*       |
+| GND       | in      | *ground*      |
+| CLK       | in      | *clock*       |
+| A0 - A7   | out     | *address bus* |
+| D0 - D7   | out     | *data bus*    |
+| ABE       | out     | *address bus enable*: <br> low when the CPU is using the address bus |
+| DBE       | out     | *data bus enable*: <br> low when the CPU is using the data bus |
+| WAIT      | in      | *wait* — when pulled low, <br> the current operation is completed <br> and then execution pauses |
+| /RD       | out     | TODO |
+| /WR       | out     | |
+| M/IO      | out     | |
+
+
+### Start/Reset behaviour
+
+When starting up, the CPU reads the program counter from $FF.  
+(Effectively executing a `JMP $FF`.)
+
+<mark>TODO: currently the simulator doesn't actually do this</mark>

docs/assembly-language.md

@@ -0,0 +1,31 @@
+# Assembly language
+
+## Syntax
+
+    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

docs/mainframe-design.md

@@ -0,0 +1,105 @@
+## [DRAFT] Design of the _Cardiograph Mark I_ mainframe computer
+
+The components of a Mark I are:
+
+- a CG 101 Central Processing Unit
+- a CG 102 Core Memory Unit
+- a CG 103 Print-Key-Punch
+- a CG 104 Matrix Display
+
+### Operator console
+
+<mark>TBC TBC TBC</mark>
+
+## Basic controls
+
+- Power
+- Load
+- Run
+- Halt
+- 4 Sense Switches
+
+## Status lights
+
+- 8 Accumulator lights
+- 8 Address lights
+- 8 Data lights
+- 8 Instruction Pointer lights (<mark>review IP size?</mark>)
+- 8 Status Register lights
+
+## Debugging controls
+
+- Run Single Step
+- Memory Read
+- Memory Read Next
+- Memory Write
+- Memory Write Next
+
+## IO programming
+
+Only one input or output device can be accessed at a time.
+
+### Reading data
+
+1. Use `DEV xx` to select input device _xx_
+2. Use `INP yy` to read one byte into memory at address _yy_
+
+<mark>TODO: find a way to allow the input device to refuse to provide input</mark>
+
+### Writing data
+
+1. Use `DEV xx` to select output device _xx_
+2. Use `OUT yy` to write one byte from memory at address _yy_
+3. Use `NXT xx` to...
+  - card punch: load a new card
+  - printer: begin a new line (CR, LF)
+  - display: begin a new line
+
+### Punched card format
+
+FIXME:
+- ~~Cards are punched in EBCDIC~~
+- ~~EBCDIC data is translated into binary by the card reader/punch~~
+- Only columns 1-64 are used (for a maximum of 64 bytes of data per card)
+
+### Printer format
+
+- The printer format is the same as the card format
+- One line of printing is equivalent to one card
+- The printer can print up to 64 characters per line
+
+### Matrix display format
+
+- The display is a 5x5 grid of lights
+- Each light has 16 possible brightness levels (0 = off, 15 = maximum)
+- The display is written one line at a time
+- After the display is selected with `DEV`, writing begins on the top line
+- Writing wraps around and begins at the top again, if more than 5 lines are written
+
+### Device numbers
+
+1. card reader / typewriter
+2. card punch / line printer
+3. display
+
+### Print-Key-Punch configurations
+
+A dial allows you to select which input device to connect to the CPU:
+
+1. none
+2. card reader
+3. keyboard
+
+A similar dial selects the output device to connect:
+
+1. none
+2. card punch
+3. printer
+
+Thus, this all-in-one device allows the following configurations:
+
+|                 | printer              | card punch       | none                     |
+|-----------------|----------------------|------------------|--------------------------|
+| **keyboard**    | ***teletypewriter*** | ***auto punch*** | ***keypunch (offline)*** |
+| **card reader** | (keys + print)       | card duplicator  | (card reader)            |
+| **none**        | line printer         | (auto punch)     | (scrap metal)            |

docs/micro-design.md

@@ -0,0 +1,40 @@
+# [DRAFT] Design for the _MicroCardiograph_ microprocessor trainer
+
+The MicroCardiograph uses memory-mapped IO.
+
+## 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
+
+
+## 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`   =   `←` `↓` `→`
+
+### Keypad as monitor input
+
+TODO

readme.md

@@ -1,210 +1,39 @@
-# Cardiograph Mark I — simulator for an imaginary computer
+# Cardiograph computers
 
-Cardiograph is an imaginary computer. It has three main components:
+The Cardiographs are a pair of imaginary computers,
+designed as educational toys.
 
-1. the CPU, *Card* (short for 'Completely Analogue Risc Machine')
+Inspired by the CARDIAC paper computer,
-2. an input-output processor, *IO*
+they are intended to be simple enough to build as
-3. a display, *Graph*
+hand-operated paper models.
+
+Their design is guided by two additional criteria:
+
+1. They should be capable of producing interesting graphical output
+2. They should accurately model the functioning of a real computer
+   (by operating on binary data, for example)
+
+## The two computers
+
+The two Cardiograph computers are:
+
+1. the _Cardiograph Mark I_ (CG) is a mainframe machine
+2. the _Micro Cardiograph_ (µCG) is a microprocessor trainer
+   (a miniaturized descendent of the mainframe)
+
+They use the same instruction set and have very similar CPUs. (TODO: is that true?)
+
+The main difference is in their peripheral hardware:
+the Mark I is designed for batch processing and supports punched-card input,
+while the MicroCardiograph is designed to be used interactively.
 
 ## Simulator
 
-### Dependencies
+_[Micro ElectroCardiograph (µECG)](micro/readme-micro.md)_ is a simulator for the Micro Cardiograph.
-Cardiograph is an imaginary computer. It has three main components:
 
-1. the CPU, *Card* (short for 'Completely Analogue Risc Machine')
+## Documentation
-2. an input-output processor, *IO*
-3. a display, *Graph*
 
-## Simulator
+- [Specification for the Cardiograph Architecture](docs/architecture-specification.md)
-
+- [Design for the mainframe computer](docs/mainframe-design.md)
-### Dependencies
+- [Design for the micro computer](docs/micro-design.md)
-
+- [Assembly Language](docs/assembly-language.md)
-- 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`   =   `←` `↓` `→`

simulator/readme-micro.md

@@ -0,0 +1,41 @@
+### 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

src/opter

@@ -1 +0,0 @@
-Subproject commit 1d98a0707c3e61e362d2d3d5413b475437b5de0e