mirror of
https://github.com/hsoft/collapseos.git
synced 2025-03-14 15:38:43 +11:00
doc: move usage documention out of the system
This commit is contained in:
parent
a3a83ae49b
commit
5c4bbaabf4
@ -23,14 +23,11 @@ tools.
|
|||||||
|
|
||||||
## Getting started
|
## Getting started
|
||||||
|
|
||||||
Usage documentation is in-system, so access to documentation requires you to
|
Documentation is in text files in `doc/`. Begin with `intro.txt`.
|
||||||
run Collapse OS. Fortunately, building and running Collapse OS on a POSIX
|
|
||||||
environment is easy.
|
|
||||||
|
|
||||||
|
Collapse OS can run on any POSIX platform and builds easily.
|
||||||
See `/cvm/README.md` for instructions.
|
See `/cvm/README.md` for instructions.
|
||||||
|
|
||||||
Then, run `0 LIST` for an introduction, follow instructions from there.
|
|
||||||
|
|
||||||
Alternatively, there's also [Michael Schierl's JS Collapse OS emulator][jsemul]
|
Alternatively, there's also [Michael Schierl's JS Collapse OS emulator][jsemul]
|
||||||
which is awesome and allows you to run Collapse OS from your browser, but it
|
which is awesome and allows you to run Collapse OS from your browser, but it
|
||||||
isn't always up to date. The "Javascript Forth" version is especially awesome:
|
isn't always up to date. The "Javascript Forth" version is especially awesome:
|
||||||
@ -42,6 +39,7 @@ it's not a z80 emulator, but a *javascript port of Collapse OS*!
|
|||||||
source code is located. Everything else is peripheral.
|
source code is located. Everything else is peripheral.
|
||||||
* `cvm`: A C implementation of Collapse OS, allowing it to run natively on any
|
* `cvm`: A C implementation of Collapse OS, allowing it to run natively on any
|
||||||
POSIX platform.
|
POSIX platform.
|
||||||
|
* `doc`: Documentation.
|
||||||
* `recipes`: collection of recipes that assemble Collapse OS on a specific
|
* `recipes`: collection of recipes that assemble Collapse OS on a specific
|
||||||
machine.
|
machine.
|
||||||
* `tools`: Tools for working with Collapse OS from "modern" environments. For
|
* `tools`: Tools for working with Collapse OS from "modern" environments. For
|
||||||
|
2
blk/001
2
blk/001
@ -1,6 +1,6 @@
|
|||||||
MASTER INDEX
|
MASTER INDEX
|
||||||
|
|
||||||
3 Usage 30 Dictionary
|
30 Dictionary
|
||||||
70 Implementation notes 100 Block editor
|
70 Implementation notes 100 Block editor
|
||||||
120 Visual Editor 150 Extra words
|
120 Visual Editor 150 Extra words
|
||||||
200 Z80 assembler 260 Cross compilation
|
200 Z80 assembler 260 Cross compilation
|
||||||
|
16
blk/003
16
blk/003
@ -1,16 +0,0 @@
|
|||||||
Collapse OS usage guide
|
|
||||||
|
|
||||||
This document is not meant to be an introduction to Forth, but
|
|
||||||
to instruct the user about the peculiarities of this Forth
|
|
||||||
implementation. The recommended introductory book is Starting
|
|
||||||
Forth by Leo Brodie. This is the reference that was used to
|
|
||||||
build this implementation and many of the conventions described
|
|
||||||
in this book are followed in Collapse OS. Be sure to refer to
|
|
||||||
the dictionary (B30) for a word reference.
|
|
||||||
|
|
||||||
Contents
|
|
||||||
|
|
||||||
5 Number literals 6 Compilation vs meta-comp.
|
|
||||||
8 Interpreter I/O 11 Signed-ness
|
|
||||||
17 DOES> 18 Disk blocks
|
|
||||||
(cont.)
|
|
11
blk/005
11
blk/005
@ -1,11 +0,0 @@
|
|||||||
Number literals
|
|
||||||
|
|
||||||
Traditional Forth often uses HEX/DEC switches to go from deci-
|
|
||||||
mal to hexadecimal parsing. Collapse OS parses literals in a
|
|
||||||
way that is closer to C.
|
|
||||||
|
|
||||||
Straight numbers are decimals, numbers starting with "0x"
|
|
||||||
are hexadecimals (example "0x12ef"), "0b" prefixes indicate
|
|
||||||
binary (example "0b1010"), char literals are single characters
|
|
||||||
surrounded by ' (example 'X'). Char literals can't be used for
|
|
||||||
whitespaces.
|
|
14
blk/006
14
blk/006
@ -1,14 +0,0 @@
|
|||||||
Compilation vs meta-compilation
|
|
||||||
|
|
||||||
Compilation vs meta-compilation. When you compile a word with
|
|
||||||
"[COMPILE] foo", it's straightforward: It writes the address
|
|
||||||
of word foo to HERE.
|
|
||||||
|
|
||||||
When you *meta* compile, it's a bit more mind blowing. It
|
|
||||||
fetches the address of the word specified by the caller, then
|
|
||||||
writes that number as a literal, followed by a reference to
|
|
||||||
",".
|
|
||||||
|
|
||||||
Example: ": foo [COMPILE] bar;" is the equivalent of ": foo bar
|
|
||||||
;" if bar is not an immediate. However, ": foo COMPILE bar ;"
|
|
||||||
is the equivalent of ": foo ['] bar , ;". Got it?
|
|
16
blk/008
16
blk/008
@ -1,16 +0,0 @@
|
|||||||
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. (cont.)
|
|
6
blk/009
6
blk/009
@ -1,6 +0,0 @@
|
|||||||
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.
|
|
9
blk/011
9
blk/011
@ -1,9 +0,0 @@
|
|||||||
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 >".
|
|
15
blk/017
15
blk/017
@ -1,15 +0,0 @@
|
|||||||
DOES>
|
|
||||||
|
|
||||||
Used inside a colon definition that itself uses CREATE, DOES>
|
|
||||||
transforms that newly created word into a "does cell", that is,
|
|
||||||
a regular cell (when called, puts the cell's addr on PS), but
|
|
||||||
right after that, it executes words that appear after the
|
|
||||||
DOES>.
|
|
||||||
|
|
||||||
"does cells" always allocate 4 bytes (2 for the cell, 2 for the
|
|
||||||
DOES> link) and there is no need for ALLOT in colon definition.
|
|
||||||
|
|
||||||
At compile time, colon definition stops processing words when
|
|
||||||
reaching the DOES>.
|
|
||||||
|
|
||||||
Example: ": CONSTANT CREATE HERE @ ! DOES> @ ;"
|
|
16
blk/018
16
blk/018
@ -1,16 +0,0 @@
|
|||||||
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@.
|
|
||||||
|
|
||||||
(cont.)
|
|
16
blk/019
16
blk/019
@ -1,16 +0,0 @@
|
|||||||
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. (cont.)
|
|
8
blk/020
8
blk/020
@ -1,8 +0,0 @@
|
|||||||
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.
|
|
13
blk/021
13
blk/021
@ -1,13 +0,0 @@
|
|||||||
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.
|
|
6
blk/022
6
blk/022
@ -1,6 +0,0 @@
|
|||||||
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!.
|
|
11
blk/023
11
blk/023
@ -1,11 +0,0 @@
|
|||||||
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.
|
|
115
doc/usage.txt
Normal file
115
doc/usage.txt
Normal file
@ -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.
|
Loading…
Reference in New Issue
Block a user