Update README, move challenge description
x1phosura x1phosura@x1phosura.zone
Tue, 27 Apr 2021 03:38:29 -0400
2 files changed,
27 insertions(+),
7 deletions(-)
M
README.md
→
README.md
@@ -1,5 +1,11 @@
+# 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). -# README +For documentation on the assembly language and architecture, consult the relevant file(s) in `doc/`. +* TODO: document assembly language ------------------------------------------------------- ### Documentation@@ -7,23 +13,37 @@ 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 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. -depending on which version you which to run. +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.