Add the runrom crate and the vnf library

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à <mssola@mssola.com>

3 files changed, 267 insertions, 0 deletions

diff --git a/crates/runrom/Cargo.toml b/crates/runrom/Cargo.toml
new file mode 100644
index 0000000..e1c70fc
--- /dev/null
+++ b/crates/runrom/Cargo.toml
@@ -0,0 +1,10 @@
+[package]
+name = "runrom"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+
+[dependencies]
+header.workspace = true
+vnf.workspace = true
\ No newline at end of file
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 <your-game-path>/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.
diff --git a/crates/runrom/src/main.rs b/crates/runrom/src/main.rs
new file mode 100644
index 0000000..ab1ea83
--- /dev/null
+++ b/crates/runrom/src/main.rs
@@ -0,0 +1,225 @@
+use header::Header;
+use std::fs::File;
+use std::io::{ErrorKind, Read, Seek, SeekFrom};
+use vnf::{Machine, MemoryInitialValue, MemoryPolicy};
+
+/// Version for this program.
+const VERSION: &str = "0.1.0";
+
+#[derive(Default)]
+struct Args {
+    file: String,
+    start: Option<u16>,
+    assume_function: bool,
+    dump_memory: bool,
+}
+
+fn print_help() {
+    println!("Run an NES/Famicom ROM to test its code under a set of conditions.\n");
+    println!("usage: runrom [OPTIONS] <FILE>\n");
+    println!("Options:");
+    println!("  -d, --dump-memory\tShow the memory that has changed after a run.");
+    println!("  -f, --function\tRun the code by assuming it's a function.");
+    println!("  -h, --help\t\tPrint this message and quit.");
+    println!("  -s, --start\t\tAddress from where to start (default: reset vector).");
+    println!("  -v, --version\t\tPrint version information.");
+    std::process::exit(0);
+}
+
+// Print the given `message` and exit(1).
+fn die(message: String) {
+    eprintln!("error: {message}");
+    std::process::exit(1);
+}
+
+fn parse_hex_digit(c: char) -> Result<u16, String> {
+    match c.to_digit(16) {
+        Some(val) => Ok(val as u16),
+        None => Err("cannot convert digit to hexadecimal".to_string()),
+    }
+}
+
+fn parse_hex_argument(given: &str) -> Result<u16, String> {
+    // Skip a leading '$' character.
+    let arg = if given.starts_with('$') {
+        given.get(1..).unwrap_or("")
+    } else {
+        given
+    };
+    let mut chars = arg.chars();
+
+    match arg.len() {
+        0 => Err("you need to provide an address".to_string()),
+        1 => Ok(parse_hex_digit(chars.next().unwrap())?),
+        2 => Ok((parse_hex_digit(chars.next().unwrap())? << 4)
+            + (parse_hex_digit(chars.next().unwrap())?)),
+        3 => Ok((parse_hex_digit(chars.next().unwrap())? << 8)
+            + (parse_hex_digit(chars.next().unwrap())? << 4)
+            + (parse_hex_digit(chars.next().unwrap())?)),
+        4 => Ok((parse_hex_digit(chars.next().unwrap())? << 12)
+            + (parse_hex_digit(chars.next().unwrap())? << 8)
+            + (parse_hex_digit(chars.next().unwrap())? << 4)
+            + (parse_hex_digit(chars.next().unwrap())?)),
+        _ => Err("hex literal is too big".to_string()),
+    }
+}
+
+fn parse_arguments() -> Args {
+    let mut args = std::env::args();
+    let mut res = Args::default();
+
+    // Skip command name.
+    args.next();
+
+    while let Some(arg) = args.next() {
+        match arg.as_str() {
+            "-h" | "--help" => print_help(),
+            "-s" | "--start" => {
+                if res.start.is_some() {
+                    die("do not specify the '-s/--start' flag twice".to_string());
+                }
+                let Some(val) = args.next() else {
+                    die("you need to specify a value for the -s/--start flag!".to_string());
+                    return res;
+                };
+                match parse_hex_argument(&val) {
+                    Ok(n) => res.start = Some(n),
+                    Err(e) => die(e),
+                }
+            }
+            "-d" | "--dump-memory" => {
+                res.dump_memory = true;
+            }
+            "-f" | "--function" => {
+                res.assume_function = true;
+            }
+            "-v" | "--version" => {
+                println!("runrom {VERSION}");
+                std::process::exit(0);
+            }
+            _ => {
+                if arg.starts_with('-') {
+                    die(format!("don't know how to handle the '{arg}' flag"));
+                }
+                if !res.file.is_empty() {
+                    die("cannot have multiple source files".to_string());
+                }
+                res.file = arg;
+            }
+        }
+    }
+
+    if res.file.is_empty() {
+        die("you need to specify the file to be run".to_string());
+    }
+
+    res
+}
+
+// Given a ROM file identified by the `file` parameter, fetch the 16-bit address
+// as pointed out by the reset vector.
+fn start_from_reset_vector(file: &String) -> u16 {
+    // 1. Read the ROM header so we fetch the size of PRG ROM.
+
+    let Ok(mut input) = File::open(file) else {
+        die(format!("failed to open the given file '{file}'"));
+        return 0;
+    };
+
+    let mut buf = vec![0u8; 0x10];
+    if let Err(e) = input.read_exact(&mut buf) {
+        match e.kind() {
+            ErrorKind::UnexpectedEof => die("malformed ROM file".to_string()),
+            _ => die(e.to_string()),
+        }
+    }
+
+    let header = match Header::try_from(buf.as_slice()) {
+        Ok(h) => h,
+        Err(e) => {
+            die(e.to_string());
+            return 0;
+        }
+    };
+
+    // 2. With a known PRG ROM size, fetch the two bytes pertaining to the reset
+    // vector.
+
+    // The two bytes of the reset address are located as follows:
+    //   1. Skip the ROM header, guaranteed to be exactly 0x10 bytes long.
+    //   2. Go to the end of PRG ROM.
+    //   3. -6: NMI addres; -4: reset addres; -2: IRQ address.
+    let offset: u64 = (0x10 + (header.prg_rom_size * 16 * 1024) - 4)
+        .try_into()
+        .unwrap();
+
+    if input.seek(SeekFrom::Start(offset)).is_err() {
+        die("cannot peek into the ROM's reset address".to_string());
+        return 0;
+    };
+    let mut buf = [0u8; 0x02];
+    if let Err(e) = input.read_exact(&mut buf) {
+        match e.kind() {
+            ErrorKind::UnexpectedEof => die("malformed ROM file".to_string()),
+            _ => die(e.to_string()),
+        }
+    }
+
+    ((buf[1] as u16) << 8) + buf[0] as u16
+}
+
+fn run(file: &String, start: u16, assume_function: bool, dump_memory: bool) -> Result<(), String> {
+    let mut machine = Machine::from(
+        file,
+        start,
+        #[allow(clippy::single_range_in_vec_init)]
+        MemoryPolicy {
+            initial_value: MemoryInitialValue::Fixed(0),
+            allowed_reads: vec![(0..0x800)],
+            allowed_writes: vec![(0..0x800)],
+            minimum_stack_value: 0,
+        },
+    )?;
+    machine.verbose = true;
+
+    if assume_function {
+        machine.run_function()?;
+    } else {
+        machine.until_address(0xFFFF)?;
+    }
+
+    if dump_memory {
+        let mut title = false;
+
+        for (idx, cell) in machine.ram.iter().enumerate() {
+            if cell.reads > 0 || cell.writes > 0 {
+                if !title {
+                    println!("\n== Memory dump ==\n");
+                    title = true;
+                }
+
+                println!(
+                    "[${:X}] = ${:02X} [reads={}, writes={}]",
+                    idx, cell.value, cell.reads, cell.writes
+                );
+            }
+        }
+    }
+
+    Ok(())
+}
+
+fn main() {
+    let args = parse_arguments();
+    let start = match args.start {
+        Some(s) => s,
+        None => start_from_reset_vector(&args.file),
+    };
+
+    match run(&args.file, start, args.assume_function, args.dump_memory) {
+        Ok(m) => m,
+        Err(e) => {
+            die(e);
+        }
+    }
+}