0
|
1 %//////////////////////////////////////////////////////////////////////////////
|
|
2 %
|
|
3 % Copyright (c) 2007,2009 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
|
|
22 \section{Overview}
|
|
23
|
|
24 The \product{dyncall} library encapsulates architecture-, OS- and compiler-specific
|
|
25 function call semantics in a virtual
|
|
26
|
|
27 \begin{center}
|
|
28 \emph{bind argument parameters from left to right and then call}
|
|
29 \end{center}
|
|
30
|
|
31 interface allowing programmers to call C functions
|
|
32 in a completely dynamic manner. In other words, instead of calling a function
|
|
33 directly, the \product{dyncall} library provides a mechanism to push the function parameters
|
|
34 manually and to issue the call afterwards.\\
|
|
35 Since the idea behind this concept is similar to call dispatching mechanisms
|
|
36 of virtual machines, the object that can be dynamically loaded with arguments,
|
|
37 and then used to actually invoke the call, is called CallVM. It is possible to
|
|
38 change the calling convention used by the CallVM at run-time.
|
|
39 Due to the fact that nearly every platform comes with one or more distinct calling
|
|
40 conventions, the \product{dyncall} library project intends to be a portable and open-source
|
|
41 approach to the variety of compiler-specific binary interfaces, platform specific
|
|
42 subtleties, and so on\ldots\\
|
|
43 \\
|
|
44 The core of the library consists of dynamic implementations of different
|
|
45 calling conventions written in assembler.
|
|
46 Although the library aims to be highly portable, some assembler code needs to
|
|
47 be written for nearly every platform/compiler/OS combination.
|
|
48 Unfortunately, there are architectures we just don't have at home or work. If
|
|
49 you want to see \product{dyncall} running on such a platform, feel free to send
|
|
50 in code and patches, or even to donate hardware you don't need anymore.
|
|
51 Check the {\bf supported platforms} section for an overview of the supported
|
|
52 platforms and the different calling convention sections for details about the
|
|
53 support.
|
|
54 \\
|
|
55 \begin{comment}
|
|
56 @@@
|
|
57 A typical binary library consists of symbolic names that map to variables and
|
|
58 functions, the latter being pre-compiled for a
|
|
59 specific calling convention and architecture. Given \product{dyncall} has been ported to
|
|
60 that binary platform, it is possible to call such a function dynamically
|
|
61 without writing glue code or prototypes or even knowing its C declaration -
|
|
62 all that is needed is a pointer to it.\\
|
|
63 To avoid confusion, note that from the point of view of the library all
|
|
64 parameters are handled the same way, even though the implementation might use
|
|
65 other ways to pass parameters in order to suit specific calling conventions.\\
|
|
66 \end{comment}
|
|
67
|
|
68
|
|
69 \subsection{Features}
|
|
70
|
|
71 \begin{itemize}
|
|
72 \item A portable and extendable function call interface for the C programming
|
|
73 language.
|
|
74 \item Ports to major platforms including Windows, Mac OS X, Linux, BSD derivates, iPhone and embedded devices and more, including lesser known and/or older platforms like Plan 9, Playstation Portable, Nintendo DS, etc..
|
|
75 \item Add-on language bindings to Python, R, Ruby, Go, Erlang, Java, Lua, sh, ...
|
|
76 \item High-level state machine design using C to model calling convention
|
|
77 parameter transfer.
|
|
78 \item One assembly \emph{hybrid} call routine per calling convention.
|
|
79 \item Formatted call, vararg function API.
|
|
80 \item Comprehensive test suite.
|
|
81 \end{itemize}
|
|
82
|
|
83 \pagebreak
|
|
84
|
|
85 \subsection{Showcase}
|
|
86
|
|
87 \paragraph{Foreign function call in C}
|
|
88 This section demonstrates how the foreign function call is issued without, and then
|
|
89 with, the help of the \product{dyncall} library and scripting language
|
|
90 bindings.
|
|
91
|
|
92 \begin{lstlisting}[language=c,caption=Foreign function call in C]
|
|
93 double call_as_sqrt(void* funptr, double x)
|
|
94 {
|
|
95 return ( ( double (*)(double) )funptr)(x);
|
|
96 }
|
|
97 \end{lstlisting}
|
|
98
|
|
99 \paragraph{\product{Dyncall} C library example}
|
|
100
|
|
101 The same operation can be broken down into atomic pieces
|
|
102 (specify calling convention, binding arguments, invoking the call)
|
|
103 using the \dc\ library.
|
|
104
|
|
105 \begin{lstlisting}[language=c,caption=Dyncall C library example]
|
|
106 #include <dyncall.h>
|
|
107 double call_as_sqrt(void* funptr, double x)
|
|
108 {
|
|
109 double r;
|
|
110 DCCallVM* vm = dcNewCallVM(4096);
|
|
111 dcMode(vm, DC_CALL_C_DEFAULT);
|
|
112 dcReset(vm);
|
|
113 dcArgDouble(vm, x);
|
|
114 r = dcCallDouble(vm, funptr);
|
|
115 dcFree(vm);
|
|
116 return r;
|
|
117 }
|
|
118 \end{lstlisting}
|
|
119
|
|
120 As you can see, this is more code after all, but completely dynamic.
|
|
121 And definitely less than generated glue-code for each function call, if
|
|
122 used correctly.
|
|
123
|
|
124 The following are examples from script bindings:
|
|
125
|
|
126 \paragraph{Python example}
|
|
127
|
|
128 \begin{lstlisting}[language=python,caption=Dyncall Python bindings example]
|
|
129 import pydc
|
|
130 def call_as_sqrt(funptr,x):
|
|
131 return pydc.call(funptr,"d)d", x)
|
|
132 \end{lstlisting}
|
|
133
|
|
134
|
|
135 \paragraph{R example}
|
|
136
|
|
137 \begin{lstlisting}[language=R,caption=Dyncall R bindings example,escapeinside={TEX}{XET}] % escapeinside is a workaround for issues with '<' in lstlisting+tex4ht
|
|
138 library(rdyncall)
|
|
139 call.as.sqrt TEX\textlessXET- function(funptr,x)
|
|
140 .dyncall(funptr,"d)d", x)
|
|
141 \end{lstlisting}
|
|
142
|
|
143
|
|
144 \pagebreak
|
|
145
|
|
146 \subsection{Supported platforms/architectures}
|
|
147
|
|
148 The feature matrix below gives a brief overview of the currently supported
|
|
149 platforms. Different colors are used, where a green cell indicates a supported
|
|
150 platform, yellow a platform that might work (but is untested) and red a platform
|
|
151 that is currently unsupported. Gray cells are combinations that don't exist
|
|
152 at the time of writing, or that are not taken into account.\\
|
|
153 Light green cells mark complete feature support, as in dyncall and dyncallback. Dark green means basic support but lacking features (e.g. dyncall support, but not dyncallback).
|
|
154 Please note that a green cell (even a light-green one) doesn't imply that all existing calling conventions/features/build tools are supported for that platform (but the most
|
|
155 important).
|
|
156 For detailed info about a platform's support consult the calling convention appendix.
|
|
157
|
|
158 \begin{table}[h]
|
|
159 \begin{tabular}{r|*{15}{c}}
|
|
160
|
|
161 & & & & & & & & & & & & & & & \\
|
|
162 & \ninetyb {\bf Alpha}\ninetye & \ninetyb {\bf ARM}\ninetye & \ninetyb {\bf ARM64}\ninetye & \ninetyb {\bf MIPS (32)}\ninetye & \ninetyb {\bf MIPS (64)}\ninetye & \ninetyb {\bf SuperH}\ninetye & \ninetyb {\bf PowerPC (32)}\ninetye & \ninetyb {\bf PowerPC (64)}\ninetye & \ninetyb {\bf m68k}\ninetye & \ninetyb {\bf m88k}\ninetye & \ninetyb {\bf x86}\ninetye & \ninetyb {\bf x64}\ninetye & \ninetyb {\bf Itanium}\ninetye & \ninetyb {\bf SPARC}\ninetye & \ninetyb {\bf SPARC64}\ninetye \\
|
|
163 \hline
|
|
164 {\bf Windows family} & \marknotx & \markunkn & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \markcmpl & \markcmpl & \marknimp & \marknotx & \marknotx \\
|
|
165 {\bf Linux} & \marknimp & \markcmpl & \markcmpl & \markunkn & \markunkn & \marknotx & \markcmpl & \markcmpl & \marknotx & \marknotx & \markcmpl & \markcmpl & \marknotx & \markimpl & \markimpl \\
|
|
166 {\bf Mac OS X/iOS/Darwin} & \marknotx & \markcmpl & \markcmpl & \marknotx & \marknotx & \marknotx & \markcmpl & \markunkn & \marknotx & \marknotx & \markcmpl & \markcmpl & \marknotx & \marknotx & \marknotx \\
|
|
167 {\bf FreeBSD} & \marknimp & \markcmpl & \marknotx & \markunkn & \markunkn & \marknimp & \markimpl & \markunkn & \marknotx & \marknotx & \markcmpl & \markcmpl & \marknimp & \markunkn & \markunkn \\
|
|
168 {\bf NetBSD} & \marknimp & \markcmpl & \marknotx & \markimpl & \markunkn & \marknimp & \markimpl & \markunkn & \marknimp & \marknimp & \markcmpl & \markcmpl & \marknimp & \markimpl & \markunkn \\
|
|
169 {\bf OpenBSD} & \marknimp & \markunkn & \marknotx & \markunkn & \markimpl & \marknimp & \markunkn & \markunkn & \marknimp & \marknimp & \markcmpl & \markcmpl & \marknimp & \markimpl & \markimpl \\
|
|
170 {\bf DragonFlyBSD} & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \markcmpl & \markcmpl & \marknotx & \marknotx & \marknotx \\
|
|
171 {\bf Solaris} & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \markcmpl & \markcmpl & \marknotx & \markimpl & \markimpl \\
|
|
172 {\bf Plan 9} & \marknimp & \marknimp & \marknotx & \marknimp & \marknotx & \marknotx & \marknimp & \marknotx & \marknotx & \marknotx & \markcmpl & \marknimp & \marknotx & \marknimp & \marknotx \\
|
|
173 {\bf Haiku/BeOS} & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \markcmpl & \marknotx & \marknotx & \marknotx & \marknotx \\
|
|
174 {\bf Minix} & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \markcmpl & \marknotx & \marknotx & \marknotx & \marknotx \\
|
|
175 {\bf Playstation Portable} & \marknotx & \marknotx & \marknotx & \markimpl & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx \\
|
|
176 {\bf Nintendo DS} & \marknotx & \markcmpl & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx \\
|
|
177 \end{tabular}
|
|
178 \caption{Supported platforms}
|
|
179 \end{table}
|
|
180
|