|
0
|
1 %//////////////////////////////////////////////////////////////////////////////
|
|
|
2 %
|
|
|
3 % Copyright (c) 2007,2010 Daniel Adler <dadler@uni-goettingen.de>,
|
|
|
4 % Tassilo Philipp <tphilipp@potion-studios.com>
|
|
|
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
|
|
|
20 \newpage
|
|
|
21 \section{\emph{Dyncall} C library API}
|
|
|
22
|
|
|
23 The library provides low-level functionality to make foreign function calls
|
|
|
24 from different run-time environments. The flexibility is constrained by the
|
|
|
25 set of supported types.
|
|
|
26
|
|
|
27 \paragraph{C interface style conventions}
|
|
|
28
|
|
|
29 This manual and the \product{dyncall} library's C interface {\tt "dyncall.h"}
|
|
|
30 use the following C source code style.
|
|
|
31
|
|
|
32
|
|
|
33 \begin{table}[h]
|
|
|
34 \begin{center}
|
|
|
35 \begin{tabular*}{0.8\textwidth}{llll}
|
|
|
36 \hline
|
|
|
37 Subject & C symbol & Details & Example \\
|
|
|
38 \hline
|
|
|
39 Types
|
|
|
40 & {\tt DC\group{type name}}
|
|
|
41 & lower-case & \capi{DCint}, \capi{DCfloat}, \capi{DClong}, \ldots\\
|
|
|
42 Structures
|
|
|
43 & {\tt DC\group{structure name}}
|
|
|
44 & camel-case
|
|
|
45 & \capi{DCCallVM}\\
|
|
|
46 Functions & {\tt dc\group{function name}} & camel-case & \capi{dcNewCallVM}, \capi{dcArgInt}, \ldots\\
|
|
|
47 \hline
|
|
|
48 \end{tabular*}
|
|
|
49 \caption{C interface conventions}
|
|
|
50 \label{sourcecode}
|
|
|
51 \end{center}
|
|
|
52 \end{table}
|
|
|
53
|
|
|
54 \subsection{Supported C/C++ argument and return types}
|
|
|
55
|
|
|
56 \begin{table}[h]
|
|
|
57 \begin{center}
|
|
|
58 \begin{tabular*}{0.75\textwidth}{ll}
|
|
|
59 \hline
|
|
|
60 Type alias & C/C++ data type\\
|
|
|
61 \hline
|
|
|
62 DCbool & \_Bool, bool\\
|
|
|
63 DCchar & char\\
|
|
|
64 DCshort & short\\
|
|
|
65 DCint & int\\
|
|
|
66 DClong & long\\
|
|
|
67 DClonglong & long long\\
|
|
|
68 DCfloat & float\\
|
|
|
69 DCdouble & double\\
|
|
|
70 DCpointer & void*\\
|
|
|
71 DCvoid & void\\
|
|
|
72 \hline
|
|
|
73 \end{tabular*}
|
|
|
74 \caption{Supported C/C++ argument and return types}
|
|
|
75 \label{types}
|
|
|
76 \end{center}
|
|
|
77 \end{table}
|
|
|
78
|
|
|
79 \pagebreak
|
|
|
80
|
|
|
81 \subsection{Call Virtual Machine - CallVM}
|
|
|
82
|
|
|
83 This \emph{CallVM} is the main entry to the functionality of the library.
|
|
|
84
|
|
|
85 \paragraph{Types}
|
|
|
86
|
|
|
87 \begin{lstlisting}[language=c]
|
|
|
88 typedef void DCCallVM; /* abstract handle */
|
|
|
89 \end{lstlisting}
|
|
|
90
|
|
|
91 \paragraph{Details}
|
|
|
92 The \emph{CallVM} is a state machine that manages all aspects of a function
|
|
|
93 call from configuration, argument passing up the actual function call on
|
|
|
94 the processor.
|
|
|
95
|
|
|
96 \subsection{Allocation}
|
|
|
97
|
|
|
98 \paragraph{Functions}
|
|
|
99
|
|
|
100 \begin{lstlisting}[language=c]
|
|
|
101 DCCallVM* dcNewCallVM (DCsize size);
|
|
|
102 void dcFree(DCCallVM* vm);
|
|
|
103 \end{lstlisting}
|
|
|
104
|
|
|
105 \lstinline{dcNewCallVM} creates a new \emph{CallVM} object, where
|
|
|
106 \lstinline{size} specifies the max size of the internal stack that will be
|
|
|
107 allocated and used to bind arguments to. Use \lstinline{dcFree} to
|
|
|
108 destroy the \emph{CallVM} object.\\
|
|
|
109 \\
|
|
|
110 This will allocate memory using the system allocators or custom ones provided
|
|
|
111 custom \capi{dcAllocMem} and \capi{dcFreeMem} macros are defined to override the
|
|
|
112 default behaviour. See \capi{dyncall\_alloc.h} for defails.
|
|
|
113
|
|
|
114
|
|
|
115 \subsection{Error Reporting}
|
|
|
116
|
|
|
117 \paragraph{Function}
|
|
|
118
|
|
|
119 \begin{lstlisting}[language=c]
|
|
|
120 DCint dcGetError(DCCallVM* vm);
|
|
|
121 \end{lstlisting}
|
|
|
122
|
|
|
123 Returns the most recent error state code out of the following:
|
|
|
124
|
|
|
125 \paragraph{Errors}
|
|
|
126
|
|
|
127 \begin{table}[h]
|
|
|
128 \begin{center}
|
|
|
129 \begin{tabular*}{0.75\textwidth}{ll}
|
|
|
130 \hline
|
|
|
131 Constant & Description\\
|
|
|
132 \hline
|
|
|
133 \lstinline@DC_ERROR_NONE@ & No error occured. \\
|
|
|
134 \lstinline@DC_ERROR_UNSUPPORTED_MODE@ & Unsupported mode, caused by \lstinline@dcMode()@ \\
|
|
|
135 \hline
|
|
|
136 \end{tabular*}
|
|
|
137 \caption{CallVM calling convention modes}
|
|
|
138 \label{errorcodes}
|
|
|
139 \end{center}
|
|
|
140 \end{table}
|
|
|
141
|
|
|
142 \pagebreak
|
|
|
143
|
|
|
144 \subsection{Configuration}
|
|
|
145
|
|
|
146 \paragraph{Function}
|
|
|
147
|
|
|
148 \begin{lstlisting}[language=c]
|
|
|
149 void dcMode (DCCallVM* vm, DCint mode);
|
|
|
150 \end{lstlisting}
|
|
|
151
|
|
|
152 Sets the calling convention to use. Note that some mode/platform combination
|
|
|
153 don't make any sense (e.g. using a PowerPC calling convention on a MIPS
|
|
|
154 platform) and are silently ignored.
|
|
|
155
|
|
|
156 \paragraph{Modes}
|
|
|
157
|
|
|
158 \begin{table}[h]
|
|
|
159 \begin{center}
|
|
|
160 \begin{tabular*}{0.75\textwidth}{ll}
|
|
|
161 \hline
|
|
|
162 Constant & Description\\
|
|
|
163 \hline
|
|
|
164 \lstinline@DC_CALL_C_DEFAULT@ & C default function call for current platform\\
|
|
|
165 \lstinline@DC_CALL_C_ELLIPSIS@ & C ellipsis function call (named arguments (before '...'))\\
|
|
|
166 \lstinline@DC_CALL_C_ELLIPSIS_VARARGS@ & C ellipsis function call (variable/unnamed arguments (after '...'))\\
|
|
|
167 \lstinline@DC_CALL_C_X86_CDECL@ & C x86 platforms standard call\\
|
|
|
168 \lstinline@DC_CALL_C_X86_WIN32_STD@ & C x86 Windows standard call\\
|
|
|
169 \lstinline@DC_CALL_C_X86_WIN32_FAST_MS@ & C x86 Windows Microsoft fast call\\
|
|
|
170 \lstinline@DC_CALL_C_X86_WIN32_FAST_GNU@ & C x86 Windows GCC fast call\\
|
|
|
171 \lstinline@DC_CALL_C_X86_WIN32_THIS_MS@ & C x86 Windows Microsoft this call\\
|
|
|
172 \lstinline@DC_CALL_C_X86_WIN32_THIS_GNU@ & C x86 Windows GCC this call\\
|
|
|
173 \lstinline@DC_CALL_C_X86_PLAN9@ & C x86 Plan9 call\\
|
|
|
174 \lstinline@DC_CALL_C_X64_WIN64@ & C x64 Windows standard call\\
|
|
|
175 \lstinline@DC_CALL_C_X64_SYSV@ & C x64 System V standard call\\
|
|
|
176 \lstinline@DC_CALL_C_PPC32_DARWIN@ & C ppc32 Mac OS X standard call\\
|
|
|
177 \lstinline@DC_CALL_C_PPC32_OSX@ & alias for DC\_CALL\_C\_PPC32\_DARWIN\\
|
|
|
178 \lstinline@DC_CALL_C_PPC32_SYSV@ & C ppc32 SystemV standard call\\
|
|
|
179 \lstinline@DC_CALL_C_PPC32_LINUX@ & alias for DC\_CALL\_C\_PPC32\_SYSV\\
|
|
|
180 \lstinline@DC_CALL_C_PPC64@ & C ppc64 SystemV standard call\\
|
|
|
181 \lstinline@DC_CALL_C_PPC64_LINUX@ & alias for DC\_CALL\_C\_PPC64\\
|
|
|
182 \lstinline@DC_CALL_C_ARM_ARM@ & C arm call (arm mode)\\
|
|
|
183 \lstinline@DC_CALL_C_ARM_THUMB@ & C arm call (thumb mode)\\
|
|
|
184 \lstinline@DC_CALL_C_ARM_ARM_EABI@ & C arm eabi call (arm mode)\\
|
|
|
185 \lstinline@DC_CALL_C_ARM_THUMB_EABI@ & C arm eabi call (thumb mode)\\
|
|
|
186 \lstinline@DC_CALL_C_ARM_ARMHF@ & C arm call (arm hardfloat - e.g. raspberry pi)\\
|
|
|
187 \lstinline@DC_CALL_C_ARM64@ & C arm64 call (AArch64)\\
|
|
|
188 \lstinline@DC_CALL_C_MIPS32_EABI@ & C mips32 eabi call\\
|
|
|
189 \lstinline@DC_CALL_C_MIPS32_PSPSDK@ & alias for DC\_CALL\_C\_MIPS32\_EABI (deprecated)\\
|
|
|
190 \lstinline@DC_CALL_C_MIPS32_O32@ & C mips32 o32 call\\
|
|
|
191 \lstinline@DC_CALL_C_MIPS64_N64@ & C mips64 n64 call\\
|
|
|
192 \lstinline@DC_CALL_C_MIPS64_N32@ & C mips64 n32 call\\
|
|
|
193 \lstinline@DC_CALL_C_SPARC32@ & C sparc32 call\\
|
|
|
194 \lstinline@DC_CALL_C_SPARC64@ & C sparc64 call\\
|
|
|
195 \lstinline@DC_CALL_SYS_DEFAULT@ & C default syscall for current platform\\
|
|
|
196 \lstinline@DC_CALL_SYS_X86_INT80H_BSD@ & C syscall for x86 BSD platforms\\
|
|
|
197 \lstinline@DC_CALL_SYS_X86_INT80H_LINUX@ & C syscall for x86 Linux\\
|
|
|
198 \lstinline@DC_CALL_SYS_PPC32@ & C syscall for ppc32 Linux\\
|
|
|
199 \hline
|
|
|
200 \end{tabular*}
|
|
|
201 \caption{CallVM calling convention modes}
|
|
|
202 \label{callingconventionmodes}
|
|
|
203 \end{center}
|
|
|
204 \end{table}
|
|
|
205
|
|
|
206 \paragraph{Details}
|
|
|
207
|
|
|
208 \lstinline@DC_CALL_C_DEFAULT@ is the default standard C call on the target
|
|
|
209 platform. It uses the standard C calling convention.
|
|
|
210 \lstinline@DC_CALL_C_ELLIPSIS@ is used for C ellipsis calls which allow
|
|
|
211 to build up a variable argument list.
|
|
|
212 On many platforms, there is only one C calling convention.
|
|
|
213 The X86 platform provides a rich family of different calling conventions.
|
|
|
214 \\
|
|
|
215
|
|
|
216
|
|
|
217 \subsection{Machine state reset}
|
|
|
218
|
|
|
219 \begin{lstlisting}[language=c]
|
|
|
220 void dcReset(DCCallVM* vm);
|
|
|
221 \end{lstlisting}
|
|
|
222
|
|
|
223 Resets the internal stack of arguments and prepares it for the selected mode.
|
|
|
224 This function should be called after setting the call mode (using dcMode), but
|
|
|
225 prior to binding arguments to the CallVM. Use it also when reusing a CallVM, as
|
|
|
226 arguments don't get flushed automatically after a function call invocation.\\
|
|
|
227
|
|
|
228 \subsection{Argument binding}
|
|
|
229
|
|
|
230 \paragraph{Functions}
|
|
|
231
|
|
|
232 \begin{lstlisting}[language=c]
|
|
|
233 void dcArgBool (DCCallVM* vm, DCbool arg);
|
|
|
234 void dcArgChar (DCCallVM* vm, DCchar arg);
|
|
|
235 void dcArgShort (DCCallVM* vm, DCshort arg);
|
|
|
236 void dcArgInt (DCCallVM* vm, DCint arg);
|
|
|
237 void dcArgLong (DCCallVM* vm, DClong arg);
|
|
|
238 void dcArgLongLong(DCCallVM* vm, DClonglong arg);
|
|
|
239 void dcArgFloat (DCCallVM* vm, DCfloat arg);
|
|
|
240 void dcArgDouble (DCCallVM* vm, DCdouble arg);
|
|
|
241 void dcArgPointer (DCCallVM* vm, DCpointer arg);
|
|
|
242 \end{lstlisting}
|
|
|
243
|
|
|
244 \paragraph{Details}
|
|
|
245
|
|
|
246 Used to bind arguments of the named types to the CallVM object.
|
|
|
247 Arguments should be bound in \emph{left-to-right} order regarding the C
|
|
|
248 function prototype.\\
|
|
|
249
|
|
|
250 \subsection{Call invocation}
|
|
|
251
|
|
|
252 \paragraph{Functions}
|
|
|
253
|
|
|
254 \begin{lstlisting}[language=c]
|
|
|
255 DCvoid dcCallVoid (DCCallVM* vm, DCpointer funcptr);
|
|
|
256 DCbool dcCallBool (DCCallVM* vm, DCpointer funcptr);
|
|
|
257 DCchar dcCallChar (DCCallVM* vm, DCpointer funcptr);
|
|
|
258 DCshort dcCallShort (DCCallVM* vm, DCpointer funcptr);
|
|
|
259 DCint dcCallInt (DCCallVM* vm, DCpointer funcptr);
|
|
|
260 DClong dcCallLong (DCCallVM* vm, DCpointer funcptr);
|
|
|
261 DClonglong dcCallLongLong(DCCallVM* vm, DCpointer funcptr);
|
|
|
262 DCfloat dcCallFloat (DCCallVM* vm, DCpointer funcptr);
|
|
|
263 DCdouble dcCallDouble (DCCallVM* vm, DCpointer funcptr);
|
|
|
264 DCpointer dcCallPointer (DCCallVM* vm, DCpointer funcptr);
|
|
|
265 \end{lstlisting}
|
|
|
266
|
|
|
267 \paragraph{Details}
|
|
|
268 Calls the function specified by \emph{funcptr} with the arguments bound to
|
|
|
269 the \emph{CallVM} and returns. Use the function that corresponds to the
|
|
|
270 dynamically called function's return value.\\
|
|
|
271 \\
|
|
|
272 After the invocation of the foreign function call, the argument values are
|
|
|
273 still bound and a second call using the same arguments can be issued. If you
|
|
|
274 need to clear the argument bindings, you have to reset the \emph{CallVM}.
|
|
|
275
|
|
|
276 \subsection{Formatted argument binding and calls (ANSI C ellipsis interface)}
|
|
|
277
|
|
|
278 \paragraph{Functions}
|
|
|
279
|
|
|
280 \begin{lstlisting}[language=c]
|
|
|
281 void dcArgF (DCCallVM* vm, const DCsigchar* signature, ...);
|
|
|
282 void dcVArgF(DCCallVM* vm, const DCsigchar* signature, va_list args);
|
|
|
283 void dcCallF (DCCallVM* vm, DCValue* result, DCpointer funcptr,
|
|
|
284 const DCsigchar* signature, ...);
|
|
|
285 void dcVCallF(DCCallVM* vm, DCValue* result, DCpointer funcptr,
|
|
|
286 const DCsigchar* signature, va_list args);
|
|
|
287 \end{lstlisting}
|
|
|
288
|
|
|
289 \paragraph{Details}
|
|
|
290
|
|
|
291 These functions can be used to operate \product{dyncall} via a printf-style
|
|
|
292 functional interface, using a signature string encoding the argument types and
|
|
|
293 return type.
|
|
|
294 \capi{dcArgF()} and \capi{dcVArgF()} just bind arguments to the \capi{DCCallVM}
|
|
|
295 object, so any return value specified in the signature is ignored. \capi{dcCallF()}
|
|
|
296 and \capi{dcVCallF()} also take a function pointer to call after binding the arguments.
|
|
|
297 The return value will be stored in what \lstinline{result} points to.
|
|
|
298 For more information about the signature format, refer to \ref{sigchar}.
|
|
|
299
|
