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
44 changes: 44 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,29 @@
/.github/ @WDrijver @TuKo1982
/.markdownlint.jsonc @WDrijver @TuKo1982

/core/best-practices/align-copy-destination.md @TuKo1982
/core/best-practices/ammx-where-it-wins.md @TuKo1982
/core/best-practices/close-loops-with-dbra.md @TuKo1982
/core/best-practices/code-size-and-placement.md @TuKo1982
/core/best-practices/fixed-point-and-bitstreams.md @TuKo1982
/core/best-practices/fpu-schedule-by-completion-slot.md @TuKo1982
/core/best-practices/fpu-when-it-pays.md @TuKo1982
/core/best-practices/interleave-dependency-chains.md @TuKo1982
/core/best-practices/memory-access-patterns.md @TuKo1982
/core/best-practices/predicated-bcc-over-one-instruction.md @TuKo1982
/core/best-practices/use-fusable-pairs.md @TuKo1982
/core/cpu-68080/bank-prefix.md @TuKo1982
/core/cpu-68080/branches-and-prediction.md @TuKo1982
/core/cpu-68080/caches-and-memory.md @TuKo1982
/core/cpu-68080/core-at-a-glance.md @TuKo1982
/core/cpu-68080/core-bugs-by-revision.md @TuKo1982
/core/cpu-68080/fpu-performance-model.md @TuKo1982
/core/cpu-68080/index.md @WDrijver
/core/cpu-68080/isa-notes-measured.md @TuKo1982
/core/cpu-68080/measured-instruction-costs.md @TuKo1982
/core/cpu-68080/performance-counters.md @TuKo1982
/core/cpu-68080/pipeline-15-stages.md @TuKo1982
/core/cpu-68080/superscalar-issue.md @TuKo1982
/core/cpu-68080/prm/ammx-unit.md @WDrijver
/core/cpu-68080/prm/apollo-bit.md @WDrijver
/core/cpu-68080/prm/b-registers.md @WDrijver
Expand Down Expand Up @@ -105,8 +127,30 @@
/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/pitfalls/alternating-branch-mispredicted.md @TuKo1982
/core/pitfalls/alu-to-ea-bubble.md @TuKo1982
/core/pitfalls/ammx-pc-relative-source.md @TuKo1982
/core/pitfalls/ammx-upper-32-bits.md @TuKo1982
/core/pitfalls/bank-prefix-pitfalls.md @TuKo1982
/core/pitfalls/fpu-47-bit-context-save.md @TuKo1982
/core/pitfalls/fpu-broken-instructions.md @TuKo1982
/core/pitfalls/fpu-exceptions-never-trap.md @TuKo1982
/core/pitfalls/fpu-float-to-integer-conversion.md @TuKo1982
/core/pitfalls/fpu-precision-and-rounding.md @TuKo1982
/core/pitfalls/fused-copy-overlap.md @TuKo1982
/core/pitfalls/maggie-depth-test-colour-write.md @TuKo1982
/core/pitfalls/maggie-span-tail.md @TuKo1982
/core/pitfalls/maggie-span-usage.md @TuKo1982
/core/pitfalls/multiply-and-bfffo-block-both-pipes.md @TuKo1982
/core/pitfalls/pc-relative-destination.md @TuKo1982
/core/pitfalls/return-address-patching.md @TuKo1982
/core/pitfalls/self-modifying-code-and-caches.md @TuKo1982
/core/pitfalls/tex-does-not-match-prm.md @TuKo1982
/core/pitfalls/touch-misuse.md @TuKo1982
/core/saga-3d-maggie/index.md @WDrijver
/core/saga-3d-maggie/registers.md @TuKo1982
/core/saga-audio-arne/index.md @WDrijver
/core/saga-audio-arne/registers.md @TuKo1982
/core/saga-dma-anni/index.md @WDrijver
/core/saga-video-isabelle/index.md @WDrijver
/hardware/index.md @WDrijver
Expand Down
55 changes: 55 additions & 0 deletions core/best-practices/align-copy-destination.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
---
title: Align the destination of copies and fills
type: best-practice
owner: TuKo1982
status: draft
origin: ai-assisted
basis: [measured, official]
components: [cpu-68080]
applies_to:
core: "Core 12841"
os: [any]
tags: [68080, alignment, copy, blit, ammx, move16]
related:
- core/cpu-68080/caches-and-memory.md
- core/best-practices/ammx-where-it-wins.md
- core/pitfalls/fused-copy-overlap.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 0 (rules 12-13), 5.1 and 12"
---

## Goal

Bandwidth: about 3.2–3.5 bytes per cycle for copies, instead of about 1.8.

## Technique

- Align the **destination** to 8 bytes (quad). A misaligned source costs only
0–13 %; a misaligned destination 1.7–1.8x.
- Use aligned AMMX `load`/`store`, or fused quad moves
(`move.l (a0)+,(a1)+` twice), for the bulk. Handle the misaligned head and
tail separately.
- Use AMMX `storem` (masked store) for the edges: about 1.85 cycles per quad,
whatever the alignment.
- Remember that P96 `AllocBitMap` bases are only 4-byte aligned.

## Evidence

Copy of a 156 x 2464-byte shape (M, Core 12841):

| Variant | Measurement | Core | Test setup |
|---|---|---|---|
| `move.l` loop | 1.7–2.0 bytes/cycle | Core 12841 | CCC |
| AMMX `load`/`store`, misaligned | About 1.8 | Core 12841 | Same |
| AMMX `load`/`store`, 8-byte aligned | 3.2–3.5 | Core 12841 | Same |
| `move16`, 16-byte aligned | 3.1–3.2 | Core 12841 | Same |
| `move16`, misaligned | About 1.75 | Core 12841 | Same |

## When not to use

- Copies are memory-bound at about 3 bytes per cycle: beyond alignment,
optimising a blit copy gained only 3–10 %.
- `move16` is never faster than aligned AMMX or fused quad moves, so it is
not worth the extra alignment work.
- Tiny shapes: for rows of 64 bytes or less, plain 68k code wins (see
[ammx-where-it-wins.md](ammx-where-it-wins.md)).
63 changes: 63 additions & 0 deletions core/best-practices/ammx-where-it-wins.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
title: Use AMMX where it wins
type: best-practice
owner: TuKo1982
status: draft
origin: ai-assisted
basis: [core-developer, measured]
components: [cpu-68080, saga-video-isabelle]
applies_to:
core: "Core 12841"
os: [any]
tags: [68080, ammx, simd, blit, fill, p96]
related:
- core/cpu-68080/prm/ammx-unit.md
- core/best-practices/align-copy-destination.md
- core/pitfalls/ammx-pc-relative-source.md
- core/pitfalls/ammx-upper-32-bits.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 6, 11 and 12"
---

## Goal

Speed for fills, masked stores, pattern fills, format conversion and
decimation, where AMMX gives 1.8x to 11x.

## Technique

- Use aligned AMMX stores for fills, `storem` masked stores for template
(text) blits, and preload pattern rows into registers for pattern fills.
- Use AMMX for byte and word lanes: format conversion and decimation.
- Keep a plain 68k path for tiny shapes:
- EOR invert for rows of 64 bytes or less;
- a dedicated column path for widths of 8 pixels or less.
- Record the real call shapes before optimising: in real GUI FillRects, 86 %
of rows were 1–4 pixels wide (M).
- Prefer arithmetic over lookup tables: a table that wins in a hot benchmark
can lose when the real workload evicts it.
- Enable AMMX register saving with the Apollo bit: `ori #$800,sr` /
`andi #$f7ff,sr` (about 8 cycles for the pair, user mode). The OS
`V_EnableAMMX` pair cost 248 cycles (M).

## Evidence

| Variant | Measurement | Core | Test setup |
|---|---|---|---|
| Aligned fills | x1.84 | Core 12841 | CCC (M) |
| P96 FillRect, real workload | 1.80 M → 0.60 M cycles | Core 12841 | Aligned AMMX stores + 68k column path |
| P96 BlitTemplate (text) | 2.38 M → 1.59 M cycles | Core 12841 | AMMX `storem` |
| P96 BlitPattern | 307 K → 28 K cycles | Core 12841 | AMMX, two pattern rows preloaded |
| 1-pixel rows, generic vs column path | 14.6 → 2.25 cycles | Core 12841 | Same |
| 6 KB colour lookup table | 1.4x faster in the benchmark, 3–10 % slower on the real console | Core 12841 | Real workload |

## When not to use

- **Lanes are bytes or words only.** `pmul*` is 4 x 16x16 (high, low or bits
23..8); there is no 32-bit add and no MAC. AMMX does not suit 24/32-bit
audio maths: FLAC LPC, Rice decoding, or lossless MP3 synthesis (a 16-bit
window gave 46 dB SNR).
- There is one AMMX unit, so the floor is about IPC 1.0; the second pipe
accepts AMMX stores only.
- A 128-bit AMMX unit is in development (G, 2026-10-29); released cores
(12841) have the 64-bit unit.
66 changes: 66 additions & 0 deletions core/best-practices/close-loops-with-dbra.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
title: Close loops with dbra or subq + bne.s
type: best-practice
owner: TuKo1982
status: draft
origin: ai-assisted
basis: [core-developer, measured]
components: [cpu-68080]
applies_to:
core: "Core 12841"
os: [any]
tags: [68080, loops, dbra, branches, fusing]
related:
- core/cpu-68080/branches-and-prediction.md
- core/best-practices/code-size-and-placement.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 0 (rule 4), 2.4 and 5.3"
---

## Goal

Speed: loop overhead of 1 cycle instead of 3.

## Technique

Close loops with `dbra`, or with `subq.l #1,Dn` followed directly by
`bne.s`, which fuse into one dbra-like instruction. A `bne.w` is not an
accelerated branch.

```asm
loop:
; ... body ...
dbra d0,loop ; 16-bit counter

; or, for a 32-bit counter:
loop2:
; ... body ...
subq.l #1,d1
bne.s loop2 ; fuses with the subq
```

A counter that drives addressing can live in An, so it does not hit the
ALU-to-EA bubble:

```asm
loop3:
; ... body ...
subq.l #1,a6 ; EA unit, no flags
move.l a6,d0 ; sets N/Z, no write back
bne.s loop3
```

## Evidence

| Variant | Measurement | Core | Test setup |
|---|---|---|---|
| Loop closed with a `bne.w` that does not fuse | 3 cycles overhead | Core 12841 | CCC counter (M) |
| Loop closed with `dbra` or `subq.l` + `bne.s` | 1 cycle overhead | Core 12841 | Same |

`subq.l #1,dn` + `bne.s/.s+/.w` fuses; `subq` + `bpl` does not (M). Gunnar:
"DBRA is fast and nearly free" (G).

## When not to use

- Very short loops (1–4 turns) are expensive whatever the closing branch: one
turn cost about 12 cycles, each extra turn 3 (M). Special-case them.
66 changes: 66 additions & 0 deletions core/best-practices/code-size-and-placement.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,66 @@
---
title: Keep code small and hot code together; don't unroll by default
type: best-practice
owner: TuKo1982
status: draft
origin: ai-assisted
basis: [core-developer, measured]
components: [cpu-68080, toolchain]
applies_to:
core: "Core 12841"
os: [any]
tags: [68080, icache, unrolling, code-size, link-order, placement]
related:
- core/cpu-68080/core-at-a-glance.md
- core/best-practices/close-loops-with-dbra.md
- core/cpu-68080/prm/optimizing.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 0 (rules 14-15), 5.3 and 12"
- "Gunnar (core developer), statements on unrolling and padding, 2026-10-29 and 2026-10-30"
---

## Goal

Speed of the whole program: hot code that stays in the I-cache. Fat code
evicts other code, and reloading it costs hundreds of cycles.

## Technique

- **Don't unroll by default** (G): "DBRA is fast and nearly free." "If you
can loop 512 times, loop 512 times." "10 lines made into 6 KB = big
mistake."
- **Share code** instead of duplicating variants.
- **Keep hot code contiguous.** Link the assembler routine right after the C
code that calls it, and put cold objects first. Profile builds must keep
the release link order: use `-fno-toplevel-reorder` and the same object
order.
- **Read memory in address order through `(An)+`** (G). Re-lay tables in the
order you read them instead of keeping a C layout; `d16(An)` everywhere
makes code fat.
- **Don't pad code to move it in the I-cache** (G: "a terrible idea"). Tune
the code for size; if it still does not fit, raise it with the Apollo team
(for example more I-cache ways in the release core).

## Evidence

| Variant | Measurement | Core | Test setup |
|---|---|---|---|
| Six IMDCT copies (12.9 KB) | Baseline | Core 12841 | Full MP3 decode, CCC (M) |
| One shared transform + 3 short windows (3.8 KB) | Full decode 0.2–0.6 % faster | Core 12841 | Same |
| Profile build with default link order | Synthesis 10.1 % of time | Core 12841 | Same |
| Profile build with release link order | Synthesis 7.3 % of time | Core 12841 | Same |
| Same binary, different load addresses | Up to about 5 % apart (41.6–49.9 cycles on one loop) | Core 12841 | Same |

- Unrolled variants that won alone (an 8 KB FPU window, a 15-row integer
window) lost in the full decoder (M).
- Shrinking one 2.4 KB routine moved the code linked after it and cost 1.7 %
on the full decode, while the routine itself got 2 % faster (M).

## When not to use

- A short scheduled tail can still win: turning a **multiply-bound**
scheduled tail into a dbra loop cost about 30 % per element (14 vs 11
cycles per sample). "Never unroll" holds for duplicated copies.
- Measure any unrolling in the full program, never in a microbenchmark.
- Core 12841 has an I-cache with few ways; 1-way builds alias code bigger
than the cache by design. Note the core build with every measurement.
68 changes: 68 additions & 0 deletions core/best-practices/fixed-point-and-bitstreams.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
title: Fixed-point multiplies and bitstream decoding on the 68080
type: best-practice
owner: TuKo1982
status: draft
origin: ai-assisted
basis: [measured]
components: [cpu-68080]
applies_to:
core: "Core 12841"
os: [any]
tags: [68080, fixed-point, muls, bfextu, bfffo, huffman, codecs]
related:
- core/cpu-68080/measured-instruction-costs.md
- core/pitfalls/multiply-and-bfffo-block-both-pipes.md
- core/pitfalls/alu-to-ea-bubble.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 10 and 11"
---

## Goal

Speed in codecs (MP3, FLAC) and other fixed-point or bitstream code.

## Technique

### Fixed point

- Keep only the high longword of a 64-bit `muls.l` (Q30/Q31 coefficients).
- For rounding, split a constant c = m + c' with |c'| ≤ 0.5 in Q32. Rounding
then costs `add.l lo,lo` / `addx.l d7,hi` (2 instructions instead of 4) and
stays exact.
- Keep 64-bit sums in a register pair with `add`/`addx`. Plain 68020
assembler with unrolled blocks and a computed entry beat GCC, which spills
every 64-bit product in multiply-heavy loops.

### Bitstreams

- Use `bfextu` at a bit position, and `bfffo` for unary codes.
- Memory bitfields cost the same as register bitfields on the 68080. Keeping
a 32-bit window in a register was slower.
- `bfextu` width 0 means 32: guard it.
- Put the sign in the table row index: it removes a dependent smi/eor/sub
chain.
- Read table fields as bytes with `moveq #0` + `move.b` (a fused zero-extending
load), and write both outputs adjacent (a fused quad store).

## Evidence

| Variant | Measurement | Core | Test setup |
|---|---|---|---|
| Huffman pair, sign handled with smi/eor/sub | 34.6 cycles per pair | Core 12841 | CCC, MP3 decode (M) |
| Sign in the table row index | 22 cycles per pair | Core 12841 | Same |
| Plus byte fields with fused movz and adjacent outputs | 15.8 cycles per pair | Core 12841 | Same |
| A 256-byte lookup table instead of `bfffo` for Rice unary codes | Slower | Core 12841 | FLAC decode (M) |

Results in context: MP3 decode went from 23.2 % to 15.7 % of real time at
258 kbps, FLAC 96/24 decode from 30.3 % to about 12–14 % CPU (M, V4 at
99 MHz).

## When not to use

- `bfffo` costs 3 cycles and blocks both pipes; `bfextu` runs in pipe 1
only. In an offset chain they add latency (4 and 6 cycles): see
[multiply-and-bfffo-block-both-pipes.md](../pitfalls/multiply-and-bfffo-block-both-pipes.md).
- A bit position that feeds the next address hits the ALU-to-EA bubble:
`bfextu` → `move.b 2(a1,d5*4)` → `add` took 7.4 cycles per link, 9.1 when
the bit position advances.
Loading
Loading