From 76e442279670a928d4804bc945888cfbb252b1c0 Mon Sep 17 00:00:00 2001
From: Virgil Dupras <hsoft@hardcoded.net>
Date: Sun, 12 Apr 2020 21:49:20 -0400
Subject: [PATCH] Add adev unit

---
 dictionary.txt | 14 ++++++++++++--
 forth/adev.fs  | 34 ++++++++++++++++++++++++++++++++++
 notes.txt      |  3 ++-
 usage.txt      | 36 ++++++++++++++++++++++++++++++++++++
 4 files changed, 84 insertions(+), 3 deletions(-)
 create mode 100644 forth/adev.fs

diff --git a/dictionary.txt b/dictionary.txt
index 0fd5186..c06a6a2 100644
--- a/dictionary.txt
+++ b/dictionary.txt
@@ -30,10 +30,10 @@ to been consistent in their use. Here's their definitions:
 @ - Fetch
 $ - Initialize
 ^ - Arguments in their opposite order
-> - Pointer in a buffer
+< - Input
+> - 1. Pointer in a buffer 2. Opposite of "<".
 ( - Lower boundary
 ) - Upper boundary
-< - Input
 * - Word indirection (pointer to word)
 ~ - Container for native code. Usually not an executable word.
 ? - Is it ...? (example: IMMED?)
@@ -122,6 +122,16 @@ HERE        -- a            Push HERE's address
 H@          -- a            HERE @
 MOVE        a1 a2 u --      Copy u bytes from a1 to a2, starting with a1, going
                             up.
+*** Addressed devices ***
+
+See usage.txt for details.
+
+ADEV$       --              Initialize adev subsystem
+A@          a -- c          Indirect C@
+A!          c a --          Indirect C!
+A@*         -- a            Address for A@ word
+A!*         -- a            Address for A! word
+AMOVE       src dst u --    Same as MOVE, but with A@ and A!
 
 *** Arithmetic / Bits ***
 
diff --git a/forth/adev.fs b/forth/adev.fs
new file mode 100644
index 0000000..80eff47
--- /dev/null
+++ b/forth/adev.fs
@@ -0,0 +1,34 @@
+( Addressed devices.
+
+Abstractions to read and write to devices that allow addressed
+access. At all times, we have one active "fetch" device and
+one active "store" device, A@ and A!.
+
+Those words have the same signature as C@ and C!, and in fact,
+initially default to proxy of those words.
+)
+
+: ADEVMEM+ 0x55 RAM+ @ + ;
+: A@* 0 ADEVMEM+ ;
+: A!* 2 ADEVMEM+ ;
+
+: ADEV$
+    H@ 0x55 RAM+ !
+    4 ALLOT
+    ['] C@ A@* !
+    ['] C! A!* !
+;
+
+: A@ A@* @ EXECUTE ;
+: A! A!* @ EXECUTE ;
+
+( Same as MOVE, but with A@ and A! )
+( src dst u -- )
+: AMOVE
+    ( u ) 0 DO
+        SWAP DUP I + A@   ( dst src x )
+        ROT SWAP OVER I + ( src dst x dst )
+        A!                ( src dst )
+    LOOP
+    2DROP
+;
diff --git a/notes.txt b/notes.txt
index b8201b6..49041f5 100644
--- a/notes.txt
+++ b/notes.txt
@@ -90,7 +90,8 @@ RAMSTART   INITIAL_SP
 +4e        INTJUMP
 +51        CURRENTPTR
 +53        readln's variables
-+55        FUTURE USES
++55        adev's variables
++57        FUTURE USES
 +59        z80a's variables
 +5b        FUTURE USES
 +70        DRIVERS
diff --git a/usage.txt b/usage.txt
index 6c76228..8a2c434 100644
--- a/usage.txt
+++ b/usage.txt
@@ -86,3 +86,39 @@ flag to true. For example, "<>{ <>}" yields true.
 To check whether A is in between B and C inclusively, you would write:
 
 A <>{ B 1 - &> C 1 + &< <>}
+
+*** Addressed devices
+
+The adev unit provides a simple but powerful abstraction over C@ and C!: A@ and
+A!. These work the same way as C@ and C! (but for performance reasons, aren't
+used in core words), but are indirect calls.
+
+Upon initialization, the default to C@ and C!, but can be set to any word
+through A@* and A!*.
+
+On top of that, it provides a few core-like words such as AMOVE.
+
+Let's demonstrate its use through a toy example:
+
+    > : F! SWAP 1 + SWAP C! ;
+    > 8 H@ DUMP
+
+    :54 0000 0000 0000 0000 ........
+    > 9 H@ A!
+    > 8 H@ DUMP
+
+    :54 0900 0000 0000 0000 ........
+    > ' F! A!* !
+    > 9 H@ 1 + A!
+    > 8 H@ DUMP
+
+    :54 090a 0000 0000 0000 ........
+    > H@ H@ 2 + 2 AMOVE
+    > 8 H@ DUMP
+
+    :54 090a 0a0b 0000 0000 ........
+    > 
+
+Of course, you might want to end up using adev in this kind of ad-hoc way to
+have some kind of mapping function, but what you'll mostly want to to is to
+plug device drivers into those words.