Mercurial > pub > dyncall > dyncall
changeset 490:17287342e273
manual:
- removed all API description and referred to manual instead, to avoid outdated and/or duplicated doc
- cleanups and clarificaions
| author | Tassilo Philipp |
|---|---|
| date | Sun, 20 Mar 2022 14:26:55 +0100 |
| parents | 63f623bff0b9 |
| children | e3bf15207d93 |
| files | doc/manual/callconvs/callconv_x86.tex doc/manual/manual_bindings.tex doc/manual/manual_cc.tex doc/manual/manual_devel.tex doc/manual/manual_dyncall_api.tex doc/manual/manual_dyncallback_api.tex doc/manual/manual_dynload_api.tex doc/manual/manual_epilog.tex |
| diffstat | 8 files changed, 409 insertions(+), 451 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/manual/callconvs/callconv_x86.tex Fri Mar 18 12:36:49 2022 +0100 +++ b/doc/manual/callconvs/callconv_x86.tex Sun Mar 20 14:26:55 2022 +0100 @@ -64,8 +64,8 @@ the syscall number as target parameter and selecting the correct mode. -\clearpage +\pagebreak \subsubsection{cdecl} @@ -142,8 +142,7 @@ \end{figure} -\clearpage - +\pagebreak \subsubsection{MS fastcall} @@ -180,6 +179,8 @@ aggregate doesn't fit entirely into ecx and edx, it is passed via the stack and remaining registers are free for subsequent arguments) \end{itemize} +\clearpage + \paragraph{Return values} \begin{itemize} @@ -245,6 +246,9 @@ \caption{Register usage on x86 fastcall (GNU) calling convention} \end{table} + +\clearpage + \paragraph{Parameter passing} \begin{itemize} @@ -269,8 +273,6 @@ \end{itemize} -\pagebreak - \paragraph{Stack layout} Stack directly after function prolog:\\ @@ -301,6 +303,8 @@ \end{figure} +\pagebreak + \subsubsection{Borland fastcall} Also called {\bf register convention} by Borland. @@ -340,8 +344,6 @@ \end{itemize} -\pagebreak - \paragraph{Return values} \begin{itemize} @@ -384,6 +386,8 @@ \end{figure} +\pagebreak + \subsubsection{Watcom fastcall} @@ -460,6 +464,7 @@ \end{figure} +\pagebreak \subsubsection{win32 stdcall} @@ -537,6 +542,9 @@ \caption{Stack layout on x86 stdcall calling convention} \end{figure} + +\pagebreak + \subsubsection{MS thiscall} \paragraph{Registers and register usage} @@ -559,8 +567,6 @@ \caption{Register usage on x86 thiscall (MS) calling convention} \end{table} -\clearpage - \paragraph{Parameter passing} @@ -699,8 +705,6 @@ -\clearpage - \subsubsection{plan9call} \paragraph{Registers and register usage} @@ -734,7 +738,6 @@ \item aggregates (structs, unions) are pushed as a sequence of dwords \end{itemize} -\pagebreak \paragraph{Return values} @@ -773,8 +776,6 @@ \end{figure} -\clearpage - \subsubsection{Linux syscalls} \paragraph{Parameter passing} @@ -787,6 +788,7 @@ \item register eax holds the return value \end{itemize} + \subsubsection{*BSD syscalls} \paragraph{Parameter passing}
--- a/doc/manual/manual_bindings.tex Fri Mar 18 12:36:49 2022 +0100 +++ b/doc/manual/manual_bindings.tex Sun Mar 20 14:26:55 2022 +0100 @@ -105,6 +105,7 @@ \sigchar{d} & double \\ \sigchar{p} & void* \\ \sigchar{Z} & const char* (pointing to C string) \\ +\sigchar{A} & aggregate (struct, union) by-value \\ \end{tabular*} \caption{Type signature encoding for function call data types} \label{sigchar} @@ -132,6 +133,7 @@ Signature character & Calling Convention \\ \hline \sigchar{:} & platform's default calling convention \\ +\sigchar{*} & platform's default C++/thiscall calling convention \\ \sigchar{e} & vararg function \\ \sigchar{.} & vararg function's variadic/ellipsis part (...), to be specified before first vararg \\ \sigchar{c} & only on x86: cdecl \\ @@ -154,7 +156,6 @@ \paragraph{Examples of C function prototypes} \begin{table}[h] -\begin{center} \begin{tabular*}{0.75\textwidth}{rll} & C function prototype & dyncall signature \\ \hline @@ -163,11 +164,12 @@ long long & f3(void*); & \sigstr{p)L}\\ void & f3(int**); & \sigstr{p)v}\\ double & f4(int, bool, char, double, const char*); & \sigstr{iBcdZ)d}\\ -void & f5(short a, long long b, ...) & \sigstr{\_esl\_.di)v} (for (promoted) varargs: double, int)\\ +void & f5(short, long long, ...); & \sigstr{\_esl\_.di)v} (for (promoted) varargs: double, int)\\ +struct A & f6(int, union B); & \sigstr{iA)A}\\ +short & Cls::f(unsigned char, ...); & \sigstr{\_*p\_eC\_.i)A} (C++: this-ptr as 1st arg, int as vararg)\\ \end{tabular*} -\caption{Type signature examples of C function prototypes} +\caption{Type signature examples of function prototypes} \label{sigex} -\end{center} \end{table} @@ -237,8 +239,7 @@ namely {\tt load}, {\tt find}, {\tt free}, {\tt call}, {\tt new\_callback}, {\tt free\_callback}. \begin{table}[h] -\begin{center} -\begin{tabular*}{0.75\textwidth}{lll} +\begin{tabular*}{1.0\textwidth}{lll} Signature character & accepted Python 2 types & accepted Python 3 types \\ \hline \sigchar{v} & no return type & no return type \\ @@ -255,7 +256,6 @@ \end{tabular*} \caption{Type signature encoding for Python bindings} \label{Pysigchar} -\end{center} \end{table} This is a very brief description that omits many details. For more, refer to the README.txt file of the binding.
--- a/doc/manual/manual_cc.tex Fri Mar 18 12:36:49 2022 +0100 +++ b/doc/manual/manual_cc.tex Sun Mar 20 14:26:55 2022 +0100 @@ -17,11 +17,7 @@ % %////////////////////////////////////////////////////////////////////////////// -\clearpage - -% ================================================== -% Calling Conventions -% ================================================== +\newpage \section{Calling Conventions} @@ -30,10 +26,10 @@ It is important to understand that this section isn't a general purpose description of the present calling conventions. It merely explains the calling conventions \textbf{for the parameter/return types -supported by \dc}, not for aggregates (structures, unions and classes), SIMD -data types (\_\_m64, \_\_m128, \_\_m128i, \_\_m128d), etc.\\ -We strongly advise the reader not to use this document as a general purpose -calling convention reference. +supported by \dc} (not for e.g. unsupported types like SIMD data types +(\_\_m64, \_\_m128, \_\_m128i, \_\_m128d), etc.).\\ We strongly advise the +reader not to use this document as a general purpose calling convention +reference. \input{callconvs/callconv_x86}\clearpage \input{callconvs/callconv_x64}\clearpage
--- a/doc/manual/manual_devel.tex Fri Mar 18 12:36:49 2022 +0100 +++ b/doc/manual/manual_devel.tex Sun Mar 20 14:26:55 2022 +0100 @@ -61,7 +61,7 @@ \item [suite\_floats] Based on suite. Test double/float variants with up to 10 arguments. -\item [suite\_aggrs] +\item [call\_suite\_aggrs] Tests passing and returning aggregates by value (struct/union and array members). Test cases can be designed in a signature-style format (and random ones generated via a Lua script).
--- a/doc/manual/manual_dyncall_api.tex Fri Mar 18 12:36:49 2022 +0100 +++ b/doc/manual/manual_dyncall_api.tex Sun Mar 20 14:26:55 2022 +0100 @@ -20,281 +20,229 @@ \clearpage \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} -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\\ -\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\\ -DCshort & short\\ -DCint & int\\ -DClong & long\\ -DClonglong & long long\\ -DCfloat & float\\ -DCdouble & double\\ -DCpointer & void*\\ -DCvoid & void\\ -\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} +See the dyncall(3) manpage for more information. -\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. 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} +%@@@ removed, as manpages are more precise and up to date -------------------> -\begin{table}[h] -\begin{center} -\begin{tabular*}{0.95\textwidth}{ll} -Constant & Description\\ -\hline -\lstinline@DC_CALL_C_DEFAULT@ & C default function call for current platform\\ -\lstinline@DC_CALL_C_DEFAULT_THIS@ & C++ default method call for current platform\\ -\lstinline@DC_CALL_C_ELLIPSIS@ & C ellipsis function call (named arguments (before '...', but after hidden args))\\ -\lstinline@DC_CALL_C_ELLIPSIS_VARARGS@ & C ellipsis function call (variable/unnamed arguments (starting with '...'))\\ -\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 thiscall\\ -\lstinline@DC_CALL_C_X86_WIN32_THIS_GNU@ & alias for DC\_CALL\_C\_X86\_CDECL (GNU thiscalls identical to cdecl)\\ -\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_WIN64_THIS@ & C++ x64 Windows thiscall\\ -\lstinline@DC_CALL_C_X64_SYSV@ & C x64 System V standard call\\ -\lstinline@DC_CALL_C_X64_SYSV_THIS@ & C++ x64 System V thiscall\\ -\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_X64_SYSCALL_SYSV@ & C syscall for x64 System V platforms\\ -\lstinline@DC_CALL_SYS_PPC32@ & C syscall for ppc32\\ -\lstinline@DC_CALL_SYS_PPC64@ & C syscall for ppc64\\ -\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 a new call. This -function should be called after setting the call mode (using dcMode), but prior -to binding arguments to the CallVM (except for when setting mode -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* 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 (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}. - +%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}. +%
--- a/doc/manual/manual_dyncallback_api.tex Fri Mar 18 12:36:49 2022 +0100 +++ b/doc/manual/manual_dyncallback_api.tex Sun Mar 20 14:26:55 2022 +0100 @@ -17,84 +17,87 @@ % %////////////////////////////////////////////////////////////////////////////// -\clearpage \section{\emph{Dyncallback} C library API} -This library extends \product{dyncall} with function callback support, allowing -the user to dynamically create a callback object that can be called directly, -or passed to functions expecting a function-pointer as argument.\\ -\\ -Invoking a \product{dyncallback} calls into a user-defined unified handler that -permits iteration and thus dynamic handling over the called-back-function's -parameters.\\ -\\ -The flexibility is constrained by the set of supported types, though.\\ -\\ -For style conventions and supported types, see \product{dyncall} API section. -In order to use \product{dyncallback}, include {\tt "dyncall\_callback.h"}. - -\subsection{Callback Object} - -The \emph{Callback Object} is the core component to this library. - -\paragraph{Types} - -\begin{lstlisting}[language=c] -typedef struct DCCallback DCCallback; -\end{lstlisting} - -\paragraph{Details} -The \emph{Callback Object} is an object that mimics a fully typed function -call to another function (a generic callback handler, in this case).\\ -\\ -This means, a pointer to this object is passed to a function accepting a pointer -to a callback function \emph{as the very callback function pointer itself}. -Or, if called directly, cast a pointer to this object to a function pointer and -issue a call. - - -\subsection{Allocation} - -\paragraph{Functions} +See the dyncallback(3) manpage for more information. -\begin{lstlisting}[language=c] -DCCallback* dcbNewCallback(const char* signature, - DCCallbackHandler* funcptr, - void* userdata, - DCaggr** aggrs); -void dcbFreeCallback(DCCallback* pcb); -\end{lstlisting} - -\lstinline{dcbNewCallback} creates and initializes a new \emph{Callback} object, -where \lstinline{signature} is the needed function signature (format is the -one outlined in the language bindings-section of this manual, see Table \ref{sigchar}) -of the function to mimic, \lstinline{funcptr} is a pointer to a callback handler, -and \lstinline{userdata} a pointer to custom data that might be useful in the -handler. -Use \lstinline{dcbFreeCallback} to destroy the \emph{Callback} object.\\ -\\ -As with \capi{dcNewCallVM}/\capi{dcFree}, this will allocate memory using the -system allocators or custom overrides. - - -\subsection{Callback handler} - -The unified callback handler's declaration used when creating a \capi{DCCallback} -is: - -\begin{lstlisting} -char cbHandler(DCCallback* cb, - DCArgs* args, - DCValue* result, - void* userdata); -\end{lstlisting} - -\capi{cb} is a pointer to the \capi{DCCallback} object in use, \capi{args} allows -for dynamic iteration over the called-back-function's arguments (input) and -\capi{result} is a pointer to a \capi{DCValue} object in order to store the -callback's return value (output, to be set by handler).\\ -Finally, \capi{userdata} is a pointer to some user defined data that can be -set when creating the callback object. -The handler itself returns a signature character (see Table \ref{sigchar}) specifying the -data type used for \capi{result}. - +%@@@ removed, as manpages are more precise and up to date -------------------> +% +%This library extends \product{dyncall} with function callback support, allowing +%the user to dynamically create a callback object that can be called directly, +%or passed to functions expecting a function-pointer as argument.\\ +%\\ +%Invoking a \product{dyncallback} calls into a user-defined unified handler that +%permits iteration and thus dynamic handling over the called-back-function's +%parameters.\\ +%\\ +%The flexibility is constrained by the set of supported types, though.\\ +%\\ +%For style conventions and supported types, see \product{dyncall} API section. +%In order to use \product{dyncallback}, include {\tt "dyncall\_callback.h"}. +% +%\subsection{Callback Object} +% +%The \emph{Callback Object} is the core component to this library. +% +%\paragraph{Types} +% +%\begin{lstlisting}[language=c] +%typedef struct DCCallback DCCallback; +%\end{lstlisting} +% +%\paragraph{Details} +%The \emph{Callback Object} is an object that mimics a fully typed function +%call to another function (a generic callback handler, in this case).\\ +%\\ +%This means, a pointer to this object is passed to a function accepting a pointer +%to a callback function \emph{as the very callback function pointer itself}. +%Or, if called directly, cast a pointer to this object to a function pointer and +%issue a call. +% +% +%\subsection{Allocation} +% +%\paragraph{Functions} +% +%\begin{lstlisting}[language=c] +%DCCallback* dcbNewCallback(const DCsigchar* signature, +% DCCallbackHandler* funcptr, +% void* userdata, +% DCaggr** aggrs); +%void dcbFreeCallback(DCCallback* pcb); +%\end{lstlisting} +% +%\lstinline{dcbNewCallback} creates and initializes a new \emph{Callback} object, +%where \lstinline{signature} is the needed function signature (format is the +%one outlined in the language bindings-section of this manual, see Table \ref{sigchar}) +%of the function to mimic, \lstinline{funcptr} is a pointer to a callback handler, +%and \lstinline{userdata} a pointer to custom data that might be useful in the +%handler. +%Use \lstinline{dcbFreeCallback} to destroy the \emph{Callback} object.\\ +%\\ +%As with \capi{dcNewCallVM}/\capi{dcFree}, this will allocate memory using the +%system allocators or custom overrides. +% +% +%\subsection{Callback handler} +% +%The unified callback handler's declaration used when creating a \capi{DCCallback} +%is: +% +%\begin{lstlisting} +%DCsigchar cbHandler(DCCallback* cb, +% DCArgs* args, +% DCValue* result, +% void* userdata); +%\end{lstlisting} +% +%\capi{cb} is a pointer to the \capi{DCCallback} object in use, \capi{args} allows +%for dynamic iteration over the called-back-function's arguments (input) and +%\capi{result} is a pointer to a \capi{DCValue} object in order to store the +%callback's return value (output, to be set by handler).\\ +%Finally, \capi{userdata} is a pointer to some user defined data that can be +%set when creating the callback object. +%The handler itself returns a signature character (see Table \ref{sigchar}) specifying the +%data type used for \capi{result}. +%
--- a/doc/manual/manual_dynload_api.tex Fri Mar 18 12:36:49 2022 +0100 +++ b/doc/manual/manual_dynload_api.tex Sun Mar 20 14:26:55 2022 +0100 @@ -17,71 +17,74 @@ % %////////////////////////////////////////////////////////////////////////////// -\clearpage \section{\product{Dynload} C library API} -The \product{dynload} library encapsulates dynamic loading mechanisms and -gives access to functions in foreign dynamic libraries and code modules. - -\subsection{Loading code} - -\begin{lstlisting}[language=c,label=dl-load] -DLLib* dlLoadLibrary(const char* libpath); -void dlFreeLibrary(void* libhandle); -\end{lstlisting} - -\lstinline{dlLoadLibrary} loads a dynamic library at \lstinline{libpath} -and returns a handle to it for use in \lstinline{dlFreeLibrary} and -\lstinline{dlFindSymbol} calls. Passing a null pointer for the \lstinline{libpath} -argument is valid, and returns a handle to the main executable of the calling code. -Also, searching libraries in library paths (e.g. by just passing the library's leaf -name) should work, however, they are OS specific. Returns a null pointer on error. - -\lstinline{dlFreeLibrary} frees the loaded library with handle \lstinline{pLib}. - -\subsection{Retrieving functions} - -\begin{lstlisting}[language=c] -void* dlFindSymbol(void* libhandle, const char* symbol); -\end{lstlisting} - -This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the -library with handle \lstinline{pLib}, or returns a null pointer if the symbol cannot -be found. The name is specified as it would appear in C source code (mangled if C++, etc.). +See the dynload(3) manpage for more information. -\subsection{Misc functions} -\begin{lstlisting}[language=c] -int dlGetLibraryPath(DLLib* pLib, char* sOut, int bufSize); -\end{lstlisting} - -This function can be used to get a copy of the path to the library loaded with handle -\lstinline{pLib}. The parameter \lstinline{sOut} is a pointer to a buffer of size -\lstinline{bufSize} (in bytes), to hold the output string. The return value is the size -of the buffer (in bytes) needed to hold the null-terminated string, or 0 if it can't be -looked up. If \lstinline{bufSize} \textgreater= return value \textgreater 1, a null-terminted string with the -path to the library should be in \lstinline{sOut}. If it returns 0, the library name wasn't -able to be found. Please note that this might happen in some rare cases, so make sure to always check. - -\subsection{Symbol iteration} - -\begin{lstlisting}[language=c] -DLSyms* dlSymsInit(const char* libPath); -void dlSymsCleanup(DLSyms* pSyms); -int dlSymsCount(DLSyms* pSyms); -const char* dlSymsName(DLSyms* pSyms, int index); -const char* dlSymsNameFromValue(DLSyms* pSyms, void* value); /* symbol must be loaded */ -\end{lstlisting} - - -These functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made -for symbol name lookups, not to get a symbol's address. For that refer to -\lstinline{dlFindSymbol}. \lstinline{dlSymsInit} will return a handle (or a null pointer -on error) to the shared object specified by \lstinline{libPath}, to be used with the other dlSyms* functions. Note that contrary -to loading and linking libraries, no (OS-specific) rules for searching libraries in library paths, etc. apply. The handle must be freed with -\lstinline{dlSymsCleanup}. \lstinline{dlSymsCount} returns the number of -symbols in the shared object, \lstinline{dlSymsName} and \lstinline{dlSymsNameFromValue} -are used to lookup symbol names using an index or symbol's address, respectively, -returning a null pointer on error. The names are returned as they would appear -in C source code (mangled if C++, etc.). The address passed to \lstinline{dlSymsNameFromValue} -must point to a loaded symbol. - +%@@@ removed, as manpages are more precise and up to date -------------------> +% +%The \product{dynload} library encapsulates dynamic loading mechanisms and +%gives access to functions in foreign dynamic libraries and code modules. +% +%\subsection{Loading code} +% +%\begin{lstlisting}[language=c,label=dl-load] +%DLLib* dlLoadLibrary(const char* libpath); +%void dlFreeLibrary(void* libhandle); +%\end{lstlisting} +% +%\lstinline{dlLoadLibrary} loads a dynamic library at \lstinline{libpath} +%and returns a handle to it for use in \lstinline{dlFreeLibrary} and +%\lstinline{dlFindSymbol} calls. Passing a null pointer for the \lstinline{libpath} +%argument is valid, and returns a handle to the main executable of the calling code. +%Also, searching libraries in library paths (e.g. by just passing the library's leaf +%name) should work, however, they are OS specific. Returns a null pointer on error. +% +%\lstinline{dlFreeLibrary} frees the loaded library with handle \lstinline{pLib}. +% +%\subsection{Retrieving functions} +% +%\begin{lstlisting}[language=c] +%void* dlFindSymbol(void* libhandle, const char* symbol); +%\end{lstlisting} +% +%This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the +%library with handle \lstinline{pLib}, or returns a null pointer if the symbol cannot +%be found. The name is specified as it would appear in C source code (mangled if C++, etc.). +% +%\subsection{Misc functions} +%\begin{lstlisting}[language=c] +%int dlGetLibraryPath(DLLib* pLib, char* sOut, int bufSize); +%\end{lstlisting} +% +%This function can be used to get a copy of the path to the library loaded with handle +%\lstinline{pLib}. The parameter \lstinline{sOut} is a pointer to a buffer of size +%\lstinline{bufSize} (in bytes), to hold the output string. The return value is the size +%of the buffer (in bytes) needed to hold the null-terminated string, or 0 if it can't be +%looked up. If \lstinline{bufSize} \textgreater= return value \textgreater 1, a null-terminted string with the +%path to the library should be in \lstinline{sOut}. If it returns 0, the library name wasn't +%able to be found. Please note that this might happen in some rare cases, so make sure to always check. +% +%\subsection{Symbol iteration} +% +%\begin{lstlisting}[language=c] +%DLSyms* dlSymsInit(const char* libPath); +%void dlSymsCleanup(DLSyms* pSyms); +%int dlSymsCount(DLSyms* pSyms); +%const char* dlSymsName(DLSyms* pSyms, int index); +%const char* dlSymsNameFromValue(DLSyms* pSyms, void* value); /* symbol must be loaded */ +%\end{lstlisting} +% +% +%These functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made +%for symbol name lookups, not to get a symbol's address. For that refer to +%\lstinline{dlFindSymbol}. \lstinline{dlSymsInit} will return a handle (or a null pointer +%on error) to the shared object specified by \lstinline{libPath}, to be used with the other dlSyms* functions. Note that contrary +%to loading and linking libraries, no (OS-specific) rules for searching libraries in library paths, etc. apply. The handle must be freed with +%\lstinline{dlSymsCleanup}. \lstinline{dlSymsCount} returns the number of +%symbols in the shared object, \lstinline{dlSymsName} and \lstinline{dlSymsNameFromValue} +%are used to lookup symbol names using an index or symbol's address, respectively, +%returning a null pointer on error. The names are returned as they would appear +%in C source code (mangled if C++, etc.). The address passed to \lstinline{dlSymsNameFromValue} +%must point to a loaded symbol. +%
--- a/doc/manual/manual_epilog.tex Fri Mar 18 12:36:49 2022 +0100 +++ b/doc/manual/manual_epilog.tex Sun Mar 20 14:26:55 2022 +0100 @@ -69,9 +69,15 @@ Currently, the \product{dyncall} library supports all of ANSI C's integer, floating point and pointer types as function call arguments and return values. -Additionally, C++'s \capi{bool} and C99's \capi{\_Bool} types are supported. +Additionally, C++'s \capi{bool} and C99's \capi{\_Bool} types are supported +across all supported platforms. Due to the still rare and often incomplete support of the \capi{long double} type on various platforms, the latter is currently not officially supported. +Also, \capi{\_Complex} is currently not supported. + +Passing or returning aggregates (struct, union) by value is supported, but only +on a limited set of platforms (check if the macro DC\_\_Feature\_AggrByVal is +defined). \subsection{Roadmap}