acid: timing perf counters + per-test perf delta + first timing/IRQ tests

Builds out the acid framework along the lines requested: comprehensive
test categories, perf data capture wired into the runner, first real
tests against timing & IRQ delivery (the categories most likely to
explain the Doom 2x speed regression in issue #131).

Core instrumentation
--------------------

Five new PERF_COUNTERs at the timing-critical hot paths so any test
or `make benchmark` run can see how often things actually fire (no
runtime cost unless built with BENCH_PROFILE=1):

* `timing_jaguar_execute_calls` -- once per `retro_run()`
* `timing_halfline_callbacks`   -- 525 per frame on NTSC
* `timing_vblank_irqs`          -- 1 per frame
* `timing_jerry_irqs`           -- JERRY PIT timer 1/2 to 68K
* `timing_gpu_irqs_to_68k`      -- TOM PIT to 68K

Verified against headless Doom benchmark: halflines = 524 * frames
exactly; vblank_irqs ~= frames; everything within spec.  These
counters will surface any future regression where (e.g.) vblank
fires twice per frame -- which is the leading hypothesis for the
Doom 1.5-2x bug.

Acid runner: per-test perf summary
----------------------------------

`test/acid/run.c` now snapshots a fixed set of perf counters before
and after each test's frame run and prints the delta, e.g.:

  [PASS       ] tests/timing/vc_per_frame.jag
                perf: timing_jaguar_execute_calls=600 timing_halfline_callbacks=314400

That lets reviewers see at a glance what each test exercised --
useful for catching tests that PASS while doing nothing, and for
attributing a slow blitter test to the right counter (calls vs
inner-iter vs phrase-write).

Top-level `make acid` now forces BENCH_PROFILE=1 + TEST_EXPORTS=1
so the runner's `dlsym(perf_counters_find)` always works.

First real tests
----------------

* `tests/timing/vc_advance.s`    [PASS] -- VC counter must change
* `tests/timing/vc_per_frame.s`  [PASS] -- VC sweeps once per frame
* `tests/irq/vblank_delivery.s`  [NOT-RUN-YET] -- VBlank IRQ raises
  in TOM (counter ticks) but our 68K vector-64 patch never fires.
  Real bug surface, exactly the kind of thing this suite is meant
  to catch.  Left checked in as a known-broken regression gate.

Documentation
-------------

* `test/acid/README.md` rewritten as a long-form roadmap covering
  all 13 planned categories (smoke, timing, irq, blitter, op, gpu,
  dsp, bus, hle, memory, quirks, stress, perf), with status
  matrix, per-test perf-summary docs, vasm install steps for the
  prb28/vasm GitHub mirror, and explicit cross-references to
  Shamus' original `docs/TODO` items per category.

* `docs/emulation-bug-hunt-todos.md` gains a final section that
  lists the still-open accuracy items from the upstream `docs/TODO`
  (VC behaviour, cycle accuracy, blitter A1<->A2 propagation, bus
  contention, OP timing) and maps each to its acid-test home.
  The original `docs/TODO` is left untouched per user direction --
  it's the historical record.

Status: 3 / 5 tests passing.  The 2 NOT-RUN-YET cases are real
emulator bugs, surfaced (not introduced) by this work.

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

Author: JoeMatt

Makefile

@@ -909,7 +909,12 @@ benchmark:
 # (see test/acid/README.md).  Requires the vasm 68K assembler on $PATH;
 # if absent, the assemble step is skipped and only the runner harness
 # is built (so CI can still validate the harness compiles).
-acid: $(TARGET)
+#
+# Forces a BENCH_PROFILE=1 + TEST_EXPORTS=1 build of the core so the
+# acid runner can dlsym `perf_counters_find` and report a per-test
+# delta (halflines, vblank IRQs, blits, inner-loop iters, ...).
+acid:
+	$(MAKE) BENCH_PROFILE=1 TEST_EXPORTS=1 -j$(shell getconf _NPROCESSORS_ONLN 2>/dev/null || echo 4)
 	$(MAKE) -C test/acid test CORE=$(abspath $(TARGET))
 
 print-%:

docs/emulation-bug-hunt-todos.md

@@ -456,3 +456,35 @@ shipping v2.2.0; capture them so they don't get lost.
   / `const`-correctness audits as a CI step.  `clang-tidy` and
   `cppcheck` would be good starting points; the codebase already
   has a C89 lint, so the infrastructure is there.
+
+## Original `docs/TODO` items still relevant (Shamus / CJ)
+
+The historical `docs/TODO` from the upstream Virtual Jaguar tree
+lists several still-open accuracy / feature items.  These map onto
+the acid-test categories in `test/acid/README.md`; tracking here so
+they don't get lost:
+
+- **"Fix VC behavior to match what a real Jaguar does. Still not
+  sure just what the heck is going on there." [Shamus]** —
+  acid `timing/`.  Active suspect for the Doom 1.5-2x speed
+  regression (issue #131).
+- **"Cycle accuracy for GPU/DSP/OP/Blitter." [Shamus]** —
+  cross-cutting; informs every category in `test/acid/`, especially
+  `bus/` (which can't pass without it).
+- **"Need to propagate blitter fixes in the A1 <- A2 direction
+  to the A1 -> A2 direction and the GPU fixes to various
+  instructions to the DSP." [Shamus]** — acid `blitter/` (A1↔A2
+  symmetry tests) and `gpu/` + `dsp/` (shared opcode coverage).
+- **"Blitter needs fixing." [Shamus]** — acid `blitter/`.
+  PR #129 fixed a perf-relevant chunk (`ADDARRAY` etc); accuracy
+  axis still wide open.
+- **"Need to emulate bus contention." [Shamus]** — acid `bus/`.
+  Almost certainly load-bearing for the Doom regression and the
+  AvP audio dropouts.
+- **"Need to fix timing in the OP. As it is now, it gives a false
+  impression of how much it's capable of." [Shamus]** —
+  acid `op/`.
+
+The original `docs/TODO` is intentionally left untouched — it's
+the authors' historical record and we track our own work via
+GitHub issues + this file + `test/acid/`.

src/core/jaguar.c

@@ -19,6 +19,7 @@
 #include "jaguar.h"
 
 #include "cdrom.h"
+#include "perf_counters.h"
 #include "dac.h"
 #include "dsp.h"
 #include "eeprom.h"
@@ -33,6 +34,16 @@
 
 static bool frameDone;
 
+/* Frame-pacing instrumentation (no-op unless built with BENCH_PROFILE).
+ * Lets the acid runner / benchmark detect timing regressions like the
+ * Doom 2x speed bug -- e.g. expected 525 halflines/frame NTSC, 60 vblank
+ * IRQs/sec.  See test/acid/README.md and src/core/perf_counters.h.
+ * Counters that fire from other TUs are declared at their use sites
+ * (PERF_COUNTER backs each name with a file-scope static). */
+PERF_COUNTER(timing_halfline_callbacks);
+PERF_COUNTER(timing_vblank_irqs);
+PERF_COUNTER(timing_jaguar_execute_calls);
+
 // Platform-independent xorshift32 PRNG for deterministic RAM initialization.
 // libc rand() produces different sequences on different platforms (glibc vs
 // macOS libsystem), which causes cross-platform baseline mismatches.
@@ -694,7 +705,8 @@ void JaguarInit(void)
 // Half line times are, naturally, half of this. :-P
 void HalflineCallback(void)
 {
-   uint16_t vc           = TOMReadWord(0xF00006, JAGUAR);
+   uint16_t vc           = (PERF_INC(timing_halfline_callbacks),
+                            TOMReadWord(0xF00006, JAGUAR));
    uint16_t vp           = TOMReadWord(0xF0003E, JAGUAR) + 1;
    uint16_t vi           = TOMReadWord(0xF0004E, JAGUAR);
 
@@ -712,7 +724,10 @@ void HalflineCallback(void)
 
    // Time for Vertical Interrupt?
    if ((vc & 0x7FF) == vi && (vc & 0x7FF) > 0)
+   {
+      PERF_INC(timing_vblank_irqs);
       TOMSetPendingVideoInt();
+   }
 
    TOMExecHalfline(vc, true);
 
@@ -934,6 +949,7 @@ uint8_t * GetRamPtr(void)
  * so the DSP runs alongside the 68K and GPU, matching real hardware timing. */
 void JaguarExecuteNew(void)
 {
+   PERF_INC(timing_jaguar_execute_calls);
    frameDone = false;
 
    do

src/jerry/jerry.c

@@ -162,6 +162,9 @@
 #include "eeprom.h"
 #include "event.h"
 #include "jaguar.h"
+#include "perf_counters.h"
+
+PERF_COUNTER(timing_jerry_irqs);
 #include "joystick.h"
 #include "m68000/m68kinterface.h"
 #include "memtrack.h"
@@ -250,6 +253,7 @@ void JERRYPIT1Callback(void)
          // Not sure, but I think we don't generate another IRQ if one's already going...
          // But this seems to work... :-/
          jerryPendingInterrupt |= IRQ2_TIMER1;
+         PERF_INC(timing_jerry_irqs);
          m68k_set_irq(2);						// Generate 68K IPL 2
       }
    }
@@ -266,6 +270,7 @@ void JERRYPIT2Callback(void)
       if (jerryInterruptMask & IRQ2_TIMER2)		// CPU Timer 2 IRQ
       {
          jerryPendingInterrupt |= IRQ2_TIMER2;
+         PERF_INC(timing_jerry_irqs);
          m68k_set_irq(2);						// Generate 68K IPL 2
       }
    }

src/tom/tom.c

@@ -262,8 +262,11 @@
 #include "jaguar.h"
 #include "m68000/m68kinterface.h"
 #include "op.h"
+#include "perf_counters.h"
 #include "settings.h"
 
+PERF_COUNTER(timing_gpu_irqs_to_68k);
+
 // Red Color Values for CrY<->RGB Color Conversion
 uint8_t redcv[16][16] = {
    //  0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
@@ -1316,7 +1319,10 @@ void TOMExecPIT(uint32_t cycles)
          GPUSetIRQLine(GPUIRQ_TIMER, ASSERT_LINE);	// GPUSetIRQLine does the 'IRQ enabled' checking
 
          if (TOMIRQEnabled(IRQ_TIMER))
+         {
+            PERF_INC(timing_gpu_irqs_to_68k);
             m68k_set_irq(2);				// Cause a 68000 IPL 2...
+         }
 
          TOMResetPIT();
       }
@@ -1329,7 +1335,10 @@ void TOMPITCallback(void)
    GPUSetIRQLine(GPUIRQ_TIMER, ASSERT_LINE); // It does the 'IRQ enabled' checking
 
    if (TOMIRQEnabled(IRQ_TIMER))
+   {
+      PERF_INC(timing_gpu_irqs_to_68k);
       m68k_set_irq(2); // Generate a 68K IPL 2...
+   }
 
    TOMResetPIT();
 }