@@ -4,7 +4,7 @@ MASTER INDEX | |||||
120 Visual Editor 150 Extra words | 120 Visual Editor 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 420 Bootstrap guide | |||||
410 PS/2 keyboard subsystem | |||||
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 | ||||
@@ -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! |