nes-ram-debug-tool - File README.md
nes-ram-debug-tool
NES ROM for TKROM boards that extracts initial NES RAM data and stores it in battery backed PRG RAM
[GIT] git clone git://vigrey.com/git/nes-ram-debug-tool
README.md - (10275 Bytes)
# NES RAM Debug Tool
##### Version 0.0.1
NES ROM for TKROM boards that extracts initial NES RAM data and stores it in battery backed PRG RAM
**_NES RAM Debug Tool was created by Vi Grey (https://vigrey.com) <vi@vigrey.com> and is licensed under the BSD 2-Clause License._**
### Description:
An NES ROM for TKROM boards and an accompanying Python script to extract the initial NES CPU and PPU RAM data of an NES console on Power On. These tools are used to debug initial NES RAM and was created with the intention of studying how memory changes on an NES console. The initial RAM data will be saved into WRAM and is meant to be dumped with a NES Cartridge Dumper like InfiniteNESLives' INLRetro Dumper-Programmer (https://www.infiniteneslives.com/inlretro.php).
### Platforms:
- Linux
- macOS
- BSD
## NES ROM
### NES ROM Build Dependencies:
- asm6 _(You'll probably have to build asm6 from source. Make sure the asm6 binary is named **asm** and that the binary is executable and accessible in your PATH. The source code can be found at **http://3dscapture.com/NES/asm6.zip**)_
### Build NES ROM:
From a terminal, go to the the main directory of this project (the directory this README.md file exists in), you can then build the NES ROM with the following command.
$ make
The resulting NES ROM will be located at **bin/nes-ram-debug-tool.nes**
### Cleaning NES ROM Build Environment:
If you used `make` to build the NES ROM file, you can run the following command to clean up the build environment.
$ make clean
### NES ROM .sav File Syntax
**Offset values are based on the beginning of the .sav file (_$0000_), rather than the WRAM location data (_$6000_)**
The first 2KB of the .sav file (_$0000_-_$07FF_) is the first 2KB of CPU RAM (CPU _$0000_-_$07FF_)
The next 4KB of the .sav file (_$0800_-_$17FF_) is the 4KB of PPU nametable data (PPU _$2000_-_$2FFF_)
The next 32B of the .sav file (_$1800_-_$181F_) is the 32KB of PPU palette data (PPU _$3F00_-_$3F1F_)
The next 4B of the .sav file (_$1820_-_$1823_) is the CRC32 checksum of _$0000_-_$181F_ of the .sav file
Bytes _$1FF3_-_$1FFC_ will be `ViGreyTech` when the .sav file was created by the accompanying .sav Create Python script **sav-create.py**. If _$1FF3_-_$1FFC_ of the .sav file is `ViGreyTech` while playing this NES ROM on an NES Console, the stored CPU and PPU RAM data in the .sav file will be injected into the NES Console's CPU and PPU RAM.
Bytes _$1FFD_-_$1FFF_ will be a 6502 JMP instruction to a 16 bit start location address in CPU RAM (CPU _$0000_-_$07FD_) for a 3 byte infinite loop that will run from CPU RAM if Bytes _$1FF3_-_$1FFC_ of the .sav file is `ViGreyTech`. That infinite loop will allow the NES Cartridge to removed from the NES Console while the NES Console is still powered on and let the user insert another NES Game Cartridge to start the new NES Game with the injected CPU and PPU RAM.
## Accompanying Python Scripts
Included in this repository are python scripts that can be used with the NES ROM's .sav file. These files are stored in the **scripts** directory.
### Accompanying Python Script Dependencies:
- Python >= 3
## .sav RAM Extract Script
This script will extract the CPU and PPU RAM values from a the 8KB NES ROM WRAM .sav file.
### .sav RAM Extract Script Usage:
$ python3 sav-ram-extract.py -h
Usage: python3 sav-ram-extract.py [ OPTIONS ] <sav_file> [out_dir_path]
sav_file is the 8KB .sav file for you wish to extract from.
out_dir_path is an optional directory path to store the created CPU and
PPU RAM files in.
Options:
-h, --help Print Help (this message) and exit
--version Print version information and exit
Examples:
python3 sav-ram-extract.py nes-ram-debug-tool.sav
python3 sav-ram-extract.py ~/nes-ram-debug-tool.sav
python3 sav-ram-extract.py ~/nes-ram-debug-tool.sav ram/
python3 sav-ram-extract.py ~/nes-ram-debug-tool.sav ~/ram/
python3 sav-ram-extract.py ../nes-ram-debug-tool.sav ~/ram/
### .sav RAM Extract Script Output CPU/PPU RAM Files
When you use the **.sav RAM Extract Script**, two .ram files should be created, one CPU .ram file and one PPU .ram file. These file names will start with the date/time of file creation, followed by a dash, then cpu.ram or ppu.ram. These .ram files contain the initial editable CPU and PPU ram of the NES console on power on that was stored in the .sav file.
The CPU .ram file will be a 64KB file that stores the initial console CPU RAM state. Only console RAM data that is editable by the cartridge is properly stored, while everything else is replaced with `00` bytes. PRG ROM data is not stored in this file. Everything at and after _$2000_ in the CPU .ram file is replaced with `00` bytes.
The PPU .ram file will be a 16KB file that stores the initial console PPU RAM state. Only console RAM data that is editable by the cartridge is properly stored, while everything else is replaced with `00` bytes. CHR ROM data is not stored in this file. Everything before _$2000_ in the PPU .ram file is replaced with `00` bytes.
## .sav Create Script
This script convert a 64KB NES CPU RAM dump and 16KB NES PPU RAM dump into a WRAM .sav file for the NES ROM. When the NES ROM uses the resulting .sav file, the NES ROM will inject that RAM data into the NES Console's CPU and PPU RAM.
### .sav Create Script Usage
$ python3 sav-create.py -h
Usage: python3 sav-create.py [ OPTIONS ]... <cpu> <ppu> <sav_file>
cpu is the 64KB CPU RAM dump file to be injected into the NES.
ppu is the 16KB PPU RAM dump file to be injected into the NES.
sav_file is the 8KB .sav file you are creating using this script.
Options:
-h, --help Print Help (this message) and exit
-l, --loop Start hex address in CPU RAM (0000-07FD) for a 3 byte
loop that allows for cartridge swapping on an NES
Console with a disabled CIC Lockout Chip after RAM
injection to the console (Default value is 0100)
--version Print version information and exit
Examples:
python3 sav-create.py cpu.dmp ppu.dmp nes-ram-debug-tool.sav
python3 sav-create.py ~/cpu.dmp ~/ppu.dmp ~/nes-ram-debug-tool.sav
python3 sav-create.py -l 07F0 cpu.dmp ppu.dmp nes-ram-debug-tool.sav
python3 sav-create.py --loop 8A cpu.dmp ppu.dmp nes-ram-debug-tool.sav
python3 sav-create.py cpu.dmp ppu.dmp nes-ram-debug-tool.sav -l 8A
python3 sav-create.py cpu.dmp -l 8 ppu.dmp ../nes-ram-debug-tool.sav
python3 sav-create.py cpu.dmp ppu.dmp -l 200 ../nes-ram-debug-tool.sav
### Cartridge Swapping
When using a .sav file that was created with the **.sav Create Script** on an NES Cartridge and powering the NES Console on, the NES Cartridge will end up injecting the data stored in the .sav file into the NES CPU and PPU RAM. It will then run an infinite loop from memory. It is at this point where the user can remove the NES Cartridge while the NES Console is still powered on, place in a new cartridge, and hit the **RESET** button. If the NES Console has a disabled CIC Lockout Chip, the injected CPU and PPU RAM should be the initial RAM upon startup of the new cartridge.
**Please Note:** If the NES Console has a functioning CIC Lockout Chip, the console will power off and back on repeatedly until the reset button is pressed. This will cause the NES Console to break out of the infinite loop. CPU RAM also degrades over time while the cartridge is being swapped on an NES Console with a functioning CIC Lockout Chip. It is still possible to cartridge swap on an unmodified front loading NES Console, but be aware of likely RAM decay. If the NES Console has a disabled CIC Lockout Chip (like a modded front loader) or no CIC Lockout Chip at all (like the top loader NES-101 console model), the console should stay powered on running the infinite loop.
### Example Pre-Made .sav Files
Included in this repository are .sav files that can be used with the NES ROM. These example .sav files are stored in the **sav-examples** directory. You can use these example .sav files to inject predetermined RAM values in the NES Console's CPU and PPU RAM using the NES ROM when it is running in an NES Cartridge.
All example .sav files will create the infinite loop in the NES Console CPU memory for cartridge swapping at CPU _$0100_-_$0102_
### Special Thanks
- **DwangoAC** (https://tas.bot): For finally convincing me to make a tool like this after I have procrastinated on making a tool like this for many months
- **Brad Smith** (http://rainwarrior.ca): For providing me with tips and knowledge while streaming production of this
- **Paul Molloy** (https://infiniteneslives.com): For creating and providing the NES TKROM board for testing and use
### License:
Copyright (C) 2019, Vi Grey
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS \`\`AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.