How to read this code
Because compactness is a primary design goal of Collapse OS,
comments in the code itself are terse. This represents an extra
challenge when comes the time of understanding it.
The code is designed to be accompanied by the documentation. If
a piece of code seems underdocumented, you should look for more
context in the documentation.
At the heart of every port are the "core routines" of Collapse
OS. These are called all the time and their optimization is
paramount. They are, however, very small in scope and all fit
in a single block.
When you see labels lblnext, lblcell and friends being defined,
you're in core routines territory. The goal of these core
routines is to support all word types as described in
HAL and Reserved registers
Most of Collapse OS' native code is written using the HAL. See
If you are reading real CPU-specific native code, you should be
aware of that CPU's register roles. See doc/impl.txt and the the
CPU-specific document of doc/code/.
Most comments in Collapse OS describe the expected stack at a
point in time. Those comments almost always describe PS with
Top-Of-Stack being the rightmost element. For example, a
"( a b c )" indicate that at this point, we expect a PS of at
least 3 items with "c" being on top of it.
When we play with the Return Stack, we'll also include its sig-
nature with "R:". Example: ( a b R:c d ) means that b is PS'
TOS and d is RS' TOS.
Those elements can be seen (and are often called such) as
Names used for those variables are contextual. They're supposed
to be context-obvious, but to allow more compactness, some
conventions are used:
* A repeat of a previous variable are often 1 or 2 letters. For
example, "firstchar" would become "fc" in following comments.
* "a" is an address.
* "sa sl" is an unpacked string. 2 elements in the stack, sl
being the length, sa being the address of sl characters.
* "w" is a "word reference" it points to the word's type byte.
* "b" is a byte, "c" is a char (also a byte). You can generally
assume the MSB to be 0.
* "n" is a cell-sized (2 bytes) number.
* "u" is a byte count. Often used in ranges.
* "f" is a boolean flag. 0 is false, nonzero if true.
* "r" is a "result", often an accumulator in an algorithm.
* For clarity purposes, the result of complex processing is
often described in comments (ex: "a*b+c"), but only once.
* In loops, for clarity purposes, the same stack comment is
often put at the beginning and end of the loop to show that
we're looping in a balanced manner.
* We indent by 2 (used to be 4) spaces in word defs, loops,
conditions. We do it loosely though: we often don't have
enough screen space to do it strictly.
* Before a DO, when range arguments come from PS, we often add
a comment describing which "variable" is used for range.
Example: "( cnt ) 0 DO ... LOOP". We can also see this
pattern sometimes in assembler code when writing an hardcoded
address put on PS at compile-time.
Driver code has to be the hardest to read. It is often deeply
tied to the way hardware is organized. For compactness reasons,
we keep comments terse, and on top of that, we can't have
complete hardware specifications in Collapse OS itself. There-
fore, it is highly recommended to have technical specifications
handy when trying to read this code.
In the hardware documentation ("hw" folder), we try to document
hardware specs directly related to driver code, but this kind
of documentation is always going to be incomplete.
Here are some common patterns you'll see:
<<8 >>8: removes MSB. Faster than "$ff AND".
>>8 IF: Checks if MSB > 0. Faster than "$ff >".
This page generated at 2021-09-19 21:05:03 from documentation in CollapseOS snapshot 20210917.