abi-and-calling-conventions

ABI 与调用约定

目的

记录应用程序二进制接口（ABI）规则：寄存器用途、栈对齐、参数传递、返回值，以及 System V AMD64、ARM AAPCS 和 RISC-V 的可变参数约定。这些规则对于汇编、FFI 和调试至关重要。

适用场景

• 编写汇编跳板或内联汇编的 clobber 声明
• 调试 C/汇编混合代码中的栈损坏问题
• Rust/C/Zig 之间的 FFI（skills/rust/rust-ffi、skills/zig/zig-cinterop）
• 阅读 skills/debuggers/gdb 中的反汇编

工作流

1. System V AMD64（Linux/macOS）

项目	规则
整数参数	rdi, rsi, rdx, rcx, r8, r9
XMM 参数	xmm0–xmm7（浮点数）
整数/指针返回值	rax（128 位时加上 rdx）
栈对齐	call 前按 16 字节对齐
红区	rsp 以下 128 字节（Linux）
被调用者保存	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 有所不同 — 参见 skills/compilers/msvc-cl。

2. ARM AAPCS（AArch32/AArch64）

AArch64：

项目	规则
整数参数	x0–x7
浮点参数	v0–v7
返回值	x0/x1 或 v0
栈对齐	16 字节
被调用者保存	x19–x28、fp（x29）、lr（x30）

Thumb 互操作：Thumb 代码的函数指针最低有效位（LSB）设为 1。

参见 skills/low-level-programming/assembly-arm。

3. RISC-V psABI（RV64）

项目	规则
整数参数	a0–a7
被调用者保存	s0–s11、sp
返回值	a0、a1
栈对齐	16 字节

参见 skills/low-level-programming/assembly-riscv。

4. 栈帧布局（概念示意）

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

5. 可变参数函数

System V：al 存放已使用的向量参数数量；va_start 使用栈上的 register_save_area。在可移植 FFI 中，优先使用类型化封装，而非直接使用 va_arg。

6. 在编译器输出中验证

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

7. Agent 用法

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

常见问题

症状	原因	修复方法
call 时崩溃	栈未对齐	将 rsp 按 16 字节对齐
浮点参数错误	XMM 与 GPR 不匹配	与函数原型保持一致
被调用者保存寄存器损坏	缺少汇编 clobber 声明	在 clobber 中列出或保存
FFI 结果异常	混用 Windows 与 SysV 约定	与工具链 ABI 保持一致
可变参数 UB	va_arg 类型错误	转换为提升后的类型

相关技能

• skills/low-level-programming/assembly-x86 — x86-64 汇编
• skills/low-level-programming/assembly-arm — AAPCS 示例
• skills/low-level-programming/assembly-riscv — RISC-V 汇编
• skills/rust/rust-ffi — extern "C" 保证
• skills/binaries/elf-inspection — 符号和重定位视图