From ab72a4f3835c63d6397517cc617baa3ed3e5b4d6 Mon Sep 17 00:00:00 2001 From: Virgil Dupras Date: Sun, 16 Aug 2020 08:33:02 -0400 Subject: [PATCH] doc: take bootstrap guide out of blkfs --- blk/001 | 2 +- blk/420 | 16 ------- blk/421 | 16 ------- blk/422 | 16 ------- blk/423 | 16 ------- blk/424 | 16 ------- blk/425 | 16 ------- blk/426 | 16 ------- blk/427 | 6 --- doc/bootstrap.txt | 116 ++++++++++++++++++++++++++++++++++++++++++++++ 10 files changed, 117 insertions(+), 119 deletions(-) delete mode 100644 blk/420 delete mode 100644 blk/421 delete mode 100644 blk/422 delete mode 100644 blk/423 delete mode 100644 blk/424 delete mode 100644 blk/425 delete mode 100644 blk/426 delete mode 100644 blk/427 create mode 100644 doc/bootstrap.txt diff --git a/blk/001 b/blk/001 index 41dc031..a160329 100644 --- a/blk/001 +++ b/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 diff --git a/blk/420 b/blk/420 deleted file mode 100644 index ccc8e86..0000000 --- a/blk/420 +++ /dev/null @@ -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.) diff --git a/blk/421 b/blk/421 deleted file mode 100644 index c0925ce..0000000 --- a/blk/421 +++ /dev/null @@ -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.) diff --git a/blk/422 b/blk/422 deleted file mode 100644 index 8600dad..0000000 --- a/blk/422 +++ /dev/null @@ -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.) diff --git a/blk/423 b/blk/423 deleted file mode 100644 index 809ff17..0000000 --- a/blk/423 +++ /dev/null @@ -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.) diff --git a/blk/424 b/blk/424 deleted file mode 100644 index b6554b8..0000000 --- a/blk/424 +++ /dev/null @@ -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.) diff --git a/blk/425 b/blk/425 deleted file mode 100644 index b8fedce..0000000 --- a/blk/425 +++ /dev/null @@ -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.) diff --git a/blk/426 b/blk/426 deleted file mode 100644 index f44fa42..0000000 --- a/blk/426 +++ /dev/null @@ -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.) diff --git a/blk/427 b/blk/427 deleted file mode 100644 index d6de7fe..0000000 --- a/blk/427 +++ /dev/null @@ -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! diff --git a/doc/bootstrap.txt b/doc/bootstrap.txt new file mode 100644 index 0000000..badf9fc --- /dev/null +++ b/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!