From df1041d40431251e22e03ec5c4df7fc5767e1543 Mon Sep 17 00:00:00 2001 From: Miquel Sabaté Solà Date: Mon, 17 Aug 2026 16:03:21 +0200 Subject: Add the runrom crate and the vnf library MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The vnf library supports the runrom crate and they both combined enable users to "run" a ROM file. This is basically an emulator, but with two key differences: 1. It is to be run programatically. That is, you are not expected to play games with this, but to run code by steps, start at a given address, run a function, etc. 2. It is headless: there are no graphics displayed on screen, nor sound being delivered. Thus, the target for both these things are developers, not players. This way developers can validate code paths without needing a full blown emulator. You can write tests with this and be able to run some checks as part of your testing infrastructure. Signed-off-by: Miquel Sabaté Solà --- crates/runrom/README.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 crates/runrom/README.md (limited to 'crates/runrom/README.md') diff --git a/crates/runrom/README.md b/crates/runrom/README.md new file mode 100644 index 0000000..c5e7604 --- /dev/null +++ b/crates/runrom/README.md @@ -0,0 +1,32 @@ +This is yet another NES/Famicom emulator. Only this time around it's +specifically tailored to NES/Famicom developers, not players. + +First of all, the `vnf` library used for this binary exposes the virtual machine +with a proper interface. This way, you can run ROM files programmatically. Then, +`runrom` is just a wrapper on top of this library with a set of options that +toggle certain features from it. This is a nice thing to have if you don't need +to write very specific conditions with a tailored program. Second of all, +`runrom` runs with no graphics nor sound. That is, it runs headless. Thus, it +can be run on your testing infrastructure, so you can run continuous integration +on critical paths from your games. + +## Basic usage + +You can run a ROM file by simply: + +``` +$ runrom /game.nes +``` + +This will display all of the instructions being run. By default it will run from +the reset vector. You can change that with the `-s/--start` option, which +accepts a 16-bit address from where to start execution. + +That being said, most of the times you want to test a specific function. For +that, you can toggle the `-f/--function` option, which tells `runrom` that the +address is just a function and, whenever a top-level `rts`/`rti` instruction is +found, then execution can be halted. + +Moreover, you may also find interesting the `-d/--dump-memory` option, which +will display a summary of memory addresses which have been updated along +execution, and some statistics about them. -- cgit v1.2.3