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-06-13 00:26:28 +00:00 · 2026-04-23 12:16:52 -04:00 · 2026-04-23 12:16:52 -04:00 · 21751c0025
commit 21751c0025
parent f07a368bf1
172 changed files with 19701 additions and 0 deletions
--- a/03_loader_and_exec_format/hunk_debug_info.md
+++ b/03_loader_and_exec_format/hunk_debug_info.md
@ -0,0 +1,163 @@
+[← Home](../README.md) · [Loader & HUNK Format](README.md)
+
+# HUNK Debug Information
+
+## Overview
+
+Two optional hunk types carry debug information in AmigaOS executables:
+
+- **HUNK_SYMBOL** ($3F0) — a simple name→offset symbol table
+- **HUNK_DEBUG** ($3F1) — arbitrary debug data (most commonly stabs records)
+
+Both are ignored by the loader and only used by debuggers.
+
+---
+
+## HUNK_SYMBOL
+
+The simplest debug hunk. Contains a list of (name, offset) pairs for the current hunk:
+
+```
+HUNK_SYMBOL ($000003F0)
+
+[Repeat:]
+  <name_len>      Length of name in longwords (0 terminates)
+  <name...>       Symbol name padded to longword boundary
+  <value>         Symbol value (offset within current hunk)
+
+<0>               Terminator: name_len = 0
+HUNK_END
+```
+
+### Example
+
+Two symbols in a code hunk:
+```
+$000003F0           HUNK_SYMBOL
+$00000001           name = 1 long (4 chars)
+"_foo"              symbol name
+$00000000           at offset 0
+$00000002           name = 2 longs (8 chars)
+"_bar\0\0\0\0"
+$00000040           at offset $40
+$00000000           terminator
+```
+
+### Use in Debuggers
+
+MonAm, wack, and IDA Pro all parse `HUNK_SYMBOL` to provide named labels in the disassembly. IDA's Amiga loader maps these directly to function/data names.
+
+---
+
+## HUNK_DEBUG
+
+`HUNK_DEBUG` carries arbitrary debug data. The most common format used by AmigaOS compilers is **stabs** records (as produced by SAS/C 6.x and GCC).
+
+```
+HUNK_DEBUG ($000003F1)
+
+<size_in_longs>     Total size of the debug data in longwords
+<data...>           Compiler-specific debug data
+HUNK_END
+```
+
+### SAS/C Stabs Format
+
+SAS/C 6.x emits stabs-format debug info. The first longword in the debug data is a tag identifying the format:
+
+```
+$3D415053   Tag = "=APS" — SAS/C stabs
+```
+
+Following the tag: standard BSD/UNIX stabs records:
+```c
+struct stab_entry {
+    ULONG  n_strx;   /* offset into string table */
+    UBYTE  n_type;   /* stab type code */
+    UBYTE  n_other;
+    UWORD  n_desc;   /* line number or misc */
+    ULONG  n_value;  /* symbol value */
+};
+```
+
+**Common stab type codes:**
+| Code | Name | Meaning |
+|---|---|---|
+| $24 | `N_FUN` | Function start |
+| $44 | `N_SLINE` | Source line number |
+| $64 | `N_SO` | Source file name |
+| $84 | `N_LSYM` | Local symbol / type |
+| $A0 | `N_GSYM` | Global symbol |
+| $C0 | `N_RSYM` | Register variable |
+
+### GCC Stabs Format
+
+GCC (`m68k-amigaos-gcc`) emits similar stabs, usually with tag `$3D474343` ("=GCC") or no tag at all.
+
+### Line Number Information
+
+Stabs records with `N_SLINE` provide source-to-address mapping, enabling source-level debugging in tools like wack:
+
+```
+N_SLINE: n_desc = source_line_number
+         n_value = offset in current code hunk
+```
+
+---
+
+## Reading Debug Info in IDA Pro
+
+IDA Pro's Amiga HUNK loader (standard IDA plugin) parses:
+- `HUNK_SYMBOL` → applies as function/data names automatically
+- `HUNK_DEBUG` → partially parsed; stab `N_FUN` entries become function names
+
+To see IDA's parsed symbols after loading:
+- `View → Open Subviews → Names` — all named locations including HUNK_SYMBOL entries
+- `View → Open Subviews → Segments` — hunk-to-segment mapping
+
+---
+
+## Stripping Debug Info
+
+To produce a smaller executable without debug info:
+
+**SAS/C:**
+```
+slink lib/c.o + myobj.o TO myexe NODBG
+```
+
+**GCC:**
+```
+m68k-amigaos-strip --strip-debug myexe
+```
+
+This removes HUNK_SYMBOL and HUNK_DEBUG records, reducing file size.
+
+---
+
+## Worked Hex Example (HUNK_SYMBOL)
+
+Binary fragment from a real executable:
+```
+Offset  Hex Bytes           Decoded
+$1A00:  00 00 03 F0         HUNK_SYMBOL
+$1A04:  00 00 00 01         name_len = 1 (4 chars)
+$1A08:  5F 6D 61 69         "_mai"
+$1A0C:  6E 00 00 00         "n\0\0\0"
+$1A10:  00 00 00 00         value = 0 (entry at start of code hunk)
+$1A14:  00 00 00 02         name_len = 2 (8 chars)
+$1A18:  5F 70 72 6F         "_pro"
+$1A1C:  63 65 73 73         "cess"
+$1A20:  00 00 00 78         value = $78
+$1A24:  00 00 00 00         terminator
+$1A28:  00 00 03 F2         HUNK_END
+```
+
+---
+
+## References
+
+- NDK39: `dos/doshunks.h` — HUNK_SYMBOL, HUNK_DEBUG constants
+- SAS/C 6.x Programmer's Guide — debug output format
+- GCC internals — stabs format documentation
+- IDA Pro Amiga loader source (community) — stabs parsing