Mercurial > pub > dyncall > dyncall

comparison doc/manual/manual_dyncall_api.tex @ 0:3e629dc19168

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial from svn dyncall-1745
author Daniel Adler
date Thu, 19 Mar 2015 22:24:28 +0100
parents
children 9bd3c5219505
comparison
equal deleted inserted replaced
-1:000000000000 0:3e629dc19168
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