Add bootstrap guide

blk/001

@@ -6,7 +6,7 @@ MASTER INDEX
 150 Extra words
 200 Z80 assembler             260 Cross compilation
 280 Z80 boot code             350 Core words
-410 PS/2 keyboard subsystem
+410 PS/2 keyboard subsystem   420 Bootstrap guide
 490 TRS-80 Recipe             520 Fonts
 550 TI-84+ Recipe             580 RC2014 Recipe
 620 Sega Master System Recipe

blk/003

@@ -13,4 +13,4 @@ Contents
  4 Number literals              6 Compilation vs meta-comp.
  8 Interpreter I/O             11 Signed-ness
 14 Addressed devices           17 DOES>
-18 Disk blocks
+18 Disk blocks                 21 How blocks are organized

blk/021

@@ -0,0 +1,13 @@
+How blocks are organized
+
+Organization of contiguous blocks is an ongoing challenge and
+Collapse OS' blocks are never as tidy as they should, but we
+try to strive towards a few goals:
+
+1. Block 0 contains documentation discovery core keys to the
+   uninitiated.
+2. First section (up to B100) is usage documentation.
+3. B100-B200 are for runtime usage utilities
+4. B200-B500 are for bootstrapping
+5. The rest is for recipes.
+6. I'm not sure yet how I'll organize multiple arches.

blk/420

@@ -0,0 +1,16 @@
+Bootstrap guide
+
+You want to deploy Collapse OS on a new system? Start here.
+
+What is Collapse OS? It is a binary placed either in ROM on
+in RAM by a bootloader. That binary, when executed, initializes
+itself to a Forth interpreter. In most cases, that Forth
+interpreter will have some access to a mass storage device,
+which allows it to access Collapse OS' disk blocks and come
+to this block to bootstrap itself some more.
+
+This binary can be separated in 5 distinct layers:
+1. Boot code (B280)
+2. Boot words (B305)
+3. Core words (low) (B350)
+4. Drivers                                              (cont.)

blk/421

@@ -0,0 +1,16 @@
+5. Core words (high)
+
+Boot code (B280)
+
+This part contains core routines that underpins Forth fundamen-
+tal structures: dict navigation and search, PSP/RSP bounds
+checks, word types (atom, native, literals, "does type"), etc.
+
+It also of course does core initialization: set RSP/PSP, HERE
+CURRENT, then find BOOT and call it (see B89).
+
+It also contains what we call the "stable ABI" in its first
+0x100 bytes. The beginning og the dict is intertwined in this
+layer because EXIT, (br), (?br) and (loop) are part of the
+stable ABI.
+                                                        (cont.)

blk/422

@@ -0,0 +1,16 @@
+Boot words (B305)
+
+Then come the implementation of core Forth words in native
+assembly. Performance is not Collapse OS' primary design goal,
+so we try to keep this section to a minimum: we much prefer
+to implement our words in Forth.
+
+However, some words are in this section for performance
+reasons. Sometimes, the gain is too great to pass up.
+
+Core words (low) (B350)
+
+Then comes the part where we begin defining words in Forth.
+Core words are designed to be cross-compiled (B260), from a
+full Forth interpreter. This means that it has access to more
+than boot words. This somes with tricky limitations.    (cont.)

blk/423

@@ -0,0 +1,16 @@
+See B260 for details.
+
+Drivers
+
+Up until now, we haven't implemented EMIT or KEY yet: those
+words are defined in the "high" part of core words because we
+generally need machine-specific drivers to implement (emit) and
+(key).
+
+Well, now is their time to shine. We split core in two
+precisely to fit drivers in there. This way. they have access
+to a pretty good vocabulary and they're also give the oppor-
+tunity to provide (emit) and (key).
+
+
+                                                        (cont.)

blk/424

@@ -0,0 +1,16 @@
+Core words (high) (B350)
+
+Then come EMIT, KEY and everything that depend on it, until
+we have a full Forth interpreter. At the very end, we define
+tricky IMMEDIATEs that, if defined earlier, would break cross
+compilation.
+
+We end that with a hook words which is also where CURRENT will
+be on boot.
+
+So that's the anatomy of a Collapse OS binary. How do you build
+one? If your machine is already covered by a recipe, you're in
+luck: follow instructions.
+
+If you're deploying to a new machine, you'll have to write a
+new xcomp (cross compilation) unit. Let's look at its   (cont.)

blk/425

@@ -0,0 +1,16 @@
+anatomy. First, we have constants. Some of them are device-
+specific, but some of them are always there. RAMSTART is the
+address at which the RAM starts on the system. System variables
+will go there and HERE will go after it.
+
+RS_ADDR is where RSP starts and PS_ADDR is where PSP starts.
+RSP and PSP are designed to be contiguous. RSP goes up and PSP
+goes down. If they meet, we know we have a stack overflow.
+
+Then, we load the assembler and cross compilation unit, which
+will be needed for the task ahead.
+
+Then, it's a matter of adding layer after layer. For most
+system, all those layers except the drivers will be added the
+same way. Drivers are a bit tricker and machine specific. I
+can't help you there, you'll have to use your wits.     (cont.)

blk/426

@@ -0,0 +1,15 @@
+After we've loaded the high part of the core words, we're at
+the "wrapping up" part. We add what we call a "hook word" (an
+empty word with a single letter name) which doesn't cost us
+much and can be very useful if we need to augment the binary
+with more words, and at that point we have our future boot
+CURRENT, which PC yields. That is why we write it to the
+LATEST field of the stable ABI: This value will be used at
+boot.
+
+After the last word of the dictionary comes the "source init"
+part. The boot sequence is designed to interpret whatever comes
+after LATEST as Forth source, and this, until it reads ASCII
+EOT character (4). This is generally used for driver init.
+
+Good luck!