collapseos/doc/blockdev.md

Using block devices

The blockdev.asm part manage what we call "block devices", an abstraction over something that we can read a byte to, write a byte to and seek into (select at which offset we will read/write to next).

A Collapse OS system can define up to 0xff devices. Those definitions are made in the glue code, so they are static.

Definition of block devices happen at include time. It would look like:

[...]
BLOCKDEV_COUNT .equ 1
#include "blockdev.asm"
; List of devices
.dw	aciaGetC, aciaPutC, 0
[...]

That tells blockdev that we're going to set up one device, that its GetC and PutC are the ones defined by acia.asm and that it has no Seek.

blockdev routines defined as zero are dummies (we don't actually call 0x0000).

Routine definitions

Parts that implement GetC, PutC and Seek do so in a loosely-coupled manner, but they should try to adhere to the convention, that is:

GetC: Get a character at current position, advance the position by 1, then return the fetched character in register A. If no input is available, block until it is (in other words, we always get a valid character).

PutC: The opposite of GetC. Write the character in A at current position and advance. If it can't write, block until it can.

Seek: Set current position (word) to value in register HL.

Shell usage

blockdev.asm supplies 2 shell commands that you can graft to your shell thus:

[...]
SHELL_EXTRA_CMD_COUNT	.equ	2
#include "shell.asm"
; extra commands
.dw	blkBselCmd, blkSeekCmd
[...]

bsel

bsel select the active block device. For now, this only affects load. It receives one argument, the device index. bsel 0 selects the first defined device, bsel 1, the second, etc. Error 0x04 when argument is out of bounds.

seek

seek receives one word argument and sets the pointer for the currently active device to the specified address. Example: seek 1234.

The device position is device-specific: if you seek on a device, then switch to another device and seek again, your previous position isn't lost. You will still be on the same position when you come back.

Example

Let's try an example: You glue yourself a Collapse OS with ACIA as its first device and a mmap starting at 0xd000 as your second device. Here's what you could do to copy memory around:

> mptr d000
D000
> load 4 [device 0 is selected initially]
[enter "abcd"]
> peek 4
61626364
> mptr c000
C000
> peek 4
[RAM garbage]
> bsel 1
> load 4
[returns immediately]
> peek 4
61626364
> seek 0002
> load 2
> peek 4
63646364

Awesome, right?