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

# Exploring blocks

Blocks 0 and 1 in Collapse OS are text blocks 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. You
can work your way around following these instructions, or you
can take the easy way: application loaders. The BLK subsystem
has convenience words for loading applications at B234.

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.

# 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 and B1 are for a master index of blocks.
2. B2-B100 are for assemblers.
3. B100-B199 are for programs loaded at runtime.
4. B200-B299 are for arch-independent cross-compiled code, inc-
   luding xcomp tools.
5. B300+ is for arch-specific code.

In the POSIX package of Collapse OS, arch-specific code is kept
in separate ".blk" 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 XCOMPH 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.). See doc/usage.txt for
usage.

# 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)