Cleanup readme and add license for going public

README.md

@@ -1,10 +1,23 @@
+# About
+
+This is an exploratory project into virtual machines and assembly language. By
+no means is this ready for production use or particularly well maintained. The
+language is inspired by x86 and ARM assembly and does very little hand holding.
+
+Checkout the `bin/example.wasm` example source to get an overview of the
+language, or keep on reading!
+
 # Design
 
-## Parsing
+## From Text To Runtime Behaviour
 
-- First we tokenize the input (syntax check)
-- Then we interpret the input (semantics check)
-- Then we execute the input
+In order to turn the source text into executable code we use 3 passes:
+- Pass 1: tokenization (syntax check)
+- Pass 2: interpretation (semantics check)
+- Pass 3: execution (runtime check)
+
+After pass 2 ties to the source code are lost, meaning that any error occurring
+afterwards can be a bit cryptic as to where it originated.
 
 ## Notation
 
@@ -41,7 +54,7 @@ seti %A [$1024];
 ```
 Remember not to use spaces inside the `[` brackets.
 
-## Reserved symbols
+## Reserved Symbols
 
 The following whitespace characters are used to separate symbols:
 - space (` `)
@@ -55,37 +68,62 @@ The following characters are used as identifiers:
 - colon (`:`) for jump labels
 - semicolon (`;`) for statement termination
 - hash (`#`) for comments
+- square brackets (`[` and `]`) for addressing memory
 
-All symbols are reserved keywords and can therefore NOT be used as labels.
+## Memory Model
+
+The stack, with which you interact through pop/push operations, grows from
+memory location 0 to the end of the memory. There is no strict checking on
+whether your own memory operations through `[]` affect the stack: this is a
+feature, not a bug. Keep in mind that the stack can underflow and overflow
+and that the memory uses byte units (8 bits), whereas the registers are all
+32 bits wide. This means that reading from location `$900` overlaps with 3
+bytes when reading from location `$901` (the first byte of `$901` is the
+second byte of location `$900`).
 
 ## Symbols
 
+All symbols are reserved keywords and can therefore NOT be used as labels.
+There is currently no strict checking, so be careful.
+
 ## Directives
 
-- `DECLARE` declares the first label argument to equal the second, immediate value, argument and is used to declare a constant for the virtual machine.
+- `DECLARE` declares the first label argument to equal the second, immediate
+value, argument and is used to declare a constant for the virtual machine.
 
 ### Operands
 
-- `addi` add the first to the second argument and store the result in the third argument
-- `subi` subtract the first from the second argument and store the result in the third argument
-- `divi` divide the first by the second argument and store the result in the third argument
-- `muli` multiply the first by the second argument and store the result in the third argument
-- `shli` shift left the first argument by the number of positions given by the second argument and store the result in the third argument
-- `shri` shift right the first argument by the number of positions given by the second argument and store the result in the third argument
+- `addi` add the first to the second argument and store the result in the third
+argument
+- `subi` subtract the first from the second argument and store the result in
+the third argument
+- `divi` divide the first by the second argument and store the result in the
+third argument
+- `muli` multiply the first by the second argument and store the result in the
+third argument
+- `shli` shift left the first argument by the number of positions given by the
+second argument and store the result in the third argument
+- `shri` shift right the first argument by the number of positions given by the
+second argument and store the result in the third argument
 - `seti` set the first register argument to the second argument
 - `int` calls the interrupt specified by the first (integer) argument
 
 ### Control Flow
 
 - `jmp` jump to the label given by the first argument
-- `lti` execute next statement if argument 1 is less than argument 2 else skip the next statement
-- `gti` execute next statement if argument 1 is greater than argument 2 else skip the next statement
-- `eqi` execute the next statement if argument 1 is equal to argument 2 else skip the next statement
+- `lti` execute next statement if argument 1 is less than argument 2 else skip
+the next statement
+- `gti` execute next statement if argument 1 is greater than argument 2 else
+skip the next statement
+- `eqi` execute the next statement if argument 1 is equal to argument 2 else
+skip the next statement
 
 ## Memory
 
-- `popi` pops the first value on the stack into the register specified as the first argument
-- `pushi` pushes the value on the stack from the register or immediate value as the first argument
+- `popi` pops the first value on the stack into the register specified as the
+first argument
+- `pushi` pushes the value on the stack from the register or immediate value as
+the first argument
 
 ## Interupts
 
@@ -93,4 +131,5 @@ All symbols are reserved keywords and can therefore NOT be used as labels.
 	- `0` put value of register A as ASCII character on stdout
 	- `1` put value of register A as decimal integer on stdout
 	- `2` put value of register A as hexadecimal integer on stdout
-	- `3` put the string pointed at by register A for the amount of characters defined by register B on stdout
+	- `3` put the string pointed at by register A for the amount of characters
+	defined by register B on stdout