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

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

Browse source 
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.
This commit is contained in:
Ilia Sharin 2026-04-23 12:16:52 -04:00
parent f07a368bf1
commit 21751c0025
172 changed files with 19701 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

16
13_toolchain/README.md Normal file
View file

@ -0,0 +1,16 @@
[← Home](../README.md)
# Toolchain — Overview
## Section Index
| File | Description |
|---|---|
| [vasm_vlink.md](vasm_vlink.md) | vasm assembler and vlink linker |
| [gcc_amiga.md](gcc_amiga.md) | m68k-amigaos-gcc cross-compiler |
| [sasc.md](sasc.md) | SAS/C 6.x compiler |
| [fd_files.md](fd_files.md) | FD/SFD file format and LVO generation |
| [pragmas.md](pragmas.md) | Compiler pragmas and inline stubs |
| [ndk.md](ndk.md) | NDK versions, contents, and where to get them |
| [makefiles.md](makefiles.md) | Makefile patterns for Amiga cross-compilation |
| [debugging.md](debugging.md) | Debugging tools: BareFoot, wack, gdb remote |

62
13_toolchain/debugging.md Normal file
View file

@ -0,0 +1,62 @@
[← Home](../README.md) · [Toolchain](README.md)
# Debugging Tools — BareFoot, wack, GDB Remote
## Overview
Debugging Amiga programs ranges from ROM-resident kernel debuggers (wack/SAD) through software monitors to modern cross-debugging via GDB stubs.
---
## Tool Comparison
| Tool | Type | Target | Best for |
|---|---|---|---|
| BareFoot | Serial debugger | Real hardware / UAE | OS-level, Exec kernel |
| wack/SAD | ROM debugger | Real hardware | Boot-time, crash analysis |
| MonAm | Software monitor | AmigaOS | Breakpoints, disassembly |
| IDA Pro | Static + remote | Cross-platform | Static RE, decompilation |
| GDB (m68k-elf-gdb) | Cross-debugger | FS-UAE / Basilisk | Source-level C debugging |
| Enforcer | Memory watchdog | AmigaOS (68020+) | Illegal memory access detection |
| MuForce | Memory watchdog | AmigaOS (68040+) | Same as Enforcer for 040/060 |
---
## Enforcer / MuForce
Detects invalid memory accesses using MMU:
```
Enforcer Hit! $0000000C read by task "myapp" at $00020456
```
```
; Install:
run >NIL: Enforcer
; or for 040/060:
run >NIL: MuForce
```
---
## FS-UAE GDB Debugging
```bash
# In fs-uae.conf:
remote_debugger = 1
remote_debugger_port = 6860
# Connect from host:
m68k-elf-gdb myapp
(gdb) target remote localhost:6860
(gdb) break main
(gdb) continue
```
---
## References
- BareFoot: Aminet `dev/debug/BareFoot.lha`
- Enforcer: Aminet `dev/debug/Enforcer.lha`
- MuForce: Aminet `dev/debug/MuForce.lha`

203
13_toolchain/fd_files.md Normal file
View file

@ -0,0 +1,203 @@
[← Home](../README.md) · [Toolchain](README.md)
# FD/SFD Files — Function Definition Format and LVO Generation
## Overview
**FD files** (Function Definition files) are the machine-readable specification of a library's public API. They define every function's name, LVO offset, and register argument mapping. FD files are the **source of truth** for generating pragma files, inline headers, and IDA LVO scripts.
---
## File Location
```
NDK:fd/exec_lib.fd
NDK:fd/dos_lib.fd
NDK:fd/intuition_lib.fd
NDK:fd/graphics_lib.fd
NDK:sfd/exec_lib.sfd (SFD = extended format with C prototypes)
```
---
## FD File Syntax
```
* "exec.library"
##base _SysBase
##bias 30
##public
Supervisor(userFunction)(A5)
ExitIntr()()
Schedule()()
Reschedule()()
Switch()()
Dispatch()()
Exception()()
InitCode(startClass,version)(D0,D1)
InitStruct(initTable,memory,size)(A1,A2,D0)
MakeLibrary(funcInit,structInit,libInit,dataSize,segList)(A0,A1,A2,D0,D1)
MakeFunctions(target,functionArray,funcDispBase)(A0,A1,A2)
FindResident(name)(A1)
InitResident(resident,segList)(A1,D1)
Alert(alertNum)(D7)
Debug(flags)(D0)
##bias 120
Forbid()()
Permit()()
##bias 132
Disable()()
Enable()()
...
```
### Syntax Rules
| Element | Meaning |
|---|---|
| `* "name"` | Comment; library identity |
| `##base _Symbol` | Global base pointer symbol name |
| `##bias N` | Set current LVO offset to −N |
| `##public` | Following functions are public |
| `##private` | Following functions are private (reserved) |
| `FuncName(args)(regs)` | Function: name, C parameter names, register assignments |
| `##end` | End of file |
**LVO auto-increment:** After each function, the bias increases by 6 (one JMP instruction slot = 6 bytes).
---
## SFD File Format (Extended)
SFD adds full C prototypes:
```
==id $Id: exec_lib.sfd,v 1.0 2003/01/01 00:00:00 Exp $
==base _SysBase
==basetype struct ExecBase *
==libname exec.library
==bias 30
==public
APTR Supervisor(ULONG (*userFunction)()) (A5)
==end
```
---
## Parsing FD Files — Python Script
```python
#!/usr/bin/env python3
"""parse_fd.py — Parse AmigaOS FD files into LVO tables.
Usage: python3 parse_fd.py exec_lib.fd [--json] [--ida]
"""
import re, sys, json, argparse
def parse_fd(path):
"""Parse an FD file and return list of (offset, name, args, regs)."""
funcs = []
bias = 30
public = True
with open(path) as f:
for line in f:
line = line.strip()
if not line or line.startswith('*'):
continue
if line.startswith('##base'):
continue
if line.startswith('##bias'):
bias = int(line.split()[1])
continue
if line == '##public':
public = True
continue
if line == '##private':
public = False
continue
if line == '##end':
break
# Parse: FuncName(args)(regs)
m = re.match(r'(\w+)\(([^)]*)\)\(([^)]*)\)', line)
if m and public:
name = m.group(1)
args = [a.strip() for a in m.group(2).split(',') if a.strip()]
regs = [r.strip() for r in m.group(3).split(',') if r.strip()]
funcs.append({
'name': name,
'lvo': -bias,
'bias': bias,
'args': args,
'regs': regs
})
bias += 6 # always advance, even for private
return funcs
def output_ida_script(funcs, base_name):
"""Generate IDA Python LVO dict."""
print(f"# Auto-generated from FD file")
print(f"LVO_{base_name} = {{")
for f in funcs:
print(f" {f['lvo']:+5d}: \"{f['name']}\",")
print("}")
def output_json(funcs):
print(json.dumps(funcs, indent=2))
def output_table(funcs):
print(f"{'LVO':>6} {'Bias':>5} {'Function':<30} {'Registers'}")
print(f"{'─'*6} {'─'*5} {'─'*30} {'─'*30}")
for f in funcs:
regs = ', '.join(f['regs']) if f['regs'] else '(none)'
print(f"{f['lvo']:>+6d} {f['bias']:>5d} {f['name']:<30} {regs}")
if __name__ == '__main__':
ap = argparse.ArgumentParser(description='Parse AmigaOS FD files')
ap.add_argument('fdfile', help='Path to .fd file')
ap.add_argument('--json', action='store_true', help='Output JSON')
ap.add_argument('--ida', action='store_true', help='Output IDA script')
args = ap.parse_args()
funcs = parse_fd(args.fdfile)
if args.json:
output_json(funcs)
elif args.ida:
output_ida_script(funcs, args.fdfile.split('/')[-1].replace('_lib.fd',''))
else:
output_table(funcs)
sys.stderr.write(f"Parsed {len(funcs)} public functions\n")
```
---
## Where to Get NDK FD Files
| NDK | Source | FD path |
|---|---|---|
| NDK 3.9 | Aminet: `dev/misc/NDK39.lha` (free) | `NDK_3.9/Include/fd/` |
| NDK 3.2 | Hyperion (commercial, ~€30) | `NDK3.2/Include_H/fd/` |
| NDK 3.1 | Commodore (archived) | `NDK3.1/Include/fd/` |
---
## Auto-Generating IDA LVO Labels
```bash
# Generate IDA script from all FD files:
for fd in NDK_3.9/Include/fd/*_lib.fd; do
python3 parse_fd.py "$fd" --ida >> all_lvos.py
done
```
Then in IDA: File → Script command → Run `all_lvos.py`
---
## References
- NDK39: `fd/` directory
- `05_reversing/static/api_call_identification.md` — using LVOs in RE

82
13_toolchain/gcc_amiga.md Normal file
View file

@ -0,0 +1,82 @@
[← Home](../README.md) · [Toolchain](README.md)
# m68k-amigaos-gcc — Cross-Compiler
## Overview
`m68k-amigaos-gcc` is the GCC-based cross-compiler for AmigaOS, typically based on GCC 2.95 (legacy) or GCC 6.5 (bebbo's fork). It produces Amiga hunk-format executables and supports all 68k variants.
---
## Installation (bebbo's toolchain)
```bash
# Docker-based (recommended):
docker pull bebbo/amiga-gcc
docker run -v $(pwd):/work bebbo/amiga-gcc m68k-amigaos-gcc -o hello hello.c
# Native build (Linux/macOS):
# NOTE: bebbo removed his repos from GitHub. Use Codeberg or his personal git:
git clone https://codeberg.org/bebbo/amiga-gcc.git
# Mirror: https://franke.ms/git/bebbo/amiga-gcc
cd amiga-gcc
make update
make all -j$(nproc)
# Installs to /opt/amiga/
```
---
## Usage
```bash
# Compile and link:
m68k-amigaos-gcc -noixemul -o hello hello.c
# Common flags:
# -noixemul — use libnix (no ixemul.library dependency)
# -m68000 — target 68000 (default)
# -m68020 — target 68020+
# -m68040 — target 68040
# -m68060 — target 68060
# -m68881 — use 68881/68882 FPU
# -Os — optimise for size
# -O2 — optimise for speed
# -fomit-frame-pointer — free up A5
# -fbaserel — base-relative addressing (small data model)
# -resident — generate resident-capable code
# -g — include debug info (HUNK_DEBUG)
# -s — strip symbols
```
---
## Startup Code
| Startup | Description |
|---|---|
| `libnix` | Minimal C runtime, no shared library dependency |
| `ixemul` | Unix-like C runtime (requires ixemul.library) |
| `crt0.o` | Raw startup — no C runtime at all |
---
## Inline/Pragma System Calls
```c
/* Use inline headers to call library functions via registers: */
#include <inline/exec.h>
#include <inline/dos.h>
/* Or use proto headers (auto-select inline vs pragma): */
#include <proto/exec.h>
#include <proto/dos.h>
```
---
## References
- Codeberg: https://codeberg.org/bebbo/amiga-gcc
- Mirror: https://franke.ms/git/bebbo/amiga-gcc
- GCC 6.5 m68k cross-compiler documentation

97
13_toolchain/makefiles.md Normal file
View file

@ -0,0 +1,97 @@
[← Home](../README.md) · [Toolchain](README.md)
# Makefile Patterns for Amiga Cross-Compilation
## Overview
Standard Makefile patterns for building Amiga executables from Linux/macOS using the bebbo cross-toolchain or vasm/vlink.
---
## GCC Cross-Compilation
```makefile
# Makefile for m68k-amigaos-gcc
PREFIX = m68k-amigaos-
CC = $(PREFIX)gcc
AS = $(PREFIX)as
LD = $(PREFIX)gcc
STRIP = $(PREFIX)strip
NDK = /opt/amiga/m68k-amigaos/ndk-include
CFLAGS = -noixemul -m68000 -Os -fomit-frame-pointer \
-I$(NDK) -Wall -Wextra
LDFLAGS = -noixemul -Wl,--emit-relocs
LIBS = -lamiga
TARGET = myapp
SRCS = main.c util.c
OBJS = $(SRCS:.c=.o)
all: $(TARGET)
$(TARGET): $(OBJS)
$(LD) $(LDFLAGS) -o $@ $^ $(LIBS)
$(STRIP) $@
%.o: %.c
$(CC) $(CFLAGS) -c -o $@ $<
clean:
rm -f $(OBJS) $(TARGET)
.PHONY: all clean
```
---
## vasm/vlink Assembly Project
```makefile
VASM = vasmm68k_mot
VLINK = vlink
AFLAGS = -Fhunk -m68000 -I/opt/amiga/ndk/Include/include_i
LFLAGS = -bamigahunk -s
TARGET = myprog
SRCS = main.s gfx.s sound.s
OBJS = $(SRCS:.s=.o)
all: $(TARGET)
$(TARGET): $(OBJS)
$(VLINK) $(LFLAGS) -o $@ $^
%.o: %.s
$(VASM) $(AFLAGS) -o $@ $<
clean:
rm -f $(OBJS) $(TARGET)
```
---
## Mixed C + Assembly
```makefile
CC = m68k-amigaos-gcc
VASM = vasmm68k_mot
%.o: %.c
$(CC) $(CFLAGS) -c -o $@ $<
%.o: %.s
$(VASM) -Fhunk -m68000 -o $@ $<
myapp: main.o fastblit.o
$(CC) $(LDFLAGS) -o $@ $^ $(LIBS)
```
---
## References
- `13_toolchain/gcc_amiga.md` — GCC setup
- `13_toolchain/vasm_vlink.md` — vasm/vlink setup

84
13_toolchain/ndk.md Normal file
View file

@ -0,0 +1,84 @@
[← Home](../README.md) · [Toolchain](README.md)
# NDK — Native Development Kit Versions
## Overview
The **NDK** (Native Development Kit) contains all header files, FD files, link libraries, and autodocs needed to develop for AmigaOS. It is the authoritative source for all structure definitions and API specifications.
---
## Version History
| NDK | OS | Source | Availability |
|---|---|---|---|
| NDK 1.3 | OS 1.3 | Commodore | Archived; ADF collections |
| NDK 2.0 | OS 2.0 | Commodore | Archived |
| NDK 3.1 | OS 3.1 | Commodore (final) | Widely archived, Aminet |
| NDK 3.5 | OS 3.5 | Haage & Partner | Included with OS 3.5 CD |
| NDK 3.9 | OS 3.9 | Haage & Partner | **Free download** from Hyperion/Aminet |
| NDK 3.2 | OS 3.2 | Hyperion | Commercial (~€30), bundled with OS 3.2 |
---
## Where to Download
| NDK | URL |
|---|---|
| NDK 3.9 | Aminet: `dev/misc/NDK39.lha` — **free, recommended baseline** |
| NDK 3.2 | https://www.hyperion-entertainment.com/ (purchase required) |
| NDK 3.1 | Search Aminet or archive.org for `NDK3.1.lha` |
---
## Contents
```
NDK_3.9/
Include/
include_h/ C headers (.h)
include_i/ Assembler includes (.i)
fd/ FD files (function definitions)
sfd/ SFD files (extended function definitions)
pragmas/ SAS/C pragma headers
inline/ GCC inline headers
proto/ Portable proto headers
lvo/ LVO offset include files (.i)
Documentation/
autodocs/ Library/device API documentation
Lib/
linker_libs/ Amiga link libraries (.lib)
startup/ C startup code
```
---
## Key Differences Between Versions
| Feature | NDK 3.1 | NDK 3.9 | NDK 3.2 |
|---|---|---|---|
| `exec/exec.h` | OS 3.1 structures | + V39 extensions | + V47 extensions |
| 68040/060 support | Minimal | 040/060 library headers | Full |
| SFD files | No | Yes | Yes |
| Locale support | Basic | Full | Full |
| Datatypes | No | Yes | Yes |
| Reaction GUI | No | No | Yes |
---
## Using NDK with Cross-Compiler
```bash
# Set up include paths:
export NDK=/path/to/NDK_3.9
m68k-amigaos-gcc -I$NDK/Include/include_h \
-L$NDK/Lib/linker_libs \
-noixemul -o output source.c
```
---
## References
- Hyperion Entertainment: https://www.hyperion-entertainment.com/
- Aminet: https://aminet.net/

83
13_toolchain/pragmas.md Normal file
View file

@ -0,0 +1,83 @@
[← Home](../README.md) · [Toolchain](README.md)
# Compiler Pragmas and Inline Stubs
## Overview
AmigaOS library calls use **register-based** calling conventions (arguments in D0–D7/A0–A6). C compilers need pragmas or inline stubs to generate the correct register assignments instead of stack-based calls.
---
## Three Mechanisms
| Method | Compiler | How it works |
|---|---|---|
| **Pragmas** | SAS/C | `#pragma libcall` directive |
| **Inline headers** | GCC | Inline asm functions in `<inline/lib.h>` |
| **Proto headers** | All | `<proto/lib.h>` — auto-selects pragma or inline |
---
## Pragma Example (SAS/C)
```c
#pragma libcall DOSBase Open 1e 2102
/* Translates to: LVO = -0x1E = -30
Args: D1 = arg1 (name), D2 = arg2 (mode)
Result: D0 */
```
---
## Inline Example (GCC)
```c
/* inline/exec.h */
static __inline APTR
AllocMem(ULONG byteSize, ULONG requirements)
{
register APTR _res __asm("d0");
register ULONG _byteSize __asm("d0") = byteSize;
register ULONG _requirements __asm("d1") = requirements;
register struct ExecBase *_SysBase __asm("a6") = SysBase;
__asm volatile (
"jsr -198(%%a6)"
: "=r"(_res)
: "r"(_byteSize), "r"(_requirements), "r"(_SysBase)
: "d1","a0","a1","cc","memory"
);
return _res;
}
```
---
## Generating Pragmas/Inlines from FD Files
```bash
# fd2pragma (Aminet: dev/misc/fd2pragma.lha):
fd2pragma exec_lib.fd exec_lib.sfd TO pragmas/exec_pragmas.h SPECIAL 6
fd2pragma exec_lib.fd exec_lib.sfd TO inline/exec.h SPECIAL 70
```
---
## Proto Headers
```c
/* proto/exec.h — portable wrapper: */
#ifdef __SASC
#include <pragmas/exec_pragmas.h>
#elif defined(__GNUC__)
#include <inline/exec.h>
#endif
extern struct ExecBase *SysBase;
```
---
## References
- NDK39: `pragmas/`, `inline/`, `proto/` directories
- `13_toolchain/fd_files.md` — FD file format

63
13_toolchain/sasc.md Normal file
View file

@ -0,0 +1,63 @@
[← Home](../README.md) · [Toolchain](README.md)
# SAS/C 6.x — Compiler Reference
## Overview
SAS/C (originally Lattice C) was the dominant commercial C compiler for AmigaOS. Version 6.58 is the final release. It produces optimised 68k code with full AmigaOS integration, including pragma-based system calls and SAS-specific debug formats.
---
## Key Features
| Feature | Description |
|---|---|
| Register args | Automatic register parameter passing |
| Pragmas | `#pragma libcall` for direct library LVO calls |
| Small data | A4-relative addressing for globals |
| Profiling | Built-in `sprof` profiler |
| Debug format | SAS stabs (`=APS` tag in HUNK_DEBUG) |
| Optimizer | Global optimizer (`lc -O`) with peephole |
---
## Pragma Format
```c
/* dos_pragmas.h — generated from FD files: */
#pragma libcall DOSBase Open 1e 2102
/* ^^ ^^ ^^^^
name LVO reg-encoding
reg-encoding: 2=D2, 1=D1, 0=result in D0, 2 args */
#pragma libcall DOSBase Close 24 101
#pragma libcall DOSBase Read 2a 32103
```
Register encoding: digits map to registers (1=D0, 2=D1, ... 9=A0, A=A1, etc.)
---
## Compilation
```
lc -v -O -b0 -j73 hello.c ; compile
blink hello.o TO hello LIB lib:sc.lib lib:amiga.lib ; link
```
| Flag | Meaning |
|---|---|
| `-v` | Verbose |
| `-O` | Optimise |
| `-b0` | Small data model (A4-relative) |
| `-b1` | Large data model |
| `-j73` | Generate 68020/68881 code |
| `-d0` | No debug info |
| `-d2` | Full debug info |
---
## References
- SAS/C 6.x User Manual
- NDK39 pragma files: `NDK_3.9/Include/pragmas/`

113
13_toolchain/vasm_vlink.md Normal file
View file

@ -0,0 +1,113 @@
[← Home](../README.md) · [Toolchain](README.md)
# vasm and vlink — Assembler and Linker
## Overview
**vasm** is a modern, free, multi-target assembler with excellent Amiga support. **vlink** is its companion linker. Together they form the primary open-source toolchain for 68k Amiga development.
---
## Installation
```bash
# Build from source:
wget http://sun.hasenbraten.de/vasm/release/vasm.tar.gz
tar xzf vasm.tar.gz && cd vasm
make CPU=m68k SYNTAX=mot # Motorola syntax
# or:
make CPU=m68k SYNTAX=madmac # Atari MadMac syntax
# vlink:
wget http://sun.hasenbraten.de/vlink/release/vlink.tar.gz
tar xzf vlink.tar.gz && cd vlink && make
```
---
## vasm Usage
```bash
# Assemble to Amiga hunk object:
vasmm68k_mot -Fhunk -o output.o input.s
# Common flags:
# -Fhunk — output Amiga hunk format
# -Fbin — raw binary
# -Felf — ELF format
# -m68000 — target 68000 (default)
# -m68020 — target 68020+
# -m68040 — target 68040
# -m68060 — target 68060
# -no-opt — disable optimisations
# -I<path> — include path
# -D<sym>=<val> — define symbol
# -phxass — PhxAss compatibility mode
# -devpac — Devpac compatibility mode
```
---
## vlink Usage
```bash
# Link hunk objects into executable:
vlink -bamigahunk -o output input1.o input2.o -Llib -lexec -ldos
# Common flags:
# -bamigahunk — output Amiga hunk executable
# -brawbin1 — raw binary
# -s — strip symbols
# -L<path> — library search path
# -l<lib> — link with library
# -Rshort — use short (16-bit) relocations where possible
```
---
## Example: Minimal Amiga Executable
```asm
; hello.s — minimal AmigaOS executable
SECTION code,CODE
start:
move.l 4.w,a6 ; ExecBase
lea dosname(pc),a1
moveq #0,d0
jsr -552(a6) ; OpenLibrary
tst.l d0
beq.s .exit
move.l d0,a6 ; DOSBase
jsr -60(a6) ; Output() → stdout handle
move.l d0,d1
lea msg(pc),a0
move.l a0,d2
moveq #12,d3
jsr -48(a6) ; Write(fh, buf, len)
move.l a6,a1
move.l 4.w,a6
jsr -414(a6) ; CloseLibrary
.exit:
moveq #0,d0
rts
dosname: dc.b "dos.library",0
msg: dc.b "Hello Amiga",10
EVEN
```
```bash
vasmm68k_mot -Fhunk -o hello.o hello.s
vlink -bamigahunk -o hello hello.o
```
---
## References
- vasm: http://sun.hasenbraten.de/vasm/
- vlink: http://sun.hasenbraten.de/vlink/