From a002c494b77f4934829b0f2ddca0c6a7d241bdbf Mon Sep 17 00:00:00 2001 From: x1phosura Date: Tue, 27 Apr 2021 03:38:29 -0400 Subject: [PATCH] Update README, move challenge description --- README.md | 34 +++++++++++++++---- .../challenge-description.md | 0 2 files changed, 27 insertions(+), 7 deletions(-) rename challenge-description.md => doc/challenge-description.md (100%) diff --git a/README.md b/README.md index ccf30d2..14f6857 100644 --- a/README.md +++ b/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. diff --git a/challenge-description.md b/doc/challenge-description.md similarity index 100% rename from challenge-description.md rename to doc/challenge-description.md