readme/notes - finish WIP - Change instruction set back to the original, but keep the improvements to the documentation

notes/2023-08-23--dev-notes.md

@@ -8,6 +8,8 @@ Do I want to do this??
 
 Or maybe go with the simpler "just swap NOP and FHP" plan...
 
+**→ Ok i'm going to bail on this for now; the current set is easier to work with and nicer to teach. It was good to learn about and think about this, and maybe it will come back later, but for now it feels like adding this complexity would be contrary to my goals of maximum simplicity and rapid learnability.**
+
 ## Instruction set layout notes
 
 ### Reference: 6502
@@ -167,6 +169,6 @@ hex   bin          group  mode      op
 67    0110 0111    1      indirect  FHP
 ```
 
-**let's do that!**
+~~**let's do that!**~~
 
 (but for now i'm going to skip indirect FTG and FHP out of laziness)

readme.md

@@ -48,57 +48,77 @@ With single stepping + verbose debugging output:
 
 ## Instruction set
 
-### Operations
+### Operations 
 
 ```
-Hex  Mnem.  Name         Operand type  Effect
----------------------------------------------
-
-00   END    End          (ignored)     Halt CPU
-01   NOP    No op        (ignored)     None
-
-50   STO    Store        literal #     mem[lit#] = A
-51   LDA    Load         literal #     A = lit#
-52   ADD    Add          literal #     A = A + lit#
-53   SUB    Sub          literal #     A = A - lit#
-54   HOP    Hop          literal #     If A == lit#, skip next op (IP += 4)
-55   JMP    Jump         literal #     IP = lit#
-56   FTG    Flag toggle  literal #     Toggle flag, where flag number == lit#
-57   FHP    Flag hop     literal #     Skip next op if flag is set, where flag number == lit#
-
-60   STO    Store        address       mem[mem[addr]] = A
-61   LDA    Load         address       A = addr
-62   ADD    Add          address       A = A + mem[addr]
-63   SUB    Sub          address       A = A - mem[addr]
-64   HOP    Hop          address       If A == mem[addr], skip next instruction (IP += 4)
-65   JMP    Jump         address       IP = mem[addr]
+00   END
+01   STO lit#   ; store ... mem[lit#] <- A
+02   STO addr   ; store ... mem[mem[addr]] <- A
+03   LDA lit#   ; load  ... A <- lit#
+04   LDA addr   ; load  ... A <- mem[addr]
+05   ADD lit#   ; add   ... A <- A + lit#      ... and un/set carry flag
+06   ADD addr   ; add   ... A <- A + mem[addr] ... and un/set carry flag
+07   SUB lit#   ; sub   ... A <- A - lit#      ... and un/set carry flag
+08   SUB addr   ; sub   ... A <- A - mem[addr] ... and un/set carry flag
+09   HOP lit#   ; hop   ... skip next instruction if A == lit# ... when true: IP <- PC + 4
+0A   HOP addr   ; hop   ... skip next instruction if A == addr ... when true: IP <- PC + 4
+0B   JMP lit#   ; jump  ... IP <- lit#
+0C   JMP addr   ; jump  ... IP <- addr
+0D   FTG lit#   ; toggle flag by number (see details below)
+0E   FHP lit#   ; flag hop ... skip next instruction if flag is set ... when true: IP <- PC + 4
+0F   NOP ————   ; no operation
 ```
 
-### Map + effects on flags, registers
+- Instructions are two bytes long:
+  one byte for the opcode, one for the operand    
+
 
 ```
-hex   bin          group  mode      op   mem  flags  IP
--------------------------------------------------------
-00    0000 0000    0      --        END              +2
-01    0000 0001    0      --        NOP              +2
+Hex   Mnem.  Operand      Effect
 
-50    0101 0000    1      direct    STO  w           +2
-51    0101 0001    1      direct    LDA  r    NZ     +2
-52    0101 0010    1      direct    ADD       NZOC   +2
-53    0101 0011    1      direct    SUB       NZOC   +2
-54    0101 0100    1      direct    HOP              +2/+4
-55    0101 0101    1      direct    JMP              arg
-56    0101 0110    1      direct    FTG       NZOC   +2
-57    0101 0111    1      direct    FHP       NZOC   +2/+4
+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
+```
 
-60    0110 0000    1      indirect  STO  r,w         +2
-61    0110 0001    1      indirect  LDA  r,r  NZ     +2
-62    0110 0010    1      indirect  ADD  r    NZOC   +2
-63    0110 0011    1      indirect  SUB  r    NZOC   +2
-64    0110 0100    1      indirect  HOP  r           +2/+4
-65    0110 0101    1      indirect  JMP  r           arg
-66    0110 0110    1      indirect  FTG  r    NZOC   +2
-67    0110 0111    1      indirect  FHP  r    NZOC   +2/+4
+### Effects on memory, flags, registers
+
+```
+op   mem  flags  IP
+
+END              +2
+NOP              +2
+
+STO  w           +2
+LDA  r    NZ     +2
+ADD       NZOC   +2
+SUB       NZOC   +2
+HOP              +2/+4
+JMP              arg
+FTG       NZOC   +2
+FHP       NZOC   +2/+4
+
+STO  r,w         +2
+LDA  r,r  NZ     +2
+ADD  r    NZOC   +2
+SUB  r    NZOC   +2
+HOP  r           +2/+4
+JMP  r           arg
+FTG  r    NZOC   +2
+FHP  r    NZOC   +2/+4
 ```