|
- # 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!
|