rslr/amiga-bootcamp
1
0
Fork 0
mirror of https://github.com/alfishe/amiga-bootcamp.git synced 2026-06-13 00:26:28 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
amiga-bootcamp/README.md
Ilia Sharin c4522ef2ed Add memory types article, expand blitter cookbook, update cross-references 
New articles:
- 01_hardware/common/memory_types.md: comprehensive Chip/Fast/Slow RAM reference
  with DMA accessibility matrix, per-model configurations (A500-A4000),
  accelerator memory expansion (classic + modern), adaptive software behavior,
  pitfalls with impact analysis, FPGA/emulation notes
- AGENTS.md: documentation standards and methodology guidelines

Blitter programming (08_graphics/blitter_programming.md):
- Rewrote minterm truth table with narrative explanation and worked  example
- Added 7 advanced use cases with assembly/C code: shifted BOB, hardware scroll,
  area fill polygon, interleaved bitplane BOBs, double-buffered game loop,
  GUI window drag, tile map renderer
- Added Good/Bad Patterns section with 5 named antipatterns
- Added Practical Limitations table (10 constraints with workarounds)
- Expanded Common Minterms table with Description and Real-World Use Case columns

Cross-reference updates:
- Root README: added memory types to coverage, quick start, section index
- 01_hardware/README: updated common/ folder description
- address_space.md: linked to memory_types.md and chip_ram_expansion.md
- memory_management.md (exec): linked to hardware memory types reference
- bitmap.md, sprites.md, animation.md, audio.md: linked to memory_types.md
  explaining DMA Chip RAM requirement for each subsystem
- chip_ram_expansion.md: linked to comprehensive memory types article
2026-04-25 14:12:46 -04:00

276 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 🔧 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, memory architecture (Chip/Fast/Slow RAM), 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) → [Memory types](01_hardware/common/memory_types.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, **memory types (Chip/Fast/Slow RAM)**, 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: CPU reset vectors, ROM checksum, hardware reset, memory detection, diagnostic indicators |
| [**kickstart_rom.md**](02_boot_sequence/kickstart_rom.md) | **Kickstart ROM internals: binary structure, module inventory, extraction tools, custom ROM building** |
| [kickstart_init.md](02_boot_sequence/kickstart_init.md) | ExecBase creation, capture vectors, ROM scan algorithm, 4-phase resident init |
| [dos_boot.md](02_boot_sequence/dos_boot.md) | strap module, boot block format and execution, MountList, Startup-Sequence walkthrough |
| [early_startup.md](02_boot_sequence/early_startup.md) | Early Startup Control menu: device selection, display mode, recovery scenarios |
### 03 — Executable Loader & HUNK Format
| File | Topic |
|---|---|
| [hunk_format.md](03_loader_and_exec_format/hunk_format.md) | Complete HUNK specification — all 22 type codes, wire format, memory flags, advisory bits |
| [hunk_ext_deep_dive.md](03_loader_and_exec_format/hunk_ext_deep_dive.md) | HUNK_EXT: exports (EXT_DEF), imports (EXT_REF32), commons, linker resolution |
| [hunk_relocation.md](03_loader_and_exec_format/hunk_relocation.md) | Relocation mechanics: visual before/after, RELOC32/SHORT/DREL32, PC-relative impact |
| [hunk_debug_info.md](03_loader_and_exec_format/hunk_debug_info.md) | HUNK_SYMBOL and HUNK_DEBUG: stabs format, debugger consumption, stripping |
| [exe_load_pipeline.md](03_loader_and_exec_format/exe_load_pipeline.md) | LoadSeg → AllocMem → relocation → segment chain → CreateProc → entry point |
| [object_file_format.md](03_loader_and_exec_format/object_file_format.md) | HUNK_UNIT object files, multi-section layout, HUNK_LIB archives, linker operation |
| [overlay_system.md](03_loader_and_exec_format/overlay_system.md) | HUNK_OVERLAY: tree architecture, runtime overlay manager, modern alternatives |
| [**exe_crunchers.md**](03_loader_and_exec_format/exe_crunchers.md) | **Executable packers: PP20/Imploder/Shrinkler, decrunch stubs, algorithms, detection** |
### 04 — Linking & Library Integration
| File | Topic |
|---|---|
| [library_structure.md](04_linking_and_libraries/library_structure.md) | Library memory layout, JMP table encoding, MakeLibrary, complete library creation example |
| [shared_libraries_runtime.md](04_linking_and_libraries/shared_libraries_runtime.md) | OpenLibrary resolution, ramlib disk loader, version negotiation, expunge mechanics |
| [register_conventions.md](04_linking_and_libraries/register_conventions.md) | Register ABI: integer, FPU, varargs/TagItem, small-data model, __saveds |
| [fd_files.md](04_linking_and_libraries/fd_files.md) | .fd descriptor format, LVO calculation, proto/inline generation |
| [lvo_table.md](04_linking_and_libraries/lvo_table.md) | Complete exec.library LVO table, IDA reconstruction script |
| [compiler_stubs.md](04_linking_and_libraries/compiler_stubs.md) | SAS/C, GCC, VBCC call patterns — compiler signature identification |
| [inline_stubs.md](04_linking_and_libraries/inline_stubs.md) | Pragma (SAS/C), inline asm (GCC), __reg (VBCC), stub generation tools |
| [link_libraries.md](04_linking_and_libraries/link_libraries.md) | amiga.lib, sc.lib, libnix, auto.lib, WBStartup glue, stack cookie |
| [startup_code.md](04_linking_and_libraries/startup_code.md) | c.o / gcrt0.S: entry contract, CLI vs WB detection, argument parsing |
| [setfunction.md](04_linking_and_libraries/setfunction.md) | Runtime function patching: canonical pattern, chaining, RE detection |
### 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 — absolute address $4, system lists, hardware detection, structure layout |
| [**multitasking.md**](06_exec_os/multitasking.md) | **Multitasking deep-dive — scheduler, context switching, IPC, memory safety, real-world scenarios** |
| [tasks_processes.md](06_exec_os/tasks_processes.md) | Task/Process structs, state machine, creation, cleanup, priority guidelines |
| [library_system.md](06_exec_os/library_system.md) | Library node, OpenLibrary lifecycle, expunge mechanics, version management |
| [library_vectors.md](06_exec_os/library_vectors.md) | JMP table, LVO offsets, MakeFunctions, SetFunction patching |
| [interrupts.md](06_exec_os/interrupts.md) | Interrupt levels 1–6, INTENA/INTREQ, server chains, CIA interrupts, software interrupts |
| [exceptions_traps.md](06_exec_os/exceptions_traps.md) | M68k exception vectors, TRAP handlers, Guru Meditation decoder, Line-F emulation |
| [memory_management.md](06_exec_os/memory_management.md) | AllocMem/AllocVec, MEMF flags, pools, fragmentation, MemHeader internals |
| [message_ports.md](06_exec_os/message_ports.md) | MsgPort, PutMsg, GetMsg, WaitPort, ownership rules, request-reply pattern |
| [signals.md](06_exec_os/signals.md) | AllocSignal, Signal, Wait, SetSignal, multi-source event loop patterns |
| [semaphores.md](06_exec_os/semaphores.md) | SignalSemaphore, shared/exclusive locking, deadlock avoidance, decision guide |
| [io_requests.md](06_exec_os/io_requests.md) | IORequest, DoIO, SendIO, CheckIO, AbortIO, IOF_QUICK, timer device example |
| [lists_nodes.md](06_exec_os/lists_nodes.md) | MinList/List/Node traversal, sentinel design, Enqueue, safe iteration |
| [resident_modules.md](06_exec_os/resident_modules.md) | RomTag, RTF_AUTOINIT, boot priority, ROM scan, disk-resident loading |
### 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 |
| [stormc.md](13_toolchain/stormc.md) | StormC native IDE and C/C++ 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, SnoopDOS, GDB remote, kprintf |
### 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 |
Reference in a new issue View git blame Copy permalink