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