From f87867ddd0a68f90e8e645b130e1bcf5415232a4 Mon Sep 17 00:00:00 2001 From: Willem Drijver Date: Tue, 3 Nov 2026 15:06:56 +0300 Subject: [PATCH] Toolchain content from TuKo1982's 68080 optimisation guide Split section 9 of the guide into toolchain/: vasm and GCC pitfalls, libnix traps, calling assembler from GCC, and a best practice on GCC code generation for the 68080. Warn about vasm 2.0f's PC-relative destinations in vasm-assembler.md (option b), explain why -m68881 is needed for FPU code, list the open GCC fixes (ApolloCrossDev PR #5 and #7), and note that the planned LineA code generation would not run on current cores. Co-Authored-By: Claude Opus 5.5 --- .github/CODEOWNERS | 10 +++ core/pitfalls/pc-relative-destination.md | 3 +- .../gcc-code-generation-for-68080.md | 63 ++++++++++++++ toolchain/c-compiler-options.md | 12 ++- toolchain/compiler-variants.md | 15 ++++ .../pitfalls/calling-assembler-from-gcc.md | 69 ++++++++++++++++ toolchain/pitfalls/float-settings-mismatch.md | 72 ++++++++++++++++ toolchain/pitfalls/gcc-bbb-autoinc.md | 70 ++++++++++++++++ .../gcc-dbra-address-register-loop.md | 68 +++++++++++++++ toolchain/pitfalls/gcc-misc-traps.md | 63 ++++++++++++++ toolchain/pitfalls/gcc-stackswap-defer-pop.md | 57 +++++++++++++ toolchain/pitfalls/libnix-and-header-traps.md | 69 ++++++++++++++++ .../pitfalls/vasm-68080-encoding-issues.md | 82 +++++++++++++++++++ .../pitfalls/vasm-pc-relative-destination.md | 74 +++++++++++++++++ toolchain/vasm-assembler.md | 22 ++++- 15 files changed, 744 insertions(+), 5 deletions(-) create mode 100644 toolchain/best-practices/gcc-code-generation-for-68080.md create mode 100644 toolchain/pitfalls/calling-assembler-from-gcc.md create mode 100644 toolchain/pitfalls/float-settings-mismatch.md create mode 100644 toolchain/pitfalls/gcc-bbb-autoinc.md create mode 100644 toolchain/pitfalls/gcc-dbra-address-register-loop.md create mode 100644 toolchain/pitfalls/gcc-misc-traps.md create mode 100644 toolchain/pitfalls/gcc-stackswap-defer-pop.md create mode 100644 toolchain/pitfalls/libnix-and-header-traps.md create mode 100644 toolchain/pitfalls/vasm-68080-encoding-issues.md create mode 100644 toolchain/pitfalls/vasm-pc-relative-destination.md diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 3117549..c774ccd 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -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 diff --git a/core/pitfalls/pc-relative-destination.md b/core/pitfalls/pc-relative-destination.md index 454d722..c2b03d2 100644 --- a/core/pitfalls/pc-relative-destination.md +++ b/core/pitfalls/pc-relative-destination.md @@ -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" --- @@ -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 ,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 diff --git a/toolchain/best-practices/gcc-code-generation-for-68080.md b/toolchain/best-practices/gcc-code-generation-for-68080.md new file mode 100644 index 0000000..5346692 --- /dev/null +++ b/toolchain/best-practices/gcc-code-generation-for-68080.md @@ -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. diff --git a/toolchain/c-compiler-options.md b/toolchain/c-compiler-options.md index 8d58f6b..40807f4 100644 --- a/toolchain/c-compiler-options.md +++ b/toolchain/c-compiler-options.md @@ -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 @@ -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)). diff --git a/toolchain/compiler-variants.md b/toolchain/compiler-variants.md index 5935ad0..cab2103 100644 --- a/toolchain/compiler-variants.md +++ b/toolchain/compiler-variants.md @@ -51,6 +51,16 @@ 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 @@ -58,6 +68,11 @@ According to the ApolloCrossDev README, the patched GCC 6.5 generates these 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 diff --git a/toolchain/pitfalls/calling-assembler-from-gcc.md b/toolchain/pitfalls/calling-assembler-from-gcc.md new file mode 100644 index 0000000..660f565 --- /dev/null +++ b/toolchain/pitfalls/calling-assembler-from-gcc.md @@ -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 | diff --git a/toolchain/pitfalls/float-settings-mismatch.md b/toolchain/pitfalls/float-settings-mismatch.md new file mode 100644 index 0000000..4f48462 --- /dev/null +++ b/toolchain/pitfalls/float-settings-mismatch.md @@ -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 | diff --git a/toolchain/pitfalls/gcc-bbb-autoinc.md b/toolchain/pitfalls/gcc-bbb-autoinc.md new file mode 100644 index 0000000..a85733a --- /dev/null +++ b/toolchain/pitfalls/gcc-bbb-autoinc.md @@ -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 | diff --git a/toolchain/pitfalls/gcc-dbra-address-register-loop.md b/toolchain/pitfalls/gcc-dbra-address-register-loop.md new file mode 100644 index 0000000..fc1bc1e --- /dev/null +++ b/toolchain/pitfalls/gcc-dbra-address-register-loop.md @@ -0,0 +1,68 @@ +--- +title: GCC 6.5 16-bit loop counter in an address register runs away +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured, source-code] +components: [toolchain] +applies_to: + core: "any" + os: [any] +tags: [gcc, ivopts, dbra, loop, miscompile, address-register] +related: + - toolchain/compiler-variants.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 9.2" + - "github.com/WDrijver/ApolloCrossDev pull request #7 and github.com/WDrijver/gcc issue #1 (open on 2026-11-03)" +--- + +## Symptom + +A loop with a 16-bit counter runs about 4 billion times instead of the +intended count, at `-O2`. It always shows on real Fast RAM; under emulators +only when the low word of the pointer is `$8000` or higher. + +## Cause + +GCC's m68k patterns `*dbne_hi`/`*dbge_hi` emit `subq.w #1,An; cmp.w #-1,An`, +which is a 32-bit operation on an address register. After ivopts builds a +UWORD counter from a pointer, the high word never reaches −1. The bug is +GCC's, not the core's: the same loop also runs away on a real 68060. + +The fix (`tst.w An; subq.w #1,An; jne`, also faster) is ApolloCrossDev pull +request #7, still open on 2026-11-03. The pattern is latent in GCC 15.2 too +(WDrijver/gcc issue #1). + +## Wrong + +A UWORD loop counter that ivopts derives from a pointer can be compiled into +this pattern: + +```asm +.loop: + ; ... body ... + subq.w #1,a2 ; 16-bit decrement of an address register + cmp.w #-1,a2 ; compares all 32 bits (sign-extended) + bne.s .loop ; high word is never -1: runs about 4 G times +``` + +## Right + +Until PR #7 is in your ApolloCrossDev build: + +- compile with `-fno-ivopts` (3–6 % slower on the tested code), or +- mark the affected function `__attribute__((noinline))`. + +## Detection + +Compile with `-S` and look for `subq.w #1,aN` followed by `cmp.w #-1,aN`. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| Loop runs away on Fast RAM | (M) | any | Real project, V4 | +| `tst.w An` tests only bits 15–0; `subq` to An leaves the CCR alone | (M) | Core 12841 | Self-checking test tstan, 252 checks x 3 passes; 0 failures on the 080 and on a real 68060 | +| The old GCC loop also runs away on a real 68060 | (M) | 68060 | Same test | +| Fix in ApolloCrossDev PR #7 | (SRC) | any | Pull request | diff --git a/toolchain/pitfalls/gcc-misc-traps.md b/toolchain/pitfalls/gcc-misc-traps.md new file mode 100644 index 0000000..e275fd5 --- /dev/null +++ b/toolchain/pitfalls/gcc-misc-traps.md @@ -0,0 +1,63 @@ +--- +title: Smaller GCC 6.5 traps (-mtune=68060, NULL writes, -O3) +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured] +components: [toolchain] +applies_to: + core: "any" + os: [any] +tags: [gcc, mtune, muls, null-pointer, trap, O3] +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 9.1 and 9.2" +--- + +## Symptom + +- Multiply-heavy C code (FLAC) runs 3 times slower than expected. +- A deliberate write to address 0 ends in a guru 80000027 instead of the + intended effect. +- `-O3` builds are not faster than `-O2`. + +## Cause + +- `-mtune=68060` stops GCC from using the 64-bit `muls.l`, because the 68060 + emulates it in software. The 68080 runs it in hardware. +- GCC treats `*(ULONG *)0` as undefined behaviour and turns it into + `trap #7` (guru 80000027). +- `-O3` gave nothing over `-O2` in the measured projects. + +## Wrong + +```sh +m68k-amigaos-gcc -O2 -m68080 -mtune=68060 ... # FLAC 3x slower +``` + +```c +*(ULONG *)0 = value; /* becomes trap #7 */ +``` + +## Right + +- Don't tune for the 68060. Use the standard flags (`-m68080`, no `-mtune`). +- Make the NULL access in assembler, and compile with + `-fno-delete-null-pointer-checks`. +- Stay at `-O2` unless a measurement shows otherwise. + +## Detection + +Check Makefiles for `-mtune=68060` and `-O3`. Grep `-S` output for +`trap #7`. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| `-mtune=68060`: FLAC 3x slower | (M) | Core 12841 | FLAC decode | +| `*(ULONG*)0` becomes `trap #7` | (M) | any | `-S` output | +| `-O3` no gain over `-O2` | (M) | Core 12841 | MP3/FLAC projects | diff --git a/toolchain/pitfalls/gcc-stackswap-defer-pop.md b/toolchain/pitfalls/gcc-stackswap-defer-pop.md new file mode 100644 index 0000000..637dd13 --- /dev/null +++ b/toolchain/pitfalls/gcc-stackswap-defer-pop.md @@ -0,0 +1,57 @@ +--- +title: GCC pops call arguments after StackSwap +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured] +components: [toolchain] +applies_to: + core: "any" + os: [amigaos-3.9, amigaos-3.2] +tags: [gcc, stackswap, stack, defer-pop, crash] +related: + - toolchain/c-compiler-options.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 0 (rule 20) and 9.2" +--- + +## Symptom + +A program or library that calls `StackSwap()` crashes callers with small +stacks. The caller's stack is corrupted after the call returns. + +## Cause + +GCC defers popping call arguments and may emit `lea N(sp),sp` *after* the +code has swapped the stack back. It then adjusts the caller's stack instead +of the private one. This crashed an MP3 library for callers with small +stacks. + +## Wrong + +```c +StackSwap(&sss); +result = decode(frame, len); /* arguments popped later ... */ +StackSwap(&sss); /* ... after this swap back */ +``` + +## Right + +Build every file that uses `StackSwap()` with `-fno-defer-pop` (or with a +frame pointer), and read the generated code around the swap. + +```sh +m68k-amigaos-gcc -noixemul -O2 -m68080 -m68881 -fno-defer-pop -c player.c +``` + +## Detection + +Compile with `-S` and check that no `lea N(sp),sp` or `addq.l #N,sp` follows +the second `StackSwap` call for arguments pushed before it. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| `lea N(sp),sp` emitted after the swap back; crashes with small caller stacks | (M) | any | MP3 library, AmigaOS 3.9 | diff --git a/toolchain/pitfalls/libnix-and-header-traps.md b/toolchain/pitfalls/libnix-and-header-traps.md new file mode 100644 index 0000000..badf3e8 --- /dev/null +++ b/toolchain/pitfalls/libnix-and-header-traps.md @@ -0,0 +1,69 @@ +--- +title: libnix and header traps +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured] +components: [toolchain] +applies_to: + core: "any" + os: [amigaos-3.9, amigaos-3.2] +tags: [libnix, sprintf, stdio, stack, headers, mui, stdint] +related: + - toolchain/c-compiler-options.md + - toolchain/target-os-headers.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 9.5" +--- + +## Symptom + +- `sprintf` prints 16-bit numbers for `%d` and returns no length. +- GCC 6 fails on `stdint.h` from an SDK. +- A MUI 3.8 system refuses to open muimaster.library. +- Output from worker processes is garbled; a requested stack size is + ignored; `memset`/`memcmp` are slow; `%p` prints wrongly. + +## Cause + +| Trap | Cause | +|---|---| +| `sprintf` behaves like RawDoFmt | libnix `sprintf` lives in `libm.a`. Without `-lm`, amiga.lib's `sprintf` (RawDoFmt: `%d` = 16 bits, no length returned) is linked silently | +| SDK `stdint.h` breaks GCC 6 | The SDK's header conflicts with GCC 6's own | +| muimaster.library does not open | GCC 6 `mui.h` sets `MUIMASTER_VMIN` to 20 (MUI 4) | +| Worker process output | libnix stdio is not safe from worker processes | +| Stack size ignored | libnix does not honour `__stack` | +| Slow `memset`/`memcmp` | libnix works byte by byte | +| `%p` | Misprints in libnix | + +## Wrong + +```sh +m68k-amigaos-gcc main.o -noixemul -o app # amiga.lib sprintf +m68k-amigaos-gcc -I sdk/include -c main.c # SDK stdint.h first +``` + +## Right + +```sh +m68k-amigaos-gcc main.o -noixemul -lm -o app # libnix sprintf +m68k-amigaos-gcc -idirafter sdk/include -c main.c # SDK headers last +``` + +- Open muimaster.library with version 19 for MUI 3.8. +- Do stdio from the main process only. +- Swap to your own stack with `StackSwap()` when you need a larger one (see + [gcc-stackswap-defer-pop.md](gcc-stackswap-defer-pop.md)). +- Write your own `memset`/`memcmp` for hot paths. + +## Detection + +Check the link line for `-lm`, the include order for SDK folders, and the +muimaster version you open. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| All items in the table | (M) | any | Project builds on AmigaOS 3.9 | diff --git a/toolchain/pitfalls/vasm-68080-encoding-issues.md b/toolchain/pitfalls/vasm-68080-encoding-issues.md new file mode 100644 index 0000000..252b1dd --- /dev/null +++ b/toolchain/pitfalls/vasm-68080-encoding-issues.md @@ -0,0 +1,82 @@ +--- +title: vasm 68080 encodings that are wrong or missing +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured, source-code] +components: [toolchain, cpu-68080] +applies_to: + core: "Core 12841" + os: [any] +tags: [vasm, bank, ammx, encoding, branches, listing] +related: + - core/pitfalls/bank-prefix-pitfalls.md + - core/pitfalls/ammx-pc-relative-source.md + - core/pitfalls/tex-does-not-match-prm.md + - toolchain/vasm-assembler.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 9.4" + - "ApolloCrossDev Compilers/_archives/vasm/vasm.tar.tar: vasm 2.0f" +--- + +## Symptom + +Assembled 68080 code does something else than the source says, or the +binary differs from what another assembler (Devpac, ASM1) produces, without +any error or warning from vasm. + +## Cause + +vasm 2.0f/2.0g (ApolloCrossDev ships 2.0f) handles these 68080 cases +differently from the core: + +| Source | What vasm does | Effect | +|---|---|---| +| BANK single operand (`tst e6`, `clr e2`) | Sets AA only | Uses the plain Dn: `tst e6` tests d6 | +| `add.l #imm,En` | Sets BB only (`$7101`) | Writes plain Dn + imm into En | +| `add.l b1,d0` | Emits `$71F1`, a BANK word with SS ≠ 0 | Illegal instruction | +| `move.l a0,b1` | Rejects it | Not a supported form anyway | +| AMMX PC-relative source (`load .k(pc),d0`) | Counts the displacement from the third word; the core counts from the second | Reads 2 bytes early | +| An out-of-range `.s` branch with `-m68080` | Silently emits the 080-only `.s+` | Runs only on the 68080 | +| abs, min, max, andn | Assembles them | They do nothing on the core and raise no exception | +| TEX | No syntax in 2.0g | Needs `dc.w` | +| movz2, moveh, some `touch (An,Xn)` forms | Not available | Needs `dc.w` | +| `load` at the top of a file | Taken as a directive | Assembly error or wrong code | + +Without `-no-opt`, vasm also emits `and/or/sub #imm` instead of +`andi/ori/subi`, rewrites branch sizes and turns `move.l #imm` into `moveq`, +so binaries are not byte-identical to Devpac builds. + +## Wrong + +```asm + tst.l e6 ; assembles as tst.l d6 + load .k(pc),d0 ; reads .k - 2 +``` + +## Right + +- Hand-encode BANK single-operand and `#imm,Rn` forms with AA = BB (see + [bank-prefix-pitfalls.md](../../core/pitfalls/bank-prefix-pitfalls.md)). +- Load AMMX data through `lea .k(pc),An` + `load (An),Dn`. +- Don't use abs/min/max/andn. +- Use `-no-opt` for byte-exact round trips and for CPU tests. +- Decode every hand-encoded `dc.w` back with an 080-aware disassembler and + check its length. + +## Detection + +Assemble with `-L file.lst` and check: + +- BANK words (`$71xx`) in front of single-operand and `#imm` instructions; +- odd displacement bytes in `.s` branches (the `.s+` form); +- `(pc)` source operands on AMMX instructions. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| Encodings in the table above | (M) | Core 12841 | vasm 2.0f/2.0g listings run on the V4 | +| ApolloCrossDev ships vasm 2.0f | (SRC) | any | `vasm.c`: `_VER "vasm 2.0f"` | +| The vasm opcode table (`cpus/m68k/opcodes.h`, "apollo" entries) is a good encoding reference | (SRC) | any | vasm source | diff --git a/toolchain/pitfalls/vasm-pc-relative-destination.md b/toolchain/pitfalls/vasm-pc-relative-destination.md new file mode 100644 index 0000000..e4f40cc --- /dev/null +++ b/toolchain/pitfalls/vasm-pc-relative-destination.md @@ -0,0 +1,74 @@ +--- +title: vasm -m68080 turns absolute destinations into PC-relative ones +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured, official, source-code] +components: [toolchain, cpu-68080] +applies_to: + core: "Core 12841" + os: [any] +tags: [vasm, pc-relative, optimization, memory-corruption, 68080] +related: + - core/pitfalls/pc-relative-destination.md + - toolchain/vasm-assembler.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 0 (rule 22) and 9.4" + - "ApolloCrossDev Compilers/_archives/vasm/vasm.tar.tar: vasm 2.0f" +--- + +## Symptom + +Silent memory corruption in assembly code that writes to a label: the write +lands at the wrong address. The source looks correct, because the label is +written as an absolute address. + +## Cause + +- With `-m68080`, vasm optimizes an absolute destination `move.x ,label` + into a PC-relative destination `label(pc)` by default. It does the same + for addq/subq, bchg/bclr/bset, eor, fmove and AMMX stores. +- The 68080 computes a PC-relative destination wrongly when the source uses + the full extension format (for example `(table.l,d0.w)` or memory + indirect). See [core/pitfalls/pc-relative-destination.md](../../core/pitfalls/pc-relative-destination.md). +- This optimization is on by default; `-opt-speed` is not what causes it. + `-nodpc` and `opt` directives do not turn it off; only `-no-opt` does. +- ApolloCrossDev ships vasm 2.0f (SRC), which has this behaviour (M). The + vasm author has been informed; a fix will come in a future ApolloCrossDev + update. + +## Wrong + +```asm + move.b (table.l,d0.w),result ; vasm -m68080 emits result(pc): miscomputed +``` + +## Right + +Address the destination through a register in code that combines a +full-format source with a label destination: + +```asm + lea result,a1 + move.b (table.l,d0.w),(a1) +``` + +Or assemble that file with `-no-opt`. That turns off **all** vasm +optimizations (also `moveq` for `move.l #imm` and branch-size choices), so +optimize those by hand. + +## Detection + +Assemble with a listing (`-L file.lst`) and look for MOVE and the other +instructions above with destination mode 7/2 (`d16(pc)`) and a full-format +source operand. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| PC-relative destination is not calculated correctly with some extended source formats | (official) PRM, integer unit page | any | Manual | +| vasm `-m68080` makes `(d16,PC)` destinations by default; only `-no-opt` stops it | (M) | any | vasm 2.0f/2.0g listings | +| The fix belongs in vasm `cpu.c`: `APOLLO_PCDEST` misses operand types DN/MA/MI/BS/CT | (SRC) | any | vasm source | +| ApolloCrossDev ships vasm 2.0f | (SRC) | any | `vasm.c`: `_VER "vasm 2.0f"` | diff --git a/toolchain/vasm-assembler.md b/toolchain/vasm-assembler.md index 031f1a2..a2a6319 100644 --- a/toolchain/vasm-assembler.md +++ b/toolchain/vasm-assembler.md @@ -22,13 +22,15 @@ sources: Assemble 68080 code with `vasmm68k_mot`: vasm built for m68k with Motorola syntax. Standard options: `-Fhunk -m68080 -m68881 -opt-speed`, with the DevPac -includes on the include path. +includes on the include path. **ApolloCrossDev ships vasm 2.0f, which with +`-m68080` silently creates PC-relative destinations that the 68080 can +miscompute:** read [vasm-pc-relative-destination.md](pitfalls/vasm-pc-relative-destination.md). ## Details ### Binary -ApolloCrossDev builds vasm from `Compilers/_archives/vasm` with +ApolloCrossDev builds vasm 2.0f from `Compilers/_archives/vasm` with `make CPU=m68k SYNTAX=mot` and installs `vasmm68k_mot` and `vobjdump` in `/bin`. @@ -46,6 +48,16 @@ Debug options in the Makefile template: `-linedebug` (source line debug information) and `-kick1hunks` (only hunk types that Kickstart 1.x understands). +Other useful options: + +| Option | Meaning | +|---|---| +| `-no-opt` | Turn off all optimizations, including the PC-relative destination rewrite. Use it for byte-exact round trips and CPU tests; optimize by hand | +| `-L ` | Write a listing: use it to check encodings | +| `-devpac` | Devpac compatibility mode | + +Use `machine ac68080` in the source for AMMX instructions. + ```sh vasmm68k_mot -Fhunk -m68080 -m68881 -opt-speed \ -I/m68k-amigaos/DevPac/Include file.s -o file.o @@ -76,10 +88,16 @@ _my_function: (`m68k-amigaos-as`) accepts 68080 instructions is not documented here. - DON'T use `-m68060` or lower. Without `-m68080`, 68080 and AMMX instructions are rejected. +- With `-m68080`, vasm rewrites absolute destinations into PC-relative ones + and encodes some 68080 forms wrongly (BANK single operands, AMMX + PC-relative sources). See [vasm-68080-encoding-issues.md](pitfalls/vasm-68080-encoding-issues.md). ## Do / Don't - DO use Motorola syntax. - DO pass `-m68080` so 68080 instructions are accepted. +- DO check the listing of code that writes to labels after a + full-extension-format source, or address such destinations through a + register. - DON'T invent AMMX mnemonics. Check `core/cpu-68080/`, or the `AMMX` folder in ApolloCrossDev `Docs/`.