Merge branch 'joamag/run-until' into 'master'

Support for address based testing

Closes #38

See merge request joamag/boytacean!41

.gitignore

@@ -1,11 +1,14 @@
 *.pyc
+*.pyd
 
 .DS_Store
 
 Cargo.lock
 
 /.vscode/settings.json
 
+/.eggs
+/.venv
 /.idea
 
 /ndk

.gitlab-ci.yml

@@ -79,6 +79,17 @@ test-rust:
     - rustc --version
     - cargo test
 
+test-pyo3:
+  stage: test
+  parallel:
+    matrix:
+      - RUST_VERSION: ["1.74.0"]
+  script:
+    - rustup toolchain install $RUST_VERSION
+    - rustup override set $RUST_VERSION
+    - rustc --version
+    - python3 setup.py test
+
 deploy-netlify-preview:
   stage: deploy
   script:

README.md

@@ -61,6 +61,12 @@ cargo build
 pip install .
 ```
 
+or
+
+```bash
+python setup.py install
+```
+
 ### WASM for Node.js
 
 ```bash

frontends/libretro/src/lib.rs

@@ -385,7 +385,7 @@ pub unsafe extern "C" fn retro_load_game(game: *const RetroGameInfo) -> bool {
     instance.set_mode(mode);
     instance.reset();
     instance.load(true);
-    instance.load_cartridge(rom);
+    instance.load_cartridge(rom).unwrap();
     update_vars();
     true
 }

frontends/sdl/src/main.rs

@@ -8,6 +8,7 @@ pub mod test;
 use audio::Audio;
 use boytacean::{
     devices::{printer::PrinterDevice, stdout::StdoutDevice},
+    error::Error,
     gb::{AudioProvider, GameBoy, GameBoyMode},
     info::Info,
     pad::PadKey,
@@ -225,7 +226,7 @@ impl Emulator {
         ));
     }
 
-    pub fn load_rom(&mut self, path: Option<&str>) {
+    pub fn load_rom(&mut self, path: Option<&str>) -> Result<(), Error> {
         let rom_path: &str = path.unwrap_or(&self.rom_path);
         let ram_path = replace_ext(rom_path, "sav").unwrap_or_else(|| "invalid".to_string());
         let rom = self.system.load_rom_file(
@@ -235,7 +236,7 @@ impl Emulator {
             } else {
                 None
             },
-        );
+        )?;
         println!(
             "========= Cartridge =========\n{}\n=============================",
             rom
@@ -253,12 +254,14 @@ impl Emulator {
             .to_str()
             .unwrap()
             .to_string();
+        Ok(())
     }
 
-    pub fn reset(&mut self) {
+    pub fn reset(&mut self) -> Result<(), Error> {
         self.system.reset();
         self.system.load(true);
-        self.load_rom(None);
+        self.load_rom(None)?;
+        Ok(())
     }
 
     pub fn apply_cheats(&mut self, cheats: &Vec<String>) {
@@ -418,7 +421,7 @@ impl Emulator {
                     Event::KeyDown {
                         keycode: Some(Keycode::R),
                         ..
-                    } => self.reset(),
+                    } => self.reset().unwrap(),
                     Event::KeyDown {
                         keycode: Some(Keycode::B),
                         ..
@@ -528,7 +531,7 @@ impl Emulator {
                         }
                         self.system.reset();
                         self.system.load(true);
-                        self.load_rom(Some(&filename));
+                        self.load_rom(Some(&filename)).unwrap();
                     }
                     _ => (),
                 }
@@ -989,7 +992,7 @@ fn main() {
     };
     let mut emulator = Emulator::new(game_boy, options);
     emulator.start(SCREEN_SCALE);
-    emulator.load_rom(Some(&args.rom_path));
+    emulator.load_rom(Some(&args.rom_path)).unwrap();
     emulator.apply_cheats(&args.cheats);
     emulator.toggle_palette();
 

frontends/web/ts/gb.ts

@@ -47,6 +47,9 @@ import info from "../package.json";
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 declare const require: any;
 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+declare const process: any;
+
 /**
  * The frequency at which the Game Boy emulator should
  * run "normally".

setup.py

@@ -35,6 +35,7 @@
     keywords="gameboy emulator rust",
     url="https://boytacean.joao.me",
     packages=["boytacean"],
+    test_suite="boytacean.test",
     package_dir={"": os.path.normpath("src/python")},
     rust_extensions=[
         setuptools_rust.RustExtension(

src/consts.rs

@@ -0,0 +1,5 @@
+// Timer registers
+pub const DIV_ADDR: u16 = 0xff04;
+pub const TIMA_ADDR: u16 = 0xff05;
+pub const TMA_ADDR: u16 = 0xff06;
+pub const TAC_ADDR: u16 = 0xff07;

src/gb.rs

@@ -426,57 +426,57 @@ impl GameBoy {
         let rom = self.rom().clone();
         self.reset();
         self.load(true);
-        self.load_cartridge(rom);
-    }
-
+        self.load_cartridge(rom).unwrap();
+    }
+
+    /// Advance the clock of the system by one tick, this will
+    /// usually imply executing one CPU instruction and advancing
+    /// all the other components of the system by the required
+    /// amount of cycles.
+    ///
+    /// This method takes into account the current speed of the
+    /// system (single or double) and will execute the required
+    /// amount of cycles in the other components of the system
+    /// accordingly.
+    ///
+    /// The amount of cycles executed by the CPU is returned.
     pub fn clock(&mut self) -> u16 {
         let cycles = self.cpu_clock() as u16;
         let cycles_n = cycles / self.multiplier() as u16;
-        if self.ppu_enabled {
-            self.ppu_clock(cycles_n);
-        }
-        if self.apu_enabled {
-            self.apu_clock(cycles_n);
-        }
-        if self.dma_enabled {
-            self.dma_clock(cycles);
-        }
-        if self.timer_enabled {
-            self.timer_clock(cycles);
-        }
-        if self.serial_enabled {
-            self.serial_clock(cycles);
-        }
+        self.clock_devices(cycles, cycles_n);
         cycles
     }
 
     /// Risky function that will clock the CPU multiple times
     /// allowing an undefined number of cycles to be executed
     /// in the other Game Boy components.
+    ///
     /// This can cause unwanted behaviour in components like
     /// the PPU where only one mode switch operation is expected
     /// per each clock call.
-    pub fn clock_m(&mut self, count: usize) -> u16 {
+    ///
+    /// At the end of this execution major synchronization issues
+    /// may arise, so use with caution.
+    pub fn clock_many(&mut self, count: usize) -> u16 {
         let mut cycles = 0u16;
         for _ in 0..count {
             cycles += self.cpu_clock() as u16;
         }
         let cycles_n = cycles / self.multiplier() as u16;
-        if self.ppu_enabled {
-            self.ppu_clock(cycles_n);
-        }
-        if self.apu_enabled {
-            self.apu_clock(cycles_n);
-        }
-        if self.dma_enabled {
-            self.dma_clock(cycles);
-        }
-        if self.timer_enabled {
-            self.timer_clock(cycles);
-        }
-        if self.serial_enabled {
-            self.serial_clock(cycles);
+        self.clock_devices(cycles, cycles_n);
+        cycles
+    }
+
+    /// Function equivalent to `clock()` but that allows pre-emptive
+    /// breaking of the clock cycle loop if the PC (Program Counter)
+    /// reaches the provided address.
+    pub fn clock_step(&mut self, addr: u16) -> u16 {
+        let cycles = self.cpu_clock() as u16;
+        if self.cpu_i().pc() == addr {
+            return cycles;
         }
+        let cycles_n = cycles / self.multiplier() as u16;
+        self.clock_devices(cycles, cycles_n);
         cycles
     }
 
@@ -503,14 +503,33 @@ impl GameBoy {
     pub fn step_to(&mut self, addr: u16) -> u32 {
         let mut cycles = 0u32;
         loop {
-            cycles += self.clock() as u32;
+            cycles += self.clock_step(addr) as u32;
             if self.cpu_i().pc() == addr {
                 break;
             }
         }
         cycles
     }
 
+    #[inline(always)]
+    fn clock_devices(&mut self, cycles: u16, cycles_n: u16) {
+        if self.ppu_enabled {
+            self.ppu_clock(cycles_n);
+        }
+        if self.apu_enabled {
+            self.apu_clock(cycles_n);
+        }
+        if self.dma_enabled {
+            self.dma_clock(cycles);
+        }
+        if self.timer_enabled {
+            self.timer_clock(cycles);
+        }
+        if self.serial_enabled {
+            self.serial_clock(cycles);
+        }
+    }
+
     pub fn key_press(&mut self, key: PadKey) {
         self.pad().key_press(key);
     }
@@ -1073,24 +1092,32 @@ impl GameBoy {
         Ok(())
     }
 
-    pub fn load_cartridge(&mut self, rom: Cartridge) -> &mut Cartridge {
+    pub fn load_cartridge(&mut self, rom: Cartridge) -> Result<&mut Cartridge, Error> {
         self.mmu().set_rom(rom);
-        self.mmu().rom()
+        Ok(self.mmu().rom())
     }
 
-    pub fn load_rom(&mut self, data: &[u8], ram_data: Option<&[u8]>) -> &mut Cartridge {
+    pub fn load_rom(
+        &mut self,
+        data: &[u8],
+        ram_data: Option<&[u8]>,
+    ) -> Result<&mut Cartridge, Error> {
         let mut rom = Cartridge::from_data(data);
         if let Some(ram_data) = ram_data {
             rom.set_ram_data(ram_data)
         }
         self.load_cartridge(rom)
     }
 
-    pub fn load_rom_file(&mut self, path: &str, ram_path: Option<&str>) -> &mut Cartridge {
-        let data = read_file(path).unwrap();
+    pub fn load_rom_file(
+        &mut self,
+        path: &str,
+        ram_path: Option<&str>,
+    ) -> Result<&mut Cartridge, Error> {
+        let data = read_file(path)?;
         match ram_path {
             Some(ram_path) => {
-                let ram_data = read_file(ram_path).unwrap();
+                let ram_data = read_file(ram_path)?;
                 self.load_rom(&data, Some(&ram_data))
             }
             None => self.load_rom(&data, None),
@@ -1176,12 +1203,12 @@ impl GameBoy {
         }));
     }
 
-    pub fn load_rom_wa(&mut self, data: &[u8]) -> Cartridge {
-        let rom = self.load_rom(data, None);
+    pub fn load_rom_wa(&mut self, data: &[u8]) -> Result<Cartridge, String> {
+        let rom = self.load_rom(data, None).map_err(|e| e.to_string())?;
         rom.set_rumble_cb(|active| {
             rumble_callback(active);
         });
-        rom.clone()
+        Ok(rom.clone())
     }
 
     pub fn load_callbacks_wa(&mut self) {

src/lib.rs

@@ -2,6 +2,7 @@
 
 pub mod apu;
 pub mod cheats;
+pub mod consts;
 pub mod cpu;
 pub mod data;
 pub mod devices;

src/py.rs

@@ -46,12 +46,18 @@ impl GameBoy {
             .map_err(PyErr::new::<PyException, _>)
     }
 
-    pub fn load_rom(&mut self, data: &[u8]) {
-        self.system.load_rom(data, None);
+    pub fn load_rom(&mut self, data: &[u8]) -> PyResult<()> {
+        self.system
+            .load_rom(data, None)
+            .map(|_| ())
+            .map_err(PyErr::new::<PyException, _>)
     }
 
-    pub fn load_rom_file(&mut self, path: &str) {
-        self.system.load_rom_file(path, None);
+    pub fn load_rom_file(&mut self, path: &str) -> PyResult<()> {
+        self.system
+            .load_rom_file(path, None)
+            .map(|_| ())
+            .map_err(PyErr::new::<PyException, _>)
     }
 
     pub fn read_memory(&mut self, addr: u16) -> u8 {
@@ -66,8 +72,12 @@ impl GameBoy {
         self.system.clock()
     }
 
-    pub fn clock_m(&mut self, count: usize) -> u16 {
-        self.system.clock_m(count)
+    pub fn clock_many(&mut self, count: usize) -> u16 {
+        self.system.clock_many(count)
+    }
+
+    pub fn clock_step(&mut self, addr: u16) -> u16 {
+        self.system.clock_step(addr)
     }
 
     pub fn clocks(&mut self, count: usize) -> u64 {

src/python/boytacean/boytacean.pyi

@@ -23,7 +23,8 @@ class GameBoy:
     def read_memory(self, addr: int) -> int: ...
     def write_memory(self, addr: int, value: int): ...
     def clock(self) -> int: ...
-    def clock_m(self, count: int) -> int: ...
+    def clock_many(self, count: int) -> int: ...
+    def clock_step(self, addr: int) -> int: ...
     def clocks(self, count: int) -> int: ...
     def next_frame(self) -> int: ...
     def step_to(self, addr: int) -> int: ...