mirror of
https://github.com/hsoft/collapseos.git
synced 2024-12-24 14:18:06 +11:00
Add bootstrap guide
This commit is contained in:
parent
b5683f447b
commit
0939241db1
2
blk/001
2
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
|
||||
|
2
blk/003
2
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
|
||||
|
13
blk/021
Normal file
13
blk/021
Normal file
@ -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.
|
16
blk/420
Normal file
16
blk/420
Normal file
@ -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.)
|
16
blk/421
Normal file
16
blk/421
Normal file
@ -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.)
|
16
blk/422
Normal file
16
blk/422
Normal file
@ -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.)
|
16
blk/423
Normal file
16
blk/423
Normal file
@ -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.)
|
16
blk/424
Normal file
16
blk/424
Normal file
@ -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.)
|
16
blk/425
Normal file
16
blk/425
Normal file
@ -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.)
|
15
blk/426
Normal file
15
blk/426
Normal file
@ -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!
|
Loading…
Reference in New Issue
Block a user