🔧 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 with worked examples, CIA, Zorro bus, CPU feature matrix
🔌 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
🌐 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
🧮 CPU & MMU	68040/060 Line-F emulation libs, PMMU page tables, cache management
🏗️ 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 → 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, CIA chips, Zorro bus
ocs_a500/	OCS chipset: custom registers, copper, blitter, sprites, Paula
ecs_a600_a3000/	ECS chipset: Super Agnus, productivity modes, Gary, Gayle
aga_a1200_a4000/	AGA chipset: Alice, Lisa, copper, blitter (64-bit), palette, Gayle IDE

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

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
locale.md	Internationalisation, catalogs
keymap.md	Keyboard mapping, MapRawKey
rexxsyslib.md	ARexx interface
mathffp.md	Floating point libraries, FFP, IEEE
layers.md	Window clipping layers
diskfont.md	Disk-based font loading

12 — Networking

File	Topic
bsdsocket.md	BSD socket API, WaitSelect
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
gcc_amiga.md	m68k-amigaos-gcc (bebbo fork, Codeberg)
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 — CPU & MMU

File	Topic
68040_68060_libraries.md	68040/060 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