Collapse OS Documentation Browser


asm/ code/ hw/ arch.txt avr.txt blk.txt blksrv.txt bootstrap.txt cross.txt design.txt dict.txt dis.txt drivers.txt ed.txt emul.txt faq.txt grid.txt hal.txt impl.txt intro.txt me.txt primer.txt ps2.txt rxtx.txt sdcard.txt sega.txt selfhost.txt spi.txt usage.txt

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

Including the BLK subsystem in a kernel

Before assembling, this requires 3 words:

BLK_ADDR: where the 1024 bytes block buffer will live. The xcomp
          unit defines it as SYSVARS - 1024 by default.

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

Then, you can call BLKSUB in your xcomp unit.

Some subsystems provide an implementation to the BLK protocol:

* SD card subsystem (doc/sdcard)

Collapse OS and its documentation are created by Virgil Dupras and licensed under the GNU GPL v3.

This documentation browser by James Stanley. Please report bugs on github or to

This page generated at 2022-01-16 21:05:03 from documentation in CollapseOS snapshot 20220115.