better dev experience and docs

Author: commonkestrel

.gitignore

@@ -1,5 +1,5 @@
 target
-fateful-cache
+.fateful-cache
 zig-cache
 zig-out
 /.vscode

README.md

@@ -5,6 +5,13 @@ Fateful is a CLI tool foring with my custom CPU, F8ful.
 It contains an emulator and an assembler.
 Fateful can be installed through [cargo](https://github.com/rust-lang/cargo) via `cargo install --git https://github.com/commonkestrel/fateful`.
 
+Running a program has two steps: assembly and emulation.
+To assemble a program, run `fateful assemble <program>.asm -o <program>.bin`
+If this is successful, you can emulate the program with `fateful emulate <program>.bin`
+The emulator is a REPL that contains various commands expalined (below)[#emulator].
+The most important command for emulating a program is `RUN`.
+Inputting `RUN 0` will run the assembly program as fast as possible until a halt is detected.
+
 ## Assembler
 
 The assembler can be used with the `fateful asm` or `fateful assemble` command to assembler f8ful assembly into f8ful machine code.
@@ -464,6 +471,9 @@ jnz 1
 
 ### Built-in Macros
 
+Built-in macros are a group of macros included by default in every program.
+The details of each macro can be found in (src/assembler/macros.asm)[./src/assembler/macros.asm].
+
 * [PUSH](#push-macro)
 * [POP](#pop-macro)
 * [PUSHA](#pusha-macro)
@@ -889,11 +899,24 @@ The input parameter provides the number of slots that the peripheral has been at
 #### Reading and Writing
 
 Peripherals can be written through a function with the signiture `void write(unsigned char, unsigned char)`.
+This function is called whenever the CPU writes to the given address or the address is `POKE`ed.
 The first parameter is the slot index that is being written to, and the second parameter is the value being written.
 
-Peripherals can be read from with a function with the signiture `unsigned char read(unsigned char)`
+Peripherals can be read from with a function with the signiture `unsigned char read(unsigned char)`.
+This function is called whenever the CPU reads from the given address or the address is `PEEK`ed at.
 The input parameter is the slot index that is being read from, and the return value should be the value at the slot.
 
+#### Drop
+
+Peripherals are dropped through a function with the signiture `void drop()`.
+This function is called when every address this peripheral is attached to is `DROP`ed, or the emulator is quit.
+This function *must* clean up any seperate threads before returning or the emulator will crash.
+
+#### Reset
+
+Peripherals are reset through a function with the signiture `void reset()`.
+This functions is called whenever the emulator resets the CPU.
+
 ### Errors
 
 Errors are only checked upon initialization - after both `init` and `stateful_init`.

examples/README.md

@@ -0,0 +1,33 @@
+# Examples
+
+This directory contains various examples to demonstrate the functionality of the emulator:
+
+## Box
+
+`box.asm` showcases many of the features of the language and emulator,
+including multiplication, conditional jumps, drawing to the screen, etc.
+
+This example draws a border with Unicode box-drawing characters along with a simple hello world:
+![box.asm output](../misc/box.png)
+
+## Fib
+
+`fib.asm` is a fibonacci sequence calculator that calculates the nth fibonacci number, where n=`COUNT`.
+The result is stored in the `D` register.
+
+This example also showcases the `test` functionality of the emulator,
+which will check that the final values of the registers match the expected values.
+
+## Mult
+
+`mult.asm` showcases multiplication through the [`math`](https://github.com/commonkestrel/fateful_math  ) library.
+This example calls the `mul16` "function" with the arguments `5` and `120`,
+storing the high and low bytes of the result in the `H` and `L` registers respectively.
+
+## Screen
+
+`screen.asm` is a relatively small program meant to show off the screen-drawing capabilities.
+This program loops through every character in the character set and prints them to the screen.
+
+This can be useful to see what looks nice together and get a feel for the character set of the emulator:
+![screen.asm output](../misc/screen.png)

examples/box.asm

@@ -13,7 +13,7 @@
 @define WALL 0xBA
 @define DASH 0xCD
 
-/// math = ./math
+/// math = https://github.com/commonkestrel/fateful_math
 @include <math/mul.asm>
 
 @cseg

examples/mul.asm

@@ -0,0 +1,15 @@
+/// Multiplies 5 and 120, storing the result in the H and L registers.
+///
+/// h: 0x02
+/// l: 0x58
+
+/// math = https://github.com/commonkestrel/fateful_math
+@include <math/mul.asm>
+
+@cseg
+@org 0x0000
+_start:
+    push 5, 0, 120, 0
+    call [mul16]
+    pop H, L
+    halt

examples/mult.asm

@@ -1,6 +1,10 @@
 { pkgs ? import <nixpkgs> {} }:
 
 pkgs.mkShell {
+  nativeBuildInputs = with pkgs; [
+	pkg-config
+  ];
+
   buildInputs = with pkgs; [
     openssl.dev
     openssl

math/mul.asm

@@ -15,7 +15,7 @@ use crate::{note, spanned_error};
 use clio::Input;
 use git2::Repository;
 
-const CACHE_DIR: &str = "fateful-cache";
+const CACHE_DIR: &str = ".fateful-cache";
 
 #[derive(Debug)]
 pub struct Lib {