Update README, move challenge description

README.md

@@ -1,29 +1,49 @@
-
 # README
 
+-------------------------------------------------------
+### Overview
+This project is a custom emulator/VM, along with tooling such as an assembler, disassembler, and integrated debugger. It was originally written as a challenge for a CTF run by my school's computer security club. It has been refactored and reorganized. In the future, I _may_ reuse this challenge and modify it, mainly so that it cannot be unintentionally autosolved by the angr framework (as it was in its original form).
+
+For documentation on the assembly language and architecture, consult the relevant file(s) in `doc/`.
+* TODO: document assembly language
+
 -------------------------------------------------------
 ### Documentation
 See files in `/doc` for my design process, VM specs, lessons learned, and other stuff.
 
 -------------------------------------------------------
 ### Build
-Build competition/prod image (default):
+Build "normal" competition/prod image (default):
 `$ make`
 
-Build debug image (includes useful debugging capabilities):
-`$ make debug`
+Build trace image (integrates debugger into the build):
+`$ make trace`
+* Note: in-between making the normal and trace images, one should run `make cleano` to remove previous object files, since they'll differ between normal and trace builds
 
 Build disassembler:
 `$ make disass`
 
-The assembler, `ass.sh`, is already good to go (as good as a bad shell-scripted assembler can be at least)
+Build VM ROM:
+`$ make rom`
+* Note: if one updates the ROM assembly in rom.asm, they'll need to manually rebuild the ROM.
+
+The assembler, `ass.sh`, is already good to go (as good as a bad shell-scripted assembler can be at least).
 
 -------------------------------------------------------
 ### Run
 `$ ./bin/hard`
 or
-`$ ./bin/hard-debug`
+`$ ./bin/hard-trace`
 
-depending on which version you which to run.
+depending on which version you wish to run.
 
+-------------------------------------------------------
+### Tooling
+To use the debugger, simply build and run the trace image, as the binary will automatically place you in the debugger to start.
+
+The assembler, `ass.sh`, can be used to create a binary ROM image given an assembly language file (file extension `.asm`) and an optional zero page initialization file (`zeropage.incbin` in the challenge's case). The latter if present, is used to initialize the first 256 bytes of ROM to some hardcoded state.
+
+The disassembler, `disass`, is located in the `bin/` directory upon being made.
+
+For usage information for both tools, run them with no arguments.