m68000-python 0.1.0__tar.gz

m68000_python-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14", "pypy3.11"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      # Everything but the corpus gates: the decoder, readability, the BCD
+      # tables, the manual-derived and referee-pinned tests, the tooling.
+      - run: python -m pytest -q
+      - run: python -m ruff check .
+      - run: python -m ruff format --check .
+      - run: python examples/minimal_m68000_host.py
+      - run: python examples/interrupt_host.py
+
+  # The SingleStepTests/m68000 gate at the pinned commit: 127 files, 317,500
+  # cases, compared on registers, SR, the queue, RAM, clocks and every bus
+  # access (docs/validation.md), and the step_clocks claim over the same
+  # cases.  The 112 MB archive is fetched once per pin and cached.
+  corpus:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.14", "pypy3.11"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - uses: actions/cache@v4
+        with:
+          path: tests/68000_test_vectors/m68000
+          key: m68000-64b253116a3de04aaac4346c43680960dc9b67e5
+      - run: test -f tests/68000_test_vectors/m68000/REVISION || python scripts/fetch_test_vectors.py
+      - run: python -m pytest -q tests/test_corpus.py tests/test_step_clocks.py tests/test_bcd.py
+
+  # The wheel a release would publish, installed into a clean interpreter and
+  # exercised from outside the source tree.
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build
+      - run: python -m build --wheel --sdist
+      - run: python -m pip install --force-reinstall dist/*.whl
+      - name: Smoke-test the installed public API
+        working-directory: ${{ runner.temp }}
+        run: python ${{ github.workspace }}/scripts/smoke_installed_package.py

m68000_python-0.1.0/.github/workflows/oracles.yml

@@ -0,0 +1,90 @@
+# The evidence CI cannot rerun on every push: the referees built from pinned
+# sources and calibrated against the gate, the second corpus as a detector,
+# the decoder against MAME's listing, the coverage map and the mutation
+# score.  Each step's headline number is the one docs/validation.md,
+# docs/referees.md, docs/coverage.md and docs/mutation.md record; a step
+# fails when its number moves, so the documents cannot drift from the tree.
+#
+# Not covered here: the MAME lockstep (needs MAME 0.285 and the ROMs) and
+# the T1 BCD gate, which ci.yml runs on every push.  Scheduled weekly, and
+# runnable on demand.
+name: Oracles
+
+on:
+  schedule:
+    - cron: "23 6 * * 1"   # Mondays, 06:23 UTC
+  workflow_dispatch:
+
+jobs:
+  oracles:
+    runs-on: ubuntu-latest
+    timeout-minutes: 150
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "pypy3.11"
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+
+      - name: Restore the SingleStepTests/m68000 corpus
+        uses: actions/cache@v4
+        with:
+          path: tests/68000_test_vectors/m68000
+          key: m68000-64b253116a3de04aaac4346c43680960dc9b67e5
+      - name: Restore the SingleStepTests/680x0 corpus
+        uses: actions/cache@v4
+        with:
+          path: tests/68000_test_vectors/680x0
+          key: 680x0-e0d5ece9670205cc84a0101081837deb446f86a3
+      - name: Fetch what the caches did not hold
+        # The two corpora cache separately, so one can be present while the
+        # other is not -- and the 680x0 cache has never once hit here. Using
+        # --with-680x0 for the second line (as this step used to) asks the
+        # script to fetch m68000 *and* 680x0 together; since m68000 was
+        # already there, that call's own fetch_m68000() immediately hit the
+        # script's "directory exists" guard, every single run. --680x0-only
+        # fetches just the corpus this step actually still needs.
+        run: |
+          test -f tests/68000_test_vectors/m68000/REVISION || {
+            rm -rf tests/68000_test_vectors/m68000
+            python scripts/fetch_test_vectors.py
+          }
+          test -d tests/68000_test_vectors/680x0/68000/v1 || {
+            rm -rf tests/68000_test_vectors/680x0
+            python scripts/fetch_test_vectors.py --680x0-only
+          }
+
+      - name: The decoder against MAME 0.285's m68000.lst, word for word
+        run: python scripts/check_decoder_vs_mame.py
+
+      - name: The second corpus as a detector, every disagreement classified
+        run: |
+          python scripts/classify_680x0.py 2>/dev/null | tee classify.txt
+          grep -q "^787,660 of 1,000,060 cases agree" classify.txt
+
+      - name: Build the referees from their pinned sources
+        run: python validation/referees/build_referees.py
+      - name: Calibrate WinUAE's tester core against the gate
+        run: |
+          python validation/referees/calibrate.py winuae | tee winuae.txt
+          grep -q "^TOTAL winuae vs m68000: 308416/314988 judged cases agree" winuae.txt
+      - name: Calibrate Musashi against the gate
+        run: |
+          python validation/referees/calibrate.py musashi | tee musashi.txt
+          grep -q "^TOTAL musashi vs m68000: 257300/261894 judged cases agree" musashi.txt
+      - name: The open questions, put to the referees
+        run: python validation/referees/questions.py
+
+      - name: Coverage map of the gate and the suite
+        run: |
+          python scripts/coverage_report.py encodings | tee encodings.txt
+          grep -q "executed as a first word        38,019" encodings.txt
+          python scripts/coverage_report.py paths | tail -5
+
+      - name: Mutation score of the suite
+        run: |
+          python scripts/mutate.py run --jobs 2 --python "$(command -v python)" --out mutation.json
+          python scripts/mutate.py escalate mutation.json --jobs 2 --python "$(command -v python)"
+          python scripts/mutate.py report mutation.json | tee mutation.txt
+          grep -q "^Score: 174/176" mutation.txt

m68000_python-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+# Build, check and publish m68000-python to PyPI with Trusted Publishing
+# (OIDC): no stored token.  PyPI must know this repository, this workflow
+# file and the `pypi` environment as the project's publisher (Aubrey
+# registers it before the first tag, as for z80-python).
+#
+# A pushed release tag (v0.1.0, not v0.1.0-rc1) builds, smoke-tests and
+# uploads.  Every pull request runs the same build, check and smoke test as
+# a dry run, so a broken release is caught before the tag.  Run it by hand
+# (workflow_dispatch) for the same dry run on any branch; only a tag is
+# ever uploaded.
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+      - "!v*-rc*"
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      dry_run:
+        description: "Build, smoke-test and check only; never upload"
+        type: boolean
+        default: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install --upgrade pip build twine
+      - run: python -m build --wheel --sdist
+      - run: python -m twine check --strict dist/*
+      - name: A release tag must name the package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "${GITHUB_REF_NAME}" = "v${version}" || {
+            echo "tag ${GITHUB_REF_NAME} does not match version ${version}"; exit 1; }
+      - run: python -m pip install dist/*.whl
+      - name: Smoke-test the installed wheel
+        working-directory: ${{ runner.temp }}
+        run: python ${{ github.workspace }}/scripts/smoke_installed_package.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    if: >-
+      startsWith(github.ref, 'refs/tags/v') &&
+      (github.event_name == 'push' || inputs.dry_run == false)
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

m68000_python-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python and package builds
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+
+# Virtual environments and tooling
+.venv/
+.venv-*/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# External validation inputs; fetch them locally, never commit them.
+# Both SingleStepTests corpora land here (scripts/fetch_test_vectors.py).
+tests/68000_test_vectors/
+
+# MAME oracle runs: traces, error.log, nvram, cfg. Never commit ROMs or traces.
+validation/mame_runs/
+# MAME's m68000.lst, fetched at a pinned tag by scripts/check_decoder_vs_mame.py.
+validation/mame/
+*.trace
+error.log
+
+# Referee sources (third-party, fetched at pinned commits) and their builds:
+# validation/referees/build_referees.py. Never commit either.
+validation/referees/src/
+validation/referees/build/

m68000_python-0.1.0/CHANGELOG.md

@@ -0,0 +1,123 @@
+# Changelog
+
+All notable changes to `m68000-python` are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- **The conformance kit**, `m68000_python.conformance` and
+  `python -m m68000_python.conformance trace|diff`, in z80-python's shape:
+  a versioned JSON manifest fixes the machine (16 MiB of flat RAM, reset or
+  an initial state, the acknowledge answers, BERR ranges, TAS's write
+  cycle, replayed device windows, `ipl` and `reset` events, stop rules); the
+  reference writes its trace with every bus access, and `diff` compares
+  another core's trace in lockstep. `examples/conformance/` holds three
+  programs and the interrupt and STOP scenarios as manifests with their
+  reference traces; `validation/lockstep.py export` writes the MAME runs as
+  replay manifests. docs/conformance.md has the certification ladder for a
+  port.
+
+### Fixed
+
+- **The reset exception takes 40 clocks, not 42** (#3). `reset()` now
+  spends 14 internal clocks before reading the SSP vector, not 16, so it
+  returns 40, as UM Table 8-14 prints (40(6/0)), and every access of the
+  reset starts 2 clocks earlier. The 14 are measured: Nuked-MD's gate-level
+  68000 (built from die photographs) reads the SSP vector 14 clocks after
+  RESET is released, and the rest of the reset at the core's clocks. A host
+  whose timing counts from `reset()` sees every later clock 2 lower, which
+  moves the E-clock phase of autovectored interrupts. docs/claims.md moves
+  the reset total from "Undecidable here" to "Provisional".
+
+## [0.1.0] — unreleased
+
+The first release: the whole 68000 instruction set and exception model,
+verified up a ladder of oracles ordered by tier, with a claim boundary for
+what no available evidence settles.
+
+### Breaking (relative to the development tree megadrive-python and sms-python built against)
+
+- **Console numbers are decimal, or hexadecimal with `$` or `0x`.** The
+  console, `console.parse_number` and `python -m m68000_python`'s
+  addresses treated a bare number as hexadecimal and `#` as decimal; they
+  now follow the family's rule. Migration: write `break $1006` or
+  `break 0x1006`, `--pc 0x1000`, and drop the `#`.
+- **`reset_devices` is a constructor keyword.** The RESET instruction's
+  pulse used to reach a `reset_devices` attribute found by `getattr`.
+  Migration: `M68000CPU(..., reset_devices=callback)`.
+- **`set_pc` refuses an odd address and `CPUState` an odd `pc`** with a
+  `ValueError`: an instruction never lives at an odd address, and a jump to
+  one is an address error, not a start. Migration: none for a host that
+  starts programs at even addresses, which is every host.
+
+### Added
+
+- The core: every defined first word (45,815), the prefetch queue, address
+  and bus errors with the seven-word frame, the interrupt lifecycle with
+  the acknowledge cycle and the E-clock wait, trace, STOP, RESET, and
+  `step_clocks` for the clock at which each access ends within a step.
+- The claim boundary (docs/claims.md): every behaviour labelled verified,
+  strong, provisional, contested, undecidable here or outside the contract,
+  by the independent lineages that support it.
+- Oracles and referees: flamewing's hardware-captured BCD tables (T1),
+  WinUAE's CPU-tester core and Musashi built from pinned sources and run
+  over the gate (docs/referees.md), the SingleStepTests/m68000 gate with
+  every bus access compared and no case excluded, the MAME 0.285 lockstep
+  on 52.8 million instructions of real code, the 680x0 corpus as a
+  classified detector, and MAME's `m68000.lst` against the decoder.
+- The suite measured: a coverage map over encodings, behavioural paths and
+  source lines (docs/coverage.md) and 176 seeded mutants of which 174 are
+  killed, the two survivors equivalent (docs/mutation.md).
+- Every handler cites its manual page and names the corpus file, referee
+  run or hardware tables that pin what the manual leaves open;
+  `tests/test_readability.py` enforces it.
+- Tooling in z80-python's shape: `CPUState`, a disassembler in MAME's
+  spelling (checked against 1,300 instructions of MAME's own disassembly
+  of real game code), `DebugSession` with breakpoints, watchpoints,
+  bus-access tracking and board targets, versioned JSON Lines traces with
+  first-divergence comparison of files and of live sessions,
+  `CommandDebugger`, and `python -m m68000_python` with `--zip` for
+  even/odd ROM pairs.
+- Examples: `examples/minimal_m68000_host.py`, `examples/interrupt_host.py`
+  and a committed reference trace; a benchmark harness with four named
+  workloads and a same-process A/B of two revisions.
+- CI on every push (CPython 3.11-3.14 and PyPy 3.11, the corpus gate on two
+  interpreters, a wheel build and installed-API smoke test) and a weekly
+  Oracles workflow that rebuilds the referees and fails when any recorded
+  number moves.
+
+### Changed
+
+- **9% faster on CPython, 37% on PyPy** (the `base` workload): a speed
+  ladder of five candidate rungs, one commit per rung, every oracle green
+  at each and measured with `benchmarks/compare_revisions.py`. Kept:
+  `MASK`/`MSB` as tuples (A) and the refills reading the program word
+  themselves (C); reverted or not adopted: the A7 byte step inlined (B),
+  flags computed inside `_add` (D), the function-code wrappers (E). The
+  table is in docs/validation.md, "Speed".
+
+### Fixed
+
+Each as a failing test first, then the fix:
+
+- An address error during the reset sequence (an odd initial PC) let the
+  core's internal exception escape from `reset()`; it is a double bus fault
+  and the processor halts (UM 5.4.4). Found by the polish round's coverage
+  check of the refills, 2026-09-25.
+
+In the verification rounds before this release:
+
+- A traced illegal, line A/F or privileged instruction was followed by a
+  trace exception; UM 6.3.8, MAME's microcode and WinUAE say an
+  instruction that was not executed is not traced (8760315).
+- A fault while TRAPV's trap was processed stacked the next opcode as IR;
+  WinUAE (run) and MAME's microcode keep TRAPV (e057279).
+- A `BusError` raised on TAS's write half escaped `step()` instead of
+  becoming the bus-error exception (36862e5).
+- The I/N bit of a fault during group 2 exception processing was set; WinUAE
+  (run) and MAME's microcode clear it (e395be9).
+- The disassembler printed every undefined word as `illegal`; MAME prints
+  `dc.w $xxxx; ILLEGAL` for all but `$4AFC`, and so does the core's now.

m68000_python-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Issues are the right place for bug reports, API discussion and proposed
+changes; a disagreement with an oracle is an issue with the evidence
+attached, not a pull request that changes the core.
+
+For a pull request:
+
+1. Keep the instruction core independent of machine and device policy; the
+   host owns everything the [README](README.md)'s boundary gives it.
+2. **Never change the core against the gate.** The pinned SingleStepTests
+   corpus decides bus order, clocks and the stacked PC unless a source
+   closer to silicon says otherwise; a rule [claims.md](docs/claims.md)
+   lists as contested stays on the gate until real-hardware evidence
+   decides it. A change that makes the gate fail is wrong or needs a new
+   decision, in that order.
+3. A core fix lands as a **failing test first**, in its own commit, then
+   the fix. Add a focused test for any behaviour change: in
+   `tests/test_coverage_gaps.py` when the manual decides it, in
+   `tests/test_referee_evidence.py` when a referee run does; and rerun the
+   whole gate.
+4. A new or changed handler keeps the readability contract
+   (`tests/test_readability.py`): its docstring starts with the Motorola
+   name, ends with its sources in parentheses, and names what pins any rule
+   the manuals do not give. The vocabulary:
+   - sources: `PRM 4-116` (a page), `PRM Table 3-18`, `PRM 2.2` (a
+     section), `UM 6.3.6`, `UM Figure 6-7`, `UM Table 8-12` or
+     `UM Table 8-12: 20 clocks`, `UM Tables 8-2, 8-3`; several joined by
+     `; `;
+   - evidence: `SST MOVE.b/.w/.l` or `SST ILLEGAL_LINEA` (files of the
+     gate corpus), `WinUAE run` (docs/referees.md), `flamewing` (the T1
+     BCD tables).
+5. Run `python -m pytest -q`, `python -m ruff check .` and
+   `python -m ruff format --check .` (CI runs all three, plus the examples
+   and a wheel build). With the corpus fetched, `pytest` includes the gate
+   and the `step_clocks` claim; without it they skip.
+6. Every number in a document is regenerated by the command the document
+   names, never remembered; a claim names its oracle and the oracle's tier
+   in the sentence that makes it.
+7. Public API and lifecycle changes go under the right heading in
+   `CHANGELOG.md` (**Breaking** with a one-line migration, before 1.0) and
+   into [docs/api-stability.md](docs/api-stability.md).
+
+Do not commit the corpora, ROMs, MAME traces, referee sources or builds,
+caches, generated package artifacts or credentials.

m68000_python-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alewman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.