Browse Source

Add filesystem docs

pull/10/head
Virgil Dupras 5 years ago
parent
commit
71cbd24e1f
2 changed files with 70 additions and 1 deletions
  1. +2
    -1
      doc/README.md
  2. +68
    -0
      doc/fs.md

+ 2
- 1
doc/README.md View File

@@ -3,10 +3,11 @@
## Assembly guide

* [Writing the glue code](glue-code.md)
* [Running Collapse OS on an emulated RC2014](emulate.md)
* [Running Collapse OS on an emulator](emulate.md)

## User guide

* [The shell](shell.md)
* [Load code in RAM and run it](load-run-code.md)
* [Using block devices](blockdev.md)
* [Using the filesystem](fs.md)

+ 68
- 0
doc/fs.md View File

@@ -0,0 +1,68 @@
# 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
>

Loading…
Cancel
Save