mirror of https://github.com/alfishe/amiga-bootcamp.git synced 2026-06-13 00:26:28 +00:00

Ilia Sharin 21751c0025 docs(amiga): complete AmigaOS 3.1/3.2 developer reference — 172 files across 17 sections

Comprehensive technical documentation covering:
- Hardware: OCS/ECS/AGA custom chip registers, Copper & Blitter deep dives
- Boot sequence: cold boot through startup-sequence
- Binary format: HUNK executable spec, relocation, debug info
- Linking & ABI: .fd files, LVO tables, register calling conventions
- Exec kernel: tasks, interrupts, memory, signals, semaphores
- AmigaDOS: file I/O, FFS/OFS layout, CLI/Shell scripting
- Graphics: planar bitmaps, Copper programming, HAM/EHB modes
- Intuition: screens, windows, IDCMP, BOOPSI
- Devices: trackdisk, SCSI, serial, timer, audio, keyboard
- Libraries: utility, expansion, IFFParse, locale, ARexx
- Networking: bsdsocket API, SANA-II, TCP/IP stack comparison
- Toolchain: GCC, vasm/vlink, SAS/C, NDK, debugging
- Reverse engineering: IDA/Ghidra setup, compiler fingerprints, case studies
- CPU & MMU: 68040/060 emulation libs, PMMU, cache management
- Driver development: SANA-II, Picasso96/RTG, AHI audio

All files include breadcrumb navigation. No local paths or proprietary content.

2026-04-23 12:17:35 -04:00

2.5 KiB

Raw Blame History

← Home · Loader & HUNK Format

HUNK_OVERLAY — Overlay System

Overview

The overlay system allows programs larger than available RAM to run by dividing code into segments loaded on demand. Only one overlay section is present in memory at any time; others are swapped in from disk when needed.

This predates virtual memory and was commonly used in A500-era applications with limited Fast RAM.

When Overlays Are Used

Application code exceeds available RAM
Rarely-used code paths (setup, error handling) should not occupy memory permanently
The game/app has a fixed resident core and multiple interchangeable level/module overlays

HUNK_OVERLAY Structure

HUNK_HEADER
  (normal header for resident hunks)

[Normal hunks: code, data, BSS]

HUNK_OVERLAY ($000003F5)
  <size_in_longs>         total size of overlay table data
  <overlay_tree...>       tree of overlay nodes

HUNK_BREAK ($000003F6)    marks end of overlay tree

Overlay Tree Format

The overlay tree describes groups of overlays and their dependencies:

<num_overlay_nodes>
For each node:
  <num_hunks>             number of hunks in this overlay
  <hunk_sizes...>         size of each hunk in longwords
  <hunk_memory_types...>  memory requirements

The resident (non-overlay) hunks are hunk 0 through N. The overlay hunks are numbered starting at N+1.

Runtime Overlay Support — overlaylibrary

AmigaOS provides dos.library support for overlays via InternalLoadSeg with an overlay table. The application calls ObtainSemaphore() + OverlayLoad() to swap overlays.

In practice, the overlay system is complex and rarely documented precisely. Most real Amiga applications avoid overlays in favour of:

Dynamic library loading (OpenLibrary)
Splitting functionality into separate executables run via Execute
AmigaOS shared library mechanism

Practical Alternative: Dynamic Linking

Modern Amiga development (and OS 3.1+ best practices) uses OpenLibrary() instead of overlays:

struct MyLib *MyBase = (struct MyLib *)OpenLibrary("mycode.library", 0);
if (MyBase) {
    MyBase->myFunction(arg1, arg2);
    CloseLibrary((struct Library *)MyBase);
}

This is functionally equivalent to overlay loading but uses the OS resource tracking system and allows multiple users.

References

Amiga ROM Kernel Reference Manual: Libraries — AmigaDOS overlay section
NDK39: dos/doshunks.h — HUNK_OVERLAY, HUNK_BREAK
Paul Tuma's Amiga HUNK format notes (community)

2.5 KiB Raw Blame History