🔧 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, game RE, 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 → Game RE → IDA/Ghidra setup
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, AutoConfig protocol, Gayle IDE/PCMCIA
ocs_a500/	OCS chipset: custom registers, copper, blitter, sprites, Paula, A1000 WCS, A2000 Zorro II, CDTV hardware, Gary CSG 5719 system controller (bus arbitration, ROM overlay, AutoConfig, Slow RAM)
ecs_a600_a3000/	ECS chipset: Super Agnus, productivity modes, Gary & Fat Gary system controller (bus arbitration, AutoConfig, SCSI/FPU glue, antipatterns)
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
floppy_vs_hdd_physical_boot.md	Physical hardware mechanisms: floppy MFM streaming, HDD RDB scanning, DMA transfers, failure modes
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
ghidra_setup.md	Ghidra setup & decompilation
compiler_fingerprints.md	SAS/C vs GCC vs VBCC codegen patterns
patching_techniques.md	Binary patching strategies
unpacking_and_decrunching.md	Executable unpacking, decruncher architecture, and manual extraction
custom_loaders_and_drm.md	Bypassing DOS, Trackloaders, and physical DRM tricks
anti_debugging.md	The Cracker vs. Developer arms race: Trace vector abuse, NMI defeat
whdload_architecture.md	WHDLoad internals, slaves, resload_DiskLoad, memory patching
case_studies/ramdrive_device.md	Case Study: ramdrive.device RE walkthrough

Per-Compiler RE Field Manuals	Topic
compilers/sasc.md	SAS/C 5.x/6.x: LINK A5 + 9-reg save, absolute strings, _LibBase globals
compilers/gcc.md	GCC 2.95.x: .text hunk, A6 frame pointer, PC-relative strings, __CTOR_LIST__
compilers/vbcc.md	VBCC: No frame pointer, per-function saves, __reg(), __MERGED hunks
compilers/stormc.md	StormC / StormC++: SAS/C-compatible C, unique C++ ABI, PPC support
compilers/aztec_c.md	Manx Aztec C: D3-D7 save only (5 regs), D2 scratch, pre-1990 era
compilers/lattice_c.md	Lattice C 3.x/4.x: SAS/C predecessor, simpler optimizer, 6-reg save
compilers/dice_c.md	DICE C: No frame pointer, _mainCRTStartup, fast compile speed

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
code_vs_data_disambiguation.md	Distinguishing code bytes from data/variables — Amiga-specific failure modes

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

Language-Specific Analysis	Topic
asm68k_binaries.md	⚠️ Hand-written assembly reversing — demos, games, bootblocks
ansi_c_reversing.md	⚠️ ANSI C reversing — struct recovery, control flow, library anchoring
cpp_vtables_reversing.md	⚠️ C++ OOP reversing — vtables, inheritance, RTTI, name mangling
other_languages.md	⚠️ Non-C languages — AMOS, Blitz Basic, Amiga E, Modula-2, FORTH

Case Studies	Topic
ramdrive_device.md	RAM disk device driver RE

Game Reverse Engineering	Topic
games/game_reversing.md	Game RE deep dive: disassembly, modification, asset extraction, save game analysis

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 deep dive: architecture, pipes & I/O redirection, script cookbook (7 patterns), ReadArgs API, built-in commands, named antipatterns, TRIPOS heritage

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 bitmap layout, baseline rendering, algorithmic styles, AvailFonts enumeration
pixel_conversion.md	Chunky ↔ Planar conversion deep dive: naive, merge/butterfly (Kalms), Copper Chunky, Akiko hardware, Blitter-assisted, RTG bypass, SoA/AoS theory, GPU swizzle modern parallels
animation.md	GEL system deep dive: BOBs, VSprites, AnimObs, hardware foundation (Blitter/Copper/Sprite interaction), collision detection, double buffering, performance tuning
rtg_programming.md	Retargetable Graphics (CyberGraphX/Picasso96): Planar vs Chunky, LockBitMapTags, Pixel Formats, Direct VRAM rendering

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
arexx_integration.md	ARexx integration guide: exposing app features, dispatch, cookbook
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