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