Add CD-debug instrumentation: post-auth poll/service dumps

Adds one-shot JaguarDumpMemWindow hooks in JaguarExecuteNew() for the
game CD-event poll function ($081220), its flag area ($0008B398), and
the BIOS service routines the game calls into ($00196446 DSP serial
comms, $00194D18 CD-data processing). Also traces writes to the
$0008B398 game flag.

These dumps decoded the post-auth blocker: the BIOS service at $194D18
expects $001AE034 (data-present) and $001AE032 (bytes-remaining) to be
non-zero, kicked by ($001AE00C & 0x2000). Our $0505FA stuff value of
$20010001 lacks bit 13, so the kick path never triggers.

Also adds .iso to libretro core's valid_extensions and headless.py docs.

Co-Authored-By: Claude Opus 4.7 <[email protected]>

Author: JoeMatt

libretro.c

@@ -807,7 +807,7 @@ void retro_get_system_info(struct retro_system_info *info)
 #endif
    info->library_version  = "v2.1.0" GIT_VERSION;
    info->need_fullpath    = true;
-   info->valid_extensions = "j64|jag|cue|cdi|chd";
+   info->valid_extensions = "j64|jag|cue|cdi|chd|iso";
 }
 
 void retro_get_system_av_info(struct retro_system_av_info *info)

src/jaguar.c

@@ -426,6 +426,43 @@ void M68KInstructionHook(void)
          JaguarWriteWord(0x001A6800, 0x0001, UNKNOWN);
       }
 
+      /* One-shot dump of the game's main poll function context once we
+       * see the game executing at $081220. Helps decode the outer caller. */
+      if (m68kPC == 0x081220)
+      {
+         static bool dumpedGamePoll = false;
+         if (!dumpedGamePoll)
+         {
+            dumpedGamePoll = true;
+            fprintf(stderr, "[CD-DUMP] Game poll function context @ $081220:\n");
+            JaguarDumpMemWindow(0x081200, 0x20, 0x80);
+            fprintf(stderr, "[CD-DUMP] Game CD-event flag area @ $0008B380:\n");
+            JaguarDumpMemWindow(0x0008B380, 0x00, 0x40);
+         }
+      }
+
+      /* One-shot dump of the BIOS service routines the game calls into. */
+      if (m68kPC == 0x196446)
+      {
+         static bool dumped196446 = false;
+         if (!dumped196446)
+         {
+            dumped196446 = true;
+            fprintf(stderr, "[CD-DUMP] BIOS service @ $00196446:\n");
+            JaguarDumpMemWindow(0x196446, 0x10, 0x100);
+         }
+      }
+      if (m68kPC == 0x194D18)
+      {
+         static bool dumped194D18 = false;
+         if (!dumped194D18)
+         {
+            dumped194D18 = true;
+            fprintf(stderr, "[CD-DUMP] BIOS service @ $00194D18:\n");
+            JaguarDumpMemWindow(0x194D18, 0x40, 0x100);
+         }
+      }
+
    }
 }
 
@@ -782,6 +819,19 @@ void JaguarWriteWord(uint32_t offset, uint16_t data, uint32_t who)
                     ramOff, data, GPUGetPC(), who);
          }
       }
+      /* Track writes to the game's CD-event flag at $0008B398.
+       * Game's poll function at $081220 returns RTS unless either
+       * BUTCH bit13 (DSARX) or this longword is non-zero. We never
+       * deliver BUTCH IRQs (game uses polling), so this flag is the
+       * only path that wakes the game's main loop. */
+      if (vjs.useCDBIOS && (ramOff == 0x08B398 || ramOff == 0x08B39A))
+      {
+         static uint32_t b398Count = 0;
+         if (++b398Count <= 20)
+            fprintf(stderr, "[CD-FLAG] $%06X = $%04X who=%u 68K_PC=$%06X GPU_PC=$%06X\n",
+                    ramOff, data, who,
+                    m68k_get_reg(NULL, M68K_REG_PC), GPUGetPC());
+      }
       jaguarMainRAM[(offset+0) & 0x1FFFFF] = data >> 8;
       jaguarMainRAM[(offset+1) & 0x1FFFFF] = data & 0xFF;
       return;

test/headless.py

@@ -15,7 +15,7 @@
 
 Usage:
     source .venv-libretropy/bin/activate
-    python test/headless.py <content.cue|.j64|.cdi> [--frames N] [--cd-bios retail|dev]
+    python test/headless.py <content.cue|.j64|.cdi|.iso> [--frames N] [--cd-bios retail|dev]
 
 The core is auto-detected from the repo root. The system_dir defaults to
 test/roms/private/ (where BIOSes are kept). Adjust via --system-dir.
@@ -46,7 +46,7 @@ def detect_core() -> Path:
 
 def parse_args() -> argparse.Namespace:
     p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    p.add_argument("content", help="Path to game content (.cue, .j64, .cdi, etc.)")
+    p.add_argument("content", help="Path to game content (.cue, .j64, .cdi, .iso, etc.)")
     p.add_argument("--frames", type=int, default=600, help="Frames to run (default: 600)")
     p.add_argument("--cd-bios", choices=["retail", "dev"], default="retail",
                    help="CD BIOS variant (default: retail)")