Rename Inner core to Cross-compiled core

And refreshed description.

blk/000

@@ -1,16 +1,16 @@
-Collapse OS file system
+Collapse OS
 
-This is a Forth-style filesystems which is very simple. It is a
-list of 1024 bytes block, organised in 16 lines of 64 columns
-each. You refer to blocks by numbers. You show them with LIST.
-You interpret them with LOAD. For a convenient way to browse
-blocks, see Block editor at B100.
+This is the first block of Collapse OS' filesystem which cons-
+ists of contiguous blocks of 1024 bytes organized in 16 lines
+of 64 characters. You can display a block's content with the
+"LIST" command. For example, "123 LIST" shows the contents of
+the block 123. If a block contains source code, you can inter-
+pret it with "LOAD".
 
 Conventions: When you see "(cont.)" at the bottom right of a
 block, it means that the next block continues the same kind of
-contents. This of course only work for informational text.
+contents. Block numbers are abbreviated with prefix "B". "BX"
+means "block X".
 
-Block numbers are abbreviated with prefix "B". "BX" means
-"block X".
-
-The master index of this filesystem is at B1.
+The master index of this filesystem is at B1. The Block editor
+at B100 is a convenient way to navigate blocks.

blk/001

@@ -6,7 +6,7 @@ MASTER INDEX
 150 Extra words
 200 Z80 assembler             260 Cross compilation
 280 Z80 boot code             350 ACIA driver
-370 SD Card driver            390 Inner core
+370 SD Card driver            390 Cross-compiled core
 420 Core words                480 AT28 Driver
 490 TRS-80 Recipe             520 Fonts
 550 TI-84+ Recipe

blk/076

@@ -1,6 +1,6 @@
 STACK OVERFLOW PROTECTION: To avoid having to check for stack
 underflow after each pop operation (which can end up being
-prohibitive in terms of costs), we give ourselves a nice 6
-bytes buffer. 6 bytes because we seldom have words requiring
-more than 3 items from the stack. Then, at each "exit" call we
-check for stack underflow.
+prohibitive in terms of costs), PS_ADDR should be set to
+at least 6 bytes before its actual limit. 6 bytes because we
+seldom have words requiring more than 3 items from the stack.
+Then, at each "exit" call we check for stack underflow.

blk/081

@@ -1,5 +1,4 @@
-(cont.)
-RAMSTART  INITIAL_SP           +55       (key) override
+RAMSTART  FUTURE USES          +55       (key) override
 +02       CURRENT              +57       readln's variables
 +04       HERE                 +59       blk's variables
 +06       C<?                  +5b       z80a's variables
@@ -13,4 +12,5 @@ RAMSTART  INITIAL_SP           +55       (key) override
 +53       (emit) override
 
 
+
                                                         (cont.)

blk/082

@@ -1,6 +1,3 @@
-INITIAL_SP holds the initial Stack Pointer value so
-that we know where to reset it on ABORT
-
 CURRENT points to the last dict entry.
 
 HERE points to current write offset.
@@ -13,4 +10,7 @@ C<* holds routine address called on C<. If the C<* override
 at 0x08 is nonzero, this routine is called instead.
 
 
+
+
+
                                                         (cont.)

blk/280

@@ -1,16 +1,16 @@
 Z80 boot code
 
 This assembles the boot binary. It requires the Z80 assembler
-(B200) and cross compilation setup (B260).
+(B200) and cross compilation setup (B260). It also requires
+these constants to be set:
 
-On top of that, it requires RAMSTART to be defined as the
-beginning address of RAM. This is where system variables are
-placed. HERE is then placed at RAM+80 (ref B80).
+RAMSTART: beginning address of RAM. This is where system
+variables are placed. HERE is then placed at RAM+80 (ref B80).
 
-We also need RS_ADDR to be set to the bottom address of the
-Return Stack.
+RS_ADDR: to be set to the bottom address of the Return Stack.
 
-RESERVED REGISTERS: At all times, IX points to RSP TOS and IY
-is IP. SP points to PSP TOS, but you can still use the stack\
-in native code. you just have to make sure you've restored it
-before "next".                                          (cont.)
+PS_ADDR: top address of the Parameter stack (PS grows down-
+wards). Allow space for stack underflow protection (B76).
+
+
+                                                        (cont.)

blk/281

@@ -1,7 +1,12 @@
-(cont.) STABLE ABI: The boot binary starts with a list of
-references. The address of these references have to stay to
-those addresses. The rest of the Collapse OS code depend on it.
-In fact, up until 0x67, the (?br) wordref, pretty much
-everything has to stay put.
+RESERVED REGISTERS: At all times, IX points to RSP TOS and IY
+is IP. SP points to PSP TOS, but you can still use the stack\
+in native code. you just have to make sure you've restored it
+before "next".
+
+STABLE ABI: The boot binary starts with a list of references.
+The address of these references have to stay to those addr-
+esses. The rest of the Collapse OS code depend on it. In fact,
+up until 0x67, the (?br) wordref, pretty much everything has
+to stay put.
 
 To assemble, run "282 LOAD".

blk/289

@@ -3,8 +3,7 @@ L1 BSET 'B' A, 'O' A, 'O' A, 'T' A, 0 A,
 
 PC ORG @ 1 + ! ( main )
 ( STACK OVERFLOW PROTECTION: See B76 )
-    SP 0xfffa LDddnn,
-    RAMSTART SP LD(nn)dd, ( RAM+00 == INITIAL_SP )
+    SP PS_ADDR LDddnn,
     IX RS_ADDR LDddnn,
 ( HERE begins at RAMEND )
     HL RAMSTART 0x80 + LDddnn,

blk/299

@@ -1,14 +1,10 @@
 PC ORG @ 0x1e + ! ( chkPS )
     HL PUSHqq,
-    RAMSTART LDHL(nn), ( RAM+00 == INITIAL_SP )
 ( We have the return address for this very call on the stack
-  and protected registers. Let's compensate )
-    HL DECss,
-    HL DECss,
-    HL DECss,
-    HL DECss,
+  and protected registers. 4 - is to compensate that. )
+    HL PS_ADDR 4 - LDddnn,
     SP SUBHLss,
     HL POPqq,
-    CNC RETcc,      ( INITIAL_SP >= SP? good )
+    CNC RETcc,      ( PS_ADDR >= SP? good )
     JR, L2 BWR      ( abortUnderflow-B298 )
 

blk/310

@@ -9,7 +9,7 @@ CODE PICK
     B (HL) LDrr,
     ( check PS range before returning )
     EXDEHL,
-    RAMSTART LDHL(nn), ( RAM+00 == INITIAL_SP )
+    HL PS_ADDR LDddnn,
     DE SUBHLss,
     CC L2 @ JPccnn,    ( abortUnderflow-B298 )
     BC PUSHqq,

blk/313

@@ -1,5 +1,5 @@
 CODE S0
-    RAMSTART LDHL(nn), ( RAM+00 == INITIAL_SP )
+    HL PS_ADDR LDddnn,
     HL PUSHqq,
 ;CODE
 

blk/327

@@ -3,8 +3,7 @@ CODE BYE
 ;CODE
 
 CODE (resSP)
-    ( INITIAL_SP == RAM+0 )
-    SP RAMSTART LDdd(nn),
+    SP PS_ADDR LDddnn,
 ;CODE
 
 CODE (resRS)

blk/350

@@ -1,9 +1,9 @@
 ACIA driver
 
 Manage I/O from an asynchronous communication interface adapter
-(ACIA). provides "EMIT" to put c char on the ACIA as well as
-an input buffer. You have to call "~ACIA" on interrupt for
-this module to work well.
+(ACIA). provides "(emit)" to put c char on the ACIA as well as
+an input buffer from which a provided "(key)" reads. You have
+to call "~ACIA" on interrupt for this module to work well.
 
 CONFIGURATION
 
@@ -12,4 +12,5 @@ ACIA_IO: IO port for the ACIA's data registers
 ACIA_MEM: Address in memory that can be used variables shared
           with ACIA's native words. 8 bytes used.
 
-Load z80 words with "352 LOAD" and Forth words with "357 LOAD".
+The whole driver is cross-compilable and is loaded with
+"352 LOAD"

blk/352

@@ -1,15 +1,8 @@
-( Save ACIA conf )
-ACIA_CTL
-: ACIA_CTL [ LITN ] ;
-ACIA_IO
-: ACIA_IO [ LITN ] ;
-ACIA_MEM
-: ACIA_MEM [ LITN ] ;
 ( Memory layout
   +0 ACIAR>
   +2 ACIAW>
   +4 ACIA(
   +6 ACIA) )
 
-1 3 LOADR+
+1 6 LOADR+
 

blk/353

@@ -1,4 +1,4 @@
-(entry) ~ACIA
+CREATE ~ACIA
     AF PUSHqq,
     HL PUSHqq,
     DE PUSHqq,

blk/356

@@ -0,0 +1,11 @@
+( Points to ACIA buf )
+: ACIA( [ ACIA_MEM 4 + LITN ] ;
+( Points to ACIA buf end )
+: ACIA) [ ACIA_MEM 6 + LITN ] ;
+( Read buf pointer. Pre-inc )
+: ACIAR> [ ACIA_MEM LITN ] ;
+( Write buf pointer. Post-inc )
+: ACIAW> [ ACIA_MEM 2 + LITN ] ;
+( This means that if W> == R>, buffer is full.
+  If R>+1 == W>, buffer is empty. )
+

blk/357

@@ -1 +1,16 @@
-1 3 LOADR+
+: (key)
+    ( inc then fetch )
+    ACIAR> @ 1+ DUP ACIA) @ = IF
+        DROP ACIA( @
+    THEN
+    ( As long as R> == W>-1, it means that buffer is empty )
+    BEGIN DUP ACIAW> @ = NOT UNTIL
+    ACIAR> !
+    ACIAR> @ C@
+;
+: (emit)
+    ( As long at CTL bit 1 is low, we are transmitting. wait )
+    BEGIN [ ACIA_CTL LITN ] PC@ 0x02 AND UNTIL
+    ( The way is clear, go! )
+    [ ACIA_IO LITN ] PC!
+;

blk/358

@@ -1,13 +1,16 @@
-0x20 CONSTANT ACIABUFSZ
-
-( Points to ACIA buf )
-: ACIA( [ ACIA_MEM 4 + LITN ] ;
-( Points to ACIA buf end )
-: ACIA) [ ACIA_MEM 6 + LITN ] ;
-( Read buf pointer. Pre-inc )
-: ACIAR> [ ACIA_MEM LITN ] ;
-( Write buf pointer. Post-inc )
-: ACIAW> [ ACIA_MEM 2 + LITN ] ;
-( This means that if W> == R>, buffer is full.
-  If R>+1 == W>, buffer is empty. )
+: ACIA$
+    H@ DUP DUP ACIA( ! ACIAR> !
+    1+ ACIAW> !  ( write index starts one position later )
+    0x20 ( buffer size ) ALLOT
+    H@ ACIA) !
+( setup ACIA
+  CR7 (1) - Receive Interrupt enabled
+  CR6:5 (00) - RTS low, transmit interrupt disabled.
+  CR4:2 (101) - 8 bits + 1 stop bit
+  CR1:0 (10) - Counter divide: 64 )
+    0b10010110 [ ACIA_CTL LITN ] PC!
+( setup interrupt )
+    0xc3 0x4e RAM+ C!  ( c3==JP, 4e==INTJUMP )
+    ~ACIA 0x4f RAM+ !
+    (im1) ;
 

blk/359

@@ -1,16 +0,0 @@
-: (key)
-    ( inc then fetch )
-    ACIAR> @ 1+ DUP ACIA) @ = IF
-        DROP ACIA( @
-    THEN
-    ( As long as R> == W>-1, it means that buffer is empty )
-    BEGIN DUP ACIAW> @ = NOT UNTIL
-    ACIAR> !
-    ACIAR> @ C@
-;
-: (emit)
-    ( As long at CTL bit 1 is low, we are transmitting. wait )
-    BEGIN ACIA_CTL PC@ 0x02 AND UNTIL
-    ( The way is clear, go! )
-    ACIA_IO PC!
-;

blk/360

@@ -1,16 +0,0 @@
-: ACIA$
-    H@ DUP DUP ACIA( ! ACIAR> !
-    1+ ACIAW> !  ( write index starts one position later )
-    ACIABUFSZ ALLOT
-    H@ ACIA) !
-( setup ACIA
-  CR7 (1) - Receive Interrupt enabled
-  CR6:5 (00) - RTS low, transmit interrupt disabled.
-  CR4:2 (101) - 8 bits + 1 stop bit
-  CR1:0 (10) - Counter divide: 64 )
-    0b10010110 ACIA_CTL PC!
-( setup interrupt )
-    0xc3 0x4e RAM+ C!  ( c3==JP, 4e==INTJUMP )
-    ['] ~ACIA 0x4f RAM+ !
-    (im1) ;
-

blk/390

@@ -1,16 +1,14 @@
-Inner core
+Cross-compiled core
 
-This unit represents core definitions that happen right after
-native definitions. Before core.fs.
+This units contains core Collapse OS that are cross-compiled.
+During building, these come right after the boot binary (B280).
 
-Unlike core.fs and its followers, this unit isn't self-
-sustained. Like native defs it uses the machinery of a full
-Forth interpreter, notably for flow structures.
-
-Because of that, it has to obey specific rules:
-
-1. It cannot compile a word from higher layers. Using
-   immediates is fine though.
+Because this unit is designed to be cross-compiled, things are
+a little weird. It is compiling in the context of a full
+Forth interpreter with all bells and whistles (and z80
+assembler), but it has to obey strict rules:
 
+1. It cannot compile a word from higher layers. Immediates are
+   fine.
 
                                                         (cont.)

blk/391

@@ -1,16 +1,16 @@
-2. If it references a word from this unit or from native
-   definitions, these need to be properly offsetted because
-   their offset at compile time are not the same as their
-   runtime offsets.
-3. Anything they refer to in the boot binary has to be properly
-   stabilized.
-4. Make sure that the words you compile are not overridden by
-   the full interpreter.
-5. When using words as immediates, make sure that they're not
-   defined in icore or, if they are, make sure that they are
-   *not* offsetted
+2. Immediate words that have been cross compiled *cannot* be
+   used. Only immediates from the host system can be used.
+3. If an immediate word compiles words, it can only be words
+   that are part of the stable ABI.
 
+All of this is because when cross compiling, all atom ref-
+erences are offsetted to the target system and are thus
+unusable directly. For the same reason, any reference to a word
+in the host system will obviously be wrong in the target
+system. More details in B260.
 
-
-
-                                                        (cont.)
+This unit is loaded in two "low" and "high" parts. The low part
+is the biggest chunk and has the most definitions. The high
+part is the "sensitive" chunk and contains "LITN", ":" and ";"
+definitions which, once defined, kind of make any more defs
+impossible.                                             (cont.)

blk/392

@@ -1,15 +1,3 @@
-Those rules are mostly met by the "xcomp" unit, which is
-expected to have been loaded prior to icore and redefines ":"
-and other defining words. So, in other words, when compiling
-icore, ":" doesn't means what you think it means, go look in
-B260.
-
-This is loaded in two "low" and "high" parts. The low part is
-the biggest chunk and has the most definitions. The high part
-is the "sensitive" chunk and contains "LITN", ":" and ";"
-definitions which, once defined, kind of make any more defs
-impossible.
-
 The gap between these 2 parts is the ideal place to put device
 driver code. Load the low part with "393 LOAD", the high part
 with "415 LOAD"

blk/420

@@ -1,12 +1,12 @@
 Core words
 
-These words follow Inner core words, but unlike them, these are
-self-bootstrapping and don't depend on the Cross Compiler. They
-will typically be included in source form right after a stage1
-binary which will interpret it on boot and bootstrap itself to
-a full intepreter, which can then be relinked with the
-Relinker. There is no loader for these libraries because you
-will typically XPACK (B267) them.
+These words follow cross-compiled words, but unlike them, these
+are self-bootstrapping and don't depend on the Cross Compiler.
+They will typically be included in source form right after a
+stage1 binary which will interpret it on boot and bootstrap
+itself to a full intepreter, which can then be relinked with
+the Relinker. There is no loader for these libraries because
+you will typically XPACK (B267) them.
 
 422 core                       438 print
 442 fmt                        447 readln

emul/xcomp.fs

@@ -1,5 +1,6 @@
 0xe800 CONSTANT RAMSTART
 0xf000 CONSTANT RS_ADDR
+0xfffa CONSTANT PS_ADDR
 212 LOAD  ( z80 assembler )
 262 LOAD  ( xcomp )
 : CODE XCODE ;

recipes/rc2014/xcomp.fs

@@ -1,5 +1,6 @@
 0x8000 CONSTANT RAMSTART
 0xf000 CONSTANT RS_ADDR
+0xfffa CONSTANT PS_ADDR
 0x80   CONSTANT ACIA_CTL
 0x81   CONSTANT ACIA_IO
 4      CONSTANT SDC_SPI
@@ -11,21 +12,20 @@ RAMSTART 0x70 + CONSTANT ACIA_MEM
 : CODE XCODE ;
 : IMMEDIATE XIMM ;
 : (entry) (xentry) ;
+: CREATE XCREATE ;
 : : [ ' X: , ] ;
 
 CURRENT @ XCURRENT !
 
 282 LOAD  ( boot.z80 )
-352 LOAD  ( acia.z80 )
-372 LOAD  ( sdc.z80 )
 393 LOAD  ( icore low )
+352 LOAD  ( acia )
+372 LOAD  ( sdc.z80 )
 415 LOAD  ( icore high )
 (entry) _
 ( Update LATEST )
 PC ORG @ 8 + !
-422 437 XPACKR ( core )
-358 360 XPACKR ( acia.fs )
-438 452 XPACKR ( print fmt readln )
+422 452 XPACKR ( core print fmt readln )
 123 132 XPACKR ( linker )
 ," : _ ACIA$ RDLN$ (ok) ; _ "
 ORG @ 256 /MOD 2 PC! 2 PC!

recipes/ti84/xcomp.fs

@@ -1,5 +1,6 @@
 0x8000 CONSTANT RAMSTART
 0xb000 CONSTANT RS_ADDR
+0xbffa CONSTANT PS_ADDR
 RAMSTART 0x70 + CONSTANT LCD_MEM
 RAMSTART 0x72 + CONSTANT KBD_MEM
 0x01 CONSTANT KBD_PORT

recipes/trs80/xcomp.fs

@@ -1,4 +1,5 @@
 0xf000 CONSTANT RS_ADDR
+0xfffa CONSTANT PS_ADDR
 RS_ADDR 0x80 - CONSTANT RAMSTART
 212 LOAD  ( z80 assembler )
 262 LOAD  ( xcomp )