mirror of
https://github.com/hsoft/collapseos.git
synced 2024-11-08 06:38:08 +11:00
116 lines
4.3 KiB
Plaintext
116 lines
4.3 KiB
Plaintext
# 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.
|