|
|
@@ -0,0 +1,115 @@ |
|
|
|
# Collapse OS usage guide |
|
|
|
|
|
|
|
If you already know Forth, start here. Otherwise, read primer |
|
|
|
first. |
|
|
|
|
|
|
|
We begin with a few oddities in Collapse OS compared to tradi- |
|
|
|
tional forths, then cover higher level operations. |
|
|
|
|
|
|
|
# Signed-ness |
|
|
|
|
|
|
|
For simplicity purposes, numbers are generally considered |
|
|
|
unsigned. For convenience, decimal parsing and formatting |
|
|
|
support the "-" prefix, but under the hood, it's all unsigned. |
|
|
|
|
|
|
|
This leads to some oddities. For example, "-1 0 <" is false. |
|
|
|
To compare whether something is negative, use the "0<" word |
|
|
|
which is the equivalent to "0x7fff >". |
|
|
|
|
|
|
|
# Branching |
|
|
|
|
|
|
|
Branching in Collapse OS is limited to 8-bit. This represents |
|
|
|
64 word references forward or backward. While this might seem |
|
|
|
a bit tight at first, having this limit saves us a non- |
|
|
|
negligible amount of resource usage. |
|
|
|
|
|
|
|
The reasoning behind this intentional limit is that huge |
|
|
|
branches are generally a indicator that a logic ought to be |
|
|
|
simplified. So here's one more constraint for you to help you |
|
|
|
towards simplicity. |
|
|
|
|
|
|
|
# Interpreter I/O |
|
|
|
|
|
|
|
The INTERPRET loop, the heart of Collapse OS, feeds itself |
|
|
|
from the C< word, which yields a character every time it is |
|
|
|
called. If no character is available to interpret, it blocks. |
|
|
|
|
|
|
|
During normal operations, C< is simply a buffered layer over |
|
|
|
KEY, which has the same behavior (but unbuffered). Before |
|
|
|
yielding any character, the C< routine fetches a whole line |
|
|
|
from KEY, puts it in a buffer, then yields the buffered line, |
|
|
|
one character at a time. |
|
|
|
|
|
|
|
Both C< and KEY can be overridden by setting an alternate |
|
|
|
routine at the proper RAM offset (see B80). For example, C< |
|
|
|
overrides are used during LOAD so that input comes from |
|
|
|
disk blocks instead of keyboard. |
|
|
|
|
|
|
|
KEY overrides can be used to, for example, temporarily give |
|
|
|
prompt control to a RS-232 device instead of the keyboard. |
|
|
|
|
|
|
|
Interpreter output is unbuffered and only has EMIT. This |
|
|
|
word can also be overriden, mostly as a companion to the |
|
|
|
raison d'etre of your KEY override. |
|
|
|
|
|
|
|
# Addressed devices |
|
|
|
|
|
|
|
A@ and A! are the indirect versions of C@ and C!. Their target |
|
|
|
word is controlled through A@* and A!* and by default point to |
|
|
|
C@ and C*. There is also a AMOVE word that is the same as MOVE |
|
|
|
but using A@ and A!. |
|
|
|
|
|
|
|
# Disk blocks |
|
|
|
|
|
|
|
Disk blocks are Collapse OS' main access to permanent storage. |
|
|
|
The system is exceedingly simple: blocks are contiguous |
|
|
|
chunks of 1024 bytes each living on some permanent media such |
|
|
|
as floppy disks or SD cards. They are mostly used for text, |
|
|
|
either informational or source code, which is organized into |
|
|
|
16 lines of 64 characters each. |
|
|
|
|
|
|
|
Blocks are referred to by number, 0-indexed. They are read |
|
|
|
through BLK@ and written through BLK!. When a block is read, |
|
|
|
its 1024 bytes content is copied to an in-memory buffer |
|
|
|
starting at BLK( and ending at BLK). Those read/write |
|
|
|
operations are often implicit. For example, LIST calls BLK@. |
|
|
|
|
|
|
|
When a word modifies the buffer, it sets the buffer as dirty |
|
|
|
by calling BLK!!. BLK@ checks, before it reads its buffer, |
|
|
|
whether the current buffer is dirty and implicitly calls BLK! |
|
|
|
when it is. |
|
|
|
|
|
|
|
The index of the block currently in memory is kept in BLK>. |
|
|
|
|
|
|
|
Many blocks contain code. That code can be interpreted through |
|
|
|
LOAD. Programs stored in blocks frequently have "loader blocks" |
|
|
|
that take care of loading all blocks relevant to the program. |
|
|
|
|
|
|
|
Blocks spanning multiple disks are tricky. If your media isn't |
|
|
|
large enough to hold all Collapse OS blocks in one unit, you'll |
|
|
|
have to make it span multiple disks. Block reference in |
|
|
|
informational texts aren't a problem: When you swap your disk, |
|
|
|
you mentally adjust the block number you fetch. |
|
|
|
|
|
|
|
However, absolute LOAD operations in Collapse OS aren't aware |
|
|
|
of disk spanning and will not work properly in your spanned |
|
|
|
system. |
|
|
|
|
|
|
|
Although the usage of absolute LOAD calls are minimally used |
|
|
|
(relative LOADs are preferred), they are sometimes unavoidable. |
|
|
|
When you span Collapse OS over multiple disks, don't forget to |
|
|
|
adjust those absolute LOADs. |
|
|
|
|
|
|
|
# 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. |