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/src/main.rs | 225 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 225 insertions(+) create mode 100644 crates/runrom/src/main.rs (limited to 'crates/runrom/src') 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, + 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] \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 { + 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 { + // 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); + } + } +} -- cgit v1.2.3