diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c774ccd..8f46680 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -157,6 +157,13 @@ /os/apolloos-and-amigaos-on-v4.md @WDrijver /os/apolloos-specific-on-v4.md @WDrijver /os/os-takeover.md @WDrijver +/os/best-practices/detect-68080-and-fpu-at-run-time.md @TuKo1982 +/os/libraries/maggie-library.md @TuKo1982 +/os/pitfalls/library-globals-shared-between-tasks.md @TuKo1982 +/os/pitfalls/maggie-library-side-effects.md @TuKo1982 +/os/pitfalls/ramlib-reuses-library-by-name.md @TuKo1982 +/os/pitfalls/stack-patches-hide-small-stack-bugs.md @TuKo1982 +/os/pitfalls/v4-rom-modules-and-reset.md @TuKo1982 /toolchain/c-compiler-options.md @WDrijver /toolchain/compiler-variants.md @WDrijver /toolchain/index.md @WDrijver diff --git a/core/saga-3d-maggie/index.md b/core/saga-3d-maggie/index.md index 025533f..4f463fb 100644 --- a/core/saga-3d-maggie/index.md +++ b/core/saga-3d-maggie/index.md @@ -29,7 +29,7 @@ or 68060 knowledge. - `registers.md`: the span unit registers as maggie.library uses them, with measured behaviour (exists; no official register documentation yet) - One file per feature, for example texture mapping -- Using maggie.library: planned in `os/libraries/` +- Using maggie.library: [os/libraries/maggie-library.md](../../os/libraries/maggie-library.md) ### For contributors diff --git a/os/apolloos-and-amigaos-on-v4.md b/os/apolloos-and-amigaos-on-v4.md index 1138b2f..ce8811f 100644 --- a/os/apolloos-and-amigaos-on-v4.md +++ b/os/apolloos-and-amigaos-on-v4.md @@ -17,14 +17,16 @@ sources: Guidelines for programs that run on Apollo V4 hardware under ApolloOS R10, AmigaOS 3.9 or AmigaOS 3.2. Read this for every Apollo V4 project. -**This file has no content yet.** If your task depends on it, tell the user -that the knowledge base does not cover OS-specific guidelines yet. +**This file is only partly covered.** It points to the files that exist so +far. For anything else, tell the user that the knowledge base does not cover +OS-specific guidelines yet. ## Details ### Detecting Apollo V4 hardware -No content yet. +Gate 68080 code on AttnFlags bit 10 and FPU code on the 68881 flag at run +time: see [best-practices/detect-68080-and-fpu-at-run-time.md](best-practices/detect-68080-and-fpu-at-run-time.md). ### OS functions per target OS @@ -32,7 +34,16 @@ No content yet. ### Using SAGA features through the OS -No content yet. +- Maggie 3D: [libraries/maggie-library.md](libraries/maggie-library.md), + and read [pitfalls/maggie-library-side-effects.md](pitfalls/maggie-library-side-effects.md) + first. + +### Known traps on V4 under AmigaOS + +See `os/pitfalls/`: stack patches hiding small-stack bugs, library globals +shared between tasks, V4 ROM modules and soft resets, and `ramlib` reusing a +library by name. `CacheClearU` doing nothing on the 68080 is in +[core/pitfalls/self-modifying-code-and-caches.md](../core/pitfalls/self-modifying-code-and-caches.md). ## Differences from AmigaOS / AROS / 68060 diff --git a/os/best-practices/detect-68080-and-fpu-at-run-time.md b/os/best-practices/detect-68080-and-fpu-at-run-time.md new file mode 100644 index 0000000..01b93b7 --- /dev/null +++ b/os/best-practices/detect-68080-and-fpu-at-run-time.md @@ -0,0 +1,56 @@ +--- +title: Detect the 68080 and the FPU at run time +type: best-practice +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured] +components: [general, cpu-68080] +applies_to: + core: "Core 12798-12841" + os: [amigaos-3.9, amigaos-3.2] +tags: [attnflags, detection, 68080, fpu, execbase, libraries] +related: + - core/cpu-68080/core-at-a-glance.md + - toolchain/best-practices/gcc-code-generation-for-68080.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 1, 9.1 and 13" +--- + +## Goal + +Correctness and portability: run 080-specific and FPU code only where it +works, and keep one binary usable on other CPUs or with the FPU switched off. + +## Technique + +- Gate 080 code paths on `AttnFlags & (1 << 10)` in ExecBase. +- Gate FPU code paths on the 68881 flag **at run time**. The FPU can be + switched off (vampiresupport.resource); AttnFlags then reads `$040f` + instead of `$847f`. +- In a library, do the check in LibInit, and build that object with + `-m68020` so it runs on any CPU before it decides. + +```c +#include +#include + +extern struct ExecBase *SysBase; + +BOOL has_68080(void) { return (SysBase->AttnFlags & (1 << 10)) != 0; } +BOOL has_fpu(void) { return (SysBase->AttnFlags & AFF_68881) != 0; } +``` + +## Evidence + +| Variant | Measurement | Core | Test setup | +|---|---|---|---| +| FPU on | AttnFlags = `$847f` | Core 12798-12841 | AmigaOS 3.9 (M) | +| FPU off | AttnFlags = `$040f` | Core 12798-12841 | Same | + +## When not to use + +- In an os-takeover program that you only ship for the V4, a single check at + start-up is enough; don't test in inner loops. +- The DevPac include set redefines `AFB_68080`; use the NDK includes (plus + DevPac `funcdef.i`) so the flag name matches. diff --git a/os/libraries/maggie-library.md b/os/libraries/maggie-library.md new file mode 100644 index 0000000..3aef30d --- /dev/null +++ b/os/libraries/maggie-library.md @@ -0,0 +1,178 @@ +--- +title: maggie.library (Maggie 3D on AmigaOS) +type: reference +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured, source-code] +components: [libraries, saga-3d-maggie] +applies_to: + core: "Core 12841+" + os: [amigaos-3.9] +tags: [maggie, 3d, library, textures, dxt1, rendering] +related: + - os/pitfalls/maggie-library-side-effects.md + - core/saga-3d-maggie/registers.md + - core/pitfalls/maggie-depth-test-colour-write.md + - core/pitfalls/maggie-span-tail.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), sections 15.1 and 15.3-15.8" + - "maggie.library source, github.com/RMortenB/MaggieLibrary, commit 64c78ef (2026-08-17), MaggieLibrary_API.md" +--- + +## Summary + +Morten's maggie.library drives the V4's Maggie span unit: it does transform, +lighting, clipping and triangle/polygon setup on the CPU and FPU, and gives +Maggie one span per scanline. Read +[maggie-library-side-effects.md](../pitfalls/maggie-library-side-effects.md) +before using it: a call changes your task's FPCR and E registers. + +## Details + +Source: . These notes were read +against commit `64c78ef` (2026-08-17); the full API is in +`MaggieLibrary_API.md`. Version tested on a V4: `maggie 4.0 (Sep 9 2026)`, +AmigaOS 3.9. + +### Linking and building (SRC) + +- **Shared:** `OpenLibrary("maggie.library", 0)` + ``. +- **Static:** `make static` gives `libmaggie.a`. Include + ``, replace OpenLibrary/CloseLibrary with + `magCreateContext()` / `magDeleteContext(base)`, store the result in the + global `MaggieBase`, and link the archive **before** `-lamiga -lm`. +- Both forms pass the base in `a6` (`##bias 30`; LVOs in + `include/lvo/Maggie_lvo.i`). +- From assembler, arguments go in registers as `maggie.fd` lists them; + floats go in `fp0`–`fp2` (for example `magVertex`, `magSetLightPosition`, + the `magDrawSprites` size). +- Library build flags: + + ```sh + -std=c11 -fexcess-precision=fast -noixemul -Ofast -fno-unsafe-math-optimizations + -fomit-frame-pointer -m68080 -mregparm -mhard-float + ``` + + `-std=c11` alone forces `-fexcess-precision=standard`, which caused about + 1320 spills of 12-byte values in the library. +- Static objects must use the caller's ABI (`-m68080 -mhard-float`). Use + `-fomit-frame-pointer` so that `a6` is free. +- The assembler reads `MaggieBase` at fixed offsets + (`raster/raster_structs.i`), checked by `_Static_assert`s. After changing + `maggie_internal.h`, do a clean rebuild. + +### Frame setup + +- **Render target:** `magSetScreenMemory(pixels, xres, yres)`. Up to + 1920x1080 in the source (the README still says 1280x720). 16-bit (default) + or 32-bit (`MAG_DRAWMODE_32BIT`) pixels. Rows are packed: the pitch is + `xres * bpp`, with no separate modulo. Align buffers to 32 bytes, as the + samples do. +- **Full screen with SAGA, as in the samples** (os-takeover): + 1. `SystemControl(SCON_TakeOverSys)` and switch off the raster/copper DMA. + 2. Save the old mode and frame pointer from the read addresses `$DFE1F4` + and `$DFE1EC`. + 3. Write the mode to `$DFF1F4` and the frame pointer to `$DFF1EC`. The + samples use `$0B02` = 640x360x16 and `$0B05` = 640x360x32. + 4. Use triple buffering, flipped after a VBlank. +- **In a window:** render into a 32-bit buffer, then + `WritePixelArray(..., RECTFMT_ARGB)` (samples/Windowed). +- **Depth buffer:** internal, allocated at 1920x1080 x 2 bytes = 4 MB. It is + a **16-bit w-buffer**, not a z-buffer. Build the projection with + `mat4_perspective` from `maggie_vec.h` so that w = view z. Call + `magClearDepth($ffff)`, then `magClear(MAG_CLEAR_COLOUR | MAG_CLEAR_DEPTH)` + (one call for both is faster). +- **Matrices:** world, view and projection are multiplied into one matrix. + Lighting uses world space and texgen view space; if you use neither, put + the whole transform in any one matrix. The viewport is fixed: + `* halfres + halfres`. Front faces are clockwise (`MAG_DRAWMODE_CULL_CCW` + swaps); culling is always on. +- **Scissor:** `magScissor(x, y, w, h)`, in pixels. + +### Draw paths, fastest first + +1. **Buffers:** `magAllocate*Buffer`, `magUpload*`, `magSet*Buffer`, then + `magDrawTriangles`, `magDrawIndexedTriangles` or `magDrawIndexedPolygons`. + Data is converted once at upload. Pass `firstVtx`/`nVtx` covering only the + vertices used: those get transformed. To change one attribute, use + `magUploadVertexPositions/Normals/TexCoords2/TexCoords3/Colours`. +2. **User pointers** (`...UP`): the same calls on your own arrays, converted + on every draw. +3. **Immediate mode** (`magBegin/magVertex/.../magEnd`): triangles only; it + collects vertices and calls `magDrawTrianglesUP`. The slowest path. + +- **Polygons:** convex, planar, with a planar UV mapping, up to 256 sides. + `$FFFF` in the index list starts a new polygon, so vertex index `$FFFF` + cannot be used. A quad is cheaper than two triangles (one setup, one edge + walk). Add collinear vertices to avoid T-junction cracks. +- **Sprites:** `magDrawSprites(start, n, size)` / `magDrawSpritesUP` + (position + colour only), always facing the camera. Use + `MAG_DRAWMODE_AFFINE_MAPPING` with them. +- **Vertex format** (`maggie_vertex.h`): `pos` vec3, `normal` vec3, + `tex` {u, v, w}, then `colour` ULONG: 40 bytes. One texture unit; UV 0..1 = + one tile. +- The span calls (`magDrawSpan`, `magDrawLinearSpan`) are disabled and do + nothing. + +### Draw modes (`magSetDrawMode`, OR the flags) + +| Flag | Value | Effect | +|---|---|---| +| `DEPTHBUFFER` | `$0001` | 16-bit w-buffer test and write | +| `BILINEAR` | `$0002` | Bilinear filtering | +| `32BIT` | `$0004` | 32-bit target (default 16) | +| `LIGHTING` | `$0008` | Per-vertex lights (up to 8) replace the vertex colour | +| `CULL_CCW` | `$0010` | Counter-clockwise front faces | +| `TEXGEN_POS/NORMAL/REFLECT` | `$0020/$0040/$0060` | Texture coordinates from position, view normal, reflection | +| `MIPMAP` | `$0080` | Automatic mip selection, even when no mipmaps were uploaded | +| `BLEND_ADD` / `BLEND_MUL` | `$0100` / `$0200` | Add to or multiply with the target | +| `AFFINE_MAPPING` | `$1000` | No perspective correction: much faster for small triangles | +| `DEPTH_MASK` | `$2000` | Hardware mode bit 3 | + +**Colour is intensity only.** Maggie interpolates one light value per pixel. +Vertex and light colours are turned into grey at upload. The tint is one RGB +per draw (`magSetRGB`), multiplied with the texture and the light. + +### Textures + +- Square, power of two, 32 to 1024 pixels: `magAllocateTexture(log2size)` + takes 5–10. +- **Always stored as DXT1** (4 bits per texel) plus the full mip chain. + `magUploadTexture(t, mipLog2, data, fmt)` takes `MAG_TEXFMT_DXT1`, `_RGB` + or `_RGBA`, plus `MAG_TEXCOMP_HQ` for slower, better compression. RGB and + RGBA are compressed on the CPU at upload: do it at load time, or ship DXT1 + (the samples load `.dds`). +- **Alpha is DXT1's 1 bit.** RGBA texels with alpha < 128 are transparent: + Maggie leaves those target pixels unchanged. There is no alpha blending. +- Texture data is kept 32-byte aligned. + +### Performance + +- The library ranks the paths buffers > user pointers > immediate, + quads/polygons over triangle pairs, and `AFFINE_MAPPING` as much faster for + small triangles (SRC). +- Measure first with `make static PROFILE=1`: it prints frame, clear, spans + and setup times per frame. "Spans" is the raster; "Setup" is the CPU work + (transform, clipping, setup, edge walk). `PROFILE=2` adds a per-edge timer, + which doubles the edge cost. +- The FPU rules apply to your own transform code: one FP register write per + cycle, fmul 5 and fadd 6 cycles of latency, 3 cycles per FP-to-integer + conversion (see [core/cpu-68080/fpu-performance-model.md](../../core/cpu-68080/fpu-performance-model.md)). + +## Differences from AmigaOS / AROS / 68060 + +- Maggie is V4 hardware, so classic AmigaOS has no library for it. + maggie.library is V4 specific. +- It relies on BANK-prefixed FPU instructions, which the Apollo team will not + support in future cores; see the side-effects pitfall. + +## Do / Don't + +- DO read [maggie-library-side-effects.md](../pitfalls/maggie-library-side-effects.md) + first. +- DO use uploaded buffers and quads/polygons for speed, and + `AFFINE_MAPPING` for small triangles. +- DON'T use vertex index `$FFFF`, or expect alpha blending or coloured + lighting. +- DON'T call `magDrawSpan`/`magDrawLinearSpan`: they do nothing. diff --git a/os/pitfalls/library-globals-shared-between-tasks.md b/os/pitfalls/library-globals-shared-between-tasks.md new file mode 100644 index 0000000..a9e3bc4 --- /dev/null +++ b/os/pitfalls/library-globals-shared-between-tasks.md @@ -0,0 +1,62 @@ +--- +title: Library globals are shared between calling tasks +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured] +components: [libraries] +applies_to: + core: "any" + os: [amigaos-3.9, amigaos-3.2] +tags: [libraries, reentrancy, race, tasks, stackswap] +related: + - os/pitfalls/stack-patches-hide-small-stack-bugs.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 13" +--- + +## Symptom + +A shared library works with one caller but crashes or mixes up data when +several tasks call it at the same time, for example several player tasks +using one decoder library. + +## Cause + +Library globals, and data in the library base, are shared by every task that +calls the library. A per-base `StackSwapStruct`, for example, is overwritten +by the second caller while the first is still using it. + +## Wrong + +```c +struct MyLibBase { + struct Library lib; + struct StackSwapStruct sss; /* one for all callers */ +}; +``` + +## Right + +Keep per-call state on the stack or in a block allocated per call (or per +opener), never in the library base or in globals: + +```c +LONG decode(struct MyLibBase *base, struct Frame *f) +{ + struct StackSwapStruct sss; /* per call */ + /* ... */ +} +``` + +## Detection + +Look for writable globals and writable fields in the library base that are +used during a call. Test with two or more tasks calling at once. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| A per-base StackSwapStruct raced with several player tasks | (M) | any | MP3 library on AmigaOS 3.9 | diff --git a/os/pitfalls/maggie-library-side-effects.md b/os/pitfalls/maggie-library-side-effects.md new file mode 100644 index 0000000..b1e6155 --- /dev/null +++ b/os/pitfalls/maggie-library-side-effects.md @@ -0,0 +1,92 @@ +--- +title: What a maggie.library call does to your task +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [core-developer, measured, source-code] +components: [libraries, saga-3d-maggie, cpu-68080] +applies_to: + core: "Core 12841+" + os: [amigaos-3.9] +tags: [maggie, fpcr, rounding, e-registers, apollo-bit, bank, fpu] +related: + - os/libraries/maggie-library.md + - core/cpu-68080/prm/apollo-bit.md + - core/cpu-68080/bank-prefix.md + - core/pitfalls/fpu-float-to-integer-conversion.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 15.2" + - "maggie.library source, github.com/RMortenB/MaggieLibrary, commit 64c78ef (2026-08-17)" +--- + +## Symptom + +After the first frame drawn with maggie.library: + +- every FP-to-integer conversion in your own code truncates; +- values you kept in E registers (D8–D31) are gone; +- with the OS running, a task switch in the middle of a draw corrupts the + frame; +- on a machine without Maggie, nothing is drawn and nothing reports why. + +## Cause + +- **FPCR is left at round-to-zero.** `magBeginScene` (and library init) set + FPCR bits 5–4 to RZ in **your** task and do not restore them (SRC). +- **D8–D31 are destroyed.** Some functions clobber all E registers: the + raster and setup code use them as FPU registers (SRC). d0/d1/a0/a1 are + scratch as usual. +- **The library uses E registers but never sets the Apollo bit** (SR bit + 11), so on AmigaOS a task switch during a draw loses them. +- **No hardware check:** `hasMaggie` is hard-wired to 1 (a TODO in the + source). Without a bound texture, nothing is drawn (`CanDraw`). +- **Scene lock:** `magBeginScene`/`magEndScene` take a library-wide + semaphore and reset the matrices, lights, depth state and draw mode. +- **BANK-prefixed FPU instructions:** about 470 in the setup and raster + assembler, for example `fdiv e0,e4,e0` = `$7905 $F200 $0220`, + `fmove.s (a2)+,e18`, and `fmoverz.l e13,d3` (which does not exist on the + V2). They work on Core 12841 (M), but the team has decided not to support + BANK on FPU instructions in future cores (G, 2026-10-26). + +## Wrong + +```c +magBeginScene(); +draw_scene(); +magEndScene(); +ix = (LONG)my_float; /* now truncates: FPCR left at RZ */ +``` + +## Right + +```c +/* GetFPCR/SetFPCR: your own helpers (fmove.l fpcr,d0 / fmove.l d0,fpcr) */ +ULONG fpcr = GetFPCR(); +SetSR(0x800, 0x800); /* Apollo bit: keep E registers across task switches */ +magBeginScene(); +draw_scene(); +magEndScene(); +SetFPCR(fpcr); /* restore your rounding mode */ +``` + +- Keep nothing in E registers across a `mag*` call. +- Check for a V4 yourself before using the library. +- Wrap each frame in `magBeginScene`/`magEndScene`. Under a full takeover you + may skip them, but then FPCR is not set to RZ for you. +- Check the library on every new core: the BANK-prefixed FPU code will need + a port when the new FPU encoding arrives. + +## Detection + +Read FPCR before and after a scene. Test E-register values across a `mag*` +call. Run a draw with other tasks active. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| FPCR set to RZ and not restored; E registers clobbered; Apollo bit not set; `hasMaggie` = 1 | (SRC) | any | maggie.library source, commit 64c78ef | +| The windowed sample sets the Apollo bit with `SetSR(0x800, 0x800)` | (SRC) | any | samples/Windowed | +| BANK-prefixed FPU instructions work | (M) | Core 12841 | Library running on the V4 | +| No BANK prefix on FPU instructions in future cores | (G, 2026-10-26) | Future core | Statement | diff --git a/os/pitfalls/ramlib-reuses-library-by-name.md b/os/pitfalls/ramlib-reuses-library-by-name.md new file mode 100644 index 0000000..531aa82 --- /dev/null +++ b/os/pitfalls/ramlib-reuses-library-by-name.md @@ -0,0 +1,51 @@ +--- +title: OpenLibrary by path returns the version already in memory +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured] +components: [libraries] +applies_to: + core: "any" + os: [amigaos-3.9, amigaos-3.2] +tags: [ramlib, openlibrary, benchmark, testing, libraries] +related: + - core/cpu-68080/performance-counters.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 8.2" +--- + +## Symptom + +You benchmark or test two builds of a library, but both runs give the same +results: the second build is never used. + +## Cause + +AmigaOS `ramlib` matches libraries by name. Opening a second build by its +path returns the library that is already in memory with that name. + +## Wrong + +```c +base1 = OpenLibrary("work:old/mylib.library", 0); +CloseLibrary(base1); +base2 = OpenLibrary("work:new/mylib.library", 0); /* still the old one */ +``` + +## Right + +Give each variant a unique name, or flush the old one from memory between +runs. When a test name changes the code layout, keep it the same length as +the real name (the name string shifts the code). + +## Detection + +Print the library's version string or a build marker after opening it. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| A second build opened by path returned the one in memory | (M) | any | Library benchmarks on AmigaOS 3.9 | diff --git a/os/pitfalls/stack-patches-hide-small-stack-bugs.md b/os/pitfalls/stack-patches-hide-small-stack-bugs.md new file mode 100644 index 0000000..52ea302 --- /dev/null +++ b/os/pitfalls/stack-patches-hide-small-stack-bugs.md @@ -0,0 +1,61 @@ +--- +title: Stack patches hide small-stack code paths +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured] +components: [general] +applies_to: + core: "any" + os: [amigaos-3.9, amigaos-3.2] +tags: [stack, stackattack, stackswap, testing, libraries] +related: + - toolchain/pitfalls/gcc-stackswap-defer-pop.md + - os/pitfalls/library-globals-shared-between-tasks.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 13" +--- + +## Symptom + +A library or program works on the developer's machine but crashes for some +users, typically callers with a small stack. + +## Cause + +StackAttack-style patches give every process a large stack. On machines with +such a patch, the code paths for small stacks (a `StackSwap()` to a private +stack, stack checks) never run, so their bugs stay hidden. + +## Wrong + +Testing only on a system with a stack patch installed. + +## Right + +Test the small-stack paths on a stack you allocate yourself and swap to with +`StackSwap()`, so they run whatever patches are installed: + +```c +struct StackSwapStruct sss; +UBYTE *stack = AllocVec(4096, MEMF_ANY); /* deliberately small */ +sss.stk_Lower = stack; +sss.stk_Upper = (ULONG)(stack + 4096); +sss.stk_Pointer = (APTR)(stack + 4096); +StackSwap(&sss); +run_test(); +StackSwap(&sss); +FreeVec(stack); +``` + +## Detection + +Check whether a stack patch is active on the test machine, and test library +entry points with a small caller stack. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| Small-stack code paths never run on machines with a stack patch | (M) | any | Library testing on AmigaOS 3.9 on the V4 | diff --git a/os/pitfalls/v4-rom-modules-and-reset.md b/os/pitfalls/v4-rom-modules-and-reset.md new file mode 100644 index 0000000..2d57e94 --- /dev/null +++ b/os/pitfalls/v4-rom-modules-and-reset.md @@ -0,0 +1,62 @@ +--- +title: V4 ROM modules, soft resets and avail flush +type: pitfall +owner: TuKo1982 +status: draft +origin: ai-assisted +basis: [measured] +components: [devs, general] +applies_to: + core: "any" + os: [amigaos-3.9] +tags: [loadmodule, rom, resident, reset, dma, ethernet, audio-device, avail] +related: + - os/apolloos-and-amigaos-on-v4.md + - core/saga-audio-arne/registers.md +sources: + - "TuKo1982, 68080 compilation and optimisation guide (2026-10-30), section 13" +--- + +## Symptom + +- A module loaded with LoadModule is not used: the ROM version stays active. +- The machine boots into a corrupted state after a soft reset while a + network driver was running. +- Audio interrupts break after `avail flush`. + +## Cause + +| Trap | Cause | +|---|---| +| LoadModule does not replace a module | Modules with priority 105 or more cannot be replaced by LoadModule on the V4: its stub has priority 104 | +| Corruption after a soft reset | Devices whose DMA survives a soft reset (V4 Ethernet RX) keep writing into memory while the next boot runs | +| Audio broken after `avail flush` | ROM audio.device 37.10 writes −1 into all Paula interrupt vectors on expunge | + +## Wrong + +```text +LoadModule DEVS:mydriver.device ; priority 110: silently not used +Avail FLUSH ; expunges audio.device 37.10 +``` + +## Right + +- Flash modules with priority 105 or more into the ROM instead of using + LoadModule. Check the live vectors, not the resident list, to see which + version is active. +- Stop the DMA of such devices in a ColdReboot patch. +- Avoid `avail flush` on the V4. + +## Detection + +After LoadModule, compare the library or device vectors with the new +module's code. After a soft reset with networking active, check for memory +corruption early in the boot. + +## Evidence + +| Claim | Source | Core | Method | +|---|---|---|---| +| LoadModule stub priority 104 | (M) | any | AmigaOS 3.9 on the V4 | +| Ethernet RX DMA survives a soft reset | (M) | any | Network driver work on the V4 | +| audio.device 37.10 writes −1 into the Paula interrupt vectors on expunge | (M) | any | AmigaOS 3.9 ROM on the V4 |