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
10 changes: 10 additions & 0 deletions .github/CODEOWNERS
Original file line number Diff line number Diff line change
Expand Up @@ -163,3 +163,13 @@
/toolchain/project-makefile.md @WDrijver
/toolchain/target-os-headers.md @WDrijver
/toolchain/vasm-assembler.md @WDrijver
/toolchain/best-practices/gcc-code-generation-for-68080.md @TuKo1982
/toolchain/pitfalls/calling-assembler-from-gcc.md @TuKo1982
/toolchain/pitfalls/float-settings-mismatch.md @TuKo1982
/toolchain/pitfalls/gcc-bbb-autoinc.md @TuKo1982
/toolchain/pitfalls/gcc-dbra-address-register-loop.md @TuKo1982
/toolchain/pitfalls/gcc-misc-traps.md @TuKo1982
/toolchain/pitfalls/gcc-stackswap-defer-pop.md @TuKo1982
/toolchain/pitfalls/libnix-and-header-traps.md @TuKo1982
/toolchain/pitfalls/vasm-68080-encoding-issues.md @TuKo1982
/toolchain/pitfalls/vasm-pc-relative-destination.md @TuKo1982
3 changes: 2 additions & 1 deletion core/pitfalls/pc-relative-destination.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ related:
- core/cpu-68080/prm/integer-unit.md
- core/cpu-68080/isa-notes-measured.md
- toolchain/vasm-assembler.md
- toolchain/pitfalls/vasm-pc-relative-destination.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 0 (rule 22), 7.2 and 9.4"
---
Expand All @@ -34,7 +35,7 @@ format, for example `(table.l,d0.w)` or memory indirect.
vasm with `-m68080` makes such destinations by itself: it rewrites an
absolute destination `move.x <src>,label` into `label(pc)` by default (also
for addq/subq, bchg/bclr/bset, eor, fmove and AMMX stores). The
toolchain side is described in [toolchain/vasm-assembler.md](../../toolchain/vasm-assembler.md).
toolchain side is described in [vasm-pc-relative-destination.md](../../toolchain/pitfalls/vasm-pc-relative-destination.md).

## Wrong

Expand Down
63 changes: 63 additions & 0 deletions toolchain/best-practices/gcc-code-generation-for-68080.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
---
title: Get the most from GCC 6.5 on the 68080
type: best-practice
owner: TuKo1982
status: draft
origin: ai-assisted
basis: [measured, source-code]
components: [toolchain, cpu-68080]
applies_to:
core: "Core 12841"
os: [any]
tags: [gcc, m68080, code-generation, portable, assembler, fpu]
related:
- toolchain/c-compiler-options.md
- toolchain/pitfalls/float-settings-mismatch.md
- toolchain/pitfalls/gcc-misc-traps.md
- core/best-practices/fixed-point-and-bitstreams.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 9.1 and 15.1"
---

## Goal

Speed with GCC 6.5 (ApolloCrossDev), and knowing where hand-written assembler
pays off.

## Technique

- **`-m68080`** (and `-mtune=68080`) makes GCC emit 080-only integer opcodes
(`addiw.l`, `cmpiw.l`, `dbra.l`; objdump shows them as `.short`). The
binary then crashes on 68020/030 and under emulators; no switch turns this
off.
- **FPU**: `-m68080` alone gives soft-float; add `-m68881` for FPU code
(see [float-settings-mismatch.md](../pitfalls/float-settings-mismatch.md)).
For full control, write FPU kernels in assembler.
- **Multiply-heavy loops**: GCC spills every 64-bit product. Plain 68020
assembler with the 64-bit sum in a register pair (add/addx) and unrolled
blocks with a computed entry beats it clearly.
- **Float-heavy C with `-std=c11`**: add `-fexcess-precision=fast`.
`-std=c11` alone forces `-fexcess-precision=standard`, which rounds every
float temporary through a Dn; in maggie.library that caused about 1320
spills of 12-byte values (SRC).
- **Libraries that may run on other CPUs**: check AttnFlags bit 10 (68080) in
LibInit, and build that object with `-m68020`.
- **Portable builds**: one code base can ship a 68020 build (`-m68020`, soft
float at compile and link time, assembler limited to 68020) and an 080
build.

## Evidence

| Variant | Measurement | Core | Test setup |
|---|---|---|---|
| MP3 decoder, 68020 build vs 080 build, on the 080 | 080 build 0–8 % faster | Core 12841 | Full decode (M) |
| `-m68080` vs `-m68020` code generation alone | About 2 % on an MP3 decoder | Core 12841 | Same |
| `-O3` vs `-O2` | No gain | Core 12841 | Same |
| Hand-written 68020 multiply loops vs GCC | Clearly faster | Core 12841 | MP3/FLAC kernels |

## When not to use

- Don't expect much from `-m68080` itself: about 2 % on its own. The large
gains came from hand-written or generated assembler kernels.
- A `-m68080` binary does not run on other CPUs or emulators: keep a 68020
build if the program must run elsewhere.
12 changes: 10 additions & 2 deletions toolchain/c-compiler-options.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,12 +32,16 @@ runtime (`-noixemul`). Link with `m68k-amigaos-gcc` and the same flags.
|---|---|
| `-O2` | Advanced optimization. Default and advised. |
| `-m68080` | Target the Apollo 68080. Default and advised. |
| `-m68881` | Use the FPU. Default and advised. |
| `-m68881` | Use the FPU. Default and advised. **Required for FPU code:** `-m68080` alone gives soft-float (see [float-settings-mismatch.md](pitfalls/float-settings-mismatch.md)) |
| `-ffast-math` | Faster, less accurate floating-point math |
| `-fomit-frame-pointer` | Frees the frame pointer register for general use |

Other optimization levels: `-O` (basic), `-O3` (aggressive), `-Os` (small
size).
size). `-O3` gave no gain over `-O2` in measured projects.

Don't add `-mtune=68060`: it stops GCC from using the 64-bit `muls.l` (FLAC
3x slower). See [gcc-misc-traps.md](pitfalls/gcc-misc-traps.md) and, for
more on code generation, [gcc-code-generation-for-68080.md](best-practices/gcc-code-generation-for-68080.md).

### C runtime

Expand Down Expand Up @@ -99,3 +103,7 @@ m68k-amigaos-gcc main.o -noixemul -O2 -m68080 -m68881 -ffast-math -fomit-frame-p
otherwise.
- DO use libnix (`-noixemul`) unless the project uses clib2.
- DON'T mix libnix and clib2 objects in one program.
- DON'T mix objects built with and without `-m68881`, and link with the same
flags you compile with.
- DO link with `-lm` when you use `sprintf` with libnix (see
[libnix-and-header-traps.md](pitfalls/libnix-and-header-traps.md)).
15 changes: 15 additions & 0 deletions toolchain/compiler-variants.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,13 +51,28 @@ Patches applied by GCC-6.50-Dev, from `Compilers/_archives/patches/`:

GCC-6.50-Stable applies `q2g-stable.patch` and the four patches by Morten.

### Known GCC bugs with pending fixes

| Bug | Fix | State on 2026-11-03 |
|---|---|---|
| bbb pass counts a post-increment twice | ApolloCrossDev pull request #5 | Open: see [gcc-bbb-autoinc.md](pitfalls/gcc-bbb-autoinc.md) |
| 16-bit loop counter in an address register runs away | ApolloCrossDev pull request #7 | Open: see [gcc-dbra-address-register-loop.md](pitfalls/gcc-dbra-address-register-loop.md) |

Until a fix is merged and you rebuild the toolchain, the matching pitfall
applies to every GCC 6.5 variant.

### 68080 instructions the compiler generates

According to the ApolloCrossDev README, the patched GCC 6.5 generates these
68080 instructions: `cmpiw.l`, `addiw.l`, `dbra.l`, `moviw.l`, `bcc.s`.
Planned, not yet supported: `mov3q`, `clr.q`, `move2.b`, `movs.b/w`,
`movz.b/w`.

`mov3q`, `clr.q`, `movs` and `movz` are LineA instructions that exist only
on cores 10280–10904 (official, see [core/cpu-68080/isa-notes-measured.md](../core/cpu-68080/isa-notes-measured.md)).
Code generated with them would not run on current cores; the fused pairs
(`moveq #0` + `move.b`, `move.w` + `ext.l`) give the same effect.

### GCC 13 and 15 (beta)

Scripts `GCC-13.1.sh`, `GCC-13.2.sh`, `GCC-13.3.sh` and `GCC-15.2.sh` build
Expand Down
69 changes: 69 additions & 0 deletions toolchain/pitfalls/calling-assembler-from-gcc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,69 @@
---
title: Calling assembler from GCC (registers, movem order, FPU ABI)
type: pitfall
owner: TuKo1982
status: draft
origin: ai-assisted
basis: [measured]
components: [toolchain, cpu-68080]
applies_to:
core: "any"
os: [any]
tags: [gcc, assembler, abi, registers, movem, fpu]
related:
- toolchain/vasm-assembler.md
- toolchain/c-compiler-options.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 9.3"
---

## Symptom

The machine hangs or C code misbehaves after calling an assembler routine.
It looks like a hardware bug: a clobbered a2 hung the machine three times
before it was found.

## Cause

- GCC expects d2–d7 and a2–a6 to be preserved by the callee.
- `movem.l` loads registers in register-mask order, not in the order you list
them. Loading arguments from the stack with one `movem.l` can put them in
the wrong registers.
- Which FPU registers a routine must preserve depends on the ABI you use, and
is easy to get wrong when it is not written down.

## Wrong

```asm
_routine:
movem.l 4(sp),a2/d1 ; loads d1 first, then a2: not "a2 then d1"
move.l (a2)+,d0 ; a2 clobbered and not restored
rts
```

## Right

```asm
_routine:
move.l a2,-(sp) ; save a callee-saved register
movea.l 8(sp),a2 ; load arguments with separate moves
move.l 12(sp),d1
move.l (a2)+,d0
movea.l (sp)+,a2
rts
```

- Document the FPU registers your routine keeps, for example "keeps
FP2–FP7/FPCR".

## Detection

Review every assembler routine called from C for writes to d2–d7/a2–a6
without a save and restore, and for `movem.l` used to load arguments.

## Evidence

| Claim | Source | Core | Method |
|---|---|---|---|
| A clobbered a2 hung the machine three times | (M) | any | Project debugging on the V4 |
| `movem.l` loads in register-mask order | (M) | any | Same |
72 changes: 72 additions & 0 deletions toolchain/pitfalls/float-settings-mismatch.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
---
title: Mixed float settings and hidden soft-float break programs and libraries
type: pitfall
owner: TuKo1982
status: draft
origin: ai-assisted
basis: [measured, source-code]
components: [toolchain]
applies_to:
core: "any"
os: [amigaos-3.9, amigaos-3.2]
tags: [gcc, soft-float, hard-float, m68881, libnix, printf, nostartfiles]
related:
- toolchain/c-compiler-options.md
- toolchain/best-practices/gcc-code-generation-for-68080.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 0 (rules 19 and 21) and 9.1-9.2"
- "WDrijver/gcc, gcc/config/m68k/m68k.c (branch gcc-6-base-amiga): no 680x0 CPU option sets FL_68881 for the AmigaOS target"
---

## Symptom

- `printf` prints garbage for doubles, while the calculations are right.
- A library built with `-nostartfiles` crashes (CHK error) on some inputs
only, for example when a ReplayGain value has to be computed.
- C code with floats runs slowly although it targets the 68080.

## Cause

- For the AmigaOS target, `-m68080` alone does **not** turn on the FPU: no
680x0 CPU option does (SRC). Hardware floating point comes from `-m68881`
(assumed correct; still to be validated with a test build). `-m68080`
alone compiles float work into calls such as `__floatsisf` (M).
- Objects built with different float settings, linked together (for example
`-m68080` objects with a libnix `printf` built for the other setting), pass
doubles in a way the other side does not expect.
- Any `double` or `exp()` in a `-nostartfiles` library pulls in `__divdf3`
and friends, which call mathieeedoub* libraries through a base that was
never opened.

## Wrong

```sh
m68k-amigaos-gcc -noixemul -O2 -m68080 -c lib.c # soft-float
m68k-amigaos-gcc -noixemul -O2 -m68080 -m68881 -c app.c # hard float
m68k-amigaos-gcc lib.o app.o -noixemul -o app # mixed
```

## Right

- Compile **and** link everything with the same flags, including `-m68881`:
the standard set is in [c-compiler-options.md](../c-compiler-options.md).
- Keep library code (`-nostartfiles`) integer (fixed point), and check its
objects for soft-float symbols.
- Write FPU kernels in assembler when you need full control over the FPU
code.

## Detection

- `m68k-amigaos-nm *.o | grep -E '__(add|sub|mul|div)[sd]f3|__floatsi|__fix'`
lists objects that use soft-float.
- Compile one float function with `-S` and check for `fmul`/`fadd` instead
of calls.

## Evidence

| Claim | Source | Core | Method |
|---|---|---|---|
| `-m68080` emits no FPU instructions | (M) | any | Project builds |
| No 680x0 CPU option sets the FPU flag for AmigaOS; `-m68881` sets hard float explicitly | (SRC) | any | GCC source, `m68k.c` |
| `-m68080` objects with libnix `printf` printed garbage doubles | (M) | any | MP3 project |
| Soft-float in a `-nostartfiles` library crashed with a CHK error | (M) | any | MP3 library, ReplayGain path |
70 changes: 70 additions & 0 deletions toolchain/pitfalls/gcc-bbb-autoinc.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
---
title: GCC 6.5 bbb pass counts a post-increment twice
type: pitfall
owner: TuKo1982
status: draft
origin: ai-assisted
basis: [measured, source-code]
components: [toolchain]
applies_to:
core: "any"
os: [any]
tags: [gcc, bbb, optimizer, autoincrement, miscompile]
related:
- toolchain/compiler-variants.md
- toolchain/c-compiler-options.md
sources:
- "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 9.2"
- "github.com/WDrijver/ApolloCrossDev pull request #5 (open on 2026-11-03)"
---

## Symptom

C code like `p + (p[0] == 'f' ? 3 : 2)` returns a pointer one byte too far,
at `-O2`.

## Cause

Bebbo's bbb optimizer pass (`-fbbb=i`, auto-increment) turns it into
`cmp.b #N,(a0)+` / Scc / `pea (3,a0,d0.w)`, which counts the post-increment
twice. The bug is in GCC 6.5 as built by ApolloCrossDev; the fix is
ApolloCrossDev pull request #5, still open on 2026-11-03.

## Wrong

```c
const char *skip(const char *p)
{
return p + (p[0] == 'f' ? 3 : 2); /* may be miscompiled at -O2 */
}
```

## Right

Until PR #5 is merged into the ApolloCrossDev build you use:

- check the generated code (see Detection), and
- rewrite the expression so the test and the addition are separate, and
check the generated code again.

```c
const char *skip(const char *p)
{
int n = 2;
if (p[0] == 'f')
n = 3;
return p + n;
}
```

## Detection

Compile with `-S` and grep the assembly for `cmp.b #N,(aN)+` followed by an
Scc.

## Evidence

| Claim | Source | Core | Method |
|---|---|---|---|
| Miscompile as described | (M) | any | Real project code, `-S` output |
| Fix in ApolloCrossDev PR #5 | (SRC) | any | Pull request |
Loading
Loading