virtualjaguar-libretro/docs/jgd-interface-notes.md

Jaguar GameDrive (JagGD) interface notes — research for #312

Status: phases 1+2 of §9 are implemented (src/core/jaggd.c, core option virtualjaguar_jgd, savestate v8, test/test_jgd.c); the GD menu, SD/FAT filesystem, GPU async reads, encrypted .jgd and .MRQ remain out of scope. This document is the hardware/protocol spec of record for that implementation, at the quality bar of docs/memory-track.md.

Primary ground truth: RetroHQ's own published homebrew API (https://github.com/RetroHQ/JagGD, by SainT, the JagGD author). Unlike the Memory Track, we did NOT have to reconstruct this interface from third-party behavior — the cart-side 68K source (gdbios_bindings.s) is public and contains the SPI register addresses, bit definitions, the full handshake protocol, and the bank-switching semantics in SainT's own comments. Local copies of everything cited live in the research scratchpad (.../scratchpad/jaggd-api/, .../scratchpad/jagstudio/, .../scratchpad/bigpemu_disasm.txt).

Confidence labels used throughout:

• established — stated in RetroHQ source (gdbios_bindings.s / gdbios.h / README.md) or directly observable in shipped JagStudio code (RAPTORGD.O, disassembled and verified identical to the bindings).
• established-behavioral — read out of the BigPEmu 1.2x arm64 binary (/Applications/BigPEmu.app/Wrapper/BigPEmu.app/BigPEmu, disassembled) or its changelog. Tells us what the ecosystem's reference emulator does, not necessarily what silicon does.
• inferred — follows from the above but not directly stated.
• guessed — plausible, must be verified before relying on it.

---

1. Hardware model

The JagGD is a flash cart with (established, from the API source + product materials):

• 16 MB of onboard SDRAM presented to the Jaguar as cartridge ROM.
• An ASIC/FPGA that decodes the cart bus, maps SDRAM into the 6 MB cart window, and exposes a small SPI-style mailbox register set.
• A microcontroller ("the GD", "the micro" in SainT's comments) behind that SPI link. It owns the SD card, the FAT filesystem, serial numbers, the menu, firmware, and it serves the GDBIOS blob on request.

Communication model: the 68K talks to the micro through three registers in JERRY's GPIO2 decode range. Cart EEPROM already works exactly this way through GPIO0/GPIO1 ($F14800/$F15000, see src/jerry/eeprom.c), so the GPIO chip selects demonstrably route to the cartridge connector; GPIO2 is the next one up and is marked "reserved" in our own jerry.c address map (established by analogy + the fact that the GD API uses these addresses from cart code).

2. Register map

All from gdbios_bindings.s (established) unless noted.

Address	Name (RetroHQ)	Access	Meaning
$F16002	ASIC_SPI_STATUS	R/W 16-bit	Status + control, bits below
$F16004	ASIC_SPI_DATA	R/W 16-bit	Write = trigger one SPI byte exchange; word read = drain rx latch
$F16005	ASIC_SPI_DATA_BYTE	R 8-bit	Received byte (low byte of $F16004)

ASIC_SPI_STATUS bits (established):

Bit	Mask	Name	Direction	Meaning
0	$0001	SLAVE_SELECT	W	Assert slave select (ack packet start)
3	$0008	HAVE_DATA	R	Handshake bit; see GDWaitData below. Idle/ready state is clear; the slave raises it to ack/announce data
4	$0010	PACKET_START	W	Request packet start / block boundary ("process it, GD!")
5	$0020	LATCH_FULL	R	A received byte is sitting in the rx latch (must be drained before starting a transaction)
15	$8000	(busy)	R	Exchange in progress. All waits are tst.w $F16002 / bmi loops, i.e. spin while bit 15 set

Write of $0000 to $F16002 = end of packet / deselect (established — every transaction ends with clr.w ASIC_SPI_STATUS).

Data register semantics (established from code shape; exact tx byte order inferred): writing any word to $F16004 clocks one byte exchange. The transmitted byte is the low byte of the written word (inferred — see GDExchangeWord trace below; the bulk-read loop writes its loop counter as a don't-care dummy, so the written value is irrelevant when only receiving). After bit 15 clears, the received byte is read at $F16005.

GDExchangeWord (send a 16-bit word, receive a 16-bit word — established):

move.w  d0,$F16004        ; exchange byte #1
(wait not busy)
move.b  $F16005,d0        ; rx1 -> low byte
ror.w   #8,d0             ; rx1 -> high byte, old high byte -> low
move.w  d0,$F16004        ; exchange byte #2 (tx = old high byte)
(wait not busy)
move.b  $F16005,d0        ; result = rx1<<8 | rx2

GDWaitData (the packet handshake — established):

1. spin until HAVE_DATA (bit 3) == 0
2. write PACKET_START|SLAVE_SELECT ($0011) to $F16002
3. spin until HAVE_DATA == 1        ; slave ack

Consequence for a machine with no GD attached: step 3 never completes. There is no timeout anywhere in the RetroHQ or JagStudio code. See §6.

3. Micro packet protocol

Transaction shape (established, from _GD_HWVersion and _GD_Install):

write $0010 to STATUS            ; request packet start
GDWaitData                       ; handshake
GDExchangeWord(command)          ; 16-bit command word
GDExchangeWord(param_size)       ; 16-bit param byte count (0 if none)
[param bytes...]
write $0010 to STATUS            ; "we're done, process it GD!"
--- response ---
GDWaitData
GDExchangeWord / byte loop       ; response payload, format per command
write $0010 to STATUS            ; after each ≤512-byte block
...
write $0000 to STATUS            ; end of packet

Known command words (established):

Cmd	Function	Response
12 ($0C)	HW version	u32: high word = firmware version, BCD (e.g. $0111 = v1.11), low word = ASIC version, BCD. Read as two GDExchangeWords, high word first. After reading, the caller busy-waits ~500 dbra iterations "to let the micro finish up"
$80	Fetch GDBIOS	u16 blob size, then the blob streamed in ≤512-byte chunks, one PACKET_START write between chunks; each byte clocked out by a dummy word write to $F16004

Before $80, the installer drains the rx latch: while LATCH_FULL set, read $F16004 (word) and re-check ("in case of FIFO DMA termination", established).

All other micro commands (file I/O, serials, LED, reset, page set, …) are issued by the GDBIOS blob, not by game code, and their SPI encodings are unknown — and irrelevant for us, because the blob itself comes from the emulated micro, i.e. we get to supply our own blob (see §7). BigPEmu necessarily does the same thing (it cannot ship RetroHQ's copyrighted blob).

4. GDBIOS blob ABI (what games actually link against)

Games do not poke registers for anything except the two commands above. They call GD_Install(buffer) (a 4 KB, long-aligned RAM buffer), which:

1. Calls HW version (cmd 12); fails if firmware < $111 (v1.11) — established, both in RetroHQ bindings (MINVERSION... actually the FW gate) and JagStudio's RAPTOR_GD_Init (identical code, verified by disassembling RAPTORGD.O).
2. Streams the blob (cmd $80) into the buffer, stores the pointer (GDB_Base).
3. Checks blob version word ≥ $100, then calls blob function 1 (GD_Init).

Blob memory layout (established):

Offset	Size	Meaning
+0	u16	GDBIOS version, BCD, min $100
+2	u16	Highest function number implemented
+N*4	4 bytes	Entry point of function N (a 4-byte slot — enough for one bra.w/jmp stub)

Call convention (established): a6 = blob base; caller does cmp.w #N,2(a6) / blt fail then jsr N*4(a6). d0-d1/a0-a1 scratch, everything else callee-saved. Function numbers and register ABI:

N	Name	Args in	Returns (d0)
1	GD_Init	—	—
2	GD_InitGPURead	a0=GPU RAM buffer (224 bytes), d0=flags (0 preserve / 1 fast)	—
3	GD_BIOSVersion	—	u16 BCD
4	GD_ROMWriteEnable	d0=1 enable / 0 disable	—
5	GD_ROMSetPage	d0 = page<<16 | bank	—
6	GD_ROMSetPages	d0 = u32, one bank nibble per page, LSN = page 0	—
7	GD_GetCartSerial	a0=16-byte buffer	0 ok / !0 fail
8	GD_GetCardSerial	a0=16-byte buffer	0 ok / !0 fail
9	GD_CardIn	—	0 no / 1 yes
10	GD_FileOpen	a0=path, d0=mode	handle ≥0 / <0 fail
11	GD_FileClose	d0=handle	0 / <0
12	GD_FileSeek	d0 = flags<<16 | handle, d1=offset	0 / <0
13	GD_FileRead	d0 = flags<<16 | handle, a0=buffer, d1=size	0 / <0
14	GD_FileWrite	d0=handle, a0=buffer, d1=size	0 / <0
15	GD_FileTell	d0=handle	offset / $FFFFFFFF
16	GD_FileSize	d0=handle	size / $FFFFFFFF
17	GD_FileAsyncPos	—	pos
18	GD_FileAsyncWait	—	—
19	GD_FileAsyncActive	—	0/1
20	GD_FileInfo	a0=path, a1=buffer, d0=flags (bit0 = long name)	≥0 / <0
21	GD_DirOpen	a0=path	handle / <0
22	GD_DirRead	d0 = flags<<16 | handle, a0=buffer	≥0 / <0
23	GD_DirClose	d0=handle	0 / <0
24	GD_Reset	d0 = 0 normal / 1 to GD menu / 2 debug	—
25	GD_SetLED	d0=flags	—
26	GD_DebugString	a0=C string (→ virtual USB COM port)	—

GD_HWVersion is not a blob function — it is raw SPI in the binding and works pre-install.

5. Bank switching semantics

Verbatim from SainT's comments in gdbios_bindings.s (established):

ROMSetPage(u16 page, u16 bank)
  Page 0 : $8xxxxx      1 : $9xxxxx      2 : $axxxxx
       3 : $bxxxxx      4 : $cxxxxx      5 : $dxxxxx
  Bank 0-15 is 1MB pages of the onboard 16MB SDRAM

ROMSetPages(u32 banks)
  Set all SDRAM banks at once, one per nibble.
  Lowest significant nibble is page 0, upto nibble 5. Data above is ignored.

So:

• Granularity: 1 MB. The 6 MB cart window ($800000–$DFFFFF) is six independent 1 MB pages, each mappable to any of sixteen 1 MB banks of the 16 MB SDRAM. (established)
• Window: whole cart space. Note page 5 covers $Dxxxxx including the $DFFF00 BUTCH-overlay tail — for emulation, keep our existing $DFFF00–$DFFFFF handling above the banked read, exactly as today's dispatch already orders it. (inferred, trivially safe)
• Latch behavior: immediate on the next bus access; a page register is plain combinational address-translation state in the ASIC. No evidence of any delay or double-buffering. (inferred)
• Initial mapping: identity (page N → bank N) so that a flat ≤6 MB image looks like a normal cart, and a >6 MB image exposes its first 6 MB. (inferred — required for anything to boot at all; BigPEmu boots >6 MB images this way per its changelog)
• Writes: GD_ROMWriteEnable(1) makes the SDRAM-backed "ROM" writable (the GD menu uses this to load; homebrew can use cart space as extra RAM). Granularity global vs per-page unknown; assume global. (established that it exists; granularity guessed)
• How the real blob performs the switch is unknown (SPI command to the micro vs. a direct ASIC register). Deliberately irrelevant to us: games can only reach banking through the blob ABI, and the emulator supplies the blob. (established consequence)

6. GD detection — what a GD-locked title actually does

From JagStudio v1.11 (RAPTORGD.O disassembled; buildfiles/template/rapapp.s; projects/basic/jaguargd/) — JagStudio is what real GD homebrew (e.g. SKYLAR) is built with (established):

1. Projects opt in with useGD=1; startup then calls RAPTOR_GD_Init unconditionally, before DSP setup ("MUST be before DSP setup").
2. RAPTOR_GD_Init = RetroHQ's GD_Install with a detect flag: raptor_GD_detect = 1, run HW-version (cmd 12); if FW < $111 → GDB_Base = 0, detect = -1, return. Otherwise install blob + GD_Init.
3. Game code branches on raptor_GD_detect == 1 ("GD Cart Detected") — and every wrapped call re-checks GDB_Base != 0 and the function-count word, returning -1 gracefully when absent.

The failure mode without a GD is a hang, not a refusal: GDWaitData step 3 spins forever waiting for HAVE_DATA to go high. On our core today, $F16002 reads fall into the F14000–F1A0FF catch-all in src/jerry/jerry.c → EepromReadWord → returns $0000 for non-EEPROM offsets — bit 3 never rises, the 68K wedges in .waitAck, and crash_detect will report video_stall. BigPEmu with JGD off behaves the same way (its GD register special-case is gated on a JGD-enabled flag bit; disabled, the read falls through to a flat memory array) — which is exactly why Batocera tells users GD-locked games "won't boot" until they turn on Force JGD.

So the detection contract we must implement is precisely: status handshake (bit 3 sequencing + bit 15 busy + bit 5 drain), command 12 returning FW ≥ $111 (recommend $0300/$0102-style current-ish BCD values; anything ≥ $0111 works), and command $80 serving a valid blob.

What we do not have to implement for detection: serial numbers can return zeros-with-success (titles hard-locked to one physical cart serial are distributed as encrypted .jgd files we can't load anyway — out of scope, same as BigPEmu).

7. What BigPEmu does (established-behavioral)

From its changelog (mirrored at emunations.com) and the arm64 binary:

• v1.01 "Added JaguarGD bank switching support." v1.02 "Added an option to force Jaguar GD emulation, which enables bank switching even in ROM images smaller than 6MB" (config key ForceJGD; sits alongside AttachButch, AttachMT, ShareMT, CDSeekSpeed in BigPEmuConfig.System). v1.19 "Added more Jaguar GD functionality. Filesystem functions are stubbed out…"
• Its JERRY byte/word read+write handlers special-case addresses ≥ $F16002 behind a JGD-enable flag. The status read is synthesized: LATCH_FULL is set from a response-FIFO head≠tail comparison, and the read has side effects on the stored status bits (read-sensitive handshake emulation). PACKET_START writes raise a "process packet" flag consumed by a command engine that fills the response FIFO. I.e. BigPEmu emulates the GD at the SPI-register level for detection/install, matching §2–§3.
• GD function services are HLE'd host-side: its file-open paths read the filename out of emulated RAM and call host filesystem/wcslen code — i.e. the blob it serves is a thin trampoline into native handlers. (This is the v1.19 "filesystem stubs" layer.)
• Auto-enable: banking turns on automatically for images ≥ 6 MB; ForceJGD covers smaller GD-locked images. Our proposed core option virtualjaguar_jgd = disabled|auto|enabled maps 1:1.
• .MRQ (GD box-art/metadata sidecar) support is pure UI, ignore.

8. Remaining unknowns, and the cheapest experiment for each

Unknown	Impact	Cheapest resolution
Exact tx byte order of $F16004 word writes (low-byte-out inferred)	None if we implement to satisfy the binding code shape (we are the only slave); matters only for exotic homebrew doing raw SPI	Write a 20-line probe ROM from the bindings, run under BigPEmu with its scripting/debugger tracing $F16004; or ask SainT on AtariAge
Full micro SPI command set beyond 12/$80	None for scope of #312 (blob is ours)	Dump the real blob: run GD_Install on real hardware and save the 4 KB buffer to SD with GD_FileWrite — a ~30-line JagStudio program; also answers the next row
What the real GDBIOS ROMSetPage pokes	None (same reason); would be nice for a hardware-faithful mode	Same blob dump, disassemble
Initial page map on boot (identity assumed)	Boot of >6 MB images	Run SKYLAR 1.0 in BigPEmu, break before first ROMSetPage, checksum the six pages against file offsets
ROMWriteEnable granularity (global assumed)	Writable-cart feature only	Blob dump / SainT
Stock-console (no GD) read value at $F16002	Only affects how faithfully "GD absent" hangs; our current $0000 reproduces the observed hang class	Real-hardware probe; not needed for #312
Whether any homebrew calls raw SPI beyond GD_HWVersion	Compatibility ceiling	Corpus scan for $F160 word constants in ROM images once we have GD titles locally

None of these block implementation.

9. Implementation sketch (mapped onto our code)

New src/core/jaggd.c + jaggd.h (mirror memtrack.c structure):

• State: jgdEnabled (from core option virtualjaguar_jgd = disabled|auto|enabled; auto = on when image > 0x5FFF00 bytes), uint8_t jgdPage[6] (init 0..5), full-image buffer jgdROM (≤16 MB; jaguarMainROM/jagMemSpace cart region stays as-is for the non-GD path), SPI engine: status, small state machine (IDLE → HANDSHAKE → CMD → LEN → PARAMS → RESPONSE), response byte-FIFO, rxLatch.
• Register hook: in src/jerry/jerry.c, intercept $F16000–$F16007 in JERRYReadByte/Word and JERRYWriteByte/Word before the F14000–F1A0FF EEPROM catch-all (which currently swallows these addresses), delegating to JGDControlRead/Write when jgdEnabled. Behavior per §2–§3: implement exactly the sequence the bindings perform; respond to cmd 12 with FW $0300 / ASIC $0102 (any BCD ≥ $0111 FW), cmd $80 with our blob; unknown commands → zero-filled responses.
• The served blob: ~200 bytes of hand-written 68K, embedded via bin2c like src/bios/* (source checked in under src/bios/ with its build script, same pattern as the CD boot stub). Header $0100, func count 26. Implemented: 1 (rts), 3 (version), 4 (write enable), 5/6 (page set), 7/8 (zero serial, return 0), 9 (return 0), 24 (write to reset backdoor — or just rts initially), 25/26 (rts); file/dir/async functions return -1 (moveq #-1,d0; rts — BigPEmu also only "stubs" these; genuinely implementing them against a host directory is possible later via the same backdoor). Banking mechanism for the blob: functions 5/6 write the packed bank value to a backdoor register we define at $F16006 (word write, inside the GPIO2 range we already own; nothing else decodes it). This keeps the blob 68K-only and trivially small, and keeps all interpretation in jaggd.c. retro_deinit must reset all of this (iOS static-state rule).
• Cart read path: in src/core/jaguar.c JaguarReadByte/Word/Long cart branches (and the DMA/JaguarRead*-alike helpers at lines ~659-690), when jgdBankingActive: off = address - 0x800000; return jgdROM[((uint32_t)jgdPage[off >> 20] << 20) | (off & 0xFFFFF)] — one table lookup + shift, same cost class as the existing MEMTRACK gate. Word/long reads that could straddle a 1 MB boundary: only possible for the odd-address/boundary cases; handle by composing bytes (straddling reads are already rare/degenerate on real carts). GD_ROMWriteEnable makes the same translation apply in JaguarWriteByte/Word cart branches (write into jgdROM).
• Loader: src/core/file.c JaguarLoadROM/callers currently cap at the cart window; accept up to 0x1000000 (16 MB), copy first 6 MB into jaguarMainROM for the flat path, keep full image in jgdROM, set auto-enable. (Alignment/padding to 1 MB multiple.)
• Savestate: serialize jgdEnabled(active), jgdPage[6], SPI engine state + FIFO; single version bump per release policy (docs/savestate-compat.md). The 16 MB image itself is NOT serialized (same as cart ROM today) — but pages written via ROMWriteEnable are dirty state; simplest correct v1: serialize a dirty flag and, if any write occurred, the full written-page set. (Defer: most titles won't write.)
• Memory map / RA: test/tools/test_memory_map.c expects the current descriptor layout; cart descriptor stays the 6 MB window (it describes the 68K address space, which is unchanged).
• Out of scope (match BigPEmu): GD menu, SD/FAT filesystem semantics, GD_InitGPURead GPU async reads (function 2 = rts; GD_FREAD_GPU modes are documented to not function without it, so returning -1 from FileRead keeps the contract honest), .jgd encrypted images, .MRQ sidecars.

Suggested implementation order: (1) register hook + detection handshake + blob install — gets "GD Cart Detected" on the JagStudio example; (2) banking

• 6 MB loader — gets SKYLAR; (3) savestate + core option plumbing + tests.

9b. SD-card file API (#783), as implemented

Blob functions 9-16, 20-23 and 26 are answered from a host folder acting as the SD card. This supersedes the "file/dir functions return -1" line in §9.

• The card folder: jaggd-sd inside the frontend's save directory, or the system directory if there is none. It is created on first use.
  • Core option virtualjaguar_jgd_sd sets access: Read/write (default), Read-only, or Disabled.
  • Frontends that bypass libretro.c call JGDFSSetRoot() / JGDFSSetAccess().
• Call path: each of those blob slots is one word write, $C000 | function, to the $F16006 backdoor.
  • The core services the call during that write: JGDHostCall in jaggd.c reads the 68K's d0/d1/a0/a1, and the result goes back in d0 via m68k_set_reg.
  • Safe because the 68K's JERRY writes are synchronous, and the stub's move.w #imm,abs.l never touches d0 afterwards.
  • Only a 68K write triggers it; GPU, DSP and blitter writes to $F16006 are ignored.
  • The call completes inside one write, so no half-finished call can land in a savestate.
• Emulated memory: paths and buffers move through JaguarReadByte/JaguarWriteByte as the 68K, so watchers see the writes.
  • Paths are capped at 255 characters plus NUL; a path with no terminator fails.
  • Buffer ranges are checked against the 24-bit bus.
• The ABI, from RetroHQ's published gdbios.h / gdbios_bindings.s (facts only; their files are not in this tree):
  • Open modes are FatFs FA_*: READ $01, WRITE $02, CREATE_NEW $04, CREATE_ALWAYS $08, OPEN_ALWAYS $10, OPEN_APPEND $30. Any write or create flag needs a writable card (the FatFs rule).
  • FileRead: d0 = flags<<16 | handle. Flags other than GD_FREAD_CPU (0) need GD_InitGPURead, which is not emulated, so they return -1. Returns 0 on success. A short read at end of file is success, as with FatFs f_read; the program finds the count with FileTell.
  • FileSeek: d0 = whence<<16 | handle (SET/CUR/END = 0/1/2), d1 = offset.
  • FileWrite returns 0 on success. FileTell and FileSize return $FFFFFFFF on failure.
  • FileInfo / DirRead records are big-endian with no padding, matching FatFs FILINFO:
    • offset 0: u32 size
    • offset 4: u16 date (year-1980)<<9 | month<<5 | day
    • offset 6: u16 time hour<<11 | min<<5 | sec/2
    • offset 8: u8 attributes ($10 dir, $20 file, $01 read-only card)
    • offset 9: char[13] 8.3 name
    • offset 22: char[256] long name, long form only
    • Short record 22 bytes, long 278. The date/time comments in gdbios.h are swapped; this is the FatFs encoding.
  • End of directory: not documented. DirRead returns -1 and writes a record with zeroed names, so a >= 0 loop and a name[0] != 0 loop both stop.
  • Errors: every failure is the full 32-bit -1, so .w and .l sign tests both see it.
• Sandbox:
  • Accepted: a leading 0: drive, and both / and \ as separators.
  • Refused: .., any other drive letter, FAT-invalid characters, a file used as a directory, and (on POSIX hosts) any symlink under the root.
  • Each component is matched case-insensitively, since FAT is.
• Limits:
  • 8 open files and 4 open directories.
  • The 8.3 alias of an over-long name is BASENA~1.EXT, FatFs's first alias; no collision numbering.
  • On non-POSIX hosts the timestamp is fixed at 1980-01-01.
• Run-ahead / netplay: writes to the card are host side effects. A run-ahead replay of a positional write rewrites the same bytes, so it converges. A CREATE_NEW replayed after rollback finds the file already present and fails, so avoid run-ahead for software that creates files. Netplay peers each have their own card folder; differing contents desync.
• Savestate: see docs/savestate-compat.md v17 ("JGF1").
• Still out of scope: GPU and async reads (functions 2, 17-19), GD_Reset (24), and GD_SetLED (25).

10. Test cases

Title	What it exercises	Local availability
JagStudio jaguargd example	GD_Install, detect flag, serials, LED, file I/O — prints "GD Cart Detected"/"NOT Detected" on screen	Yes — prebuilt build/jaguargd.bin (BJL/RAM-load format) in the scratchpad JagStudio tree; rebuild to .rom with JagStudio (Windows/Wine or the shipped jaggd-x64 tooling) for a cart image
SKYLAR 1.0 preview (JagFest 2024)	The real thing: 16 MB image, live ROMSetPage banking + GD file access	No — download from the AtariAge thread ("SKYLAR 1.0 - 16MB BankSwitching GameDrive ROM", topic 371072; needs the SKYLAR directory on "SD card" — file calls will return -1 under our stub, so expect partial function: boot+banking yes, streamed assets no
Own probe ROM (recommended)	Deterministic harness ROM built with rmac + the RetroHQ bindings: install, ROMSetPages, checksum each page window, report via screen color / RAM flag readable by harness_dlsym	Build ourselves — best regression asset, no distribution problem, drop into test/roms/
GD-locked commercial homebrew	The ForceJGD path for <6 MB images	None in the local corpus (scanned test/roms/private — no GD titles, nothing >4 MB unpacked). Names of specific GD-locked retail homebrew were not pinned down by public sources during this research; Batocera/BigPEmu docs confirm the class exists without naming titles. Acquire via AtariAge when needed; the probe ROM covers the mechanism in the meantime

The local corpus check: test/roms/private/ROMS is a classic-era set (139 retail entries + PD folder); no GD-aware or >6 MB images. The two >4 MB files are 7z archives (Ultra Vortek, PD collection).

11. Source index (provenance)

• github.com/RetroHQ/JagGD — gdbios.h, gdbios_bindings.s, README.md (SainT/RetroHQ, official). Registers, bits, protocol, blob ABI, page/bank semantics, GPU-read notes. Cloned to scratchpad jaggd-api/.
• JagStudio v1.11 (reboot-games.com/jagstudio/releases/jagstudio-v1.11.zip) — buildfiles/raptor/RAPTORGD.O (disassembled with capstone; byte-for-byte the same logic as the bindings + raptor_GD_detect), RAPTORGD.INC, template/rapapp.s (useGD=1 init ordering), projects/basic/jaguargd/ example. Scratchpad jagstudio/.
• BigPEmu macOS arm64 binary — JERRY handler special-cases at 0x1001d0a0c/0x1001d1f88/0x1001d22f8 (GD SPI status/data emulation, gated on a mode flag), GD filesystem HLE cluster near 0x10014b150 (host-side file ops on emulated-RAM filenames), config key block (ForceJGD next to AttachButch/AttachMT). Disasm at scratchpad bigpemu_disasm.txt (2M lines).
• BigPEmu changelog v1.01/v1.02/v1.19 via emunations.com mirror; BigPEmu user manual (richwhitehouse.com) for MRQ note.
• AtariAge topic 371072 (SKYLAR 1.0) — existence/shape of a real 16 MB banking title; JagStudio credit "Rik, CJ and SainT for implementing … Bankswitching / GameDrive files … in JagStudio".
• Batocera wiki systems:jaguar — user-facing confirmation that GD-locked games need Force JGD Emulation.
• This repo: src/jerry/jerry.c GPIO map comment (F16000-F16FFF = GPIO2 reserved; F14000-F1A0FF catch-all currently swallowing GD addresses via EepromReadByte → $0000), src/core/jaguar.c cart dispatch + MEMTRACK overlay pattern, src/jerry/eeprom.c GPIO0/1 precedent that GPIO decodes reach the cart connector.