collapseos/doc/fs.md

Using the filesystem

The Collapse OS filesystem (CFS) is a very simple FS that aims at implementation simplicity first. It is not efficient or featureful, but allows you to get play around with the concept of files so that you can conveniently run programs targeting named blocks of data with in storage.

The filesystem sits on a block device and there can only be one active filesystem at once.

Files are represented by adjacent blocks of 0x100 bytes with 0x20 bytes of metadata on the first block. That metadata tells the location of the next block which allows for block iteration.

To create a file, you must allocate blocks to it and these blocks can't be grown (you have to delete the file and re-allocate it). When allocating new files, Collapse OS tries to reuse blocks from deleted files if it can.

Once "mounted" (turned on with fson), you can list files, allocate new files with fnew, mark files as deleted with fdel and, more importantly, open files with fopn.

Opened files are accessed a independent block devices. It's the glue code that decides how many file handles we'll support and to which block device ID each file handle will be assigned.

For example, you could have a system with three block devices, one for ACIA and one for a SD card and one for a file handle. You would mount the filesystem on block device 1 (the SD card), then open a file on handle 0 with fopn 0 filename. You would then do bsel 2 to select your third block device which is mapped to the file you've just opened.

Trying it in the emulator

The shell emulator in tools/emul/shell is geared for filesystem usage. If you look at shell_.asm, you'll see that there are 4 block devices: one for console, one for fake storage (fsdev) and two file handles (we call them stdout and stdin, but both are read/write in this context).

The fake device fsdev is hooked to the host system through the cfspack utility. Then the emulated shell is started, it checks for the existence of a cfsin directory and, if it exists, it packs its content into a CFS blob and shoves it into its fsdev storage.

To, to try it out, do this:

$ mkdir cfsin
$ echo "Hello!" > cfsin/foo
$ echo "Goodbye!" > cfsin/bar
$ ./shell

The shell, upon startup, automatically calls fson targeting block device 1, so it's ready to use:

> fls
foo
bar
> mptr 9000
9000
> fopn 0 foo
> bsel 2
> load 5
> peek 5
656C6C6F21
> fdel bar
> fls
foo
>