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.
2026-06-13 00:26:28 +00:00 · 2026-04-23 12:16:52 -04:00 · 2026-04-23 12:16:52 -04:00 · 21751c0025
commit 21751c0025
parent f07a368bf1
172 changed files with 19701 additions and 0 deletions
--- a/15_cpu_and_mmu/68040_68060_libraries.md
+++ b/15_cpu_and_mmu/68040_68060_libraries.md
@ -0,0 +1,151 @@
+[← Home](../README.md) · [CPU & MMU](README.md)
+
+# 68040.library and 68060.library — CPU Support Libraries
+
+## Overview
+
+The 68040 and 68060 processors **removed certain instructions** that the 68020/68030 supported in hardware. These "unimplemented" instructions cause a Line-F exception when executed. The `68040.library` and `68060.library` are **trap handler libraries** that catch these exceptions and **emulate the missing instructions in software**, providing transparent backward compatibility.
+
+Without these libraries, any program using the affected instructions would crash with a Line-F exception on 040/060 hardware.
+
+---
+
+## What Instructions Are Emulated?
+
+### 68040.library
+
+The 68040 removed several FPU instructions that the 68881/68882 supported:
+
+| Category | Missing Instructions | Description |
+|---|---|---|
+| Transcendental FPU | `FSIN`, `FCOS`, `FTAN`, `FASIN`, `FACOS`, `FATAN` | Trig functions |
+| Transcendental FPU | `FSINH`, `FCOSH`, `FTANH`, `FATANH` | Hyperbolic functions |
+| Transcendental FPU | `FLOG2`, `FLOG10`, `FLOGN`, `FLOGNP1` | Logarithms |
+| Transcendental FPU | `FETOX`, `FETOXM1`, `FTWOTOX`, `FTENTOX` | Exponentials |
+| Other FPU | `FMOD`, `FREM` | Modulo/remainder |
+| Other FPU | `FGETEXP`, `FGETMAN` | Get exponent/mantissa |
+| Other FPU | `FSGLDIV`, `FSGLMUL` | Single-precision ops |
+| Integer | `MOVEP` | Move peripheral (not on all 040 revisions) |
+
+### 68060.library
+
+The 68060 removed **everything the 040 removed** plus additional instructions:
+
+| Category | Additionally Missing | Description |
+|---|---|---|
+| Integer | `MOVEP` | Move peripheral (byte-strided) |
+| Integer | `CAS2` | Compare-and-swap dual |
+| Integer | `CHK2`, `CMP2` | Range check |
+| Integer | `MULU.L (64-bit)` | 64-bit unsigned multiply |
+| Integer | `MULS.L (64-bit)` | 64-bit signed multiply |
+| Integer | `DIVU.L (64-bit)` | 64-bit unsigned divide |
+| Integer | `DIVS.L (64-bit)` | 64-bit signed divide |
+| FPU | All 68040-missing FPU ops | Same as above |
+| FPU | `FMOVECR` | Move constant ROM |
+| FPU | `FDABS`, `FDSQRT`, etc. | Some double-precision ops |
+
+---
+
+## How They Work
+
+```
+1. Program executes FSIN (opcode $F200 xxxx)
+2. 68040/060 CPU has no microcode for this → Line-F exception (#11)
+3. CPU vectors to the Line-F exception handler
+4. 68040.library's handler decodes the opcode from the stack frame
+5. Software emulates FSIN using basic FADD/FMUL/FDIV
+6. Result is placed in the correct FPU register
+7. Handler returns → program continues as if nothing happened
+```
+
+---
+
+## Installation
+
+These libraries are **loaded at boot time** as resident modules. They install themselves as the Line-F exception vector handler.
+
+```
+; In startup-sequence or user-startup:
+LIBS:68040.library    ; for 68040 systems
+; or:
+LIBS:68060.library    ; for 68060 systems (replaces 68040.library)
+```
+
+The library is typically loaded by `SetPatch` or an explicit `C:LoadModule`:
+
+```
+C:LoadModule LIBS:68040.library
+; or for 68060:
+C:LoadModule LIBS:68060.library
+```
+
+---
+
+## struct (ROM Tag)
+
+Both libraries register as `RTF_COLDSTART` resident modules with high priority to ensure they are initialised before any user code runs:
+
+```c
+/* Typical RomTag for 68040.library: */
+static struct Resident romtag = {
+    RTC_MATCHWORD,         /* $4AFC */
+    &romtag,
+    &endskip,
+    RTF_COLDSTART,         /* flags: cold start */
+    40,                    /* version */
+    NT_LIBRARY,
+    105,                   /* priority: very high */
+    "68040.library",
+    "68040.library 40.1 (1.1.93)\r\n",
+    initRoutine
+};
+```
+
+---
+
+## Detection
+
+```c
+/* Check which CPU is present: */
+if (SysBase->AttnFlags & AFF_68040)  /* 68040 */
+if (SysBase->AttnFlags & AFF_68060)  /* 68060 */
+
+/* AttnFlags bits: */
+#define AFB_68010   0
+#define AFB_68020   1
+#define AFB_68030   2
+#define AFB_68040   3
+#define AFB_68060   7   /* added by 68060.library */
+#define AFB_68881   4   /* FPU present */
+#define AFB_68882   5
+#define AFB_FPU40   6   /* 040 internal FPU */
+```
+
+---
+
+## Performance Impact
+
+Software emulation of transcendental FPU instructions is **10–100x slower** than the 68881/68882 hardware implementation. Performance-critical code should:
+- Use lookup tables for trig functions
+- Use polynomial approximations (Chebyshev, CORDIC)
+- Avoid `FSIN`/`FCOS` in tight loops
+
+---
+
+## Common Sources
+
+| Library | Source |
+|---|---|
+| 68040.library 37.4 | Commodore (OS 3.0 distribution) |
+| 68040.library 40.1 | Commodore (OS 3.1 distribution) |
+| 68060.library 40.1 | Phase5 (original 68060 accelerators) |
+| 68060.library 46.x | Motorola reference implementation |
+
+---
+
+## References
+
+- Motorola: *MC68040 User's Manual* — unimplemented instruction list
+- Motorola: *MC68060 User's Manual* — unimplemented instruction list  
+- NDK39: `exec/execbase.h` — `AttnFlags`
+- Phase5: 68060.library source (public domain)
--- a/15_cpu_and_mmu/README.md
+++ b/15_cpu_and_mmu/README.md
@ -0,0 +1,11 @@
+[← Home](../README.md)
+
+# CPU and MMU — Overview
+
+## Section Index
+
+| File | Description |
+|---|---|
+| [68040_68060_libraries.md](68040_68060_libraries.md) | 68040.library / 68060.library — CPU instruction emulation |
+| [mmu_management.md](mmu_management.md) | MMU page tables, mmu.library, Enforcer, VMM |
+| [cache_management.md](cache_management.md) | Cache control: CacheClearU, CacheControl, CACR |
--- a/15_cpu_and_mmu/cache_management.md
+++ b/15_cpu_and_mmu/cache_management.md
@ -0,0 +1,102 @@
+[← Home](../README.md) · [CPU & MMU](README.md)
+
+# Cache Management — CacheClearU, CacheControl, CACR
+
+## Overview
+
+68020+ processors have instruction and data caches that must be managed correctly, especially when loading code (hunks), self-modifying code, or DMA operations. AmigaOS provides `exec.library` functions for safe cache management.
+
+---
+
+## exec.library Cache Functions
+
+| LVO | Function | Description |
+|---|---|---|
+| −636 | `CacheClearU()` | Flush all caches (user-friendly, safe) |
+| −642 | `CacheClearE(addr, len, caches)` | Flush specific address range |
+| −648 | `CacheControl(cacheBits, cacheMask)` | Enable/disable cache features |
+| −762 | `CachePreDMA(addr, &len, flags)` | Prepare for DMA transfer |
+| −768 | `CachePostDMA(addr, &len, flags)` | Cleanup after DMA transfer |
+
+---
+
+## When to Flush Caches
+
+| Scenario | Function to Call |
+|---|---|
+| After loading code from disk | `CacheClearU()` |
+| After JIT / dynamic code generation | `CacheClearE(code, len, CACRF_ClearI)` |
+| Before DMA read from memory | `CachePreDMA()` (flush dirty data cache) |
+| After DMA write to memory | `CachePostDMA()` (invalidate stale data cache) |
+| After `SetFunction()` patching | `CacheClearU()` |
+
+---
+
+## CacheControl Bits
+
+```c
+/* exec/execbase.h — NDK39 */
+#define CACRF_EnableI      (1<<0)  /* enable instruction cache */
+#define CACRF_FreezeI      (1<<1)  /* freeze instruction cache */
+#define CACRF_ClearI       (1<<3)  /* clear instruction cache */
+#define CACRF_IBE          (1<<4)  /* instruction burst enable */
+#define CACRF_EnableD      (1<<8)  /* enable data cache */
+#define CACRF_FreezeD      (1<<9)  /* freeze data cache */
+#define CACRF_ClearD       (1<<11) /* clear data cache */
+#define CACRF_DBE          (1<<12) /* data burst enable */
+#define CACRF_WriteAllocate (1<<13) /* write-allocate data cache */
+#define CACRF_EnableE      (1<<30) /* enable external cache (A3640) */
+#define CACRF_CopyBack     (1<<31) /* enable copyback mode */
+```
+
+---
+
+## CACR Register (Direct Access)
+
+```asm
+; 68040 CACR bits:
+;   bit 15: DE (data cache enable)
+;   bit 14: — (reserved)
+;   bit 13: —
+;   bit 12: —  
+;   bit 11: —
+;   bit 10: —
+;   bit 9: —
+;   bit 8: IE (instruction cache enable)
+
+; Read CACR:
+    movec.l cacr,d0
+
+; Flush all caches (68040/060):
+    cpusha  dc              ; push data cache
+    cpusha  ic              ; push instruction cache
+    cinva   dc              ; invalidate data cache
+    cinva   ic              ; invalidate instruction cache
+
+; 68030:
+    movec.l cacr,d0
+    or.l    #$0808,d0       ; set ClearI + ClearD bits
+    movec.l d0,cacr
+```
+
+---
+
+## DMA and Cache Coherency
+
+Amiga custom chips (blitter, copper, audio, disk) perform DMA directly to/from Chip RAM, bypassing the CPU cache. This creates coherency issues on 68040/060:
+
+```c
+/* Before blitter reads data you just wrote: */
+CachePreDMA(data, &length, DMA_ReadFromRAM);
+
+/* After blitter writes data you want to read: */
+CachePostDMA(data, &length, 0);
+```
+
+---
+
+## References
+
+- NDK39: `exec/execbase.h`
+- Motorola: *MC68040 User's Manual* — cache chapter
+- ADCD 2.1: `CacheClearU`, `CacheClearE`, `CacheControl`
--- a/15_cpu_and_mmu/mmu_management.md
+++ b/15_cpu_and_mmu/mmu_management.md
@ -0,0 +1,187 @@
+[← Home](../README.md) · [CPU & MMU](README.md)
+
+# MMU Management — 68030/040/060 Memory Management Units
+
+## Overview
+
+The Motorola 68030, 68040, and 68060 include on-chip **MMUs** (Memory Management Units) that provide virtual-to-physical address translation, memory protection, and cache control. AmigaOS itself does **not use the MMU** for virtual memory — it was designed for a flat address space. However, several third-party tools and libraries use the MMU for:
+
+- **Enforcer/MuForce** — detecting illegal memory accesses
+- **VMM** — virtual memory (swap to disk)
+- **CyberGuard/MuGuard** — memory protection
+- **SetPatch/MuSetPatch** — cache management
+
+---
+
+## MMU Architecture Comparison
+
+| Feature | 68030 | 68040 | 68060 |
+|---|---|---|---|
+| MMU type | External (on-chip optional) | On-chip, always present | On-chip, always present |
+| Page sizes | 256B, 512B, 1K, 2K, 4K, 8K, 16K, 32K | 4K, 8K (fixed) | 4K, 8K (fixed) |
+| Table levels | 1–4 configurable | Fixed 3-level | Fixed 3-level |
+| TLB entries | 22 (ATC) | 64 (data) + 64 (instruction) | 48 (data) + 48 (instruction) |
+| PMMU instructions | `PMOVE`, `PFLUSH`, `PTEST`, `PLOAD` | `PFLUSHA`, `PFLUSHN`, `CINV`, `CPUSH` | Same as 040 |
+| Transparent translation | `TT0`, `TT1` (via PMOVE) | `DTT0/1`, `ITT0/1` (via MOVEC) | Same as 040 |
+| Supervisor root pointer | `SRP` (via PMOVE) | `SRP` (via MOVEC) | `SRP` (via MOVEC) |
+| CPU root pointer | `CRP` (via PMOVE) | `URP` (via MOVEC) | `URP` (via MOVEC) |
+
+---
+
+## Key Registers
+
+### 68030
+
+```
+TC  — Translation Control
+    Bit 31: E (enable)
+    Bits 30–28: SRE, FCL (function code lookup)
+    Bits 27–24: PS (page size)
+    Bits 23–20: IS (initial shift)
+    Bits 19–16: TIA (table index A bits)
+    ...
+
+TT0, TT1 — Transparent Translation Registers
+    Bit 15: E (enable)
+    Bits 31–24: Logical address base
+    Bits 23–16: Logical address mask
+    Bits 2–0: Function code
+
+CRP — CPU Root Pointer (64-bit)
+SRP — Supervisor Root Pointer (64-bit)
+```
+
+### 68040/060
+
+```
+TC  — Translation Control (MOVEC accessible)
+    Bit 15: E (enable translation)
+    Bit 14: P (page size: 0=4K, 1=8K)
+
+DTT0, DTT1 — Data Transparent Translation
+ITT0, ITT1 — Instruction Transparent Translation
+    Same format: base/mask/enable/cache-mode
+
+URP — User Root Pointer (32-bit, MOVEC)
+SRP — Supervisor Root Pointer (32-bit, MOVEC)
+```
+
+---
+
+## Page Table Entry Format (68040/060)
+
+```
+31          12  11  10  9  8  7  6  5  4  3  2  1  0
+┌──────────────┬───┬───┬──┬──┬──┬──┬──┬──┬──┬──┬──┐
+│ Physical Addr│ U1│ U0│ S│CM1│CM0│ M│ U│ W│  UDT  │
+└──────────────┴───┴───┴──┴──┴──┴──┴──┴──┴──┴──┴──┘
+
+UDT: 00=invalid, 01=page descriptor, 10=valid4byte, 11=valid8byte
+W:   write-protected
+U:   used (accessed)
+M:   modified (dirty)
+CM:  cache mode (00=cacheable/writethrough, 01=cacheable/copyback,
+     10=noncacheable/serialized, 11=noncacheable)
+S:   supervisor only
+```
+
+---
+
+## mmu.library (Third-Party)
+
+Several third-party `mmu.library` implementations exist:
+
+| Library | Author | Description |
+|---|---|---|
+| `mmu.library` (MuLib) | Thomas Richter | The standard; used by MuForce, MuGuard, VMM |
+| `68040mmu.library` | Phase5 | Basic 040 MMU setup for CyberStorm |
+
+### MuLib API (Key Functions)
+
+```c
+struct Library *MMUBase = OpenLibrary("mmu.library", 46);
+
+/* Get current MMU context: */
+struct MMUContext *ctx = CurrentContext(MMUBase);
+
+/* Get page properties: */
+ULONG props = GetPageProperties(ctx, address);
+
+/* Set page properties: */
+SetPageProperties(ctx, address, length,
+    MAPP_READABLE | MAPP_WRITABLE,  /* what to set */
+    ~0UL                              /* mask */
+);
+
+/* Remap a virtual page to a different physical address: */
+RemapPage(ctx, virtualAddr, physicalAddr, properties);
+
+/* Flush TLB: */
+RebuildTree(ctx);  /* rebuild MMU tables and flush */
+```
+
+### Property Flags
+
+```c
+#define MAPP_READABLE       (1<<0)
+#define MAPP_WRITABLE       (1<<1)
+#define MAPP_EXECUTABLE     (1<<2)
+#define MAPP_CACHEABLE      (1<<3)
+#define MAPP_COPYBACK       (1<<4)
+#define MAPP_SUPERVISORONLY (1<<5)
+#define MAPP_USERPAGE0      (1<<6)
+#define MAPP_USERPAGE1      (1<<7)
+#define MAPP_GLOBAL         (1<<8)
+#define MAPP_BLANK          (1<<9)   /* invalid/unmapped */
+#define MAPP_SWAPPED        (1<<10)  /* paged out to disk */
+#define MAPP_TRANSLATED     (1<<11)  /* virtual ≠ physical */
+```
+
+---
+
+## Enforcer — How It Uses MMU
+
+Enforcer maps address `$000000–$0003FF` (low memory) and `$00C00000+` (unassigned ranges) as **invalid pages**. Any access to these causes an MMU exception that Enforcer catches, logs, and allows the program to continue:
+
+```
+ENFORCER HIT: 00000000 READ  by task "BadApp" at 0002045A
+```
+
+---
+
+## VMM — Virtual Memory
+
+VMM (Virtual Memory Manager) uses the MMU to implement demand-paged virtual memory:
+1. Maps physical RAM pages into the address space
+2. When RAM is full, pages least-recently-used blocks to a swap file on disk
+3. On access to a swapped-out page → MMU exception → VMM reads page back from disk
+4. Transparent to applications — they see continuous RAM
+
+---
+
+## Direct MMU Programming (No Library)
+
+```asm
+; 68040: Enable MMU with 4K pages
+    ; Set up page tables at PAGE_TABLE_BASE...
+    movec.l  PAGE_TABLE_BASE,urp    ; set User Root Pointer
+    movec.l  PAGE_TABLE_BASE,srp    ; set Supervisor Root Pointer
+    move.l   #$8000,d0              ; TC: E=1, P=0 (4K pages)
+    movec.l  d0,tc                  ; enable translation!
+    pflusha                          ; flush all TLB entries
+
+; 68040: Set transparent translation (map $00000000–$00FFFFFF 1:1)
+    move.l   #$00FFE040,d0          ; base=$00, mask=$FF, E=1, CM=writethrough
+    movec.l  d0,dtt0                ; data transparent translation 0
+    movec.l  d0,itt0                ; instruction transparent translation 0
+```
+
+---
+
+## References
+
+- Motorola: *MC68030 User's Manual* — MMU chapter
+- Motorola: *MC68040 User's Manual* — MMU chapter
+- Motorola: *MC68060 User's Manual* — MMU chapter
+- Thomas Richter: MuLib documentation (Aminet: `util/libs/MMULib.lha`)
+- Enforcer source (public domain)