From 0939241db1ea2f3ee587e8e2bbc897159eb89fbb Mon Sep 17 00:00:00 2001 From: Virgil Dupras Date: Thu, 21 May 2020 15:25:12 -0400 Subject: [PATCH] Add bootstrap guide --- blk/001 | 2 +- blk/003 | 2 +- blk/021 | 13 +++++++++++++ blk/420 | 16 ++++++++++++++++ blk/421 | 16 ++++++++++++++++ blk/422 | 16 ++++++++++++++++ blk/423 | 16 ++++++++++++++++ blk/424 | 16 ++++++++++++++++ blk/425 | 16 ++++++++++++++++ blk/426 | 15 +++++++++++++++ 10 files changed, 126 insertions(+), 2 deletions(-) create mode 100644 blk/021 create mode 100644 blk/420 create mode 100644 blk/421 create mode 100644 blk/422 create mode 100644 blk/423 create mode 100644 blk/424 create mode 100644 blk/425 create mode 100644 blk/426 diff --git a/blk/001 b/blk/001 index 8075f1d..33183c3 100644 --- a/blk/001 +++ b/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 diff --git a/blk/003 b/blk/003 index f3d061b..aa19f53 100644 --- a/blk/003 +++ b/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 diff --git a/blk/021 b/blk/021 new file mode 100644 index 0000000..460d38f --- /dev/null +++ b/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. diff --git a/blk/420 b/blk/420 new file mode 100644 index 0000000..ccc8e86 --- /dev/null +++ b/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.) diff --git a/blk/421 b/blk/421 new file mode 100644 index 0000000..c54ff1a --- /dev/null +++ b/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.) diff --git a/blk/422 b/blk/422 new file mode 100644 index 0000000..fdedb6e --- /dev/null +++ b/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.) diff --git a/blk/423 b/blk/423 new file mode 100644 index 0000000..809ff17 --- /dev/null +++ b/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.) diff --git a/blk/424 b/blk/424 new file mode 100644 index 0000000..b6554b8 --- /dev/null +++ b/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.) diff --git a/blk/425 b/blk/425 new file mode 100644 index 0000000..8a160c3 --- /dev/null +++ b/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.) diff --git a/blk/426 b/blk/426 new file mode 100644 index 0000000..7ac61a7 --- /dev/null +++ b/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!