--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/manual/manual_dyncall_api.tex	Thu Mar 19 22:24:28 2015 +0100
@@ -0,0 +1,299 @@
+%//////////////////////////////////////////////////////////////////////////////
+%
+% 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
+% 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.
+%
+%//////////////////////////////////////////////////////////////////////////////
+
+\newpage
+\section{\emph{Dyncall} C library API}
+
+The library provides low-level functionality to make foreign function calls
+from different run-time environments. The flexibility is constrained by the
+set of supported types.
+
+\paragraph{C interface style conventions}
+
+This manual and the \product{dyncall} library's C interface {\tt "dyncall.h"}
+use the following C source code style.
+
+
+\begin{table}[h]
+\begin{center}
+\begin{tabular*}{0.8\textwidth}{llll}
+\hline
+Subject    & C symbol & Details & Example \\
+\hline  
+Types      
+  & {\tt DC\group{type name}}      
+  & lower-case & \capi{DCint}, \capi{DCfloat}, \capi{DClong}, \ldots\\
+Structures 
+  & {\tt DC\group{structure name}} 
+  & camel-case 
+  & \capi{DCCallVM}\\
+Functions  & {\tt dc\group{function name}}  & camel-case & \capi{dcNewCallVM}, \capi{dcArgInt}, \ldots\\
+\hline
+\end{tabular*}
+\caption{C interface conventions}
+\label{sourcecode}
+\end{center}
+\end{table}
+
+\subsection{Supported C/C++ argument and return types}
+
+\begin{table}[h]
+\begin{center}
+\begin{tabular*}{0.75\textwidth}{ll}
+\hline
+Type alias & C/C++ data type\\
+\hline
+DCbool     & \_Bool, bool\\
+DCchar     & char\\
+DCshort    & short\\
+DCint      & int\\
+DClong     & long\\
+DClonglong & long long\\
+DCfloat    & float\\
+DCdouble   & double\\
+DCpointer  & void*\\
+DCvoid     & void\\
+\hline
+\end{tabular*}
+\caption{Supported C/C++ argument and return types}
+\label{types}
+\end{center}
+\end{table}
+
+\pagebreak
+
+\subsection{Call Virtual Machine - CallVM}
+
+This \emph{CallVM} is the main entry to the functionality of the library.
+
+\paragraph{Types}
+
+\begin{lstlisting}[language=c]
+typedef void DCCallVM; /* abstract handle */
+\end{lstlisting}
+
+\paragraph{Details}
+The \emph{CallVM} is a state machine that manages all aspects of a function 
+call from configuration, argument passing up the actual function call on
+the processor.
+
+\subsection{Allocation}
+
+\paragraph{Functions}
+
+\begin{lstlisting}[language=c]
+DCCallVM* dcNewCallVM (DCsize size);
+void      dcFree(DCCallVM* vm);
+\end{lstlisting}
+
+\lstinline{dcNewCallVM} creates a new \emph{CallVM} object, where
+\lstinline{size} specifies the max size of the internal stack that will be
+allocated and used to bind arguments to. Use \lstinline{dcFree} to
+destroy the \emph{CallVM} object.\\
+\\
+This will allocate memory using the system allocators or custom ones provided
+custom \capi{dcAllocMem} and \capi{dcFreeMem} macros are defined to override the
+default behaviour. See \capi{dyncall\_alloc.h} for defails.
+
+
+\subsection{Error Reporting}
+
+\paragraph{Function}
+
+\begin{lstlisting}[language=c]
+DCint dcGetError(DCCallVM* vm);
+\end{lstlisting}
+
+Returns the most recent error state code out of the following:
+
+\paragraph{Errors}
+
+\begin{table}[h]
+\begin{center}
+\begin{tabular*}{0.75\textwidth}{ll}
+\hline
+Constant & Description\\
+\hline
+\lstinline@DC_ERROR_NONE@             & No error occured. \\
+\lstinline@DC_ERROR_UNSUPPORTED_MODE@ & Unsupported mode, caused by \lstinline@dcMode()@ \\
+\hline
+\end{tabular*}
+\caption{CallVM calling convention modes}
+\label{errorcodes}
+\end{center}
+\end{table}
+
+\pagebreak
+
+\subsection{Configuration}
+
+\paragraph{Function}
+
+\begin{lstlisting}[language=c]
+void dcMode (DCCallVM* vm, DCint mode);
+\end{lstlisting}
+
+Sets the calling convention to use. Note that some mode/platform combination
+don't make any sense (e.g. using a PowerPC calling convention on a MIPS
+platform) and are silently ignored.
+
+\paragraph{Modes}
+
+\begin{table}[h]
+\begin{center}
+\begin{tabular*}{0.75\textwidth}{ll}
+\hline
+Constant & Description\\
+\hline
+\lstinline@DC_CALL_C_DEFAULT@            & C default function call for current platform\\
+\lstinline@DC_CALL_C_ELLIPSIS@           & C ellipsis function call (named arguments (before '...'))\\
+\lstinline@DC_CALL_C_ELLIPSIS_VARARGS@   & C ellipsis function call (variable/unnamed arguments (after '...'))\\
+\lstinline@DC_CALL_C_X86_CDECL@          & C x86 platforms standard call\\
+\lstinline@DC_CALL_C_X86_WIN32_STD@      & C x86 Windows standard call\\
+\lstinline@DC_CALL_C_X86_WIN32_FAST_MS@  & C x86 Windows Microsoft fast call\\
+\lstinline@DC_CALL_C_X86_WIN32_FAST_GNU@ & C x86 Windows GCC fast call\\
+\lstinline@DC_CALL_C_X86_WIN32_THIS_MS@  & C x86 Windows Microsoft this call\\
+\lstinline@DC_CALL_C_X86_WIN32_THIS_GNU@ & C x86 Windows GCC this call\\
+\lstinline@DC_CALL_C_X86_PLAN9@          & C x86 Plan9 call\\
+\lstinline@DC_CALL_C_X64_WIN64@          & C x64 Windows standard call\\
+\lstinline@DC_CALL_C_X64_SYSV@           & C x64 System V standard call\\
+\lstinline@DC_CALL_C_PPC32_DARWIN@       & C ppc32 Mac OS X standard call\\
+\lstinline@DC_CALL_C_PPC32_OSX@          & alias for DC\_CALL\_C\_PPC32\_DARWIN\\
+\lstinline@DC_CALL_C_PPC32_SYSV@         & C ppc32 SystemV standard call\\
+\lstinline@DC_CALL_C_PPC32_LINUX@        & alias for DC\_CALL\_C\_PPC32\_SYSV\\
+\lstinline@DC_CALL_C_PPC64@              & C ppc64 SystemV standard call\\
+\lstinline@DC_CALL_C_PPC64_LINUX@        & alias for DC\_CALL\_C\_PPC64\\
+\lstinline@DC_CALL_C_ARM_ARM@            & C arm call (arm mode)\\
+\lstinline@DC_CALL_C_ARM_THUMB@          & C arm call (thumb mode)\\
+\lstinline@DC_CALL_C_ARM_ARM_EABI@       & C arm eabi call (arm mode)\\
+\lstinline@DC_CALL_C_ARM_THUMB_EABI@     & C arm eabi call (thumb mode)\\
+\lstinline@DC_CALL_C_ARM_ARMHF@          & C arm call (arm hardfloat - e.g. raspberry pi)\\
+\lstinline@DC_CALL_C_ARM64@              & C arm64 call (AArch64)\\
+\lstinline@DC_CALL_C_MIPS32_EABI@        & C mips32 eabi call\\
+\lstinline@DC_CALL_C_MIPS32_PSPSDK@      & alias for DC\_CALL\_C\_MIPS32\_EABI (deprecated)\\
+\lstinline@DC_CALL_C_MIPS32_O32@         & C mips32 o32 call\\
+\lstinline@DC_CALL_C_MIPS64_N64@         & C mips64 n64 call\\
+\lstinline@DC_CALL_C_MIPS64_N32@         & C mips64 n32 call\\
+\lstinline@DC_CALL_C_SPARC32@            & C sparc32 call\\
+\lstinline@DC_CALL_C_SPARC64@            & C sparc64 call\\
+\lstinline@DC_CALL_SYS_DEFAULT@          & C default syscall for current platform\\
+\lstinline@DC_CALL_SYS_X86_INT80H_BSD@   & C syscall for x86 BSD platforms\\
+\lstinline@DC_CALL_SYS_X86_INT80H_LINUX@ & C syscall for x86 Linux\\
+\lstinline@DC_CALL_SYS_PPC32@            & C syscall for ppc32 Linux\\
+\hline
+\end{tabular*}
+\caption{CallVM calling convention modes}
+\label{callingconventionmodes}
+\end{center}
+\end{table}
+
+\paragraph{Details}
+
+\lstinline@DC_CALL_C_DEFAULT@ is the default standard C call on the target
+platform. It uses the standard C calling convention.
+\lstinline@DC_CALL_C_ELLIPSIS@ is used for C ellipsis calls which allow
+to build up a variable argument list.
+On many platforms, there is only one C calling convention. 
+The X86 platform provides a rich family of different calling conventions.
+\\
+
+
+\subsection{Machine state reset}
+
+\begin{lstlisting}[language=c]
+void dcReset(DCCallVM* vm);
+\end{lstlisting}
+
+Resets the internal stack of arguments and prepares it for the selected mode.
+This function should be called after setting the call mode (using dcMode), but
+prior to binding arguments to the CallVM. Use it also when reusing a CallVM, as
+arguments don't get flushed automatically after a function call invocation.\\
+
+\subsection{Argument binding}
+
+\paragraph{Functions}
+
+\begin{lstlisting}[language=c]
+void dcArgBool    (DCCallVM* vm, DCbool     arg);
+void dcArgChar    (DCCallVM* vm, DCchar     arg);
+void dcArgShort   (DCCallVM* vm, DCshort    arg);
+void dcArgInt     (DCCallVM* vm, DCint      arg);
+void dcArgLong    (DCCallVM* vm, DClong     arg);
+void dcArgLongLong(DCCallVM* vm, DClonglong arg);
+void dcArgFloat   (DCCallVM* vm, DCfloat    arg);
+void dcArgDouble  (DCCallVM* vm, DCdouble   arg);
+void dcArgPointer (DCCallVM* vm, DCpointer  arg);
+\end{lstlisting}
+
+\paragraph{Details}
+
+Used to bind arguments of the named types to the CallVM object.
+Arguments should be bound in \emph{left-to-right} order regarding the C
+function prototype.\\
+
+\subsection{Call invocation}
+
+\paragraph{Functions}
+
+\begin{lstlisting}[language=c]
+DCvoid     dcCallVoid    (DCCallVM* vm, DCpointer funcptr);
+DCbool     dcCallBool    (DCCallVM* vm, DCpointer funcptr);
+DCchar     dcCallChar    (DCCallVM* vm, DCpointer funcptr);
+DCshort    dcCallShort   (DCCallVM* vm, DCpointer funcptr);
+DCint      dcCallInt     (DCCallVM* vm, DCpointer funcptr);
+DClong     dcCallLong    (DCCallVM* vm, DCpointer funcptr);
+DClonglong dcCallLongLong(DCCallVM* vm, DCpointer funcptr);
+DCfloat    dcCallFloat   (DCCallVM* vm, DCpointer funcptr);
+DCdouble   dcCallDouble  (DCCallVM* vm, DCpointer funcptr);
+DCpointer  dcCallPointer (DCCallVM* vm, DCpointer funcptr);
+\end{lstlisting}
+
+\paragraph{Details}
+Calls the function specified by \emph{funcptr} with the arguments bound to
+the \emph{CallVM} and returns. Use the function that corresponds to the
+dynamically called function's return value.\\
+\\
+After the invocation of the foreign function call, the argument values are
+still bound and a second call using the same arguments can be issued. If you
+need to clear the argument bindings, you have to reset the \emph{CallVM}.
+
+\subsection{Formatted argument binding and calls (ANSI C ellipsis interface)}
+
+\paragraph{Functions}
+
+\begin{lstlisting}[language=c]
+void dcArgF (DCCallVM* vm, const DCsigchar* signature, ...);
+void dcVArgF(DCCallVM* vm, const DCsigchar* signature, va_list args);
+void dcCallF (DCCallVM* vm, DCValue* result, DCpointer funcptr, 
+              const DCsigchar* signature, ...);
+void dcVCallF(DCCallVM* vm, DCValue* result, DCpointer funcptr, 
+              const DCsigchar* signature, va_list args);
+\end{lstlisting}
+
+\paragraph{Details}
+
+These functions can be used to operate \product{dyncall} via a printf-style
+functional interface, using a signature string encoding the argument types and 
+return type.
+\capi{dcArgF()} and \capi{dcVArgF()} just bind arguments to the \capi{DCCallVM}
+object, so any return value specified in the signature is ignored. \capi{dcCallF()}
+and \capi{dcVCallF()} also take a function pointer to call after binding the arguments.
+The return value will be stored in what \lstinline{result} points to.
+For more information about the signature format, refer to \ref{sigchar}.
+