Add user guide

README.md

@@ -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
+The project is progressing well and I already have a working shell (see `doc`
-project's roadmap is still hazy.
+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

doc/README.md

@@ -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)
+

doc/shell.md

@@ -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>