m68000-python 0.1.0__py3-none-any.whl

m68000_python/_bcd.py

@@ -0,0 +1,137 @@
+"""Binary-coded decimal: ABCD, SBCD, NBCD (PRM Table 3-8).
+
+PRM Table 3-18 gives X and C (the decimal carry or borrow) and a sticky Z,
+and calls N and V undefined.  They are not undefined on silicon, and the
+rule below is the one flamewing's 68k-bcd-verifier checks exhaustively on a
+Model 1 and a Model 3 Sega Genesis (T1; docs/undocumented-behavior.md): the
+byte is first added or subtracted in binary, then corrected by 6 in each
+nibble that produced a binary carry (borrow) or, for an add, a digit above 9;
+N is bit 7 of the corrected byte, and V is set when the correction flipped
+bit 7 -- from 0 to 1 for an add, from 1 to 0 for a subtract.  C and X are set
+by a carry (borrow) out of either the binary step or the correction.
+
+The three instructions' bus sequences are the microcode's (SST ABCD, SBCD, NBCD; T3): the
+register forms prefetch and then spend two internal clocks; the memory forms
+read, prefetch, then write.
+"""
+
+from m68000_python._core import C, N, V, X, Z
+from m68000_python._ea import DN, EA_KIND
+
+
+def decimal_add(destination: int, source: int, extend: int) -> tuple[int, int]:
+    """ABCD's result byte and X N Z V C bits (Z to be ANDed in: sticky)."""
+    binary = destination + source + extend
+    low_carry = (destination & 0xF) + (source & 0xF) + extend > 0xF
+    uncorrected = binary & 0xFF
+    correction = 0
+    if low_carry or (uncorrected & 0xF) > 9:
+        correction = 0x06
+    if binary > 0xFF or uncorrected > 0x99:
+        correction |= 0x60
+    corrected = uncorrected + correction
+    result = corrected & 0xFF
+    flags = Z if result == 0 else 0
+    if binary > 0xFF or corrected > 0xFF:
+        flags |= X | C
+    if result & 0x80:
+        flags |= N
+    if result & 0x80 and not uncorrected & 0x80:
+        flags |= V  # the correction carried into bit 7 (T1, flamewing)
+    return result, flags
+
+
+def decimal_subtract(destination: int, source: int, extend: int) -> tuple[int, int]:
+    """SBCD's (and NBCD's, with destination 0) result byte and X N Z V C bits."""
+    binary = destination - source - extend
+    low_borrow = (destination & 0xF) - (source & 0xF) - extend < 0
+    uncorrected = binary & 0xFF
+    correction = 0
+    if low_borrow:
+        correction = 0x06
+    if binary < 0:
+        correction |= 0x60
+    corrected = uncorrected - correction
+    result = corrected & 0xFF
+    flags = Z if result == 0 else 0
+    if binary < 0 or corrected < 0:
+        flags |= X | C
+    if result & 0x80:
+        flags |= N
+    if uncorrected & 0x80 and not result & 0x80:
+        flags |= V  # the correction borrowed out of bit 7 (T1, flamewing)
+    return result, flags
+
+
+class BCDMixin:
+    """Private BCD implementation."""
+
+    def _set_bcd_flags(self, flags: int) -> None:
+        # X N V C replaced; Z only ever cleared (PRM Table 3-18, sticky Z).
+        sr = self.SR
+        self.SR = (sr & 0xFF00) | (flags & (X | N | V | C)) | (sr & flags & Z)
+
+    def _bcd_pair(self, opcode: int, operation) -> None:
+        """The two forms shared by ABCD and SBCD: Dy,Dx and -(Ay),-(Ax)."""
+        rx = (opcode >> 9) & 7
+        ry = opcode & 7
+        extend = (self.SR >> 4) & 1
+        R = self.R
+        if not opcode & 8:
+            result, flags = operation(R[rx] & 0xFF, R[ry] & 0xFF, extend)
+            self._set_bcd_flags(flags)
+            self._prefetch()
+            self._cycles += 2
+            R[rx] = (R[rx] & 0xFFFFFF00) | result
+            return
+        self._cycles += 2
+        self._commit_pc()
+        source_address = (R[8 + ry] - self._step_size(ry, 1)) & 0xFFFFFFFF
+        R[8 + ry] = source_address
+        source = self._read_byte(source_address)
+        destination_address = (R[8 + rx] - self._step_size(rx, 1)) & 0xFFFFFFFF
+        R[8 + rx] = destination_address
+        destination = self._read_byte(destination_address)
+        result, flags = operation(destination, source, extend)
+        self._set_bcd_flags(flags)
+        self._prefetch()
+        self._write_byte(destination_address, result)
+
+    def _op_abcd(self, opcode: int) -> None:
+        """ABCD -- destination <- destination + source + X, decimal (PRM 4-3; UM Table 8-11).
+
+        N and V, undefined in PRM: flamewing's hardware-captured tables (T1,
+        tests/test_bcd.py).  Bus order, the 2 idle clocks of the register form and
+        the PC an address error stacks: SST ABCD.
+        """
+        self._bcd_pair(opcode, decimal_add)
+
+    def _op_sbcd(self, opcode: int) -> None:
+        """SBCD -- destination <- destination - source - X, decimal (PRM 4-176; UM Table 8-11).
+
+        N and V: flamewing's tables (T1).  Bus order and the PC an address error
+        stacks: SST SBCD.
+        """
+        self._bcd_pair(opcode, decimal_subtract)
+
+    def _op_nbcd(self, opcode: int) -> None:
+        """NBCD -- destination <- 0 - destination - X, decimal (PRM 4-142; UM Table 8-6).
+
+        N and V: flamewing's tables (T1).  Bus order and the PC an address error
+        stacks: SST NBCD.
+        """
+        kind = EA_KIND[opcode & 0x3F]
+        register = opcode & 7
+        extend = (self.SR >> 4) & 1
+        if kind == DN:
+            result, flags = decimal_subtract(0, self.R[register] & 0xFF, extend)
+            self._set_bcd_flags(flags)
+            self._prefetch()
+            self._cycles += 2
+            self.R[register] = (self.R[register] & 0xFFFFFF00) | result
+            return
+        address = self._ea_address(kind, register, 1)
+        result, flags = decimal_subtract(0, self._read_byte(address), extend)
+        self._set_bcd_flags(flags)
+        self._prefetch()
+        self._write_byte(address, result)

m68000_python/_bits.py

@@ -0,0 +1,100 @@
+"""Bit manipulation: BTST, BCHG, BCLR, BSET (PRM Table 3-6; UM Table 8-8).
+
+The bit number comes from Dn (dynamic) or from the word after the opcode
+(static).  On a data register the operation is on the whole long and the
+number is taken mod 32; on memory it is on a byte, mod 8 (PRM 4, BTST).  Z
+is set if the tested bit was 0; nothing else changes.  On a register the
+changing forms cost 2 clocks more for bits 16-31 (UM Table 8-8 note), and
+BCLR 2 more again (SST BCLR, T3).
+"""
+
+from m68000_python._core import Z
+from m68000_python._ea import DN, EA_KIND, IMM
+
+# The operations, by bits 7-6 of the opcode: test, change, clear, set.
+TEST, CHANGE, CLEAR, SET = range(4)
+
+
+class BitsMixin:
+    """Private bit-manipulation implementation."""
+
+    def _bit_operation(self, opcode: int, operation: int) -> None:
+        if opcode & 0x0100:
+            number = self.R[(opcode >> 9) & 7]
+        else:
+            self._commit_pc()
+            number = self._extension() & 0xFF
+        kind = EA_KIND[opcode & 0x3F]
+        register = opcode & 7
+        if kind == DN:
+            number &= 31
+            value = self.R[register]
+            self._set_z(value, number)
+            self._prefetch()
+            if operation == TEST:
+                self._cycles += 2
+                return
+            self._cycles += 4 if operation == CLEAR else 2
+            if number >= 16:
+                self._cycles += 2
+            self.R[register] = self._apply_bit(value, number, operation)
+            return
+        number &= 7
+        if kind == IMM:  # BTST Dn,#data: the operand is the byte after the opcode
+            value = self._extension() & 0xFF
+            self._set_z(value, number)
+            self._prefetch()
+            self._cycles += 2
+            return
+        address, value = self._ea_fetch(kind, register, 1)
+        self._set_z(value, number)
+        self._prefetch()
+        if operation != TEST:
+            self._write_byte(address, self._apply_bit(value, number, operation))
+
+    def _set_z(self, value: int, number: int) -> None:
+        if value >> number & 1:
+            self.SR &= ~Z
+        else:
+            self.SR |= Z
+
+    @staticmethod
+    def _apply_bit(value: int, number: int, operation: int) -> int:
+        bit = 1 << number
+        if operation == CHANGE:
+            return value ^ bit
+        if operation == CLEAR:
+            return value & ~bit
+        return value | bit
+
+    def _op_btst(self, opcode: int) -> None:
+        """BTST -- Z <- NOT bit n of the destination (PRM 4-62; UM Table 8-8).
+
+        Bus order, the 2 idle clocks of the register form, and the PC an address
+        error stacks: SST BTST.
+        """
+        self._bit_operation(opcode, TEST)
+
+    def _op_bchg(self, opcode: int) -> None:
+        """BCHG -- Z <- NOT bit n, then invert bit n (PRM 4-28; UM Table 8-8).
+
+        On a register 6 clocks, 8 for bits 16-31 (UM Table 8-8's note); bus
+        order and the PC an address error stacks: SST BCHG.
+        """
+        self._bit_operation(opcode, CHANGE)
+
+    def _op_bclr(self, opcode: int) -> None:
+        """BCLR -- Z <- NOT bit n, then clear bit n (PRM 4-31; UM Table 8-8).
+
+        On a register 8 clocks, 10 for bits 16-31, 2 more than BCHG and BSET at
+        every bit; bus order and the PC an address error stacks: SST BCLR.
+        """
+        self._bit_operation(opcode, CLEAR)
+
+    def _op_bset(self, opcode: int) -> None:
+        """BSET -- Z <- NOT bit n, then set bit n (PRM 4-57; UM Table 8-8).
+
+        On a register 6 clocks, 8 for bits 16-31; bus order and the PC an
+        address error stacks: SST BSET.
+        """
+        self._bit_operation(opcode, SET)

m68000_python/_control.py

@@ -0,0 +1,208 @@
+"""Program control: branches, jumps, returns, DBcc, Scc, NOP (PRM Table 3-9).
+
+A taken branch or jump throws the prefetch queue away and refills it from
+the target with two program reads (UM Table 8-9, "What prefetch does to
+these numbers" in docs/timing.md).  A target at an odd address faults on the
+first of those reads.
+"""
+
+from m68000_python._ea import (
+    ABSL,
+    ABSW,
+    DISP,
+    DN,
+    EA_KIND,
+    IND,
+    INDEX,
+    PCDISP,
+    PCINDEX,
+    sign_extend_8,
+    sign_extend_16,
+    word_to_long,
+)
+from m68000_python._flags import CONDITION
+
+
+class ControlMixin:
+    """Private program-control implementation."""
+
+    # -- branches (PRM 4, Bcc/BRA/BSR; UM Table 8-9) -------------------------
+
+    def _branch_target(self, opcode: int) -> int:
+        """The target of a Bcc/BRA/BSR: displacement from the extension word's address.
+
+        An 8-bit displacement of 0 means a 16-bit one follows; $FF is an
+        ordinary -1 on the 68000 (the 68020's long form does not exist;
+        corpus issue #4).
+        """
+        base = self._pc - 2  # the address of the word after the opcode
+        displacement = opcode & 0xFF
+        if displacement:
+            return (base + sign_extend_8(displacement)) & 0xFFFFFFFF
+        return (base + sign_extend_16(self.irc)) & 0xFFFFFFFF
+
+    def _op_bra(self, opcode: int) -> None:
+        """BRA -- branch always: PC <- PC + d (PRM 4-25; UM Table 8-9: 10 clocks)."""
+        self._cycles += 2
+        self._jump(self._branch_target(opcode))
+
+    def _op_bcc(self, opcode: int) -> None:
+        """Bcc -- branch if the condition holds (PRM 4-25; UM Table 8-9).
+
+        Taken: 10 clocks, two internal then the refill.  Not taken with an
+        8-bit displacement: 8 clocks; with a 16-bit one, 12, the extra read
+        skipping the displacement word.
+        """
+        if CONDITION[(opcode >> 8) & 0xF][self.SR & 0xF]:
+            self._cycles += 2
+            self._jump(self._branch_target(opcode))
+            return
+        self._cycles += 4
+        if not opcode & 0xFF:
+            self._extension()
+        self._prefetch()
+
+    def _op_bsr(self, opcode: int) -> None:
+        """BSR -- push the return address, then branch (PRM 4-59; UM Table 8-9: 18 clocks).
+
+        A fault on the refill stacks the target itself: SST BSR.
+        """
+        target = self._branch_target(opcode)
+        # The return address is past the displacement word, when there is one.
+        returns = self._pc if not opcode & 0xFF else self._pc - 2
+        self._cycles += 2
+        self._push_long(returns)
+        self._fault_pc = target  # a fault on the refill stacks the target
+        self._jump(target)
+
+    # -- DBcc and Scc (PRM 4-91, 4-173) ---------------------------------------
+
+    def _op_dbcc(self, opcode: int) -> None:
+        """DBcc -- if cc is false, decrement Dn.w; branch unless it is -1 (PRM 4-91; UM Table 8-9).
+
+        UM Table 8-9: condition true 12 clocks; false and branching 10; false
+        with the count expired 14.
+
+        The branch target's word is read before Dn is written, so an odd target
+        faults with Dn unchanged and stacks the instruction's address + 4:
+        SST DBcc.  WinUAE run stacks the target + 2 instead: contested, the core
+        follows the gate (docs/claims.md).
+        """
+        register = opcode & 7
+        if CONDITION[(opcode >> 8) & 0xF][self.SR & 0xF]:
+            self._cycles += 4
+            self._extension()
+            self._prefetch()
+            return
+        # Condition false: the word at the branch target is read whether or
+        # not the count expires, and Dn is written only after that read, so
+        # an odd target faults with Dn unchanged.
+        self._cycles += 2
+        target = (self._pc - 2 + sign_extend_16(self.irc)) & 0xFFFFFFFF
+        self._commit_pc()
+        count = (self.R[register] - 1) & 0xFFFF
+        self.irc = self._read_program_word(target)
+        if count != 0xFFFF:
+            self._pc = (target + 2) & 0xFFFFFFFF
+        else:
+            self._extension()  # expired: carry on after the displacement word
+        self.R[register] = (self.R[register] & 0xFFFF0000) | count
+        self._prefetch()
+
+    def _op_scc(self, opcode: int) -> None:
+        """Scc -- set a byte to $FF if the condition holds, else $00 (PRM 4-173; UM Table 8-6).
+
+        UM Table 8-6: register 4 clocks false, 6 true; memory 8 plus the EA,
+        the operand read before it is written.  The read, the refill between it
+        and the write, and the PC an address error stacks: SST Scc.
+        """
+        value = 0xFF if CONDITION[(opcode >> 8) & 0xF][self.SR & 0xF] else 0
+        kind = EA_KIND[opcode & 0x3F]
+        register = opcode & 7
+        if kind == DN:
+            self._prefetch()
+            if value:
+                self._cycles += 2
+            self.R[register] = (self.R[register] & 0xFFFFFF00) | value
+            return
+        address = self._ea_address(kind, register, 1)
+        self._read_byte(address)
+        self._prefetch()
+        self._write_byte(address, value)
+
+    # -- jumps and returns ----------------------------------------------------
+
+    def _control_address(self, kind: int, register: int) -> int:
+        """The address of a control-mode operand, for JMP/JSR/LEA/PEA (UM Table 8-10).
+
+        Unlike an operand read, these modes do not take the extension word
+        from the queue as they go: the refill happens later, as part of the
+        jump or the next step.  Internal clocks are the table's.
+        """
+        R = self.R
+        if kind == IND:
+            return R[8 + register]
+        if kind == DISP:
+            return (R[8 + register] + sign_extend_16(self.irc)) & 0xFFFFFFFF
+        if kind == INDEX:
+            return self._indexed(R[8 + register], self.irc)
+        if kind == ABSW:
+            return word_to_long(self.irc)
+        if kind == ABSL:
+            high = self._extension()
+            return ((high << 16) | self.irc) & 0xFFFFFFFF
+        if kind == PCDISP:
+            return (self._pc - 2 + sign_extend_16(self.irc)) & 0xFFFFFFFF
+        if kind == PCINDEX:
+            return self._indexed(self._pc - 2, self.irc)
+        raise AssertionError(f"not a control kind: {kind}")
+
+    def _op_jmp(self, opcode: int) -> None:
+        """JMP -- PC <- effective address (PRM 4-108; UM Table 8-10)."""
+        kind = EA_KIND[opcode & 0x3F]
+        target = self._control_address(kind, opcode & 7)
+        if kind in (DISP, ABSW, PCDISP):
+            self._cycles += 2
+        elif kind in (INDEX, PCINDEX):
+            self._cycles += 6
+        self._jump(target)
+
+    def _op_jsr(self, opcode: int) -> None:
+        """JSR -- push the return address, PC <- effective address (PRM 4-109; UM Table 8-10).
+
+        The target's first word is read before the push, so an odd target faults
+        with nothing pushed: SST JSR.  Through (d16,An), (d8,An,Xn), (d16,PC) and
+        (d8,PC,Xn) WinUAE run stacks 2 less than the gate: contested, the core
+        follows the gate (docs/claims.md).
+        """
+        kind = EA_KIND[opcode & 0x3F]
+        target = self._control_address(kind, opcode & 7)
+        # The return address is past the extension words.
+        returns = self._pc - 2 if kind == IND else self._pc
+        if kind in (DISP, ABSW, PCDISP):
+            self._cycles += 2
+        elif kind in (INDEX, PCINDEX):
+            self._cycles += 6
+        if kind != IND:
+            self._commit_pc()
+        # The target's first word is read before the push, so an odd target
+        # faults with nothing pushed.
+        target &= 0xFFFFFFFF
+        self.irc = self._read_program_word(target)
+        self._pc = (target + 2) & 0xFFFFFFFF
+        self._push_long(returns)
+        self._prefetch()
+
+    def _op_rts(self, opcode: int) -> None:
+        """RTS -- PC <- (SP)+ (PRM 4-169; UM Table 8-12: 16 clocks)."""
+        self._jump(self._pop_long())
+
+    def _op_rtr(self, opcode: int) -> None:
+        """RTR -- CCR <- (SP)+, then PC <- (SP)+ (PRM 4-168; UM Table 8-12: 20 clocks)."""
+        ccr = self._pop_word()
+        self._set_ccr(ccr)
+        self._jump(self._pop_long())
+
+    def _op_nop(self, opcode: int) -> None:
+        """NOP -- no operation (PRM 4-147; UM Table 8-12: 4 clocks, the prefetch)."""
+        self._prefetch()