changeset 117:4a64b733dc76

- doc, added first version of mips64 callconv page - cleanups, todo update
author cslag
date Sun, 03 Jul 2016 01:39:37 +0200
parents c5cb02203df4
children f0437f85091b
files ToDo doc/manual/callconvs/callconv_arm32.tex doc/manual/callconvs/callconv_arm64.tex doc/manual/callconvs/callconv_mips.tex doc/manual/callconvs/callconv_mips64.tex doc/manual/manual_literature.tex
diffstat 6 files changed, 147 insertions(+), 51 deletions(-) [+]
line wrap: on
line diff
--- a/ToDo	Thu Jun 23 12:38:51 2016 +0200
+++ b/ToDo	Sun Jul 03 01:39:37 2016 +0200
@@ -35,6 +35,8 @@
   be used to test dycnall bindings
 - pkg-config support?
 - quadmath support (long double)
+- add tests using alloca(), as this might depend on the frame pointer being correctly
+  set; we don't check for this, currently, at all
 
 portasm:
 --------
@@ -101,6 +103,8 @@
 - provide more examples on how to use dyncall, dynload and dyncallback
   * e.g. enhance manual with a couple of examples (e.g. calling MessageBoxA on windows, etc.)
 - manuals for bindings (as stated in bindings-section, above)
+- under "dyncall support", in each calling convention appendix, list crucial details of e.g. big/little endian support, etc.
+- specify integer models in use, use common ILP32, LLP64, etc. terms
 
 regressions:
 ------------
--- a/doc/manual/callconvs/callconv_arm32.tex	Thu Jun 23 12:38:51 2016 +0200
+++ b/doc/manual/callconvs/callconv_arm32.tex	Sun Jul 03 01:39:37 2016 +0200
@@ -1,5 +1,5 @@
 %
-% Copyright (c) 2007,2010 Daniel Adler <dadler@uni-goettingen.de>, 
+% Copyright (c) 2007,2010 Daniel Adler <dadler@uni-goettingen.de>,
 %                         Tassilo Philipp <tphilipp@potion-studios.com>
 %
 % Permission to use, copy, modify, and distribute this software for any
@@ -22,8 +22,8 @@
 
 \paragraph{Overview}
 
-The ARM32 family of processors is based on 
-the Advanced RISC Machines (ARM) processor architecture (32 bit RISC). 
+The ARM32 family of processors is based on the Advanced RISC Machines (ARM)
+processor architecture (32 bit RISC).
 The word size is 32 bits (and the programming model is LLP64).\\
 Basically, this family of microprocessors can be run in 2 major modes:\\
 \\
@@ -102,20 +102,20 @@
 register save area                       & \hspace{4cm} &                                      & \mrrbrace{5}{caller's frame} \\
 \hhline{~-~~}
 local data                               &              &                                      &                              \\
-\hhline{~-~~}                                           
+\hhline{~-~~}
 \mrlbrace{7}{parameter area}             & \ldots       & \mrrbrace{3}{stack parameters}       &                              \\
                                          & \ldots       &                                      &                              \\
                                          & \ldots       &                                      &                              \\
-\hhline{~=~~}                                           
+\hhline{~=~~}
                                          & r3           & \mrrbrace{4}{spill area (if needed)} & \mrrbrace{7}{current frame}  \\
                                          & r2           &                                      &                              \\
                                          & r1           &                                      &                              \\
                                          & r0           &                                      &                              \\
-\hhline{~-~~}                                           
+\hhline{~-~~}
 register save area (with return address) &              &                                      &                              \\
-\hhline{~-~~}                                           
+\hhline{~-~~}
 local data                               &              &                                      &                              \\
-\hhline{~-~~}                                           
+\hhline{~-~~}
 parameter area                           & \vdots       &                                      &                              \\
 \hhline{~-~~}
 \end{tabular}
@@ -188,24 +188,24 @@
 \begin{tabular}{5|3|1 1}
 \hhline{~-~~}
                                          & \vdots       &                                      &                              \\
-\hhline{~=~~}                                           
+\hhline{~=~~}
 register save area                       & \hspace{4cm} &                                      & \mrrbrace{5}{caller's frame} \\
-\hhline{~-~~}                                           
+\hhline{~-~~}
 local data                               &              &                                      &                              \\
-\hhline{~-~~}                                           
+\hhline{~-~~}
 \mrlbrace{7}{parameter area}             & \ldots       & \mrrbrace{3}{stack parameters}       &                              \\
                                          & \ldots       &                                      &                              \\
                                          & \ldots       &                                      &                              \\
-\hhline{~=~~}                                           
+\hhline{~=~~}
                                          & r3           & \mrrbrace{4}{spill area (if needed)} & \mrrbrace{7}{current frame}  \\
                                          & r2           &                                      &                              \\
                                          & r1           &                                      &                              \\
                                          & r0           &                                      &                              \\
-\hhline{~-~~}                                           
+\hhline{~-~~}
 register save area (with return address) &              &                                      &                              \\
-\hhline{~-~~}                                           
+\hhline{~-~~}
 local data                               &              &                                      &                              \\
-\hhline{~-~~}                                           
+\hhline{~-~~}
 parameter area                           & \vdots       &                                      &                              \\
 \hhline{~-~~}
 \end{tabular}
@@ -350,8 +350,8 @@
 \subsubsection{Architectures}
 
 The ARM architecture family contains several revisions with capabilities and
-extensions (such as thumb-interworking, more vector registers, ...) 
-The following table sums up the most important properties of the various 
+extensions (such as thumb-interworking, more vector registers, ...)
+The following table sums up the most important properties of the various
 architecture standards, from a calling convention perspective.
 
 % iPhone 3GS : ARM Cortex-A8
@@ -368,8 +368,8 @@
 ARMv4T & ARM 7, ARM 9, Neo FreeRunner (OpenMoko) & \\
 ARMv5  & ARM 9E & BLX instruction available \\
 ARMv6  & & No vector registers available in thumb \\
-ARMv7  & iPod touch, iPhone 3GS/4, Raspberry Pi 2 & VFP throughout available, armhf calling convention on some platforms \\ 
-ARMv8  & iPhone 6 and higher & 64bit support \\ 
+ARMv7  & iPod touch, iPhone 3GS/4, Raspberry Pi 2 & VFP throughout available, armhf calling convention on some platforms \\
+ARMv8  & iPhone 6 and higher & 64bit support \\
 \end{tabular*}
 \caption{Overview of ARM Architecture, Platforms and Details}
 \end{table}
--- a/doc/manual/callconvs/callconv_arm64.tex	Thu Jun 23 12:38:51 2016 +0200
+++ b/doc/manual/callconvs/callconv_arm64.tex	Sun Jul 03 01:39:37 2016 +0200
@@ -22,9 +22,8 @@
 
 \paragraph{Overview}
 
-ARMv8 introduced the AArch64 calling convention. ARM64 chips can be run in 64 or 32bit mode, but not by the same process. Interworking is only intre-process.\\
-The word size is defined to be 32 bits, a dword 64 bits. Note that this is due to historical reasons (terminology
-didn't change from ARM32).\\
+ARMv8 introduced the AArch64 calling convention. ARM64 chips can be run in 64 or 32bit mode, but not by the same process. Interworking is only intra-process.\\
+The word size is defined to be 32 bits, a dword 64 bits. Note that this is due to historical reasons (terminology didn't change from ARM32).\\
 For more details, take a look at the Procedure Call Standard for the ARM 64-bit Architecture \cite{AAPCS64}.\\
 
 \paragraph{\product{dyncall} support}
--- a/doc/manual/callconvs/callconv_mips.tex	Thu Jun 23 12:38:51 2016 +0200
+++ b/doc/manual/callconvs/callconv_mips.tex	Sun Jul 03 01:39:37 2016 +0200
@@ -17,14 +17,13 @@
 %
 %//////////////////////////////////////////////////////////////////////////////
 
-\subsection{MIPS Calling Convention}
+\subsection{MIPS32 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: 
+Nowadays, MIPS32 and MIPS64 are the main ones used for 32-bit and 64-bit instruction sets, respectively.\\
+Given MIPS processor are often used for embedded devices, several add-on extensions exist for the MIPS family, for example: 
 
 \begin{description}
 \item [MIPS-3D] simple floating-point SIMD instructions dedicated to common 3D tasks.
@@ -33,13 +32,13 @@
 \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}.\\
+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}\cite{MIPSo64}, \emph{N32}\cite{MIPSn32/n64}, \emph{N64}\cite{MIPSn32/n64}, \emph{EABI}\cite{MIPSeabi} and \emph{NUBI}\cite{MIPSnubi}.\\
 
 \paragraph{\product{dyncall} support}
 
-Currently, dyncall supports for MIPS 32-bit architectures the O32 calling convention, as well as EABI (which is used on the Homebrew SDK for
-the Playstation Portable). For MIPS 64-bit machines, dyncall supports the N32 and N64 calling conventions.
+Currently, dyncall supports for MIPS 32-bit architectures the widely-used O32 calling convention, as well as EABI (which is used on the Homebrew SDK for
+the Playstation Portable). \product{dyncall} currently does not support MIPS16e (contrary to the like-minded ARM-THUMB, which is supported). Both, calls and callbacks are supported.
 
 \subsubsection{MIPS EABI 32-bit Calling Convention}
 
@@ -64,7 +63,7 @@
 {\bf hi, lo}                           &                      & Multiply/divide special registers \\
 {\bf \$f0,\$f2}                        &                      & Float results \\
 {\bf \$f1,\$f3,\$f4-\$f11,\$f20-\$f23} &                      & Float temporaries \\
-{\bf \$f12-\$f19}                      &                      & Single precisition float arguments \\
+{\bf \$f12-\$f19}                      &                      & Single precision float arguments \\
 \end{tabular*}
 \caption{Register usage on MIPS32 EABI calling convention}
 \end{table}
@@ -95,7 +94,7 @@
 \hhline{~=~~}                            
 register save area                       & \hspace{4cm} &                                & \mrrbrace{5}{caller's frame} \\
 \hhline{~-~~}                            
-local data                               &              &                                &   \\
+local data                               &              &                                &                              \\
 \hhline{~-~~}                            
 \mrlbrace{3}{parameter area}             & \ldots       & \mrrbrace{3}{stack parameters} &                              \\
                                          & \ldots       &                                &                              \\
@@ -131,7 +130,7 @@
 {\bf \$25}                   & {\bf \$t9}           & 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 \$k0,\$k1}      & reserved for kernel \\
-{\bf \$28}                   & {\bf \$gp}           & global pointer, preserve \\
+{\bf \$28}                   & {\bf \$gp}           & global pointer, preserved by caller \\
 {\bf \$29}                   & {\bf \$sp}           & stack pointer, preserve \\
 {\bf \$30}                   & {\bf \$fp}           & frame pointer, preserve \\
 {\bf \$31}                   & {\bf \$ra}           & return address, preserve \\
@@ -168,29 +167,29 @@
 \begin{figure}[h]
 \begin{tabular}{5|3|1 1}
 \hhline{~-~~}
-                                         & \vdots         &                                &                              \\
+                                         & \vdots         &                                &                               \\
 \hhline{~=~~}                            
 local data                               & \hspace{4cm}   &                                & \mrrbrace{12}{caller's frame} \\
 \hhline{~-~~}                            
-register save area                       & return address &                                &   \\
-                                         & s7             &                                &   \\
-                                         & \vdots         &                                &   \\
-                                         & s0             &                                &   \\
+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             &                                &                              \\
+\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}  \\
+local data                               &                &                                & \mrrbrace{5}{current frame}   \\
 \hhline{~-~~}                                             
-register save area (with return address) &                &                                &                              \\
+register save area (with return address) &                &                                &                               \\
 \hhline{~-~~}                                             
-parameter area                           &                &                                &                              \\
-                                         & \vdots         &                                &                              \\
+parameter area                           &                &                                &                               \\
+                                         & \vdots         &                                &                               \\
 \hhline{~-~~}
 \end{tabular}
 \caption{Stack layout on MIPS O32 calling convention}
--- a/doc/manual/callconvs/callconv_mips64.tex	Thu Jun 23 12:38:51 2016 +0200
+++ b/doc/manual/callconvs/callconv_mips64.tex	Sun Jul 03 01:39:37 2016 +0200
@@ -21,11 +21,89 @@
 
 \paragraph{Overview}
 
-@@@\\
+There are two main ABIs in use for MIPS64 chips, \emph{N64}\cite{MIPSn32/n64} and \emph{N32}\cite{MIPSn32/n64}. Both are
+basically the same, except that N32 uses 32-bit pointers and long integers, instead of 64. All registers of a MIPS64 chip are considered
+to be 64-bit wide, even for the N32 calling convention.\\
+The word size is defined to be 32 bits, a dword 64 bits. Note that this is due to historical reasons (terminology didn't change from MIPS32).\\
+Other than that there are 64-bit versions of the other ABIs found for MIPS32, e.g. the EABI\cite{MIPSeabi} and O64\cite{MIPSo64}.
 
 \paragraph{\product{dyncall} support}
 
-Our test machine is a Loongson-CPU 2F subnotebook with OpenBSD.
+For MIPS 64-bit machines, dyncall supports the N32 and N64 calling conventions for calls and callbacks.
+Our test machine is a Loongson-CPU 2F subnotebook, as well as an EdgeRouter Lite, both running OpenBSD.
+
+\subsubsection{MIPS N64 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, or double precision float arguments\\
+{\bf \$12-\$15,\$24}                   & {\bf \$t4-\$t7,\$t8} & 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, preserve \\
+{\bf \$29}                             & {\bf \$sp}           & Stack pointer, preserve \\
+{\bf \$30}                             & {\bf \$s8}           & Frame pointer, preserve \\
+{\bf \$31}                             & {\bf \$ra}           & Return address, preserve \\
+{\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 \\
+{\bf \$f24-\$f31}                      &                      & Preserved \\%@@@on N32, this changes
+\end{tabular*}
+\caption{Register usage on MIPS N64 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 first 8 integers (<= 64-bit)are passed in registers \$a0-\$a7
+\item first 8 floating point arguments (single or double precision) are passed in registers \$f12-\$f19
+\item if either integer or float registers are used up, the stack is used
+\item all stack entries are 64-bit aligned
+\item results are returned in \$v0, and for a second one \$v1 is used
+\item float arguments passed in the variable part of a vararg call are passed like integers
+\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              & padding? @@@ &                                & \mrrbrace{7}{current frame}  \\
+                                & \$ra         &                                &                              \\
+                                & \$s8         &                                &                              \\
+                                & \$gp         &                                &                              \\
+\hhline{~-~~}
+local data                      &              &                                &                              \\
+\hhline{~-~~}
+parameter area                  &              &                                &                              \\
+\hhline{~-~~}
+                                & \vdots       &                                &                              \\
+\hhline{~-~~}
+\end{tabular}
+\caption{Stack layout on mips64 n64 calling convention}
+\end{figure}
+
--- a/doc/manual/manual_literature.tex	Thu Jun 23 12:38:51 2016 +0200
+++ b/doc/manual/manual_literature.tex	Sun Jul 03 01:39:37 2016 +0200
@@ -158,6 +158,22 @@
 	MIPS Calling Conventions Summary\\
 	\url{http://courses.cs.washington.edu/courses/cse410/09sp/examples/MIPSCallingConventionsSummary.pdf}
 
+\bibitem{MIPSo64}
+	MIPS O64 Application Binary Interface for GCC\\
+	\url{http://gcc.gnu.org/projects/mipso64-abi.html}
+
+\bibitem{MIPSn32/n64}
+	MIPSpro™ N32 ABI Handbook\\
+	\url{https://www.linux-mips.org/pub/linux/mips/doc/ABI/MIPS-N32-ABI-Handbook.pdf}
+
+\bibitem{MIPSeabi}
+	mips eabi documentation...\\
+	\url{http://www.cygwin.com/ml/binutils/2003-06/msg00436.html}
+
+\bibitem{MIPSnubi}
+	NUBI - A Revised ABI for the MIPS® Architecture\\
+	\url{ftp://ftp.linux-mips.org//pub/linux/mips/doc/NUBI/MD00438-2C-NUBIDESC-SPC-00.20.pdf}
+
 \bibitem{devkitPro}
 	devkitPro - homebrew game development\\
 	\url{http://www.devkitpro.org/}