%//////////////////////////////////////////////////////////////////////////////
%
% Copyright (c) 2007,2010-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.
%
%//////////////////////////////////////////////////////////////////////////////
\clearpage
\section{\emph{Dyncall} C library API}
See the dyncall(3) manpage for more information.
%@@@ removed, as manpages are more precise and up to date ------------------->
%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}
%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\\
% & {\tt dcb\group{function name}} & & \capi{dcbNewCallback}, \ldots\\
% & {\tt dl\group{function name}} & & \capi{dlLoadLibrary}, \ldots\\
%\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}
%Type alias & C/C++ data type\\
%\hline
%DCbool & \_Bool, bool\\
%DCchar & char, unsigned char\\
%DCshort & short, unsigned short\\
%DCint & int, unsigned char\\
%DClong & long, unsigned char\\
%DClonglong & long long, unsigned char\\
%DCfloat & float\\
%DCdouble & double\\
%DCpointer & void*\\
%DCvoid & void\\
%\em{...} & \em{aggregates (struct, union)}
%\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.95\textwidth}{ll}
%Constant & Description\\
%\hline
%\lstinline@DC_ERROR_NONE@ & No error occured. \\
%\lstinline@DC_ERROR_UNSUPPORTED_MODE@ & Unsupported mode, caused by \lstinline@dcMode()@ \\
%\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. See dyncall.h for a list of available
%modes. 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.
%
%
%\subsection{Machine state reset}
%
%\begin{lstlisting}[language=c]
%void dcReset(DCCallVM* vm);
%\end{lstlisting}
%
%Resets the internal stack of arguments and prepares it for a new call. This
%function should be called after setting the initial/main call mode (using
%dcMode()), but prior to binding arguments to the CallVM (sometimes dcMode()
%calls are needed after pushing some args, e.g. DC\_SIGCHAR\_CC\_ELLIPSIS\_VARARGS,
%which is used prior to binding varargs of variadic functions). Use it also when
%reusing a CallVM, as arguments don't get flushed automatically after a function
%call invocation.\\
%Note: you should also call this function after initial creation of the a CallVM
%object, as dcNewCallVM doesn't do this, implicitly.
%
%
%\subsection{Argument binding}
%
%\paragraph{Functions}
%
%\begin{lstlisting}[language=c]
%void dcArgBool (DCCallVM*, DCbool);
%void dcArgChar (DCCallVM*, DCchar);
%void dcArgShort (DCCallVM*, DCshort);
%void dcArgInt (DCCallVM*, DCint);
%void dcArgLong (DCCallVM*, DClong);
%void dcArgLongLong(DCCallVM*, DClonglong);
%void dcArgFloat (DCCallVM*, DCfloat);
%void dcArgDouble (DCCallVM*, DCdouble);
%void dcArgPointer (DCCallVM*, DCpointer);
%void dcArgAggr (DCCallVM*, const DCaggr*, const void*);
%\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.\\
%\\
%See the dyncall(3) manpage for more information.
%
%
%\subsection{Call invocation}
%
%\paragraph{Functions}
%
%\begin{lstlisting}[language=c]
%DCvoid dcCallVoid (DCCallVM*, DCpointer);
%DCbool dcCallBool (DCCallVM*, DCpointer);
%DCchar dcCallChar (DCCallVM*, DCpointer);
%DCshort dcCallShort (DCCallVM*, DCpointer);
%DCint dcCallInt (DCCallVM*, DCpointer);
%DClong dcCallLong (DCCallVM*, DCpointer);
%DClonglong dcCallLongLong(DCCallVM*, DCpointer);
%DCfloat dcCallFloat (DCCallVM*, DCpointer);
%DCdouble dcCallDouble (DCCallVM*, DCpointer);
%DCpointer dcCallPointer (DCCallVM*, DCpointer);
%DCpointer dcCallAggr(DCCallVM*, DCpointer, const DCaggr*, DCpointer);
%void dcBeginCallAggr(DCCallVM*, const DCaggr*);
%\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}.\\
%\\
%See the dyncall(3) manpage for more information.
%
%\subsection{Formatted argument binding and calls (ANSI C ellipsis interface)}
%
%\paragraph{Functions}
%
%\begin{lstlisting}[language=c]
%void dcArgF (DCCallVM*, const DCsigchar*, ...);
%void dcVArgF (DCCallVM*, const DCsigchar*, va_list);
%void dcCallF (DCCallVM*, DCValue*, DCpointer, const DCsigchar*, ...);
%void dcVCallF(DCCallVM*, DCValue*, DCpointer, const DCsigchar*, va_list);
%\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 (and optionally also the calling convention used).
%\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}.
%