The BLK subsystem

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>.

Most blocks contain code. That code can be interpreted through
LOAD. LOAD operations cannot be nested, that is, you can't call
LOAD from a block or you can't call a word that calls LOAD from
a block.

Using blocks

You will typically interact in 2 main ways with blocks: LISTing
them or LOADing them. You LIST a block with a block number
argument. For example, "0 LIST" spits the master index block.

LOAD interprets the specified block as if you typed it. You also
invoke it with a block number. "42 LOAD" reads block 42 in the
buffer and, for each of the 16 lines, interprets it as if it
was typed in the input buffer.

You can see the whole list of words supplied by the BLK sub-
system at doc/dict.

Exploring blocks

Block 0 in Collapse OS is a text block describing the whole
contents in all blocks, organized in sections. Sections are
typically 5, 10 or 20 blocks in size.

The first line of each block is often a comment describing the
contents of the block. To take advantage of this, we have the
INDEX word which prints the first line of each block in a range.

So, for example, if you see in the master index that Collapse OS
core words spans from B210 to B229 and you want to quickly find
a word in it, you'd run "210 229 INDEX".

LOADing applications

The first block of each section (a section often contains an
application) will typically contain loading instructions in
comments. These generally involve "application loaders", words
that LOAD the appropriate blocks for the application to be
loaded in memory.

The BLK subsystem contains these loader words:

ED     Text editor (doc/ed)
VE     Visual text editor (doc/ed)
ME     Memory editor (doc/me)
XCOMP  Cross-compilation tools (doc/cross)
ARCHM  Arch-specific macros, constants and loaders (doc/arch)
RXTX   Serial communication tools (doc/rxtx)

For example, it has the "VE" word which loads VE. Therefore, on
a freshly booted system, if you want to run VE, simply type
"VE". IF VE isn't loaded yet, it will LOAD. If it is loaded, it
will run.

Some of these words, such as ARCHM are "doors" opening the way
to further loader words, such as assemblers (doc/asm/intro).

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. B0 is a textual master index of blocks. LIST it to see the
   whole contents of the blkfs.
2. B1-B199 are for applications.
4. B200-B299 are for arch-independent cross-compiled code, inc-
   luding xcomp tools and subsystems.
5. B300+ is for arch-specific code.

In the POSIX package of Collapse OS, arch-specific code is kept
in separate "blk.fs" files so that depending on the arch being
built, the content of B300+ varies.

B300 is always an "arch-specific" master index and B301 is
always the "macros" block for this architecture (the block
you want to load before XCOMPC during bootstrapping). This block
defines all subsequent loader words for this archtecture.

When collapse comes and you want to build your final Collapse OS
media, you'll probably want to keep all arch-specific contents
at once. You will then need to organize those blocks yourself in
the way you see fit.

The BLK subsystem enables disk access and provides all disk-
related words (LOAD, LIST, FLUSH, etc.).

Including the BLK subsystem in a kernel

Before assembling, this requires 3 words:

BLK_MEM: where the 1024 bytes block buffer will live as well as
         BLK variables. The total size used is $409 bytes.

(blk@) blkno dest --  Reads blkno into dest (almost always BLK(
                      is passed there).
(blk!) blkno dest --  Write contents of buffer at dest into
                      blkno.

Then, you can call BLKSUB in your xcomp unit.

These are the variables defined in BLKSUB:

BLK>    Currently active block number
BLKDTY  Whether current block is dirty (needs to be saved on
        FLUSH). Nonzero means dirty.
BLKIN>  Upon LOAD, old IN> value is saved there so that when
        LOAD is finished, we can restore it and continue
        interpreting INBUF where we were.
BLK(    Address of the BLK buffer.
BLK)    Address where the BLK buffer ends.

Some subsystems provide an implementation to the BLK protocol:

* SD card subsystem (doc/sdcard)