mirror of https://github.com/hsoft/collapseos.git
114 lines
4.0 KiB
Plaintext
114 lines
4.0 KiB
Plaintext
# 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!
|