feat(models): cover the eight NMOS packages the data sheet lists

The 6500 data sheet names ten packages sharing one die. Two were
modelled. The other eight differ only in how far an address reaches and
which interrupt lines the package brings out, both of which the
per-model pages state exhaustively.

A line the package does not bring out is not a line a system can assert,
so pulling one now raises instead of quietly taking the interrupt. That
makes the 6507 having no interrupt pins a behaviour rather than a
sentence in its summary.

Author: gufranco

README.md

@@ -183,29 +183,46 @@ describe("w65c802").address_bits
 cpu = Cpu(SparseMemory(), model="65802")
 ```
 
-| Model | Address bits | Decimal | Notes |
-|:------|:------------:|:-------:|:------|
-| `6502` | 16 | yes | MOS 6502. Aliases: `mos6502`, `nmos6502`, `6510`, `8500` |
-| `6507` | 13 | yes | The same die in a smaller package. Aliases: `mos6507` |
-| `2a03` | 16 | **no** | Ricoh 2A03 and 2A07. Aliases: `ricoh2a03`, `2a07`, `nes6502`, `famicom` |
-| `65c02` | 16 | yes | The base CMOS design. Aliases: `synertek65c02`, `cmos6502` |
-| `r65c02` | 16 | yes | Rockwell R65C02, adding thirty two single-bit instructions. Aliases: `rockwell65c02` |
-| `w65c02` | 16 | yes | WDC W65C02S, adding stop and wait. Aliases: `wdc65c02`, `w65c02s` |
-| `65802` | 16 | yes | WDC W65C802, the sixteen bit core in a 6502 pin out. Aliases: `w65c802`, `65c802` |
-| `65816` | 24 | yes | WDC W65C816S. Aliases: `w65c816`, `w65c816s`, `65c816`, `65816s` |
+| Model | Address bits | Pins | Decimal | Notes |
+|:------|:------------:|:-----|:-------:|:------|
+| `6502` | 16 | IRQ, NMI, RDY | yes | MOS 6502. Aliases: `mos6502`, `nmos6502`, `6510`, `8500` |
+| `6503` | 12 | IRQ, NMI | yes | Four kilobytes, on-chip clock. Aliases: `mos6503` |
+| `6504` | 13 | IRQ | yes | Eight kilobytes, no non-maskable pin. Aliases: `mos6504` |
+| `6505` | 12 | IRQ, RDY | yes | Four kilobytes, ready line, no non-maskable pin. Aliases: `mos6505` |
+| `6506` | 12 | IRQ | yes | Four kilobytes, second clock output instead of ready. Aliases: `mos6506` |
+| `6507` | 13 | RDY | yes | The same die in a smaller package, no interrupt pins at all. Aliases: `mos6507` |
+| `6512` | 16 | IRQ, NMI, RDY | yes | The 6502 with the clock oscillator left off the die. Aliases: `mos6512` |
+| `6513` | 12 | IRQ, NMI | yes | The 6503 on an external clock. Aliases: `mos6513` |
+| `6514` | 13 | IRQ | yes | The 6504 on an external clock. Aliases: `mos6514` |
+| `6515` | 12 | IRQ, RDY | yes | The 6505 on an external clock. Aliases: `mos6515` |
+| `2a03` | 16 | IRQ, NMI, RDY | **no** | Ricoh 2A03 and 2A07. Aliases: `ricoh2a03`, `2a07`, `nes6502`, `famicom` |
+| `65c02` | 16 | IRQ, NMI, RDY | yes | The base CMOS design. Aliases: `synertek65c02`, `cmos6502` |
+| `r65c02` | 16 | IRQ, NMI, RDY | yes | Rockwell R65C02, adding thirty two single-bit instructions. Aliases: `rockwell65c02` |
+| `w65c02` | 16 | IRQ, NMI, RDY | yes | WDC W65C02S, adding stop and wait. Aliases: `wdc65c02`, `w65c02s` |
+| `65802` | 16 | IRQ, NMI, RDY | yes | WDC W65C802, the sixteen bit core in a 6502 pin out. Aliases: `w65c802`, `65c802` |
+| `65816` | 24 | IRQ, NMI, RDY | yes | WDC W65C816S. Aliases: `w65c816`, `w65c816s`, `65c816`, `65816s` |
 
 Three of those differences are the kind that produce a bug rather than a compile error.
 
 The address bus is not cosmetic. The 65802 has sixteen address lines, so bank bits never leave the chip and a read of `$7E0012` lands on `$0012`. The 6507 has thirteen, so everything above eight kilobytes is a mirror of something below it.
 
+Neither are the pins. The ten NMOS packages share one die and one instruction set, and what separates most of them is how far an address reaches and which interrupt lines the package brought out. A line that is not on the package is not a line a system can assert, so pulling one here raises rather than quietly taking the interrupt:
+
+```python
+cpu = Cpu(SparseMemory(), model="6507")
+cpu.irq()
+
+# NoSuchPin: the 6507 has no irq pin; it brings out rdy
+```
+
 Decimal mode is a property of the part. The Ricoh variant in the Famicom has the decimal adder left unwired, so the flag can be set and changes nothing. Code that sets it and expects decimal arithmetic is wrong, and the part will not say so.
 
 And the undocumented instructions are not optional. A hundred and fifty one of the 6502's opcodes were never documented, programs used them anyway, and a core that treats them as undefined is wrong for the machines that shipped.
 
 Revisions are separate models, including the ones that only fixed a bug, because a machine has whichever revision it was built with. The three CMOS parts differ in exactly two opcode columns and two opcodes: a bit-clear instruction on a part that does not have it is a no-operation, and nothing reports that the bit was never cleared.
 
 > [!NOTE]
-> A model is only listed once a conformance suite backs it. A model with no suite behind it would make its fidelity a claim rather than a measurement.
+> A model is only listed once something measures it. Six are held to a suite of their own. The other ten name the part they narrow and are held to that part's suite plus a check that the narrowing, fewer address lines or fewer pins, is the only difference. Either way the fidelity is a measurement rather than a claim.
 
 ## What "nothing starts clean" means
 

conformance/hardware.json

@@ -60,6 +60,15 @@
       "readVia": "docs/manufacturer/w65c816s-2024.pdf, 55 pages",
       "covers": "The current revision. Its caveats table carries the same values as the 2004 one, renumbered from Table 8-1 to Table 7-1, which is what makes those claims safe to cite without pinning a revision.",
       "pinnedIn": "docs/documents.json, manufacturer/w65c816s-2024.pdf"
+    },
+    "mos6500_datasheet": {
+      "publisher": "Commodore Semiconductor Group, formerly MOS Technology, Inc.",
+      "title": "6500 Microprocessors data sheet",
+      "revision": "November 1985, with the March 1980 printing beside it",
+      "readOn": "2026-08-21",
+      "readVia": "docs/manufacturer/mos-6500-mpu-nov-1985.pdf, 12 pages",
+      "covers": "Which parts the NMOS family has. A page per package giving its addressable range and the interrupt lines it brings out, which between them are the whole of what a program can tell apart.",
+      "pinnedIn": "docs/documents.json, manufacturer/mos-6500-mpu-nov-1985.pdf"
     }
   },
   "facts": {
@@ -285,6 +294,17 @@
       "section": "Table 7-1 Caveats, which the 2004 revision numbers Table 8-1",
       "quote": "A.ABS,X,ASL,LSR,ROL with no Page Crossing: 7 cycles, 6 cycles, 6 cycles, 7 cycles.",
       "note": "Every cell of the comparison table is the same in the 2004 and 2024 revisions, twenty years apart. Only the section number moved. A claim taken from that table therefore does not depend on which revision a reader happens to hold, which is worth knowing because three revisions of this data sheet are pinned here."
+    },
+    "nmosFamilyPackages": {
+      "document": "mos6500_datasheet",
+      "section": "Features of 6502 through Features of 6515",
+      "quote": "Features of 6504: 8K Addressable Bytes of Memory (A0-A12). On-the-chip Clock. IRQ Interrupt. 8 Bit Bidirectional Data Bus.",
+      "note": "Ten packages, one die. The list of features under each is exhaustive, so a line absent from it is a line the package does not bring out: the 6504 has no non-maskable pin and the 6507 has neither interrupt pin. Six of the ten have an on-chip oscillator and four take their clock on pins, which is the only difference between 6502 and 6512, between 6503 and 6513, and so on, and it is not something a program can see.",
+      "whatIsImplemented": {
+        "addressLines": "12 on the 6503, 6505, 6506, 6513 and 6515; 13 on the 6504, 6507 and 6514; 16 on the 6502 and 6512",
+        "interruptPins": "Both on the 6502, 6503, 6512 and 6513. The request line alone on the 6504, 6505, 6506, 6514 and 6515. Neither on the 6507.",
+        "whatHappensWhenOneIsMissing": "Pulling it raises, because a line the package does not bring out is not a line a system can assert"
+      }
     }
   }
 }

conformance/hardware.test.py

@@ -16,7 +16,7 @@
 ROOT = Path(__file__).resolve().parent.parent
 sys.path.insert(0, str(ROOT))
 
-from mos65xx import Memory, mos6502, wdc65816  # noqa: E402
+from mos65xx import Memory, models, mos6502, wdc65816  # noqa: E402
 
 HARDWARE = Path(__file__).resolve().parent / "hardware.json"
 
@@ -270,6 +270,39 @@ def test_which_is_what_the_earliest_revision_says_and_the_later_ones_omit(self)
 
         self.assertIn("lands above 0001FF rather than wrapping", recorded["note"])
 
+    def packages(self) -> list[str]:
+        """The ten the data sheet lists, read from what it is recorded as covering."""
+        manifest = json.loads((ROOT / "docs" / "documents.json").read_text())
+        found = [
+            entry["covers"]
+            for entry in manifest["documents"]
+            if "mos-6500-mpu-nov" in entry["file"]
+        ]
+
+        return [str(name) for name in found[0]]
+
+    def test_the_data_sheet_lists_ten_packages(self) -> None:
+        self.assertEqual(len(self.packages()), 10)
+
+    def test_the_family_table_matches_the_parts_this_package_builds(self) -> None:
+        recorded = fact("nmosFamilyPackages")["whatIsImplemented"]["interruptPins"]
+        both = [
+            name for name in self.packages() if {"irq", "nmi"} <= set(models.describe(name).pins)
+        ]
+
+        self.assertEqual(
+            (both, "6502, 6503, 6512 and 6513" in recorded),
+            (["6502", "6503", "6512", "6513"], True),
+        )
+
+    def test_and_the_one_with_neither_line_is_the_one_the_table_names(self) -> None:
+        recorded = fact("nmosFamilyPackages")["whatIsImplemented"]["interruptPins"]
+        neither = [
+            name for name in self.packages() if not {"irq", "nmi"} & set(models.describe(name).pins)
+        ]
+
+        self.assertEqual((neither, "Neither on the 6507" in recorded), (["6507"], True))
+
     def test_the_comparison_table_is_the_same_in_both_revisions_that_carry_it(self) -> None:
         recorded = fact("caveatsTableIsStableAcrossRevisions")
 

mos65xx/__init__.py

@@ -27,7 +27,7 @@
 
 from . import mos65c02, mos6502, opcodes65c02, opcodes6502
 from .memory import Memory, SparseMemory, scramble
-from .models import MODELS, UnknownModelError, describe
+from .models import MODELS, NoSuchPin, UnknownModelError, describe
 from .opcodes65816 import (
     FLAG_DEPENDENT,
     MODE_SIZE,
@@ -86,6 +86,7 @@ def Cpu(memory: Any, model: str = DEFAULT_MODEL, **options: Any) -> Any:  # noqa
     "Cpu",
     "Cpu65816",
     "Memory",
+    "NoSuchPin",
     "SparseMemory",
     "StepLimit",
     "Stopped",

mos65xx/models.py

@@ -12,13 +12,21 @@
 A model with no suite behind it does not belong in this table, because then its
 fidelity would be a claim rather than a measurement.
 
-Two of these have no suite of their own, and each says which part it narrows.
-Neither is a different processor: the 6507 is a 6502 with three address lines
-left inside the package, and the 65802 is a 65816 in a forty pin part whose bank
-registers reach nothing outside the first bank. What holds them is the suite of
-the part they narrow plus a check that the narrowing is the only difference, so
-the claim is still measured; it is measured against a sibling rather than against
-a recording of its own.
+Ten of these have no suite of their own, and each says which part it narrows.
+None is a different processor. Nine are the 6502 die in a smaller package, with
+address lines left inside and, on most of them, one or both interrupt pins gone;
+the 65802 is a 65816 in a forty pin part whose bank registers reach nothing
+outside the first bank. What holds them is the suite of the part they narrow
+plus a check that the narrowing is the only difference, so the claim is still
+measured; it is measured against a sibling rather than against a recording of
+its own.
+
+A pin the package does not bring out is not a pin a system can assert, so
+pulling one here raises rather than quietly taking the interrupt. That is the
+whole of what separates the 6503, 6504, 6505 and 6506 from one another: they
+have the same core, the same instructions and the same timing, and they differ
+in how far an address reaches and which of the two interrupt lines survived the
+pin count.
 """
 
 from __future__ import annotations
@@ -31,6 +39,16 @@ class UnknownModelError(Exception):
     pass
 
 
+class NoSuchPin(Exception):
+    """Raised when a caller pulls a line the package does not bring out.
+
+    The narrower parts of the family are the same die in a smaller package, and
+    the lines that did not fit are simply not there. A system cannot assert one,
+    so a model that quietly accepted the request would be describing a part
+    nobody could build.
+    """
+
+
 class Model:
     """One part of the family: what it is, what it reaches, and how to build it."""
 
@@ -45,6 +63,7 @@ def __init__(
         aliases: Iterable[str] = (),
         revision: str | None = None,
         narrows: str | None = None,
+        pins: Iterable[str] = ("irq", "nmi", "rdy"),
     ) -> None:
         self.name = name
         self.summary = summary
@@ -55,6 +74,7 @@ def __init__(
         self.aliases = tuple(aliases)
         self.revision = revision
         self.narrows = narrows
+        self.pins = tuple(pins)
 
     @property
     def address_mask(self) -> int:
@@ -74,6 +94,7 @@ def _build_6502(model: Model, memory: Any, **options: Any) -> Any:
     cpu = Cpu6502(memory, decimal=model.decimal, **options)
     cpu.model = model.name
     cpu.address_mask = model.address_mask
+    cpu.package_pins = model.pins
     return cpu
 
 
@@ -87,6 +108,7 @@ def _build_65c02(model: Model, memory: Any, **options: Any) -> Any:
     cpu = Cpu65c02(memory, table=TABLES[model.revision], decimal=model.decimal, **options)
     cpu.model = model.name
     cpu.address_mask = model.address_mask
+    cpu.package_pins = model.pins
     return cpu
 
 
@@ -96,6 +118,7 @@ def _build_65816(model: Model, memory: Any, **options: Any) -> Any:
     cpu = Cpu65816(memory, **options)
     cpu.model = model.name
     cpu.address_mask = model.address_mask
+    cpu.package_pins = model.pins
     return cpu
 
 
@@ -125,8 +148,112 @@ def _build_65816(model: Model, memory: Any, **options: Any) -> Any:
         decimal=True,
         core=_build_6502,
         narrows="6502",
+        pins=("rdy",),
         aliases=("mos6507",),
     ),
+    Model(
+        name="6503",
+        summary=(
+            "MOS 6503. Twelve address lines and both interrupt pins, in a twenty eight pin "
+            "package. Four kilobytes, and everything above that is a mirror."
+        ),
+        address_bits=12,
+        data_bits=8,
+        decimal=True,
+        core=_build_6502,
+        narrows="6502",
+        pins=("irq", "nmi"),
+        aliases=("mos6503",),
+    ),
+    Model(
+        name="6504",
+        summary=(
+            "MOS 6504. Thirteen address lines and the request pin only, so a program on it "
+            "cannot be interrupted by anything it cannot mask."
+        ),
+        address_bits=13,
+        data_bits=8,
+        decimal=True,
+        core=_build_6502,
+        narrows="6502",
+        pins=("irq",),
+        aliases=("mos6504",),
+    ),
+    Model(
+        name="6505",
+        summary=(
+            "MOS 6505. Twelve address lines, the request pin and the ready line, with no "
+            "non-maskable pin brought out."
+        ),
+        address_bits=12,
+        data_bits=8,
+        decimal=True,
+        core=_build_6502,
+        narrows="6502",
+        pins=("irq", "rdy"),
+        aliases=("mos6505",),
+    ),
+    Model(
+        name="6506",
+        summary=(
+            "MOS 6506. Twelve address lines and the request pin, with the ready line spent on "
+            "a second clock output instead."
+        ),
+        address_bits=12,
+        data_bits=8,
+        decimal=True,
+        core=_build_6502,
+        narrows="6502",
+        pins=("irq",),
+        aliases=("mos6506",),
+    ),
+    Model(
+        name="6512",
+        summary=(
+            "MOS 6512. The 6502 with the clock oscillator left off the die, so the two phases "
+            "come in on pins. Nothing a program can see differs."
+        ),
+        address_bits=16,
+        data_bits=8,
+        decimal=True,
+        core=_build_6502,
+        narrows="6502",
+        pins=("irq", "nmi", "rdy"),
+        aliases=("mos6512",),
+    ),
+    Model(
+        name="6513",
+        summary="MOS 6513. The 6503 driven by an external clock rather than its own.",
+        address_bits=12,
+        data_bits=8,
+        decimal=True,
+        core=_build_6502,
+        narrows="6502",
+        pins=("irq", "nmi"),
+        aliases=("mos6513",),
+    ),
+    Model(
+        name="6514",
+        summary="MOS 6514. The 6504 driven by an external clock rather than its own.",
+        address_bits=13,
+        data_bits=8,
+        decimal=True,
+        core=_build_6502,
+        narrows="6502",
+        pins=("irq",),
+        aliases=("mos6514",),
+    ),
+    Model(
+        name="6515",
+        summary="MOS 6515. The 6505 driven by an external clock rather than its own.",
+        address_bits=12,
+        data_bits=8,
+        decimal=True,
+        core=_build_6502,
+        narrows="6502",
+        pins=("irq", "rdy"),
+        aliases=("mos6515",),
+    ),
     Model(
         name="2a03",
         summary=(