%//////////////////////////////////////////////////////////////////////////////
%
% Copyright (c) 2007,2009 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.
%
%//////////////////////////////////////////////////////////////////////////////

\subsection{MIPS Calling Convention}

\paragraph{Overview}

The MIPS family of processors is based on the MIPS processor architecture.
Multiple revisions of the MIPS Instruction set exist, namely MIPS I, MIPS II, MIPS III, MIPS IV, MIPS32 and MIPS64.
Today, MIPS32 and MIPS64 for 32-bit and 64-bit respectively.\\
Several add-on extensions exist for the MIPS family: 

\begin{description}
\item [MIPS-3D] simple floating-point SIMD instructions dedicated to common 3D tasks.
\item [MDMX] (MaDMaX) more extensive integer SIMD instruction set using 64 bit floating-point registers.
\item [MIPS16e] adds compression to the instruction stream to make programs take up less room (allegedly a response to the THUMB instruction set of the ARM architecture).
\item [MIPS MT] multithreading additions to the system similar to HyperThreading.
\end{description}

Unfortunately, there is actually no such thing as "The MIPS Calling Convention".  Many possible conventions are used
by many different environments such as \emph{O32}\cite{MIPSo32}, \emph{O64}, \emph{N32}, \emph{N64} and \emph{EABI}.\\

\paragraph{\product{dyncall} support}

Currently, dyncall supports the EABI calling convention which is used on the Homebrew SDK for the Playstation Portable.
As documentation for this EABI is unofficial, this port is currently experimental. It also supports O32, N32 and N64.

\subsubsection{MIPS EABI 32-bit Calling Convention}

\paragraph{Register usage}

\begin{table}[h]
\begin{tabular*}{0.95\textwidth}{lll}
Name                                   & Alias                     & Brief description\\
\hline                                                             
{\bf \$0}                              & {\bf \$zero}              & Hardware zero \\
{\bf \$1}                              & {\bf \$at}                & Assembler temporary \\
{\bf \$2-\$3}                          & {\bf \$v0-\$v1}           & Integer results \\
{\bf \$4-\$11}                         & {\bf \$a0-\$a7}           & Integer arguments\\
{\bf \$12-\$15,\$24,\$25}              & {\bf \$t4-\$t7,\$t8,\$t9} & Integer temporaries \\
{\bf \$25}                             & {\bf \$t9}                & Integer temporary, hold the address of the called function for all PIC calls (by convention) \\
{\bf \$16-\$23}                        & {\bf \$s0-\$s7}           & Preserved \\
{\bf \$26,\$27}                        & {\bf \$kt0,\$kt1}         & Reserved for kernel \\
{\bf \$28}                             & {\bf \$gp}                & Global pointer \\
{\bf \$29}                             & {\bf \$sp}                & Stack pointer \\
{\bf \$30}                             & {\bf \$s8}                & Frame pointer \\
{\bf \$31}                             & {\bf \$ra}                & Return address \\
{\bf hi, lo}                           &                           & Multiply/divide special registers \\
{\bf \$f0,\$f2}                        &                           & Float results \\
{\bf \$f1,\$f3,\$f4-\$f11,\$f20-\$f23} &                           & Float temporaries \\
{\bf \$f12-\$f19}                      &                           & Float arguments \\
\end{tabular*}
\caption{Register usage on MIPS32 EABI calling convention}
\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 Stack always aligned to 8 bytes.
\item first 8 integers and floats are passed independently in registers using \$a0-\$a7 and \$f12-\$f19, respectively.
\item if either integer or float registers are consumed up, the stack is used.
\item 64-bit floats and integers are passed on two integer registers starting at an even register number, probably skipping one odd register.
\item \$a0-\$a7 and \$f12-\$f19 are not required to be preserved.
\item results are returned in \$v0 (32-bit), \$v0 and \$v1 (64-bit), \$f0 (32 bit float) and \$f0 and \$f2 (2 $\times$ 32 bit float e.g. complex).
\end{itemize}

\paragraph{Stack layout}

Stack directly after function prolog:\\

\begin{figure}[h]
\begin{tabular}{5|3|1 1}
\hhline{~-~~}
                                         & \vdots       &                                &                              \\
\hhline{~=~~}                            
register save area                       & \hspace{4cm} &                                & \mrrbrace{5}{caller's frame} \\
\hhline{~-~~}                            
local data                               &              &                                &   \\
\hhline{~-~~}                            
\mrlbrace{3}{parameter area}             & \ldots       & \mrrbrace{3}{stack parameters} &                              \\
                                         & \ldots       &                                &                              \\
                                         & \ldots       &                                &                              \\
\hhline{~=~~}
register save area (with return address) &              &                                & \mrrbrace{5}{current frame}  \\
\hhline{~-~~}
local data                               &              &                                &                              \\
\hhline{~-~~}
parameter area                           &              &                                &                              \\
\hhline{~-~~}
                                         & \vdots       &                                &                              \\
\hhline{~-~~}
\end{tabular}
\caption{Stack layout on mips32 eabi calling convention}
\end{figure}

\newpage

\subsubsection{MIPS O32 32-bit Calling Convention}

\paragraph{Register usage}

\begin{table}[h]
\begin{tabular*}{0.95\textwidth}{lll}
Name                                   & Alias                     & Brief description\\
\hline                                                             
{\bf \$0}                              & {\bf \$zero}              & Hardware zero \\
{\bf \$1}                              & {\bf \$at}                & Assembler temporary \\
{\bf \$2-\$3}                          & {\bf \$v0-\$v1}           & Integer results, scratch \\
{\bf \$4-\$7}                          & {\bf \$a0-\$a3}           & Integer arguments, scratch\\
{\bf \$8-\$15,\$24,\$25}               & {\bf \$t0-\$t7,\$t8,\$t9} & Integer temporaries, scratch \\
{\bf \$16-\$23}                        & {\bf \$s0-\$s7}           & Preserved \\
{\bf \$26,\$27}                        & {\bf \$k0,\$k1}           & Reserved for kernel \\
{\bf \$28}                             & {\bf \$gp}                & Global pointer, preserve \\
{\bf \$29}                             & {\bf \$sp}                & Stack pointer, preserve \\
{\bf \$30}                             & {\bf \$fp}                & Frame pointer, preserve \\
{\bf \$31}                             & {\bf \$ra}                & Return address \\


\end{tabular*}
\caption{Register usage on MIPS O32 calling convention}
\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 different stack areas (e.g. parameter area, register save area, ...) are always aligned to 8 bytes.
\item first 4 32bit arguments are passed in registers \$a0-\$a3, respectively
\item subsequent parameters are passed vie the stack
\item @@@unsure... 64-bit floats and integers are passed on two integer registers starting at an even register number, probably skipping one odd register.
\item results are returned in \$v0 (32-bit integer), \$v0 and \$v1 (64-bit integer/float)
\item note that only s? registers that are modified by the function are required to be preserved on save area
\end{itemize}

\paragraph{Stack layout}

Stack directly after function prolog:\\

\begin{figure}[h]
\begin{tabular}{5|3|1 1}
\hhline{~-~~}
                                         & \vdots         &                                &                              \\
\hhline{~=~~}                            
local data                               & \hspace{4cm}   &                                & \mrrbrace{12}{caller's frame} \\
\hhline{~-~~}                            
register save area                       & return address &                                &   \\
                                         & s7             &                                &   \\
                                         & \vdots         &                                &   \\
                                         & s0             &                                &   \\
\hhline{~-~~}                                             
\mrlbrace{7}{parameter area}             & \ldots         & \mrrbrace{3}{stack parameters} &                              \\
                                         & \ldots         &                                &                              \\
                                         & \ldots         &                                &                              \\
                                         & a3             & \mrrbrace{4}{spill area}       &                              \\
                                         & a2             &                                &                              \\
                                         & a1             &                                &                              \\
                                         & a0             &                                &                              \\
\hhline{~=~~}                                             
local data                               &                &                                & \mrrbrace{5}{current frame}  \\
\hhline{~-~~}                                             
register save area (with return address) &                &                                &                              \\
\hhline{~-~~}                                             
parameter area                           &                &                                &                              \\
                                         & \vdots         &                                &                              \\
\hhline{~-~~}
\end{tabular}
\caption{Stack layout on MIPS O32 calling convention}
\end{figure}

\newpage

\subsubsection{MIPS N32 32-bit Calling Convention}

@@@