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
|
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 %
|