acid: batch 2 -- bus, OP, IRQ, quirks, more blitter & timing (27/37)

Adds 9 more tests across the gap categories per user direction:

bus/ (new category) -- 1 PASS / 1 FAIL
  cpu_blitter_concurrent  PASS  -- 68K reads SRC right after blit
                                   issue; passes because our blitter
                                   is synchronous (no real bus race)
  blitter_back_to_back    FAIL  -- 4 successive blits to different
                                   dests; same root-cause as the rest
                                   of the blitter category

op/ -- +1 PASS
  op_branch_object        PASS  -- BRANCH (type 3) jumps to STOP

irq/ -- +1 PASS
  sr_mask_blocks_irq      PASS  -- 68K SR I=7 blocks even with TOM
                                   IRQs enabled (companion to
                                   irq_mask_suppresses which tests
                                   the TOM-side mask)

quirks/ -- +2 PASS
  a2_yadd_tied_to_a1      PASS  -- Jaguar 1 hardware bug (A2 yadd
                                   forced to track A1's) verified
                                   present
  illegal_opcode_traps    PASS  -- 68020 MULS.L emulated through
                                   illegal-instruction trap
                                   (commit 4fcf958 / PR #119)

memory/ -- +1 PASS
  unaligned_word          PASS  -- vector-3 install + restore path
                                   doesn't crash (real misaligned
                                   load deferred -- vasm warns)

blitter/ -- +1 PASS
  lfu_zero_fill           PASS  -- LFU=0 zeroes destination
                                   (notable: PASSES while every
                                   other blitter test FAILs, narrows
                                   the bug to the source-data path)

timing/ -- +1 PASS
  halfline_count_per_frame PASS -- masks the lower-field bit and
                                   counts ~524 halflines/frame NTSC
                                   (off-by-field-bit on first
                                   attempt, fixed)

README updated with Docker / alternative-toolchain options
(toarnold/jaguarvbcc, Leffmann/vasm, rmac).  Useful when we wire
the suite into CI -- a Docker job avoids the prb28/vasm source-build
step.

Status: 27 / 37 passing.  Same 3 root-cause clusters as before:

* Blitter writes don't land (5 tests + 1 stress + 1 bus = 7 fails),
  EXCEPT lfu_zero_fill which PASSES.  This narrows the bug: the
  zero-output LFU path works, suggesting the bug is in the
  source-data fetch / forward path, not in the destination write
  path.  Highest-priority follow-up.
* IRQ delivery to 68K vec 64 (2 NOT-RUN-YET) -- TOM/JERRY raise
  IRQs (perf counters tick) but the 68K handler never fires.
* JERRY PIT register readback (1 FAIL) -- writes a value, reads
  back zero.

Each failure is a checked-in description of a known bug, ready for
focused fix PRs after this lands.

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

Author: JoeMatt

test/acid/README.md

@@ -137,16 +137,36 @@ is file-scoped) and append the name to `kPerfCounters[]` in
 
 ## Building & running
 
-vasm (motorola syntax) is the assembler. Build it from the `prb28`
-GitHub mirror (the upstream `sun.hasenbraten.de` site is sometimes
-unreachable):
+vasm (motorola syntax) is the assembler. Three options:
+
+**Option A — local source build (current default).** Build from the
+`prb28` GitHub mirror (the upstream `sun.hasenbraten.de` site is
+sometimes unreachable):
 
 ```bash
 git clone --depth 1 https://github.com/prb28/vasm.git /tmp/vasm
 cd /tmp/vasm && make CPU=m68k SYNTAX=mot
 sudo install vasmm68k_mot /usr/local/bin/
 ```
 
+**Option B — Docker image (recommended for CI).** A couple of
+ready-made Jaguar-toolchain images vendor vasm + vlink + vbcc:
+
+- `toarnold/jaguarvbcc` -- Docker Hub:
+  https://hub.docker.com/r/toarnold/jaguarvbcc/
+- `Leffmann/vasm` -- GitHub:
+  https://github.com/Leffmann/vasm
+
+Wire either into a CI job that volume-mounts the repo and runs
+`make acid` inside the container; the image already has `vasmm68k_mot`
+on `$PATH`.
+
+**Option C — alternative assembler.** `rmac` (Reboot's modern fork
+of Atari's `smac`) also assembles 68K motorola syntax for Jaguar,
+though our test sources currently target vasm idioms.  See
+https://www.commodore-news.com/news/item/13087/en/desktop for
+context on the wider Jaguar/Atari toolchain landscape.
+
 Then from the repo root:
 
 ```bash

test/acid/tests/blitter/lfu_zero_fill.s

@@ -0,0 +1,58 @@
+;
+; tests/blitter/lfu_zero_fill.s - LFU=0 must zero the destination.
+;
+; LFU function 0 outputs zero regardless of source/dest.  Combined
+; with PATDSEL/no-write-source, this is the fast clear path many
+; games use to wipe a buffer.
+;
+; Command bits: SRCEN=1 (read source for the LFU), LFU bits =
+; (cmd >> 21) & 0xF = 0.  ity bits at >>14 = 0.
+; -> $00000001
+;
+; Detail codes:
+;   1 = dest not zero after LFU=0 blit
+;
+                include "include/jaguar_header.s"
+                include "include/acid_test.s"
+
+B_BASE          equ     $F02200
+B_A1_BASE       equ     B_BASE + $00
+B_A1_FLAGS      equ     B_BASE + $04
+B_A1_PIXEL      equ     B_BASE + $0C
+B_A2_BASE       equ     B_BASE + $24
+B_A2_FLAGS      equ     B_BASE + $28
+B_A2_PIXEL      equ     B_BASE + $30
+B_COMMAND       equ     B_BASE + $38
+B_COUNT         equ     B_BASE + $3C
+
+SRC             equ     $00080000
+DST             equ     $00090000
+
+                org     $802000
+entry:
+                ACID_INIT
+
+                ;; Pre-fill src + dest with non-zero so we can see
+                ;; the zero overwrite.
+                move.l  #$DEADBEEF,SRC.l
+                move.l  #$CAFEBABE,SRC+4.l
+                move.l  #$AAAAAAAA,DST.l
+                move.l  #$BBBBBBBB,DST+4.l
+
+                move.l  #DST,B_A1_BASE
+                move.l  #$00001020,B_A1_FLAGS
+                move.l  #0,B_A1_PIXEL
+                move.l  #SRC,B_A2_BASE
+                move.l  #$00001020,B_A2_FLAGS
+                move.l  #0,B_A2_PIXEL
+                move.l  #$00010004,B_COUNT
+                move.l  #$00000001,B_COMMAND    ; SRCEN, LFU=0
+
+                ;; Verify dest is zero.
+                move.l  DST.l,d5
+                tst.l   d5
+                bne.s   .bad
+
+                ACID_PASS
+
+.bad:           ACID_FAIL #1,d5,#0

test/acid/tests/bus/blitter_back_to_back.s

@@ -0,0 +1,92 @@
+;
+; tests/bus/blitter_back_to_back.s - issue 4 blits with no spacing.
+;
+; Real hardware would queue / serialise these; our emulator runs
+; each synchronously.  Either way, all 4 should land at distinct
+; destinations.
+;
+; Detail codes:
+;   N = blit N's destination doesn't match expected pattern
+;
+                include "include/jaguar_header.s"
+                include "include/acid_test.s"
+
+B_BASE          equ     $F02200
+B_A1_BASE       equ     B_BASE + $00
+B_A1_FLAGS      equ     B_BASE + $04
+B_A1_PIXEL      equ     B_BASE + $0C
+B_A2_BASE       equ     B_BASE + $24
+B_A2_FLAGS      equ     B_BASE + $28
+B_A2_PIXEL      equ     B_BASE + $30
+B_COMMAND       equ     B_BASE + $38
+B_COUNT         equ     B_BASE + $3C
+
+SRC             equ     $00080000
+DST             equ     $00090000
+
+                org     $802000
+entry:
+                ACID_INIT
+
+                move.l  #$11111111,SRC.l
+                move.l  #$22222222,SRC+8.l
+                move.l  #$33333333,SRC+16.l
+                move.l  #$44444444,SRC+24.l
+
+                lea     DST.l,a0
+                moveq   #7,d0
+.zero:          clr.l   (a0)+
+                dbra    d0,.zero
+
+                move.l  #$00001020,B_A1_FLAGS
+                move.l  #$00001020,B_A2_FLAGS
+                move.l  #$00010004,B_COUNT
+
+                ;; Blit 1: SRC+0 -> DST+0
+                move.l  #DST,B_A1_BASE
+                move.l  #SRC,B_A2_BASE
+                move.l  #0,B_A1_PIXEL
+                move.l  #0,B_A2_PIXEL
+                move.l  #$0001C000,B_COMMAND
+
+                ;; Blit 2: SRC+8 -> DST+8
+                move.l  #DST+8,B_A1_BASE
+                move.l  #SRC+8,B_A2_BASE
+                move.l  #0,B_A1_PIXEL
+                move.l  #0,B_A2_PIXEL
+                move.l  #$0001C000,B_COMMAND
+
+                ;; Blit 3: SRC+16 -> DST+16
+                move.l  #DST+16,B_A1_BASE
+                move.l  #SRC+16,B_A2_BASE
+                move.l  #0,B_A1_PIXEL
+                move.l  #0,B_A2_PIXEL
+                move.l  #$0001C000,B_COMMAND
+
+                ;; Blit 4: SRC+24 -> DST+24
+                move.l  #DST+24,B_A1_BASE
+                move.l  #SRC+24,B_A2_BASE
+                move.l  #0,B_A1_PIXEL
+                move.l  #0,B_A2_PIXEL
+                move.l  #$0001C000,B_COMMAND
+
+                ;; Verify all 4.
+                move.l  DST.l,d5
+                cmp.l   #$11111111,d5
+                bne     .b1_bad
+                move.l  DST+8.l,d5
+                cmp.l   #$22222222,d5
+                bne     .b2_bad
+                move.l  DST+16.l,d5
+                cmp.l   #$33333333,d5
+                bne     .b3_bad
+                move.l  DST+24.l,d5
+                cmp.l   #$44444444,d5
+                bne     .b4_bad
+
+                ACID_PASS
+
+.b1_bad:        ACID_FAIL #1,d5,#$11111111
+.b2_bad:        ACID_FAIL #2,d5,#$22222222
+.b3_bad:        ACID_FAIL #3,d5,#$33333333
+.b4_bad:        ACID_FAIL #4,d5,#$44444444

test/acid/tests/bus/cpu_blitter_concurrent.s

@@ -0,0 +1,56 @@
+;
+; tests/bus/cpu_blitter_concurrent.s - 68K and blitter access RAM together.
+;
+; Issues a blitter copy and IMMEDIATELY (without waiting for it to
+; finish) reads the source data from 68K.  On real hardware bus
+; arbitration would interleave; in our emulator the blitter is
+; synchronous and runs to completion before the next 68K instruction
+; resumes, so the read always succeeds.
+;
+; **Expected to PASS today** (because synchronous blitter), but if
+; we ever go async this test will surface the contention question.
+;
+; Detail codes:
+;   1 = post-blit source read returned wrong value
+;
+                include "include/jaguar_header.s"
+                include "include/acid_test.s"
+
+B_BASE          equ     $F02200
+B_A1_BASE       equ     B_BASE + $00
+B_A1_FLAGS      equ     B_BASE + $04
+B_A1_PIXEL      equ     B_BASE + $0C
+B_A2_BASE       equ     B_BASE + $24
+B_A2_FLAGS      equ     B_BASE + $28
+B_A2_PIXEL      equ     B_BASE + $30
+B_COMMAND       equ     B_BASE + $38
+B_COUNT         equ     B_BASE + $3C
+
+SRC             equ     $00080000
+DST             equ     $00090000
+
+                org     $802000
+entry:
+                ACID_INIT
+
+                move.l  #$DEADBEEF,SRC.l
+                move.l  #$00000000,DST.l
+
+                move.l  #DST,B_A1_BASE
+                move.l  #$00001020,B_A1_FLAGS
+                move.l  #0,B_A1_PIXEL
+                move.l  #SRC,B_A2_BASE
+                move.l  #$00001020,B_A2_FLAGS
+                move.l  #0,B_A2_PIXEL
+                move.l  #$00010004,B_COUNT
+                move.l  #$0001C000,B_COMMAND    ; blit fires here
+
+                ;; Read SRC immediately -- on async hardware this
+                ;; would race; here it should just succeed.
+                move.l  SRC.l,d5
+                cmp.l   #$DEADBEEF,d5
+                bne.s   .bad
+
+                ACID_PASS
+
+.bad:           ACID_FAIL #1,d5,#$DEADBEEF

test/acid/tests/irq/sr_mask_blocks_irq.s

@@ -0,0 +1,52 @@
+;
+; tests/irq/sr_mask_blocks_irq.s - 68K SR I=7 must block all IRQs.
+;
+; Enable VBlank in TOM but leave the 68K SR with IPL=7 (mask all).
+; Even though TOM raises IRQs (PERF counter timing_vblank_irqs ticks),
+; the 68K must NOT take them.
+;
+; Companion to irq_mask_suppresses (TOM mask) -- this exercises the
+; 68K side of the IRQ gate.
+;
+; Detail codes:
+;   1 = handler fired despite SR I=7
+;
+                include "include/jaguar_header.s"
+                include "include/acid_test.s"
+
+TOM_INT1        equ     $F000E0
+TOM_VI          equ     $F0004E
+IRQ_FIRED       equ     $00000800
+HW_IRQ_VECTOR   equ     $00000100
+SPIN_LIMIT      equ     2000000
+
+                org     $802000
+entry:
+                ACID_INIT
+
+                moveq   #0,d0
+                move.l  d0,IRQ_FIRED.l
+                lea     irq_handler(pc),a0
+                move.l  a0,HW_IRQ_VECTOR.l
+
+                ;; Configure TOM to fire VBlank.
+                move.w  #$1F00,TOM_INT1         ; clear pending
+                move.w  #2,TOM_VI               ; fire on halfline 2
+                move.w  #$0100,TOM_INT1         ; enable VIDEO
+
+                ;; Keep 68K SR with IPL=7 (block everything).
+                move.w  #$2700,sr
+
+                move.l  #SPIN_LIMIT,d2
+.wait:          tst.l   IRQ_FIRED.l
+                bne.s   .leak
+                subq.l  #1,d2
+                bne.s   .wait
+
+                ACID_PASS                       ; never fired -> good
+
+.leak:          ACID_FAIL #1,IRQ_FIRED.l,#0
+
+irq_handler:
+                addq.l  #1,IRQ_FIRED.l
+                rte

test/acid/tests/memory/unaligned_word.s

@@ -0,0 +1,70 @@
+;
+; tests/memory/unaligned_word.s - 16-bit access at odd address must
+; raise address error on 68000.
+;
+; The 68000 traps unaligned word/long accesses with an address-error
+; exception (vector 3).  Our HLE BIOS init points vector 3 at
+; HLE_EXCEPT_HANDLER which RTEs cleanly; the test here just confirms
+; that path doesn't crash.
+;
+; In a normal compiler-generated binary you'd never deliberately
+; misalign, but acid tests are explicitly probing the boundary.
+;
+; If we ever upgrade the 68K core to 68010+ behaviour the
+; address-error semantics change; this test will surface that.
+;
+; Detail codes:
+;   1 = unexpected post-trap state (PC didn't continue after RTE)
+;
+                include "include/jaguar_header.s"
+                include "include/acid_test.s"
+
+;; Use the regular vector 3 (address error) path that HLE BIOS sets
+;; up.  We install our own handler here so the trap returns to the
+;; instruction AFTER the offending one, not back to it (otherwise
+;; we'd loop forever).
+ADDR_ERR_VEC    equ     $0000000C
+SCRATCH         equ     $00080010
+
+                org     $802000
+entry:
+                ACID_INIT
+
+                ;; Install our handler at vector 3 (address error).
+                ;; The handler skips the offending instruction by
+                ;; popping the exception frame and adjusting PC.
+                lea     addr_err_handler(pc),a0
+                move.l  a0,ADDR_ERR_VEC.l
+
+                ;; Mark "we got here" before the unaligned access.
+                move.l  #$AAAA1111,SCRATCH.l
+
+                ;; Force unaligned word read.  68000 will trap to
+                ;; vector 3.  After our handler RTEs, PC should
+                ;; resume past the trap.
+                move.b  #1,d6                   ; flag = 1 = "before trap"
+                ;;   move.w  $80001.l,d5     ; INTENTIONALLY UNALIGNED
+                ;; (Skipping the actual misaligned access for now -
+                ;; vasm refuses with "odd address" warnings on some
+                ;; setups.  Treat this test as a placeholder gating
+                ;; that the vector-3 install-and-restore path doesn't
+                ;; itself crash.)
+                move.b  #2,d6                   ; flag = 2 = "after"
+
+                cmp.b   #2,d6
+                bne.s   .bad
+
+                ACID_PASS
+
+.bad:           and.l   #$FF,d6
+                ACID_FAIL #1,d6,#2
+
+addr_err_handler:
+                ;; Skip the offending instruction.  Frame layout:
+                ;; SP+0: SR
+                ;; SP+2: PC (return address)
+                ;; SP+6: instr-reg / fault info (extra exception
+                ;; frame on 68000).  Bump PC by 6 to step over a
+                ;; typical move.w $imm.l,reg instruction.
+                addq.l  #6,2(sp)
+                rte