libffi/README.md

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