50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# 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 "normal" competition/prod image (default):
|
|
`$ make`
|
|
|
|
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`
|
|
|
|
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-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.
|
|
|
|
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.
|
|
|