--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/callconvs/callconv_mips.tex	Thu Mar 19 22:24:28 2015 +0100
@@ -0,0 +1,117 @@
+%//////////////////////////////////////////////////////////////////////////////
+%
+% 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{32}, \emph{O64}, \emph{N32}, \emph{64} 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.
+
+\subsubsection{MIPS EABI 32-bit Calling Convention}
+
+\paragraph{Register usage}
+
+\begin{table}[h]
+\begin{tabular}{lll}
+\hline
+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 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 integer), \$v0 and \$v1 (64-bit integer/float), \$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                &                            &                                & \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}
+