Skip to content

Document intake: 68080 Programmer's Reference Manual - #7

Merged
WDrijver merged 1 commit into
mainfrom
prm-intake
Nov 3, 2026
Merged

WDrijver merged 1 commit into
mainfrom
prm-intake

Conversation

@WDrijver

@WDrijver WDrijver commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

First document intake (CONTRIBUTING.md section 11): the Apollo 68080 Programmer's Reference Manual (AC68080PRM.odt, update okt 2026). The ODT is leading.

What's in it

  • sources/official/AC68080PRM.odt: the original, unchanged.
  • tools/intake/prm68080.py: the converter. It uses only the Python standard library. The ODT has no semantic headings (its layout is visual), so pandoc output was not usable; the converter relies on the manual's fixed page structure. --check verifies that the generated files match the ODT.
  • core/cpu-68080/prm/ (89 files):
    • an index that maps each mnemonic to its file;
    • one file per instruction: 28 integer, 36 AMMX, 10 FPU;
    • 15 overview files: programming model, units, B registers, Apollo bit, superscalar, fusing, efficiency, pipeline, timing, optimizing, trace, specs.
  • core/cpu-68080/index.md: now points to prm/.
  • CONTRIBUTING.md section 11, sources/README.md and the CI workflow: the converter step, and a new check "Generated files match their originals".

Conversion notes

  • Diagrams in text:
    • The register drawing and the FPU timing chart are described as tables.
    • The benchmark chart's data was taken from the embedded chart object.
    • The two images are the Vampire logo only.
  • Notation:
    • Register and memory contents are shown as bytes. . marks a box the original leaves empty.
    • Encodings are shown as one row per bit field.
  • Gray text is marked "grayed out in the original". Its meaning varies, see item 7 below.
  • Status: all files are reviewed (WDrijver). The converter keeps that status while a file's content is unchanged, and generates the file as draft again when its content changes.
  • Added for AI: the Summary, "Differences from 68060" and DO/DON'T sections are written by the converter, based on statements in the manual.

Possible errors in the original

Reported to the document owner (Tommo). The conversion keeps the original as it is.

  1. The example mnemonics on the STOREILM and STOREM pages look swapped. Each page's result matches the other instruction.
  2. In the MOVZ2 example, memory starts with 02 23 but the result shows 01 23.
  3. FDBcc's operation reads PC – 1 → Dn; DBcc has Dn – 1 → Dn.
  4. The AMMX overview writes bsel d1,d2,e0, but the PCMPccB page writes bsel d2,d1,e0.
  5. Some encoding boxes are left empty:
    • bit 7 in Bcc, BRA and BSR;
    • bits 15 and 12 of the second word in MOVE2, MOVEH, MOVEX and MOVZ2, where the B field is only 2 bits wide.
  6. MOVEH and STOREILM say "where a0 points to", but their examples use a1 and a2.
  7. The meaning of gray text is not stated for the MOVEC event counters $80C–$80F and $00A–$00E.

Knowledge base files relied on

  • CONTRIBUTING.md sections 4 and 11
  • templates/files/reference.md

🤖 Generated with Claude Code

Add the original ODT to sources/official/ and a converter,
tools/intake/prm68080.py, that generates core/cpu-68080/prm/: an index,
one file per instruction (integer, AMMX, FPU) and overview files.
Diagrams and the benchmark chart are described as tables.

The converter keeps a maintainer's status while a file's content is
unchanged, and CI checks that the generated files match the original.
Generated files are marked reviewed by WDrijver.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@WDrijver
WDrijver requested a review from TuKo1982 as a code owner November 3, 2026 10:35
@WDrijver
WDrijver merged commit 948baf6 into main Nov 3, 2026
2 checks passed
@WDrijver
WDrijver deleted the prm-intake branch November 3, 2026 10:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant