m68000-python 0.1.0__py3-none-any.whl

m68000_python/console.py

@@ -0,0 +1,254 @@
+"""A line-command debugger over :class:`~m68000_python.debug.DebugSession`.
+
+``CommandDebugger(session).execute("step 3")`` returns the lines a terminal
+would print; ``interact(stdin, stdout)`` is the prompt loop that
+``python -m m68000_python`` runs.  Numbers are decimal, or hexadecimal with a
+``$`` or ``0x`` prefix, the rule of every console in this family.
+"""
+
+from dataclasses import dataclass
+from typing import TextIO
+
+from m68000_python.debug import BoundaryKind, DebugSession, StepRecord
+from m68000_python.disasm import disassemble
+
+HELP = """\
+registers | r            show the registers
+step [n] | s [n]         run n boundaries (default 1), showing each
+run [n] | c [n]          run until a breakpoint, watchpoint, STOP or n steps (default 1,000,000)
+break ADDR | b ADDR      stop before the instruction at ADDR
+delete ADDR              remove a breakpoint
+watch ADDR [r|w|rw]      stop after a step that touches ADDR
+unwatch ADDR             remove a watchpoint
+disassemble [ADDR] [N]   N instructions from ADDR (default: PC, 8) | d
+memory ADDR [N]          N bytes from ADDR (default 64) | m
+set REG VALUE            set d0-d7, a0-a7, usp, ssp, sr or pc
+ipl LEVEL                set the interrupt level (0-7)
+history [N]              the last N boundaries (default 10)
+help                     this text
+quit | q                 leave"""
+
+
+class CommandError(Exception):
+    """A command that could not be run; the message says why."""
+
+
+@dataclass(frozen=True, slots=True)
+class CommandResult:
+    """What one command printed, and whether it asked to leave."""
+
+    lines: tuple[str, ...] = ()
+    quit: bool = False
+
+    def __post_init__(self) -> None:
+        if type(self.lines) is not tuple or not all(type(line) is str for line in self.lines):
+            raise ValueError("lines must be a tuple of strings")
+        if type(self.quit) is not bool:
+            raise ValueError("quit must be a bool")
+
+
+def parse_number(text: str, name: str = "number", *, maximum: int = 0xFFFFFFFF) -> int:
+    """Parse a decimal number, or a hexadecimal one written ``$1F`` or ``0x1F``."""
+    body = text.strip()
+    try:
+        if body.startswith("$"):
+            value = int(body[1:], 16)
+        elif body[:2].lower() == "0x":
+            value = int(body[2:], 16)
+        else:
+            value = int(body, 10)
+    except ValueError:
+        raise CommandError(f"{name}: {text!r} is not a number") from None
+    if not 0 <= value <= maximum:
+        raise CommandError(f"{name}: {text} is out of range 0..{maximum:#x}")
+    return value
+
+
+class CommandDebugger:
+    """Execute debugger commands against a session."""
+
+    def __init__(self, session: DebugSession) -> None:
+        self.session = session
+
+    # -- views ---------------------------------------------------------------
+
+    def registers(self) -> list[str]:
+        state = self.session.target.capture_state()
+        d = " ".join(f"D{i}={value:08X}" for i, value in enumerate(state.d))
+        a = " ".join(f"A{i}={value:08X}" for i, value in enumerate((*state.a, state.a7)))
+        sr = state.sr
+        flags = "".join(
+            c if sr & bit else "."
+            for c, bit in zip("TSXNZVC", (0x8000, 0x2000, 16, 8, 4, 2, 1), strict=True)
+        )
+        status = f"PC={state.pc & 0xFFFFFF:06X} SR={sr:04X} {flags} I={(sr >> 8) & 7}"
+        extra = f"USP={state.usp:08X} SSP={state.ssp:08X} IPL={state.ipl} clock={state.clock}"
+        if state.stopped:
+            extra += " STOPPED"
+        if state.halted:
+            extra += " HALTED"
+        return [d[:47], d[48:], a[:47], a[48:], status, extra]
+
+    def _result(self, lines: list[str]) -> CommandResult:
+        return CommandResult(tuple(lines))
+
+    def _describe(self, record: StepRecord) -> str:
+        if record.kind is BoundaryKind.INSTRUCTION:
+            text = (
+                record.instruction.text
+                if record.instruction
+                else f"(opcode {record.before.ir:04X})"
+            )
+            return f"{record.before.pc & 0xFFFFFF:06X}  {text:40} {record.cycles:4} clocks"
+        return f"{record.before.pc & 0xFFFFFF:06X}  <{record.kind.value}> {record.cycles} clocks"
+
+    def disassemble(self, address: int | None, count: int) -> list[str]:
+        peek = self.session.peek_word
+        if peek is None:
+            raise CommandError("the session has no peek_word: nothing to disassemble from")
+        if address is None:
+            address = self.session.target.capture_state().pc & 0xFFFFFF
+        lines = []
+        for _ in range(count):
+            instruction = disassemble(peek, address)
+            words = " ".join(f"{word:04X}" for word in instruction.words)
+            lines.append(f"{address:06X}  {words:24} {instruction.text}")
+            address = (address + instruction.length) & 0xFFFFFF
+        return lines
+
+    def memory(self, address: int, count: int) -> list[str]:
+        peek = self.session.peek_word
+        if peek is None:
+            raise CommandError("the session has no peek_word: no memory to show")
+        lines = []
+        for row in range(address & ~1, address + count, 16):
+            words = [peek((row + i) & 0xFFFFFF) for i in range(0, 16, 2)]
+            data = b"".join(word.to_bytes(2, "big") for word in words)
+            text = "".join(chr(b) if 32 <= b < 127 else "." for b in data)
+            lines.append(f"{row & 0xFFFFFF:06X}  {data.hex(' ')}  {text}")
+        return lines
+
+    # -- the command language --------------------------------------------------
+
+    def execute(self, line: str) -> CommandResult:
+        words = line.split()
+        if not words:
+            return CommandResult()
+        command, arguments = words[0].lower(), words[1:]
+        session = self.session
+        if command in ("quit", "q", "exit"):
+            return CommandResult(quit=True)
+        if command == "help":
+            return self._result(HELP.splitlines())
+        if command in ("registers", "r", "regs"):
+            return self._result(self.registers())
+        if command in ("step", "s"):
+            count = parse_number(arguments[0], "count") if arguments else 1
+            if count == 0:
+                raise CommandError("count must be positive")
+            return self._result([self._describe(session.step()) for _ in range(count)])
+        if command in ("run", "c", "continue"):
+            count = parse_number(arguments[0], "count") if arguments else 1_000_000
+            if count == 0:
+                raise CommandError("count must be positive")
+            result = session.run(max_steps=count)
+            lines = [
+                f"{result.reason.value} after {result.steps:,} steps, {result.cycles:,} clocks"
+            ]
+            lines += [
+                f"  {kind} {address:06X} = {value:X}" for kind, address, value, _ in result.hits
+            ]
+            return self._result(lines + self.registers())
+        if command in ("break", "b"):
+            session.add_breakpoint(
+                parse_number(self._one(arguments, "address"), "address", maximum=0xFFFFFF)
+            )
+            return self._result(
+                [f"breakpoints: {', '.join(f'{a:06X}' for a in sorted(session.breakpoints))}"]
+            )
+        if command == "delete":
+            session.remove_breakpoint(
+                parse_number(self._one(arguments, "address"), "address", maximum=0xFFFFFF)
+            )
+            return CommandResult()
+        if command == "watch":
+            if not arguments:
+                raise CommandError("watch needs an address")
+            kind = arguments[1] if len(arguments) > 1 else "rw"
+            try:
+                session.add_watchpoint(
+                    parse_number(arguments[0], "address", maximum=0xFFFFFF), kind
+                )
+            except ValueError as exc:
+                raise CommandError(str(exc)) from None
+            return CommandResult()
+        if command == "unwatch":
+            session.remove_watchpoint(
+                parse_number(self._one(arguments, "address"), "address", maximum=0xFFFFFF)
+            )
+            return CommandResult()
+        if command in ("disassemble", "d", "dis"):
+            address = parse_number(arguments[0], "address", maximum=0xFFFFFF) if arguments else None
+            count = parse_number(arguments[1], "count") if len(arguments) > 1 else 8
+            return self._result(self.disassemble(address, count))
+        if command in ("memory", "m"):
+            address = parse_number(self._one(arguments[:1], "address"), "address", maximum=0xFFFFFF)
+            count = parse_number(arguments[1], "count", maximum=4096) if len(arguments) > 1 else 64
+            return self._result(self.memory(address, count))
+        if command == "set":
+            if len(arguments) != 2:
+                raise CommandError("set needs a register and a value")
+            self._set(arguments[0].lower(), parse_number(arguments[1], arguments[0]))
+            return self._result(self.registers())
+        if command == "ipl":
+            session.cpu.set_ipl(parse_number(self._one(arguments, "level"), "level", maximum=7))
+            return CommandResult()
+        if command == "history":
+            count = parse_number(arguments[0], "count") if arguments else 10
+            records = list(session.iter_history())[-count:] if count else []
+            return self._result([self._describe(record) for record in records])
+        raise CommandError(f"unknown command {command!r} (try help)")
+
+    @staticmethod
+    def _one(arguments: list[str], name: str) -> str:
+        if len(arguments) != 1:
+            raise CommandError(f"expected one {name}")
+        return arguments[0]
+
+    def _set(self, name: str, value: int) -> None:
+        cpu = self.session.cpu
+        if len(name) == 2 and name[0] in "da" and name[1] in "01234567":
+            cpu.R[(0 if name[0] == "d" else 8) + int(name[1])] = value
+        elif name == "usp":
+            cpu.usp = value
+        elif name == "ssp":
+            cpu.ssp = value
+        elif name == "sr":
+            if value > 0xFFFF:
+                raise CommandError("sr is 16 bits")
+            cpu.set_sr(value)
+        elif name == "pc":
+            cpu.set_pc(value)
+        else:
+            raise CommandError(f"no register {name!r}")
+
+    def interact(self, stdin: TextIO, stdout: TextIO) -> None:
+        """Read commands from ``stdin`` until ``quit`` or end of input."""
+        while True:
+            stdout.write("m68000> ")
+            stdout.flush()
+            line = stdin.readline()
+            if not line:
+                return
+            try:
+                result = self.execute(line)
+            except CommandError as exc:
+                stdout.write(f"error: {exc}\n")
+                continue
+            for text in result.lines:
+                stdout.write(text + "\n")
+            if result.quit:
+                return
+
+
+__all__ = ["CommandDebugger", "CommandError", "CommandResult", "parse_number"]

m68000_python/cpu.py

@@ -0,0 +1,373 @@
+"""The public MC68000 CPU class.
+
+The host owns memory and every device.  It passes four callables in --
+``read_byte(address)``, ``read_word(address)``, ``write_byte(address, value)``
+and ``write_word(address, value)`` over a 24-bit address space -- calls
+:meth:`M68000CPU.step`, and adds the returned clock count to its own clock.
+Interrupts are a level the host sets with :meth:`M68000CPU.set_ipl`; the
+optional ``acknowledge(level)`` callable answers the interrupt-acknowledge
+cycle with a vector number, :data:`AUTOVECTOR` or :data:`SPURIOUS`.  See
+README.md, "The embedding contract".
+"""
+
+from collections.abc import Callable
+
+from m68000_python._alu import ALUMixin
+from m68000_python._bcd import BCDMixin
+from m68000_python._bits import BitsMixin
+from m68000_python._control import ControlMixin
+from m68000_python._core import (
+    AUTOVECTOR,
+    IPL_MASK,
+    MASK24,
+    SPURIOUS,
+    VECTOR_AUTOVECTOR_BASE,
+    VECTOR_SPURIOUS,
+    VECTOR_TRACE,
+    VECTOR_UNINITIALIZED,
+    Acknowledge,
+    CoreMixin,
+    GroupZero,
+    ReadFunction,
+    S,
+    T,
+    WriteFunction,
+)
+from m68000_python._dispatch import Handler, build_table
+from m68000_python._ea import EAMixin
+from m68000_python._flags import FlagsMixin
+from m68000_python._loads import LoadsMixin
+from m68000_python._shifts import ShiftsMixin
+from m68000_python._system import SystemMixin
+from m68000_python.state import CPUState
+
+
+class M68000CPU(
+    ALUMixin,
+    BCDMixin,
+    BitsMixin,
+    ControlMixin,
+    LoadsMixin,
+    ShiftsMixin,
+    SystemMixin,
+    EAMixin,
+    FlagsMixin,
+    CoreMixin,
+):
+    """A Motorola MC68000 instruction core (also the MC68HC000 and MC68EC000).
+
+    Registers: ``R`` is a list of sixteen 32-bit values, D0-D7 then A0-A7,
+    where A7 is the stack pointer of the current mode; ``usp`` and ``ssp``
+    name the two stack pointers whatever the mode.  ``SR`` is the 16-bit
+    status register.  ``PC`` is the address of the next instruction; the
+    prefetch queue behind it is ``ir`` (that instruction's first word) and
+    ``irc`` (the word after it), read from memory ahead of execution as the
+    chip does (docs/start-here.md, "Prefetch").
+
+    Keyword options, each costing nothing unless used:
+
+    * ``acknowledge(level)``: the interrupt-acknowledge cycle.  Return a
+      vector number (0-255), :data:`AUTOVECTOR`, or :data:`SPURIOUS`.  Left
+      out, every interrupt is autovectored, as on most arcade boards.
+    * ``function_codes=True``: every bus call gets ``fc=`` (UM Table 3-2):
+      1/2 user data/program, 5/6 supervisor data/program, 7 CPU space.
+    * ``tas_write(address, value)``: the write half of TAS's read-modify-write
+      cycle, for a bus that treats it differently (the Genesis drops it;
+      docs/undocumented-behavior.md).  Defaults to ``write_byte``.
+    * ``address_error(address, write, fc)``: told about the access an address
+      error aborted, which never reaches the bus (UM 6.3.10).
+    * ``reset_devices()``: called when the RESET instruction pulses the RESET
+      line (PRM 6-83); the processor itself is not reset.
+
+    A host raises :class:`BusError` from any bus callable to assert BERR.
+    """
+
+    _table: list[Handler]
+
+    def __init__(
+        self,
+        read_byte: ReadFunction,
+        read_word: ReadFunction,
+        write_byte: WriteFunction,
+        write_word: WriteFunction,
+        *,
+        acknowledge: Acknowledge | None = None,
+        function_codes: bool = False,
+        tas_write: WriteFunction | None = None,
+        address_error: Callable[[int, bool, int], None] | None = None,
+        reset_devices: Callable[[], None] | None = None,
+    ) -> None:
+        for name, value in (("acknowledge", acknowledge), ("tas_write", tas_write),
+                            ("address_error", address_error),
+                            ("reset_devices", reset_devices)):  # fmt: skip
+            if value is not None and not callable(value):
+                raise TypeError(f"{name} must be callable or None")
+        if type(function_codes) is not bool:
+            raise TypeError("function_codes must be a bool")
+        self._init_core(
+            read_byte,
+            read_word,
+            write_byte,
+            write_word,
+            acknowledge,
+            function_codes,
+            tas_write,
+            address_error,
+            reset_devices,
+        )
+        cls = type(self)
+        if "_table" not in cls.__dict__:
+            cls._table = build_table(cls)
+
+    # -- state capture and restore (docs/cpu-state.md) --------------------------
+
+    def capture_state(self) -> CPUState:
+        """Return an immutable snapshot of all CPU-owned state; no host reads."""
+        R = self.R
+        return CPUState(
+            d=tuple(R[0:8]),
+            a=tuple(R[8:15]),
+            usp=self.usp,
+            ssp=self.ssp,
+            sr=self.SR,
+            pc=(self._pc - 4) & 0xFFFFFFFF,
+            ir=self.ir,
+            irc=self.irc,
+            ipl=self.ipl,
+            nmi_edge=self._nmi_edge,
+            trace_pending=self._trace_pending,
+            stopped=self.stopped,
+            halted=self.halted,
+            clock=self.clock,
+        )
+
+    def restore_state(self, state: CPUState) -> None:
+        """Restore a captured state without touching the host's memory or devices."""
+        if type(state) is not CPUState:
+            raise TypeError("state must be a CPUState")
+        R = self.R
+        R[0:8] = state.d
+        R[8:15] = state.a
+        self.SR = state.sr
+        if state.sr & S:
+            R[15], self._other_sp = state.ssp, state.usp
+        else:
+            R[15], self._other_sp = state.usp, state.ssp
+        self._pc = (state.pc + 4) & 0xFFFFFFFF
+        self.ir = state.ir
+        self.irc = state.irc
+        self.ipl = state.ipl
+        self._nmi_edge = state.nmi_edge
+        self._trace_pending = state.trace_pending
+        self.stopped = state.stopped
+        self.halted = state.halted
+        self.clock = state.clock
+
+    # -- the program counter as a programmer sees it --------------------------
+
+    @property
+    def PC(self) -> int:
+        """The address of the next instruction (the queue reads 4 bytes ahead)."""
+        return (self._pc - 4) & 0xFFFFFFFF
+
+    def set_pc(self, address: int) -> None:
+        """Start executing at ``address``: refill the prefetch queue from it.
+
+        Two program reads, as a jump does; no clocks are counted.  The host
+        uses this instead of a reset when it loads a program itself.  An odd
+        address is refused: instructions live at even addresses (UM 6.3.10),
+        and a jump to an odd one is an address error, not a start.
+        """
+        if address & 1:
+            raise ValueError("an instruction address must be even")
+        address &= 0xFFFFFFFF
+        self.ir = self._read_program(address & MASK24)
+        self.irc = self._read_program((address + 2) & MASK24)
+        self._pc = (address + 4) & 0xFFFFFFFF
+        self.stopped = False
+
+    # -- external signals -----------------------------------------------------
+
+    def set_sr(self, value: int) -> None:
+        """Write SR as an instruction would: A7 follows S to the other stack pointer.
+
+        Assigning ``SR`` directly changes the bits and nothing else, which is
+        what a state restore wants and a host usually does not.
+        """
+        self._set_sr(value)
+
+    def _next_pc(self) -> int:
+        """The address execution resumes at: what an interrupt or trace stacks.
+
+        At a boundary the queue has read 4 bytes ahead.  STOP leaves the queue
+        as it was (its immediate still in IRC, corpus T3), so a stopped CPU
+        resumes at the prefetch address itself: the instruction after STOP.
+        """
+        return self._pc if self.stopped else (self._pc - 4) & 0xFFFFFFFF
+
+    def set_ipl(self, level: int) -> None:
+        """Set the interrupt level on IPL2-IPL0 (0 = none, 7 = non-maskable).
+
+        Level 7 is edge-triggered: a change to 7 from below is taken once
+        even with the mask at 7 (UM 6.3.2).
+        """
+        if not 0 <= level <= 7:
+            raise ValueError("IPL level must be 0-7")
+        if level == 7 and self.ipl != 7:
+            self._nmi_edge = True
+        self.ipl = level
+
+    def reset(self) -> int:
+        """The reset exception (UM 6.3.1): S set, T clear, mask 7, SSP and PC from 0 and 4.
+
+        Nothing is pushed.  A fault while fetching the vectors or the first
+        instruction (an odd initial PC) halts the processor as a double bus
+        fault (UM 5.4.4).  Returns the clocks spent, 40 as UM Table 8-14
+        prints: 14 internal, the four vector reads, and the two-read refill
+        of the queue with its 2 idle clocks, as every other exception entry
+        refills it.  The 14 are Nuked-MD's: its gate-level 68000 reads the
+        SSP vector 14 clocks after RESET is released (docs/claims.md).
+        """
+        self._cycles = 0
+        self.halted = False
+        self.stopped = False
+        self._trace_pending = False
+        self._nmi_edge = False
+        self._set_sr((self.SR | S | IPL_MASK) & ~T)
+        self._cycles += 14
+        try:
+            self.R[15] = (self._read_program_word(0) << 16) | self._read_program_word(2)
+            pc = (self._read_program_word(4) << 16) | self._read_program_word(6)
+            self._fault_pc = pc
+            self._jump_idle(pc)
+        except GroupZero:
+            # An address or bus error during the reset sequence (an odd initial
+            # PC, BERR on a vector) is a double bus fault: halt (UM 5.4.4).
+            self.halted = True
+        self.clock += self._cycles
+        return self._cycles
+
+    # -- execution ------------------------------------------------------------
+
+    @property
+    def step_clocks(self) -> int:
+        """Clocks the step in progress has spent so far (read-only).
+
+        Read from inside a bus callback, it counts the access being made as
+        complete: that access occupies clocks ``step_clocks - 4`` to
+        ``step_clocks`` of the step, so ``clock + step_clocks - 4`` is when it
+        began on the host's running count.  A host that stalls the CPU (a
+        wait state, a device holding the bus) uses it to place the stall at
+        the right clock; the core itself does not model wait states, so the
+        host adds its own stall clocks to the ``step()`` total.  Inside an
+        ``acknowledge`` callback the acknowledge cycle's own four clocks are
+        not yet counted.  Between steps it is the last ``step()``'s (or
+        ``reset()``'s) total.
+        """
+        return self._cycles
+
+    def step(self) -> int:
+        """Run one instruction or one exception entry; return its clock count.
+
+        At an instruction boundary, in this order: a halted CPU idles; a
+        trace exception left by the previous instruction is taken (UM 6.3.8:
+        trace outranks interrupts); an interrupt above the mask, or a level
+        7 edge, is taken (UM 6.3.2); a stopped CPU idles; otherwise the
+        instruction in IR runs.
+        """
+        if self.halted:
+            self._cycles = 4
+            self.clock += 4
+            return 4
+        self._cycles = 0
+        try:
+            level = self.ipl
+            if self._trace_pending:
+                self._trace_pending = False
+                self._opcode = self.ir
+                self._exception(VECTOR_TRACE, self._next_pc())
+                self.stopped = False
+            elif level and (level > (self.SR >> 8) & 7 or (level == 7 and self._nmi_edge)):
+                self._interrupt(level)
+            elif self.stopped:
+                self._cycles = 4
+            else:
+                opcode = self._opcode = self.ir
+                self._fault_pc = self._pc - 2
+                traced = self.SR & T
+                if traced:
+                    self._untraced = False
+                self._table[opcode](self, opcode)
+                if traced and not self._untraced:
+                    # Trace follows an instruction that completed, as its own
+                    # boundary: the next step takes it (UM 6.3.8).  An illegal
+                    # or privileged instruction was never executed and is not
+                    # traced (_system._not_executed).  The corpus's final
+                    # states are captured before the trace (its issue #2).
+                    self._trace_pending = True
+        except GroupZero as fault:
+            self._group_zero(fault)
+        self.clock += self._cycles
+        return self._cycles
+
+    def _interrupt(self, level: int) -> None:
+        """Interrupt entry (UM 6.3.2-6.3.4): acknowledge, stack, vector.
+
+        The mask rises to the accepted level; the acknowledge cycle names the
+        vector, or asks for the autovector (24 + level), or reports spurious
+        (vector 24).  A vector number outside 0-255 is an uninitialized
+        vector (15).
+        """
+        if level == 7:
+            self._nmi_edge = False
+        self._opcode = self.ir
+        pc = self._next_pc()  # the instruction the interrupt came before
+        self.stopped = False
+        # Three internal steps: SR copied, S set and T cleared, the mask
+        # raised to the level being taken (UM 6.3.2; MAME 0.285's order).
+        self._cycles += 6
+        saved = self.SR
+        self._set_sr(((saved | S) & ~T & ~IPL_MASK) | (level << 8))
+        self._processing_exception = True
+        sp = self.R[15]
+        self._write_word(sp - 2, pc)
+        # The acknowledge cycle comes between the first push and the rest.
+        answer = AUTOVECTOR if self._acknowledge is None else self._acknowledge(level)
+        self._cycles += 4
+        if answer == AUTOVECTOR:
+            vector = VECTOR_AUTOVECTOR_BASE + level
+            # VPA: the cycle waits for the E clock (CLK/10) as the manual
+            # describes (UM 5.1.4, 6.3.2); the phase is the host's running
+            # clock count, ``clock``, as MAME 0.285's vpa_sync takes it.
+            self._cycles += self._e_clock_wait()
+        elif answer == SPURIOUS:
+            vector = VECTOR_SPURIOUS
+        elif 0 <= answer <= 255:
+            vector = answer
+        else:
+            vector = VECTOR_UNINITIALIZED
+        self._cycles += 4
+        sp = (sp - 6) & 0xFFFFFFFF
+        self.R[15] = sp
+        self._write_word(sp, saved)
+        self._write_word(sp + 2, pc >> 16)
+        target = self._read_vector(vector)
+        self._jump_idle(target)
+        self._processing_exception = False
+
+    def _e_clock_wait(self) -> int:
+        """Clocks an autovectored acknowledge waits for the E clock.
+
+        MAME 0.285 (m68000.cpp, ``vpa_sync`` and ``vpa_after``): with t the
+        clock count at the start of the cycle, the transfer is aligned to the
+        next E-clock period boundary, one period later when fewer than 3
+        clocks remain, and one clock is added after it.  The MAME lockstep
+        on System 16B agrees at every phase (docs/validation.md, rung 6).
+        """
+        now = self.clock + self._cycles - 4
+        phase = now % 10
+        self.last_acknowledge_phase = phase
+        return ((10 - phase) if phase < 7 else (20 - phase)) + 1
+
+
+__all__ = ["AUTOVECTOR", "M68000CPU", "SPURIOUS"]