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/01_hardware/ecs_a600_a3000/README.md
+++ b/01_hardware/ecs_a600_a3000/README.md
@ -0,0 +1,67 @@
+[← Home](../../README.md) · [Hardware](../README.md)
+
+# ECS Chipset — A600 / A3000 / A500+
+
+## Overview
+
+The **Enhanced Chip Set** (ECS) is a significant revision of OCS, shipping from 1990 onward. It adds 2 MB Chip RAM addressing, programmable display timing, and extended registers while maintaining full backward compatibility with OCS software.
+
+## Chip Summary
+
+| Chip | Part | Changes from OCS |
+|---|---|---|
+| **Super Agnus** | MOS 8372A | Addresses 2 MB Chip RAM, extended DMA window |
+| **ECS Denise** | MOS 8373 | BPLCON3, border blank, programmable sync |
+| **Paula** | MOS 8364 | Unchanged |
+
+## Contents
+
+| File | Topic |
+|---|---|
+| [chipset_ecs.md](chipset_ecs.md) | Super Agnus and ECS Denise internals |
+| [ecs_registers_delta.md](ecs_registers_delta.md) | New/changed registers vs OCS |
+| [productivity_modes.md](productivity_modes.md) | Multiscan/productivity display modes |
+| [gary_gayle.md](gary_gayle.md) | Gary (A3000) and Gayle (A600) chips: IDE, PCMCIA |
+| [chip_ram_expansion.md](chip_ram_expansion.md) | 2 MB Chip RAM with Super Agnus |
+
+## ECS vs OCS — Key Differences
+
+| Feature | OCS | ECS |
+|---|---|---|
+| Max Chip RAM | 1 MB (Fat Agnus) | **2 MB** (Super Agnus) |
+| Display sync | Fixed NTSC/PAL | **BEAMCON0** — programmable |
+| Bitplane scroll | 4-bit (BPLCON1) | Extended (ECS Denise) |
+| Border blank | No | **BPLCON3** border control |
+| Hires sprites | No | ECS Denise extended sprite control |
+| DMA window | Smaller | Extended: wider bitplane fetch |
+
+## Identifying ECS at Runtime
+
+```c
+#include <exec/execbase.h>
+
+struct ExecBase *SysBase = *((struct ExecBase **)4);
+/* AttnFlags does not directly identify chipset */
+
+/* Use graphics.library GfxBase->ChipRevBits0 */
+#include <graphics/gfxbase.h>
+struct GfxBase *GfxBase = (struct GfxBase *)OpenLibrary("graphics.library", 0);
+if (GfxBase->ChipRevBits0 & GFXB_BIG_BLITTER) { /* ECS+ */ }
+if (GfxBase->ChipRevBits0 & GFXB_HR_AGNUS)    { /* Super Agnus */ }
+if (GfxBase->ChipRevBits0 & GFXB_HR_DENISE)   { /* ECS Denise */ }
+```
+
+## Machines Using ECS
+
+| Model | Notes |
+|---|---|
+| A3000 | Super Agnus + ECS Denise; 68030; SCSI; Zorro III |
+| A500+ | Super Agnus (1 MB variant); ECS Denise; no IDE |
+| A600 | Super Agnus (1 MB variant); ECS Denise; Gayle; IDE; PCMCIA |
+| A2000 (late) | Some late rev boards shipped with ECS chips |
+
+## References
+
+- ADCD 2.1 Hardware Manual — ECS extension chapters
+- NDK39: `graphics/gfxbase.h` — ChipRevBits0 flags
+- *Amiga Hardware Reference Manual* 3rd ed. — ECS appendix
--- a/01_hardware/ecs_a600_a3000/chip_ram_expansion.md
+++ b/01_hardware/ecs_a600_a3000/chip_ram_expansion.md
@ -0,0 +1,76 @@
+[← Home](../../README.md) · [Hardware](../README.md) · [ECS](README.md)
+
+# 2 MB Chip RAM with Super Agnus
+
+## Overview
+
+The original Agnus (8361/8367) could address only **512 KB** of Chip RAM. The Fat Agnus (later OCS revision) addressed **1 MB**. Super Agnus (8372A) extends the DMA address bus to **21 bits**, allowing **2 MB** of Chip RAM to be addressed by all DMA channels.
+
+## Requirements for 2 MB Chip RAM
+
+All of the following must be present:
+
+1. **Super Agnus 8372A** — 2 MB variant (not all 8372A chips support 2 MB; check marking)
+2. **2 MB of Chip RAM physically installed** — requires modified A3000 or a third-party board
+3. **OS 2.0 or later** — earlier OS does not manage the extended Chip RAM
+
+On the A3000, 2 MB Chip RAM is the standard configuration. On A500/A2000 with Super Agnus, it requires a RAM expansion that adds 1 MB in the Chip RAM window.
+
+## Address Space Layout with 2 MB Chip RAM
+
+```
+$000000–$1FFFFF   2 MB Chip RAM (DMA accessible by all channels)
+$200000+          Fast RAM (CPU only)
+```
+
+The Chip RAM extends from $000000 to $1FFFFF. Previously, $100000–$1FFFFF was "ranger" slow RAM, not DMA-accessible.
+
+## OS Detection and Use
+
+AmigaOS automatically discovers Chip RAM size via the exec memory list:
+
+```c
+/* Check available Chip RAM */
+ULONG chip_free  = AvailMem(MEMF_CHIP);
+ULONG chip_total = AvailMem(MEMF_CHIP | MEMF_TOTAL);
+```
+
+The exec memory list is built at boot time from the chip RAM size detected by the ROM initialisation code, which queries Agnus's internal address counter.
+
+## AmigaOS ROM Initialisation (Exec init)
+
+During cold boot, the Kickstart ROM probes Chip RAM size:
+
+1. Write a test pattern to $100000 (top of 1 MB range)
+2. Read back — if the value matches, 2 MB Chip RAM is present
+3. The exec `MemHeader` for Chip RAM is extended to $1FFFFF
+
+This is performed in the `RomBoot()` → `InitCode()` sequence before the exec memory system is fully initialised.
+
+## Implications for Programming
+
+- **Bitplane pointers** can address any location in the 2 MB range
+- **Copper lists, sprite data, audio samples** can all use the upper 1 MB
+- `AllocMem(size, MEMF_CHIP)` will draw from the full 2 MB pool
+- **MEMF_24BITDMA** is set on Chip RAM to indicate DMA accessibility within the 24-bit space
+
+## Common Pitfall: 1 MB vs 2 MB Super Agnus
+
+Some Super Agnus chips (8372A rev 1) are hardware-limited to 1 MB despite the ECS part number. Identifying the 2 MB variant:
+
+```asm
+; Read the Agnus chip ID from VPOSR
+move.w  $DFF004, d0     ; VPOSR
+and.w   #$7F00, d0      ; mask to chip ID bits
+cmp.w   #$2300, d0      ; 8372A 2MB = ID $23?
+beq     .is_2mb_agnus
+```
+
+Software should not assume 2 MB Chip RAM — always use `AvailMem()` to determine the actual size.
+
+## References
+
+- Commodore A3000 Technical Reference Manual — memory section
+- AmigaMail Vol. 2 — Chip RAM expansion articles
+- NDK39: `exec/memory.h` — MEMF flags
+- ADCD 2.1 Hardware Manual — memory map section
--- a/01_hardware/ecs_a600_a3000/chipset_ecs.md
+++ b/01_hardware/ecs_a600_a3000/chipset_ecs.md
@ -0,0 +1,119 @@
+[← Home](../../README.md) · [Hardware](../README.md) · [ECS](README.md)
+
+# ECS Chipset Internals — Super Agnus & ECS Denise
+
+## Super Agnus (MOS 8372A)
+
+### Chip RAM Addressing
+
+OCS Agnus could only generate 19-bit DMA addresses (512 KB) or 20-bit (1 MB with Fat Agnus). Super Agnus extends this to **21 bits**, addressing 2 MB of Chip RAM.
+
+The revision of Super Agnus present determines the Chip RAM limit:
+
+| Part | Chip RAM Max | Marking |
+|---|---|---|
+| 8372A rev 1 | 1 MB | AGNUS 8372A |
+| 8372A rev 4+ | 2 MB | AGNUS 8372A (2MB) |
+
+> [!NOTE]
+> Software cannot assume 2 MB Chip RAM is available just because Super Agnus is present. The actual installed RAM amount must be checked via `AvailMem(MEMF_CHIP)`.
+
+### Extended DMA Window
+
+Super Agnus extends the bitplane DMA fetch window, allowing:
+- Full overscan displays without copper tricks
+- Access to the full 2 MB address range for all DMA channels
+
+### AGNUS ID Register
+
+Super Agnus provides an ID register readable via the `VPOSR` / `DIWSTRT` path. The chip revision can be read:
+
+```asm
+move.w  VPOSR+custom, d0    ; read VPOSR
+lsr.w   #8, d0              ; shift to get Agnus ID in low byte
+```
+
+| VPOSR[15:8] | Chip | Notes |
+|---|---|---|
+| $00 | OCS Agnus 8367/8361 | Original |
+| $10 | OCS Fat Agnus 8371 | 1 MB PAL |
+| $20 | Super Agnus 8372A | ECS, 1 or 2 MB |
+| $30 | Super Agnus 8372B | Some ECS |
+
+---
+
+## ECS Denise (MOS 8373)
+
+### New Capabilities
+
+ECS Denise adds to OCS Denise (8362):
+
+1. **BPLCON3** — new control register for border colour, sprite bank
+2. **Sub-pixel scrolling** — additional scroll control bits
+3. **Genlock extensions** — improved external sync handling
+4. **Border blank** — BPLCON3 can blank the border area to colour 0
+
+### DENISEID — Revision Register
+
+ECS Denise provides a self-identification register at `$DFF07C` (read only on ECS+):
+
+```asm
+move.w  $DFF07C, d0   ; read DENISEID
+```
+
+| Value | Chip |
+|---|---|
+| $FFFF | OCS Denise 8362 (register not present) |
+| $00FC | ECS Denise 8373 |
+| $00F8 | AGA Lisa |
+
+---
+
+## BPLCON3 — ECS Denise Extension
+
+New register at `$DFF106` (ECS only, must not be written on OCS):
+
+```
+bit 15-13: BANK2-0    — sprite colour bank (AGA: upper 4 bits of colour reg)
+bit 12-10: PF2OF2-0   — playfield 2 colour offset (for dual playfield)
+bit  9:    LOCT       — low colour enable (AGA HAM8 mode)
+bit  6:    BRDRBLNK   — border blank: forces border area to colour 0
+bit  5:    BRDNTRAN   — border not-transparent (disable border transparency)
+bit  4:    ZDCLKEN     — horizontal/vertical count display
+bit  3:    BRDSPRT    — sprites in border area enable
+bit  2:    EXTBLKEN   — external blank signal
+```
+
+**Border blank use:**
+```asm
+move.w  #$0020, $DFF106   ; set BRDRBLNK — blank border area
+```
+
+---
+
+## GfxBase ChipRevBits0 Flags
+
+```c
+/* graphics/gfxbase.h */
+#define GFXB_BIG_BLITTER  0   /* ECS big blitter present */
+#define GFXB_BLITTER_DMA  1
+#define GFXB_HR_AGNUS     2   /* Super Agnus */
+#define GFXB_HR_DENISE    3   /* ECS Denise */
+#define GFXB_AA_ALICE     4   /* AGA Alice */
+#define GFXB_AA_LISA      5   /* AGA Lisa */
+```
+
+Reading chipset type in C:
+```c
+UBYTE rev = GfxBase->ChipRevBits0;
+BOOL is_ecs_agnus  = (rev & (1 << GFXB_HR_AGNUS)) != 0;
+BOOL is_ecs_denise = (rev & (1 << GFXB_HR_DENISE)) != 0;
+BOOL is_aga        = (rev & (1 << GFXB_AA_ALICE))  != 0;
+```
+
+## References
+
+- ADCD 2.1 Hardware Manual — ECS registers, Super Agnus chapter
+- NDK39: `graphics/gfxbase.h`
+- AmigaMail Vol. 2 — ECS chipset programming articles
+- *Amiga Hardware Reference Manual* 3rd ed. — Appendix F (ECS)
--- a/01_hardware/ecs_a600_a3000/ecs_registers_delta.md
+++ b/01_hardware/ecs_a600_a3000/ecs_registers_delta.md
@ -0,0 +1,114 @@
+[← Home](../../README.md) · [Hardware](../README.md) · [ECS](README.md)
+
+# ECS Register Deltas vs OCS
+
+This file documents registers that are **new or changed in ECS** versus OCS. OCS registers not listed here are unchanged.
+
+## New Registers
+
+### BEAMCON0 — $DFF1DC (ECS only)
+
+The most significant new ECS register. Controls display sync generation and timing mode.
+
+```
+bit 15: HARDDIS  — disable hard limits on display window
+bit 14: LPENDIS  — disable light pen latch
+bit 13: VARVBEN  — enable variable VBlank
+bit 12: LOLDIS   — disable long line sync
+bit 11: CSCBEN   — composite sync on colour burst
+bit 10: VARVSYEN — variable vertical sync
+bit  9: VARHSYEN — variable horizontal sync
+bit  8: VARBEAMEN— variable beam enable
+bit  7: DUAL     — dual sync (separate composite + RGB)
+bit  6: PAL      — 1 = PAL timing, 0 = NTSC timing
+bit  5: VARCSYEN — variable composite sync
+bit  4: BLANKEN  — enable blanking signal
+bit  3: CSYTRUE  — composite sync polarity
+bit  2: VSYTRUE  — vertical sync polarity
+bit  1: HSYTRUE  — horizontal sync polarity
+bit  0: MONCSYEN — monochrome composite sync enable
+```
+
+**Default OCS behaviour** is replicated by writing $0000 to BEAMCON0 on ECS.
+
+**PAL/NTSC software switch:**
+```asm
+move.w  #$0020, $DFF1DC    ; BEAMCON0 = PAL mode
+move.w  #$0000, $DFF1DC    ; BEAMCON0 = NTSC mode
+```
+
+**Productivity mode (31 kHz):**
+```asm
+move.w  #$0A00, $DFF1DC    ; VARBEAMEN + VARVSYEN (31 kHz VGA-like)
+```
+
+### BPLCON3 — $DFF106 (ECS Denise only)
+
+New bitplane/sprite control register — see `chipset_ecs.md` for full bit definition.
+
+### DENISEID — $DFF07C (read only, ECS+)
+
+Chip identification — see `chipset_ecs.md`.
+
+## Changed / Extended Registers
+
+### BPLCON0 — $DFF100
+
+OCS BPLCON0 bit 0 (`ECSENA`) is reserved (must be 0) on OCS. On ECS:
+```
+bit 0: ECSENA — 1 = enable ECS features (required to use BPLCON3 etc.)
+```
+
+Must set `ECSENA=1` before programming ECS-specific display modes.
+
+### DIWSTRT / DIWSTOP — $DFF08E / $DFF090
+
+OCS: 8-bit vertical and 8-bit horizontal (limited range).
+
+ECS: `DIWHIGH` ($DFF1E4) extends these to full 12-bit resolution:
+
+### DIWHIGH — $DFF1E4 (ECS only)
+
+```
+bit 15:   FLOP1  — playfield 1 window high bit
+bit 7:    FLOP0  — playfield 0 window high bit
+bit 13-8: HB7-2  — horizontal window stop bits [7:2]
+bit 5-0:  HS7-2  — horizontal window start bits [7:2]
+```
+
+Allows the display window to be positioned anywhere in the extended beam range, enabling full overscan without copper tricks.
+
+### FMODE — $DFF1FC (ECS read, AGA write)
+
+On ECS, `$DFF1FC` is reserved. On AGA it becomes the `FMODE` register (see AGA section).
+
+## ECS-Only DMA Extended Mode
+
+Super Agnus extends the chip bus to allow DMA access across the full 2 MB range. No register change is needed — the chip detects the extended address automatically based on the installed RAM size and its internal revision.
+
+## Programming Notes
+
+> [!WARNING]
+> **OCS compatibility:** Never write to `BEAMCON0`, `BPLCON3`, or `DIWHIGH` on OCS hardware — the addresses are not decoded on OCS and writes may corrupt adjacent chip state or have undefined effects. Always check `GfxBase->ChipRevBits0` before writing ECS registers.
+
+Safe ECS register programming pattern:
+```c
+#include <graphics/gfxbase.h>
+
+extern struct GfxBase *GfxBase;
+
+void set_pal_mode(void) {
+    if (GfxBase->ChipRevBits0 & (1 << GFXB_HR_AGNUS)) {
+        /* Safe to write BEAMCON0 */
+        volatile UWORD *beamcon0 = (UWORD *)0xDFF1DC;
+        *beamcon0 = 0x0020;  /* PAL */
+    }
+}
+```
+
+## References
+
+- ADCD 2.1 Hardware Manual — ECS register descriptions
+- NDK39: `hardware/custom.h` (note: some ECS registers not in OCS struct)
+- AmigaMail Vol. 2 — ECS programming tutorials
+- *Amiga Hardware Reference Manual* 3rd ed. — Appendix F
--- a/01_hardware/ecs_a600_a3000/gary_gayle.md
+++ b/01_hardware/ecs_a600_a3000/gary_gayle.md
@ -0,0 +1,114 @@
+[← Home](../../README.md) · [Hardware](../README.md) · [ECS](README.md)
+
+# Gary & Gayle — System Controller Chips
+
+## Gary (A3000)
+
+**Gary** is the custom system controller chip in the A3000, combining functions that are discrete ICs on the A2000:
+
+- **Bus controller**: Manages the interaction between 68030/68882, chip bus, and Zorro III
+- **Auto-config controller**: Runs the Zorro expansion enumeration
+- **DMA arbitration**: Between 68030, custom chips, and Zorro III DMA
+- **SCSI interface glue**: Works with the A3000's built-in WD33C93 SCSI controller
+- **ROM decode**: Maps Kickstart ROM into the address space
+
+Gary is not directly programmable by user software; its configuration is set by hardware strapping and the ROM initialisation sequence.
+
+## Gayle (A600 / A1200)
+
+**Gayle** is the custom chip providing **IDE** and **PCMCIA** interface on the A600 and A1200. The A600 and A1200 use different Gayle revisions with different PCMCIA pinouts.
+
+### Gayle Identification
+
+```
+A600 Gayle revision ID: read from $DA8000
+A1200 Gayle revision ID: read from $DA8000
+```
+
+```asm
+move.b  $DA8000, d0    ; Read Gayle ID byte
+```
+
+| Byte | Machine |
+|---|---|
+| $D0 | A600 Gayle |
+| $D1 | A1200 Gayle (revision 1) |
+
+### Gayle Register Map (A600/A1200)
+
+| Address | Register | Description |
+|---|---|---|
+| $DA8000 | GAYLE_ID | Chip ID (read shifts bits) |
+| $DA9000 | GAYLE_INT_STATUS | Interrupt status |
+| $DA9004 | GAYLE_INT_ENABLE | Interrupt enable |
+| $DA9008 | GAYLE_CONTROL | Control register |
+
+### IDE Interface
+
+The IDE interface via Gayle is at `$DA0000` (A1200) or `$DA0000` (A600):
+
+| Offset | Register | Description |
+|---|---|---|
+| $DA0000 | DATA | IDE data register (16-bit) |
+| $DA0004 | ERROR/FEATURE | Error (read) / Feature (write) |
+| $DA0008 | SECTOR_COUNT | Sector count |
+| $DA000C | SECTOR_NUMBER | Sector number (LBA 7:0) |
+| $DA0010 | CYLINDER_LOW | Cylinder low (LBA 15:8) |
+| $DA0014 | CYLINDER_HIGH | Cylinder high (LBA 23:16) |
+| $DA0018 | DRIVE_HEAD | Drive/Head/LBA (LBA 27:24) |
+| $DA001C | STATUS/COMMAND | Status (read) / Command (write) |
+| $DA101C | ALT_STATUS | Alternate status (no interrupt clear) |
+| $DA101C | DEVICE_CONTROL | Device control (write) |
+
+> [!NOTE]
+> On the A1200, IDE registers are byte-wide on odd addresses in a 16-bit window. The data register is 16-bit. This differs from standard PC IDE — byte lanes are swapped relative to x86 convention.
+
+### PCMCIA Interface (A600/A1200)
+
+The A600 and A1200 support a Type II PCMCIA (PC Card) slot:
+
+| Address Range | Type | Description |
+|---|---|---|
+| $600000–$9FFFFF | Attribute memory | Card configuration (CIS access) |
+| $A00000–$A3FFFF | Common memory | Modem/network card data |
+| $A40000–$A7FFFF | Common memory (cont.) | |
+| $600000 (Gayle) | Gayle attribute | Gayle own config space |
+
+PCMCIA interrupt routing: Card interrupt → Gayle → CIA-A (`/FLG` pin) → CPU IPL 6.
+
+### Gayle Interrupt Bits
+
+```c
+/* DA9000 GAYLE_INT_STATUS */
+#define GAYLE_IRQ_IDE    (1<<6)  /* IDE drive interrupt */
+#define GAYLE_IRQ_CARD   (1<<5)  /* PCMCIA card interrupt */
+#define GAYLE_IRQ_BVD1   (1<<4)  /* PCMCIA battery voltage 1 */
+#define GAYLE_IRQ_BVD2   (1<<3)  /* PCMCIA battery voltage 2 */
+#define GAYLE_IRQ_WP     (1<<2)  /* PCMCIA write protect */
+#define GAYLE_IRQ_CD     (1<<1)  /* PCMCIA card detect */
+```
+
+### Gayle Power Control
+
+Gayle controls PCMCIA card power (5V / 3.3V on A1200 rev 1D+):
+```c
+/* GAYLE_CONTROL bits */
+#define GAYLE_POW        (1<<7)  /* PCMCIA power on */
+#define GAYLE_WS         (1<<6)  /* wait states for PCMCIA */
+```
+
+## AmigaOS IDE Access
+
+AmigaOS accesses the Gayle IDE through the `scsi.device` or dedicated `ata.device` driver provided with OS 3.1+. Direct IDE programming is done in the filesystem handler (`trackdisk.device` replacement).
+
+The standard path:
+```
+Application → dos.library → File System Handler → scsi.device → Gayle IDE
+```
+
+## References
+
+- Commodore A600 Technical Reference Manual — Gayle chapter
+- Commodore A1200 Technical Reference Manual — Gayle chapter
+- ADCD 2.1 — `Devices_Manual_guide/` scsi.device
+- NDK39: `hardware/gayle.h` (if present), community-documented Gayle registers
--- a/01_hardware/ecs_a600_a3000/productivity_modes.md
+++ b/01_hardware/ecs_a600_a3000/productivity_modes.md
@ -0,0 +1,97 @@
+[← Home](../../README.md) · [Hardware](../README.md) · [ECS](README.md)
+
+# ECS Productivity & Multiscan Display Modes
+
+## Overview
+
+ECS introduces **BEAMCON0** which allows the Amiga to produce non-standard display timings. The most useful are **productivity mode** (~28 kHz / 31 kHz horizontal) and **multiscan mode**, which provide flicker-free, high-resolution displays compatible with standard SVGA monitors.
+
+These modes are available on A3000 and some A2000/A600 configurations with a multisync monitor.
+
+## Standard OCS Timings (for reference)
+
+| Mode | H rate | V rate | Resolution |
+|---|---|---|---|
+| PAL LORES | 15.625 kHz | 50 Hz | 320×256 |
+| PAL HIRES | 15.625 kHz | 50 Hz | 640×256 |
+| NTSC LORES | 15.720 kHz | 60 Hz | 320×200 |
+| NTSC HIRES | 15.720 kHz | 60 Hz | 640×200 |
+| PAL interlace | 15.625 kHz | 50 Hz (25 Hz/field) | 320×512 / 640×512 |
+
+## ECS Multiscan Modes
+
+| Mode | H rate | V rate | Resolution | BEAMCON0 |
+|---|---|---|---|---|
+| Productivity | ~28.6 kHz | 57 Hz | 640×480 | $0A00 |
+| Super72 | ~28.6 kHz | 72 Hz | 800×600 (approx) | varies |
+| DblPAL | 31.25 kHz | 50 Hz | 640×512 | custom |
+| DblNTSC | 31.47 kHz | 60 Hz | 640×400 | custom |
+| VGA-like | 31.47 kHz | 60 Hz | 640×480 | custom |
+
+## Programming Productivity Mode
+
+Productivity mode on the A3000 (PAL, 640×480):
+
+```asm
+; Set BEAMCON0 for variable beam timing
+move.w  #$0A00, $DFF1DC    ; VARBEAMEN | VARVSYEN
+
+; Program horizontal total, sync, blank (custom timing)
+move.w  #$71, $DFF1C0      ; HTOTAL (horizontal total - 1)
+move.w  #$0F, $DFF1C4      ; HSSTRT (H sync start)
+move.w  #$19, $DFF1C6      ; HSSTOP (H sync stop)
+move.w  #$09, $DFF1C8      ; HBSTRT (H blank start)
+move.w  #$71, $DFF1CA      ; HBSTOP (H blank stop)
+
+; Vertical timing
+move.w  #$0242, $DFF1E0    ; VTOTAL
+move.w  #$0015, $DFF1E6    ; VSSTRT
+move.w  #$001D, $DFF1E8    ; VSSTOP
+```
+
+> [!NOTE]
+> The exact register values depend on the target monitor's sync requirements. The A3000's monitor (1084S or Commodore 1950) has a specific timing window. Always consult the monitor's datasheet.
+
+## OS Support: ScreenModes
+
+AmigaOS 3.1 integrates ECS productivity modes through the **screenmode** system:
+
+```c
+#include <graphics/modeid.h>
+#include <libraries/asl.h>
+
+/* Open a 640×480 productivity screen */
+struct Screen *scr = OpenScreenTags(NULL,
+    SA_DisplayID,  PRODDBL_MONITOR_ID | HIRES_KEY,
+    SA_Width,      640,
+    SA_Height,     480,
+    SA_Depth,      4,
+    TAG_DONE);
+```
+
+**Key mode IDs for ECS:**
+```c
+#define MULTISCAN_MONITOR_ID  0x00041000  /* multiscan / productivity */
+#define SUPER72_MONITOR_ID    0x00081000
+#define DBLNTSC_MONITOR_ID    0x00401000
+#define DBLPAL_MONITOR_ID     0x00421000
+```
+
+These IDs are returned by `BestModeID()` and accepted by `OpenScreen()` / `OpenScreenTags()`.
+
+## Hardware Requirements
+
+- **ECS chipset** (Super Agnus + ECS Denise) — required for BEAMCON0
+- **Multisync monitor** — standard 15 kHz PAL/NTSC monitors do not support 31 kHz
+- **A3000** — has built-in multiscan support; A2000 requires a separate scan doubler card
+
+## Flicker Fixer (A2000/A500)
+
+Some Zorro II cards (e.g., Flicker Fixer by MicroWay, Indivision ECS) scan-double the 15 kHz signal to 31 kHz for use with VGA monitors. These operate transparently — no BEAMCON0 programming needed.
+
+## References
+
+- ADCD 2.1 Hardware Manual — ECS display modes
+- AmigaMail Vol. 2 — ECS multiscan articles
+- NDK39: `graphics/modeid.h` — monitor mode IDs
+- A3000 Technical Reference Manual — display timing chapter