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) (B390)

# 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
few (<0x20) bytes.

# 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

Core words don't include (key) and (emit) implementations be-
cause that's hardware-dependant. This is where we need to load
code that implement it, as well as any other code we want to
include in the binary.

We do it now because if we wait until the high layer of core
words is loaded, we'll have messed up immediates and ":" will
be broken. If we load our code before, we won't have access to
a wide vocabulary.

# Core words (high)

The final layer of core words contains the BOOT word as well
as tricky immediates which, if they're defined sooner, mess
cross compilation up. Once this layer is loaded, we become
severly limited in the words we can use without messing up.

# Hook word

After having loaded that last core words layer, we end that
with a hook word, the "(entry) _" line. A hook word is an empty
word at the end of the dictionary which serves 3 purposes:

1. After having created that word, PC conveniently holds the
   value that should go in the LATEST field in stable ABI. Had
   the word been non-empty, getting that value would be less
   straightforward.
2. Because LATEST points to an empty word, it means that it also
   points to the initialization string, which directly follows.
   If it was non-empty, we would need to know the word's length
   to get to that string.
3. If, for some reason, you want to "graft" another dictionary
   on top of this one, having it end with an empty word makes
   grafting convenient: you already know what your "prev field"
   offset should be for the grafting to be correct.

# Initialization string

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.

# Building it

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 the hook word and init string.

To produce a Collapse OS binary, you run that xcomp unit and
then observe the values of "ORG @" and "H@". That will give you
the start and stop offset of your binary, which you can then
copy to your target media.

Good luck!