1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
%//////////////////////////////////////////////////////////////////////////////
%
% Copyright (c) 2007,2009 Daniel Adler <dadler@uni-goettingen.de>,
% Tassilo Philipp <tphilipp@potion-studios.com>
%
% Permission to use, copy, modify, and distribute this software for any
% purpose with or without fee is hereby granted, provided that the above
% copyright notice and this permission notice appear in all copies.
%
% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
%
%//////////////////////////////////////////////////////////////////////////////
\newpage
\section{Overview}
The \product{dyncall} library encapsulates architecture-, OS- and compiler-specific
function call semantics in a virtual
\begin{center}
\emph{bind argument parameters from left to right and then call}
\end{center}
interface allowing programmers to call C functions
in a completely dynamic manner. In other words, instead of calling a function
directly, the \product{dyncall} library provides a mechanism to push the function parameters
manually and to issue the call afterwards.\\
Since the idea behind this concept is similar to call dispatching mechanisms
of virtual machines, the object that can be dynamically loaded with arguments,
and then used to actually invoke the call, is called CallVM. It is possible to
change the calling convention used by the CallVM at run-time.
Due to the fact that nearly every platform comes with one or more distinct calling
conventions, the \product{dyncall} library project intends to be a portable and open-source
approach to the variety of compiler-specific binary interfaces, platform specific
subtleties, and so on\ldots\\
\\
The core of the library consists of dynamic implementations of different
calling conventions written in assembler.
Although the library aims to be highly portable, some assembler code needs to
be written for nearly every platform/compiler/OS combination.
Unfortunately, there are architectures we just don't have at home or work. If
you want to see \product{dyncall} running on such a platform, feel free to send
in code and patches, or even to donate hardware you don't need anymore.
Check the {\bf supported platforms} section for an overview of the supported
platforms and the different calling convention sections for details about the
support.
\\
\begin{comment}
@@@
A typical binary library consists of symbolic names that map to variables and
functions, the latter being pre-compiled for a
specific calling convention and architecture. Given \product{dyncall} has been ported to
that binary platform, it is possible to call such a function dynamically
without writing glue code or prototypes or even knowing its C declaration -
all that is needed is a pointer to it.\\
To avoid confusion, note that from the point of view of the library all
parameters are handled the same way, even though the implementation might use
other ways to pass parameters in order to suit specific calling conventions.\\
\end{comment}
\subsection{Features}
\begin{itemize}
\item A portable and extendable function call interface for the C programming
language.
\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..
\item Add-on language bindings to Python, R, Ruby, Java, Lua, sh, ...
\item High-level state machine design using C to model calling convention
parameter transfer.
\item One assembly \emph{hybrid} call routine per calling convention.
\item Formatted call, vararg function API.
\item Comprehensive test suite.
\end{itemize}
\pagebreak
\subsection{Showcase}
\paragraph{Foreign function call in C}
This section demonstrates how the foreign function call is issued without, and then
with, the help of the \product{dyncall} library and scripting language
bindings.
\begin{lstlisting}[language=c,caption=Foreign function call in C]
double call_as_sqrt(void* funptr, double x)
{
return ( ( double (*)(double) )funptr)(x);
}
\end{lstlisting}
\paragraph{\product{Dyncall} C library example}
The same operation can be broken down into atomic pieces
(specify calling convention, binding arguments, invoking the call)
using the \dc\ library.
\begin{lstlisting}[language=c,caption=Dyncall C library example]
#include <dyncall.h>
double call_as_sqrt(void* funptr, double x)
{
double r;
DCCallVM* vm = dcNewCallVM(4096);
dcMode(vm, DC_CALL_C_DEFAULT);
dcReset(vm);
dcArgDouble(vm, x);
r = dcCallDouble(vm, funptr);
dcFree(vm);
return r;
}
\end{lstlisting}
As you can see, this is more code after all, but completely dynamic.
And definitely less than generated glue-code for each function call, if
used correctly.
The following are examples from script bindings:
\paragraph{Python example}
\begin{lstlisting}[language=python,caption=Dyncall Python bindings example]
import pydc
def call_as_sqrt(funptr,x):
return pydc.call(funptr,"d)d", x)
\end{lstlisting}
\paragraph{R example}
\begin{lstlisting}[language=R,caption=Dyncall R bindings example]
library(rdyncall)
call.as.sqrt <- function(funptr,x)
.dyncall(funptr,"d)d", x)
\end{lstlisting}
\pagebreak
\subsection{Supported platforms/architectures}
The feature matrix below gives a brief overview of the currently supported
platforms. Different colors are used, where a green cell indicates a supported
platform, yellow a platform that might work (but is untested) and red a platform
that is currently unsupported. Gray cells are combinations that don't exist
at the time of writing, or that are not taken into account.\\
Please note that a green cell doesn't imply that all existing calling
conventions/features/build tools are supported for that platform (but the most important).
For details about the support consult the appendix.
\begin{table}[h]
\begin{tabular}{r|*{14}{c}}
\marknull & & & & & & & & & & & & & & \\
& \ninetyb {\bf Alpha}\ninetye & \ninetyb {\bf ARM}\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 \\
\hline
{\bf Windows family} & \marknotx & \markunkn & \markunkn & \marknotx & \marknimp & \marknotx & \marknotx & \marknotx & \marknotx & \markimpl & \markimpl & \marknimp & \marknotx & \marknotx \\
{\bf Minix} & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \markimpl & \marknotx & \marknotx & \marknotx & \marknotx \\
{\bf Linux} & \marknimp & \markimpl & \marknotx & \marknotx & \marknotx & \markimpl & \marknimp & \marknotx & \marknotx & \markimpl & \markimpl & \marknotx & \markimpl & \markimpl \\
{\bf Mac OS X/iOS/Darwin} & \marknotx & \markimpl & \marknotx & \marknotx & \marknotx & \markimpl & \marknimp & \marknotx & \marknotx & \markimpl & \markimpl & \marknotx & \marknotx & \marknotx \\
{\bf FreeBSD} & \marknimp & \markimpl & \markunkn & \markunkn & \marknimp & \markimpl & \marknimp & \marknotx & \marknotx & \markimpl & \markimpl & \marknimp & \markunkn & \markunkn \\
{\bf NetBSD} & \marknimp & \markimpl & \markimpl & \markunkn & \marknimp & \markimpl & \marknimp & \marknimp & \marknimp & \markimpl & \markimpl & \marknimp & \markimpl & \markunkn \\
{\bf OpenBSD} & \marknimp & \markunkn & \markunkn & \markimpl & \marknimp & \markunkn & \marknimp & \marknimp & \marknimp & \markimpl & \markimpl & \marknimp & \markimpl & \markimpl \\
{\bf DragonFlyBSD} & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \markimpl & \markimpl & \marknotx & \marknotx & \marknotx \\
{\bf Solaris} & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \markimpl & \markimpl & \marknotx & \markimpl & \markimpl \\
{\bf Plan 9} & \marknimp & \marknimp & \marknimp & \marknotx & \marknotx & \marknimp & \marknotx & \marknotx & \marknotx & \markimpl & \marknimp & \marknotx & \marknimp & \marknotx \\
{\bf Haiku/BeOS} & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \markimpl & \marknotx & \marknotx & \marknotx & \marknotx \\
{\bf Playstation Portable} & \marknotx & \marknotx & \markimpl & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx \\
{\bf Nintendo DS} & \marknotx & \markimpl & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx & \marknotx \\
\end{tabular}
\caption{Supported platforms}
\end{table}
|
