@@ -4,7 +4,7 @@ MASTER INDEX | |||
120 Visual Editor 150 Extra words | |||
200 Z80 assembler 260 Cross compilation | |||
280 Z80 boot code 350 Core words | |||
410 PS/2 keyboard subsystem 420 Bootstrap guide | |||
410 PS/2 keyboard subsystem | |||
490 TRS-80 Recipe 520 Fonts | |||
550 TI-84+ Recipe 580 RC2014 Recipe | |||
620 Sega Master System Recipe | |||
@@ -1,16 +0,0 @@ | |||
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.) |
@@ -1,16 +0,0 @@ | |||
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 (B85). | |||
It also of course does core initialization: set RSP/PSP, HERE | |||
CURRENT, then call BOOT (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.) |
@@ -1,16 +0,0 @@ | |||
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 comes with tricky limitations. (cont.) |
@@ -1,16 +0,0 @@ | |||
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.) |
@@ -1,16 +0,0 @@ | |||
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.) |
@@ -1,16 +0,0 @@ | |||
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 B80. | |||
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. | |||
(cont.) |
@@ -1,16 +0,0 @@ | |||
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) 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. | |||
(cont.) |
@@ -1,6 +0,0 @@ | |||
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! |
@@ -0,0 +1,116 @@ | |||
# Bootstrap guide | |||
You want to deploy Collapse OS on a new system? Read usage.txt | |||
and impl.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 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 | |||
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. | |||
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 og the dict is intertwined in this | |||
layer because EXIT, (br), (?br) and (loop) are part of the | |||
stable ABI. | |||
# 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 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) (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 | |||
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 B80. | |||
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) 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! |