Improve flow of command-line debugging

Cargo.lock

@@ -28,6 +28,15 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "addr2line"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbe277e56a376000877090da837660b4427aad530e3028d44e0bffe4f89a1c1"
+dependencies = [
+ "gimli",
+]
+
 [[package]]
 name = "adler2"
 version = "2.0.0"
@@ -388,6 +397,24 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "atoi"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f28d99ec8bfea296261ca1af174f24225171fea9664ba9003cbebee704810528"
+dependencies = [
+ "num-traits",
+]
+
+[[package]]
+name = "atomic"
+version = "0.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d818003e740b63afc82337e3160717f4f63078720a810b7b903e70a5d1d2994"
+dependencies = [
+ "bytemuck",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -400,6 +427,21 @@ version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ace50bade8e6234aa140d9a2f552bbee1db4d353f69b8217bc503490fc1a9f26"
 
+[[package]]
+name = "backtrace"
+version = "0.3.74"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d82cb332cdfaed17ae235a638438ac4d4839913cc2af585c3c6746e8f8bee1a"
+dependencies = [
+ "addr2line",
+ "cfg-if",
+ "libc",
+ "miniz_oxide",
+ "object",
+ "rustc-demangle",
+ "windows-targets 0.52.6",
+]
+
 [[package]]
 name = "bindgen"
 version = "0.70.1"
@@ -1306,6 +1348,12 @@ dependencies = [
  "windows 0.58.0",
 ]
 
+[[package]]
+name = "gimli"
+version = "0.31.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07e28edb80900c19c28f1072f2e8aeca7fa06b23cd4169cefe1af5aa3260783f"
+
 [[package]]
 name = "gl_generator"
 version = "0.14.0"
@@ -1709,9 +1757,11 @@ checksum = "e2db585e1d738fc771bf08a151420d3ed193d9d895a36df7f6f8a9456b911ddc"
 
 [[package]]
 name = "lemur"
-version = "0.2.3"
+version = "0.2.5"
 dependencies = [
  "anyhow",
+ "atoi",
+ "atomic",
  "bitflags 2.6.0",
  "bytemuck",
  "cc",
@@ -1724,6 +1774,7 @@ dependencies = [
  "egui-winit",
  "egui_extras",
  "gilrs",
+ "hex",
  "image",
  "itertools",
  "num-derive",
@@ -1736,6 +1787,7 @@ dependencies = [
  "serde",
  "serde_json",
  "thread-priority",
+ "tokio",
  "wgpu",
  "windows 0.58.0",
  "winit",
@@ -1902,6 +1954,17 @@ dependencies = [
  "simd-adler32",
 ]
 
+[[package]]
+name = "mio"
+version = "1.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2886843bf800fba2e3377cff24abf6379b4c4d5c6681eaf9ea5b0d15090450bd"
+dependencies = [
+ "libc",
+ "wasi",
+ "windows-sys 0.52.0",
+]
+
 [[package]]
 name = "naga"
 version = "23.1.0"
@@ -2276,6 +2339,15 @@ dependencies = [
  "objc2-foundation",
 ]
 
+[[package]]
+name = "object"
+version = "0.36.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "62948e14d923ea95ea2c7c86c71013138b66525b86bdc08d2dcc262bdb497b87"
+dependencies = [
+ "memchr",
+]
+
 [[package]]
 name = "oboe"
 version = "0.6.1"
@@ -2696,6 +2768,12 @@ dependencies = [
  "realfft",
 ]
 
+[[package]]
+name = "rustc-demangle"
+version = "0.1.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "719b953e2095829ee67db738b3bfa9fa368c94900df327b3f07fe6e794d2fe1f"
+
 [[package]]
 name = "rustc-hash"
 version = "1.1.0"
@@ -2918,6 +2996,16 @@ dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "socket2"
+version = "0.5.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c970269d99b64e60ec3bd6ad27270092a5394c4e309314b18ae3fe575695fbe8"
+dependencies = [
+ "libc",
+ "windows-sys 0.52.0",
+]
+
 [[package]]
 name = "spirv"
 version = "0.3.0+sdk-1.3.268.0"
@@ -3070,6 +3158,33 @@ dependencies = [
  "zerovec",
 ]
 
+[[package]]
+name = "tokio"
+version = "1.42.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5cec9b21b0450273377fc97bd4c33a8acffc8c996c987a7c5b319a0083707551"
+dependencies = [
+ "backtrace",
+ "bytes",
+ "libc",
+ "mio",
+ "pin-project-lite",
+ "socket2",
+ "tokio-macros",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "693d596312e88961bc67d7f1f97af8a70227d9f90c31bba5806eec004978d752"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
 [[package]]
 name = "toml"
 version = "0.8.19"

Cargo.toml

@@ -4,11 +4,13 @@ description = "An emulator for the Virtual Boy."
 repository = "https://git.virtual-boy.com/PVB/lemur"
 publish = false
 license = "MIT"
-version = "0.2.3"
+version = "0.2.5"
 edition = "2021"
 
 [dependencies]
 anyhow = "1"
+atoi = "2"
+atomic = "0.6"
 bitflags = { version = "2", features = ["serde"] }
 bytemuck = { version = "1", features = ["derive"] }
 clap = { version = "4", features = ["derive"] }
@@ -20,6 +22,7 @@ egui-toast = { git = "https://github.com/urholaukkarinen/egui-toast.git", rev =
 egui-winit = "0.30"
 egui-wgpu = { version = "0.30", features = ["winit"] }
 gilrs = { version = "0.11", features = ["serde-serialize"] }
+hex = "0.4"
 image = { version = "0.25", default-features = false, features = ["png"] }
 itertools = "0.13"
 num-derive = "0.4"
@@ -32,6 +35,7 @@ rubato = "0.16"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 thread-priority = "1"
+tokio = { version = "1", features = ["io-util", "macros", "net", "rt", "sync"] }
 wgpu = "23"
 winit = { version = "0.30", features = ["serde"] }
 

scripts/release.sh

@@ -1,3 +1,4 @@
+set -e
 version=$(cat Cargo.toml | sed -n -e '/version/ {s/.* = *//p;q}' | tr -d '"')
 
 read -p "You wanted to release $version, right? [Y/n] " -n 1 -r
@@ -18,11 +19,15 @@ if ! command -v jq 2>&1 >/dev/null; then
     echo "Please install jq."
     exit 1
 fi
+if ! command -v docker 2>&1 >/dev/null; then
+    echo "Please install docker."
+    exit 1
+fi
 
 docker build -f build.Dockerfile -t lemur-build .
 MSYS_NO_PATHCONV=1 docker run -it --rm -v .:/app -w /app --entrypoint bash lemur-build /app/scripts/do-bundle.sh
 
-read -r -d EOF 'body' <<EOF
+body=$(cat <<EOF
 ## How to install
 
 The emulator can be found in the "Downloads" section of this release.
@@ -43,8 +48,9 @@ If you're not sure which to choose, use [this guide](https://support.apple.com/e
 
 You can either download and run \`lemur-linux\`, or download and install the attached .deb file.
 EOF
+)
 
-read -r -d EOF 'payload' <<EOF
+payload=$(cat <<EOF
 {
   "body": $(echo "$body" | jq -Rsa .),
   "draft": false,
@@ -53,6 +59,7 @@ read -r -d EOF 'payload' <<EOF
   "tag_name": "v${version}"
 }
 EOF
+)
 
 echo "Creating release..."
 response=$(curl -s --json "$payload" "https://git.virtual-boy.com/api/v1/repos/PVB/lemur/releases?token=$RELEASE_TOKEN")

src/app.rs

@@ -18,7 +18,7 @@ use crate::{
     emulator::{EmulatorClient, EmulatorCommand, SimId},
     input::MappingProvider,
     persistence::Persistence,
-    window::{AboutWindow, AppWindow, GameWindow, InputWindow},
+    window::{AboutWindow, AppWindow, GameWindow, GdbServerWindow, InputWindow},
 };
 
 fn load_icon() -> anyhow::Result<IconData> {
@@ -41,10 +41,15 @@ pub struct Application {
     persistence: Persistence,
     viewports: HashMap<ViewportId, Viewport>,
     focused: Option<ViewportId>,
+    init_debug_port: Option<u16>,
 }
 
 impl Application {
-    pub fn new(client: EmulatorClient, proxy: EventLoopProxy<UserEvent>) -> Self {
+    pub fn new(
+        client: EmulatorClient,
+        proxy: EventLoopProxy<UserEvent>,
+        debug_port: Option<u16>,
+    ) -> Self {
         let icon = load_icon().ok().map(Arc::new);
         let persistence = Persistence::new();
         let mappings = MappingProvider::new(persistence.clone());
@@ -63,6 +68,7 @@ impl Application {
             persistence,
             viewports: HashMap::new(),
             focused: None,
+            init_debug_port: debug_port,
         }
     }
 
@@ -80,15 +86,19 @@ impl Application {
 
 impl ApplicationHandler<UserEvent> for Application {
     fn resumed(&mut self, event_loop: &ActiveEventLoop) {
+        if let Some(port) = self.init_debug_port {
+            let mut server =
+                GdbServerWindow::new(SimId::Player1, self.client.clone(), self.proxy.clone());
+            server.launch(port);
+            self.open(event_loop, Box::new(server));
+        }
         let app = GameWindow::new(
             self.client.clone(),
             self.proxy.clone(),
             self.persistence.clone(),
             SimId::Player1,
         );
-        let wrapper = Viewport::new(event_loop, self.icon.clone(), Box::new(app));
+        self.open(event_loop, Box::new(app));
-        self.focused = Some(wrapper.id());
-        self.viewports.insert(wrapper.id(), wrapper);
     }
 
     fn window_event(
@@ -183,6 +193,11 @@ impl ApplicationHandler<UserEvent> for Application {
                 let about = AboutWindow;
                 self.open(event_loop, Box::new(about));
             }
+            UserEvent::OpenDebugger(sim_id) => {
+                let debugger =
+                    GdbServerWindow::new(sim_id, self.client.clone(), self.proxy.clone());
+                self.open(event_loop, Box::new(debugger));
+            }
             UserEvent::OpenInput => {
                 let input = InputWindow::new(self.mappings.clone());
                 self.open(event_loop, Box::new(input));
@@ -196,6 +211,9 @@ impl ApplicationHandler<UserEvent> for Application {
                 );
                 self.open(event_loop, Box::new(p2));
             }
+            UserEvent::Quit => {
+                event_loop.exit();
+            }
         }
     }
 
@@ -374,8 +392,10 @@ impl Drop for Viewport {
 pub enum UserEvent {
     GamepadEvent(gilrs::Event),
     OpenAbout,
+    OpenDebugger(SimId),
     OpenInput,
     OpenPlayer2,
+    Quit,
 }
 
 pub enum Action {

src/emulator.rs

@@ -1,34 +1,28 @@
 use std::{
     collections::HashMap,
+    fmt::Display,
     fs::{self, File},
     io::{Read, Seek, SeekFrom, Write},
+    ops::Range,
     path::{Path, PathBuf},
     sync::{
-        atomic::{AtomicBool, AtomicUsize, Ordering},
+        atomic::{AtomicBool, Ordering},
         mpsc::{self, RecvError, TryRecvError},
         Arc,
     },
 };
 
 use anyhow::Result;
+use atomic::Atomic;
+use bytemuck::NoUninit;
 use egui_toast::{Toast, ToastKind, ToastOptions};
 
 use crate::{audio::Audio, graphics::TextureSink};
-pub use shrooms_vb_core::VBKey;
+use shrooms_vb_core::{Sim, StopReason, EXPECTED_FRAME_SIZE};
-use shrooms_vb_core::{Sim, EXPECTED_FRAME_SIZE};
+pub use shrooms_vb_core::{VBKey, VBRegister};
 
 mod shrooms_vb_core;
 
-pub struct EmulatorBuilder {
-    rom: Option<PathBuf>,
-    commands: mpsc::Receiver<EmulatorCommand>,
-    sim_count: Arc<AtomicUsize>,
-    running: Arc<[AtomicBool; 2]>,
-    has_game: Arc<[AtomicBool; 2]>,
-    audio_on: Arc<[AtomicBool; 2]>,
-    linked: Arc<AtomicBool>,
-}
-
 #[derive(PartialEq, Eq, Hash, Clone, Copy, Debug)]
 pub enum SimId {
     Player1,
@@ -45,6 +39,14 @@ impl SimId {
         }
     }
 }
+impl Display for SimId {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            Self::Player1 => "Player 1",
+            Self::Player2 => "Player 2",
+        })
+    }
+}
 
 struct Cart {
     rom_path: PathBuf,
@@ -83,23 +85,35 @@ fn sram_path(rom_path: &Path, sim_id: SimId) -> PathBuf {
     }
 }
 
+pub struct EmulatorBuilder {
+    rom: Option<PathBuf>,
+    commands: mpsc::Receiver<EmulatorCommand>,
+    sim_state: Arc<[Atomic<SimState>; 2]>,
+    state: Arc<Atomic<EmulatorState>>,
+    audio_on: Arc<[AtomicBool; 2]>,
+    linked: Arc<AtomicBool>,
+    start_paused: bool,
+}
+
 impl EmulatorBuilder {
     pub fn new() -> (Self, EmulatorClient) {
         let (queue, commands) = mpsc::channel();
         let builder = Self {
             rom: None,
             commands,
-            sim_count: Arc::new(AtomicUsize::new(0)),
+            sim_state: Arc::new([
-            running: Arc::new([AtomicBool::new(false), AtomicBool::new(false)]),
+                Atomic::new(SimState::Uninitialized),
-            has_game: Arc::new([AtomicBool::new(false), AtomicBool::new(false)]),
+                Atomic::new(SimState::Uninitialized),
+            ]),
+            state: Arc::new(Atomic::new(EmulatorState::Paused)),
             audio_on: Arc::new([AtomicBool::new(true), AtomicBool::new(true)]),
             linked: Arc::new(AtomicBool::new(false)),
+            start_paused: false,
         };
         let client = EmulatorClient {
             queue,
-            sim_count: builder.sim_count.clone(),
+            sim_state: builder.sim_state.clone(),
-            running: builder.running.clone(),
+            state: builder.state.clone(),
-            has_game: builder.has_game.clone(),
             audio_on: builder.audio_on.clone(),
             linked: builder.linked.clone(),
         };
@@ -113,18 +127,27 @@ impl EmulatorBuilder {
         }
     }
 
+    pub fn start_paused(self, paused: bool) -> Self {
+        Self {
+            start_paused: paused,
+            ..self
+        }
+    }
+
     pub fn build(self) -> Result<Emulator> {
         let mut emulator = Emulator::new(
             self.commands,
-            self.sim_count,
+            self.sim_state,
-            self.running,
+            self.state,
-            self.has_game,
             self.audio_on,
             self.linked,
         )?;
         if let Some(path) = self.rom {
             emulator.load_cart(SimId::Player1, &path)?;
         }
+        if self.start_paused {
+            emulator.pause_sims()?;
+        }
         Ok(emulator)
     }
 }
@@ -134,13 +157,13 @@ pub struct Emulator {
     carts: [Option<Cart>; 2],
     audio: Audio,
     commands: mpsc::Receiver<EmulatorCommand>,
-    sim_count: Arc<AtomicUsize>,
+    sim_state: Arc<[Atomic<SimState>; 2]>,
-    running: Arc<[AtomicBool; 2]>,
+    state: Arc<Atomic<EmulatorState>>,
-    has_game: Arc<[AtomicBool; 2]>,
     audio_on: Arc<[AtomicBool; 2]>,
     linked: Arc<AtomicBool>,
     renderers: HashMap<SimId, TextureSink>,
     messages: HashMap<SimId, mpsc::Sender<Toast>>,
+    debuggers: HashMap<SimId, DebugInfo>,
     eye_contents: Vec<u8>,
     audio_samples: Vec<f32>,
 }
@@ -148,9 +171,8 @@ pub struct Emulator {
 impl Emulator {
     fn new(
         commands: mpsc::Receiver<EmulatorCommand>,
-        sim_count: Arc<AtomicUsize>,
+        sim_state: Arc<[Atomic<SimState>; 2]>,
-        running: Arc<[AtomicBool; 2]>,
+        state: Arc<Atomic<EmulatorState>>,
-        has_game: Arc<[AtomicBool; 2]>,
         audio_on: Arc<[AtomicBool; 2]>,
         linked: Arc<AtomicBool>,
     ) -> Result<Self> {
@@ -159,15 +181,15 @@ impl Emulator {
             carts: [None, None],
             audio: Audio::init()?,
             commands,
-            sim_count,
+            sim_state,
-            running,
+            state,
-            has_game,
             audio_on,
             linked,
             renderers: HashMap::new(),
             messages: HashMap::new(),
+            debuggers: HashMap::new(),
             eye_contents: vec![0u8; 384 * 224 * 2],
-            audio_samples: vec![0.0; EXPECTED_FRAME_SIZE],
+            audio_samples: Vec::with_capacity(EXPECTED_FRAME_SIZE),
         })
     }
 
@@ -198,17 +220,17 @@ impl Emulator {
         let index = sim_id.to_index();
         while self.sims.len() <= index {
             self.sims.push(Sim::new());
+            self.sim_state[index].store(SimState::NoGame, Ordering::Release);
         }
-        self.sim_count.store(self.sims.len(), Ordering::Relaxed);
         let sim = &mut self.sims[index];
         sim.reset();
         if let Some(cart) = new_cart {
             sim.load_cart(cart.rom.clone(), cart.sram.clone())?;
             self.carts[index] = Some(cart);
-            self.has_game[index].store(true, Ordering::Release);
+            self.sim_state[index].store(SimState::Ready, Ordering::Release);
         }
-        if self.has_game[index].load(Ordering::Acquire) {
+        if self.sim_state[index].load(Ordering::Acquire) == SimState::Ready {
-            self.running[index].store(true, Ordering::Release);
+            self.resume_sims();
         }
         Ok(())
     }
@@ -233,9 +255,31 @@ impl Emulator {
         self.linked.store(false, Ordering::Release);
     }
 
-    pub fn pause_sim(&mut self, sim_id: SimId) -> Result<()> {
+    fn pause_sims(&mut self) -> Result<()> {
-        self.running[sim_id.to_index()].store(false, Ordering::Release);
+        if self
-        self.save_sram(sim_id)
+            .state
+            .compare_exchange(
+                EmulatorState::Running,
+                EmulatorState::Paused,
+                Ordering::AcqRel,
+                Ordering::Relaxed,
+            )
+            .is_ok()
+        {
+            for sim_id in SimId::values() {
+                self.save_sram(sim_id)?;
+            }
+        }
+        Ok(())
+    }
+
+    fn resume_sims(&mut self) {
+        let _ = self.state.compare_exchange(
+            EmulatorState::Paused,
+            EmulatorState::Running,
+            Ordering::AcqRel,
+            Ordering::Relaxed,
+        );
     }
 
     fn save_sram(&mut self, sim_id: SimId) -> Result<()> {
@@ -253,13 +297,62 @@ impl Emulator {
         self.save_sram(SimId::Player2)?;
         self.renderers.remove(&SimId::Player2);
         self.sims.truncate(1);
-        self.sim_count.store(self.sims.len(), Ordering::Relaxed);
+        self.sim_state[SimId::Player2.to_index()].store(SimState::Uninitialized, Ordering::Release);
-        self.running[SimId::Player2.to_index()].store(false, Ordering::Release);
+        self.stop_debugging(SimId::Player2);
-        self.has_game[SimId::Player2.to_index()].store(false, Ordering::Release);
         self.linked.store(false, Ordering::Release);
         Ok(())
     }
 
+    fn start_debugging(&mut self, sim_id: SimId, sender: DebugSender) {
+        let debug = DebugInfo {
+            sender,
+            stop_reason: Some(DebugStopReason::Trapped),
+        };
+        self.debuggers.insert(sim_id, debug);
+        self.state
+            .store(EmulatorState::Debugging, Ordering::Release);
+    }
+
+    fn stop_debugging(&mut self, sim_id: SimId) {
+        if let Some(sim) = self.sims.get_mut(sim_id.to_index()) {
+            sim.clear_breakpoints();
+        }
+        self.debuggers.remove(&sim_id);
+        if self.debuggers.is_empty() {
+            let _ = self.state.compare_exchange(
+                EmulatorState::Debugging,
+                EmulatorState::Running,
+                Ordering::AcqRel,
+                Ordering::Relaxed,
+            );
+        }
+    }
+
+    fn debug_interrupt(&mut self, sim_id: SimId) {
+        self.debug_stop(sim_id, DebugStopReason::Trapped);
+    }
+
+    fn debug_stop(&mut self, sim_id: SimId, reason: DebugStopReason) {
+        let Some(debugger) = self.debuggers.get_mut(&sim_id) else {
+            self.stop_debugging(sim_id);
+            return;
+        };
+        if debugger.stop_reason != Some(reason) {
+            debugger.stop_reason = Some(reason);
+            if debugger.sender.send(DebugEvent::Stopped(reason)).is_err() {
+                self.stop_debugging(sim_id);
+            }
+        }
+    }
+
+    fn debug_continue(&mut self, sim_id: SimId) {
+        let Some(debugger) = self.debuggers.get_mut(&sim_id) else {
+            self.stop_debugging(sim_id);
+            return;
+        };
+        debugger.stop_reason = None;
+    }
+
     pub fn run(&mut self) {
         loop {
             let idle = self.tick();
@@ -289,9 +382,20 @@ impl Emulator {
 
     // returns true if the emulator is "idle" (i.e. this didn't output anything)
     pub fn tick(&mut self) -> bool {
-        let p1_running = self.running[SimId::Player1.to_index()].load(Ordering::Acquire);
+        let p1_state = self.sim_state[SimId::Player1.to_index()].load(Ordering::Acquire);
-        let p2_running = self.running[SimId::Player2.to_index()].load(Ordering::Acquire);
+        let p2_state = self.sim_state[SimId::Player2.to_index()].load(Ordering::Acquire);
-        let mut idle = p1_running || p2_running;
+        let state = self.state.load(Ordering::Acquire);
+
+        // Emulation
+        // Don't emulate if the state is "paused", or if any sim is paused in the debugger
+        let running = match state {
+            EmulatorState::Paused => false,
+            EmulatorState::Running => true,
+            EmulatorState::Debugging => self.debuggers.values().all(|d| d.stop_reason.is_none()),
+        };
+        let p1_running = running && p1_state == SimState::Ready;
+        let p2_running = running && p2_state == SimState::Ready;
+        let mut idle = !p1_running && !p2_running;
         if p1_running && p2_running {
             Sim::emulate_many(&mut self.sims);
         } else if p1_running {
@@ -300,6 +404,22 @@ impl Emulator {
             self.sims[SimId::Player2.to_index()].emulate();
         }
 
+        // Debug state
+        if state == EmulatorState::Debugging {
+            for sim_id in SimId::values() {
+                let Some(sim) = self.sims.get_mut(sim_id.to_index()) else {
+                    continue;
+                };
+                if let Some(reason) = sim.stop_reason() {
+                    let stop_reason = match reason {
+                        StopReason::Breakpoint => DebugStopReason::Breakpoint,
+                    };
+                    self.debug_stop(sim_id, stop_reason);
+                }
+            }
+        }
+
+        // Video
         for sim_id in SimId::values() {
             let Some(renderer) = self.renderers.get_mut(&sim_id) else {
                 continue;
@@ -314,24 +434,27 @@ impl Emulator {
                 }
             }
         }
+
+        // Audio
+        // Audio playback speed is how we keep the emulator running in real time.
+        // Even if we're muted, call `read_samples` to know how many frames of silence to play.
         let p1_audio =
             p1_running && self.audio_on[SimId::Player1.to_index()].load(Ordering::Acquire);
         let p2_audio =
             p2_running && self.audio_on[SimId::Player2.to_index()].load(Ordering::Acquire);
-        let weight = if p1_audio && p2_audio { 0.5 } else { 1.0 };
+        let (p1_weight, p2_weight) = match (p1_audio, p2_audio) {
-        if p1_audio {
+            (true, true) => (0.5, 0.5),
-            if let Some(sim) = self.sims.get_mut(SimId::Player1.to_index()) {
+            (true, false) => (1.0, 0.0),
-                sim.read_samples(&mut self.audio_samples, weight);
+            (false, true) => (0.0, 1.0),
-            }
+            (false, false) => (0.0, 0.0),
+        };
+        if let Some(sim) = self.sims.get_mut(SimId::Player1.to_index()) {
+            sim.read_samples(&mut self.audio_samples, p1_weight);
         }
-        if p2_audio {
+        if let Some(sim) = self.sims.get_mut(SimId::Player2.to_index()) {
-            if let Some(sim) = self.sims.get_mut(SimId::Player2.to_index()) {
+            sim.read_samples(&mut self.audio_samples, p2_weight);
-                sim.read_samples(&mut self.audio_samples, weight);
-            }
         }
-        if self.audio_samples.is_empty() {
+        if !self.audio_samples.is_empty() {
-            self.audio_samples.resize(EXPECTED_FRAME_SIZE, 0.0);
-        } else {
             idle = false;
         }
         self.audio.update(&self.audio_samples);
@@ -367,19 +490,50 @@ impl Emulator {
                 }
             }
             EmulatorCommand::Pause => {
-                for sim_id in SimId::values() {
+                if let Err(error) = self.pause_sims() {
-                    if let Err(error) = self.pause_sim(sim_id) {
+                    self.report_error(SimId::Player1, format!("Error pausing: {error}"));
-                        self.report_error(sim_id, format!("Error pausing: {error}"));
-                    }
                 }
             }
             EmulatorCommand::Resume => {
-                for sim_id in SimId::values() {
+                self.resume_sims();
-                    let index = sim_id.to_index();
+            }
-                    if self.has_game[index].load(Ordering::Acquire) {
+            EmulatorCommand::StartDebugging(sim_id, debugger) => {
-                        self.running[index].store(true, Ordering::Relaxed);
+                self.start_debugging(sim_id, debugger);
-                    }
+            }
-                }
+            EmulatorCommand::StopDebugging(sim_id) => {
+                self.stop_debugging(sim_id);
+            }
+            EmulatorCommand::DebugInterrupt(sim_id) => {
+                self.debug_interrupt(sim_id);
+            }
+            EmulatorCommand::DebugContinue(sim_id) => {
+                self.debug_continue(sim_id);
+            }
+            EmulatorCommand::ReadRegister(sim_id, register, done) => {
+                let Some(sim) = self.sims.get_mut(sim_id.to_index()) else {
+                    return;
+                };
+                let value = sim.read_register(register);
+                let _ = done.send(value);
+            }
+            EmulatorCommand::ReadMemory(sim_id, addresses, mut buffer, done) => {
+                let Some(sim) = self.sims.get_mut(sim_id.to_index()) else {
+                    return;
+                };
+                sim.read_memory(addresses, &mut buffer);
+                let _ = done.send(buffer);
+            }
+            EmulatorCommand::AddBreakpoint(sim_id, address) => {
+                let Some(sim) = self.sims.get_mut(sim_id.to_index()) else {
+                    return;
+                };
+                sim.add_breakpoint(address);
+            }
+            EmulatorCommand::RemoveBreakpoint(sim_id, address) => {
+                let Some(sim) = self.sims.get_mut(sim_id.to_index()) else {
+                    return;
+                };
+                sim.remove_breakpoint(address);
             }
             EmulatorCommand::SetAudioEnabled(p1, p2) => {
                 self.audio_on[SimId::Player1.to_index()].store(p1, Ordering::Release);
@@ -438,6 +592,14 @@ pub enum EmulatorCommand {
     StopSecondSim,
     Pause,
     Resume,
+    StartDebugging(SimId, DebugSender),
+    StopDebugging(SimId),
+    DebugInterrupt(SimId),
+    DebugContinue(SimId),
+    ReadRegister(SimId, VBRegister, oneshot::Sender<u32>),
+    ReadMemory(SimId, Range<u32>, Vec<u8>, oneshot::Sender<Vec<u8>>),
+    AddBreakpoint(SimId, u32),
+    RemoveBreakpoint(SimId, u32),
     SetAudioEnabled(bool, bool),
     Link,
     Unlink,
@@ -446,32 +608,63 @@ pub enum EmulatorCommand {
     Exit(oneshot::Sender<()>),
 }
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq, NoUninit)]
+#[repr(usize)]
+pub enum SimState {
+    Uninitialized,
+    NoGame,
+    Ready,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, NoUninit)]
+#[repr(usize)]
+pub enum EmulatorState {
+    Paused,
+    Running,
+    Debugging,
+}
+
+type DebugSender = tokio::sync::mpsc::UnboundedSender<DebugEvent>;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum DebugStopReason {
+    // We hit a breakpoint
+    Breakpoint,
+    // The debugger told us to pause
+    Trapped,
+}
+
+struct DebugInfo {
+    sender: DebugSender,
+    stop_reason: Option<DebugStopReason>,
+}
+
+pub enum DebugEvent {
+    Stopped(DebugStopReason),
+}
+
 #[derive(Clone)]
 pub struct EmulatorClient {
     queue: mpsc::Sender<EmulatorCommand>,
-    sim_count: Arc<AtomicUsize>,
+    sim_state: Arc<[Atomic<SimState>; 2]>,
-    running: Arc<[AtomicBool; 2]>,
+    state: Arc<Atomic<EmulatorState>>,
-    has_game: Arc<[AtomicBool; 2]>,
     audio_on: Arc<[AtomicBool; 2]>,
     linked: Arc<AtomicBool>,
 }
 
 impl EmulatorClient {
-    pub fn has_player_2(&self) -> bool {
+    pub fn sim_state(&self, sim_id: SimId) -> SimState {
-        self.sim_count.load(Ordering::Acquire) == 2
+        self.sim_state[sim_id.to_index()].load(Ordering::Acquire)
     }
-    pub fn is_running(&self, sim_id: SimId) -> bool {
+    pub fn emulator_state(&self) -> EmulatorState {
-        self.running[sim_id.to_index()].load(Ordering::Acquire)
+        self.state.load(Ordering::Acquire)
-    }
-    pub fn has_game(&self, sim_id: SimId) -> bool {
-        self.has_game[sim_id.to_index()].load(Ordering::Acquire)
-    }
-    pub fn are_sims_linked(&self) -> bool {
-        self.linked.load(Ordering::Acquire)
     }
     pub fn is_audio_enabled(&self, sim_id: SimId) -> bool {
         self.audio_on[sim_id.to_index()].load(Ordering::Acquire)
     }
+    pub fn are_sims_linked(&self) -> bool {
+        self.linked.load(Ordering::Acquire)
+    }
     pub fn send_command(&self, command: EmulatorCommand) -> bool {
         match self.queue.send(command) {
             Ok(()) => true,

src/emulator/shrooms_vb_core.rs

@@ -1,4 +1,4 @@
-use std::{ffi::c_void, ptr, slice};
+use std::{ffi::c_void, ops::Range, ptr, slice};
 
 use anyhow::{anyhow, Result};
 use bitflags::bitflags;
@@ -55,7 +55,16 @@ bitflags! {
     }
 }
 
+#[derive(Clone, Copy, Debug)]
+pub enum VBRegister {
+    Program(u32),
+    System(u32),
+    PC,
+}
+
 type OnFrame = extern "C" fn(sim: *mut VB) -> c_int;
+type OnExecute =
+    extern "C" fn(sim: *mut VB, address: u32, code: *const u16, length: c_int) -> c_int;
 
 #[link(name = "vb")]
 extern "C" {
@@ -77,6 +86,10 @@ extern "C" {
         right_stride_x: c_int,
         right_stride_y: c_int,
     );
+    #[link_name = "vbGetProgramCounter"]
+    fn vb_get_program_counter(sim: *mut VB) -> u32;
+    #[link_name = "vbGetProgramRegister"]
+    fn vb_get_program_register(sim: *mut VB, index: c_uint) -> i32;
     #[link_name = "vbGetSamples"]
     fn vb_get_samples(
         sim: *mut VB,
@@ -84,18 +97,24 @@ extern "C" {
         capacity: *mut c_uint,
         position: *mut c_uint,
     ) -> *mut c_void;
+    #[link_name = "vbGetSystemRegister"]
+    fn vb_get_system_register(sim: *mut VB, index: c_uint) -> i32;
     #[link_name = "vbGetUserData"]
     fn vb_get_user_data(sim: *mut VB) -> *mut c_void;
     #[link_name = "vbInit"]
     fn vb_init(sim: *mut VB) -> *mut VB;
+    #[link_name = "vbRead"]
+    fn vb_read(sim: *mut VB, address: u32, typ_: VBDataType) -> i32;
     #[link_name = "vbReset"]
     fn vb_reset(sim: *mut VB);
     #[link_name = "vbSetCartRAM"]
     fn vb_set_cart_ram(sim: *mut VB, sram: *mut c_void, size: u32) -> c_int;
     #[link_name = "vbSetCartROM"]
     fn vb_set_cart_rom(sim: *mut VB, rom: *mut c_void, size: u32) -> c_int;
+    #[link_name = "vbSetExecuteCallback"]
+    fn vb_set_execute_callback(sim: *mut VB, callback: Option<OnExecute>);
     #[link_name = "vbSetFrameCallback"]
-    fn vb_set_frame_callback(sim: *mut VB, on_frame: OnFrame);
+    fn vb_set_frame_callback(sim: *mut VB, callback: Option<OnFrame>);
     #[link_name = "vbSetKeys"]
     fn vb_set_keys(sim: *mut VB, keys: u16) -> u16;
     #[link_name = "vbSetOption"]
@@ -115,7 +134,7 @@ extern "C" {
     fn vb_size_of() -> usize;
 }
 
-extern "C" fn on_frame(sim: *mut VB) -> i32 {
+extern "C" fn on_frame(sim: *mut VB) -> c_int {
     // SAFETY: the *mut VB owns its userdata.
     // There is no way for the userdata to be null or otherwise invalid.
     let data: &mut VBState = unsafe { &mut *vb_get_user_data(sim).cast() };
@@ -123,12 +142,27 @@ extern "C" fn on_frame(sim: *mut VB) -> i32 {
     1
 }
 
+extern "C" fn on_execute(sim: *mut VB, address: u32, _code: *const u16, _length: c_int) -> c_int {
+    // SAFETY: the *mut VB owns its userdata.
+    // There is no way for the userdata to be null or otherwise invalid.
+    let data: &mut VBState = unsafe { &mut *vb_get_user_data(sim).cast() };
+
+    if data.breakpoints.binary_search(&address).is_err() {
+        return 0;
+    }
+
+    data.stop_reason = Some(StopReason::Breakpoint);
+    1
+}
+
 const AUDIO_CAPACITY_SAMPLES: usize = 834 * 4;
 const AUDIO_CAPACITY_FLOATS: usize = AUDIO_CAPACITY_SAMPLES * 2;
 pub const EXPECTED_FRAME_SIZE: usize = 834 * 2;
 
 struct VBState {
     frame_seen: bool,
+    stop_reason: Option<StopReason>,
+    breakpoints: Vec<u32>,
 }
 
 #[repr(transparent)]
@@ -136,8 +170,9 @@ pub struct Sim {
     sim: *mut VB,
 }
 
-// SAFETY: the memory pointed to by sim is valid
+pub enum StopReason {
-unsafe impl Send for Sim {}
+    Breakpoint,
+}
 
 impl Sim {
     pub fn new() -> Self {
@@ -151,9 +186,13 @@ impl Sim {
         unsafe { vb_reset(sim) };
 
         // set up userdata
-        let state = VBState { frame_seen: false };
+        let state = VBState {
+            frame_seen: false,
+            stop_reason: None,
+            breakpoints: vec![],
+        };
         unsafe { vb_set_user_data(sim, Box::into_raw(Box::new(state)).cast()) };
-        unsafe { vb_set_frame_callback(sim, on_frame) };
+        unsafe { vb_set_frame_callback(sim, Some(on_frame)) };
 
         // set up audio buffer
         let audio_buffer = vec![0.0f32; AUDIO_CAPACITY_FLOATS];
@@ -242,9 +281,7 @@ impl Sim {
     }
 
     pub fn read_pixels(&mut self, buffers: &mut [u8]) -> bool {
-        // SAFETY: the *mut VB owns its userdata.
+        let data = self.get_state();
-        // There is no way for the userdata to be null or otherwise invalid.
-        let data: &mut VBState = unsafe { &mut *vb_get_user_data(self.sim).cast() };
         if !data.frame_seen {
             return false;
         }
@@ -291,6 +328,61 @@ impl Sim {
     pub fn set_keys(&mut self, keys: VBKey) {
         unsafe { vb_set_keys(self.sim, keys.bits()) };
     }
+
+    pub fn read_register(&mut self, register: VBRegister) -> u32 {
+        match register {
+            VBRegister::Program(index) => unsafe {
+                vb_get_program_register(self.sim, index) as u32
+            },
+            VBRegister::System(index) => unsafe { vb_get_system_register(self.sim, index) as u32 },
+            VBRegister::PC => unsafe { vb_get_program_counter(self.sim) },
+        }
+    }
+
+    pub fn read_memory(&mut self, addresses: Range<u32>, into: &mut Vec<u8>) {
+        for address in addresses {
+            let byte = unsafe { vb_read(self.sim, address, VBDataType::U8) };
+            into.push(byte as u8);
+        }
+    }
+
+    pub fn add_breakpoint(&mut self, address: u32) {
+        let data = self.get_state();
+        if let Err(index) = data.breakpoints.binary_search(&address) {
+            data.breakpoints.insert(index, address);
+        }
+
+        unsafe {
+            vb_set_execute_callback(self.sim, Some(on_execute));
+        }
+    }
+
+    pub fn remove_breakpoint(&mut self, address: u32) {
+        let data = self.get_state();
+        if let Ok(index) = data.breakpoints.binary_search(&address) {
+            data.breakpoints.remove(index);
+            if data.breakpoints.is_empty() {
+                unsafe { vb_set_execute_callback(self.sim, None) };
+            }
+        }
+    }
+
+    pub fn clear_breakpoints(&mut self) {
+        let data = self.get_state();
+        data.breakpoints.clear();
+        unsafe { vb_set_execute_callback(self.sim, None) };
+    }
+
+    pub fn stop_reason(&mut self) -> Option<StopReason> {
+        let data = self.get_state();
+        data.stop_reason.take()
+    }
+
+    fn get_state(&mut self) -> &mut VBState {
+        // SAFETY: the *mut VB owns its userdata.
+        // There is no way for the userdata to be null or otherwise invalid.
+        unsafe { &mut *vb_get_user_data(self.sim).cast() }
+    }
 }
 
 impl Drop for Sim {

src/gdbserver.rs

@@ -0,0 +1,355 @@
+use anyhow::{bail, Result};
+use registers::REGISTERS;
+use request::{Request, RequestKind, RequestSource};
+use response::Response;
+use std::{
+    sync::{Arc, Mutex},
+    thread,
+};
+use tokio::{
+    io::{AsyncWriteExt as _, BufReader},
+    net::{TcpListener, TcpStream},
+    select,
+    sync::{mpsc, oneshot},
+};
+
+use crate::emulator::{DebugEvent, DebugStopReason, EmulatorClient, EmulatorCommand, SimId};
+
+mod registers;
+mod request;
+mod response;
+
+pub struct GdbServer {
+    sim_id: SimId,
+    client: EmulatorClient,
+    status: Arc<Mutex<GdbServerStatus>>,
+    killer: Option<oneshot::Sender<()>>,
+}
+
+impl GdbServer {
+    pub fn new(sim_id: SimId, client: EmulatorClient) -> Self {
+        Self {
+            sim_id,
+            client,
+            status: Arc::new(Mutex::new(GdbServerStatus::Stopped)),
+            killer: None,
+        }
+    }
+
+    pub fn status(&self) -> GdbServerStatus {
+        self.status.lock().unwrap().clone()
+    }
+
+    pub fn start(&mut self, port: u16) {
+        *self.status.lock().unwrap() = GdbServerStatus::Connecting;
+        let sim_id = self.sim_id;
+        let client = self.client.clone();
+        let status = self.status.clone();
+        let (tx, rx) = oneshot::channel();
+        self.killer = Some(tx);
+        thread::spawn(move || {
+            tokio::runtime::Builder::new_current_thread()
+                .enable_all()
+                .build()
+                .unwrap()
+                .block_on(async move {
+                    select! {
+                        _ = run_server(sim_id, client, port, &status) => {}
+                        _ = rx => {
+                            *status.lock().unwrap() = GdbServerStatus::Stopped;
+                        }
+                    }
+                })
+        });
+    }
+
+    pub fn stop(&mut self) {
+        if let Some(killer) = self.killer.take() {
+            let _ = killer.send(());
+        }
+    }
+}
+
+async fn run_server(
+    sim_id: SimId,
+    client: EmulatorClient,
+    port: u16,
+    status: &Mutex<GdbServerStatus>,
+) {
+    let Some(stream) = try_connect(port, status).await else {
+        return;
+    };
+    let mut connection = GdbConnection::new(sim_id, client);
+    match connection.run(stream).await {
+        Ok(()) => {
+            *status.lock().unwrap() = GdbServerStatus::Stopped;
+        }
+        Err(error) => {
+            *status.lock().unwrap() = GdbServerStatus::Error(error.to_string());
+        }
+    }
+}
+
+async fn try_connect(port: u16, status: &Mutex<GdbServerStatus>) -> Option<TcpStream> {
+    *status.lock().unwrap() = GdbServerStatus::Connecting;
+    let listener = match TcpListener::bind(("127.0.0.1", port)).await {
+        Ok(l) => l,
+        Err(err) => {
+            *status.lock().unwrap() = GdbServerStatus::Error(err.to_string());
+            return None;
+        }
+    };
+    match listener.accept().await {
+        Ok((stream, _)) => {
+            *status.lock().unwrap() = GdbServerStatus::Running;
+            Some(stream)
+        }
+        Err(err) => {
+            *status.lock().unwrap() = GdbServerStatus::Error(err.to_string());
+            None
+        }
+    }
+}
+
+#[derive(Clone)]
+pub enum GdbServerStatus {
+    Stopped,
+    Connecting,
+    Running,
+    Error(String),
+}
+
+impl GdbServerStatus {
+    pub fn running(&self) -> bool {
+        matches!(self, Self::Connecting | Self::Running)
+    }
+}
+
+struct GdbConnection {
+    sim_id: SimId,
+    client: EmulatorClient,
+    ack_messages: bool,
+    stop_reason: Option<DebugStopReason>,
+    response_buf: Option<Vec<u8>>,
+    memory_buf: Option<Vec<u8>>,
+}
+
+impl GdbConnection {
+    fn new(sim_id: SimId, client: EmulatorClient) -> Self {
+        Self {
+            sim_id,
+            client,
+            ack_messages: true,
+            stop_reason: None,
+            response_buf: None,
+            memory_buf: None,
+        }
+    }
+    async fn run(&mut self, stream: TcpStream) -> Result<()> {
+        let (debug_sink, mut debug_source) = mpsc::unbounded_channel();
+        let (rx, mut tx) = stream.into_split();
+        let mut request_source = RequestSource::new(BufReader::new(rx));
+        self.client
+            .send_command(EmulatorCommand::StartDebugging(self.sim_id, debug_sink));
+        loop {
+            let response = select! {
+                maybe_event = debug_source.recv() => {
+                    let Some(event) = maybe_event else {
+                        // debugger has stopped running
+                        break;
+                    };
+                    self.handle_event(event)
+                }
+                maybe_request = request_source.recv() => {
+                    let req = maybe_request?;
+                    self.handle_request(req)?
+                }
+            };
+            if let Some(res) = response {
+                let buffer = res.finish();
+                match std::str::from_utf8(&buffer) {
+                    Ok(text) => println!("response: {text}"),
+                    Err(_) => println!("response: {buffer:02x?}"),
+                }
+                tx.write_all(&buffer).await?;
+                self.response_buf = Some(buffer);
+                tx.flush().await?;
+            }
+        }
+        Ok(())
+    }
+
+    fn handle_event(&mut self, event: DebugEvent) -> Option<Response> {
+        let res = match event {
+            DebugEvent::Stopped(reason) => {
+                if self.stop_reason.is_some_and(|r| r == reason) {
+                    return None;
+                }
+                self.stop_reason = Some(reason);
+                self.response()
+                    .write_str(debug_stop_reason_string(self.stop_reason))
+            }
+        };
+        Some(res)
+    }
+
+    fn handle_request(&mut self, mut req: Request<'_>) -> Result<Option<Response>> {
+        println!("received {:02x?}", req);
+
+        if req.kind == RequestKind::Signal {
+            self.client
+                .send_command(EmulatorCommand::DebugInterrupt(self.sim_id));
+            return Ok(None); // we'll send a message when the emulator reports it has stopped
+        }
+
+        let res = if req.match_str("QStartNoAckMode") {
+            let res = self.response().write_str("OK");
+            self.ack_messages = false;
+            res
+        } else if req.match_str("qSupported:") {
+            self.response()
+                .write_str("multiprocess+;swbreak+;vContSupported+;PacketSize=10000")
+        } else if req
+            .match_some_str([
+                "QThreadSuffixSupported",
+                "QListThreadsInStopReply",
+                "QEnableErrorStrings",
+            ])
+            .is_some()
+        {
+            self.response().write_str("OK")
+        } else if req.match_str("qHostInfo") {
+            self.response().write_str(&format!(
+                "triple:{};endian:little;ptrsize:4;",
+                hex::encode("v810-unknown-vb")
+            ))
+        } else if req.match_str("qProcessInfo") {
+            self.response().write_str(&format!(
+                "pid:1;triple:{};endian:little;ptrsize:4;",
+                hex::encode("v810-unknown-vb")
+            ))
+        } else if req.match_str("qRegisterInfo") {
+            let mut get_reg_info = || {
+                let register = req.match_hex::<usize>()?;
+                REGISTERS.get(register)
+            };
+            if let Some(reg_info) = get_reg_info() {
+                self.response().write_str(&reg_info.to_description())
+            } else {
+                self.response()
+            }
+        } else if req.match_str("vCont?") {
+            self.response().write_str("vCont;c;")
+        } else if req.match_str("qC") {
+            // The v810 has no threads, so report that the "current thread" is 1.
+            self.response().write_str("QCp1.t1")
+        } else if req.match_str("qfThreadInfo") {
+            self.response().write_str("mp1.t1")
+        } else if req.match_str("qsThreadInfo") {
+            self.response().write_str("l")
+        } else if req.match_str("k") {
+            bail!("debug process was killed");
+        } else if req.match_str("?") {
+            self.response()
+                .write_str(debug_stop_reason_string(self.stop_reason))
+        } else if req.match_some_str(["c", "vCont;c:"]).is_some() {
+            self.client
+                .send_command(EmulatorCommand::DebugContinue(self.sim_id));
+            self.stop_reason = None;
+            // Don't send a response until we hit a breakpoint or get interrupted
+            return Ok(None);
+        } else if req.match_str("p") {
+            let mut read_register = || {
+                let register_index = req.match_hex::<usize>()?;
+                let register = REGISTERS.get(register_index)?.to_vb_register();
+                let (tx, rx) = ::oneshot::channel();
+                self.client
+                    .send_command(EmulatorCommand::ReadRegister(self.sim_id, register, tx));
+                rx.recv().ok()
+            };
+            if let Some(value) = read_register() {
+                self.response().write_hex(value)
+            } else {
+                self.response()
+            }
+        } else if let Some(op) = req.match_some_str(["m", "x"]) {
+            let mut read_memory = || {
+                let start = req.match_hex::<u32>()?;
+                if !req.match_str(",") {
+                    return None;
+                };
+                let size = req.match_hex::<u32>()?;
+                let mut buf = self.memory_buf.take().unwrap_or_default();
+                buf.clear();
+                let (tx, rx) = ::oneshot::channel();
+                self.client.send_command(EmulatorCommand::ReadMemory(
+                    self.sim_id,
+                    start..(start + size),
+                    buf,
+                    tx,
+                ));
+                rx.recv().ok()
+            };
+            if let Some(memory) = read_memory() {
+                let mut res = self.response();
+                if op == "m" {
+                    // send the hex-encoded byte stream
+                    for byte in &memory {
+                        res = res.write_hex(*byte);
+                    }
+                } else {
+                    // send the raw byte stream
+                    for byte in &memory {
+                        res = res.write_byte(*byte);
+                    }
+                }
+                self.memory_buf = Some(memory);
+                res
+            } else {
+                self.response()
+            }
+        } else if req.match_str("Z0,") {
+            if let Some(address) = req.match_hex() {
+                self.client
+                    .send_command(EmulatorCommand::AddBreakpoint(self.sim_id, address));
+                self.response().write_str("OK")
+            } else {
+                self.response()
+            }
+        } else if req.match_str("z0,") {
+            if let Some(address) = req.match_hex() {
+                self.client
+                    .send_command(EmulatorCommand::RemoveBreakpoint(self.sim_id, address));
+                self.response().write_str("OK")
+            } else {
+                self.response()
+            }
+        } else {
+            // unrecognized command
+            self.response()
+        };
+        Ok(Some(res))
+    }
+
+    fn response(&mut self) -> Response {
+        Response::new(
+            self.response_buf.take().unwrap_or_default(),
+            self.ack_messages,
+        )
+    }
+}
+
+impl Drop for GdbConnection {
+    fn drop(&mut self) {
+        self.client
+            .send_command(EmulatorCommand::StopDebugging(self.sim_id));
+    }
+}
+
+fn debug_stop_reason_string(reason: Option<DebugStopReason>) -> &'static str {
+    match reason {
+        Some(DebugStopReason::Breakpoint) => "T05;thread:p1.t1;threads;p1.t1;reason:breakpoint",
+        Some(DebugStopReason::Trapped) => "T05;swbreak;thread:p1.t1;threads:p1.t1;reason:trap;",
+        None => "T00;thread:p1.t1;threads:p1.t1;",
+    }
+}

src/gdbserver/registers.rs

@@ -0,0 +1,130 @@
+use crate::emulator::VBRegister;
+
+pub struct RegisterInfo {
+    dwarf: u32,
+    name: &'static str,
+    set: &'static str,
+    alt_name: Option<&'static str>,
+    generic: Option<&'static str>,
+}
+
+impl RegisterInfo {
+    pub fn to_description(&self) -> String {
+        let mut string = format!("name:{}", self.name);
+        if let Some(alt) = self.alt_name {
+            string.push_str(&format!(";alt-name:{}", alt));
+        }
+        string.push_str(&format!(
+            ";bitsize:32;offset:{};encoding:uint;format:hex;set:{};dwarf:{}",
+            self.dwarf * 4,
+            self.set,
+            self.dwarf
+        ));
+        if let Some(generic) = self.generic {
+            string.push_str(&format!(";generic:{}", generic));
+        }
+        string
+    }
+
+    pub fn to_vb_register(&self) -> VBRegister {
+        match self.dwarf {
+            0..32 => VBRegister::Program(self.dwarf),
+            32..40 => VBRegister::System(self.dwarf - 32),
+            40..42 => VBRegister::System(self.dwarf - 16),
+            42..45 => VBRegister::System(self.dwarf - 13),
+            45 => VBRegister::PC,
+            other => panic!("unexpected DWARF register {other}"),
+        }
+    }
+}
+
+macro_rules! register {
+    ($set:expr, $dwarf:expr, $name:expr) => {
+        RegisterInfo {
+            dwarf: $dwarf,
+            name: $name,
+            set: $set,
+            alt_name: None,
+            generic: None,
+        }
+    };
+    ($set:expr, $dwarf:expr, $name:expr, alt: $alt:expr) => {
+        RegisterInfo {
+            dwarf: $dwarf,
+            name: $name,
+            set: $set,
+            alt_name: Some($alt),
+            generic: None,
+        }
+    };
+    ($set:expr, $dwarf:expr, $name:expr, generic: $generic:expr) => {
+        RegisterInfo {
+            dwarf: $dwarf,
+            name: $name,
+            set: $set,
+            alt_name: None,
+            generic: Some($generic),
+        }
+    };
+    ($set:expr, $dwarf:expr, $name:expr, alt: $alt:expr, generic: $generic:expr) => {
+        RegisterInfo {
+            dwarf: $dwarf,
+            name: $name,
+            set: $set,
+            alt_name: Some($alt),
+            generic: Some($generic),
+        }
+    };
+}
+
+const GENERAL: &str = "General Purpose Registers";
+const SPECIAL: &str = "Special Registers";
+
+pub const REGISTERS: [RegisterInfo; 46] = [
+    register!(GENERAL, 0, "r0"),
+    register!(GENERAL, 1, "r1"),
+    register!(GENERAL, 2, "fp", alt: "r2", generic: "fp"),
+    register!(GENERAL, 3, "sp", alt: "r3", generic: "sp"),
+    register!(GENERAL, 4, "gp", alt: "r4"),
+    register!(GENERAL, 5, "tp", alt: "r5"),
+    register!(GENERAL, 6, "r6", generic: "arg1"),
+    register!(GENERAL, 7, "r7", generic: "arg2"),
+    register!(GENERAL, 8, "r8", generic: "arg3"),
+    register!(GENERAL, 9, "r9", generic: "arg4"),
+    register!(GENERAL, 10, "r10"),
+    register!(GENERAL, 11, "r11"),
+    register!(GENERAL, 12, "r12"),
+    register!(GENERAL, 13, "r13"),
+    register!(GENERAL, 14, "r14"),
+    register!(GENERAL, 15, "r15"),
+    register!(GENERAL, 16, "r16"),
+    register!(GENERAL, 17, "r17"),
+    register!(GENERAL, 18, "r18"),
+    register!(GENERAL, 19, "r19"),
+    register!(GENERAL, 20, "r20"),
+    register!(GENERAL, 21, "r21"),
+    register!(GENERAL, 22, "r22"),
+    register!(GENERAL, 23, "r23"),
+    register!(GENERAL, 24, "r24"),
+    register!(GENERAL, 25, "r25"),
+    register!(GENERAL, 26, "r26"),
+    register!(GENERAL, 27, "r27"),
+    register!(GENERAL, 28, "r28"),
+    register!(GENERAL, 29, "r29"),
+    register!(GENERAL, 30, "r30"),
+    register!(GENERAL, 31, "lp", alt: "r31", generic: "ra"),
+    register!(SPECIAL, 32, "eipc", alt: "sr0"),
+    register!(SPECIAL, 33, "eipsw", alt: "sr1"),
+    register!(SPECIAL, 34, "fepc", alt: "sr2"),
+    register!(SPECIAL, 35, "fepsw", alt: "sr3"),
+    register!(SPECIAL, 36, "ecr", alt: "sr4"),
+    register!(SPECIAL, 37, "psw", alt: "sr5", generic: "flags"),
+    register!(SPECIAL, 38, "pir", alt: "sr6"),
+    register!(SPECIAL, 39, "tkcw", alt: "sr7"),
+    register!(SPECIAL, 40, "chcw", alt: "sr24"),
+    register!(SPECIAL, 41, "adtre", alt: "sr25"),
+    register!(SPECIAL, 42, "sr29"),
+    register!(SPECIAL, 43, "sr30"),
+    register!(SPECIAL, 44, "sr31"),
+    register!(SPECIAL, 45, "pc", generic: "pc"),
+];

src/gdbserver/request.rs

@@ -0,0 +1,179 @@
+use anyhow::{bail, Result};
+use atoi::FromRadix16;
+use tokio::io::{AsyncRead, AsyncReadExt as _};
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum RequestKind {
+    Signal,
+    Command,
+}
+impl RequestKind {
+    fn name(self) -> &'static str {
+        match self {
+            Self::Signal => "Signal",
+            Self::Command => "Command",
+        }
+    }
+}
+
+pub struct Request<'a> {
+    pub kind: RequestKind,
+    buffer: &'a [u8],
+}
+
+impl std::fmt::Debug for Request<'_> {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        let mut ds = f.debug_tuple(self.kind.name());
+        match self.kind {
+            RequestKind::Signal => ds.field(&self.buffer),
+            RequestKind::Command => match std::str::from_utf8(self.buffer) {
+                Ok(str) => ds.field(&str),
+                Err(_) => ds.field(&self.buffer),
+            },
+        };
+        ds.finish()
+    }
+}
+
+impl Request<'_> {
+    pub fn match_str(&mut self, prefix: &str) -> bool {
+        if let Some(new_buffer) = self.buffer.strip_prefix(prefix.as_bytes()) {
+            self.buffer = new_buffer;
+            return true;
+        }
+        false
+    }
+
+    pub fn match_some_str<'a, I: IntoIterator<Item = &'a str>>(
+        &mut self,
+        prefixes: I,
+    ) -> Option<&'a str> {
+        prefixes.into_iter().find(|&prefix| self.match_str(prefix))
+    }
+
+    pub fn match_hex<I: FromRadix16>(&mut self) -> Option<I> {
+        match I::from_radix_16(self.buffer) {
+            (_, 0) => None,
+            (val, used) => {
+                self.buffer = self.buffer.split_at(used).1;
+                Some(val)
+            }
+        }
+    }
+}
+
+pub struct RequestSource<R> {
+    reader: R,
+    buffer: Vec<u8>,
+    state: RequestReadState,
+}
+
+impl<R: AsyncRead + Unpin> RequestSource<R> {
+    pub fn new(reader: R) -> Self {
+        Self {
+            reader,
+            buffer: vec![],
+            state: RequestReadState::Header,
+        }
+    }
+
+    pub async fn recv(&mut self) -> Result<Request<'_>> {
+        let mut char = self.reader.read_u8().await?;
+        if matches!(self.state, RequestReadState::Start) {
+            self.buffer.clear();
+            self.state = RequestReadState::Header;
+        }
+        if matches!(self.state, RequestReadState::Header) {
+            // Just ignore positive acks
+            while char == b'+' {
+                char = self.reader.read_u8().await?;
+            }
+            if char == b'-' {
+                bail!("no support for negative acks");
+            }
+            if char == 0x03 {
+                // This is how the client "cancels an in-flight request"
+                self.buffer.push(char);
+                self.state = RequestReadState::Start;
+                return Ok(Request {
+                    kind: RequestKind::Signal,
+                    buffer: &self.buffer,
+                });
+            }
+            if char != b'$' {
+                // Messages are supposed to start with a dollar sign
+                bail!("malformed message");
+            }
+            self.state = RequestReadState::Body {
+                checksum: 0,
+                escaping: false,
+            };
+            char = self.reader.read_u8().await?;
+        }
+        while let RequestReadState::Body { checksum, escaping } = &mut self.state {
+            if char == b'#' && !*escaping {
+                self.state = RequestReadState::Checksum {
+                    expected: *checksum,
+                    actual: 0,
+                    digits: 0,
+                };
+                char = self.reader.read_u8().await?;
+                break;
+            }
+            *checksum = checksum.wrapping_add(char);
+
+            if *escaping {
+                // escaped character
+                self.buffer.push(char ^ 0x20);
+                *escaping = false;
+            } else if char == b'}' {
+                // next character will be escaped
+                *escaping = true;
+            } else {
+                self.buffer.push(char);
+            }
+            char = self.reader.read_u8().await?;
+        }
+        while let RequestReadState::Checksum {
+            expected,
+            actual,
+            digits,
+        } = &mut self.state
+        {
+            let digit = match char {
+                b'0'..=b'9' => char - b'0',
+                b'a'..=b'f' => char - b'a' + 10,
+                b'A'..=b'F' => char - b'A' + 10,
+                _ => bail!("invalid checksum"),
+            };
+            *actual = (*actual << 4) + digit;
+            *digits += 1;
+            if *digits == 2 {
+                if *expected != *actual {
+                    bail!("mismatched checksum");
+                }
+                self.state = RequestReadState::Start;
+                return Ok(Request {
+                    kind: RequestKind::Command,
+                    buffer: &self.buffer,
+                });
+            }
+            char = self.reader.read_u8().await?;
+        }
+        unreachable!();
+    }
+}
+
+enum RequestReadState {
+    Start,
+    Header,
+    Body {
+        checksum: u8,
+        escaping: bool,
+    },
+    Checksum {
+        expected: u8,
+        actual: u8,
+        digits: u8,
+    },
+}

src/gdbserver/response.rs

@@ -0,0 +1,63 @@
+use num_traits::ToBytes;
+
+pub struct Response {
+    buffer: Vec<u8>,
+    checksum: u8,
+}
+
+impl Response {
+    pub fn new(mut buffer: Vec<u8>, ack: bool) -> Self {
+        buffer.clear();
+        if ack {
+            buffer.push(b'+');
+        }
+        buffer.push(b'$');
+        Self {
+            buffer,
+            checksum: 0,
+        }
+    }
+
+    pub fn write_str(self, str: &str) -> Self {
+        let mut me = self;
+        for byte in str.as_bytes() {
+            me = me.write_byte(*byte);
+        }
+        me
+    }
+
+    pub fn write_byte(mut self, byte: u8) -> Self {
+        if byte == b'}' || byte == b'#' || byte == b'$' || byte == b'*' {
+            self.buffer.push(b'}');
+            self.checksum = self.checksum.wrapping_add(b'}');
+            let escaped = byte ^ 0x20;
+            self.buffer.push(escaped);
+            self.checksum = self.checksum.wrapping_add(escaped);
+        } else {
+            self.buffer.push(byte);
+            self.checksum = self.checksum.wrapping_add(byte);
+        }
+        self
+    }
+
+    pub fn write_hex<T: ToBytes>(mut self, value: T) -> Self {
+        for byte in value.to_le_bytes().as_ref() {
+            for digit in [(byte >> 4), (byte & 0xf)] {
+                let char = if digit > 9 {
+                    b'a' + digit - 10
+                } else {
+                    b'0' + digit
+                };
+                self.buffer.push(char);
+                self.checksum = self.checksum.wrapping_add(char);
+            }
+        }
+        self
+    }
+
+    pub fn finish(mut self) -> Vec<u8> {
+        let checksum = self.checksum;
+        self.buffer.push(b'#');
+        self.write_hex(checksum).buffer
+    }
+}

src/main.rs

@@ -14,6 +14,7 @@ mod app;
 mod audio;
 mod controller;
 mod emulator;
+mod gdbserver;
 mod graphics;
 mod input;
 mod persistence;
@@ -21,7 +22,11 @@ mod window;
 
 #[derive(Parser)]
 struct Args {
+    /// The path to a virtual boy ROM to run.
     rom: Option<PathBuf>,
+    /// Start a GDB/LLDB debug server on this port.
+    #[arg(short, long)]
+    debug_port: Option<u16>,
 }
 
 fn set_panic_handler() {
@@ -82,6 +87,9 @@ fn main() -> Result<()> {
     if let Some(path) = args.rom {
         builder = builder.with_rom(&path);
     }
+    if args.debug_port.is_some() {
+        builder = builder.start_paused(true);
+    }
 
     ThreadBuilder::default()
         .name("Emulator".to_owned())
@@ -100,6 +108,6 @@ fn main() -> Result<()> {
     let event_loop = EventLoop::with_user_event().build().unwrap();
     event_loop.set_control_flow(ControlFlow::Poll);
     let proxy = event_loop.create_proxy();
-    event_loop.run_app(&mut Application::new(client, proxy))?;
+    event_loop.run_app(&mut Application::new(client, proxy, args.debug_port))?;
     Ok(())
 }

src/window.rs

@@ -1,12 +1,14 @@
 pub use about::AboutWindow;
 use egui::{Context, ViewportBuilder, ViewportId};
 pub use game::GameWindow;
+pub use gdb::GdbServerWindow;
 pub use input::InputWindow;
 use winit::event::KeyEvent;
 
 mod about;
 mod game;
 mod game_screen;
+mod gdb;
 mod input;
 
 pub trait AppWindow {

src/window/game.rs

@@ -2,7 +2,7 @@ use std::sync::mpsc;
 
 use crate::{
     app::UserEvent,
-    emulator::{EmulatorClient, EmulatorCommand, SimId},
+    emulator::{EmulatorClient, EmulatorCommand, EmulatorState, SimId, SimState},
     persistence::Persistence,
 };
 use egui::{
@@ -73,7 +73,7 @@ impl GameWindow {
                     .pick_file();
                 if let Some(path) = rom {
                     self.client
-                        .send_command(EmulatorCommand::LoadGame(SimId::Player1, path));
+                        .send_command(EmulatorCommand::LoadGame(self.sim_id, path));
                 }
                 ui.close_menu();
             }
@@ -82,17 +82,19 @@ impl GameWindow {
             }
         });
         ui.menu_button("Emulation", |ui| {
-            let has_game = self.client.has_game(self.sim_id);
+            let state = self.client.emulator_state();
-            if self.client.is_running(self.sim_id) {
+            let is_ready = self.client.sim_state(self.sim_id) == SimState::Ready;
-                if ui.add_enabled(has_game, Button::new("Pause")).clicked() {
+            let can_pause = is_ready && state == EmulatorState::Running;
+            if state == EmulatorState::Running {
+                if ui.add_enabled(is_ready, Button::new("Pause")).clicked() {
                     self.client.send_command(EmulatorCommand::Pause);
                     ui.close_menu();
                 }
-            } else if ui.add_enabled(has_game, Button::new("Resume")).clicked() {
+            } else if ui.add_enabled(can_pause, Button::new("Resume")).clicked() {
                 self.client.send_command(EmulatorCommand::Resume);
                 ui.close_menu();
             }
-            if ui.add_enabled(has_game, Button::new("Reset")).clicked() {
+            if ui.add_enabled(is_ready, Button::new("Reset")).clicked() {
                 self.client
                     .send_command(EmulatorCommand::Reset(self.sim_id));
                 ui.close_menu();
@@ -100,8 +102,9 @@ impl GameWindow {
         });
         ui.menu_button("Options", |ui| self.show_options_menu(ctx, ui));
         ui.menu_button("Multiplayer", |ui| {
+            let has_player_2 = self.client.sim_state(SimId::Player2) != SimState::Uninitialized;
             if self.sim_id == SimId::Player1
-                && !self.client.has_player_2()
+                && !has_player_2
                 && ui.button("Open Player 2").clicked()
             {
                 self.client
@@ -109,7 +112,7 @@ impl GameWindow {
                 self.proxy.send_event(UserEvent::OpenPlayer2).unwrap();
                 ui.close_menu();
             }
-            if self.client.has_player_2() {
+            if has_player_2 {
                 let linked = self.client.are_sims_linked();
                 if linked && ui.button("Unlink").clicked() {
                     self.client.send_command(EmulatorCommand::Unlink);
@@ -121,6 +124,14 @@ impl GameWindow {
                 }
             }
         });
+        ui.menu_button("Tools", |ui| {
+            if ui.button("GDB Server").clicked() {
+                self.proxy
+                    .send_event(UserEvent::OpenDebugger(self.sim_id))
+                    .unwrap();
+                ui.close_menu();
+            }
+        });
         ui.menu_button("About", |ui| {
             self.proxy.send_event(UserEvent::OpenAbout).unwrap();
             ui.close_menu();
@@ -199,7 +210,7 @@ impl GameWindow {
                         let color_str = |color: Color32| {
                             format!("{:02x}{:02x}{:02x}", color.r(), color.g(), color.b())
                         };
-                        let is_running = self.client.is_running(self.sim_id);
+                        let is_running = self.client.emulator_state() == EmulatorState::Running;
                         if is_running {
                             self.client.send_command(EmulatorCommand::Pause);
                         }

src/window/gdb.rs

@@ -0,0 +1,96 @@
+use egui::{Button, CentralPanel, TextEdit, ViewportBuilder, ViewportId};
+use winit::event_loop::EventLoopProxy;
+
+use crate::{
+    app::UserEvent,
+    emulator::{EmulatorClient, SimId},
+    gdbserver::{GdbServer, GdbServerStatus},
+};
+
+use super::AppWindow;
+
+pub struct GdbServerWindow {
+    sim_id: SimId,
+    port_str: String,
+    launched: bool,
+    server: GdbServer,
+    proxy: EventLoopProxy<UserEvent>,
+}
+
+impl GdbServerWindow {
+    pub fn new(sim_id: SimId, client: EmulatorClient, proxy: EventLoopProxy<UserEvent>) -> Self {
+        Self {
+            sim_id,
+            port_str: (8080 + sim_id.to_index()).to_string(),
+            launched: false,
+            server: GdbServer::new(sim_id, client),
+            proxy,
+        }
+    }
+
+    pub fn launch(&mut self, port: u16) {
+        self.server.stop();
+        self.port_str = port.to_string();
+        self.launched = true;
+        self.server.start(port);
+    }
+}
+
+impl AppWindow for GdbServerWindow {
+    fn viewport_id(&self) -> ViewportId {
+        ViewportId::from_hash_of(format!("Debugger-{}", self.sim_id))
+    }
+
+    fn initial_viewport(&self) -> ViewportBuilder {
+        ViewportBuilder::default()
+            .with_title(format!("GDB Server ({})", self.sim_id))
+            .with_inner_size((300.0, 200.0))
+    }
+
+    fn show(&mut self, ctx: &egui::Context) {
+        let port_num: Option<u16> = self.port_str.parse().ok();
+        let status = self.server.status();
+        CentralPanel::default().show(ctx, |ui| {
+            ui.horizontal(|ui| {
+                if port_num.is_none() {
+                    let style = ui.style_mut();
+                    let error = style.visuals.error_fg_color;
+                    style.visuals.widgets.active.bg_stroke.color = error;
+                    style.visuals.widgets.hovered.bg_stroke.color = error;
+                }
+                ui.label("Port");
+                let port_editor = TextEdit::singleline(&mut self.port_str).desired_width(100.0);
+                ui.add_enabled(!status.running(), port_editor);
+            });
+
+            if !status.running() {
+                if self.launched {
+                    self.proxy.send_event(UserEvent::Quit).unwrap();
+                }
+                let start_button = Button::new("Start");
+                if ui.add_enabled(port_num.is_some(), start_button).clicked() {
+                    let port = port_num.unwrap();
+                    self.server.start(port);
+                }
+            } else {
+                let stop_button = Button::new("Stop");
+                if ui.add(stop_button).clicked() {
+                    self.server.stop();
+                }
+            }
+
+            match &status {
+                GdbServerStatus::Stopped => {}
+                GdbServerStatus::Connecting => {
+                    ui.label("Connecting...");
+                }
+                GdbServerStatus::Running => {
+                    ui.label("Running");
+                }
+                GdbServerStatus::Error(message) => {
+                    ui.label(message);
+                }
+            }
+        });
+    }
+}