1
This directory contains the libffi package, which is not part of GCC but
2
shipped with GCC as convenience.
7
libffi-2.00 has not been released yet! This is a development snapshot!
9
libffi-1.20 was released on October 5, 1998. Check the libffi web
10
page for updates: <URL:http://sources.redhat.com/libffi/>.
16
Compilers for high level languages generate code that follow certain
17
conventions. These conventions are necessary, in part, for separate
18
compilation to work. One such convention is the "calling
19
convention". The "calling convention" is essentially a set of
20
assumptions made by the compiler about where function arguments will
21
be found on entry to a function. A "calling convention" also specifies
22
where the return value for a function is found.
24
Some programs may not know at the time of compilation what arguments
25
are to be passed to a function. For instance, an interpreter may be
26
told at run-time about the number and types of arguments used to call
27
a given function. Libffi can be used in such programs to provide a
28
bridge from the interpreter program to compiled code.
30
The libffi library provides a portable, high level programming
31
interface to various calling conventions. This allows a programmer to
32
call any function specified by a call interface description at run
35
Ffi stands for Foreign Function Interface. A foreign function
36
interface is the popular name for the interface that allows code
37
written in one language to call code written in another language. The
38
libffi library really only provides the lowest, machine dependent
39
layer of a fully featured foreign function interface. A layer must
40
exist above libffi that handles type conversions for values passed
41
between the two languages.
44
Supported Platforms and Prerequisites
45
=====================================
47
Libffi has been ported to:
49
SunOS 4.1.3 & Solaris 2.x (SPARC-V8, SPARC-V9)
51
Irix 5.3 & 6.2 (System V/o32 & n32)
53
Intel x86 - Linux (System V ABI)
55
Alpha - Linux and OSF/1
57
m68k - Linux (System V ABI)
59
PowerPC - Linux (System V ABI, Darwin, AIX)
61
ARM - Linux (System V ABI)
63
Libffi has been tested with the egcs 1.0.2 gcc compiler. Chances are
64
that other versions will work. Libffi has also been built and tested
65
with the SGI compiler tools.
67
On PowerPC, the tests failed (see the note below).
69
You must use GNU make to build libffi. SGI's make will not work.
70
Sun's probably won't either.
72
If you port libffi to another platform, please let me know! I assume
73
that some will be easy (x86 NetBSD), and others will be more difficult
80
[Note: before actually performing any of these installation steps,
81
you may wish to read the "Platform Specific Notes" below.]
83
First you must configure the distribution for your particular
84
system. Go to the directory you wish to build libffi in and run the
85
"configure" program found in the root directory of the libffi source
88
You may want to tell configure where to install the libffi library and
89
header files. To do that, use the --prefix configure switch. Libffi
90
will install under /usr/local by default.
92
If you want to enable extra run-time debugging checks use the the
93
--enable-debug configure switch. This is useful when your program dies
94
mysteriously while using libffi.
96
Another useful configure switch is --enable-purify-safety. Using this
97
will add some extra code which will suppress certain warnings when you
98
are using Purify with libffi. Only use this switch when using
99
Purify, as it will slow down the library.
101
Configure has many other options. Use "configure --help" to see them all.
103
Once configure has finished, type "make". Note that you must be using
104
GNU make. SGI's make will not work. Sun's probably won't either.
105
You can ftp GNU make from prep.ai.mit.edu:/pub/gnu.
107
To ensure that libffi is working as advertised, type "make test".
109
To install the library and header files, type "make install".
118
Libffi assumes that you have a pointer to the function you wish to
119
call and that you know the number and types of arguments to pass it,
120
as well as the return type of the function.
122
The first thing you must do is create an ffi_cif object that matches
123
the signature of the function you wish to call. The cif in ffi_cif
124
stands for Call InterFace. To prepare a call interface object, use the
127
ffi_status ffi_prep_cif(ffi_cif *cif, ffi_abi abi,
129
ffi_type *rtype, ffi_type **atypes);
131
CIF is a pointer to the call interface object you wish
134
ABI is an enum that specifies the calling convention
135
to use for the call. FFI_DEFAULT_ABI defaults
136
to the system's native calling convention. Other
137
ABI's may be used with care. They are system
140
NARGS is the number of arguments this function accepts.
141
libffi does not yet support vararg functions.
143
RTYPE is a pointer to an ffi_type structure that represents
144
the return type of the function. Ffi_type objects
145
describe the types of values. libffi provides
146
ffi_type objects for many of the native C types:
147
signed int, unsigned int, signed char, unsigned char,
148
etc. There is also a pointer ffi_type object and
149
a void ffi_type. Use &ffi_type_void for functions that
152
ATYPES is a vector of ffi_type pointers. ARGS must be NARGS long.
153
If NARGS is 0, this is ignored.
156
ffi_prep_cif will return a status code that you are responsible
157
for checking. It will be one of the following:
159
FFI_OK - All is good.
161
FFI_BAD_TYPEDEF - One of the ffi_type objects that ffi_prep_cif
165
Before making the call, the VALUES vector should be initialized
166
with pointers to the appropriate argument values.
168
To call the the function using the initialized ffi_cif, use the
171
void ffi_call(ffi_cif *cif, void *fn, void *rvalue, void **avalues);
173
CIF is a pointer to the ffi_cif initialized specifically
176
FN is a pointer to the function you want to call.
178
RVALUE is a pointer to a chunk of memory that is to hold the
179
result of the function call. Currently, it must be
180
at least one word in size (except for the n32 version
181
under Irix 6.x, which must be a pointer to an 8 byte
182
aligned value (a long long). It must also be at least
183
word aligned (depending on the return type, and the
184
system's alignment requirements). If RTYPE is
185
&ffi_type_void, this is ignored. If RVALUE is NULL,
186
the return value is discarded.
188
AVALUES is a vector of void* that point to the memory locations
189
holding the argument values for a call.
190
If NARGS is 0, this is ignored.
193
If you are expecting a return value from FN it will have been stored
201
Here is a trivial example that calls puts() a few times.
214
/* Initialize the argument info vectors */
215
args[0] = &ffi_type_uint;
218
/* Initialize the cif */
219
if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
220
&ffi_type_uint, args) == FFI_OK)
223
ffi_call(&cif, puts, &rc, values);
224
/* rc now holds the result of the call to puts */
226
/* values holds a pointer to the function's arg, so to
227
call puts() again all we need to do is change the
230
ffi_call(&cif, puts, &rc, values);
241
Although libffi has no special support for unions or bit-fields, it is
242
perfectly happy passing structures back and forth. You must first
243
describe the structure to libffi by creating a new ffi_type object
244
for it. Here is the definition of ffi_type:
246
typedef struct _ffi_type
251
struct _ffi_type **elements;
254
All structures must have type set to FFI_TYPE_STRUCT. You may set
255
size and alignment to 0. These will be calculated and reset to the
256
appropriate values by ffi_prep_cif().
258
elements is a NULL terminated array of pointers to ffi_type objects
259
that describe the type of the structure elements. These may, in turn,
260
be structure elements.
262
The following example initializes a ffi_type object representing the
263
tm struct from Linux's time.h:
275
/* Those are for future use. */
276
long int __tm_gmtoff__;
277
__const char *__tm_zone__;
282
ffi_type *tm_type_elements[12];
285
tm_type.size = tm_type.alignment = 0;
286
tm_type.elements = &tm_type_elements;
288
for (i = 0; i < 9; i++)
289
tm_type_elements[i] = &ffi_type_sint;
291
tm_type_elements[9] = &ffi_type_slong;
292
tm_type_elements[10] = &ffi_type_pointer;
293
tm_type_elements[11] = NULL;
295
/* tm_type can now be used to represent tm argument types and
296
return types for ffi_prep_cif() */
301
Platform Specific Notes
302
=======================
307
There are no known problems with the x86 port.
309
Sun SPARC - SunOS 4.1.3 & Solaris 2.x
310
-------------------------------------
312
You must use GNU Make to build libffi on Sun platforms.
314
MIPS - Irix 5.3 & 6.x
315
---------------------
317
Irix 6.2 and better supports three different calling conventions: o32,
318
n32 and n64. Currently, libffi only supports both o32 and n32 under
319
Irix 6.x, but only o32 under Irix 5.3. Libffi will automatically be
320
configured for whichever calling convention it was built for.
322
By default, the configure script will try to build libffi with the GNU
323
development tools. To build libffi with the SGI development tools, set
324
the environment variable CC to either "cc -32" or "cc -n32" before
325
running configure under Irix 6.x (depending on whether you want an o32
326
or n32 library), or just "cc" for Irix 5.3.
328
With the n32 calling convention, when returning structures smaller
329
than 16 bytes, be sure to provide an RVALUE that is 8 byte aligned.
330
Here's one way of forcing this:
332
double struct_storage[2];
333
my_small_struct *s = (my_small_struct *) struct_storage;
334
/* Use s for RVALUE */
336
If you don't do this you are liable to get spurious bus errors.
338
"long long" values are not supported yet.
340
You must use GNU Make to build libffi on SGI platforms.
345
The ARM port was performed on a NetWinder running ARM Linux ELF
346
(2.0.31) and gcc 2.8.1.
353
There are two `System V ABI's which libffi implements for PowerPC.
354
They differ only in how small structures are returned from functions.
356
In the FFI_SYSV version, structures that are 8 bytes or smaller are
357
returned in registers. This is what GCC does when it is configured
358
for solaris, and is what the System V ABI I have (dated September
361
In the FFI_GCC_SYSV version, all structures are returned the same way:
362
by passing a pointer as the first argument to the function. This is
363
what GCC does when it is configured for linux or a generic sysv
366
EGCS 1.0.1 (and probably other versions of EGCS/GCC) also has a
367
inconsistency with the SysV ABI: When a procedure is called with many
368
floating-point arguments, some of them get put on the stack. They are
369
all supposed to be stored in double-precision format, even if they are
370
only single-precision, but EGCS stores single-precision arguments as
371
single-precision anyway. This causes one test to fail (the `many
375
What's With The Crazy Comments?
376
===============================
378
You might notice a number of cryptic comments in the code, delimited
379
by /*@ and @*/. These are annotations read by the program LCLint, a
380
tool for statically checking C programs. You can read all about it at
381
<http://larch-www.lcs.mit.edu:8001/larch/lclint/index.html>.
388
Raffaele Sena produces ARM port.
391
Fixed x86 long double and long long return support.
392
m68k bug fixes from Andreas Schwab.
393
Patch for DU assembler compatibility for the Alpha from Richard
397
Bug fixes and MIPS configuration changes.
400
Bug fixes and m68k port from Andreas Schwab. PowerPC port from
401
Geoffrey Keating. Various bug x86, Sparc and MIPS bug fixes.
404
Richard Henderson produces Alpha port.
407
Fixed an n32 ABI bug. New libtool, auto* support.
410
libtool is now used to generate shared and static libraries.
411
Fixed a minor portability problem reported by Russ McManus
415
Added --enable-purify-safety to keep Purify from complaining
416
about certain low level code.
417
Sparc fix for calling functions with < 6 args.
421
Added missing ffi_type_void, needed for supporting void return
422
types. Fixed test case for non MIPS machines. Cygnus Support
423
is now Cygnus Solutions.
426
Added notes about GNU make.
429
Added configuration fix for non GNU compilers.
432
Added --enable-debug configure switch. Clean-ups based on LCLint
433
feedback. ffi_mips.h is always installed. Many configuration
434
fixes. Fixed ffitest.c for sparc builds.
437
Fixed n32 problem. Many clean-ups.
440
Gordon Irlam rewrites v8.S again. Bug fixes.
443
Gordon Irlam improved the sparc port.
446
Interface changes based on feedback.
449
Sparc port complete (modulo struct passing bug).
452
Passing struct args, and returning struct values works for
453
all architectures/calling conventions. Expanded tests.
456
Added SGI n32 support. Fixed bugs in both o32 and Linux support.
460
Fixed float passing bug in mips version. Restructured some
461
of the code. Builds cleanly with SGI tools.
464
First release. No public announcement.
470
libffi was written by Anthony Green <green@cygnus.com>.
472
Portions of libffi were derived from Gianni Mariani's free gencall
473
library for Silicon Graphics machines.
475
The closure mechanism was designed and implemented by Kresten Krab
478
The Sparc port was derived from code contributed by the fine folks at
479
Visible Decisions Inc <http://www.vdi.com>. Further enhancements were
480
made by Gordon Irlam at Cygnus Solutions <http://www.cygnus.com>.
482
The Alpha port was written by Richard Henderson at Cygnus Solutions.
484
Andreas Schwab ported libffi to m68k Linux and provided a number of
487
Geoffrey Keating ported libffi to the PowerPC.
489
Raffaele Sena ported libffi to the ARM.
491
Jesper Skov and Andrew Haley both did more than their fair share of
492
stepping through the code and tracking down bugs.
494
Thanks also to Tom Tromey for bug fixes and configuration help.
496
Thanks to Jim Blandy, who provided some useful feedback on the libffi
499
If you have a problem, or have found a bug, please send a note to
added
removed
libffi/README
