1 | README for libffi-2.00 |
---|
2 | |
---|
3 | libffi-2.00 has not been released yet! This is a development snapshot! |
---|
4 | |
---|
5 | libffi-1.20 was released on [SOME FUTURE DAY]. Check the libffi web |
---|
6 | page for updates: <URL:http://sourceware.cygnus.com/libffi/>. |
---|
7 | |
---|
8 | |
---|
9 | What is libffi? |
---|
10 | =============== |
---|
11 | |
---|
12 | Compilers for high level languages generate code that follow certain |
---|
13 | conventions. These conventions are necessary, in part, for separate |
---|
14 | compilation to work. One such convention is the "calling |
---|
15 | convention". The "calling convention" is essentially a set of |
---|
16 | assumptions made by the compiler about where function arguments will |
---|
17 | be found on entry to a function. A "calling convention" also specifies |
---|
18 | where the return value for a function is found. |
---|
19 | |
---|
20 | Some programs may not know at the time of compilation what arguments |
---|
21 | are to be passed to a function. For instance, an interpreter may be |
---|
22 | told at run-time about the number and types of arguments used to call |
---|
23 | a given function. Libffi can be used in such programs to provide a |
---|
24 | bridge from the interpreter program to compiled code. |
---|
25 | |
---|
26 | The libffi library provides a portable, high level programming |
---|
27 | interface to various calling conventions. This allows a programmer to |
---|
28 | call any function specified by a call interface description at run |
---|
29 | time. |
---|
30 | |
---|
31 | Ffi stands for Foreign Function Interface. A foreign function |
---|
32 | interface is the popular name for the interface that allows code |
---|
33 | written in one language to call code written in another language. The |
---|
34 | libffi library really only provides the lowest, machine dependent |
---|
35 | layer of a fully featured foreign function interface. A layer must |
---|
36 | exist above libffi that handles type conversions for values passed |
---|
37 | between the two languages. |
---|
38 | |
---|
39 | |
---|
40 | Supported Platforms and Prerequisites |
---|
41 | ===================================== |
---|
42 | |
---|
43 | Libffi has been ported to: |
---|
44 | |
---|
45 | SunOS 4.1.3 & Solaris 2.x (Sparc v8) |
---|
46 | |
---|
47 | Irix 5.3 & 6.2 (System V/o32 & n32) |
---|
48 | |
---|
49 | Intel x86 - Linux (System V ABI) |
---|
50 | |
---|
51 | Alpha - Linux and OSF/1 |
---|
52 | |
---|
53 | m68k - Linux (System V ABI) |
---|
54 | |
---|
55 | PowerPC - Linux (System V ABI, Darwin, AIX) |
---|
56 | |
---|
57 | ARM - Linux (System V ABI) |
---|
58 | |
---|
59 | Libffi has been tested with the egcs 1.0.2 gcc compiler. Chances are |
---|
60 | that other versions will work. Libffi has also been built and tested |
---|
61 | with the SGI compiler tools. |
---|
62 | |
---|
63 | On PowerPC, the tests failed (see the note below). |
---|
64 | |
---|
65 | You must use GNU make to build libffi. SGI's make will not work. |
---|
66 | Sun's probably won't either. |
---|
67 | |
---|
68 | If you port libffi to another platform, please let me know! I assume |
---|
69 | that some will be easy (x86 NetBSD), and others will be more difficult |
---|
70 | (HP). |
---|
71 | |
---|
72 | |
---|
73 | Installing libffi |
---|
74 | ================= |
---|
75 | |
---|
76 | [Note: before actually performing any of these installation steps, |
---|
77 | you may wish to read the "Platform Specific Notes" below.] |
---|
78 | |
---|
79 | First you must configure the distribution for your particular |
---|
80 | system. Go to the directory you wish to build libffi in and run the |
---|
81 | "configure" program found in the root directory of the libffi source |
---|
82 | distribution. |
---|
83 | |
---|
84 | You may want to tell configure where to install the libffi library and |
---|
85 | header files. To do that, use the --prefix configure switch. Libffi |
---|
86 | will install under /usr/local by default. |
---|
87 | |
---|
88 | If you want to enable extra run-time debugging checks use the the |
---|
89 | --enable-debug configure switch. This is useful when your program dies |
---|
90 | mysteriously while using libffi. |
---|
91 | |
---|
92 | Another useful configure switch is --enable-purify-safety. Using this |
---|
93 | will add some extra code which will suppress certain warnings when you |
---|
94 | are using Purify with libffi. Only use this switch when using |
---|
95 | Purify, as it will slow down the library. |
---|
96 | |
---|
97 | Configure has many other options. Use "configure --help" to see them all. |
---|
98 | |
---|
99 | Once configure has finished, type "make". Note that you must be using |
---|
100 | GNU make. SGI's make will not work. Sun's probably won't either. |
---|
101 | You can ftp GNU make from prep.ai.mit.edu:/pub/gnu. |
---|
102 | |
---|
103 | To ensure that libffi is working as advertised, type "make test". |
---|
104 | |
---|
105 | To install the library and header files, type "make install". |
---|
106 | |
---|
107 | |
---|
108 | Using libffi |
---|
109 | ============ |
---|
110 | |
---|
111 | The Basics |
---|
112 | ---------- |
---|
113 | |
---|
114 | Libffi assumes that you have a pointer to the function you wish to |
---|
115 | call and that you know the number and types of arguments to pass it, |
---|
116 | as well as the return type of the function. |
---|
117 | |
---|
118 | The first thing you must do is create an ffi_cif object that matches |
---|
119 | the signature of the function you wish to call. The cif in ffi_cif |
---|
120 | stands for Call InterFace. To prepare a call interface object, use the |
---|
121 | following function: |
---|
122 | |
---|
123 | ffi_status ffi_prep_cif(ffi_cif *cif, ffi_abi abi, |
---|
124 | unsigned int nargs, |
---|
125 | ffi_type *rtype, ffi_type **atypes); |
---|
126 | |
---|
127 | CIF is a pointer to the call interface object you wish |
---|
128 | to initialize. |
---|
129 | |
---|
130 | ABI is an enum that specifies the calling convention |
---|
131 | to use for the call. FFI_DEFAULT_ABI defaults |
---|
132 | to the system's native calling convention. Other |
---|
133 | ABI's may be used with care. They are system |
---|
134 | specific. |
---|
135 | |
---|
136 | NARGS is the number of arguments this function accepts. |
---|
137 | libffi does not yet support vararg functions. |
---|
138 | |
---|
139 | RTYPE is a pointer to an ffi_type structure that represents |
---|
140 | the return type of the function. Ffi_type objects |
---|
141 | describe the types of values. libffi provides |
---|
142 | ffi_type objects for many of the native C types: |
---|
143 | signed int, unsigned int, signed char, unsigned char, |
---|
144 | etc. There is also a pointer ffi_type object and |
---|
145 | a void ffi_type. Use &ffi_type_void for functions that |
---|
146 | don't return values. |
---|
147 | |
---|
148 | ATYPES is a vector of ffi_type pointers. ARGS must be NARGS long. |
---|
149 | If NARGS is 0, this is ignored. |
---|
150 | |
---|
151 | |
---|
152 | ffi_prep_cif will return a status code that you are responsible |
---|
153 | for checking. It will be one of the following: |
---|
154 | |
---|
155 | FFI_OK - All is good. |
---|
156 | |
---|
157 | FFI_BAD_TYPEDEF - One of the ffi_type objects that ffi_prep_cif |
---|
158 | came across is bad. |
---|
159 | |
---|
160 | |
---|
161 | Before making the call, the VALUES vector should be initialized |
---|
162 | with pointers to the appropriate argument values. |
---|
163 | |
---|
164 | To call the the function using the initialized ffi_cif, use the |
---|
165 | ffi_call function: |
---|
166 | |
---|
167 | void ffi_call(ffi_cif *cif, void *fn, void *rvalue, void **avalues); |
---|
168 | |
---|
169 | CIF is a pointer to the ffi_cif initialized specifically |
---|
170 | for this function. |
---|
171 | |
---|
172 | FN is a pointer to the function you want to call. |
---|
173 | |
---|
174 | RVALUE is a pointer to a chunk of memory that is to hold the |
---|
175 | result of the function call. Currently, it must be |
---|
176 | at least one word in size (except for the n32 version |
---|
177 | under Irix 6.x, which must be a pointer to an 8 byte |
---|
178 | aligned value (a long long). It must also be at least |
---|
179 | word aligned (depending on the return type, and the |
---|
180 | system's alignment requirements). If RTYPE is |
---|
181 | &ffi_type_void, this is ignored. If RVALUE is NULL, |
---|
182 | the return value is discarded. |
---|
183 | |
---|
184 | AVALUES is a vector of void* that point to the memory locations |
---|
185 | holding the argument values for a call. |
---|
186 | If NARGS is 0, this is ignored. |
---|
187 | |
---|
188 | |
---|
189 | If you are expecting a return value from FN it will have been stored |
---|
190 | at RVALUE. |
---|
191 | |
---|
192 | |
---|
193 | |
---|
194 | An Example |
---|
195 | ---------- |
---|
196 | |
---|
197 | Here is a trivial example that calls puts() a few times. |
---|
198 | |
---|
199 | #include <stdio.h> |
---|
200 | #include <ffi.h> |
---|
201 | |
---|
202 | int main() |
---|
203 | { |
---|
204 | ffi_cif cif; |
---|
205 | ffi_type *args[1]; |
---|
206 | void *values[1]; |
---|
207 | char *s; |
---|
208 | int rc; |
---|
209 | |
---|
210 | /* Initialize the argument info vectors */ |
---|
211 | args[0] = &ffi_type_uint; |
---|
212 | values[0] = &s; |
---|
213 | |
---|
214 | /* Initialize the cif */ |
---|
215 | if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, |
---|
216 | &ffi_type_uint, args) == FFI_OK) |
---|
217 | { |
---|
218 | s = "Hello World!"; |
---|
219 | ffi_call(&cif, puts, &rc, values); |
---|
220 | /* rc now holds the result of the call to puts */ |
---|
221 | |
---|
222 | /* values holds a pointer to the function's arg, so to |
---|
223 | call puts() again all we need to do is change the |
---|
224 | value of s */ |
---|
225 | s = "This is cool!"; |
---|
226 | ffi_call(&cif, puts, &rc, values); |
---|
227 | } |
---|
228 | |
---|
229 | return 0; |
---|
230 | } |
---|
231 | |
---|
232 | |
---|
233 | |
---|
234 | Aggregate Types |
---|
235 | --------------- |
---|
236 | |
---|
237 | Although libffi has no special support for unions or bit-fields, it is |
---|
238 | perfectly happy passing structures back and forth. You must first |
---|
239 | describe the structure to libffi by creating a new ffi_type object |
---|
240 | for it. Here is the definition of ffi_type: |
---|
241 | |
---|
242 | typedef struct _ffi_type |
---|
243 | { |
---|
244 | unsigned size; |
---|
245 | short alignment; |
---|
246 | short type; |
---|
247 | struct _ffi_type **elements; |
---|
248 | } ffi_type; |
---|
249 | |
---|
250 | All structures must have type set to FFI_TYPE_STRUCT. You may set |
---|
251 | size and alignment to 0. These will be calculated and reset to the |
---|
252 | appropriate values by ffi_prep_cif(). |
---|
253 | |
---|
254 | elements is a NULL terminated array of pointers to ffi_type objects |
---|
255 | that describe the type of the structure elements. These may, in turn, |
---|
256 | be structure elements. |
---|
257 | |
---|
258 | The following example initializes a ffi_type object representing the |
---|
259 | tm struct from Linux's time.h: |
---|
260 | |
---|
261 | struct tm { |
---|
262 | int tm_sec; |
---|
263 | int tm_min; |
---|
264 | int tm_hour; |
---|
265 | int tm_mday; |
---|
266 | int tm_mon; |
---|
267 | int tm_year; |
---|
268 | int tm_wday; |
---|
269 | int tm_yday; |
---|
270 | int tm_isdst; |
---|
271 | /* Those are for future use. */ |
---|
272 | long int __tm_gmtoff__; |
---|
273 | __const char *__tm_zone__; |
---|
274 | }; |
---|
275 | |
---|
276 | { |
---|
277 | ffi_type tm_type; |
---|
278 | ffi_type *tm_type_elements[12]; |
---|
279 | int i; |
---|
280 | |
---|
281 | tm_type.size = tm_type.alignment = 0; |
---|
282 | tm_type.elements = &tm_type_elements; |
---|
283 | |
---|
284 | for (i = 0; i < 9; i++) |
---|
285 | tm_type_elements[i] = &ffi_type_sint; |
---|
286 | |
---|
287 | tm_type_elements[9] = &ffi_type_slong; |
---|
288 | tm_type_elements[10] = &ffi_type_pointer; |
---|
289 | tm_type_elements[11] = NULL; |
---|
290 | |
---|
291 | /* tm_type can now be used to represent tm argument types and |
---|
292 | return types for ffi_prep_cif() */ |
---|
293 | } |
---|
294 | |
---|
295 | |
---|
296 | |
---|
297 | Platform Specific Notes |
---|
298 | ======================= |
---|
299 | |
---|
300 | Intel x86 |
---|
301 | --------- |
---|
302 | |
---|
303 | There are no known problems with the x86 port. |
---|
304 | |
---|
305 | Sun Sparc - SunOS 4.1.3 & Solaris 2.x |
---|
306 | ------------------------------------- |
---|
307 | |
---|
308 | There's a bug in the structure passing code for sparc processors. |
---|
309 | Struct arguments that are passed in value actually end up being passed |
---|
310 | by reference. This will be fixed Real Soon Now. |
---|
311 | |
---|
312 | "long long" values are not supported yet. |
---|
313 | |
---|
314 | You must use GNU Make to build libffi on Sun platforms. |
---|
315 | |
---|
316 | MIPS - Irix 5.3 & 6.x |
---|
317 | --------------------- |
---|
318 | |
---|
319 | Irix 6.2 and better supports three different calling conventions: o32, |
---|
320 | n32 and n64. Currently, libffi only supports both o32 and n32 under |
---|
321 | Irix 6.x, but only o32 under Irix 5.3. Libffi will automatically be |
---|
322 | configured for whichever calling convention it was built for. |
---|
323 | |
---|
324 | By default, the configure script will try to build libffi with the GNU |
---|
325 | development tools. To build libffi with the SGI development tools, set |
---|
326 | the environment variable CC to either "cc -32" or "cc -n32" before |
---|
327 | running configure under Irix 6.x (depending on whether you want an o32 |
---|
328 | or n32 library), or just "cc" for Irix 5.3. |
---|
329 | |
---|
330 | With the n32 calling convention, when returning structures smaller |
---|
331 | than 16 bytes, be sure to provide an RVALUE that is 8 byte aligned. |
---|
332 | Here's one way of forcing this: |
---|
333 | |
---|
334 | double struct_storage[2]; |
---|
335 | my_small_struct *s = (my_small_struct *) struct_storage; |
---|
336 | /* Use s for RVALUE */ |
---|
337 | |
---|
338 | If you don't do this you are liable to get spurious bus errors. |
---|
339 | |
---|
340 | "long long" values are not supported yet. |
---|
341 | |
---|
342 | You must use GNU Make to build libffi on SGI platforms. |
---|
343 | |
---|
344 | ARM - System V ABI |
---|
345 | ------------------ |
---|
346 | |
---|
347 | The ARM port was performed on a NetWinder running ARM Linux ELF |
---|
348 | (2.0.31) and gcc 2.8.1. |
---|
349 | |
---|
350 | |
---|
351 | |
---|
352 | PowerPC System V ABI |
---|
353 | -------------------- |
---|
354 | |
---|
355 | There are two `System V ABI's which libffi implements for PowerPC. |
---|
356 | They differ only in how small structures are returned from functions. |
---|
357 | |
---|
358 | In the FFI_SYSV version, structures that are 8 bytes or smaller are |
---|
359 | returned in registers. This is what GCC does when it is configured |
---|
360 | for solaris, and is what the System V ABI I have (dated September |
---|
361 | 1995) says. |
---|
362 | |
---|
363 | In the FFI_GCC_SYSV version, all structures are returned the same way: |
---|
364 | by passing a pointer as the first argument to the function. This is |
---|
365 | what GCC does when it is configured for linux or a generic sysv |
---|
366 | target. |
---|
367 | |
---|
368 | EGCS 1.0.1 (and probably other versions of EGCS/GCC) also has a |
---|
369 | inconsistency with the SysV ABI: When a procedure is called with many |
---|
370 | floating-point arguments, some of them get put on the stack. They are |
---|
371 | all supposed to be stored in double-precision format, even if they are |
---|
372 | only single-precision, but EGCS stores single-precision arguments as |
---|
373 | single-precision anyway. This causes one test to fail (the `many |
---|
374 | arguments' test). |
---|
375 | |
---|
376 | |
---|
377 | What's With The Crazy Comments? |
---|
378 | =============================== |
---|
379 | |
---|
380 | You might notice a number of cryptic comments in the code, delimited |
---|
381 | by /*@ and @*/. These are annotations read by the program LCLint, a |
---|
382 | tool for statically checking C programs. You can read all about it at |
---|
383 | <http://larch-www.lcs.mit.edu:8001/larch/lclint/index.html>. |
---|
384 | |
---|
385 | |
---|
386 | History |
---|
387 | ======= |
---|
388 | |
---|
389 | 1.20 Oct-5-98 |
---|
390 | Raffaele Sena produces ARM port. |
---|
391 | |
---|
392 | 1.19 Oct-5-98 |
---|
393 | Fixed x86 long double and long long return support. |
---|
394 | m68k bug fixes from Andreas Schwab. |
---|
395 | Patch for DU assembler compatibility for the Alpha from Richard |
---|
396 | Henderson. |
---|
397 | |
---|
398 | 1.18 Apr-17-98 |
---|
399 | Bug fixes and MIPS configuration changes. |
---|
400 | |
---|
401 | 1.17 Feb-24-98 |
---|
402 | Bug fixes and m68k port from Andreas Schwab. PowerPC port from |
---|
403 | Geoffrey Keating. Various bug x86, Sparc and MIPS bug fixes. |
---|
404 | |
---|
405 | 1.16 Feb-11-98 |
---|
406 | Richard Henderson produces Alpha port. |
---|
407 | |
---|
408 | 1.15 Dec-4-97 |
---|
409 | Fixed an n32 ABI bug. New libtool, auto* support. |
---|
410 | |
---|
411 | 1.14 May-13-97 |
---|
412 | libtool is now used to generate shared and static libraries. |
---|
413 | Fixed a minor portability problem reported by Russ McManus |
---|
414 | <mcmanr@eq.gs.com>. |
---|
415 | |
---|
416 | 1.13 Dec-2-96 |
---|
417 | Added --enable-purify-safety to keep Purify from complaining |
---|
418 | about certain low level code. |
---|
419 | Sparc fix for calling functions with < 6 args. |
---|
420 | Linux x86 a.out fix. |
---|
421 | |
---|
422 | 1.12 Nov-22-96 |
---|
423 | Added missing ffi_type_void, needed for supporting void return |
---|
424 | types. Fixed test case for non MIPS machines. Cygnus Support |
---|
425 | is now Cygnus Solutions. |
---|
426 | |
---|
427 | 1.11 Oct-30-96 |
---|
428 | Added notes about GNU make. |
---|
429 | |
---|
430 | 1.10 Oct-29-96 |
---|
431 | Added configuration fix for non GNU compilers. |
---|
432 | |
---|
433 | 1.09 Oct-29-96 |
---|
434 | Added --enable-debug configure switch. Clean-ups based on LCLint |
---|
435 | feedback. ffi_mips.h is always installed. Many configuration |
---|
436 | fixes. Fixed ffitest.c for sparc builds. |
---|
437 | |
---|
438 | 1.08 Oct-15-96 |
---|
439 | Fixed n32 problem. Many clean-ups. |
---|
440 | |
---|
441 | 1.07 Oct-14-96 |
---|
442 | Gordon Irlam rewrites v8.S again. Bug fixes. |
---|
443 | |
---|
444 | 1.06 Oct-14-96 |
---|
445 | Gordon Irlam improved the sparc port. |
---|
446 | |
---|
447 | 1.05 Oct-14-96 |
---|
448 | Interface changes based on feedback. |
---|
449 | |
---|
450 | 1.04 Oct-11-96 |
---|
451 | Sparc port complete (modulo struct passing bug). |
---|
452 | |
---|
453 | 1.03 Oct-10-96 |
---|
454 | Passing struct args, and returning struct values works for |
---|
455 | all architectures/calling conventions. Expanded tests. |
---|
456 | |
---|
457 | 1.02 Oct-9-96 |
---|
458 | Added SGI n32 support. Fixed bugs in both o32 and Linux support. |
---|
459 | Added "make test". |
---|
460 | |
---|
461 | 1.01 Oct-8-96 |
---|
462 | Fixed float passing bug in mips version. Restructured some |
---|
463 | of the code. Builds cleanly with SGI tools. |
---|
464 | |
---|
465 | 1.00 Oct-7-96 |
---|
466 | First release. No public announcement. |
---|
467 | |
---|
468 | |
---|
469 | Authors & Credits |
---|
470 | ================= |
---|
471 | |
---|
472 | libffi was written by Anthony Green <green@cygnus.com>. |
---|
473 | |
---|
474 | Portions of libffi were derived from Gianni Mariani's free gencall |
---|
475 | library for Silicon Graphics machines. |
---|
476 | |
---|
477 | The closure mechanism was designed and implemented by Kresten Krab |
---|
478 | Thorup. |
---|
479 | |
---|
480 | The Sparc port was derived from code contributed by the fine folks at |
---|
481 | Visible Decisions Inc <http://www.vdi.com>. Further enhancements were |
---|
482 | made by Gordon Irlam at Cygnus Solutions <http://www.cygnus.com>. |
---|
483 | |
---|
484 | The Alpha port was written by Richard Henderson at Cygnus Solutions. |
---|
485 | |
---|
486 | Andreas Schwab ported libffi to m68k Linux and provided a number of |
---|
487 | bug fixes. |
---|
488 | |
---|
489 | Geoffrey Keating ported libffi to the PowerPC. |
---|
490 | |
---|
491 | Raffaele Sena ported libffi to the ARM. |
---|
492 | |
---|
493 | Jesper Skov and Andrew Haley both did more than their fair share of |
---|
494 | stepping through the code and tracking down bugs. |
---|
495 | |
---|
496 | Thanks also to Tom Tromey for bug fixes and configuration help. |
---|
497 | |
---|
498 | Thanks to Jim Blandy, who provided some useful feedback on the libffi |
---|
499 | interface. |
---|
500 | |
---|
501 | If you have a problem, or have found a bug, please send a note to |
---|
502 | green@cygnus.com. |
---|