mirror of
https://github.com/hsoft/collapseos.git
synced 2024-11-05 08:30:55 +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
|
150 Extra words
|
||||||
200 Z80 assembler 260 Cross compilation
|
200 Z80 assembler 260 Cross compilation
|
||||||
280 Z80 boot code 350 Core words
|
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
|
490 TRS-80 Recipe 520 Fonts
|
||||||
550 TI-84+ Recipe 580 RC2014 Recipe
|
550 TI-84+ Recipe 580 RC2014 Recipe
|
||||||
620 Sega Master System 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.
|
4 Number literals 6 Compilation vs meta-comp.
|
||||||
8 Interpreter I/O 11 Signed-ness
|
8 Interpreter I/O 11 Signed-ness
|
||||||
14 Addressed devices 17 DOES>
|
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