Emulates a MOS 6502 chip with an interactive debugger.
LIVE DEMO
Snake.mp4
Source Code for snake
- Clone the repository:
git clone https://github.com/ArchUsr64/6502_emulator - Change to newly created directory:
cd 6502_emulator - Run the emulator:
cargo run --release
Assemble one of the provided examples under examples/ using the provided python build script:
python build_asm.py examples/snake.asm
This should build an a.out binary which the emulator can understand along with symbols.dbg for debugging.
Run the emulator with the newly generated files:
cargo run -- -a examples/snake.asm -d symbols.dbg a.out
Click the 'Pause Execution' button in the Debug Controls window to pause the execution at any time or start in paused state via the -s flag.
Once paused, use the Step button to execute the next instruction. Add breakpoints from the 'Breakpoints' window and press the 'X' button to
remove previously added entires. Watchpoints can be used to observe and change memory addresses at runtime.
The symbols required for debugging are included in a newline delimited entries of line numbers and program counter addresses, with the addresses in hexadecimal.
For an example take a look at the provided symbols.dbg.
Usage: nemu [OPTIONS] [EXECUTABLE]
| Option | Description | Default |
|---|---|---|
| -v | Verbosity: Verbosity level for console logs | 0 (Errors only) |
| -s | Start debug: Stard the emulator in debug mode | false |
| -i | Instructions per frame: The number of CPU instructions to execute per rendered frame | 100 |
| -d | Debug symbols: Path for the file containing debug symbols | symbols.dbg |
| -a | Assembly source: Path for the assembly source file | examples/snake.asm |
Use WASD or the arrow keys to provide input events.
| Address | Description |
|---|---|
0xfb - 0xfe |
Keyboard Inputs stored here in: left, down, up, right order where 1 indicates KeyDown |
0xff |
Random Number Generator (Value is updated to a random byte on every instruction execution |
0x100 - 0x1ff |
Stack to store subroutine return addresses |
0xfb00 - 0xffff |
0x400 (1024) byte space to store the RGB values for pixels on a 32x32 grid in standard raster scan order |
Each color byte is divided into bit fields of size 3, 3 and 2. The bit field if size 2 is least significant and represents the blue color, with the most significant bit field representing red as shown below:
MSB LSB
^ ^
765 432 10
| | |
RRR GGG BB
- NesDev wiki for providing amazing documentation of the chip.
- Vasm as the assembler.
- Egui for making the debugger UI possible.
- Macroquad for providing an easy to use graphics API.
- Emulating a 6502 system in JavaScript • Matt Godbolt
- Assembly language vs. machine code - Ben Eater