docs(amiga): complete AmigaOS 3.1/3.2 developer reference — 172 files across 17 sections

Comprehensive technical documentation covering:
- Hardware: OCS/ECS/AGA custom chip registers, Copper & Blitter deep dives
- Boot sequence: cold boot through startup-sequence
- Binary format: HUNK executable spec, relocation, debug info
- Linking & ABI: .fd files, LVO tables, register calling conventions
- Exec kernel: tasks, interrupts, memory, signals, semaphores
- AmigaDOS: file I/O, FFS/OFS layout, CLI/Shell scripting
- Graphics: planar bitmaps, Copper programming, HAM/EHB modes
- Intuition: screens, windows, IDCMP, BOOPSI
- Devices: trackdisk, SCSI, serial, timer, audio, keyboard
- Libraries: utility, expansion, IFFParse, locale, ARexx
- Networking: bsdsocket API, SANA-II, TCP/IP stack comparison
- Toolchain: GCC, vasm/vlink, SAS/C, NDK, debugging
- Reverse engineering: IDA/Ghidra setup, compiler fingerprints, case studies
- CPU & MMU: 68040/060 emulation libs, PMMU, cache management
- Driver development: SANA-II, Picasso96/RTG, AHI audio

All files include breadcrumb navigation. No local paths or proprietary content.

01_hardware/aga_a1200_a4000/cpu_030_040.md

@@ -0,0 +1,139 @@
+[← Home](../../README.md) · [Hardware](../README.md) · [AGA](README.md)
+
+# 68030/040 on the Amiga (A3000/A4000)
+
+## Overview
+
+The A3000 ships with a **Motorola 68030** at 16 or 25 MHz. The A4000 ships with either a 68030 or **68040** at 25 MHz. Later accelerator cards bring the 68060. This document covers CPU-specific concerns for AmigaOS 3.1/3.2 on these platforms.
+
+## 68030 (A3000)
+
+### On-Chip Caches
+- **Instruction cache**: 256 bytes, direct-mapped
+- **Data cache**: 256 bytes, direct-mapped
+- Both enabled by default on AmigaOS 3.1 (`CacheControl()` call)
+
+### On-Chip PMMU
+- Full 68030 PMMU: ATC (Address Translation Cache), TT registers
+- AmigaOS does **not** use the MMU by default on A3000
+- Third-party tools (e.g., VMM, mmu.library) use it for virtual memory
+
+### Cache Control (exec)
+```c
+#include <proto/exec.h>
+
+/* Enable instruction and data caches */
+CacheControl(CACRF_EnableI | CACRF_EnableD, CACRF_EnableI | CACRF_EnableD);
+
+/* Flush caches (required before self-modifying code) */
+CacheClearU();          /* clear all caches */
+CacheClearE(addr, len, CACRF_ClearI | CACRF_ClearD);  /* targeted flush */
+```
+
+### Cache Coherency with DMA
+The 68030 data cache is **not snooped** by the Amiga chip bus. If the CPU writes to a buffer that the DMA engine (Blitter, audio, custom chips) will read, the cache must be flushed first:
+
+```c
+/* Before handing a buffer to DMA: */
+CacheClearE(buf, size, CACRF_ClearD);
+```
+
+Similarly, after DMA writes to a buffer that the CPU will read:
+```c
+CacheClearE(buf, size, CACRF_ClearD);
+```
+
+This is a common source of bugs in audio/video programming on 68030+ Amigas.
+
+---
+
+## 68040 (A4000 / Accelerators)
+
+### On-Chip FPU — Partial Implementation
+The 68040 has an on-chip FPU but omits many instructions present in the 68881/68882:
+
+**Missing from 68040 FPU:**
+- `FSIN`, `FCOS`, `FTAN`, `FASIN`, `FACOS`, `FATAN`
+- `FETOX`, `FETOXM1`, `FLOGN`, `FLOG10`
+- `FSINH`, `FCOSH`, `FTANH`
+- `FATANH`, `FASINH`, `FACOSH`
+- `FSCALE`, `FREMX`, `FREMX`, `FINTRZ`
+
+AmigaOS provides `68040.library` which installs Line-F exception handlers to emulate the missing instructions in software.
+
+```c
+/* 68040.library is opened automatically by exec at boot */
+/* Software should check that it is open before using FP */
+struct Library *MathLib = OpenLibrary("68040.library", 0);
+```
+
+> [!WARNING]
+> If `68040.library` is not installed and software uses a missing 68040 FPU instruction, the system will crash with a Line-F exception. Always ensure `68040.library` is present on A4000.
+
+### 4 KB Instruction + Data Caches
+- 68040 has **4 KB instruction cache** and **4 KB data cache**, both 4-way set-associative
+- Cache coherency is more complex: DMA writes may not be visible to the CPU without invalidation
+- `CacheClearE()` / `CacheClearU()` remain the correct API
+
+### 68040 Memory Model
+```
+CACR (Cache Control Register) accessed via MOVEC:
+  bit 15: EDC   — enable data cache
+  bit 14: NAD   — no allocate data (streaming mode)
+  bit 13: ESB   — enable store buffer
+  bit 10: DPI   — disable push-inhibit
+  bit  7: EIC   — enable instruction cache
+  bit  3: CINV  — cache invalidate
+```
+
+### Bus Error Stack Frame (68040)
+The 68040 generates a **different bus error stack frame** from the 68000:
+- 68000: 14-byte frame
+- 68040: 104-byte frame with pipeline state
+
+This matters for exception handlers and debuggers targeting both platforms.
+
+---
+
+## 68060 (Accelerator Cards)
+
+Available via Blizzard 060, CyberStorm 060, etc. Key differences:
+
+- **Superscalar**: two integer pipelines (in-order, no OOO)
+- **Branch prediction**: static and dynamic
+- **No MOVE16 snooping** on some Amiga implementations
+- On-chip FPU: missing same transcendentals as 68040 → needs `68060.library`
+- Separate `68060.library` for the additional missing instructions vs 68040
+
+```c
+struct Library *Lib060 = OpenLibrary("68060.library", 0);
+```
+
+---
+
+## AmigaOS exec CacheControl() API
+
+```c
+#include <exec/execbase.h>
+#include <proto/exec.h>
+
+/* SysBase->CacheFlags reflect current cache state */
+ULONG flags = CacheControl(0, 0);   /* query without changing */
+
+/* Flag bits: */
+#define CACRF_EnableD   (1L<<3)   /* data cache enable */
+#define CACRF_FreezeD   (1L<<4)   /* data cache freeze */
+#define CACRF_ClearD    (1L<<5)   /* clear data cache */
+#define CACRF_EnableI   (1L<<8)   /* instruction cache enable */
+#define CACRF_FreezeI   (1L<<9)   /* instruction cache freeze */
+#define CACRF_ClearI    (1L<<10)  /* clear instruction cache */
+#define CACRF_CopyBack  (1L<<31)  /* data cache write-back mode */
+```
+
+## References
+
+- Motorola 68030 User's Manual (M68030UM/AD)
+- Motorola 68040 User's Manual (M68040UM/AD)
+- NDK39: `exec/execbase.h`, `proto/exec.h` — CacheControl, CacheClearE
+- ADCD 2.1: `Libraries_Manual_guide/` — exec CacheControl autodoc
+- Commodore A3000/A4000 Technical Reference Manuals