Mercurial > pub > dyncall > dyncall
annotate doc/manual/manual_dyncall_api.tex @ 360:32736025371f
- doc updates with more info about signature string usage
author | Tassilo Philipp |
---|---|
date | Mon, 13 Apr 2020 21:35:43 +0200 |
parents | 6e33db95e724 |
children | 78dfa2f9783a |
rev | line source |
---|---|
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 | |
360
32736025371f
- doc updates with more info about signature string usage
Tassilo Philipp
parents:
340
diff
changeset
|
290 return type (and optionally also the calling convention used). |
0 | 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 |