izaya/collapseos
1
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Pimp up the docs a little bit

Browse Source
This commit is contained in:
Virgil Dupras 2019-10-04 12:05:05 -04:00
parent c96c8e7df0
commit 55be698f61
2 changed files with 31 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
doc/blockdev.md
View File

@ -1,8 +1,8 @@
# Using block devices # Using block devices
The `blockdev.asm` part manage what we call "block devices", an abstraction over 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 something that we can read a byte to, write a byte to, optionally at arbitrary
which offset we will read/write to next). offsets.
A Collapse OS system can define up to `0xff` devices. Those definitions are made A Collapse OS system can define up to `0xff` devices. Those definitions are made
in the glue code, so they are static. in the glue code, so they are static.
@ -13,29 +13,33 @@ Definition of block devices happen at include time. It would look like:
BLOCKDEV_COUNT .equ 1 BLOCKDEV_COUNT .equ 1
#include "blockdev.asm" #include "blockdev.asm"
; List of devices ; List of devices
.dw aciaGetC, aciaPutC, 0 .dw aciaGetC, aciaPutC
[...] [...]
That tells `blockdev` that we're going to set up one device, that its GetC and 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. PutC are the ones defined by `acia.asm`.
blockdev routines defined as zero are dummies (we don't actually call `0x0000`). If your block device is read-only or write-only, use dummy routines. `unsetZ`
is a good choice since it will return with the `Z` flag set, indicating an
error (dummy methods aren't supposed to be called).
Each defined block device, in addition to its routine definition, holds a
seek pointer. This seek pointer is used in shell commands described below.
## Routine definitions ## Routine definitions
Parts that implement GetC, PutC and Seek do so in a loosely-coupled manner, but Parts that implement GetC and PutC do so in a loosely-coupled manner, but
they should try to adhere to the convention, that is: they should try to adhere to the convention, that is:
**GetC**: Get a character at current position, advance the position by 1, then **GetC**: Get the character at position specified by `HL`. If it supports 32-bit
return the fetched character in register `A`. If no input is addressing, `DE` contains the high-order bytes. Return the result in
available, block until it is (in other words, we always get a valid `A`. If there's an error (for example, address out of range), set `Z`.
character). This routine is not expected to block. We expect the result to be
immediate.
**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`.
**PutC**: The opposite of GetC. Write the character in `A` at specified
position. `Z` set on error.
## Shell usage ## Shell usage
`blockdev.asm` supplies 4 shell commands that you can graft to your shell thus: `blockdev.asm` supplies 4 shell commands that you can graft to your shell thus:
@ -49,9 +53,10 @@ they should try to adhere to the convention, that is:
### bsel ### bsel
`bsel` select the active block device. For now, this only affects `load`. It `bsel` select the active block device. This specify a target for `load` and
receives one argument, the device index. `bsel 0` selects the first defined `save`. Some applications also use the active blockdev. It receives one
device, `bsel 1`, the second, etc. Error `0x04` when argument is out of bounds. 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
@ -69,11 +74,15 @@ active blockdev at its current position. If it hits the end of the blockdev
before it could load its specified number of bytes, it stops. It only raises an before it could load its specified number of bytes, it stops. It only raises an
error if it couldn't load any byte. error if it couldn't load any byte.
It moves the device's position to the byte after the last loaded byte.
### save ### save
`save` is the opposite of `load`. It writes the specified number of bytes from `save` is the opposite of `load`. It writes the specified number of bytes from
memory to the active blockdev at its current position. memory to the active blockdev at its current position.
It moves the device's position to the byte after the last written byte.
### Example ### Example
Let's try an example: You glue yourself a Collapse OS with ACIA as its first Let's try an example: You glue yourself a Collapse OS with ACIA as its first

5
doc/shell.md
View File

@ -35,6 +35,9 @@ table describes those codes:
| `04` | Unsupported command | | `04` | Unsupported command |
| `05` | I/O error | | `05` | I/O error |
Applications have their own error codes as well. If you see an error code that
isn't in this list, it's an application-specific error code.
## mptr ## mptr
The shell has a global memory pointer (let's call it `memptr`) that is used by The shell has a global memory pointer (let's call it `memptr`) that is used by
@ -83,7 +86,7 @@ in your glue code a `jp printstr` at `0x0004`:
> mptr a000 > mptr a000
A000 A000
> load 6 > poke 6
Hello\0 (you can send a null char through a terminal with CTRL+@) Hello\0 (you can send a null char through a terminal with CTRL+@)
> mptr 0004 > mptr 0004
0004 0004