mirror of
https://github.com/hsoft/collapseos.git
synced 2024-12-25 05:38:05 +11:00
Add user guide
This commit is contained in:
parent
26b125b337
commit
9aae4ea040
@ -104,13 +104,17 @@ There's very little done so far, but here's how it's organized:
|
||||
* `parts`: Pieces of code to be assembled by the user into an OS.
|
||||
* `recipes`: collection of recipes that assemble parts together on a specific
|
||||
machine.
|
||||
* `doc`: User guide for when you've successfully installed Collapse OS.
|
||||
|
||||
Each folder has a README with more details.
|
||||
|
||||
## Roadmap
|
||||
|
||||
I'm still fiddling with things, honing my skills and knowledge, so the
|
||||
project's roadmap is still hazy.
|
||||
The project is progressing well and I already have a working shell (see `doc`
|
||||
to see what it can do) on a classic RC2014.
|
||||
|
||||
However, such a vast project involves quite a lot of fiddling and I can't really
|
||||
have a precise roadmap, only a general direction:
|
||||
|
||||
The primary target for Collapse OS is the z80 architecture. There's a good
|
||||
amount of great z80-related hacks all around the internet, and the z80 CPU is
|
||||
|
10
doc/README.md
Normal file
10
doc/README.md
Normal file
@ -0,0 +1,10 @@
|
||||
# User Guide
|
||||
|
||||
This collection of document is intended to be a user guide, not assembly
|
||||
instructions. It is therefore assumed that you have a machine with Collapse OS
|
||||
properly running.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
* [The shell](shell.md)
|
||||
|
92
doc/shell.md
Normal file
92
doc/shell.md
Normal file
@ -0,0 +1,92 @@
|
||||
# shell
|
||||
|
||||
The shell is a text interface giving you access to commands to control your
|
||||
machine. It is not built to be user friendly, but to minimize binary space and
|
||||
maximize code simplicity.
|
||||
|
||||
We expect the user of this shell to work with a copy of the user guide within
|
||||
reach.
|
||||
|
||||
It is its design goal, however, to give you the levers you need to control your
|
||||
machine fully.
|
||||
|
||||
## Commands and arguments
|
||||
|
||||
You invoke a command by typing its name, followed by a list of arguments. All
|
||||
numerical arguments have to be typed in hexadecimal form, without prefix or
|
||||
suffix. Lowercase is fine. Single digit is fine for byte (not word) arguments
|
||||
smaller than `0x10`. Example calls:
|
||||
|
||||
seek 01ff
|
||||
peek 4
|
||||
load 1f
|
||||
call 00 0123
|
||||
|
||||
All numbers printed by the shell are in hexadecimals form.
|
||||
|
||||
Whenever a command is malformed, the shell will print `ERR` with a code. This
|
||||
table describes those codes:
|
||||
|
||||
| Code | Description |
|
||||
|------|---------------------------|
|
||||
| `01` | Unknown command |
|
||||
| `02` | Badly formatted arguments |
|
||||
|
||||
## seek
|
||||
|
||||
The shell has a global memory pointer (let's call it `memptr`) that is used by
|
||||
other commands. This pointer is 2 bytes long and starts at `0x0000`. To move
|
||||
it, you use the seek command with the new pointer position. The command
|
||||
prints out the new `memptr` (just to confirm that it has run). Example:
|
||||
|
||||
> seek 42ff
|
||||
42FF
|
||||
|
||||
## peek
|
||||
|
||||
Read memory targeted by `memptr` and prints its contents in hexadecimal form.
|
||||
This command takes one byte argument (optional, default to 1), the number of
|
||||
bytes we want to read. Example:
|
||||
|
||||
> seek 0040
|
||||
0040
|
||||
> peek 2
|
||||
ED56
|
||||
|
||||
## load
|
||||
|
||||
Puts the serial console in input mode and waits for a specific number of
|
||||
characters to be typed (that number being specified by a byte argument). These
|
||||
characters will be literally placed in memory, one after the other, starting at
|
||||
`memptr`.
|
||||
|
||||
This command is, for now, of limited use because it's tied to the active
|
||||
console, but a method for selecting I/O sources is planned and this command will
|
||||
become much more useful.
|
||||
|
||||
Example:
|
||||
|
||||
> load 5
|
||||
Hello
|
||||
> peek 5
|
||||
48656C6C6F
|
||||
|
||||
## call
|
||||
|
||||
Calls the routine at `memptr`, setting the `A` and `HL` registers to the value
|
||||
specified by its optional arguments (default to 0).
|
||||
|
||||
Be aware that this results in a call, not a jump, so your routine needs to
|
||||
return if you don't want to break your system.
|
||||
|
||||
The following example works in the case where you've made yourself a jump table
|
||||
in your glue code a `jp printstr` at `0x0004`:
|
||||
|
||||
> seek a000
|
||||
A000
|
||||
> load 6
|
||||
Hello\0 (you can send a null char through a terminal with CTRL+@)
|
||||
> seek 0004
|
||||
0004
|
||||
> call 00 a000
|
||||
Hello>
|
Loading…
Reference in New Issue
Block a user