Merge pull request #95 from joshtriplett/news
[libffi.git] / README
1 Status
2 ======
3
4 libffi-3.0.14 was released on TBD.  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.
43 For specific configuration details and testing status, please
44 refer to the wiki page here:
45
46  http://www.moxielogic.org/wiki/index.php?title=Libffi_3.0.13
47
48 At the time of release, the following basic configurations have been
49 tested:
50
51 |-----------------+------------------+-------------------------|
52 | Architecture    | Operating System | Compiler                |
53 |-----------------+------------------+-------------------------|
54 | AArch64 (ARM64) | iOS              | Clang                   |
55 | AArch64         | Linux            | GCC                     |
56 | Alpha           | Linux            | GCC                     |
57 | Alpha           | Tru64            | GCC                     |
58 | ARC             | Linux            | GCC                     |
59 | ARM             | Linux            | GCC                     |
60 | ARM             | iOS              | GCC                     |
61 | AVR32           | Linux            | GCC                     |
62 | Blackfin        | uClinux          | GCC                     |
63 | HPPA            | HPUX             | GCC                     |
64 | IA-64           | Linux            | GCC                     |
65 | M68K            | FreeMiNT         | GCC                     |
66 | M68K            | Linux            | GCC                     |
67 | M68K            | RTEMS            | GCC                     |
68 | M88K            | OpenBSD/mvme88k  | GCC                     |
69 | Meta            | Linux            | GCC                     |
70 | MicroBlaze      | Linux            | GCC                     |
71 | MIPS            | IRIX             | GCC                     |
72 | MIPS            | Linux            | GCC                     |
73 | MIPS            | RTEMS            | GCC                     |
74 | MIPS64          | Linux            | GCC                     |
75 | Moxie           | Bare metal       | GCC                     |
76 | Nios II         | Linux            | GCC                     |
77 | PowerPC 32-bit  | AIX              | IBM XL C                |
78 | PowerPC 64-bit  | AIX              | IBM XL C                |
79 | PowerPC         | AMIGA            | GCC                     |
80 | PowerPC         | Linux            | GCC                     |
81 | PowerPC         | Mac OSX          | GCC                     |
82 | PowerPC         | FreeBSD          | GCC                     |
83 | PowerPC 64-bit  | FreeBSD          | GCC                     |
84 | PowerPC 64-bit  | Linux ELFv1      | GCC                     |
85 | PowerPC 64-bit  | Linux ELFv2      | GCC                     |
86 | S390            | Linux            | GCC                     |
87 | S390X           | Linux            | GCC                     |
88 | SPARC           | Linux            | GCC                     |
89 | SPARC           | Solaris          | GCC                     |
90 | SPARC           | Solaris          | Oracle Solaris Studio C |
91 | SPARC64         | Linux            | GCC                     |
92 | SPARC64         | FreeBSD          | GCC                     |
93 | SPARC64         | Solaris          | Oracle Solaris Studio C |
94 | TILE-Gx/TILEPro | Linux            | GCC                     |
95 | VAX             | OpenBSD/vax      | GCC                     |
96 | X86             | FreeBSD          | GCC                     |
97 | X86             | GNU HURD         | GCC                     |
98 | X86             | Interix          | GCC                     |
99 | X86             | kFreeBSD         | GCC                     |
100 | X86             | Linux            | GCC                     |
101 | X86             | Mac OSX          | GCC                     |
102 | X86             | OpenBSD          | GCC                     |
103 | X86             | OS/2             | GCC                     |
104 | X86             | Solaris          | GCC                     |
105 | X86             | Solaris          | Oracle Solaris Studio C |
106 | X86             | Windows/Cygwin   | GCC                     |
107 | X86             | Windows/MingW    | GCC                     |
108 | X86-64          | FreeBSD          | GCC                     |
109 | X86-64          | Linux            | GCC                     |
110 | X86-64          | Linux/x32        | GCC                     |
111 | X86-64          | OpenBSD          | GCC                     |
112 | X86-64          | Solaris          | Oracle Solaris Studio C |
113 | X86-64          | Windows/MingW    | GCC                     |
114 | Xtensa          | Linux            | GCC                     |
115 |-----------------+------------------+-------------------------|
116
117 Please send additional platform test results to
118 libffi-discuss@sourceware.org and feel free to update the wiki page
119 above.
120
121 Installing libffi
122 =================
123
124 First you must configure the distribution for your particular
125 system. Go to the directory you wish to build libffi in and run the
126 "configure" program found in the root directory of the libffi source
127 distribution.
128
129 If you're building libffi directly from version control, configure won't
130 exist yet; run ./autogen.sh first.
131
132 You may want to tell configure where to install the libffi library and
133 header files. To do that, use the --prefix configure switch.  Libffi
134 will install under /usr/local by default. 
135
136 If you want to enable extra run-time debugging checks use the the
137 --enable-debug configure switch. This is useful when your program dies
138 mysteriously while using libffi. 
139
140 Another useful configure switch is --enable-purify-safety. Using this
141 will add some extra code which will suppress certain warnings when you
142 are using Purify with libffi. Only use this switch when using 
143 Purify, as it will slow down the library.
144
145 It's also possible to build libffi on Windows platforms with
146 Microsoft's Visual C++ compiler.  In this case, use the msvcc.sh
147 wrapper script during configuration like so:
148
149 path/to/configure CC=path/to/msvcc.sh LD=link CPP=\"cl -nologo -EP\"
150
151 For 64-bit Windows builds, use CC="path/to/msvcc.sh -m64".
152 You may also need to specify --build appropriately. When building with MSVC
153 under a MingW environment, you may need to remove the line in configure
154 that sets 'fix_srcfile_path' to a 'cygpath' command. ('cygpath' is not
155 present in MingW, and is not required when using MingW-style paths.)
156
157 For iOS builds, the 'libffi.xcodeproj' Xcode project is available.
158
159 Configure has many other options. Use "configure --help" to see them all.
160
161 Once configure has finished, type "make". Note that you must be using
162 GNU make.  You can ftp GNU make from ftp.gnu.org:/pub/gnu/make .
163
164 To ensure that libffi is working as advertised, type "make check".
165 This will require that you have DejaGNU installed.
166
167 To install the library and header files, type "make install".
168
169
170 History
171 =======
172
173 See the ChangeLog files for details.
174
175 3.0.14 TBD
176         Add AArch64 (ARM64) iOS support.
177         Add Nios II support.
178         Add m88k and DEC VAX support.
179         Add support for stdcall, thiscall, and fastcall on non-Windows 32-bit
180           x86 targets such as Linux.
181         Make the testsuite more robust: eliminated several spurious failures.
182         Android build fix.
183         Fix MIPS N32 ABI bug.
184         Various x86, FreeBSD and UltraSPARC IIi fixes.
185
186 3.0.13 Mar-17-13
187         Add Meta support.
188         Add missing Moxie bits.
189         Fix stack alignment bug on 32-bit x86.
190         Build fix for m68000 targets.
191         Build fix for soft-float Power targets.
192         Fix the install dir location for some platforms when building
193           with GCC (OS X, Solaris).
194         Fix Cygwin regression.
195
196 3.0.12 Feb-11-13
197         Add Moxie support.
198         Add AArch64 support.
199         Add Blackfin support.
200         Add TILE-Gx/TILEPro support.
201         Add MicroBlaze support.
202         Add Xtensa support.
203         Add support for PaX enabled kernels with MPROTECT.
204         Add support for native vendor compilers on
205           Solaris and AIX.
206         Work around LLVM/GCC interoperability issue on x86_64.
207
208 3.0.11 Apr-11-12
209         Lots of build fixes.
210         Add support for variadic functions (ffi_prep_cif_var).
211         Add Linux/x32 support.
212         Add thiscall, fastcall and MSVC cdecl support on Windows.
213         Add Amiga and newer MacOS support.
214         Add m68k FreeMiNT support.
215         Integration with iOS' xcode build tools.
216         Fix Octeon and MC68881 support.
217         Fix code pessimizations.
218
219 3.0.10 Aug-23-11
220         Add support for Apple's iOS.
221         Add support for ARM VFP ABI.
222         Add RTEMS support for MIPS and M68K.
223         Fix instruction cache clearing problems on
224           ARM and SPARC.
225         Fix the N64 build on mips-sgi-irix6.5.
226         Enable builds with Microsoft's compiler.
227         Enable x86 builds with Oracle's Solaris compiler.
228         Fix support for calling code compiled with Oracle's Sparc
229           Solaris compiler.
230         Testsuite fixes for Tru64 Unix.
231         Additional platform support.
232
233 3.0.9 Dec-31-09
234         Add AVR32 and win64 ports.  Add ARM softfp support.
235         Many fixes for AIX, Solaris, HP-UX, *BSD.
236         Several PowerPC and x86-64 bug fixes.
237         Build DLL for windows.
238
239 3.0.8 Dec-19-08
240         Add *BSD, BeOS, and PA-Linux support.
241
242 3.0.7 Nov-11-08
243         Fix for ppc FreeBSD.
244         (thanks to Andreas Tobler)
245
246 3.0.6 Jul-17-08
247         Fix for closures on sh.
248         Mark the sh/sh64 stack as non-executable.
249         (both thanks to Kaz Kojima)
250
251 3.0.5 Apr-3-08
252         Fix libffi.pc file.
253         Fix #define ARM for IcedTea users.
254         Fix x86 closure bug.
255
256 3.0.4 Feb-24-08
257         Fix x86 OpenBSD configury.
258
259 3.0.3 Feb-22-08
260         Enable x86 OpenBSD thanks to Thomas Heller, and
261         x86-64 FreeBSD thanks to Björn König and Andreas Tobler.
262         Clean up test instruction in README.
263
264 3.0.2 Feb-21-08
265         Improved x86 FreeBSD support.
266         Thanks to Björn König.
267
268 3.0.1 Feb-15-08
269         Fix instruction cache flushing bug on MIPS.
270         Thanks to David Daney.
271
272 3.0.0 Feb-15-08
273         Many changes, mostly thanks to the GCC project.
274         Cygnus Solutions is now Red Hat.
275
276   [10 years go by...]
277
278 1.20 Oct-5-98
279         Raffaele Sena produces ARM port.
280
281 1.19 Oct-5-98
282         Fixed x86 long double and long long return support.
283         m68k bug fixes from Andreas Schwab.
284         Patch for DU assembler compatibility for the Alpha from Richard
285         Henderson.
286
287 1.18 Apr-17-98
288         Bug fixes and MIPS configuration changes.
289
290 1.17 Feb-24-98
291         Bug fixes and m68k port from Andreas Schwab. PowerPC port from
292         Geoffrey Keating. Various bug x86, Sparc and MIPS bug fixes.
293
294 1.16 Feb-11-98
295         Richard Henderson produces Alpha port.
296
297 1.15 Dec-4-97
298         Fixed an n32 ABI bug. New libtool, auto* support.
299
300 1.14 May-13-97
301         libtool is now used to generate shared and static libraries.
302         Fixed a minor portability problem reported by Russ McManus
303         <mcmanr@eq.gs.com>.
304
305 1.13 Dec-2-96
306         Added --enable-purify-safety to keep Purify from complaining
307         about certain low level code.
308         Sparc fix for calling functions with < 6 args.
309         Linux x86 a.out fix.
310
311 1.12 Nov-22-96
312         Added missing ffi_type_void, needed for supporting void return 
313         types. Fixed test case for non MIPS machines. Cygnus Support 
314         is now Cygnus Solutions. 
315
316 1.11 Oct-30-96
317         Added notes about GNU make.
318
319 1.10 Oct-29-96
320         Added configuration fix for non GNU compilers.
321
322 1.09 Oct-29-96
323         Added --enable-debug configure switch. Clean-ups based on LCLint 
324         feedback. ffi_mips.h is always installed. Many configuration 
325         fixes. Fixed ffitest.c for sparc builds.
326
327 1.08 Oct-15-96
328         Fixed n32 problem. Many clean-ups.
329
330 1.07 Oct-14-96
331         Gordon Irlam rewrites v8.S again. Bug fixes.
332
333 1.06 Oct-14-96
334         Gordon Irlam improved the sparc port. 
335
336 1.05 Oct-14-96
337         Interface changes based on feedback.
338
339 1.04 Oct-11-96
340         Sparc port complete (modulo struct passing bug).
341
342 1.03 Oct-10-96
343         Passing struct args, and returning struct values works for
344         all architectures/calling conventions. Expanded tests.
345
346 1.02 Oct-9-96
347         Added SGI n32 support. Fixed bugs in both o32 and Linux support.
348         Added "make test".
349
350 1.01 Oct-8-96
351         Fixed float passing bug in mips version. Restructured some
352         of the code. Builds cleanly with SGI tools.
353
354 1.00 Oct-7-96
355         First release. No public announcement.
356
357
358 Authors & Credits
359 =================
360
361 libffi was originally written by Anthony Green <green@moxielogic.com>.
362
363 The developers of the GNU Compiler Collection project have made
364 innumerable valuable contributions.  See the ChangeLog file for
365 details.
366
367 Some of the ideas behind libffi were inspired by Gianni Mariani's free
368 gencall library for Silicon Graphics machines.
369
370 The closure mechanism was designed and implemented by Kresten Krab
371 Thorup.
372
373 Major processor architecture ports were contributed by the following
374 developers:
375
376 aarch64         Marcus Shawcroft, James Greenhalgh
377 alpha           Richard Henderson
378 arm             Raffaele Sena
379 blackfin        Alexandre Keunecke I. de Mendonca
380 cris            Simon Posnjak, Hans-Peter Nilsson
381 frv             Anthony Green
382 ia64            Hans Boehm
383 m32r            Kazuhiro Inaoka
384 m68k            Andreas Schwab
385 m88k            Miod Vallat
386 microblaze      Nathan Rossi
387 mips            Anthony Green, Casey Marshall
388 mips64          David Daney
389 moxie           Anthony Green
390 nios ii         Sandra Loosemore
391 pa              Randolph Chung, Dave Anglin, Andreas Tobler
392 powerpc         Geoffrey Keating, Andreas Tobler, 
393                          David Edelsohn, John Hornkvist
394 powerpc64       Jakub Jelinek
395 s390            Gerhard Tonn, Ulrich Weigand
396 sh              Kaz Kojima
397 sh64            Kaz Kojima
398 sparc           Anthony Green, Gordon Irlam
399 tile-gx/tilepro Walter Lee
400 vax             Miod Vallat
401 x86             Anthony Green, Jon Beniston
402 x86-64          Bo Thorsen
403 xtensa          Chris Zankel
404
405 Jesper Skov and Andrew Haley both did more than their fair share of
406 stepping through the code and tracking down bugs.
407
408 Thanks also to Tom Tromey for bug fixes, documentation and
409 configuration help.
410
411 Thanks to Jim Blandy, who provided some useful feedback on the libffi
412 interface.
413
414 Andreas Tobler has done a tremendous amount of work on the testsuite.
415
416 Alex Oliva solved the executable page problem for SElinux.
417
418 The list above is almost certainly incomplete and inaccurate.  I'm
419 happy to make corrections or additions upon request.
420
421 If you have a problem, or have found a bug, please send a note to the
422 author at green@moxielogic.com, or the project mailing list at
423 libffi-discuss@sourceware.org.