From ddce9abba14eeaa1d853fe30749dbaaa49d73d21 Mon Sep 17 00:00:00 2001
From: CrazyEttin <>
Date: Sun, 24 Jul 2022 22:47:37 +0300
Subject: [PATCH] Add information on the initial program loader to the readme,
 reorganise and otherwise clarify the readme, and change instruction pointer
 to byte pointer in the disassembler

---
 disassembler.pas | 44 ++++++++++++++++++++++----------------------
 readme.md        | 34 +++++++++++++++++++++-------------
 2 files changed, 43 insertions(+), 35 deletions(-)

diff --git a/disassembler.pas b/disassembler.pas
index 9b1a76c..eabb3cd 100644
--- a/disassembler.pas
+++ b/disassembler.pas
@@ -5,7 +5,7 @@ uses Crt, Sysutils;
 var
     Op, Regs: 0 .. $f; //Opcode, and register arguments in a single variable
     X, Y: 0 .. 3; //Register arguments in separate variables
-    Addr, IP, EP: word; //Address argument and instruction and end pointers
+    Addr, BP, EP: word; //Address argument and byte and end pointers
     Opcodes: array [0 .. $f] of string; //Opcodes in human readable form
     Bin: array [0 .. $ffef] of byte; //Program in binary form
     Prog: file of byte; //Program file
@@ -30,8 +30,8 @@ begin
     Opcodes [$e] := 'CLEQ    ';
     Opcodes [$f] := 'CLNEQ   ';
 
-    //Initialise the instruction pointer
-    IP := 0;
+    //Initialise the byte pointer
+    BP := 0;
 
     //Read a program file and check for errors
     if ParamCount <> 1 then begin
@@ -47,38 +47,38 @@ begin
         exit;
     end;
     repeat
-        read (Prog, Bin [IP]);
-        IP := IP + 1;
-    until (eof (Prog)) or (IP = $fff0);
+        read (Prog, Bin [BP]);
+        BP := BP + 1;
+    until (eof (Prog)) or (BP = $fff0);
 
     //Save the end point and reinitialise the instruction pointer
-    EP := IP;
-    IP := 0;
+    EP := BP;
+    BP := 0;
 
     //Begin the main loop
     repeat
 
         //Print the memory location
-        if IP < $1000 then write (' ');
-        if IP < $100 then write (' ');
-        if IP < $10 then write (' ');
-        write (IntToHex (IP, 1), '    ');
+        if BP < $1000 then write (' ');
+        if BP < $100 then write (' ');
+        if BP < $10 then write (' ');
+        write (IntToHex (BP, 1), '    ');
 
         //Fetch the instruction and increment the instruction pointer
         //Opcode
-        Op := Bin [IP] and $f0 shr 4;
+        Op := Bin [BP] and $f0 shr 4;
         //Register arguments
-        Regs := Bin [IP] and $f;
-        X := Bin [IP] and $c shr 2;
-        Y := Bin [IP] and 3;
-        IP := IP + 1;
+        Regs := Bin [BP] and $f;
+        X := Bin [BP] and $c shr 2;
+        Y := Bin [BP] and 3;
+        BP := BP + 1;
         //Address argument
         if Op >= $a then begin
-            Addr := Bin [IP];
+            Addr := Bin [BP];
             Addr := Addr shl 8;
-            IP := IP + 1;
-            Addr := Addr + Bin [IP];
-            IP := IP - 1;
+            BP := BP + 1;
+            Addr := Addr + Bin [BP];
+            BP := BP - 1;
         end;
 
         //Print the data
@@ -100,6 +100,6 @@ begin
 
 
 
-    until (IP >= EP);
+    until (BP >= EP);
 
 end.
diff --git a/readme.md b/readme.md
index 943b9b2..2ee6e76 100644
--- a/readme.md
+++ b/readme.md
@@ -1,8 +1,8 @@
 Thingamajig
 ===========
 
-Thingamajig is a RISC-y and MISC-y hobbyist instruction set
-architecture. Its git repository can be found at
+Thingamajig is a RISC-y and MISC-y hobbyist computer architecture. Its
+git repository can be found at
 https://ahti.space/git/crazyettin/Thingamajig.
 
 Registers and Memory
@@ -15,17 +15,9 @@ Registers and Memory
 
 Multi-byte values are big-endian. Memory addresses FFF0-FFFF are
 reserved for memory mapped devices. The instruction and return pointers
-should not have values higher than FFEF and FFF0 respectively to avoid
-the reserved addresses. The instruction and return pointers are
-initialised as 0 and FFF0 respectively; other registers and memory are
-unitialised.
-
-Memory-Mapped Devices
----------------------
-
-Input (when read from) and output (when written to) are mapped to
-address FFFF. Arbitrary devices can be mapped to the other reserved
-addresses.
+cannot have values higher than FFEF and FFF0 respectively to avoid the
+reserved addresses. The instruction and return pointers are initialised
+as 0 and FFF0 respectively; other registers and memory are unitialised.
 
 Instructions
 ------------
@@ -56,3 +48,19 @@ C   BREQ    RX, RY, ADDR   if (RX == RY) IP = ADDR
 D   BRNEQ   RX, RY, ADDR   if (RX != RY) IP = ADDR
 E   CLEQ    RX, RY, ADDR   if (RX == RY) {RP -= 1; *RP = IP; IP = ADDR}
 F   CLNEQ   RX, RY, ADDR   if (RX != RY) {RP -= 1; *RP = IP; IP = ADDR}
+
+Memory-Mapped Devices
+---------------------
+
+Input (when read from) and output (when written to) are mapped to
+address FFFF. The emulator implements this by emulating a dumb serial
+terminal.
+
+Arbitrary devices can be mapped to the other reserved addresses.
+
+Initial Program Loader
+----------------------
+
+At boot the initial program loader loads a program to the memory
+starting from address 0 after which is cedes control to the processor.
+The emulator loads the program from a file.