HLE CD: signal completion via DSP RAM [\$F1B4C8] = \$FFFFFFFF

Per docs/cd-bios-calling-convention.md and the retail BIOS disassembly:

  "The BIOS does NOT use CD_poll. It polls DSP RAM flag at [\$F1B4C8] —
   the GPU ISR writes \$FFFFFFFF there when the transfer completes, and
   the BIOS loops until negative."

HLEHandleCDRead now mirrors that contract: clear the flag at the start
of the read and write \$FFFFFFFF when the transfer finishes.  This is
the hardware-correct completion primitive.  Game boot stubs that follow
the BIOS convention will pick this up automatically.

The remaining failing CUE games (Baldies, BrainDead 13, Iron Soldier 2,
Primal Rage) do NOT poll [\$F1B4C8] — they either spin in STOP waiting
for a JERRY ext IRQ from BUTCH, or they read the BUTCH FIFO data
register (\$DFFF24/\$DFFF28) directly from the 68K.  Both are separate,
larger problems (interrupt-driven streaming and direct-FIFO emulation)
tracked for follow-up work.

Test diagnostic: the boot smoke test now also dumps 32 bytes of code
around each visited PC when fewer than 32 unique PCs are seen, so the
wait-loop instruction stream can be decoded without re-running.

Result: 4 PASS / 5 FAIL (no regression vs prior baseline).
Made-with: Cursor

Author: JoeMatt

src/jagcd_hle.c

@@ -19,8 +19,16 @@
 #include "log.h"
 #include "vjag_memory.h"
 #include "gpu.h"
+#include "dsp.h"
 #include "m68000/m68kinterface.h"
 
+/* DSP RAM "CD transfer done" flag.  Per docs/cd-bios-calling-convention.md:
+ *   "The BIOS does NOT use CD_poll. It polls DSP RAM flag at [$F1B4C8] —
+ *    the GPU ISR writes $FFFFFFFF there when the transfer completes, and
+ *    the BIOS loops until negative."
+ * Game boot stubs follow the same convention. */
+#define CD_DSP_DONE_FLAG_ADDR  0x00F1B4C8
+
 /* file_stream_transforms.h redefines fprintf; restore real stdio. */
 #undef fprintf
 
@@ -231,6 +239,11 @@ static void HLEHandleCDRead(void)
       return;
    }
 
+   /* Clear the DSP completion flag so polling code sees a 0 -> $FFFFFFFF
+    * transition once the transfer finishes.  Real hardware: the GPU CD ISR
+    * writes $FFFFFFFF here when its write pointer reaches the end address. */
+   DSPWriteLong(CD_DSP_DONE_FLAG_ADDR, 0x00000000, UNKNOWN);
+
    /* Scan for the D1 sentinel sync block in the byte-swapped disc data.
     *
     * On real hardware the I2S path byte-swaps each 16-bit word, and the
@@ -468,6 +481,11 @@ static void HLEHandleCDRead(void)
       GPUWriteLong(hle_gpu_data_base + 16, d1, 0);
    }
 
+   /* Signal completion to BIOS-style polling code via DSP RAM flag.
+    * Real GPU CD ISR writes $FFFFFFFF here when its write pointer reaches
+    * the end address. */
+   DSPWriteLong(CD_DSP_DONE_FLAG_ADDR, 0xFFFFFFFFu, UNKNOWN);
+
    HLE_LOG("CD_read: transferred %u bytes (%u sectors) "
            "to $%06X-$%06X\n",
            byteCount, s, destAddr, hle_read_end_addr - 1);

test/test_cd_hle_boot.c

@@ -221,6 +221,22 @@ static void cd_run_one_disc(const char *path, unsigned frames,
         for (size_t i = 0; i < hist.unique_count; i++)
             fprintf(stderr, " $%06X", hist.unique[i]);
         fprintf(stderr, "\n");
+
+        /* Dump 32 bytes around each visited PC so the developer can decode
+         * the instruction stream of the wait loop without re-running. */
+        if (ram) {
+            for (size_t i = 0; i < hist.unique_count; i++) {
+                uint32_t pc = hist.unique[i];
+                if (pc >= 0x200000) continue;
+                uint32_t base = (pc >= 8) ? (pc - 8) : 0;
+                uint32_t end  = base + 32;
+                if (end > 0x200000) end = 0x200000;
+                fprintf(stderr, "    [PC-BYTES $%06X]", pc);
+                for (uint32_t a = base; a < end; a++)
+                    fprintf(stderr, " %02X", ram[a]);
+                fprintf(stderr, "\n");
+            }
+        }
     }
 
     cd_unload_game();