Add filesystem docs
This commit is contained in:
parent
4f44d3de63
commit
71cbd24e1f
@ -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
doc/fs.md
Normal file
68
doc/fs.md
Normal 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…
Reference in New Issue
Block a user