%//////////////////////////////////////////////////////////////////////////////
%
% Copyright (c) 2007-2019 Daniel Adler <dadler@uni-goettingen.de>, 
%                         Tassilo Philipp <tphilipp@potion-studios.com>
%
% Permission to use, copy, modify, and distribute this software for any
% purpose with or without fee is hereby granted, provided that the above
% copyright notice and this permission notice appear in all copies.
%
% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
%
%//////////////////////////////////////////////////////////////////////////////

% ==================================================
% PowerPC 32
% ==================================================
\subsection{PowerPC (32bit) Calling Conventions}

\paragraph{Overview}

\begin{itemize}
\item Word size is 32 bits
\item Big endian (MSB) and litte endian (LSB) operating modes.
\item Processor operates on floats in double precision floating point arithmetc (IEEE-754) values directly (single precision is converted on the fly)
\item Apple Mac OS X/Darwin PPC is specified in "Mac OS X ABI Function Call Guide"\cite{ppcMacOSX}. It uses Big Endian (MSB).
\item Linux PPC 32-bit ABI is specified in "LSB for PPC"\cite{ppc32LSB} which is based on "System V ABI". It uses Big Endian (MSB).
\item PowerPC EABI is defined in the "PowerPC Embedded Application Binary Interface 32-Bit Implementation".
\end{itemize}

\paragraph{\product{dyncall} support}

\product{Dyncall} and \product{dyncallback} are supported for PowerPC (32bit) Big Endian (MSB), for Darwin's and System V's calling convention.


\subsubsection{Mac OS X/Darwin}

\paragraph{Registers and register usage}

\begin{table}[h]
\begin{tabular*}{0.95\textwidth}{3 B}
Name                & Brief description\\
\hline
{\bf gpr0}          & scratch\\
{\bf gpr1}          & stack pointer\\
{\bf gpr2}          & scratch\\
{\bf gpr3,gpr4}     & return value, parameter 0 and 1 for integer or pointer, scratch\\
{\bf gpr5-gpr10}    & parameter 2-7 for integer or pointer parameters, scratch\\
{\bf gpr11}         & preserve\\
{\bf gpr12}         & branch target for dynamic code generation\\
{\bf gpr13-31}      & preserve\\
{\bf fpr0}          & scratch\\
{\bf fpr1}          & floating point return value, floating point parameter 0 (always double precision)\\
{\bf fpr2-fpr13}    & floating point parameters 1-12 (always double precision)\\
{\bf fpr14-fpr31}   & preserve\\
{\bf v0-v1}         & scratch\\
{\bf v2-v13}        & vector parameters\\
{\bf v14-v19}       & scratch\\
{\bf v20-v31}       & preserve\\
{\bf lr}            & link-register, scratch\\
{\bf ctr}           & count-register, scratch\\
{\bf cr0-cr7}       & conditional register fields, each 4-bit wide (cr0-cr1 and cr5-cr7 are scratch)\\
\end{tabular*}
\caption{Register usage on Darwin PowerPC 32-Bit}
\end{table}

\paragraph{Parameter passing}

\begin{itemize}
\item stack grows down
\item stack parameter order: right-to-left
\item caller cleans up the stack
\item the first 8 integer parameters are passed in registers gpr3-gpr10
\item the first 12 floating point parameters are passed in registers fpr1-fpr13
\item 64 bit arguments are passed as if they were two 32 bit arguments, without skipping registers for alignment (this means passing half via a register and half via the stack is allowed)
\item if a float parameter is passed via a register, gpr registers are skipped for subsequent integer parameters (based on the size of
the float - 1 register for single precision and 2 for double precision floating point values)
\item the caller pushes subsequent parameters onto the stack
\item for every parameter passed via a register, space is reserved in the stack parameter area (in order to spill the parameters if
needed - e.g. varargs)
\item ellipsis calls take floating point values in int and float registers (single precision floats are promoted to double precision
as defined for ellipsis calls)
\item all nonvector parameters are aligned on 4-byte boundaries
\item vector parameters are aligned on 16-byte boundaries
\item composite parameters with size of 1 or 2 bytes occupy low-order bytes of their 4-byte area. INCONSISTENT with other 32-bit PPC
binary interfaces. In AIX and OS 9, padding bytes always follow the data structure
\item composite parameters 3 bytes or larger in size occupy high-order bytes
\item integer parameters \textless\ 32 bit are right-justified (meaning occupy higher-address bytes) in their 4-byte slot on the stack, requiring extra-care for big-endian targets
\end{itemize}


\paragraph{Return values}

\begin{itemize}
\item return values of integer \textless=\ 32bit or pointer type use gpr3
\item 64 bit integers use gpr3 and gpr4 (hiword in gpr3, loword in gpr4)
\item floating point values are returned via fpr1
\item structures \textless=\ 64 bits use gpr3 and gpr4
\item for types \textgreater\ 64 bits, a secret first parameter with an address to the return value is passed
\end{itemize}


\paragraph{Stack layout}

% verified/amended: TP nov 2019 (see also doc/disas_examples/ppc.darwin.disas)
Stack frame is always 16-byte aligned. Prolog opens frame with additional, fixed space for a linkage area, to hold a number of values (not all of them are required to be saved, though). Stack directly after function prolog:\\

\begin{figure}[h]
\begin{tabular}{5|3|1 1}
                                  & \vdots                        &                                      &                               \\
\hhline{~=~~}
register save area                & \hspace{4cm}                  &                                      & \mrrbrace{14}{caller's frame} \\
\hhline{~-~~}
local data                        &                               &                                      &                               \\
\hhline{~-~~}
\mrlbrace{6}{parameter area}      & last arg                      & \mrrbrace{3}{stack parameters}       &                               \\
                                  & \ldots                        &                                      &                               \\
                                  & 9th word of arg data          &                                      &                               \\
                                  & gpr10                         & \mrrbrace{3}{spill area (as needed)} &                               \\
                                  & \ldots                        &                                      &                               \\
                                  & gpr3                          &                                      &                               \\
\hhline{~-~~}
\mrlbrace{6}{linkage area}        & reserved                      &                                      &                               \\
                                  & reserved                      &                                      &                               \\
                                  & reserved                      &                                      &                               \\
                                  & return address (callee saved) &                                      &                               \\
                                  & condition reg (callee saved)  &                                      &                               \\
                                  & parent stack frame pointer    &                                      &                               \\
\hhline{~=~~}
register save area                &                               &                                      & \mrrbrace{4}{current frame}   \\
\hhline{~-~~}
local data                        &                               &                                      &                               \\
\hhline{~-~~}
parameter area                    &                               &                                      &                               \\
\hhline{~-~~}
linkage area                      & \vdots                        &                                      &                               \\
\end{tabular}
\caption{Stack layout on ppc32 Darwin}
\end{figure}


\newpage


\subsubsection{System V PPC 32-bit}

\paragraph{Status}

\paragraph{Registers and register usage}

\begin{table}[h]
\begin{tabular*}{0.95\textwidth}{3 B}
Name              & Brief description\\
\hline
{\bf r0}          & scratch\\
{\bf r1}          & stack pointer, preserve\\
{\bf r2}          & system-reserved\\
{\bf r3-r4}       & parameter passing and return value, scratch\\
{\bf r5-r10}      & parameter passing, scratch\\
{\bf r11-r12}     & scratch\\
{\bf r13}         & small data area pointer register\\
{\bf r14-r30}     & local variables, preserve\\
{\bf r31}         & used for local variables or \emph{environment pointer}, preserve\\
{\bf f0}          & scratch\\
{\bf f1}          & parameter passing and return value, scratch\\
{\bf f2-f8}       & parameter passing, scratch\\
{\bf f9-13}       & scratch\\
{\bf f14-f31}     & local variables, preserve\\
{\bf cr0-cr7}     & conditional register fields, each 4-bit wide (cr0-cr1 and cr5-cr7 are scratch)\\
{\bf lr}          & link register, scratch\\
{\bf ctr}         & count register, scratch \\
{\bf xer}         & fixed-point exception register, scratch\\
{\bf fpscr}       & floating-point Status and Control Register\\
% {\bf v0-v1}         & scratch\\
% {\bf v2-v13}        & vector parameters\\
% {\bf v14-v19}       & scratch\\
% {\bf v20-v31}       & permanent\\
% {\bf lr}            & scratch, link-register\\
% {\bf ctr}           & scratch, count-register\\
% {\bf cr0-cr1}       & scratch\\
% {\bf cr2-cr4}       & permanent\\
% {\bf cr5-cr7}       & scratch\\
\end{tabular*}
\caption{Register usage on System V ABI PowerPC Processor}
\end{table}

\paragraph{Parameter passing}

\begin{itemize}
\item Stack pointer (r1) is always 16-byte aligned. The EABI differs here - it is 8-byte alignment.
\item 8 general-purpose registers (r3-r10) for integer and pointer types.
\item 8 floating-pointer registers (f1-f8) for float (promoted to double) and double types.
\item Additional arguments are passed on the stack directly after the back-chain and saved return address (8 bytes structure) on the callers stack frame.
\item 64-bit integer data types are passed in general-purpose registers as a whole in two
 32-bit general purpose registers (an odd and an even e.g. r3 and r4), skipping an even integer register
 or passed on the stack; they are never splitted into a register and stack part
\item Ellipse calls set CR bit 6 
\item integer parameters \textless\ 32 bit are right-justified (meaning occupy high-order bytes) in their 4-byte area, requiring extra-care for big-endian targets
\item no spill area is used on stack, iterating over varargs requires a specific va\_list implementation
\end{itemize}

\paragraph{Return values}

\begin{itemize}
\item 32-bit integers use register r3, 64-bit use registers r3 and r4 (hiword in r3, loword in r4).
\item floating-point values are returned using register f1.
\end{itemize}


\paragraph{Stack layout}

% verified/amended: TP nov 2019 (see also doc/disas_examples/ppc.sysv.disas)
Stack frame is always 16-byte aligned. Stack directly after function prolog:\\

\begin{figure}[h]
\begin{tabular}{5|3|1 1}
                                  & \vdots                        &                                &                              \\
\hhline{~=~~}
register save area                & \hspace{4cm}                  &                                & \mrrbrace{7}{caller's frame} \\
\hhline{~-~~}
local data                        &                               &                                &                              \\
\hhline{~-~~}
\mrlbrace{3}{parameter area}      & last arg                      & \mrrbrace{3}{stack parameters} &                              \\
                                  & \ldots                        &                                &                              \\
                                  & first arg passed via stack    &                                &                              \\
\hhline{~-~~}
                                  & return address (callee saved) &                                &                              \\
\hhline{~-~~}
                                  & parent stack frame pointer    &                                &                              \\
\hhline{~=~~}
register save area                &                               &                                & \mrrbrace{4}{current frame}  \\
\hhline{~-~~}
local data                        &                               &                                &                              \\
\hhline{~-~~}
parameter area                    &                               &                                &                              \\
\hhline{~-~~}
                                  & \vdots                        &                                &                              \\
\end{tabular}
\caption{Stack layout on System V ABI for PowerPC 32-bit calling convention}
\end{figure}