collapseos/doc/bootstrap.txt

# Bootstrap guide

You want to deploy Collapse OS on a new system? Read usage.txt,
impl.txt, cross.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 bootstrap
itself some more.

This binary can be separated in 5 distinct layers:

1. Arch-specific boot code (B280 for Z80)
2. Arch-specific boot words (B305 for Z80)
3. Arch-independant core words (low) (B350)
4. Drivers, might contain arch-specific code
5. Arch-independant core words (high) (B380)

# Boot code

This part contains core routines that underpins Forth fundamen-
tal structures: dict navigation and FIND, 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 of the dict is intertwined in this
layer because EXIT, (br), (?br) and (loop) are part of the
stable ABI.

# Boot words

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)

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)

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 impl.txt.

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. This allows us to boot
with CURRENT pointing to "source init" content rather than being
an actual wordref.

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!