From 8c02cdae8491e35f2757568011618e10093ebde4 Mon Sep 17 00:00:00 2001 From: Willem Drijver Date: Tue, 3 Nov 2026 13:35:22 +0300 Subject: [PATCH] Document intake: 68080 Programmer's Reference Manual 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 --- .github/CODEOWNERS | 89 + .github/workflows/kb-checks.yml | 2 + CONTRIBUTING.md | 21 +- core/cpu-68080/index.md | 51 +- core/cpu-68080/prm/ammx-unit.md | 64 + core/cpu-68080/prm/ammx/ammx-format.md | 81 + core/cpu-68080/prm/ammx/bfly.md | 82 + core/cpu-68080/prm/ammx/bsel.md | 70 + core/cpu-68080/prm/ammx/c2p.md | 70 + core/cpu-68080/prm/ammx/load.md | 70 + core/cpu-68080/prm/ammx/loadi.md | 81 + core/cpu-68080/prm/ammx/lsdq.md | 72 + core/cpu-68080/prm/ammx/minterm.md | 88 + core/cpu-68080/prm/ammx/pack3216.md | 71 + core/cpu-68080/prm/ammx/packuswb.md | 76 + core/cpu-68080/prm/ammx/padd.md | 79 + core/cpu-68080/prm/ammx/pand.md | 68 + core/cpu-68080/prm/ammx/pandn.md | 68 + core/cpu-68080/prm/ammx/pavgb.md | 68 + core/cpu-68080/prm/ammx/pcmpccb.md | 79 + core/cpu-68080/prm/ammx/pcmpccw.md | 80 + core/cpu-68080/prm/ammx/peor.md | 72 + core/cpu-68080/prm/ammx/pmaxb.md | 75 + core/cpu-68080/prm/ammx/pmaxw.md | 60 + core/cpu-68080/prm/ammx/pminb.md | 75 + core/cpu-68080/prm/ammx/pminw.md | 60 + core/cpu-68080/prm/ammx/pmul.md | 80 + core/cpu-68080/prm/ammx/pmula.md | 74 + core/cpu-68080/prm/ammx/por.md | 68 + core/cpu-68080/prm/ammx/psub.md | 79 + core/cpu-68080/prm/ammx/rex.md | 65 + core/cpu-68080/prm/ammx/store.md | 57 + core/cpu-68080/prm/ammx/storec.md | 78 + core/cpu-68080/prm/ammx/storei.md | 83 + core/cpu-68080/prm/ammx/storeilm.md | 82 + core/cpu-68080/prm/ammx/storem.md | 78 + core/cpu-68080/prm/ammx/storem3.md | 84 + core/cpu-68080/prm/ammx/tex.md | 124 ++ core/cpu-68080/prm/ammx/trans.md | 86 + core/cpu-68080/prm/ammx/unpack1632.md | 71 + core/cpu-68080/prm/ammx/vperm.md | 77 + core/cpu-68080/prm/apollo-bit.md | 47 + core/cpu-68080/prm/b-registers.md | 51 + core/cpu-68080/prm/fpu-unit.md | 72 + core/cpu-68080/prm/fpu/fadd-3op.md | 66 + core/cpu-68080/prm/fpu/fdbcc-l.md | 57 + core/cpu-68080/prm/fpu/fdiv-3op.md | 66 + core/cpu-68080/prm/fpu/fmove-dn.md | 76 + core/cpu-68080/prm/fpu/fmovem.md | 78 + core/cpu-68080/prm/fpu/fmoverz.md | 67 + core/cpu-68080/prm/fpu/fmul-3op.md | 66 + core/cpu-68080/prm/fpu/fpu-format.md | 78 + core/cpu-68080/prm/fpu/fsqrt-3op.md | 66 + core/cpu-68080/prm/fpu/fsub-3op.md | 66 + core/cpu-68080/prm/index.md | 170 ++ core/cpu-68080/prm/instruction-efficiency.md | 98 + core/cpu-68080/prm/instruction-fusing.md | 70 + core/cpu-68080/prm/instruction-timing.md | 76 + core/cpu-68080/prm/integer-unit.md | 67 + core/cpu-68080/prm/integer/addiw.md | 74 + core/cpu-68080/prm/integer/addq-bn.md | 62 + core/cpu-68080/prm/integer/bank.md | 82 + core/cpu-68080/prm/integer/bcc-s-plus.md | 62 + core/cpu-68080/prm/integer/bra-s-plus.md | 61 + core/cpu-68080/prm/integer/bsr-s-plus.md | 61 + core/cpu-68080/prm/integer/clr-q.md | 86 + core/cpu-68080/prm/integer/cmp-bn.md | 56 + core/cpu-68080/prm/integer/cmpiw.md | 60 + core/cpu-68080/prm/integer/dbcc-l.md | 60 + core/cpu-68080/prm/integer/extub-extuw.md | 70 + core/cpu-68080/prm/integer/lea-bn.md | 74 + core/cpu-68080/prm/integer/mov3q.md | 75 + core/cpu-68080/prm/integer/move-bn.md | 71 + core/cpu-68080/prm/integer/move-sr.md | 58 + core/cpu-68080/prm/integer/move16.md | 71 + core/cpu-68080/prm/integer/move2.md | 89 + core/cpu-68080/prm/integer/movea-bn.md | 55 + core/cpu-68080/prm/integer/movec.md | 115 ++ core/cpu-68080/prm/integer/moveh.md | 82 + core/cpu-68080/prm/integer/movex.md | 77 + core/cpu-68080/prm/integer/moviw.md | 113 ++ core/cpu-68080/prm/integer/movs.md | 77 + core/cpu-68080/prm/integer/movz.md | 77 + core/cpu-68080/prm/integer/movz2.md | 87 + core/cpu-68080/prm/integer/perm.md | 72 + core/cpu-68080/prm/integer/subq-bn.md | 50 + core/cpu-68080/prm/integer/touch.md | 65 + core/cpu-68080/prm/optimizing.md | 70 + core/cpu-68080/prm/pipeline.md | 51 + core/cpu-68080/prm/programming-model.md | 47 + core/cpu-68080/prm/specs.md | 43 + core/cpu-68080/prm/superscalar.md | 71 + core/cpu-68080/prm/trace.md | 54 + sources/README.md | 5 + sources/official/AC68080PRM.odt | Bin 0 -> 131440 bytes tools/intake/prm68080.py | 1771 ++++++++++++++++++ 96 files changed, 8429 insertions(+), 20 deletions(-) create mode 100644 core/cpu-68080/prm/ammx-unit.md create mode 100644 core/cpu-68080/prm/ammx/ammx-format.md create mode 100644 core/cpu-68080/prm/ammx/bfly.md create mode 100644 core/cpu-68080/prm/ammx/bsel.md create mode 100644 core/cpu-68080/prm/ammx/c2p.md create mode 100644 core/cpu-68080/prm/ammx/load.md create mode 100644 core/cpu-68080/prm/ammx/loadi.md create mode 100644 core/cpu-68080/prm/ammx/lsdq.md create mode 100644 core/cpu-68080/prm/ammx/minterm.md create mode 100644 core/cpu-68080/prm/ammx/pack3216.md create mode 100644 core/cpu-68080/prm/ammx/packuswb.md create mode 100644 core/cpu-68080/prm/ammx/padd.md create mode 100644 core/cpu-68080/prm/ammx/pand.md create mode 100644 core/cpu-68080/prm/ammx/pandn.md create mode 100644 core/cpu-68080/prm/ammx/pavgb.md create mode 100644 core/cpu-68080/prm/ammx/pcmpccb.md create mode 100644 core/cpu-68080/prm/ammx/pcmpccw.md create mode 100644 core/cpu-68080/prm/ammx/peor.md create mode 100644 core/cpu-68080/prm/ammx/pmaxb.md create mode 100644 core/cpu-68080/prm/ammx/pmaxw.md create mode 100644 core/cpu-68080/prm/ammx/pminb.md create mode 100644 core/cpu-68080/prm/ammx/pminw.md create mode 100644 core/cpu-68080/prm/ammx/pmul.md create mode 100644 core/cpu-68080/prm/ammx/pmula.md create mode 100644 core/cpu-68080/prm/ammx/por.md create mode 100644 core/cpu-68080/prm/ammx/psub.md create mode 100644 core/cpu-68080/prm/ammx/rex.md create mode 100644 core/cpu-68080/prm/ammx/store.md create mode 100644 core/cpu-68080/prm/ammx/storec.md create mode 100644 core/cpu-68080/prm/ammx/storei.md create mode 100644 core/cpu-68080/prm/ammx/storeilm.md create mode 100644 core/cpu-68080/prm/ammx/storem.md create mode 100644 core/cpu-68080/prm/ammx/storem3.md create mode 100644 core/cpu-68080/prm/ammx/tex.md create mode 100644 core/cpu-68080/prm/ammx/trans.md create mode 100644 core/cpu-68080/prm/ammx/unpack1632.md create mode 100644 core/cpu-68080/prm/ammx/vperm.md create mode 100644 core/cpu-68080/prm/apollo-bit.md create mode 100644 core/cpu-68080/prm/b-registers.md create mode 100644 core/cpu-68080/prm/fpu-unit.md create mode 100644 core/cpu-68080/prm/fpu/fadd-3op.md create mode 100644 core/cpu-68080/prm/fpu/fdbcc-l.md create mode 100644 core/cpu-68080/prm/fpu/fdiv-3op.md create mode 100644 core/cpu-68080/prm/fpu/fmove-dn.md create mode 100644 core/cpu-68080/prm/fpu/fmovem.md create mode 100644 core/cpu-68080/prm/fpu/fmoverz.md create mode 100644 core/cpu-68080/prm/fpu/fmul-3op.md create mode 100644 core/cpu-68080/prm/fpu/fpu-format.md create mode 100644 core/cpu-68080/prm/fpu/fsqrt-3op.md create mode 100644 core/cpu-68080/prm/fpu/fsub-3op.md create mode 100644 core/cpu-68080/prm/index.md create mode 100644 core/cpu-68080/prm/instruction-efficiency.md create mode 100644 core/cpu-68080/prm/instruction-fusing.md create mode 100644 core/cpu-68080/prm/instruction-timing.md create mode 100644 core/cpu-68080/prm/integer-unit.md create mode 100644 core/cpu-68080/prm/integer/addiw.md create mode 100644 core/cpu-68080/prm/integer/addq-bn.md create mode 100644 core/cpu-68080/prm/integer/bank.md create mode 100644 core/cpu-68080/prm/integer/bcc-s-plus.md create mode 100644 core/cpu-68080/prm/integer/bra-s-plus.md create mode 100644 core/cpu-68080/prm/integer/bsr-s-plus.md create mode 100644 core/cpu-68080/prm/integer/clr-q.md create mode 100644 core/cpu-68080/prm/integer/cmp-bn.md create mode 100644 core/cpu-68080/prm/integer/cmpiw.md create mode 100644 core/cpu-68080/prm/integer/dbcc-l.md create mode 100644 core/cpu-68080/prm/integer/extub-extuw.md create mode 100644 core/cpu-68080/prm/integer/lea-bn.md create mode 100644 core/cpu-68080/prm/integer/mov3q.md create mode 100644 core/cpu-68080/prm/integer/move-bn.md create mode 100644 core/cpu-68080/prm/integer/move-sr.md create mode 100644 core/cpu-68080/prm/integer/move16.md create mode 100644 core/cpu-68080/prm/integer/move2.md create mode 100644 core/cpu-68080/prm/integer/movea-bn.md create mode 100644 core/cpu-68080/prm/integer/movec.md create mode 100644 core/cpu-68080/prm/integer/moveh.md create mode 100644 core/cpu-68080/prm/integer/movex.md create mode 100644 core/cpu-68080/prm/integer/moviw.md create mode 100644 core/cpu-68080/prm/integer/movs.md create mode 100644 core/cpu-68080/prm/integer/movz.md create mode 100644 core/cpu-68080/prm/integer/movz2.md create mode 100644 core/cpu-68080/prm/integer/perm.md create mode 100644 core/cpu-68080/prm/integer/subq-bn.md create mode 100644 core/cpu-68080/prm/integer/touch.md create mode 100644 core/cpu-68080/prm/optimizing.md create mode 100644 core/cpu-68080/prm/pipeline.md create mode 100644 core/cpu-68080/prm/programming-model.md create mode 100644 core/cpu-68080/prm/specs.md create mode 100644 core/cpu-68080/prm/superscalar.md create mode 100644 core/cpu-68080/prm/trace.md create mode 100644 sources/official/AC68080PRM.odt create mode 100644 tools/intake/prm68080.py diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 24dc70f..dd665fc 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -16,6 +16,95 @@ /.markdownlint.jsonc @WDrijver @TuKo1982 /core/cpu-68080/index.md @WDrijver +/core/cpu-68080/prm/ammx-unit.md @WDrijver +/core/cpu-68080/prm/apollo-bit.md @WDrijver +/core/cpu-68080/prm/b-registers.md @WDrijver +/core/cpu-68080/prm/fpu-unit.md @WDrijver +/core/cpu-68080/prm/index.md @WDrijver +/core/cpu-68080/prm/instruction-efficiency.md @WDrijver +/core/cpu-68080/prm/instruction-fusing.md @WDrijver +/core/cpu-68080/prm/instruction-timing.md @WDrijver +/core/cpu-68080/prm/integer-unit.md @WDrijver +/core/cpu-68080/prm/optimizing.md @WDrijver +/core/cpu-68080/prm/pipeline.md @WDrijver +/core/cpu-68080/prm/programming-model.md @WDrijver +/core/cpu-68080/prm/specs.md @WDrijver +/core/cpu-68080/prm/superscalar.md @WDrijver +/core/cpu-68080/prm/trace.md @WDrijver +/core/cpu-68080/prm/ammx/ammx-format.md @WDrijver +/core/cpu-68080/prm/ammx/bfly.md @WDrijver +/core/cpu-68080/prm/ammx/bsel.md @WDrijver +/core/cpu-68080/prm/ammx/c2p.md @WDrijver +/core/cpu-68080/prm/ammx/load.md @WDrijver +/core/cpu-68080/prm/ammx/loadi.md @WDrijver +/core/cpu-68080/prm/ammx/lsdq.md @WDrijver +/core/cpu-68080/prm/ammx/minterm.md @WDrijver +/core/cpu-68080/prm/ammx/pack3216.md @WDrijver +/core/cpu-68080/prm/ammx/packuswb.md @WDrijver +/core/cpu-68080/prm/ammx/padd.md @WDrijver +/core/cpu-68080/prm/ammx/pand.md @WDrijver +/core/cpu-68080/prm/ammx/pandn.md @WDrijver +/core/cpu-68080/prm/ammx/pavgb.md @WDrijver +/core/cpu-68080/prm/ammx/pcmpccb.md @WDrijver +/core/cpu-68080/prm/ammx/pcmpccw.md @WDrijver +/core/cpu-68080/prm/ammx/peor.md @WDrijver +/core/cpu-68080/prm/ammx/pmaxb.md @WDrijver +/core/cpu-68080/prm/ammx/pmaxw.md @WDrijver +/core/cpu-68080/prm/ammx/pminb.md @WDrijver +/core/cpu-68080/prm/ammx/pminw.md @WDrijver +/core/cpu-68080/prm/ammx/pmul.md @WDrijver +/core/cpu-68080/prm/ammx/pmula.md @WDrijver +/core/cpu-68080/prm/ammx/por.md @WDrijver +/core/cpu-68080/prm/ammx/psub.md @WDrijver +/core/cpu-68080/prm/ammx/rex.md @WDrijver +/core/cpu-68080/prm/ammx/store.md @WDrijver +/core/cpu-68080/prm/ammx/storec.md @WDrijver +/core/cpu-68080/prm/ammx/storei.md @WDrijver +/core/cpu-68080/prm/ammx/storeilm.md @WDrijver +/core/cpu-68080/prm/ammx/storem.md @WDrijver +/core/cpu-68080/prm/ammx/storem3.md @WDrijver +/core/cpu-68080/prm/ammx/tex.md @WDrijver +/core/cpu-68080/prm/ammx/trans.md @WDrijver +/core/cpu-68080/prm/ammx/unpack1632.md @WDrijver +/core/cpu-68080/prm/ammx/vperm.md @WDrijver +/core/cpu-68080/prm/fpu/fadd-3op.md @WDrijver +/core/cpu-68080/prm/fpu/fdbcc-l.md @WDrijver +/core/cpu-68080/prm/fpu/fdiv-3op.md @WDrijver +/core/cpu-68080/prm/fpu/fmove-dn.md @WDrijver +/core/cpu-68080/prm/fpu/fmovem.md @WDrijver +/core/cpu-68080/prm/fpu/fmoverz.md @WDrijver +/core/cpu-68080/prm/fpu/fmul-3op.md @WDrijver +/core/cpu-68080/prm/fpu/fpu-format.md @WDrijver +/core/cpu-68080/prm/fpu/fsqrt-3op.md @WDrijver +/core/cpu-68080/prm/fpu/fsub-3op.md @WDrijver +/core/cpu-68080/prm/integer/addiw.md @WDrijver +/core/cpu-68080/prm/integer/addq-bn.md @WDrijver +/core/cpu-68080/prm/integer/bank.md @WDrijver +/core/cpu-68080/prm/integer/bcc-s-plus.md @WDrijver +/core/cpu-68080/prm/integer/bra-s-plus.md @WDrijver +/core/cpu-68080/prm/integer/bsr-s-plus.md @WDrijver +/core/cpu-68080/prm/integer/clr-q.md @WDrijver +/core/cpu-68080/prm/integer/cmp-bn.md @WDrijver +/core/cpu-68080/prm/integer/cmpiw.md @WDrijver +/core/cpu-68080/prm/integer/dbcc-l.md @WDrijver +/core/cpu-68080/prm/integer/extub-extuw.md @WDrijver +/core/cpu-68080/prm/integer/lea-bn.md @WDrijver +/core/cpu-68080/prm/integer/mov3q.md @WDrijver +/core/cpu-68080/prm/integer/move-bn.md @WDrijver +/core/cpu-68080/prm/integer/move-sr.md @WDrijver +/core/cpu-68080/prm/integer/move16.md @WDrijver +/core/cpu-68080/prm/integer/move2.md @WDrijver +/core/cpu-68080/prm/integer/movea-bn.md @WDrijver +/core/cpu-68080/prm/integer/movec.md @WDrijver +/core/cpu-68080/prm/integer/moveh.md @WDrijver +/core/cpu-68080/prm/integer/movex.md @WDrijver +/core/cpu-68080/prm/integer/moviw.md @WDrijver +/core/cpu-68080/prm/integer/movs.md @WDrijver +/core/cpu-68080/prm/integer/movz.md @WDrijver +/core/cpu-68080/prm/integer/movz2.md @WDrijver +/core/cpu-68080/prm/integer/perm.md @WDrijver +/core/cpu-68080/prm/integer/subq-bn.md @WDrijver +/core/cpu-68080/prm/integer/touch.md @WDrijver /core/saga-3d-maggie/index.md @WDrijver /core/saga-audio-arne/index.md @WDrijver /core/saga-dma-anni/index.md @WDrijver diff --git a/.github/workflows/kb-checks.yml b/.github/workflows/kb-checks.yml index f65b031..7bdc267 100644 --- a/.github/workflows/kb-checks.yml +++ b/.github/workflows/kb-checks.yml @@ -22,6 +22,8 @@ jobs: run: python tools/check_frontmatter.py - name: Internal links run: python tools/check_links.py + - name: Generated files match their originals + run: for s in tools/intake/*.py; do python "$s" --check; done - name: Owners are GitHub users run: python tools/check_owners.py env: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d48cf54..29229de 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -269,6 +269,8 @@ Every pull request runs (scripts in `tools/`): - `check_links.py`: internal markdown links point to existing files - `check_owners.py`: every owner is an existing GitHub account - Markdown lint (rules in `.markdownlint.jsonc`) +- `intake/*.py --check`: files generated by document intake match their + original in `sources/official/` (section 11) - Compilation of all `kb:compile` code blocks with ApolloCrossDev (GCC-6.50-Dev, flags as in its Makefile template; see `tools/compile-snippets.sh`) @@ -306,17 +308,24 @@ regenerate. 1. Add or update the original in `sources/official/`, in an editable format such as ODT. PDF is a last resort. -2. Convert it to Markdown, for example with pandoc. -3. Optimize for AI (see below) and split it into knowledge base files in the - right pillar. Every generated file gets: +2. Convert it with a converter script in `tools/intake/`, one per document + (for example `tools/intake/prm68080.py`). The script does the conversion, + the optimization for AI and the split, so an update of the original is + regenerated the same way. Use only the Python standard library. +3. The script splits the result into knowledge base files in the right + pillar (see "Optimized for AI" below). Every generated file gets: - `origin: official` - `owner`: a maintainer - `status: draft` - `generated_from: sources/official/` 4. Open a PR. The maintainer checks the conversion against the original and - sets `status: reviewed` when it is correct. -5. On an update of the original: repeat steps 1–4, and review the diff of - the generated files. + sets `status: reviewed` in a generated file when it is correct. The + converter keeps that status as long as the file's content stays the same, + and generates the file as `draft` again when its content changes. +5. On an update of the original: replace it in `sources/official/`, run the + converter, and review the diff of the generated files in the PR. CI fails + when the generated files do not match the original + (`tools/intake/