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