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