3.0.9rc6
[libffi.git] / README
1 Status
2 ======
3
4 libffi-3.0.9 was released on December XX, 2009. 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
14 convention". The "calling convention" is essentially a set of
15 assumptions made by the compiler about where function arguments will
16 be found on entry to a function. A "calling convention" also specifies
17 where the return value for a 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      hppa linux
48      mips o32 linux (little endian)
49      powerpc darwin
50      powerpc freebsd
51      powerpc64 linux
52      sparc solaris
53      sparc64 freebsd
54      sparc64 solaris
55      x86 cygwin
56      x86 darwin
57      x86 freebsd
58      x86 linux
59      x86 openbsd
60      x86 solaris
61      x86-64 mingw
62      x86-64 darwin
63      x86-64 linux
64      x86-64 OS X
65      x86-64 freebsd
66      x86-64 solaris
67      
68 Please send additional platform test results to
69 libffi-discuss@sourceware.org.
70
71 Installing libffi
72 =================
73
74 [Note: before actually performing any of these installation steps,
75  you may wish to read the "Platform Specific Notes" below.]
76
77 First you must configure the distribution for your particular
78 system. Go to the directory you wish to build libffi in and run the
79 "configure" program found in the root directory of the libffi source
80 distribution.
81
82 You may want to tell configure where to install the libffi library and
83 header files. To do that, use the --prefix configure switch.  Libffi
84 will install under /usr/local by default. 
85
86 If you want to enable extra run-time debugging checks use the the
87 --enable-debug configure switch. This is useful when your program dies
88 mysteriously while using libffi. 
89
90 Another useful configure switch is --enable-purify-safety. Using this
91 will add some extra code which will suppress certain warnings when you
92 are using Purify with libffi. Only use this switch when using 
93 Purify, as it will slow down the library.
94
95 Configure has many other options. Use "configure --help" to see them all.
96
97 Once configure has finished, type "make". Note that you must be using
98 GNU make.  You can ftp GNU make from prep.ai.mit.edu:/pub/gnu.
99
100 To ensure that libffi is working as advertised, type "make check".
101 This will require that you have DejaGNU installed.
102
103 To install the library and header files, type "make install".
104
105
106 Platform Specific Notes
107 =======================
108
109         MIPS - Irix 5.3 & 6.x
110         ---------------------
111
112 Irix 6.2 and better supports three different calling conventions: o32,
113 n32 and n64. Currently, libffi only supports both o32 and n32 under
114 Irix 6.x, but only o32 under Irix 5.3. Libffi will automatically be
115 configured for whichever calling convention it was built for.
116
117 By default, the configure script will try to build libffi with the GNU
118 development tools. To build libffi with the SGI development tools, set
119 the environment variable CC to either "cc -32" or "cc -n32" before
120 running configure under Irix 6.x (depending on whether you want an o32
121 or n32 library), or just "cc" for Irix 5.3.
122
123 With the n32 calling convention, when returning structures smaller
124 than 16 bytes, be sure to provide an RVALUE that is 8 byte aligned.
125 Here's one way of forcing this:
126
127         double struct_storage[2];
128         my_small_struct *s = (my_small_struct *) struct_storage;  
129         /* Use s for RVALUE */
130
131 If you don't do this you are liable to get spurious bus errors. 
132
133 "long long" values are not supported yet.
134
135 You must use GNU Make to build libffi on SGI platforms.
136
137
138         PowerPC System V ABI
139         --------------------
140
141 There are two `System V ABI's which libffi implements for PowerPC.
142 They differ only in how small structures are returned from functions.
143
144 In the FFI_SYSV version, structures that are 8 bytes or smaller are
145 returned in registers.  This is what GCC does when it is configured
146 for solaris, and is what the System V ABI I have (dated September
147 1995) says.
148
149 In the FFI_GCC_SYSV version, all structures are returned the same way:
150 by passing a pointer as the first argument to the function.  This is
151 what GCC does when it is configured for linux or a generic sysv
152 target.
153
154 EGCS 1.0.1 (and probably other versions of EGCS/GCC) also has a
155 inconsistency with the SysV ABI: When a procedure is called with many
156 floating-point arguments, some of them get put on the stack.  They are
157 all supposed to be stored in double-precision format, even if they are
158 only single-precision, but EGCS stores single-precision arguments as
159 single-precision anyway.  This causes one test to fail (the `many
160 arguments' test).
161
162
163 History
164 =======
165
166 See the ChangeLog files for details.
167
168 3.0.9 Dec-xx-09
169         Add AVR32 and win64 ports.  Add ARM softfp support.
170         Many fixes for AIX, Solaris, HP-UX, *BSD.
171         Fix x86-64 closure bug.
172
173 3.0.8 Dec-19-08
174         Add *BSD, BeOS, and PA-Linux support.
175
176 3.0.7 Nov-11-08
177         Fix for ppc FreeBSD.
178         (thanks to Andreas Tobler)
179
180 3.0.6 Jul-17-08
181         Fix for closures on sh.
182         Mark the sh/sh64 stack as non-executable.
183         (both thanks to Kaz Kojima)
184
185 3.0.5 Apr-3-08
186         Fix libffi.pc file.
187         Fix #define ARM for IcedTea users.
188         Fix x86 closure bug.
189
190 3.0.4 Feb-24-08
191         Fix x86 OpenBSD configury.
192
193 3.0.3 Feb-22-08
194         Enable x86 OpenBSD thanks to Thomas Heller, and
195         x86-64 FreeBSD thanks to Björn König and Andreas Tobler.
196         Clean up test instruction in README.
197
198 3.0.2 Feb-21-08
199         Improved x86 FreeBSD support.
200         Thanks to Björn König.
201
202 3.0.1 Feb-15-08
203         Fix instruction cache flushing bug on MIPS.
204         Thanks to David Daney.
205
206 3.0.0 Feb-15-08
207         Many changes, mostly thanks to the GCC project.
208         Cygnus Solutions is now Red Hat.
209
210   [10 years go by...]
211
212 1.20 Oct-5-98
213         Raffaele Sena produces ARM port.
214
215 1.19 Oct-5-98
216         Fixed x86 long double and long long return support.
217         m68k bug fixes from Andreas Schwab.
218         Patch for DU assembler compatibility for the Alpha from Richard
219         Henderson.
220
221 1.18 Apr-17-98
222         Bug fixes and MIPS configuration changes.
223
224 1.17 Feb-24-98
225         Bug fixes and m68k port from Andreas Schwab. PowerPC port from
226         Geoffrey Keating. Various bug x86, Sparc and MIPS bug fixes.
227
228 1.16 Feb-11-98
229         Richard Henderson produces Alpha port.
230
231 1.15 Dec-4-97
232         Fixed an n32 ABI bug. New libtool, auto* support.
233
234 1.14 May-13-97
235         libtool is now used to generate shared and static libraries.
236         Fixed a minor portability problem reported by Russ McManus
237         <mcmanr@eq.gs.com>.
238
239 1.13 Dec-2-96
240         Added --enable-purify-safety to keep Purify from complaining
241         about certain low level code.
242         Sparc fix for calling functions with < 6 args.
243         Linux x86 a.out fix.
244
245 1.12 Nov-22-96
246         Added missing ffi_type_void, needed for supporting void return 
247         types. Fixed test case for non MIPS machines. Cygnus Support 
248         is now Cygnus Solutions. 
249
250 1.11 Oct-30-96
251         Added notes about GNU make.
252
253 1.10 Oct-29-96
254         Added configuration fix for non GNU compilers.
255
256 1.09 Oct-29-96
257         Added --enable-debug configure switch. Clean-ups based on LCLint 
258         feedback. ffi_mips.h is always installed. Many configuration 
259         fixes. Fixed ffitest.c for sparc builds.
260
261 1.08 Oct-15-96
262         Fixed n32 problem. Many clean-ups.
263
264 1.07 Oct-14-96
265         Gordon Irlam rewrites v8.S again. Bug fixes.
266
267 1.06 Oct-14-96
268         Gordon Irlam improved the sparc port. 
269
270 1.05 Oct-14-96
271         Interface changes based on feedback.
272
273 1.04 Oct-11-96
274         Sparc port complete (modulo struct passing bug).
275
276 1.03 Oct-10-96
277         Passing struct args, and returning struct values works for
278         all architectures/calling conventions. Expanded tests.
279
280 1.02 Oct-9-96
281         Added SGI n32 support. Fixed bugs in both o32 and Linux support.
282         Added "make test".
283
284 1.01 Oct-8-96
285         Fixed float passing bug in mips version. Restructured some
286         of the code. Builds cleanly with SGI tools.
287
288 1.00 Oct-7-96
289         First release. No public announcement.
290
291
292 Authors & Credits
293 =================
294
295 libffi was originally written by Anthony Green <green@redhat.com>.
296
297 The developers of the GNU Compiler Collection project have made
298 innumerable valuable contributions.  See the ChangeLog file for
299 details.
300
301 Some of the ideas behind libffi were inspired by Gianni Mariani's free
302 gencall library for Silicon Graphics machines.
303
304 The closure mechanism was designed and implemented by Kresten Krab
305 Thorup.
306
307 Major processor architecture ports were contributed by the following
308 developers:
309
310 alpha           Richard Henderson
311 arm             Raffaele Sena
312 cris            Simon Posnjak, Hans-Peter Nilsson
313 frv             Anthony Green
314 ia64            Hans Boehm
315 m32r            Kazuhiro Inaoka
316 m68k            Andreas Schwab
317 mips            Anthony Green, Casey Marshall
318 mips64          David Daney
319 pa              Randolph Chung, Dave Anglin, Andreas Tobler
320 powerpc         Geoffrey Keating, Andreas Tobler, 
321                          David Edelsohn, John Hornkvist
322 powerpc64       Jakub Jelinek
323 s390            Gerhard Tonn, Ulrich Weigand
324 sh              Kaz Kojima
325 sh64            Kaz Kojima
326 sparc           Anthony Green, Gordon Irlam
327 x86             Anthony Green, Jon Beniston
328 x86-64          Bo Thorsen
329
330 Jesper Skov and Andrew Haley both did more than their fair share of
331 stepping through the code and tracking down bugs.
332
333 Thanks also to Tom Tromey for bug fixes, documentation and
334 configuration help.
335
336 Thanks to Jim Blandy, who provided some useful feedback on the libffi
337 interface.
338
339 Andreas Tobler has done a tremendous amount of work on the testsuite.
340
341 Alex Oliva solved the executable page problem for SElinux.
342
343 The list above is almost certainly incomplete and inaccurate.  I'm
344 happy to make corrections or additions upon request.
345
346 If you have a problem, or have found a bug, please send a note to
347 green@redhat.com.