Add tests and test helpers

Signed-off-by: Joseph Mattiello <[email protected]>

Author: JoeMatt

.gitignore

@@ -32,3 +32,8 @@ chd_dump.c
 test/roms/private/*
 !test/roms/private/.gitkeep
 !test/roms/private/README.md
+/test/test_dsp_instructions
+/test/test_gpu_instructions
+/test/test_hle_bios
+/test/test_irq
+/test/test_m68k_instructions

Makefile

@@ -616,7 +616,52 @@ endif
 clean:
 	rm -f $(TARGET) $(OBJECTS)
 
-.PHONY: clean
+# --- Unit tests ---
+# Build tests against the dylib via dlsym.
+# Run: make test  (builds core + tests, then runs all test suites)
+
+TEST_CC     ?= $(CC)
+TEST_CFLAGS  = -O0 -g -Wno-incompatible-pointer-types
+TEST_LDFLAGS = -ldl
+TEST_BINS    = test/test_gpu_instructions test/test_dsp_instructions test/test_m68k_instructions test/test_irq test/test_hle_bios test/test_blitter_simd
+
+test/test_gpu_instructions: test/test_gpu_instructions.c test/test_framework.h $(TARGET)
+	$(TEST_CC) $(TEST_CFLAGS) -o $@ $< $(TEST_LDFLAGS)
+
+test/test_dsp_instructions: test/test_dsp_instructions.c test/test_framework.h $(TARGET)
+	$(TEST_CC) $(TEST_CFLAGS) -o $@ $< $(TEST_LDFLAGS)
+
+test/test_m68k_instructions: test/test_m68k_instructions.c test/test_framework.h $(TARGET)
+	$(TEST_CC) $(TEST_CFLAGS) -o $@ $< $(TEST_LDFLAGS)
+
+test/test_irq: test/test_irq.c test/test_framework.h $(TARGET)
+	$(TEST_CC) $(TEST_CFLAGS) -o $@ $< $(TEST_LDFLAGS)
+
+test/test_hle_bios: test/test_hle_bios.c test/test_framework.h $(TARGET)
+	$(TEST_CC) $(TEST_CFLAGS) -o $@ $< $(TEST_LDFLAGS)
+
+test/test_blitter_simd: test/test_blitter_simd.c src/blitter_simd.h $(TARGET)
+	$(TEST_CC) -O2 -o $@ test/test_blitter_simd.c src/blitter_simd_neon.c
+
+test-build: $(TEST_BINS)
+
+test: test-build
+	@echo ""; echo "=== Running unit tests ===" ; echo ""
+	@fail=0; \
+	for t in test/test_gpu_instructions test/test_dsp_instructions test/test_m68k_instructions test/test_irq test/test_hle_bios test/test_blitter_simd; do \
+		if [ -x "$$t" ]; then \
+			DYLD_LIBRARY_PATH=. LD_LIBRARY_PATH=. "$$t" > /tmp/vj_test_out.txt 2>&1; \
+			rc=$$?; \
+			grep -E 'PASS|FAIL|SKIP|===|---|Results:' /tmp/vj_test_out.txt; \
+			if [ $$rc -ne 0 ]; then fail=1; fi; \
+		fi; \
+	done; \
+	exit $$fail
+
+clean-test:
+	rm -f $(TEST_BINS) $(addsuffix .dSYM,$(TEST_BINS))
+
+.PHONY: clean test test-build clean-test
 endif
 
 print-%:

docs/test-infrastructure.md

@@ -66,6 +66,49 @@ Tests libretro SRAM interface for save game handling.
 ./test/sram_test.sh ./virtualjaguar_libretro.dylib
 ```
 
+## Unit Test Suites (make test)
+
+Six test suites run via `make test`, covering CPU emulation, interrupt handling,
+HLE BIOS, and blitter SIMD correctness.
+
+### test_gpu_instructions.c — GPU RISC ISA (51 tests)
+Arithmetic, logic, shift/rotate, compare, move/MOVEI, STORE/LOAD, saturation,
+register bank switching. Tests run GPU programs in GPU RAM via dlsym.
+
+### test_dsp_instructions.c — DSP RISC ISA (28 tests)
+Same ISA as GPU with DSP-specific differences: signed saturation (sat16s/sat32s
+instead of SAT8/SAT16), 8KB RAM at $F1B000.
+
+### test_m68k_instructions.c — Motorola 68000 (39 tests)
+MOVEQ, ADD/SUB/NEG/CLR, MULU/MULS/DIVU, SWAP, EXT, AND/OR/EOR/NOT,
+LSL/LSR/ASR/ROL/ROR, CMP/TST, memory addressing modes (direct, pre-dec,
+post-inc), LEA, ADDA/SUBA, BTST/BSET/BCLR.
+
+### test_irq.c — Interrupt Handling (18 tests)
+TOM IRQ enable/disable/latch/pending, JERRY IRQ enable, GPU IRQ assert/clear/IMASK,
+TOM video mode register, JERRY timer prescaler, BUTCH interrupt control.
+
+### test_hle_bios.c — HLE CD BIOS (14 tests)
+Jump table, CD_poll A1=0 convention, CD_wait_response, ISR setup handlers,
+TOC format, no-op entry safety, GPU auth magic, RAM byte order.
+
+### test_blitter_simd.c — Blitter SIMD (40,067 tests)
+Exhaustive bit-exact comparison of LFU, DCOMP, ZCOMP, byte_merge against
+reference implementations.
+
+### Build & Run
+```bash
+make -j4 DEBUG=1    # Build core
+make test           # Build & run all test suites
+make test-build     # Build tests only
+make clean-test     # Remove test binaries
+```
+
+### Framework (test_framework.h)
+Minimal single-header test framework with dlsym-based core loading.
+Provides GPU/DSP instruction encoding helpers, assert macros, and
+function pointers to all hardware subsystem functions.
+
 ## CI Integration
 
 GitHub Actions workflow (`.github/workflows/regression-test.yml`) runs
@@ -80,9 +123,14 @@ test/
   regression_test.sh       # Screenshot regression suite
   sram_test.sh             # SRAM interface test
   test_cd_boot.c           # CD boot diagnostics (C)
-  test_blitter_simd.c      # SIMD blitter test (C)
+  test_framework.h         # Unit test framework header
+  test_gpu_instructions.c  # GPU RISC ISA tests (51)
+  test_dsp_instructions.c  # DSP RISC ISA tests (28)
+  test_m68k_instructions.c # 68K CPU tests (39)
+  test_irq.c               # Interrupt handling tests (18)
+  test_hle_bios.c          # HLE CD BIOS tests (14)
+  test_blitter_simd.c      # SIMD blitter tests (40067)
   baselines/               # Reference PNG screenshots
   roms/                    # Test ROMs (private/ is git-ignored)
   tools/                   # Test ROM generators, SRAM test harness
-  cd_trace_*.log           # Debug logs from CD boot tests
 ```

libretro.c

@@ -382,6 +382,19 @@ static void check_variables(void)
          vjs.cdBiosType = CDBIOS_RETAIL;
    }
 
+   var.key = "virtualjaguar_cd_boot_mode";
+   var.value = NULL;
+
+   if (environ_cb(RETRO_ENVIRONMENT_GET_VARIABLE, &var) && var.value)
+   {
+      if (strcmp(var.value, "hle") == 0)
+         vjs.cdBootMode = CDBOOT_HLE;
+      else if (strcmp(var.value, "bios") == 0)
+         vjs.cdBootMode = CDBOOT_BIOS;
+      else
+         vjs.cdBootMode = CDBOOT_AUTO;
+   }
+
    var.key = "virtualjaguar_alt_inputs";
    var.value = NULL;
    if (environ_cb(RETRO_ENVIRONMENT_GET_VARIABLE, &var) && var.value)
@@ -1108,17 +1121,24 @@ bool retro_load_game(const struct retro_game_info *info)
       strncpy(cd_image_path, info->path, sizeof(cd_image_path) - 1);
       cd_image_path[sizeof(cd_image_path) - 1] = '\0';
 
-      /* For CD mode, force BIOS on -- CD games require the BIOS */
       vjs.useJaguarBIOS = true;
       vjs.useCDBIOS     = true;
 
-      /* Try to load an external CD BIOS from the system directory.
-       * If no external BIOS is found, we'll use HLE (High-Level
-       * Emulation) to boot the CD game directly. */
       cd_bios_loaded_externally = false;
-      if (!load_external_cd_bios())
+
+      if (vjs.cdBootMode == CDBOOT_HLE)
+      {
+         fprintf(stderr, "[CD] Boot mode: HLE (skipping BIOS search)\n");
+      }
+      else
       {
-         fprintf(stderr, "[CD] No external BIOS found — will use HLE boot path\n");
+         if (!load_external_cd_bios())
+         {
+            if (vjs.cdBootMode == CDBOOT_BIOS)
+               fprintf(stderr, "[CD] WARNING: Boot mode is BIOS but no external BIOS found\n");
+            else
+               fprintf(stderr, "[CD] No external BIOS found — will use HLE boot path\n");
+         }
       }
    }
 

libretro_core_options.h

@@ -161,6 +161,21 @@ struct retro_core_option_v2_definition option_defs_us[] = {
       },
       "retail"
    },
+   {
+      "virtualjaguar_cd_boot_mode",
+      "CD Boot Mode (Restart)",
+      NULL,
+      "How to boot Jaguar CD games. Auto uses the real BIOS if found, otherwise HLE. HLE always uses high-level emulation (no BIOS ROM needed). BIOS requires an external BIOS ROM file.",
+      NULL,
+      NULL,
+      {
+         { "auto", "Auto" },
+         { "hle",  "HLE (No BIOS Required)" },
+         { "bios", "BIOS (Required)" },
+         { NULL, NULL },
+      },
+      "auto"
+   },
    {
       "virtualjaguar_alt_inputs",
       "Enable Core Options Remapping",

src/settings.h

@@ -32,6 +32,7 @@ struct VJSettings
 	bool useFastBlitter;
 	bool useCDBIOS;
 	uint32_t cdBiosType;
+	uint32_t cdBootMode;
 
 	// Paths
 
@@ -48,6 +49,10 @@ enum { BT_K_SERIES, BT_M_SERIES, BT_STUBULATOR_1, BT_STUBULATOR_2 };
 
 enum { CDBIOS_RETAIL, CDBIOS_DEV };
 
+// CD boot modes
+
+enum { CDBOOT_AUTO, CDBOOT_HLE, CDBOOT_BIOS };
+
 // Exported variables
 
 extern struct VJSettings vjs;

test/headless.py

@@ -50,6 +50,8 @@ def parse_args() -> argparse.Namespace:
     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)")
+    p.add_argument("--cd-boot-mode", choices=["auto", "hle", "bios"], default="auto",
+                   help="CD boot mode: auto, hle, or bios (default: auto)")
     p.add_argument("--core", type=Path, default=None, help="Override core path")
     p.add_argument("--system-dir", type=Path, default=REPO_ROOT / "test" / "roms" / "private",
                    help="Directory containing BIOS files")
@@ -112,6 +114,7 @@ def language(self): return None
         "virtualjaguar_bios": "enabled",
         "virtualjaguar_usefastblitter": "enabled",
         "virtualjaguar_cd_bios_type": args.cd_bios,
+        "virtualjaguar_cd_boot_mode": args.cd_boot_mode,
     }
 
     paths = FixedPathDriver(args.system_dir, args.save_dir, core)