|
- # 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 an 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 impl.txt). 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. B1-B4 are for a master index of blocks.
- 3. B5-B199 are for runtime usage utilities
- 4. B200-B599 are for bootstrapping
- 5. The rest is for recipes.
-
- Blocks are currently not organized neatly. I'm planning the
- extraction of recipes into some kind of block "overlays" that
- would live in the recipes subfolder so each recipe would build
- its own specific blkfs which would contain only its recipe code,
- starting at B600.
|