mirror of
https://github.com/alfishe/amiga-bootcamp.git
synced 2026-06-13 00:26:28 +00:00
84 lines
2.5 KiB
Markdown
84 lines
2.5 KiB
Markdown
|
[← Home](../README.md) · [Loader & HUNK Format](README.md)
|
||
|
|
|
||
|
|
# 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:
|
||
|
|
|
||
|
|
```c
|
||
|
|
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)
|