%//////////////////////////////////////////////////////////////////////////////
%
% Copyright (c) 2007-2022 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 macos/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"\cite{ppceabi}
\item There is also the "PowerOpen ABI"\cite{poabi}, a nearly identical version of it is used in AIX % more info: http://www.ingallegri.com/public/ppc.html
\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.\\
\product{Dyncall} can also be used to issue syscalls by using the syscall
number as target parameter and selecting the correct mode.


\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 13 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
required by 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 mac 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
\item aggregates (struct, union) with only one (non-aggregate / non-array) field are passed as if the field itself would be passed
\item {\it non-trivial} C++ aggregates (as defined by the language) of any size, are passed indirectly via a pointer to a copy of the aggregate
\item all other aggregates are passed as a sequence of words (like integer parameters)
\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 for all aggregates, the caller allocates space, passes pointer to it to the callee as a hidden first param
(meaning in gpr3), and callee writes return value to this space; the ptr to the aggregate is returned in gpr3
\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}


\clearpage


\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 Ellipsis 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
\item aggregates (struct, union) and types \textgreater\ 64 bits are passed indirectly, as a pointer to the data (or a copy of it, if necessary to avoid modification)
\item {\it non-trivial} C++ aggregates (as defined by the language) of any size, are passed indirectly via a pointer to a copy of the aggregate
\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
\item for {\it non-trivial} C++ aggregates, the caller allocates space, passes pointer to it to the callee as a hidden first param
(meaning in gpr3), and callee writes return value to this space; the ptr to the aggregate is returned in gpr3
\item aggregates (struct, union) \textless=\ 64 bits use gpr3 and gpr4
\item for all other aggregates and types \textgreater\ 64 bits, a secret first parameter with an address to a caller allocated space is passed to the function (in gpr3), which is written to by the callee
\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}


\subsubsection{System V PPC 32-bit / Linux Standard Base version}

This is in essence the same as the System V PPC 32-bit calling convention, but differs for aggregate return values:
% @@@AGGR could be more verbose

\begin{itemize}
\item for all aggregates, the caller allocates space, passes pointer to it to the callee as a hidden first param
(meaning in gpr3), and callee writes return value to this space; the ptr to the aggregate is returned in gpr3
\end{itemize}


\clearpage

\subsubsection{System V syscalls}

\paragraph{Parameter passing}

\begin{itemize}
\item syscall is issued via the {\em sc} instruction
\item kernel destroys registers r13
\item syscall number is set in r0
\item params are passed in registers r3 through r10
\item no stack in use, meaning syscalls are in theory limited to eight arguments
\item register r3 holds the return value, overflow flag in conditional register cr0 signals errors in syscall
\end{itemize}

