doc: take bootstrap guide out of blkfs

blk/001

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

blk/420

@@ -1,16 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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 (B85).
-
-It also of course does core initialization: set RSP/PSP, HERE
-CURRENT, then call BOOT (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

@@ -1,16 +0,0 @@
-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 comes with tricky limitations.    (cont.)

blk/423

@@ -1,16 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,16 +0,0 @@
-anatomy. First, we have constants. Some of them are device-
-specific, but some of them are always there. SYSVARS is the
-address at which the RAM starts on the system. System variables
-will go there and use 0x80 bytes. See B80.
-
-HERESTART determines where... HERE is at startup. 0 means
-"same as CURRENT".
-
-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.
-
-                                                        (cont.)

blk/426

@@ -1,16 +0,0 @@
-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.
-
-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.
-
-
-                                                        (cont.)

blk/427

@@ -1,6 +0,0 @@
-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!

doc/bootstrap.txt

@@ -0,0 +1,116 @@
+# Bootstrap guide
+
+You want to deploy Collapse OS on a new system? Read usage.txt
+and impl.txt, then continue 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
+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.
+
+It also of course does core initialization: set RSP/PSP, HERE
+CURRENT, then call BOOT.
+
+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.
+
+# 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 comes with tricky limitations.
+
+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).
+
+# 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
+anatomy. First, we have constants. Some of them are device-
+specific, but some of them are always there. SYSVARS is the
+address at which the RAM starts on the system. System variables
+will go there and use 0x80 bytes. See B80.
+
+HERESTART determines where... HERE is at startup. 0 means
+"same as CURRENT".
+
+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.
+
+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!