%CopyrightBegin%
 %CopyrightEnd%



HiPE PowerPC ABI
================
This document describes aspects of HiPE's runtime system
that are specific for the 32 and 64-bit PowerPC architectures.

Register Usage
--------------
r1, r2, and r13 are reserved for the C runtime system.

r29-r31 are fixed (unallocatable).
r29 (HP) is the current process' heap pointer.
r30 (NSP) is the current process' native stack pointer.
r31 (P) is the current process' "Process" pointer.

r0, r3-r12, and r14-r28 are caller-save. They are used as temporary
scratch registers and for function call parameters and results.

The runtime system uses temporaries in specific contexts:
r28 (TEMP_LR) is used to preserve LR around BIF calls.
r27 (TEMP_ARG0) is used to preserve the return value in nbif_stack_trap_ra,
and LR in hipe_ppc_inc_stack (the caller saved its LR in TEMP_LR).
r12 is used to pass the callee address in native-to-BEAM traps.
r11 is used to construct callee addresses in calls via trampolines.
r4 (ARG0) is used for MBUF-after-BIF checks, for storing the
arity of a BIF that throws an exception or does GC due to MBUF,
and for checking P->flags for pending timeout.
r3 is used to inspect the type of a thrown exception, and to
return a result token from glue.S back to hipe_mode_switch().
r0 is used to pass the callee arity in native-to-BEAM traps.

LR and CTR are caller-save.

Calling Convention
------------------
The first NR_ARG_REGS parameters (a tunable parameter between 0 and 7,
inclusive) are passed in r4-r10.

r3 is not used for parameter passing. This allows the BIF wrappers to
simply move P to r3 without shifting the remaining parameter registers.

r0/r11/r12 are not used for parameter passing since they may be modified
during function linkage.

The return value from a function is placed in r3.

Stack Frame Layout
------------------
[From top to bottom: formals in left-to-right order, incoming return
address, fixed-size chunk for locals & spills, variable-size area
for actuals, outgoing return address. NSP normally points at the
bottom of the fixed-size chunk, except during a recursive call.
The callee pops the actuals, so no NSP adjustment at return.]

Stack Descriptors
-----------------
sdesc_fsize() is the frame size excluding the return address word.

Standard Linux PowerPC Calling Conventions (32-bit)
===================================================

Reg		Status		Role
---		------		----
r0		calleR-save	volatile
				may be modified during function linkage
				r0 cannot be base reg in load/store insns
r1		calleE-save	stack pointer, 16-byte aligned, must point
				to valid frame with link to previous frame
r2		reserved	thread register
				(TOC in AIX, GOT in 64-bit, caller-save in OSX)
r3-r4		calleR-save	volatile, parameters, return values
r5-r10		calleR-save	volatile, parameters
r11		calleR-save	volatile,
				may be modified during function linkage
				(calls by pointer & environment pointer in AIX)
r12		calleR-save	volatile,
				may be modified during function linkage
r13		reserved	small data area pointer
				(callee-save in AIX, thread reg in 64-bit,
				callee-save in OSX)
r14-r30		calleE-save	local variables
r31		calleE-save	local variable or "environment pointer"
f0		calleR-save	volatile
f1		calleR-save	volatile, parameters, return values
f2-f8		calleR-save	volatile, parameters
f9-f13		calleR-save	volatile
f14-f31		calleE-save	local variables
CR0/1/5/6/7	calleR-save	condition codes, CR1 used in stdarg calls
CR2/3/4		calleE-save	condition codes
LR		calleR-save	return address
CTR		calleR-save	counter, indirect jump address
XER		calleR-save	fixed-point exception register

Standard PPC64 ELF ABI Calling Conventions
==========================================

Reg		Status		Role
---		------		----
r0		calleR-save	volatile
				may be modified during function linkage
				r0 cannot be base reg in load/store insns
r1		calleE-save	stack pointer, 16-byte aligned, must point
				to valid frame with link to previous frame
r2		reserved	TOC pointer
r3		calleR-save	volatile, parameters, return values
r4-r10		calleR-save	volatile, parameters
r11		calleR-save	volatile,
				may be modified during function linkage
				(calls by pointer & environment pointer)
r12		calleR-save	volatile,
				may be modified during function linkage
				(exception handling and glink code)
r13		reserved	system thread ID
r14-r31		calleE-save	local variables

f0		calleR-save	volatile
f1-f4		calleR-save	volatile, parameters, return values
f5-f13		calleR-save	volatile, parameters
f14-f31		calleE-save	local variables

CR0/1/5/6/7	calleR-save	volatile condition codes
CR2/3/4		calleE-save	non-volatile condition codes

LR		calleR-save	return address, volatile
CTR		calleR-save	counter, indirect jump address (volatile)
XER		calleR-save	fixed-point exception register (volatile)
FPSCR		calleR-save	floating-point status and control (volatile)

v0-v1		calleR-save	volatile, scratch
v2-v13		calleR-save	volatile, parameters
v14-v19		calleR-save	volatile, scratch
v20-v31		calleE-save	non-volatile local variables
vrsave		calleE-save	non-volatile