amiga-bootcamp/README.md

# 🔧 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](00_overview/history.md) → [Boot sequence](02_boot_sequence/cold_boot.md) → [Exec kernel](06_exec_os/exec_base.md) |
| **Writing code** | [Toolchain setup](13_toolchain/gcc_amiga.md) → [Calling conventions](04_linking_and_libraries/register_conventions.md) → [.fd files](04_linking_and_libraries/fd_files.md) |
| **Doing hardware** | [Address space](01_hardware/common/address_space.md) → [Custom registers](01_hardware/ocs_a500/custom_registers.md) → [Copper programming](08_graphics/copper_programming.md) |
| **Reverse engineering** | [RE methodology](05_reversing/methodology.md) → [IDA/Ghidra setup](05_reversing/ida_setup.md) → [API call identification](05_reversing/static/api_call_identification.md) |
| **Building an FPGA core** | [Hardware models](00_overview/hardware_models.md) → [AGA chipset](01_hardware/aga_a1200_a4000/chipset_aga.md) → [68040/060 libs](15_cpu_and_mmu/68040_68060_libraries.md) |

---

> **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](00_overview/history.md) | Amiga lineage, chipset generations timeline |
| [hardware_models.md](00_overview/hardware_models.md) | Per-model specification table |
| [os_versions.md](00_overview/os_versions.md) | OS 3.0 → 3.1 → 3.2 delta matrix |

### 01 — Hardware (by chipset generation)
| Folder | Coverage |
|---|---|
| [common/](01_hardware/common/) | M68k CPU, address space, CIA chips, Zorro bus |
| [ocs_a500/](01_hardware/ocs_a500/) | OCS chipset: custom registers, copper, blitter, sprites, Paula |
| [ecs_a600_a3000/](01_hardware/ecs_a600_a3000/) | ECS chipset: Super Agnus, productivity modes, Gary, Gayle |
| [aga_a1200_a4000/](01_hardware/aga_a1200_a4000/) | AGA chipset: Alice, Lisa, copper, blitter (64-bit), palette, Gayle IDE |

### 02 — Boot Sequence
| File | Topic |
|---|---|
| [cold_boot.md](02_boot_sequence/cold_boot.md) | Power-on, ROM checksum, memory detection |
| [kickstart_init.md](02_boot_sequence/kickstart_init.md) | ROM scan, ExecBase creation, resident modules |
| [dos_boot.md](02_boot_sequence/dos_boot.md) | Bootstrap, mount list, startup-sequence |
| [early_startup.md](02_boot_sequence/early_startup.md) | Early Startup Control menu, boot options |

### 03 — Executable Loader & HUNK Format
| File | Topic |
|---|---|
| [hunk_format.md](03_loader_and_exec_format/hunk_format.md) | Complete HUNK binary specification |
| [hunk_ext_deep_dive.md](03_loader_and_exec_format/hunk_ext_deep_dive.md) | Exports, imports, commons |
| [hunk_relocation.md](03_loader_and_exec_format/hunk_relocation.md) | Relocation mechanics |
| [hunk_debug_info.md](03_loader_and_exec_format/hunk_debug_info.md) | Debug symbols, stabs |
| [exe_load_pipeline.md](03_loader_and_exec_format/exe_load_pipeline.md) | LoadSeg → Process creation |
| [object_file_format.md](03_loader_and_exec_format/object_file_format.md) | Compiler object files |
| [overlay_system.md](03_loader_and_exec_format/overlay_system.md) | HUNK_OVERLAY mechanism |

### 04 — Linking & Library Integration
| File | Topic |
|---|---|
| [fd_files.md](04_linking_and_libraries/fd_files.md) | .fd descriptor format, fd2pragma |
| [lvo_table.md](04_linking_and_libraries/lvo_table.md) | Library vector offsets |
| [library_structure.md](04_linking_and_libraries/library_structure.md) | struct Library, JMP table layout |
| [inline_stubs.md](04_linking_and_libraries/inline_stubs.md) | SAS/C, GCC, VBCC inline stubs |
| [compiler_stubs.md](04_linking_and_libraries/compiler_stubs.md) | Compiler-generated stub code |
| [link_libraries.md](04_linking_and_libraries/link_libraries.md) | amiga.lib, startup objects |
| [shared_libraries_runtime.md](04_linking_and_libraries/shared_libraries_runtime.md) | OpenLibrary lifecycle |
| [register_conventions.md](04_linking_and_libraries/register_conventions.md) | M68k AmigaOS calling conventions |
| [setfunction.md](04_linking_and_libraries/setfunction.md) | SetFunction patching mechanism |
| [startup_code.md](04_linking_and_libraries/startup_code.md) | Program startup and exit |

### 05 — Reverse Engineering
| File | Topic |
|---|---|
| [methodology.md](05_reversing/methodology.md) | General Amiga RE workflow |
| [ida_setup.md](05_reversing/ida_setup.md) | IDA Pro setup for Amiga binaries |
| [compiler_fingerprints.md](05_reversing/compiler_fingerprints.md) | SAS/C vs GCC vs VBCC codegen patterns |
| [patching_techniques.md](05_reversing/patching_techniques.md) | Binary patching strategies |

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

| Dynamic Analysis | Topic |
|---|---|
| [enforcer_mungwall.md](05_reversing/dynamic/enforcer_mungwall.md) | Enforcer, MungWall memory debugging |
| [setfunction_patching.md](05_reversing/dynamic/setfunction_patching.md) | Runtime function hooking |
| [live_memory_probing.md](05_reversing/dynamic/live_memory_probing.md) | Live memory inspection |
| [serial_debug.md](05_reversing/dynamic/serial_debug.md) | Serial debug output |

| [ramdrive_device.md](05_reversing/case_studies/ramdrive_device.md) | RAM disk device driver RE |

### 06 — Exec Kernel (OS 3.1/3.2)
| File | Topic |
|---|---|
| [exec_base.md](06_exec_os/exec_base.md) | ExecBase structure |
| [library_system.md](06_exec_os/library_system.md) | Library lifecycle |
| [library_vectors.md](06_exec_os/library_vectors.md) | JMP table, SetFunction |
| [tasks_processes.md](06_exec_os/tasks_processes.md) | Multitasking |
| [interrupts.md](06_exec_os/interrupts.md) | Interrupt levels, INTENA |
| [exceptions_traps.md](06_exec_os/exceptions_traps.md) | Exception vectors, TRAP instructions, Guru codes |
| [memory_management.md](06_exec_os/memory_management.md) | AllocMem, MEMF flags |
| [message_ports.md](06_exec_os/message_ports.md) | PutMsg/GetMsg/WaitPort |
| [signals.md](06_exec_os/signals.md) | AllocSignal, Wait |
| [semaphores.md](06_exec_os/semaphores.md) | ObtainSemaphore |
| [io_requests.md](06_exec_os/io_requests.md) | IORequest, DoIO/SendIO |
| [lists_nodes.md](06_exec_os/lists_nodes.md) | MinList, Node, Enqueue |
| [resident_modules.md](06_exec_os/resident_modules.md) | RomTag, RTF_AUTOINIT |

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

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

### 09 — Intuition
| File | Topic |
|---|---|
| [intuition_base.md](09_intuition/intuition_base.md) | IntuitionBase global state |
| [screens.md](09_intuition/screens.md) | OpenScreen, SA_ tags, public screens |
| [windows.md](09_intuition/windows.md) | OpenWindow, WA_ tags, event loop |
| [gadgets.md](09_intuition/gadgets.md) | GadTools, BOOPSI gadgets |
| [menus.md](09_intuition/menus.md) | MenuStrip construction |
| [requesters.md](09_intuition/requesters.md) | EasyRequest, ASL file/font requesters |
| [idcmp.md](09_intuition/idcmp.md) | IDCMP message classes, IntuiMessage |
| [boopsi.md](09_intuition/boopsi.md) | BOOPSI object system, custom classes |
| [input_events.md](09_intuition/input_events.md) | InputEvent, Commodities Exchange |

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

### 11 — Libraries
| File | Topic |
|---|---|
| [utility.md](11_libraries/utility.md) | TagItems, hooks, date utilities |
| [expansion.md](11_libraries/expansion.md) | Zorro bus, AutoConfig |
| [icon.md](11_libraries/icon.md) | Workbench icons, DiskObject |
| [workbench.md](11_libraries/workbench.md) | WBStartup, AppWindow |
| [iffparse.md](11_libraries/iffparse.md) | IFF file parsing, ILBM/8SVX |
| [locale.md](11_libraries/locale.md) | Internationalisation, catalogs |
| [keymap.md](11_libraries/keymap.md) | Keyboard mapping, MapRawKey |
| [rexxsyslib.md](11_libraries/rexxsyslib.md) | ARexx interface |
| [mathffp.md](11_libraries/mathffp.md) | Floating point libraries, FFP, IEEE |
| [layers.md](11_libraries/layers.md) | Window clipping layers |
| [diskfont.md](11_libraries/diskfont.md) | Disk-based font loading |

### 12 — Networking
| File | Topic |
|---|---|
| [bsdsocket.md](12_networking/bsdsocket.md) | BSD socket API, WaitSelect |
| [sana2.md](12_networking/sana2.md) | SANA-II device driver interface |
| [tcp_ip_stacks.md](12_networking/tcp_ip_stacks.md) | AmiTCP vs Miami vs Roadshow |
| [protocols.md](12_networking/protocols.md) | DNS, HTTP, DHCP |

### 13 — Toolchain
| File | Topic |
|---|---|
| [vasm_vlink.md](13_toolchain/vasm_vlink.md) | vasm assembler, vlink linker |
| [gcc_amiga.md](13_toolchain/gcc_amiga.md) | m68k-amigaos-gcc (bebbo fork, Codeberg) |
| [sasc.md](13_toolchain/sasc.md) | SAS/C 6.x compiler |
| [fd_files.md](13_toolchain/fd_files.md) | FD/SFD file format, Python parser |
| [pragmas.md](13_toolchain/pragmas.md) | Compiler pragmas, inline stubs |
| [ndk.md](13_toolchain/ndk.md) | NDK versions, contents, downloads |
| [makefiles.md](13_toolchain/makefiles.md) | Cross-compilation Makefile patterns |
| [debugging.md](13_toolchain/debugging.md) | Enforcer, GDB remote, BareFoot |

### 14 — References
| File | Topic |
|---|---|
| [custom_chip_registers.md](14_references/custom_chip_registers.md) | Complete custom chip register map |
| [exec_lvo_table.md](14_references/exec_lvo_table.md) | exec.library LVO table |
| [dos_lvo_table.md](14_references/dos_lvo_table.md) | dos.library LVO table |
| [error_codes.md](14_references/error_codes.md) | DOS error code reference |

### 15 — CPU & MMU
| File | Topic |
|---|---|
| [68040_68060_libraries.md](15_cpu_and_mmu/68040_68060_libraries.md) | 68040/060 instruction emulation libraries |
| [mmu_management.md](15_cpu_and_mmu/mmu_management.md) | MMU page tables, mmu.library, Enforcer, VMM |
| [cache_management.md](15_cpu_and_mmu/cache_management.md) | CacheClearU, CACR, DMA coherency |

### 16 — Driver Development
| File | Topic |
|---|---|
| [device_driver_basics.md](16_driver_development/device_driver_basics.md) | Exec device framework, BeginIO/AbortIO |
| [sana2_driver.md](16_driver_development/sana2_driver.md) | Writing SANA-II network drivers |
| [rtg_driver.md](16_driver_development/rtg_driver.md) | Writing Picasso96/RTG display drivers |
| [ahi_driver.md](16_driver_development/ahi_driver.md) | Writing AHI audio drivers |