$Id$

HiPE x86 ABI
============
This document describes aspects of HiPE's runtime system
that are specific for the x86 (IA32) architecture.

Register Usage
--------------
%esp and %ebp are fixed and must be preserved by calls (callee-save).
%eax, %edx, %ecx, %ebx, %edi are clobbered by calls (caller-save).
%esi is a fixed global register (unallocatable).

%esp is the native code stack pointer, growing towards lower addresses.
%ebp (aka P) is the current process' "Process*".
%esi (aka HP) is the current process' heap pointer. (If HP_IN_ESI is true.)

The caller-save registers are used as temporary scratch registers
and for parameters in function calls.

[XXX: Eventually, when we have better register allocation in place,
the current "Process*" may be put in %fs instead, which will make
%ebp available as a general-purpose register.]

Calling Convention
------------------
The first NR_ARG_REGS (a tunable parameter between 0 and 5, inclusive)
parameters are passed in %eax, %edx, %ecx, %ebx, and %edi.

The first return value from a function is placed in %eax, the second
(if any) is placed in %edx.

The callee returns by using the "ret $N" instruction, which also
deallocates the stacked actual parameters.

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. %esp normally points at the
bottom of the fixed-size chunk, except during a recursive call.
The callee pops the actuals, so no %esp adjustment at return.]

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

Stacks and Unix Signal Handlers
-------------------------------
Each Erlang process has its own private native code stack.
This stack is managed by the compiler and the runtime system.
It is not guaranteed to have space for a Unix signal handler.
The Unix process MUST employ an "alternate signal stack" using
sigaltstack(), and all user-defined signal handlers MUST be
registered with sigaction() and the SA_ONSTACK flag. Failure
to observe these rules may lead to memory corruption errors.


Standard Unix x86 Calling Conventions
=====================================

%eax, %edx, %ecx are clobbered by calls (caller-save)
%esp, %ebp, %ebx, %esi, %edi are preserved by calls (callee-save)
%eax and %edx receive function call return values
%esp is the stack pointer (fixed)
%ebp is optional frame pointer or local variable
actual parameters are pushed right-to-left
caller deallocates parameters after return (addl $N,%esp)
