Upload 2 files

gb_console.py

@@ -0,0 +1,373 @@
+"""
+gb_console.py -- the full DMG console around the SM83 core: MMU with MBC1/MBC5
+banking, the complete PPU (background + window + sprites, per-dot pixel emission,
+variable-length mode 3 with the SCX fine-scroll penalty, STAT/LYC and VBlank
+interrupt lines, OAM DMA), the DIV/TIMA timer, joypad, and serial-out capture.
+
+The PPU's pixel datapath runs through the units API: tile-row decode, palette
+apply, and the sprite-priority mux are gb_units units (golden fns or verified
+neural nets); the rest is address wiring and scheduling -- the orchestrator the
+README describes as standard cycle-accurate emulator engineering.
+
+Simplifications (documented, identical in golden and neural runs so comparisons
+stay meaningful): OAM DMA copies instantly at the write; no sprite-fetch mode-3
+stalls (mode 3 length = 172 + SCX%8); no OAM/VRAM access blocking by mode.
+"""
+import numpy as np
+from gb_sm83 import SM83, IF_VBLANK, IF_STAT, IF_TIMER
+
+DOTS_PER_LINE, LINES_TOTAL, LINES_VIS = 456, 154, 144
+
+
+class PPU:
+    def __init__(self, bus, units, render=True):
+        self.bus = bus; self.u = units; self.render = render
+        self.fb = np.zeros((LINES_VIS, 160), np.uint8)
+        self.ly = 0; self.lx = 0; self.mode = 2
+        self.win_line = 0; self.stat_line = 0
+        self.frame = 0; self.frame_done = False
+        self.line_sprites = []
+        self.bg_cache = None; self.win_cache = None
+
+    # ---- per-line setup ----
+    def oam_scan(self):
+        io = self.bus.io; oam = self.bus.oam
+        h = 16 if io[0x40] & 0x04 else 8
+        sel = []
+        for i in range(40):
+            sy = int(oam[i * 4])
+            if sy <= self.ly + 16 < sy + h:
+                sel.append(i)
+                if len(sel) == 10: break
+        # DMG priority: lower X wins, ties by OAM order (stable sort)
+        self.line_sprites = sorted(sel, key=lambda i: int(oam[i * 4 + 1]))
+
+    def sprite_pixel(self, x):
+        """Winning sprite (idx, palette#, bg-priority) at screen x, or None."""
+        io = self.bus.io; oam = self.bus.oam; vram = self.bus.vram
+        h = 16 if io[0x40] & 0x04 else 8
+        for i in self.line_sprites:
+            sx = int(oam[i * 4 + 1])
+            if not (sx <= x + 8 < sx + 8):
+                continue
+            sy, tile, attr = int(oam[i * 4]), int(oam[i * 4 + 2]), int(oam[i * 4 + 3])
+            row = self.ly + 16 - sy
+            if attr & 0x40: row = h - 1 - row                 # Y flip
+            if h == 16: tile = (tile & 0xFE) | (row >> 3); row &= 7
+            base = tile * 16 + row * 2
+            idx = self.u.tilerow(int(vram[base]), int(vram[base + 1]))
+            col = x + 8 - sx
+            if attr & 0x20: col = 7 - col                     # X flip
+            ci = idx[col]
+            if ci != 0:
+                return ci, (attr >> 4) & 1, (attr >> 7) & 1
+        return None
+
+    def bg_pixel(self, x):
+        io = self.bus.io; vram = self.bus.vram
+        lcdc = int(io[0x40])
+        use_win = (lcdc & 0x20) and self.ly >= int(io[0x4A]) and x >= int(io[0x4B]) - 7
+        if use_win:
+            wy = self.win_line; wx = x - (int(io[0x4B]) - 7)
+            map_base = 0x1C00 if lcdc & 0x40 else 0x1800
+            ty, tx, fy, fx = wy >> 3, wx >> 3, wy & 7, wx & 7
+            key = ("w", tx, ty)
+            cache = self.win_cache
+        else:
+            sy = (self.ly + int(io[0x42])) & 0xFF; sx = (x + int(io[0x43])) & 0xFF
+            map_base = 0x1C00 if lcdc & 0x08 else 0x1800
+            ty, tx, fy, fx = sy >> 3, sx >> 3, sy & 7, sx & 7
+            key = ("b", tx, ty)
+            cache = self.bg_cache
+        if cache is None or cache[0] != key:
+            tid = int(vram[map_base + ty * 32 + tx])
+            if lcdc & 0x10: base = tid * 16 + fy * 2
+            else: base = 0x1000 + (tid - 256 if tid > 127 else tid) * 16 + fy * 2
+            row = self.u.tilerow(int(vram[base]), int(vram[base + 1]))
+            cache = (key, row, fy)
+            if use_win: self.win_cache = cache
+            else: self.bg_cache = cache
+        elif cache[2] != fy:
+            tid = int(vram[map_base + ty * 32 + tx])
+            if lcdc & 0x10: base = tid * 16 + fy * 2
+            else: base = 0x1000 + (tid - 256 if tid > 127 else tid) * 16 + fy * 2
+            cache = (key, self.u.tilerow(int(vram[base]), int(vram[base + 1])), fy)
+            if use_win: self.win_cache = cache
+            else: self.bg_cache = cache
+        return cache[1][fx], use_win
+
+    def emit_pixel(self, x):
+        io = self.bus.io
+        lcdc = int(io[0x40])
+        bg_ci = 0; used_win = False
+        if lcdc & 0x01:
+            bg_ci, used_win = self.bg_pixel(x)
+        sp = self.sprite_pixel(x) if lcdc & 0x02 else None
+        if sp is not None and self.u.sprmux(bg_ci, sp[0], sp[2]):
+            shade = self.u.palette(sp[0], int(io[0x49 if sp[1] else 0x48]))
+        else:
+            shade = self.u.palette(bg_ci, int(io[0x47])) if lcdc & 0x01 else 0
+        self.fb[self.ly, x] = shade
+        return used_win
+
+    # ---- STAT machinery ----
+    def update_stat(self):
+        io = self.bus.io
+        coinc = int(self.ly == int(io[0x45]))
+        io[0x41] = (io[0x41] & 0xF8) | (coinc << 2) | self.mode
+        line = ((int(io[0x41] >> 6) & 1) and coinc) or \
+               (((io[0x41] >> 5) & 1) and self.mode == 2) or \
+               (((io[0x41] >> 4) & 1) and self.mode == 1) or \
+               (((io[0x41] >> 3) & 1) and self.mode == 0)
+        line = int(bool(line))
+        if line and not self.stat_line:
+            self.bus.req_if(IF_STAT)
+        self.stat_line = line
+
+    def set_mode(self, m):
+        if m != self.mode:
+            self.mode = m
+            self.update_stat()
+
+    # ---- the dot clock ----
+    def tick(self, dots):
+        io = self.bus.io
+        if not (io[0x40] & 0x80):                      # LCD off
+            self.ly = 0; self.lx = 0; self.mode = 0
+            io[0x44] = 0
+            return
+        if not self.render:
+            self.tick_fast(dots)
+            return
+        for _ in range(dots):
+            lx, ly = self.lx, self.ly
+            if ly < LINES_VIS:
+                if lx == 0:
+                    self.oam_scan(); self.set_mode(2)
+                    self.bg_cache = self.win_cache = None
+                    self.win_used = False
+                elif lx == 80:
+                    self.set_mode(3)
+                scx_pen = int(io[0x43]) & 7
+                px = lx - 80 - scx_pen
+                if self.render and 80 <= lx and 0 <= px < 160:
+                    if self.emit_pixel(px):
+                        self.win_used = True
+                if lx == 80 + scx_pen + 172:
+                    self.set_mode(0)
+                    if not self.render:
+                        # window line counter must advance even without rendering
+                        lcdc = int(io[0x40])
+                        if (lcdc & 0x20) and ly >= int(io[0x4A]) and int(io[0x4B]) - 7 < 160:
+                            self.win_used = True
+            self.lx += 1
+            if self.lx == DOTS_PER_LINE:
+                self.lx = 0
+                if ly < LINES_VIS and getattr(self, "win_used", False):
+                    self.win_line += 1
+                self.ly += 1
+                if self.ly == LINES_VIS:
+                    self.set_mode(1); self.bus.req_if(IF_VBLANK)
+                elif self.ly == LINES_TOTAL:
+                    self.ly = 0; self.win_line = 0
+                    self.frame += 1; self.frame_done = True
+                io[0x44] = self.ly
+                self.update_stat()
+
+    def tick_fast(self, dots):
+        """No pixel emission: jump between mode boundaries instead of per-dot.
+        LY/mode/STAT/VBlank/window-line behavior identical to the per-dot path."""
+        io = self.bus.io
+        while dots:
+            if self.lx == 0 and self.ly < LINES_VIS:
+                self.set_mode(2)
+            scx_pen = int(io[0x43]) & 7
+            m3_end = 80 + scx_pen + 172
+            if self.ly < LINES_VIS:
+                nxt = 80 if self.lx < 80 else (m3_end if self.lx < m3_end else DOTS_PER_LINE)
+            else:
+                nxt = DOTS_PER_LINE
+            step = min(dots, nxt - self.lx)
+            self.lx += step; dots -= step
+            if self.ly < LINES_VIS:
+                if self.lx == 80: self.set_mode(3)
+                elif self.lx == m3_end and self.mode == 3:
+                    self.set_mode(0)
+                    lcdc = int(io[0x40])
+                    if (lcdc & 0x20) and self.ly >= int(io[0x4A]) and int(io[0x4B]) - 7 < 160:
+                        self.win_line += 1
+            if self.lx == DOTS_PER_LINE:
+                self.lx = 0; self.ly += 1
+                if self.ly == LINES_VIS:
+                    self.set_mode(1); self.bus.req_if(IF_VBLANK)
+                elif self.ly == LINES_TOTAL:
+                    self.ly = 0; self.win_line = 0
+                    self.frame += 1; self.frame_done = True
+                io[0x44] = self.ly
+                self.update_stat()
+
+
+class Bus:
+    def __init__(self, rom, units, render=True):
+        self.rom = np.frombuffer(bytes(rom), dtype=np.uint8)
+        cart = self.rom[0x147]
+        self.mbc = 5 if cart in (0x19, 0x1A, 0x1B, 0x1C, 0x1D, 0x1E) else \
+                   (1 if cart in (0x01, 0x02, 0x03) else 0)
+        self.rom_bank = 1; self.ram_bank = 0; self.ram_on = False
+        self.cart_ram = np.zeros(0x8000, np.uint8)
+        self.vram = np.zeros(0x2000, np.uint8)
+        self.wram = np.zeros(0x2000, np.uint8)
+        self.oam = np.zeros(0xA0, np.uint8)
+        self.hram = np.zeros(0x7F, np.uint8)
+        self.io = np.zeros(0x80, np.uint8)
+        self.ie = 0
+        self.io[0x40] = 0x91; self.io[0x41] = 0x85; self.io[0x47] = 0xFC
+        self.io[0x00] = 0xCF; self.io[0x0F] = 0xE1
+        self.divt = 0xAB00
+        self.serial = []
+        self.keys = set()        # subset of {"right","left","up","down","a","b","select","start"}
+        self.ppu = PPU(self, units, render)
+        self.cycles = 0
+
+    def req_if(self, bit): self.io[0x0F] |= bit
+    def clear_IF(self, bit): self.io[0x0F] &= ~bit & 0xFF
+    def io_IE(self): return self.ie
+    def io_IF(self): return int(self.io[0x0F])
+
+    # ---- timer: divt is the t-cycle counter; DIV is bits 8..15. TIMA increments on
+    # falling edges of the TAC-selected bit, i.e. once per 2^(bit+1) t-cycles ----
+    TAC_BITS = {0: 9, 1: 3, 2: 5, 3: 7}
+    def timer_tick(self, t):
+        old = self.divt
+        self.divt += t
+        tac = int(self.io[0x07])
+        if tac & 4:
+            period = 1 << (self.TAC_BITS[tac & 3] + 1)
+            n = self.divt // period - old // period
+            if n:
+                tima = int(self.io[0x05]) + n
+                if tima > 0xFF:
+                    tma = int(self.io[0x06])
+                    tima = tma + (tima - 0x100) % max(1, 0x100 - tma)
+                    self.req_if(IF_TIMER)
+                self.io[0x05] = tima
+
+    def tick(self, m):
+        self.cycles += m
+        self.timer_tick(4 * m)
+        self.ppu.tick(4 * m)
+
+    # ---- address decode ----
+    def read(self, a):
+        self.tick(1)
+        return self._read(a)
+    def _read(self, a):
+        a &= 0xFFFF
+        if a < 0x4000:
+            return int(self.rom[a])
+        if a < 0x8000:
+            bank = self.rom_bank % max(1, len(self.rom) // 0x4000)
+            return int(self.rom[bank * 0x4000 + (a - 0x4000)])
+        if a < 0xA000: return int(self.vram[a - 0x8000])
+        if a < 0xC000:
+            if not self.ram_on: return 0xFF
+            return int(self.cart_ram[(self.ram_bank * 0x2000 + (a - 0xA000)) % 0x8000])
+        if a < 0xE000: return int(self.wram[a - 0xC000])
+        if a < 0xFE00: return int(self.wram[a - 0xE000])
+        if a < 0xFEA0: return int(self.oam[a - 0xFE00])
+        if a < 0xFF00: return 0xFF
+        if a == 0xFF00:
+            sel = int(self.io[0x00]); low = 0x0F
+            if not sel & 0x10:                          # d-pad selected (low = pressed)
+                for bit, k in enumerate(("right", "left", "up", "down")):
+                    if k in self.keys: low &= ~(1 << bit)
+            if not sel & 0x20:                          # buttons selected
+                for bit, k in enumerate(("a", "b", "select", "start")):
+                    if k in self.keys: low &= ~(1 << bit)
+            return (sel & 0x30) | 0xC0 | low
+        if a == 0xFF04: return (self.divt >> 8) & 0xFF
+        if a == 0xFFFF: return self.ie
+        if a < 0xFF80: return int(self.io[a - 0xFF00])
+        return int(self.hram[a - 0xFF80])
+
+    def write(self, a, v):
+        self.tick(1)
+        self._write(a, v)
+    def _write(self, a, v):
+        a &= 0xFFFF; v &= 0xFF
+        if a < 0x8000:
+            if self.mbc == 5:
+                if a < 0x2000: self.ram_on = (v & 0x0F) == 0x0A
+                elif a < 0x3000: self.rom_bank = (self.rom_bank & 0x100) | v
+                elif a < 0x4000: self.rom_bank = (self.rom_bank & 0xFF) | ((v & 1) << 8)
+                elif a < 0x6000: self.ram_bank = v & 0x0F
+            elif self.mbc == 1:
+                if a < 0x2000: self.ram_on = (v & 0x0F) == 0x0A
+                elif a < 0x4000:
+                    v &= 0x1F; self.rom_bank = (self.rom_bank & 0x60) | (v if v else 1)
+                elif a < 0x6000: self.rom_bank = (self.rom_bank & 0x1F) | ((v & 3) << 5)
+            return
+        if a < 0xA000: self.vram[a - 0x8000] = v; return
+        if a < 0xC000:
+            if self.ram_on:
+                self.cart_ram[(self.ram_bank * 0x2000 + (a - 0xA000)) % 0x8000] = v
+            return
+        if a < 0xE000: self.wram[a - 0xC000] = v; return
+        if a < 0xFE00: self.wram[a - 0xE000] = v; return
+        if a < 0xFEA0: self.oam[a - 0xFE00] = v; return
+        if a < 0xFF00: return
+        if a == 0xFF04: self.divt = 0; return
+        if a == 0xFF46:                                # OAM DMA (instant copy)
+            self.io[0x46] = v
+            src = v << 8
+            for i in range(0xA0):
+                self.oam[i] = self._read(src + i)
+            return
+        if a == 0xFF02 and v & 0x80:                   # serial transfer start
+            self.serial.append(int(self.io[0x01]))
+            self.io[0x02] = v & 0x7F
+            return
+        if a == 0xFF41:                                # STAT: low 3 bits read-only
+            self.io[0x41] = (self.io[0x41] & 0x07) | (v & 0xF8)
+            self.ppu.update_stat(); return
+        if a == 0xFF44: return                         # LY read-only
+        if a == 0xFFFF: self.ie = v; return
+        if a < 0xFF80: self.io[a - 0xFF00] = v; return
+        self.hram[a - 0xFF80] = v
+
+
+class Console:
+    def __init__(self, rom, units, render=True):
+        self.bus = Bus(rom, units, render)
+        self.cpu = SM83(self.bus, units)
+    def run_frame(self, max_steps=5_000_000):
+        self.bus.ppu.frame_done = False
+        for _ in range(max_steps):
+            self.cpu.step()
+            if self.bus.ppu.frame_done:
+                return
+        raise RuntimeError("frame did not complete")
+    def serial_text(self):
+        return bytes(self.bus.serial).decode("ascii", "replace")
+
+    # ---- state snapshot, for switching units mid-run ----
+    def snapshot(self):
+        c, b = self.cpu, self.bus
+        return dict(
+            regs=(c.A, c.B, c.C, c.D, c.E, c.H, c.L, c.fZ, c.fN, c.fH, c.fC,
+                  c.SP, c.PC, c.IME, c.ei_pending, c.halted),
+            bank=(b.rom_bank, b.ram_bank, b.ram_on, b.divt),
+            vram=b.vram.copy(), wram=b.wram.copy(), oam=b.oam.copy(),
+            hram=b.hram.copy(), io=b.io.copy(), ie=b.ie, cart_ram=b.cart_ram.copy(),
+            ppu=(b.ppu.ly, b.ppu.lx, b.ppu.mode, b.ppu.win_line, b.ppu.stat_line,
+                 b.ppu.frame))
+    def restore(self, s):
+        c, b = self.cpu, self.bus
+        (c.A, c.B, c.C, c.D, c.E, c.H, c.L, c.fZ, c.fN, c.fH, c.fC,
+         c.SP, c.PC, c.IME, c.ei_pending, c.halted) = s["regs"]
+        b.rom_bank, b.ram_bank, b.ram_on, b.divt = s["bank"]
+        b.vram[:] = s["vram"]; b.wram[:] = s["wram"]; b.oam[:] = s["oam"]
+        b.hram[:] = s["hram"]; b.io[:] = s["io"]; b.ie = s["ie"]
+        b.cart_ram[:] = s["cart_ram"]
+        (b.ppu.ly, b.ppu.lx, b.ppu.mode, b.ppu.win_line, b.ppu.stat_line,
+         b.ppu.frame) = s["ppu"]

gb_sm83.py

@@ -0,0 +1,237 @@
+"""
+gb_sm83.py -- the COMPLETE SM83 (LR35902) core: all 256 base + 256 CB opcodes,
+stack/CALL/RET/RST, 16-bit arithmetic, EI/DI/RETI/HALT and the full interrupt
+sequence, at M-CYCLE bus granularity.
+
+Two properties carry the methodology through:
+  1. Every data transformation goes through the units API (gb_units.GoldenUnits or
+     gb_units.NeuralUnits) -- decode, ALU, rotates, BIT/RES/SET, DAA, all of it.
+     One step() implementation serves both, so golden-vs-neural comparison tests
+     the units, never two different orchestrators.
+  2. 16-bit arithmetic is COMPOSED from the verified 8-bit ADC/SBC by rippling the
+     carry lo->hi (INC/DEC rr, ADD HL,rr, ADD SP,e, LD HL,SP+e), exactly like the
+     hardware. No unit ever sees a domain it wasn't exhaustively verified on.
+
+M-cycle commit: the core never touches memory directly -- every access goes through
+bus.read/bus.write, and the bus ticks the rest of the machine (PPU dots, timer) one
+m-cycle per access plus explicit internal cycles. A write therefore lands on the dot
+stream at its true position INSIDE the instruction, closing the gap the per-dot brick
+documented.
+"""
+from gb_units import (NOP, LD_NN_SP, STOP, JR, JRcc, LDrrnn, ADDHLrr, LDmA, LDAm,
+                      INCrr, DECrr, INCr, DECr, LDrn, ROTA, DAAc, CPLc, SCFc, CCFc,
+                      LDrr_, HALTc, ALUr, ALUn, RETcc, LDHnA, ADDSPe, LDHAn, LDHLSPe,
+                      POPrr, RETc, RETIc, JPHL, LDSPHL, JPcc, LDCA, LDnnA, LDAC,
+                      LDAnn, JPnn, CBPREF, DIc, EIc, CALLcc, PUSHrr, CALLnn, RSTc, ILL)
+
+IF_VBLANK, IF_STAT, IF_TIMER, IF_SERIAL, IF_JOYPAD = 1, 2, 4, 8, 16
+ROTNAMES = ["RLC", "RRC", "RL", "RR", "SLA", "SRA", "SWAP", "SRL"]
+
+
+class SM83:
+    def __init__(self, bus, units):
+        self.bus = bus; self.u = units
+        # post-bootrom DMG state
+        self.A, self.B, self.C, self.D, self.E, self.H, self.L = 0x01, 0x00, 0x13, 0x00, 0xD8, 0x01, 0x4D
+        self.fZ, self.fN, self.fH, self.fC = 1, 0, 1, 1            # F = 0xB0
+        self.SP, self.PC = 0xFFFE, 0x0100
+        self.IME = False; self.ei_pending = False; self.halted = False
+        self.instr_count = 0
+
+    # ---- register plumbing (wiring, not logic) ----
+    def get_hl(self): return (self.H << 8) | self.L
+    def set_hl(self, v): self.H, self.L = (v >> 8) & 0xFF, v & 0xFF
+    def F(self): return (self.fZ << 7) | (self.fN << 6) | (self.fH << 5) | (self.fC << 4)
+    def setF(self, v):
+        self.fZ, self.fN, self.fH, self.fC = (v >> 7) & 1, (v >> 6) & 1, (v >> 5) & 1, (v >> 4) & 1
+
+    def get_r(self, i):
+        if i == 6: return self.bus.read(self.get_hl())
+        return (self.B, self.C, self.D, self.E, self.H, self.L, None, self.A)[i]
+    def set_r(self, i, v):
+        v &= 0xFF
+        if i == 0: self.B = v
+        elif i == 1: self.C = v
+        elif i == 2: self.D = v
+        elif i == 3: self.E = v
+        elif i == 4: self.H = v
+        elif i == 5: self.L = v
+        elif i == 6: self.bus.write(self.get_hl(), v)
+        else: self.A = v
+
+    def get_rr(self, p):      # BC DE HL SP
+        return [(self.B << 8) | self.C, (self.D << 8) | self.E, self.get_hl(), self.SP][p]
+    def set_rr(self, p, v):
+        v &= 0xFFFF
+        if p == 0: self.B, self.C = v >> 8, v & 0xFF
+        elif p == 1: self.D, self.E = v >> 8, v & 0xFF
+        elif p == 2: self.set_hl(v)
+        else: self.SP = v
+
+    def cond(self, cc):
+        return [self.fZ == 0, self.fZ == 1, self.fC == 0, self.fC == 1][cc]
+
+    # ---- bus helpers ----
+    def fetch(self):
+        v = self.bus.read(self.PC); self.PC = (self.PC + 1) & 0xFFFF; return v
+    def fetch16(self):
+        lo = self.fetch(); return lo | (self.fetch() << 8)
+    def push16(self, v):
+        self.bus.tick(1)
+        self.SP = (self.SP - 1) & 0xFFFF; self.bus.write(self.SP, (v >> 8) & 0xFF)
+        self.SP = (self.SP - 1) & 0xFFFF; self.bus.write(self.SP, v & 0xFF)
+    def pop16(self):
+        lo = self.bus.read(self.SP); self.SP = (self.SP + 1) & 0xFFFF
+        hi = self.bus.read(self.SP); self.SP = (self.SP + 1) & 0xFFFF
+        return lo | (hi << 8)
+
+    # ---- composed 16-bit arithmetic: verified 8-bit units, rippled carry ----
+    def add16_hl(self, rr):
+        lo, _, _, c = self.u.adc(self.L, rr & 0xFF, 0)
+        hi, _, h, c2 = self.u.adc(self.H, rr >> 8, c)
+        self.H, self.L = hi, lo
+        self.fN, self.fH, self.fC = 0, h, c2
+        self.bus.tick(1)
+    def inc16(self, v):
+        lo, _, _, c = self.u.adc(v & 0xFF, 1, 0)
+        hi, _, _, _ = self.u.adc(v >> 8, 0, c)
+        return (hi << 8) | lo
+    def dec16(self, v):
+        lo, _, _, c = self.u.sbc(v & 0xFF, 1, 0)
+        hi, _, _, _ = self.u.sbc(v >> 8, 0, c)
+        return (hi << 8) | lo
+    def sp_plus_e(self, e):
+        """SP + signed e. H/C from the LOW byte add (documented SM83 behavior)."""
+        lo, _, h, c = self.u.adc(self.SP & 0xFF, e, 0)
+        hi, _, _, _ = self.u.adc(self.SP >> 8, 0xFF if e & 0x80 else 0x00, c)
+        self.fZ, self.fN, self.fH, self.fC = 0, 0, h, c
+        return (hi << 8) | lo
+
+    def alu(self, kind, v):
+        """8-bit ALU group dispatch through verified units."""
+        if kind == 0: self.A, self.fZ, self.fH, self.fC = self.u.adc(self.A, v, 0); self.fN = 0
+        elif kind == 1: self.A, self.fZ, self.fH, self.fC = self.u.adc(self.A, v, self.fC); self.fN = 0
+        elif kind == 2: self.A, self.fZ, self.fH, self.fC = self.u.sbc(self.A, v, 0); self.fN = 1
+        elif kind == 3: self.A, self.fZ, self.fH, self.fC = self.u.sbc(self.A, v, self.fC); self.fN = 1
+        elif kind == 4: self.A, self.fZ = self.u.logic("AND", self.A, v); self.fN, self.fH, self.fC = 0, 1, 0
+        elif kind == 5: self.A, self.fZ = self.u.logic("XOR", self.A, v); self.fN, self.fH, self.fC = 0, 0, 0
+        elif kind == 6: self.A, self.fZ = self.u.logic("OR", self.A, v); self.fN, self.fH, self.fC = 0, 0, 0
+        else: _, self.fZ, self.fH, self.fC = self.u.sbc(self.A, v, 0); self.fN = 1   # CP
+
+    # ---- interrupts ----
+    def service_interrupt(self):
+        pend = self.bus.io_IE() & self.bus.io_IF() & 0x1F
+        if not pend:
+            return False
+        bit = (pend & -pend).bit_length() - 1
+        self.bus.clear_IF(1 << bit)
+        self.IME = False
+        self.bus.tick(2)
+        self.push16(self.PC)                      # push16 includes 1 internal tick
+        self.PC = 0x40 + 8 * bit
+        return True
+
+    # ---- one instruction (or interrupt entry / halt cycle) ----
+    def step(self):
+        if self.ei_pending:
+            self.ei_pending = False; self.IME = True
+        if self.halted:
+            if self.bus.io_IE() & self.bus.io_IF() & 0x1F:
+                self.halted = False
+            else:
+                self.bus.tick(1); return
+        if self.IME and self.service_interrupt():
+            return
+        op = self.fetch()
+        cls, y, z = self.u.decode(op)
+        self.instr_count += 1
+        u = self.u; p = y >> 1
+
+        if cls == NOP: pass
+        elif cls == LD_NN_SP:
+            a = self.fetch16(); self.bus.write(a, self.SP & 0xFF)
+            self.bus.write((a + 1) & 0xFFFF, self.SP >> 8)
+        elif cls == STOP: self.bus.tick(2)
+        elif cls == JR:
+            e = self.fetch(); e = e - 256 if e > 127 else e
+            self.PC = (self.PC + e) & 0xFFFF; self.bus.tick(1)
+        elif cls == JRcc:
+            e = self.fetch(); e = e - 256 if e > 127 else e
+            if self.cond(y - 4): self.PC = (self.PC + e) & 0xFFFF; self.bus.tick(1)
+        elif cls == LDrrnn: self.set_rr(p, self.fetch16())
+        elif cls == ADDHLrr: self.add16_hl(self.get_rr(p))
+        elif cls == LDmA or cls == LDAm:
+            addr = [(self.B << 8) | self.C, (self.D << 8) | self.E,
+                    self.get_hl(), self.get_hl()][p]
+            if cls == LDmA: self.bus.write(addr, self.A)
+            else: self.A = self.bus.read(addr)
+            if p == 2: self.set_hl(self.inc16(addr))
+            elif p == 3: self.set_hl(self.dec16(addr))
+        elif cls == INCrr: self.set_rr(p, self.inc16(self.get_rr(p))); self.bus.tick(1)
+        elif cls == DECrr: self.set_rr(p, self.dec16(self.get_rr(p))); self.bus.tick(1)
+        elif cls == INCr:
+            r, self.fZ, self.fH = u.inc(self.get_r(y)); self.set_r(y, r); self.fN = 0
+        elif cls == DECr:
+            r, self.fZ, self.fH = u.dec(self.get_r(y)); self.set_r(y, r); self.fN = 1
+        elif cls == LDrn: self.set_r(y, self.fetch())
+        elif cls == ROTA:
+            self.A, _, self.fC = u.rot(ROTNAMES[y], self.A, self.fC)
+            self.fZ = self.fN = self.fH = 0
+        elif cls == DAAc:
+            self.A, self.fZ, self.fC = u.daa(self.A, self.fN, self.fH, self.fC); self.fH = 0
+        elif cls == CPLc: self.A = u.cpl(self.A); self.fN = self.fH = 1
+        elif cls == SCFc: self.fN = self.fH = 0; self.fC = 1
+        elif cls == CCFc: self.fN = self.fH = 0; self.fC ^= 1
+        elif cls == HALTc: self.halted = True
+        elif cls == LDrr_: self.set_r(y, self.get_r(z))
+        elif cls == ALUr: self.alu(y, self.get_r(z))
+        elif cls == ALUn: self.alu(y, self.fetch())
+        elif cls == RETcc:
+            self.bus.tick(1)
+            if self.cond(y): self.PC = self.pop16(); self.bus.tick(1)
+        elif cls == LDHnA: self.bus.write(0xFF00 | self.fetch(), self.A)
+        elif cls == LDHAn: self.A = self.bus.read(0xFF00 | self.fetch())
+        elif cls == ADDSPe: self.SP = self.sp_plus_e(self.fetch()); self.bus.tick(2)
+        elif cls == LDHLSPe: self.set_hl(self.sp_plus_e(self.fetch())); self.bus.tick(1)
+        elif cls == POPrr:
+            v = self.pop16()
+            if p == 3: self.A = v >> 8; self.setF(v & 0xFF)     # AF
+            else: self.set_rr(p, v)
+        elif cls == RETc: self.PC = self.pop16(); self.bus.tick(1)
+        elif cls == RETIc: self.PC = self.pop16(); self.bus.tick(1); self.IME = True
+        elif cls == JPHL: self.PC = self.get_hl()
+        elif cls == LDSPHL: self.SP = self.get_hl(); self.bus.tick(1)
+        elif cls == JPcc:
+            a = self.fetch16()
+            if self.cond(y): self.PC = a; self.bus.tick(1)
+        elif cls == LDCA: self.bus.write(0xFF00 | self.C, self.A)
+        elif cls == LDAC: self.A = self.bus.read(0xFF00 | self.C)
+        elif cls == LDnnA: self.bus.write(self.fetch16(), self.A)
+        elif cls == LDAnn: self.A = self.bus.read(self.fetch16())
+        elif cls == JPnn: self.PC = self.fetch16(); self.bus.tick(1)
+        elif cls == CBPREF: self.step_cb()
+        elif cls == DIc: self.IME = False; self.ei_pending = False
+        elif cls == EIc: self.ei_pending = True
+        elif cls == CALLcc:
+            a = self.fetch16()
+            if self.cond(y): self.push16(self.PC); self.PC = a
+        elif cls == PUSHrr:
+            v = ((self.A << 8) | self.F()) if p == 3 else self.get_rr(p)
+            self.push16(v)
+        elif cls == CALLnn:
+            a = self.fetch16(); self.push16(self.PC); self.PC = a
+        elif cls == RSTc: self.push16(self.PC); self.PC = y * 8
+        else:
+            raise NotImplementedError(f"illegal opcode {op:#04x} at {self.PC - 1:#06x}")
+
+    def step_cb(self):
+        kind, sub, tgt = self.u.cbdecode(self.fetch())
+        u = self.u
+        if kind == 0:                                  # rotates/shifts
+            res, z, c = u.rot(ROTNAMES[sub], self.get_r(tgt), self.fC)
+            self.set_r(tgt, res)
+            self.fZ, self.fN, self.fH, self.fC = z, 0, 0, c
+        elif kind == 1:                                # BIT
+            self.fZ = u.bit(self.get_r(tgt), sub); self.fN, self.fH = 0, 1
+        else:                                          # RES / SET
+            self.set_r(tgt, u.setres(kind == 3, self.get_r(tgt), sub))