Add memory maps

dictionary.txt

@@ -89,6 +89,8 @@ I'          -- n            Copy RS second item to PS
 J           -- n            Copy RS third item to PS
 
 *** Memory ***
+(mmap*)     -- a            Address of active memory mapper. 0 for none. See
+                            "Memory maps" in notes.txt.
 @           a -- n          Set n to value at address a
 !           n a --          Store n in address a
 ?           a --            Print value of addr a

forth/icore.fs

@@ -67,6 +67,23 @@
 : (parse*) 0x0a _c RAM+ ;
 : HERE 0x04 _c RAM+ ;
 : CURRENT 0x02 _c RAM+ ;
+: (mmap*) 0x51 _c RAM+ ;
+
+( The goal here is to be as fast as possible *when there is
+  no mmap*, which is the most frequent situation. That is why
+  we don't DUP and we rather refetch. That is also why we
+  use direct literal instead of RAM+ or (mmap*). )
+: (mmap)
+    [ RAMSTART 0x51 + LITN ] _c _@
+    IF
+        [ RAMSTART 0x51 + LITN ] _c _@ EXECUTE
+    THEN
+;
+
+: @ _c (mmap) _c _@ ;
+: C@ _c (mmap) _c _C@ ;
+: ! _c (mmap) _c _! ;
+: C! _c (mmap) _c _C! ;
 
 : QUIT
     0 _c FLAGS _c ! _c (resRS)
@@ -204,6 +221,7 @@
 ;
 
 : BOOT
+    0 0x51 _c RAM+ _c _!
     LIT< (parse) _c (find) _c DROP _c (parse*) _c !
     ( 60 == SYSTEM SCRATCHPAD )
     _c CURRENT _c @ 0x60 _c RAM+ _c !
@@ -233,7 +251,7 @@
     ( We cannot use LITN as IMMEDIATE because of bootstrapping
       issues. Same thing for ",".
       32 == NUMBER 14 == compiledWord )
-    [ 32 H@ ! 2 ALLOT 14 H@ ! 2 ALLOT ] _c ,
+    [ 32 H@ _! 2 ALLOT 14 H@ _! 2 ALLOT ] _c ,
     BEGIN
     _c WORD
     _c (find)
@@ -250,10 +268,10 @@
 ;
 
 ( Give ":" and ";" their real name and make them IMMEDIATE )
-0x81 ' X 1 - C!
+0x81 ' X 1 - _C!
-':' ' X 4 - C!
+':' ' X 4 - _C!
-0x81 ' Y 1 - C!
+0x81 ' Y 1 - _C!
-';' ' Y 4 - C!
+';' ' Y 4 - _C!
 
 ( Add dummy entry. we use CREATE because (entry) is, at this
   point, broken. Adjust H@ durint port 2 ping. )

forth/z80c.fs

@@ -232,7 +232,7 @@ L2 FSET ( skip )
     BC PUSHqq,
 ;CODE
 
-CODE !
+CODE _!
     HL POPqq,
     DE POPqq,
     chkPS,
@@ -241,7 +241,7 @@ CODE !
     (HL) D LDrr,
 ;CODE
 
-CODE @
+CODE _@
     HL POPqq,
     chkPS,
     E (HL) LDrr,
@@ -250,14 +250,14 @@ CODE @
     DE PUSHqq,
 ;CODE
 
-CODE C!
+CODE _C!
     HL POPqq,
     DE POPqq,
     chkPS,
     (HL) E LDrr,
 ;CODE
 
-CODE C@
+CODE _C@
     HL POPqq,
     chkPS,
     L (HL) LDrr,

notes.txt

@@ -88,7 +88,8 @@ RAMSTART   INITIAL_SP
 +0e        WORDBUF
 +2e        SYSVNXT
 +4e        INTJUMP
-+51        RESERVED
++51        MMAPPTR
++53        RESERVED
 +60        SYSTEM SCRATCHPAD
 +80        RAMEND
 
@@ -116,6 +117,9 @@ those slots...) in boot binaries are made to jump to this address. If you use
 one of those slots for an interrupt, write a jump to the appropriate offset in
 that RAM location.
 
+MMAPPTR: Address behind (mmap), which is called before every !/C!/@/C@ world
+to give the opportunity to change the address of the call.
+
 SYSTEM SCRATCHPAD is reserved for temporary system storage or can be reserved
 by low-level drivers. These are the current usages of this space throughout the
 project:
@@ -154,3 +158,29 @@ can't have comments. This leads to peculiar code in this area. If you see weird
 whitespace usage, it's probably because not using those whitespace would result
 in dict entry creation overwriting the code before it has the chance to be
 interpreted.
+
+*** Memory maps
+
+We have a mechanism to map memory ranges to something else. We call this memory
+maps. There is a reserved address in memory for a memory mapping routine. The
+word (mmap*) returns that address. By default, it's zero which means no mapping.
+
+Each call to @, C@, ! or C! call that word, if nonzero, before executing. This
+allows you to do pretty much anything. Try to be efficient in your programming,
+however, because those words are called *very* often.
+
+Here's a toy example of memory map usage:
+
+> 8 0x8000 DUMP
+:00 0000 0000 0000 0000 ........
+> : foo DUP 0x8000 = IF 2 + THEN ;
+> ' foo (mmap*) !
+> 8 0x8000 DUMP
+:00 0000 0000 0000 0000 ........
+> 0x1234 0x8000 !
+> 8 0x8000 DUMP
+:00 3412 3412 0000 0000 4.4.....
+> 0 (mmap*) !
+> 8 0x8000 DUMP
+:00 0000 3412 0000 0000 ..4.....
+>