🔧 Amiga OS 3.1/3.2 — The Developer's Source of Truth

From cold boot to driver authoring

Everything Commodore never published in one place.

A comprehensive, self-contained technical reference for AmigaOS Classic — covering hardware registers, OS internals, reverse engineering, and cross-compilation. Written for developers building on real hardware, FPGA cores, and emulators.

---

Why This Exists

The Amiga's documentation was scattered across out-of-print manuals, Usenet posts, ADCD archives, and tribal knowledge passed between developers since 1985. This repository consolidates it into a single, cross-linked, searchable knowledge base — verified against NDK 3.9 headers and official Commodore documentation.

What's Inside

Layer	Coverage
⚙️ Hardware	Custom chip registers (OCS/ECS/AGA), Copper & Blitter programming, memory architecture (Chip/Fast/Slow RAM), CIA, Zorro bus, CPU feature matrix, per-model hardware (A1000 WCS, A2000 Zorro II, CDTV DMAC/CD-ROM, CD32 Akiko C2P)
🔌 Boot & Init	Cold boot sequence, ROM checksum, resident module scan, Kickstart init, startup-sequence
📦 Binary Format	HUNK executable format (every record type), relocation, debug info, overlays
🔗 Linking & ABI	.fd files, LVO tables, register calling conventions, compiler stubs, SetFunction
🧠 Exec Kernel	Tasks, interrupts, signals, semaphores, memory management, message ports, exception vectors
💾 AmigaDOS	File I/O, filesystem layout (FFS/OFS), CLI/Shell scripting, packet system
🎨 Graphics	Planar bitmaps, Copper deep dive, Blitter deep dive, HAM/EHB modes, sprites, display pipeline
🖥️ Intuition	Screens, windows, IDCMP, GadTools, BOOPSI, menus
📟 Devices	trackdisk, SCSI, serial, parallel, timer, audio, keyboard, console
📚 Libraries	utility, expansion, IFFParse, locale, ARexx, math, layers, diskfont, DataTypes, AmigaGuide, translator (speech)
🌐 Networking	bsdsocket.library API, SANA-II, TCP/IP stacks comparison
🛠️ Toolchain	GCC (bebbo/Codeberg), vasm/vlink, SAS/C, NDK, Makefiles, debugging
🔍 Reverse Engineering	IDA/Ghidra setup, compiler fingerprints, binary patching, 3 case studies
🧮 FPU, MMU & Cache	68881/68882 FPU architecture, 68040/060 Line-F FPU emulation, PMMU page tables, cache coherency
🏗️ Driver Development	exec.device framework, SANA-II network drivers, Picasso96/RTG, AHI audio

Quick Start

You are...	Start here
New to Amiga	History & chipsets → Boot sequence → Exec kernel
Writing code	Toolchain setup → Calling conventions → .fd files
Doing hardware	Address space → Memory types → Custom registers → Copper programming
Reverse engineering	RE methodology → IDA/Ghidra setup → API call identification
Building an FPGA core	Hardware models → AGA chipset → 68040/060 libs

---

Scope: AmigaOS Classic 3.1 (Kickstart 40.x) and 3.2 (Kickstart 47.x). Hardware coverage spans all chipset generations: OCS, ECS, AGA.

Sources

Reference	URL / Path
ADCD 2.1 Online	http://amigadev.elowar.com/read/ADCD_2.1/
NDK 3.9	Aminet: dev/misc/NDK39.lha (free)
NDK 3.2	Hyperion Entertainment (commercial)

| ROM Kernel Manual: Libraries | ADCD 2.1 → Libraries_Manual_guide/ | | ROM Kernel Manual: Devices | ADCD 2.1 → Devices_Manual_guide/ | | ROM Kernel Manual: Hardware | ADCD 2.1 → Hardware_Manual_guide/ | | Includes & Autodocs | ADCD 2.1 → Includes_and_Autodocs_3._guide/ |

---

Documentation Map

00 — Overview

File	Topic
history.md	Amiga lineage, chipset generations timeline
hardware_models.md	Per-model specification table
os_versions.md	OS 3.0 → 3.1 → 3.2 delta matrix

01 — Hardware (by chipset generation)

Folder	Coverage
common/	M68k CPU, address space, memory types (Chip/Fast/Slow RAM), CIA chips, Zorro bus, Gayle IDE/PCMCIA
ocs_a500/	OCS chipset: custom registers, copper, blitter, sprites, Paula, A1000 WCS, A2000 Zorro II, CDTV hardware
ecs_a600_a3000/	ECS chipset: Super Agnus, productivity modes, Gary system controller
aga_a1200_a4000/	AGA chipset: Alice, Lisa, copper, blitter (64-bit), palette, CD32 Akiko, A4000T SCSI

02 — Boot Sequence

File	Topic
cold_boot.md	Power-on: CPU reset vectors, ROM checksum, hardware reset, memory detection, diagnostic indicators
kickstart_rom.md	Kickstart ROM internals: binary structure, module inventory, extraction tools, custom ROM building
kickstart_init.md	ExecBase creation, capture vectors, ROM scan algorithm, 4-phase resident init
dos_boot.md	strap module, boot block format and execution, MountList, Startup-Sequence walkthrough
early_startup.md	Early Startup Control menu: device selection, display mode, recovery scenarios

03 — Executable Loader & HUNK Format

File	Topic
hunk_format.md	Complete HUNK specification — all 22 type codes, wire format, memory flags, advisory bits
hunk_ext_deep_dive.md	HUNK_EXT: exports (EXT_DEF), imports (EXT_REF32), commons, linker resolution
hunk_relocation.md	Relocation mechanics: visual before/after, RELOC32/SHORT/DREL32, PC-relative impact
hunk_debug_info.md	HUNK_SYMBOL and HUNK_DEBUG: stabs format, debugger consumption, stripping
exe_load_pipeline.md	LoadSeg → AllocMem → relocation → segment chain → CreateProc → entry point
object_file_format.md	HUNK_UNIT object files, multi-section layout, HUNK_LIB archives, linker operation
overlay_system.md	HUNK_OVERLAY: tree architecture, runtime overlay manager, modern alternatives
exe_crunchers.md	Executable packers: PP20/Imploder/Shrinkler, decrunch stubs, algorithms, detection

04 — Linking & Library Integration

File	Topic
library_structure.md	Library memory layout, JMP table encoding, MakeLibrary, complete library creation example
shared_libraries_runtime.md	OpenLibrary resolution, ramlib disk loader, version negotiation, expunge mechanics
register_conventions.md	Register ABI: integer, FPU, varargs/TagItem, small-data model, __saveds
fd_files.md	.fd descriptor format, LVO calculation, proto/inline generation
lvo_table.md	Complete exec.library LVO table, IDA reconstruction script
compiler_stubs.md	SAS/C, GCC, VBCC call patterns — compiler signature identification
inline_stubs.md	Pragma (SAS/C), inline asm (GCC), __reg (VBCC), stub generation tools
link_libraries.md	amiga.lib, sc.lib, libnix, auto.lib, WBStartup glue, stack cookie
startup_code.md	c.o / gcrt0.S: entry contract, CLI vs WB detection, argument parsing
setfunction.md	Runtime function patching: canonical pattern, chaining, RE detection

05 — Reverse Engineering

File	Topic
methodology.md	General Amiga RE workflow
ida_setup.md	IDA Pro setup for Amiga binaries
compiler_fingerprints.md	SAS/C vs GCC vs VBCC codegen patterns
patching_techniques.md	Binary patching strategies

Static Analysis	Topic
api_call_identification.md	Recognising OS API calls in disassembly
hunk_reconstruction.md	Rebuilding HUNK structure
library_jmp_table.md	Decoding library JMP tables
m68k_codegen_patterns.md	Compiler-specific assembly idioms
string_xref_analysis.md	String cross-reference hunting
struct_recovery.md	Recovering C structures from assembly

Dynamic Analysis	Topic
enforcer_mungwall.md	Enforcer, MungWall memory debugging
setfunction_patching.md	Runtime function hooking
live_memory_probing.md	Live memory inspection
serial_debug.md	Serial debug output

| ramdrive_device.md | RAM disk device driver RE |

06 — Exec Kernel (OS 3.1/3.2)

File	Topic
exec_base.md	ExecBase — absolute address $4, system lists, hardware detection, structure layout
multitasking.md	Multitasking deep-dive — scheduler, context switching, IPC, memory safety, real-world scenarios
tasks_processes.md	Task/Process structs, state machine, creation, cleanup, priority guidelines
library_system.md	Library node, OpenLibrary lifecycle, expunge mechanics, version management
library_vectors.md	JMP table, LVO offsets, MakeFunctions, SetFunction patching
interrupts.md	Interrupt levels 1–6, INTENA/INTREQ, server chains, CIA interrupts, software interrupts
exceptions_traps.md	M68k exception vectors, TRAP handlers, Guru Meditation decoder, Line-F emulation
memory_management.md	AllocMem/AllocVec, MEMF flags, pools, fragmentation, MemHeader internals
message_ports.md	MsgPort, PutMsg, GetMsg, WaitPort, ownership rules, request-reply pattern
signals.md	AllocSignal, Signal, Wait, SetSignal, multi-source event loop patterns
semaphores.md	SignalSemaphore, shared/exclusive locking, deadlock avoidance, decision guide
io_requests.md	IORequest, DoIO, SendIO, CheckIO, AbortIO, IOF_QUICK, timer device example
lists_nodes.md	MinList/List/Node traversal, sentinel design, Enqueue, safe iteration
resident_modules.md	RomTag, RTF_AUTOINIT, boot priority, ROM scan, disk-resident loading

07 — AmigaDOS

File	Topic
dos_base.md	DosLibrary structure and global state
file_io.md	Open/Read/Write, FileHandle, BPTR
locks_examine.md	Lock/UnLock, Examine, FileInfoBlock
pattern_matching.md	ParsePattern, MatchPattern
process_management.md	CreateNewProc, SystemTagList
packet_system.md	DosPacket, ACTION_* codes
filesystem.md	FFS/OFS block layout, hash, checksum
environment.md	GetVar/SetVar, local/global env variables
error_handling.md	IoErr, error codes, PrintFault
cli_shell.md	CLI/Shell: pipes, redirection, scripts, ReadArgs

08 — Graphics

File	Topic
gfx_base.md	GfxBase, chip detection, PAL/NTSC
bitmap.md	Planar BitMap, pixel layout, allocation
copper.md	Copper coprocessor, MOVE/WAIT/SKIP, UCopList
copper_programming.md	Copper deep dive: architecture, system diagram, examples
blitter.md	Blitter DMA, minterms, BltBitMap
blitter_programming.md	Blitter deep dive: cookie-cut, fill, line draw
sprites.md	Hardware sprites, SimpleSprite
rastport.md	RastPort, drawing primitives, layers
views.md	View/ViewPort, MakeVPort, display pipeline
text_fonts.md	TextFont, OpenFont, text rendering
display_modes.md	ModeID, display database
ham_ehb_modes.md	HAM6, HAM8, EHB special display modes
animation.md	GEL system: BOBs, VSprites, AnimObs

09 — Intuition

File	Topic
intuition_base.md	IntuitionBase global state
screens.md	OpenScreen, SA_ tags, public screens
windows.md	OpenWindow, WA_ tags, event loop
gadgets.md	GadTools, BOOPSI gadgets
menus.md	MenuStrip construction
requesters.md	EasyRequest, ASL file/font requesters
idcmp.md	IDCMP message classes, IntuiMessage
boopsi.md	BOOPSI object system, custom classes
input_events.md	InputEvent, Commodities Exchange
commodities.md	Commodities Exchange: hotkeys, screen blankers, CxObject API

10 — Devices

File	Topic
trackdisk.md	Floppy I/O, geometry
scsi.md	Hard disk, HD_SCSICMD
serial.md	RS-232 serial
parallel.md	Centronics parallel
timer.md	Timing, delays, E-clock
audio.md	DMA audio channels
keyboard.md	Keycodes, key matrix
gameport.md	Joystick and mouse
input.md	Event stream merging
console.md	Text terminal, escape sequences

11 — Libraries

File	Topic
utility.md	TagItems, hooks, date utilities
expansion.md	Zorro bus, AutoConfig
icon.md	Workbench icons, DiskObject
workbench.md	WBStartup, AppWindow
iffparse.md	IFF file parsing: ILBM/8SVX/ANIM, nested chunks, ByteRun1, PBM deinterleaving, clipboard, decision guide vs DataTypes
locale.md	Internationalization, catalogs
keymap.md	Keyboard mapping, MapRawKey
rexxsyslib.md	ARexx interface
mathffp.md	Floating point libraries, FFP, IEEE
layers.md	Window clipping layers
diskfont.md	Bitmap fonts: .font file format, FontContentsHeader, glyph bitmap layout, FONTS: assign, adding fonts, bitmap vs TrueType, Compugraphic outline fonts
datatypes.md	DataTypes system: object-oriented file loading for images, sound, text, animation
amigaguide.md	AmigaGuide hypertext help system: database format, API, context-sensitive help
translator.md	translator.library: English-to-phonetic translation, narrator.device integration, ARPABET phonemes

12 — Networking

File	Topic
bsdsocket.md	BSD socket API deep dive: event-loop patterns, WaitSelect signal integration, non-blocking I/O, multi-socket design, performance
sana2.md	SANA-II device driver interface
tcp_ip_stacks.md	AmiTCP vs Miami vs Roadshow
protocols.md	DNS, HTTP, DHCP

13 — Toolchain

File	Topic
vasm_vlink.md	vasm assembler & vlink linker: modular architecture, Devpac/PhxAss compatibility, optimization system, linker scripts, C↔asm interop, 30+ output formats
gcc_amiga.md	m68k-amigaos-gcc (bebbo fork, Codeberg)
vbcc.md	VBCC cross-compiler: __reg() register control, AmigaOS/MorphOS/AROS, vlink, fast compile times
sasc.md	SAS/C 6.x compiler
stormc.md	StormC native IDE and C/C++ compiler
fd_files.md	FD/SFD file format, Python parser
pragmas.md	Compiler pragmas, inline stubs
ndk.md	NDK versions, contents, downloads
makefiles.md	Cross-compilation Makefile patterns
debugging.md	Enforcer, SnoopDOS, GDB remote, kprintf

14 — References

File	Topic
custom_chip_registers.md	Complete custom chip register map
exec_lvo_table.md	exec.library LVO table
dos_lvo_table.md	dos.library LVO table
error_codes.md	DOS error code reference

15 — FPU, MMU & Cache

File	Topic
fpu_architecture.md	FPU architecture & history: 68881/68882, 68040/060 FPU, die budget, transistor counts, coprocessor interface, FPU vs soft-float benchmarks, Amiga FPU accelerator landscape
68040_68060_libraries.md	68040/060 FPU and instruction emulation libraries
mmu_management.md	MMU page tables, mmu.library, Enforcer, VMM
cache_management.md	CacheClearU, CACR, DMA coherency

16 — Driver Development

File	Topic
device_driver_basics.md	Exec device framework, BeginIO/AbortIO
sana2_driver.md	Writing SANA-II network drivers
rtg_driver.md	Writing Picasso96/RTG display drivers
ahi_driver.md	Writing AHI audio drivers