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 59929047d4 exec_os: enrich all stubs to bootcamp-quality reference articles 
Complete rewrite of 14 exec_os articles from stubs to comprehensive
deep-dive technical references with architecture diagrams, pitfalls,
and best practices.

New: multitasking.md (scheduler, IPC, memory safety, real-world scenarios)
Enriched: exec_base, tasks_processes, library_system, library_vectors,
interrupts, exceptions_traps, memory_management, message_ports, signals,
semaphores, io_requests, lists_nodes, resident_modules

Updated indexes: 06_exec_os/README.md, root README.md
2026-04-23 17:55:31 -04:00

273 lines
17 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, 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 — 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 |
| [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 |
Reference in a new issue View git blame Copy permalink