mirror of
https://github.com/alfishe/amiga-bootcamp.git
synced 2026-06-12 16:16:28 +00:00
26 KiB
26 KiB
🔧 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 |
| kickstart-boot-diagnostics.md | Kickstart POST: color-screen self-test, 7-phase ColdStart, coldCrash handler, diagnostic cartridge, troubleshooting |
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 |
| games/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 |
| cdfs.md | CD-ROM filesystems: ISO 9660, Rock Ridge, Joliet, UDF, HFS; 7 handler implementations; architecture; hardware platforms |
| 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 |
| display_modes.md | ModeID selection flowchart, CRT vs flat-panel, interlace/progressive tradeoffs, named antipatterns, FPGA/MiSTer impact, historical context, modern analogies, FAQ |
| ham_ehb_modes.md | HAM6/HAM8 encoding pipeline, EHB half-brite, fringing, palette programming, FPGA decoder logic |
| 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 |
| frameworks/mui/ | MUI (Magic User Interface): architecture, layout system, widgets, custom classes, events, reference snippets |
10 — Devices
| File | Topic |
|---|---|
| trackdisk.md | Floppy I/O, geometry |
| scsi.md | Hard disk, HD_SCSICMD |
| atapi.md | ATA/ATAPI wire protocol, packet commands, CF, removable media |
| 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 |
17 — Demoscene Techniques
| File | Topic |
|---|---|
| README.md | Section overview: technique classification, DMA budget, famous effects table |
| copper_effects.md | Copper bars, raster splits, gradient shading, sine-based color cycling, double-buffered lists |
| sprite_techniques.md | Sprite multiplexing, sprite-built images, 15-color attached sprites, priority control |
| pixel_tricks.md | Copper chunky, HAM art, scroll-register distortion, modulo wrapping, plasma effects |
| 3d_rendering.md | Fixed-point 3D math, Blitter-filled polygons, rotozoom, dot tunnels, voxel space |
| timing_optimization.md | Cycle counting, Blitter-CPU interleaving, memory access patterns, self-modifying code |