libffi/README

   1 This directory contains the libffi package, which is not part of GCC but
   2 shipped with GCC as convenience.
   3
   4 Status
   5 ======
   6
   7 libffi-3.0.8 was released on December 19, 2008. Check the libffi web
   8 page for updates: <URL:http://sourceware.org/libffi/>.
   9
  10
  11 What is libffi?
  12 ===============
  13
  14 Compilers for high level languages generate code that follow certain
  15 conventions. These conventions are necessary, in part, for separate
  16 compilation to work. One such convention is the "calling
  17 convention". The "calling convention" is essentially a set of
  18 assumptions made by the compiler about where function arguments will
  19 be found on entry to a function. A "calling convention" also specifies
  20 where the return value for a function is found.
  21
  22 Some programs may not know at the time of compilation what arguments
  23 are to be passed to a function. For instance, an interpreter may be
  24 told at run-time about the number and types of arguments used to call
  25 a given function. Libffi can be used in such programs to provide a
  26 bridge from the interpreter program to compiled code.
  27
  28 The libffi library provides a portable, high level programming
  29 interface to various calling conventions. This allows a programmer to
  30 call any function specified by a call interface description at run
  31 time.
  32
  33 FFI stands for Foreign Function Interface.  A foreign function
  34 interface is the popular name for the interface that allows code
  35 written in one language to call code written in another language. The
  36 libffi library really only provides the lowest, machine dependent
  37 layer of a fully featured foreign function interface. A layer must
  38 exist above libffi that handles type conversions for values passed
  39 between the two languages.
  40
  41
  42 Supported Platforms
  43 ===================
  44
  45 Libffi has been ported to many different platforms, although this
  46 release was only tested on:
  47
  48      arm oabi linux
  49      arm eabi linux
  50      hppa linux
  51      mips o32 linux (little endian)
  52      powerpc darwin
  53      powerpc freebsd
  54      powerpc64 linux
  55      sparc solaris
  56      sparc64 freebsd
  57      sparc64 solaris
  58      x86 cygwin
  59      x86 darwin
  60      x86 freebsd
  61      x86 linux
  62      x86 openbsd
  63      x86 solaris
  64      x86-64 mingw
  65      x86-64 darwin
  66      x86-64 linux
  67      x86-64 OS X
  68      x86-64 freebsd
  69      x86-64 solaris
  70
  71 Please send additional platform test results to
  72 libffi-discuss@sourceware.org.
  73
  74 Installing libffi
  75 =================
  76
  77 [Note: before actually performing any of these installation steps,
  78  you may wish to read the "Platform Specific Notes" below.]
  79
  80 First you must configure the distribution for your particular
  81 system. Go to the directory you wish to build libffi in and run the
  82 "configure" program found in the root directory of the libffi source
  83 distribution.
  84
  85 You may want to tell configure where to install the libffi library and
  86 header files. To do that, use the --prefix configure switch.  Libffi
  87 will install under /usr/local by default.
  88
  89 If you want to enable extra run-time debugging checks use the the
  90 --enable-debug configure switch. This is useful when your program dies
  91 mysteriously while using libffi.
  92
  93 Another useful configure switch is --enable-purify-safety. Using this
  94 will add some extra code which will suppress certain warnings when you
  95 are using Purify with libffi. Only use this switch when using
  96 Purify, as it will slow down the library.
  97
  98 Configure has many other options. Use "configure --help" to see them all.
  99
 100 Once configure has finished, type "make". Note that you must be using
 101 GNU make.  You can ftp GNU make from prep.ai.mit.edu:/pub/gnu.
 102
 103 To ensure that libffi is working as advertised, type "make check".
 104 This will require that you have DejaGNU installed.
 105
 106 To install the library and header files, type "make install".
 107
 108
 109 Platform Specific Notes
 110 =======================
 111
 112         MIPS - Irix 5.3 & 6.x
 113         ---------------------
 114
 115 Irix 6.2 and better supports three different calling conventions: o32,
 116 n32 and n64. Currently, libffi only supports both o32 and n32 under
 117 Irix 6.x, but only o32 under Irix 5.3. Libffi will automatically be
 118 configured for whichever calling convention it was built for.
 119
 120 By default, the configure script will try to build libffi with the GNU
 121 development tools. To build libffi with the SGI development tools, set
 122 the environment variable CC to either "cc -32" or "cc -n32" before
 123 running configure under Irix 6.x (depending on whether you want an o32
 124 or n32 library), or just "cc" for Irix 5.3.
 125
 126 With the n32 calling convention, when returning structures smaller
 127 than 16 bytes, be sure to provide an RVALUE that is 8 byte aligned.
 128 Here's one way of forcing this:
 129
 130         double struct_storage[2];
 131         my_small_struct *s = (my_small_struct *) struct_storage;
 132         /* Use s for RVALUE */
 133
 134 If you don't do this you are liable to get spurious bus errors.
 135
 136 "long long" values are not supported yet.
 137
 138 You must use GNU Make to build libffi on SGI platforms.
 139
 140
 141         PowerPC System V ABI
 142         --------------------
 143
 144 There are two `System V ABI's which libffi implements for PowerPC.
 145 They differ only in how small structures are returned from functions.
 146
 147 In the FFI_SYSV version, structures that are 8 bytes or smaller are
 148 returned in registers.  This is what GCC does when it is configured
 149 for solaris, and is what the System V ABI I have (dated September
 150 1995) says.
 151
 152 In the FFI_GCC_SYSV version, all structures are returned the same way:
 153 by passing a pointer as the first argument to the function.  This is
 154 what GCC does when it is configured for linux or a generic sysv
 155 target.
 156
 157 EGCS 1.0.1 (and probably other versions of EGCS/GCC) also has a
 158 inconsistency with the SysV ABI: When a procedure is called with many
 159 floating-point arguments, some of them get put on the stack.  They are
 160 all supposed to be stored in double-precision format, even if they are
 161 only single-precision, but EGCS stores single-precision arguments as
 162 single-precision anyway.  This causes one test to fail (the `many
 163 arguments' test).
 164
 165
 166 History
 167 =======
 168
 169 3.0.7 Nov-11-08
 170         Fix for ppc FreeBSD.
 171         (thanks to Andreas Tobler)
 172
 173 3.0.6 Jul-17-08
 174         Fix for closures on sh.
 175         Mark the sh/sh64 stack as non-executable.
 176         (both thanks to Kaz Kojima)
 177
 178 3.0.5 Apr-3-08
 179         Fix libffi.pc file.
 180         Fix #define ARM for IcedTea users.
 181         Fix x86 closure bug.
 182
 183 3.0.4 Feb-24-08
 184         Fix x86 OpenBSD configury.
 185
 186 3.0.3 Feb-22-08
 187         Enable x86 OpenBSD thanks to Thomas Heller, and
 188         x86-64 FreeBSD thanks to Björn König and Andreas Tobler.
 189         Clean up test instruction in README.
 190
 191 3.0.2 Feb-21-08
 192         Improved x86 FreeBSD support.
 193         Thanks to Björn König.
 194
 195 3.0.1 Feb-15-08
 196         Fix instruction cache flushing bug on MIPS.
 197         Thanks to David Daney.
 198
 199 3.0.0 Feb-15-08
 200         Many changes, mostly thanks to the GCC project.
 201         Cygnus Solutions is now Red Hat.
 202
 203   [10 years go by...]
 204
 205 1.20 Oct-5-98
 206         Raffaele Sena produces ARM port.
 207
 208 1.19 Oct-5-98
 209         Fixed x86 long double and long long return support.
 210         m68k bug fixes from Andreas Schwab.
 211         Patch for DU assembler compatibility for the Alpha from Richard
 212         Henderson.
 213
 214 1.18 Apr-17-98
 215         Bug fixes and MIPS configuration changes.
 216
 217 1.17 Feb-24-98
 218         Bug fixes and m68k port from Andreas Schwab. PowerPC port from
 219         Geoffrey Keating. Various bug x86, Sparc and MIPS bug fixes.
 220
 221 1.16 Feb-11-98
 222         Richard Henderson produces Alpha port.
 223
 224 1.15 Dec-4-97
 225         Fixed an n32 ABI bug. New libtool, auto* support.
 226
 227 1.14 May-13-97
 228         libtool is now used to generate shared and static libraries.
 229         Fixed a minor portability problem reported by Russ McManus
 230         <mcmanr@eq.gs.com>.
 231
 232 1.13 Dec-2-96
 233         Added --enable-purify-safety to keep Purify from complaining
 234         about certain low level code.
 235         Sparc fix for calling functions with < 6 args.
 236         Linux x86 a.out fix.
 237
 238 1.12 Nov-22-96
 239         Added missing ffi_type_void, needed for supporting void return
 240         types. Fixed test case for non MIPS machines. Cygnus Support
 241         is now Cygnus Solutions.
 242
 243 1.11 Oct-30-96
 244         Added notes about GNU make.
 245
 246 1.10 Oct-29-96
 247         Added configuration fix for non GNU compilers.
 248
 249 1.09 Oct-29-96
 250         Added --enable-debug configure switch. Clean-ups based on LCLint
 251         feedback. ffi_mips.h is always installed. Many configuration
 252         fixes. Fixed ffitest.c for sparc builds.
 253
 254 1.08 Oct-15-96
 255         Fixed n32 problem. Many clean-ups.
 256
 257 1.07 Oct-14-96
 258         Gordon Irlam rewrites v8.S again. Bug fixes.
 259
 260 1.06 Oct-14-96
 261         Gordon Irlam improved the sparc port.
 262
 263 1.05 Oct-14-96
 264         Interface changes based on feedback.
 265
 266 1.04 Oct-11-96
 267         Sparc port complete (modulo struct passing bug).
 268
 269 1.03 Oct-10-96
 270         Passing struct args, and returning struct values works for
 271         all architectures/calling conventions. Expanded tests.
 272
 273 1.02 Oct-9-96
 274         Added SGI n32 support. Fixed bugs in both o32 and Linux support.
 275         Added "make test".
 276
 277 1.01 Oct-8-96
 278         Fixed float passing bug in mips version. Restructured some
 279         of the code. Builds cleanly with SGI tools.
 280
 281 1.00 Oct-7-96
 282         First release. No public announcement.
 283
 284
 285 Authors & Credits
 286 =================
 287
 288 libffi was originally written by Anthony Green <green@redhat.com>.
 289
 290 The developers of the GNU Compiler Collection project have made
 291 innumerable valuable contributions.  See the ChangeLog file for
 292 details.
 293
 294 Some of the ideas behind libffi were inspired by Gianni Mariani's free
 295 gencall library for Silicon Graphics machines.
 296
 297 The closure mechanism was designed and implemented by Kresten Krab
 298 Thorup.
 299
 300 Major processor architecture ports were contributed by the following
 301 developers:
 302
 303 alpha           Richard Henderson
 304 arm             Raffaele Sena
 305 cris            Simon Posnjak, Hans-Peter Nilsson
 306 frv             Anthony Green
 307 ia64            Hans Boehm
 308 m32r            Kazuhiro Inaoka
 309 m68k            Andreas Schwab
 310 mips            Anthony Green, Casey Marshall
 311 mips64          David Daney
 312 pa              Randolph Chung, Dave Anglin, Andreas Tobler
 313 powerpc         Geoffrey Keating, Andreas Tobler,
 314                          David Edelsohn, John Hornkvist
 315 powerpc64       Jakub Jelinek
 316 s390            Gerhard Tonn, Ulrich Weigand
 317 sh              Kaz Kojima
 318 sh64            Kaz Kojima
 319 sparc           Anthony Green, Gordon Irlam
 320 x86             Anthony Green, Jon Beniston
 321 x86-64          Bo Thorsen
 322
 323 Jesper Skov and Andrew Haley both did more than their fair share of
 324 stepping through the code and tracking down bugs.
 325
 326 Thanks also to Tom Tromey for bug fixes, documentation and
 327 configuration help.
 328
 329 Thanks to Jim Blandy, who provided some useful feedback on the libffi
 330 interface.
 331
 332 Andreas Tobler has done a tremendous amount of work on the testsuite.
 333
 334 Alex Oliva solved the executable page problem for SElinux.
 335
 336 The list above is almost certainly incomplete and inaccurate.  I'm
 337 happy to make corrections or additions upon request.
 338
 339 If you have a problem, or have found a bug, please send a note to
 340 green@redhat.com.