abi-and-calling-conventions

ABI and Calling Conventions

Purpose

Document application binary interface (ABI) rules: register roles, stack alignment, argument passing, return values, and variadic conventions across System V AMD64, ARM AAPCS, and RISC-V — essential for assembly, FFI, and debugging.

When to Use

• Writing assembly thunks or inline asm clobbers
• Debugging corrupted stack in mixed C/asm
• FFI between Rust/C/Zig (skills/rust/rust-ffi, skills/zig/zig-cinterop)
• Reading disassembly from skills/debuggers/gdb

Workflow

1. System V AMD64 (Linux/macOS)

Item	Rule
Integer args	rdi, rsi, rdx, rcx, r8, r9
XMM args	xmm0–xmm7 (float)
Return int/ptr	rax (+ rdx for 128-bit)
Stack alignment	16-byte before call
Red zone	128 bytes below rsp (Linux)
Callee-saved	rbx, rbp, r12–r15

/* void foo(int a, int b, int c, int d, int e, int f, int g); */
/* a–f in regs, g on stack */

Windows x64 differs — see skills/compilers/msvc-cl.

2. ARM AAPCS (AArch32/AArch64)

AArch64:

Item	Rule
Integer args	x0–x7
Float args	v0–v7
Return	x0/x1 or v0
Stack align	16-byte
Callee-saved	x19–x28, fp (x29), lr (x30)

Thumb interworking: LSB of function pointer set for Thumb code.

See skills/low-level-programming/assembly-arm.

3. RISC-V psABI (RV64)

Item	Rule
Integer args	a0–a7
Callee-saved	s0–s11, sp
Return	a0, a1
Stack align	16-byte

See skills/low-level-programming/assembly-riscv.

4. Stack frame layout (conceptual)

high addresses
├── return address
├── saved frame pointer
├── local variables
├── spill slots / alignment padding
└── outgoing args (if any)
low addresses (rsp)

5. Variadic functions

System V: al holds number of vector args used; register_save_area on stack for va_start. Prefer typed wrappers over raw va_arg in portable FFI.

6. Verify in compiler output

gcc -O2 -S -o - foo.c   # study .cfi_* and mov args
objdump -d -M intel ./a.out

7. Agent usage

/abi-and-calling-conventions Which registers hold args 5–8 in AArch64 for my C function?

Common Problems

Symptom	Cause	Fix
Crash on call	Stack misaligned	Align rsp mod 16
Wrong float arg	XMM vs GPR mismatch	Match prototype
Corrupt callee-saved	Asm clobber missing	List in clobber or save
FFI garbage	Windows vs SysV mix	Match toolchain ABI
Variadic UB	Wrong type to va_arg	Cast to promoted type

Related Skills

• skills/low-level-programming/assembly-x86 — x86-64 asm
• skills/low-level-programming/assembly-arm — AAPCS examples
• skills/low-level-programming/assembly-riscv — RISC-V asm
• skills/rust/rust-ffi — extern "C" guarantees
• skills/binaries/elf-inspection — symbol and relocation views