fc253d4e9efeb6229e52837bf5bd9e78daf7326a
[libffi.git] / libffi / README
1 Status
2 ======
3
4 libffi-2.99.6 was released on February 14, 2008. Check the libffi web
5 page for updates: <URL:http://sourceware.org/libffi/>.
6
7
8 What is libffi?
9 ===============
10
11 Compilers for high level languages generate code that follow certain
12 conventions.  These conventions are necessary, in part, for separate
13 compilation to work.  One such convention is the "calling convention".
14 The "calling convention" is a set of assumptions made by the compiler
15 about where function arguments will be found on entry to a function.
16 A "calling convention" also specifies where the return value for a
17 function is found.
18
19 Some programs may not know at the time of compilation what arguments
20 are to be passed to a function.  For instance, an interpreter may be
21 told at run-time about the number and types of arguments used to call
22 a given function.  Libffi can be used in such programs to provide a
23 bridge from the interpreter program to compiled code.
24
25 The libffi library provides a portable, high level programming
26 interface to various calling conventions.  This allows a programmer to
27 call any function specified by a call interface description at run
28 time.
29
30 FFI stands for Foreign Function Interface.  A foreign function
31 interface is the popular name for the interface that allows code
32 written in one language to call code written in another language.  The
33 libffi library really only provides the lowest, machine dependent
34 layer of a fully featured foreign function interface. A layer must
35 exist above libffi that handles type conversions for values passed
36 between the two languages.
37
38
39 Supported Platforms
40 ===================
41
42 Libffi has been ported to many different platforms, although this
43 release was only tested on:
44
45      arm oabi linux
46      arm eabi linux
47      hppa64 linux
48      powerpc darwin
49      powerpc64 linux
50      sparc solaris (SPARC V9 ABI)
51      x86 cygwin
52      x86 darwin
53      x86 linux
54      x86-64 linux
55      
56
57 Installing libffi
58 =================
59
60 [Note: before actually performing any of these installation steps,
61  you may wish to read the "Platform Specific Notes" below.]
62
63 First you must configure the distribution for your particular
64 system. Go to the directory you wish to build libffi in and run the
65 "configure" program found in the root directory of the libffi source
66 distribution.
67
68 You may want to tell configure where to install the libffi library and
69 header files. To do that, use the --prefix configure switch.  Libffi
70 will install under /usr/local by default. 
71
72 If you want to enable extra run-time debugging checks use the the
73 --enable-debug configure switch. This is useful when your program dies
74 mysteriously while using libffi. 
75
76 Another useful configure switch is --enable-purify-safety. Using this
77 will add some extra code which will suppress certain warnings when you
78 are using Purify with libffi. Only use this switch when using 
79 Purify, as it will slow down the library.
80
81 Configure has many other options. Use "configure --help" to see them all.
82
83 Once configure has finished, type "make". Note that you must be using
84 GNU make. SGI's make will not work.  Sun's probably won't either.
85 You can ftp GNU make from prep.ai.mit.edu:/pub/gnu.
86
87 To ensure that libffi is working as advertised, type "make test".
88
89 To install the library and header files, type "make install".
90
91
92 Platform Specific Notes
93 =======================
94
95         Intel x86
96         ---------
97
98 There are no known problems with the x86 port.
99
100         Sun SPARC - SunOS 4.1.3 & Solaris 2.x
101         -------------------------------------
102
103 You must use GNU Make to build libffi on Sun platforms.
104
105         MIPS - Irix 5.3 & 6.x
106         ---------------------
107
108 Irix 6.2 and better supports three different calling conventions: o32,
109 n32 and n64. Currently, libffi only supports both o32 and n32 under
110 Irix 6.x, but only o32 under Irix 5.3. Libffi will automatically be
111 configured for whichever calling convention it was built for.
112
113 By default, the configure script will try to build libffi with the GNU
114 development tools. To build libffi with the SGI development tools, set
115 the environment variable CC to either "cc -32" or "cc -n32" before
116 running configure under Irix 6.x (depending on whether you want an o32
117 or n32 library), or just "cc" for Irix 5.3.
118
119 With the n32 calling convention, when returning structures smaller
120 than 16 bytes, be sure to provide an RVALUE that is 8 byte aligned.
121 Here's one way of forcing this:
122
123         double struct_storage[2];
124         my_small_struct *s = (my_small_struct *) struct_storage;  
125         /* Use s for RVALUE */
126
127 If you don't do this you are liable to get spurious bus errors. 
128
129 "long long" values are not supported yet.
130
131 You must use GNU Make to build libffi on SGI platforms.
132
133         ARM - System V ABI
134         ------------------
135
136 The ARM port was performed on a NetWinder running ARM Linux ELF
137 (2.0.31) and gcc 2.8.1.
138
139         PowerPC System V ABI
140         --------------------
141
142 There are two `System V ABI's which libffi implements for PowerPC.
143 They differ only in how small structures are returned from functions.
144
145 In the FFI_SYSV version, structures that are 8 bytes or smaller are
146 returned in registers.  This is what GCC does when it is configured
147 for solaris, and is what the System V ABI I have (dated September
148 1995) says.
149
150 In the FFI_GCC_SYSV version, all structures are returned the same way:
151 by passing a pointer as the first argument to the function.  This is
152 what GCC does when it is configured for linux or a generic sysv
153 target.
154
155 EGCS 1.0.1 (and probably other versions of EGCS/GCC) also has a
156 inconsistency with the SysV ABI: When a procedure is called with many
157 floating-point arguments, some of them get put on the stack.  They are
158 all supposed to be stored in double-precision format, even if they are
159 only single-precision, but EGCS stores single-precision arguments as
160 single-precision anyway.  This causes one test to fail (the `many
161 arguments' test).
162
163
164 History
165 =======
166
167 3.00 Feb-XX-08
168         Many changes, mostly thanks to the GCC project.
169         Cygnus Solutions is now Red Hat.
170
171   [10 years go by...]
172
173 1.20 Oct-5-98
174         Raffaele Sena produces ARM port.
175
176 1.19 Oct-5-98
177         Fixed x86 long double and long long return support.
178         m68k bug fixes from Andreas Schwab.
179         Patch for DU assembler compatibility for the Alpha from Richard
180         Henderson.
181
182 1.18 Apr-17-98
183         Bug fixes and MIPS configuration changes.
184
185 1.17 Feb-24-98
186         Bug fixes and m68k port from Andreas Schwab. PowerPC port from
187         Geoffrey Keating. Various bug x86, Sparc and MIPS bug fixes.
188
189 1.16 Feb-11-98
190         Richard Henderson produces Alpha port.
191
192 1.15 Dec-4-97
193         Fixed an n32 ABI bug. New libtool, auto* support.
194
195 1.14 May-13-97
196         libtool is now used to generate shared and static libraries.
197         Fixed a minor portability problem reported by Russ McManus
198         <mcmanr@eq.gs.com>.
199
200 1.13 Dec-2-96
201         Added --enable-purify-safety to keep Purify from complaining
202         about certain low level code.
203         Sparc fix for calling functions with < 6 args.
204         Linux x86 a.out fix.
205
206 1.12 Nov-22-96
207         Added missing ffi_type_void, needed for supporting void return 
208         types. Fixed test case for non MIPS machines. Cygnus Support 
209         is now Cygnus Solutions. 
210
211 1.11 Oct-30-96
212         Added notes about GNU make.
213
214 1.10 Oct-29-96
215         Added configuration fix for non GNU compilers.
216
217 1.09 Oct-29-96
218         Added --enable-debug configure switch. Clean-ups based on LCLint 
219         feedback. ffi_mips.h is always installed. Many configuration 
220         fixes. Fixed ffitest.c for sparc builds.
221
222 1.08 Oct-15-96
223         Fixed n32 problem. Many clean-ups.
224
225 1.07 Oct-14-96
226         Gordon Irlam rewrites v8.S again. Bug fixes.
227
228 1.06 Oct-14-96
229         Gordon Irlam improved the sparc port. 
230
231 1.05 Oct-14-96
232         Interface changes based on feedback.
233
234 1.04 Oct-11-96
235         Sparc port complete (modulo struct passing bug).
236
237 1.03 Oct-10-96
238         Passing struct args, and returning struct values works for
239         all architectures/calling conventions. Expanded tests.
240
241 1.02 Oct-9-96
242         Added SGI n32 support. Fixed bugs in both o32 and Linux support.
243         Added "make test".
244
245 1.01 Oct-8-96
246         Fixed float passing bug in mips version. Restructured some
247         of the code. Builds cleanly with SGI tools.
248
249 1.00 Oct-7-96
250         First release. No public announcement.
251
252
253 Authors & Credits
254 =================
255
256 libffi was originally written by Anthony Green <green@redhat.com>.
257
258 The developers of the GNU Compiler Collection project have made
259 innumerable valuable contributions.  See the ChangeLog file for
260 details.
261
262 Some of the ideas behind libffi were inspired by Gianni Mariani's free
263 gencall library for Silicon Graphics machines.
264
265 The closure mechanism was designed and implemented by Kresten Krab
266 Thorup.
267
268 Major processor architecture ports were contributed by the following
269 developers:
270
271 alpha           Richard Henderson
272 arm             Raffaele Sena
273 cris            Simon Posnjak, Hans-Peter Nilsson
274 frv             Anthony Green
275 ia64            Hans Boehm
276 m32r            Kazuhiro Inaoka
277 m68k            Andreas Schwab
278 mips            Anthony Green
279 mips64          David Daney
280 pa              Randolph Chung
281 powerpc         Geoffrey Keating
282 powerpc64       Jakub Jelinek
283 s390            Gerhard Tonn, Ulrich Weigand
284 sh              Kaz Kojima
285 sh64            Kaz Kojima
286 sparc           Anthony Green, Gordon Irlam
287 x86             Anthony Green
288 x86-64          Bo Thorsen
289
290 Jesper Skov and Andrew Haley both did more than their fair share of
291 stepping through the code and tracking down bugs.
292
293 Thanks also to Tom Tromey for bug fixes, documentation and
294 configuration help.
295
296 Thanks to Jim Blandy, who provided some useful feedback on the libffi
297 interface.
298
299 Andreas Tobler has done a tremendous amount of work on the testsuite.
300
301 The list above is almost certainly incomplete and inaccurate.  I'm
302 happy to make corrections or additions upon request.
303
304 If you have a problem, or have found a bug, please send a note to
305 green@redhat.com.