Mercurial > pub > dyncall > dyncall

comparison doc/manual/manual_overview.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 a996f29affdf
comparison
equal deleted inserted replaced
-1:000000000000 0:3e629dc19168
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