Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 89 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions .github/workflows/kb-checks.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
21 changes: 15 additions & 6 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Expand Down Expand Up @@ -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/<file>`
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/<script> --check`).

When the PR states that the Markdown becomes leading instead, leave out
`generated_from` and remove the original from `sources/official/`. From then
Expand Down
51 changes: 37 additions & 14 deletions core/cpu-68080/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,36 +8,59 @@ components: [cpu-68080]
applies_to:
core: "any"
os: [any]
related:
- core/cpu-68080/prm/index.md
sources:
- "Not yet collected"
- "Apollo 68080 Programmer's Reference Manual, AC68080PRM.odt (update okt 2026)"
---

## Summary

The Apollo 68080 CPU, successor of the Motorola 68000 family, with the AMMX SIMD extension.

**This folder has no content yet.** If your task depends on it, tell the
user that the knowledge base does not cover the 68080 CPU yet. Do not fill the
gap with classic Amiga or 68060 knowledge.
The Apollo 68080 CPU, successor of the Motorola 68000 family, with the AMMX
SIMD extension. Its reference is the 68080 Programmer's Reference Manual,
converted in [prm/](prm/index.md).

## Details

### Planned files
### Where to look

| Topic | File |
|---|---|
| Any 68080 instruction, by mnemonic | [prm/index.md](prm/index.md) |
| Registers (D, A, B, E, FP) | [prm/programming-model.md](prm/programming-model.md) |
| Integer unit, BANK prefix, 3 operands | [prm/integer-unit.md](prm/integer-unit.md) |
| AMMX SIMD unit and its instruction format | [prm/ammx-unit.md](prm/ammx-unit.md), [prm/ammx/ammx-format.md](prm/ammx/ammx-format.md) |
| Floating point unit | [prm/fpu-unit.md](prm/fpu-unit.md) |
| Apollo bit (SR bit 11), LineA instructions | [prm/apollo-bit.md](prm/apollo-bit.md) |
| Superscalar pipes, fusing, pipeline | [prm/superscalar.md](prm/superscalar.md), [prm/instruction-fusing.md](prm/instruction-fusing.md), [prm/pipeline.md](prm/pipeline.md) |
| Cycle counts, benchmark, optimizing | [prm/instruction-timing.md](prm/instruction-timing.md), [prm/instruction-efficiency.md](prm/instruction-efficiency.md), [prm/optimizing.md](prm/optimizing.md) |
| Caches, bus, trace | [prm/specs.md](prm/specs.md), [prm/trace.md](prm/trace.md) |

The files in `prm/` are generated from the original manual in
`sources/official/` and are never edited by hand. Other 68080 content goes
next to `prm/` in this folder.

### Not covered yet

- `isa.md`: instruction set additions beyond the 68060
- `ammx.md`: AMMX SIMD instructions and registers
- `pipeline-and-timing.md`: pipeline, cycle counts, pairing rules
- `differences-from-68060.md`: what a 68060 programmer would wrongly assume
- A full 68080 instruction set reference: the manual covers only what the
68080 adds to the 68000 family. For the classic instructions, the Motorola
manuals apply.
- `differences-from-68060.md`: what a 68060 programmer would wrongly assume,
collected in one place.

### For contributors

Check the ApolloCrossDev `Docs/` folder (`AC68080PRM.pdf`, `AMMX/`, `FPU/`, `Integer/`) and the 68080 coding pages on apollo-core.com. Start new files from `templates/files/reference.md`.
Check the ApolloCrossDev `Docs/` folder (`AMMX/`, `FPU/`, `Integer/`) and the
68080 coding pages on apollo-core.com. Start new files from
`templates/files/reference.md`.

## Differences from AmigaOS / AROS / 68060

No content yet.
Each file in `prm/` states its differences from the 68000–68060.

## Do / Don't

- DO look up a 68080 instruction in [prm/index.md](prm/index.md) before
using it.
- DON'T invent register addresses, bit meanings or instruction behavior for
the 68080 CPU. Say that the knowledge base does not cover it.
the 68080 CPU. If the knowledge base does not cover it, say so.
64 changes: 64 additions & 0 deletions core/cpu-68080/prm/ammx-unit.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
title: "68080 AMMX unit"
type: reference
owner: WDrijver
status: reviewed
origin: official
components: [cpu-68080]
applies_to:
core: "any"
os: [any]
tags: [68080, ammx, simd, vector]
related:
- core/cpu-68080/prm/index.md
- core/cpu-68080/prm/ammx/ammx-format.md
sources:
- "Apollo 68080 Programmer's Reference Manual, AC68080PRM.odt (update okt 2026)"
generated_from: sources/official/AC68080PRM.odt
---

<!-- GENERATED by tools/intake/prm68080.py from sources/official/AC68080PRM.odt. Do not edit: change the original and regenerate. -->

## Summary

AMMX is the 68080's 64-bit SIMD unit: a line-F coprocessor with id 7, 3-operand, using D0–D7, E0–E23, A0–A7 and B0–B7, without changing the condition codes.

## Details

- Ammx stands for Apollo MultiMedia eXtension. It is an integrated coprocessor with id=7. It handles 64 bit instructions.
- It has access to 32 64bit wide data registers, D0..7 & E0..23. The same as the integer unit can use. The data can be a multiple bytes or words that are processed in one go. So called Single Instruction Multiple Data or SIMD.
- This division of 64bits into lets say 2 x 32 or 8 x 8 parts is called vector.
- Ammx instructions are normally 3 operand, unlike the 2 operand 68k.
- It can use all the address registers, A0..7 & B0..7.
- Ammx does not change the condition-codes at all. Pcmp sets the condition in the destination register. Bsel can be used to make conditional changes with that.
- See page 56 of the original ([ammx/pcmpccb.md](ammx/pcmpccb.md)) for this example with register values.

```asm
pcmpgtb d0,d1,d2 ; d2 = (d1>d0)
bsel d1,d2,e0 ; if (d1>d0) then replace e0 with d1
```

- or storeilm d1,d2,(a0) ; if (d1&lt;=d0) then write d1
- Ammx format: page 42 of the original ([ammx/ammx-format.md](ammx/ammx-format.md))

### Vector handling by type

Which element type each instruction uses, source or destination match. The original shows each list next to its heading.

| Vector type | Instructions |
|---|---|
| Vector Bit (64x bit) | bsel, minterm, pand, pandn, peor, por |
| Vector Byte (8x byte) | bfly, c2p, packuswb, padd, pavg, pcmpccb, pmaxb, pminb, psub, storec, storeilm, storem, storem3, vperm |
| Vector Word (4x word) | bfly, pack3216, packuswb, padd, pcmpccw, pmaxw, pminw, pmul88, pmulh, pmull, psub, storem3, trans, unpack1632 |
| Vector Long (2x long) | pack3216, pmula, storem3, unpack1632 |
| Vector Quad (1 quad) | c2p, load, loadi, lsdq, store, storec, storei, storeilm, storem, storem3, vperm |

- Note: tex & rex are not vector operations.

## Differences from AmigaOS / AROS / 68060

- The 68000–68060 have no SIMD unit. AMMX instructions do not change the condition codes; PCMPcc writes its result to a register.

## Do / Don't

- DON'T branch on condition codes after AMMX instructions: use PCMPcc with BSEL, PAND/PANDN or STOREILM.
81 changes: 81 additions & 0 deletions core/cpu-68080/prm/ammx/ammx-format.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
---
title: "AMMX: Apollo Multi Media eXtension"
type: reference
owner: WDrijver
status: reviewed
origin: official
components: [cpu-68080]
applies_to:
core: "any"
os: [any]
tags: [68080, ammx, ammx]
related:
- core/cpu-68080/prm/index.md
sources:
- "Apollo 68080 Programmer's Reference Manual, AC68080PRM.odt (update okt 2026)"
generated_from: sources/official/AC68080PRM.odt
---

<!-- GENERATED by tools/intake/prm68080.py from sources/official/AC68080PRM.odt. Do not edit: change the original and regenerate. -->

## Summary

**AMMX** (Apollo Multi Media eXtension).

## Details

| Field | Value |
|---|---|
| Operation | handles 64 bit instructions |
| Syntax | `instruction <vea>,b,d`<br>where d is the destination |
| Description | AMMX is a line-F coprocessor with id=7. It handles 64 bit. So some say Apply More Magic eXtension. |
| Condition codes | not affected |

### Encoding

| Word | Bits | Content |
|---|---|---|
| 1 | 15–9 | `1111111` |
| 1 | 8 | A |
| 1 | 7 | B |
| 1 | 6 | D |
| 1 | 5–3 | Mode |
| 1 | 2–0 | Register |
| 2 | 15–12 | b |
| 2 | 11–8 | d |
| 2 | 7 | M |
| 2 | 6–0 | Opcode |

- B is msb of b. D is msb of d.
- b & d are data-registers. d0..7 / e0..23
- \*M=1 write to memory (b,d,vea) else default mode 0= to register (vea,b,d) *(grayed out in the original)*
- vector effective address or &lt;vea&gt; = A, Mode, Register

| A=0 | Mode | Register | A=1 |
|---|---|---|---|
| Data register Dn | 000 | Register | Data register E8..15 |
| Data register E0..7 | 001 | Register | Data register E16..23 |
| Address indirect (An) | 010 | Register | (Bn) |
| Address post inc (An)+ | 011 | Register | (Bn)+ |
| Addresss pre decr -(An) | 100 | Register | -(Bn) |
| d16(An) | 101 | Register | d16(Bn) |
| d8(An,Xn.w x Size) | 110 | Register | d8(Bn,Xn.w x Size) |
| d16(pc) | 111 | 010 | |
| d8(pc,Xn.w x Size) | 111 | 011 | |
| Abs.w | 111 | 000 | |
| Abs.l | 111 | 001 | |
| #imm.Q | 111 | 100 | #imm.W |
| – vperm – | 111 | 111 | |

### Notes

- #imm.W is repeated. $1234.w expands to Quad $1234123412341234.
- \* future *(grayed out in the original)*

## Differences from AmigaOS / AROS / 68060

- The 68000–68060 have no AMMX. It is new on the 68080.

## Do / Don't

- No rules beyond the details above.
Loading
Loading