Mercurial > pub > dyncall > dyncall
annotate doc/manual/manual_dyncall_api.tex @ 533:71c884e610f0
- integration of patches from Raphael Luba, Thekla, Inc.:
* integration of aggregate-by-value (struct, union) support patch for x64 (win and sysv)
* windows/x64 asm additions to specify how stack unwinds (help for debuggers, exception handling, etc.)
* see Changelog for details
- new calling convention modes for thiscalls (platform agnostic, was specific before)
* new signature character for platform agnostic thiscalls ('*' / DC_SIGCHAR_CC_THISCALL)
- dcCallF(), dcVCallF(), dcArgF() and dcVArgF():
* added support for aggregates-by-value (wasn't part of patch)
* change that those functions don't implicitly call dcReset() anymore, which was unflexible (breaking change)
- added macros to feature test implementation for aggregate-by-value and syscall support
- changed libdyncall_s.lib and libdyncallback_s.lib order in callback test makefiles, as some toolchains are picky about order
- doc:
* man page updates to describe aggregate interface
* manual overview changes to highlight platforms with aggregate-by-value support
- test/plain: replaced tests w/ old/stale sctruct interface with new aggregate one
| author | Tassilo Philipp |
|---|---|
| date | Thu, 21 Apr 2022 13:35:47 +0200 |
| parents | 17287342e273 |
| children |
| rev | line source |
|---|---|
| 0 | 1 %////////////////////////////////////////////////////////////////////////////// |
| 2 % | |
|
533
71c884e610f0
- integration of patches from Raphael Luba, Thekla, Inc.:
Tassilo Philipp
parents:
490
diff
changeset
|
3 % Copyright (c) 2007,2010-2022 Daniel Adler <dadler@uni-goettingen.de>, |
|
71c884e610f0
- integration of patches from Raphael Luba, Thekla, Inc.:
Tassilo Philipp
parents:
490
diff
changeset
|
4 % Tassilo Philipp <tphilipp@potion-studios.com> |
| 0 | 5 % |
| 6 % Permission to use, copy, modify, and distribute this software for any | |
| 7 % purpose with or without fee is hereby granted, provided that the above | |
| 8 % copyright notice and this permission notice appear in all copies. | |
| 9 % | |
| 10 % THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES | |
| 11 % WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF | |
| 12 % MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR | |
| 13 % ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES | |
| 14 % WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN | |
| 15 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF | |
| 16 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. | |
| 17 % | |
| 18 %////////////////////////////////////////////////////////////////////////////// | |
| 19 | |
| 467 | 20 \clearpage |
| 0 | 21 \section{\emph{Dyncall} C library API} |
| 22 | |
| 490 | 23 See the dyncall(3) manpage for more information. |
| 0 | 24 |
| 490 | 25 %@@@ removed, as manpages are more precise and up to date -------------------> |
| 0 | 26 |
| 490 | 27 %The library provides low-level functionality to make foreign function calls |
| 28 %from different run-time environments. The flexibility is constrained by the | |
| 29 %set of supported types. | |
| 30 % | |
| 31 %\paragraph{C interface style conventions} | |
| 32 % | |
| 33 %This manual and the \product{dyncall} library's C interface {\tt "dyncall.h"} | |
| 34 %use the following C source code style. | |
| 35 % | |
| 36 % | |
| 37 %\begin{table}[h] | |
| 38 %\begin{center} | |
| 39 %\begin{tabular*}{0.8\textwidth}{llll} | |
| 40 %Subject & C symbol & Details & Example \\ | |
| 41 %\hline | |
| 42 %Types & {\tt DC\group{type name}} & lower-case & \capi{DCint}, \capi{DCfloat}, \capi{DClong}, \ldots\\ | |
| 43 %Structures & {\tt DC\group{structure name}} & camel-case & \capi{DCCallVM}\\ | |
| 44 %Functions & {\tt dc\group{function name}} & camel-case & \capi{dcNewCallVM}, \capi{dcArgInt}, \ldots\\ | |
| 45 % & {\tt dcb\group{function name}} & & \capi{dcbNewCallback}, \ldots\\ | |
| 46 % & {\tt dl\group{function name}} & & \capi{dlLoadLibrary}, \ldots\\ | |
| 47 %\end{tabular*} | |
| 48 %\caption{C interface conventions} | |
| 49 %\label{sourcecode} | |
| 50 %\end{center} | |
| 51 %\end{table} | |
| 52 % | |
| 53 %\subsection{Supported C/C++ argument and return types} | |
| 54 % | |
| 55 %\begin{table}[h] | |
| 56 %\begin{center} | |
| 57 %\begin{tabular*}{0.75\textwidth}{ll} | |
| 58 %Type alias & C/C++ data type\\ | |
| 59 %\hline | |
| 60 %DCbool & \_Bool, bool\\ | |
| 61 %DCchar & char, unsigned char\\ | |
| 62 %DCshort & short, unsigned short\\ | |
| 63 %DCint & int, unsigned char\\ | |
| 64 %DClong & long, unsigned char\\ | |
| 65 %DClonglong & long long, unsigned char\\ | |
| 66 %DCfloat & float\\ | |
| 67 %DCdouble & double\\ | |
| 68 %DCpointer & void*\\ | |
| 69 %DCvoid & void\\ | |
| 70 %\em{...} & \em{aggregates (struct, union)} | |
| 71 %\end{tabular*} | |
| 72 %\caption{Supported C/C++ argument and return types} | |
| 73 %\label{types} | |
| 74 %\end{center} | |
| 75 %\end{table} | |
| 76 % | |
| 77 %\pagebreak | |
| 78 % | |
| 79 %\subsection{Call Virtual Machine - CallVM} | |
| 80 % | |
| 81 %This \emph{CallVM} is the main entry to the functionality of the library. | |
| 82 % | |
| 83 %\paragraph{Types} | |
| 84 % | |
| 85 %\begin{lstlisting}[language=c] | |
| 86 %typedef void DCCallVM; /* abstract handle */ | |
| 87 %\end{lstlisting} | |
| 88 % | |
| 89 %\paragraph{Details} | |
| 90 %The \emph{CallVM} is a state machine that manages all aspects of a function | |
| 91 %call from configuration, argument passing up the actual function call on | |
| 92 %the processor. | |
| 93 % | |
| 94 %\subsection{Allocation} | |
| 95 % | |
| 96 %\paragraph{Functions} | |
| 97 % | |
| 98 %\begin{lstlisting}[language=c] | |
| 99 %DCCallVM* dcNewCallVM (DCsize size); | |
| 100 %void dcFree(DCCallVM* vm); | |
| 101 %\end{lstlisting} | |
| 102 % | |
| 103 %\lstinline{dcNewCallVM} creates a new \emph{CallVM} object, where | |
| 104 %\lstinline{size} specifies the max size of the internal stack that will be | |
| 105 %allocated and used to bind arguments to. Use \lstinline{dcFree} to | |
| 106 %destroy the \emph{CallVM} object.\\ | |
| 107 %\\ | |
| 108 %This will allocate memory using the system allocators or custom ones provided | |
| 109 %custom \capi{dcAllocMem} and \capi{dcFreeMem} macros are defined to override the | |
| 110 %default behaviour. See \capi{dyncall\_alloc.h} for defails. | |
| 111 % | |
| 112 % | |
| 113 %\subsection{Error Reporting} | |
| 114 % | |
| 115 %\paragraph{Function} | |
| 116 % | |
| 117 %\begin{lstlisting}[language=c] | |
| 118 %DCint dcGetError(DCCallVM* vm); | |
| 119 %\end{lstlisting} | |
| 120 % | |
| 121 %Returns the most recent error state code out of the following: | |
| 122 % | |
| 123 %\paragraph{Errors} | |
| 124 % | |
| 125 %\begin{table}[h] | |
| 126 %\begin{center} | |
| 127 %\begin{tabular*}{0.95\textwidth}{ll} | |
| 128 %Constant & Description\\ | |
| 129 %\hline | |
| 130 %\lstinline@DC_ERROR_NONE@ & No error occured. \\ | |
| 131 %\lstinline@DC_ERROR_UNSUPPORTED_MODE@ & Unsupported mode, caused by \lstinline@dcMode()@ \\ | |
| 132 %\end{tabular*} | |
| 133 %\caption{CallVM calling convention modes} | |
| 134 %\label{errorcodes} | |
| 135 %\end{center} | |
| 136 %\end{table} | |
| 137 % | |
| 138 %\pagebreak | |
| 139 % | |
| 140 %\subsection{Configuration} | |
| 141 % | |
| 142 %\paragraph{Function} | |
| 143 % | |
| 144 %\begin{lstlisting}[language=c] | |
| 145 %void dcMode (DCCallVM* vm, DCint mode); | |
| 146 %\end{lstlisting} | |
| 147 % | |
| 148 %Sets the calling convention to use. See dyncall.h for a list of available | |
| 149 %modes. Note that some mode/platform combination don't make any sense (e.g. | |
| 150 %using a PowerPC calling convention on a MIPS platform) and are silently | |
| 151 %ignored. | |
| 152 % | |
| 153 % | |
| 154 %\subsection{Machine state reset} | |
| 155 % | |
| 156 %\begin{lstlisting}[language=c] | |
| 157 %void dcReset(DCCallVM* vm); | |
| 158 %\end{lstlisting} | |
| 159 % | |
| 160 %Resets the internal stack of arguments and prepares it for a new call. This | |
| 161 %function should be called after setting the initial/main call mode (using | |
| 162 %dcMode()), but prior to binding arguments to the CallVM (sometimes dcMode() | |
| 163 %calls are needed after pushing some args, e.g. DC\_SIGCHAR\_CC\_ELLIPSIS\_VARARGS, | |
| 164 %which is used prior to binding varargs of variadic functions). Use it also when | |
| 165 %reusing a CallVM, as arguments don't get flushed automatically after a function | |
| 166 %call invocation.\\ | |
| 167 %Note: you should also call this function after initial creation of the a CallVM | |
| 168 %object, as dcNewCallVM doesn't do this, implicitly. | |
| 169 % | |
| 170 % | |
| 171 %\subsection{Argument binding} | |
| 172 % | |
| 173 %\paragraph{Functions} | |
| 174 % | |
| 175 %\begin{lstlisting}[language=c] | |
| 176 %void dcArgBool (DCCallVM*, DCbool); | |
| 177 %void dcArgChar (DCCallVM*, DCchar); | |
| 178 %void dcArgShort (DCCallVM*, DCshort); | |
| 179 %void dcArgInt (DCCallVM*, DCint); | |
| 180 %void dcArgLong (DCCallVM*, DClong); | |
| 181 %void dcArgLongLong(DCCallVM*, DClonglong); | |
| 182 %void dcArgFloat (DCCallVM*, DCfloat); | |
| 183 %void dcArgDouble (DCCallVM*, DCdouble); | |
| 184 %void dcArgPointer (DCCallVM*, DCpointer); | |
| 185 %void dcArgAggr (DCCallVM*, const DCaggr*, const void*); | |
| 186 %\end{lstlisting} | |
| 187 % | |
| 188 %\paragraph{Details} | |
| 189 % | |
| 190 %Used to bind arguments of the named types to the CallVM object. | |
| 191 %Arguments should be bound in \emph{left-to-right} order regarding the C | |
| 192 %function prototype.\\ | |
| 193 %\\ | |
| 194 %See the dyncall(3) manpage for more information. | |
| 195 % | |
| 196 % | |
| 197 %\subsection{Call invocation} | |
| 198 % | |
| 199 %\paragraph{Functions} | |
| 200 % | |
| 201 %\begin{lstlisting}[language=c] | |
| 202 %DCvoid dcCallVoid (DCCallVM*, DCpointer); | |
| 203 %DCbool dcCallBool (DCCallVM*, DCpointer); | |
| 204 %DCchar dcCallChar (DCCallVM*, DCpointer); | |
| 205 %DCshort dcCallShort (DCCallVM*, DCpointer); | |
| 206 %DCint dcCallInt (DCCallVM*, DCpointer); | |
| 207 %DClong dcCallLong (DCCallVM*, DCpointer); | |
| 208 %DClonglong dcCallLongLong(DCCallVM*, DCpointer); | |
| 209 %DCfloat dcCallFloat (DCCallVM*, DCpointer); | |
| 210 %DCdouble dcCallDouble (DCCallVM*, DCpointer); | |
| 211 %DCpointer dcCallPointer (DCCallVM*, DCpointer); | |
| 212 %DCpointer dcCallAggr(DCCallVM*, DCpointer, const DCaggr*, DCpointer); | |
| 213 %void dcBeginCallAggr(DCCallVM*, const DCaggr*); | |
| 214 %\end{lstlisting} | |
| 215 % | |
| 216 %\paragraph{Details} | |
| 217 %Calls the function specified by \emph{funcptr} with the arguments bound to | |
| 218 %the \emph{CallVM} and returns. Use the function that corresponds to the | |
| 219 %dynamically called function's return value.\\ | |
| 220 %\\ | |
| 221 %After the invocation of the foreign function call, the argument values are | |
| 222 %still bound and a second call using the same arguments can be issued. If you | |
| 223 %need to clear the argument bindings, you have to reset the \emph{CallVM}.\\ | |
| 224 %\\ | |
| 225 %See the dyncall(3) manpage for more information. | |
| 226 % | |
| 227 %\subsection{Formatted argument binding and calls (ANSI C ellipsis interface)} | |
| 228 % | |
| 229 %\paragraph{Functions} | |
| 230 % | |
| 231 %\begin{lstlisting}[language=c] | |
| 232 %void dcArgF (DCCallVM*, const DCsigchar*, ...); | |
| 233 %void dcVArgF (DCCallVM*, const DCsigchar*, va_list); | |
| 234 %void dcCallF (DCCallVM*, DCValue*, DCpointer, const DCsigchar*, ...); | |
| 235 %void dcVCallF(DCCallVM*, DCValue*, DCpointer, const DCsigchar*, va_list); | |
| 236 %\end{lstlisting} | |
| 237 % | |
| 238 %\paragraph{Details} | |
| 239 % | |
| 240 %These functions can be used to operate \product{dyncall} via a printf-style | |
| 241 %functional interface, using a signature string encoding the argument types and | |
| 242 %return type (and optionally also the calling convention used). | |
| 243 %\capi{dcArgF()} and \capi{dcVArgF()} just bind arguments to the \capi{DCCallVM} | |
| 244 %object, so any return value specified in the signature is ignored. \capi{dcCallF()} | |
| 245 %and \capi{dcVCallF()} also take a function pointer to call after binding the arguments. | |
| 246 %The return value will be stored in what \lstinline{result} points to. | |
| 247 %For more information about the signature format, refer to \ref{sigchar}. | |
| 248 % |