amiga-bootcamp/04_linking_and_libraries/register_conventions.md

← Home · Linking & Libraries

M68k Register Calling Conventions on Amiga

Overview

AmigaOS uses a pure register-based calling convention for all OS API calls. There is no stack-based C ABI for library functions. Every argument is passed in a specific CPU register defined by the .fd file for that library.

---

The AmigaOS Register Convention

All OS library calls follow this scheme:

Register	Role
A6	Library base pointer (always)
D0	Return value (32-bit integer or BOOL)
D0+D1	64-bit return (rare; e.g., DivideU)
D1–D7, A0–A3	Arguments — exact registers per .fd
D2–D7, A2–A3	Callee-preserved (OS will not trash these)
D0, D1, A0, A1	Scratch (may be destroyed by any OS call)
A4	Global data pointer (VBCC; not used by OS)
A5	Frame pointer (some compilers; not used by OS)
A6	Library base — always trashed to point to lib
A7	Stack pointer

Key rules:

• A6 is always destroyed — it holds the target library base after every OS call
• D0, D1, A0, A1 are volatile — save them if needed across OS calls
• FP0, FP1 are scratch if the FPU is present

---

Example: dos.library Write()

From fd/dos_lib.fd:

Write(file,buffer,length)(d1,d2,d3)

/* C call: */
LONG n = Write(fh, buf, 512);

/* Compiles to: */
MOVEA.L  _DOSBase, A6
MOVE.L   fh,    D1
MOVE.L   buf,   D2
MOVE.L   #512,  D3
JSR      -48(A6)
; D0 = bytes written (−1 = error)

---

Preserved vs. Scratch Register Summary

Scratch (caller must save if needed):
    D0  D1  A0  A1  A6  FP0  FP1

Preserved (callee saves/restores):
    D2  D3  D4  D5  D6  D7
    A2  A3  A4  A5
    FP2  FP3  FP4  FP5  FP6  FP7

This matches the Motorola 68000 family software convention, but AmigaOS does not use A5 as a frame pointer (unlike the standard System V m68k ABI).

---

Inter-Library Calls

When one library function calls another library internally, it must:

; save A6 (current lib base), load new lib base
MOVEM.L  A6, -(SP)
MOVEA.L  _GfxBase, A6
JSR      -102(A6)          ; graphics.library BltClear()
MOVEM.L  (SP)+, A6

Failure to save/restore A6 is a common bug in hand-written assembly library code.

---

C Compiler Differences

SAS/C 6.x

• Generates standard MOVEA.L libbase,A6; JSR -lvo(A6) via #pragma amicall
• Uses A5 as a frame pointer in non-leaf functions
• Stack frame: LINK A5,#-N on entry, UNLK A5 on exit

GCC (bebbo m68k-amigaos)

• Generates inline-asm stubs with explicit register constraints
• No frame pointer by default (-fomit-frame-pointer)
• D2–D7/A2–A3 saved on stack per function (ABI-compatible)

VBCC

• Uses __reg() storage class for explicit register placement
• No frame pointer — tighter code than SAS/C for register-intensive functions

---

Detecting the Calling Convention in IDA Pro

Pattern to identify an OS API call in disassembly:

MOVEA.L  (_DOSBase).L, A6     ; load library base
JSR      (-138,A6)            ; call at LVO −138

Cross-reference the LVO against the .fd file to identify the function. IDA's Amiga loader applies LVO names automatically when library definitions are present.

---

References

• NDK39: fd/*.fd — register assignments per function
• Amiga ROM Kernel Reference Manual: Libraries — register conventions appendix
• SAS/C 6.x Programmer's Guide — calling convention chapter
• GCC m68k-amigaos (bebbo) — libnix inline headers