From edfdfd2e85b8d01d2455934f1d7f4d7eb2f3cf1c Mon Sep 17 00:00:00 2001 From: Anthony Green Date: Wed, 13 Jan 2010 02:56:19 -0500 Subject: [PATCH] Add closure example doc --- .pc/applied-patches | 1 + .pc/closure-api-example-doc/.timestamp | 0 .pc/closure-api-example-doc/ChangeLog.libffi | 580 +++++++++++++++++++ .pc/closure-api-example-doc/doc/libffi.info | 533 +++++++++++++++++ .pc/closure-api-example-doc/doc/libffi.texi | 541 +++++++++++++++++ ChangeLog.libffi | 5 + doc/libffi.info | 90 ++- doc/libffi.texi | 63 +- patches/closure-api-example-doc | 247 ++++++++ patches/series | 1 + 10 files changed, 2042 insertions(+), 19 deletions(-) create mode 100644 .pc/closure-api-example-doc/.timestamp create mode 100644 .pc/closure-api-example-doc/ChangeLog.libffi create mode 100644 .pc/closure-api-example-doc/doc/libffi.info create mode 100644 .pc/closure-api-example-doc/doc/libffi.texi create mode 100644 patches/closure-api-example-doc diff --git a/.pc/applied-patches b/.pc/applied-patches index e8c461fd..2c872f9e 100644 --- a/.pc/applied-patches +++ b/.pc/applied-patches @@ -1 +1,2 @@ stand-alone +closure-api-example-doc diff --git a/.pc/closure-api-example-doc/.timestamp b/.pc/closure-api-example-doc/.timestamp new file mode 100644 index 00000000..e69de29b diff --git a/.pc/closure-api-example-doc/ChangeLog.libffi b/.pc/closure-api-example-doc/ChangeLog.libffi new file mode 100644 index 00000000..3a4a137b --- /dev/null +++ b/.pc/closure-api-example-doc/ChangeLog.libffi @@ -0,0 +1,580 @@ +2009-12-25 Samuli Suominen + + * configure.ac: Undefine _AC_ARG_VAR_PRECIOUS for autoconf 2.64. + * configure: Rebuilt. + * fficonfig.h.in: Rebuilt. + +2009-06-16 Andrew Haley + + * testsuite/libffi.call/cls_align_sint64.c, + testsuite/libffi.call/cls_align_uint64.c, + testsuite/libffi.call/cls_longdouble_va.c, + testsuite/libffi.call/cls_ulonglong.c, + testsuite/libffi.call/return_ll1.c, + testsuite/libffi.call/stret_medium2.c: Fix printf format + specifiers. + * testsuite/libffi.call/huge_struct.c: Ad x86 XFAILs. + * testsuite/libffi.call/float2.c: Fix dg-excess-errors. + * testsuite/libffi.call/ffitest.h, + testsuite/libffi.special/ffitestcxx.h (PRIdLL, PRIuLL): Define. + +2009-06-12 Andrew Haley + + * testsuite/libffi.call/cls_align_sint64.c, + testsuite/libffi.call/cls_align_uint64.c, + testsuite/libffi.call/cls_ulonglong.c, + testsuite/libffi.call/return_ll1.c, + testsuite/libffi.call/stret_medium2.c: Fix printf format + specifiers. + testsuite/libffi.special/unwindtest.cc: include stdint.h. + +2009-06-11 Timothy Wall + + * Makefile.am, + configure.ac, + include/ffi.h.in, + include/ffi_common.h, + src/closures.c, + src/dlmalloc.c, + src/x86/ffi.c, + src/x86/ffitarget.h, + src/x86/win64.S (new), + README: Added win64 support (mingw or MSVC) + * Makefile.in, + include/Makefile.in, + man/Makefile.in, + testsuite/Makefile.in, + configure, + aclocal.m4: Regenerated + * ltcf-c.sh: properly escape cygwin/w32 path + * man/ffi_call.3: Clarify size requirements for return value. + * src/x86/ffi64.c: Fix filename in comment. + * src/x86/win32.S: Remove unused extern. + + * testsuite/libffi.call/closure_fn0.c, + testsuite/libffi.call/closure_fn1.c, + testsuite/libffi.call/closure_fn2.c, + testsuite/libffi.call/closure_fn3.c, + testsuite/libffi.call/closure_fn4.c, + testsuite/libffi.call/closure_fn5.c, + testsuite/libffi.call/closure_fn6.c, + testsuite/libffi.call/closure_stdcall.c, + testsuite/libffi.call/cls_12byte.c, + testsuite/libffi.call/cls_16byte.c, + testsuite/libffi.call/cls_18byte.c, + testsuite/libffi.call/cls_19byte.c, + testsuite/libffi.call/cls_1_1byte.c, + testsuite/libffi.call/cls_20byte.c, + testsuite/libffi.call/cls_20byte1.c, + testsuite/libffi.call/cls_24byte.c, + testsuite/libffi.call/cls_2byte.c, + testsuite/libffi.call/cls_3_1byte.c, + testsuite/libffi.call/cls_3byte1.c, + testsuite/libffi.call/cls_3byte2.c, + testsuite/libffi.call/cls_4_1byte.c, + testsuite/libffi.call/cls_4byte.c, + testsuite/libffi.call/cls_5_1_byte.c, + testsuite/libffi.call/cls_5byte.c, + testsuite/libffi.call/cls_64byte.c, + testsuite/libffi.call/cls_6_1_byte.c, + testsuite/libffi.call/cls_6byte.c, + testsuite/libffi.call/cls_7_1_byte.c, + testsuite/libffi.call/cls_7byte.c, + testsuite/libffi.call/cls_8byte.c, + testsuite/libffi.call/cls_9byte1.c, + testsuite/libffi.call/cls_9byte2.c, + testsuite/libffi.call/cls_align_double.c, + testsuite/libffi.call/cls_align_float.c, + testsuite/libffi.call/cls_align_longdouble.c, + testsuite/libffi.call/cls_align_longdouble_split.c, + testsuite/libffi.call/cls_align_longdouble_split2.c, + testsuite/libffi.call/cls_align_pointer.c, + testsuite/libffi.call/cls_align_sint16.c, + testsuite/libffi.call/cls_align_sint32.c, + testsuite/libffi.call/cls_align_sint64.c, + testsuite/libffi.call/cls_align_uint16.c, + testsuite/libffi.call/cls_align_uint32.c, + testsuite/libffi.call/cls_align_uint64.c, + testsuite/libffi.call/cls_dbls_struct.c, + testsuite/libffi.call/cls_double.c, + testsuite/libffi.call/cls_double_va.c, + testsuite/libffi.call/cls_float.c, + testsuite/libffi.call/cls_longdouble.c, + testsuite/libffi.call/cls_longdouble_va.c, + testsuite/libffi.call/cls_multi_schar.c, + testsuite/libffi.call/cls_multi_sshort.c, + testsuite/libffi.call/cls_multi_sshortchar.c, + testsuite/libffi.call/cls_multi_uchar.c, + testsuite/libffi.call/cls_multi_ushort.c, + testsuite/libffi.call/cls_multi_ushortchar.c, + testsuite/libffi.call/cls_pointer.c, + testsuite/libffi.call/cls_pointer_stack.c, + testsuite/libffi.call/cls_schar.c, + testsuite/libffi.call/cls_sint.c, + testsuite/libffi.call/cls_sshort.c, + testsuite/libffi.call/cls_uchar.c, + testsuite/libffi.call/cls_uint.c, + testsuite/libffi.call/cls_ulonglong.c, + testsuite/libffi.call/cls_ushort.c, + testsuite/libffi.call/err_bad_abi.c, + testsuite/libffi.call/err_bad_typedef.c, + testsuite/libffi.call/float2.c, + testsuite/libffi.call/huge_struct.c, + testsuite/libffi.call/nested_struct.c, + testsuite/libffi.call/nested_struct1.c, + testsuite/libffi.call/nested_struct10.c, + testsuite/libffi.call/nested_struct2.c, + testsuite/libffi.call/nested_struct3.c, + testsuite/libffi.call/nested_struct4.c, + testsuite/libffi.call/nested_struct5.c, + testsuite/libffi.call/nested_struct6.c, + testsuite/libffi.call/nested_struct7.c, + testsuite/libffi.call/nested_struct8.c, + testsuite/libffi.call/nested_struct9.c, + testsuite/libffi.call/problem1.c, + testsuite/libffi.call/return_ldl.c, + testsuite/libffi.call/return_ll1.c, + testsuite/libffi.call/stret_large.c, + testsuite/libffi.call/stret_large2.c, + testsuite/libffi.call/stret_medium.c, + testsuite/libffi.call/stret_medium2.c, + testsuite/libffi.special/unwindtest.cc: use ffi_closure_alloc instead + of checking for MMAP. Use intptr_t instead of long casts. + +2009-06-04 Andrew Haley + + * src/powerpc/ffitarget.h: Fix misapplied merge from gcc. + +2009-06-04 Andrew Haley + + * src/mips/o32.S, + src/mips/n32.S: Fix licence formatting. + +2009-06-04 Andrew Haley + + * src/x86/darwin.S: Fix licence formatting. + src/x86/win32.S: Likewise. + src/sh64/sysv.S: Likewise. + src/sh/sysv.S: Likewise. + +2009-06-04 Andrew Haley + + * src/sh64/ffi.c: Remove lint directives. Was missing from merge + of Andreas Tobler's patch from 2006-04-22. + +2009-06-04 Andrew Haley + + * src/sh/ffi.c: Apply missing hunk from Alexandre Oliva's patch of + 2007-03-07. + +2008-12-26 Timothy Wall + + * testsuite/libffi.call/cls_longdouble.c, + testsuite/libffi.call/cls_longdouble_va.c, + testsuite/libffi.call/cls_align_longdouble.c, + testsuite/libffi.call/cls_align_longdouble_split.c, + testsuite/libffi.call/cls_align_longdouble_split2.c: mark expected + failures on x86_64 cygwin/mingw. + +2008-12-22 Timothy Wall + + * testsuite/libffi.call/closure_fn0.c, + testsuite/libffi.call/closure_fn1.c, + testsuite/libffi.call/closure_fn2.c, + testsuite/libffi.call/closure_fn3.c, + testsuite/libffi.call/closure_fn4.c, + testsuite/libffi.call/closure_fn5.c, + testsuite/libffi.call/closure_fn6.c, + testsuite/libffi.call/closure_loc_fn0.c, + testsuite/libffi.call/closure_stdcall.c, + testsuite/libffi.call/cls_align_pointer.c, + testsuite/libffi.call/cls_pointer.c, + testsuite/libffi.call/cls_pointer_stack.c: use portable cast from + pointer to integer (intptr_t). + * testsuite/libffi.call/cls_longdouble.c: disable for win64. + +2008-12-19 Anthony Green + + * configure.ac: Bump version to 3.0.8. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + * libtool-version: Increment revision. + * README: Update for new release. + +2008-11-11 Anthony Green + + * configure.ac: Bump version to 3.0.7. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + * libtool-version: Increment revision. + * README: Update for new release. + +2008-08-25 Andreas Tobler + + * src/powerpc/ffitarget.h (ffi_abi): Add FFI_LINUX and + FFI_LINUX_SOFT_FLOAT to the POWERPC_FREEBSD enum. + Add note about flag bits used for FFI_SYSV_TYPE_SMALL_STRUCT. + Adjust copyright notice. + * src/powerpc/ffi.c: Add two new flags to indicate if we have one + register or two register to use for FFI_SYSV structs. + (ffi_prep_cif_machdep): Pass the right register flag introduced above. + (ffi_closure_helper_SYSV): Fix the return type for + FFI_SYSV_TYPE_SMALL_STRUCT. Comment. + Adjust copyright notice. + +2008-07-24 Anthony Green + + * testsuite/libffi.call/cls_dbls_struct.c, + testsuite/libffi.call/cls_double_va.c, + testsuite/libffi.call/cls_longdouble.c, + testsuite/libffi.call/cls_longdouble_va.c, + testsuite/libffi.call/cls_pointer.c, + testsuite/libffi.call/cls_pointer_stack.c, + testsuite/libffi.call/err_bad_abi.c: Clean up failures from + compiler warnings. + +2008-07-17 Anthony Green + + * configure.ac: Bump version to 3.0.6. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + * libtool-version: Increment revision. Add documentation. + * README: Update for new release. + +2008-07-16 Kaz Kojima + + * src/sh/ffi.c (ffi_prep_closure_loc): Turn INSN into an unsigned + int. + +2008-07-16 Kaz Kojima + + * src/sh/sysv.S: Add .note.GNU-stack on Linux. + * src/sh64/sysv.S: Likewise. + +2008-04-03 Anthony Green + + * libffi.pc.in (Libs): Add -L${libdir}. + * configure.ac: Bump version to 3.0.5. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + * libtool-version: Increment revision. + * README: Update for new release. + +2008-04-03 Anthony Green + Xerces Ranby + + * include/ffi.h.in: Wrap definition of target architecture to + protect from double definitions. + +2008-03-22 Moriyoshi Koizumi + + * src/x86/ffi.c (ffi_prep_closure_loc): Fix for bug revealed in + closure_loc_fn0.c. + * testsuite/libffi.call/closure_loc_fn0.c (closure_loc_test_fn0): + New test. + +2008-03-04 Anthony Green + Blake Chaffin + hos@tamanegi.org + + * testsuite/libffi.call/cls_align_longdouble_split2.c + testsuite/libffi.call/cls_align_longdouble_split.c + testsuite/libffi.call/cls_dbls_struct.c + testsuite/libffi.call/cls_double_va.c + testsuite/libffi.call/cls_longdouble.c + testsuite/libffi.call/cls_longdouble_va.c + testsuite/libffi.call/cls_pointer.c + testsuite/libffi.call/cls_pointer_stack.c + testsuite/libffi.call/err_bad_abi.c + testsuite/libffi.call/err_bad_typedef.c + testsuite/libffi.call/huge_struct.c + testsuite/libffi.call/stret_large2.c + testsuite/libffi.call/stret_large.c + testsuite/libffi.call/stret_medium2.c + testsuite/libffi.call/stret_medium.c: New tests from Apple. + +2008-02-26 Jakub Jelinek + Anthony Green + + * src/alpha/osf.S: Add .note.GNU-stack on Linux. + * src/s390/sysv.S: Likewise. + * src/powerpc/linux64.S: Likewise. + * src/powerpc/linux64_closure.S: Likewise. + * src/powerpc/ppc_closure.S: Likewise. + * src/powerpc/sysv.S: Likewise. + * src/x86/unix64.S: Likewise. + * src/x86/sysv.S: Likewise. + * src/sparc/v8.S: Likewise. + * src/sparc/v9.S: Likewise. + * src/m68k/sysv.S: Likewise. + * src/ia64/unix.S: Likewise. + * src/arm/sysv.S: Likewise. + +2008-02-26 Anthony Green + Thomas Heller + + * src/x86/ffi.c (ffi_closure_SYSV_inner): Change C++ comment to C + comment. + +2008-02-26 Anthony Green + Thomas Heller + + * include/ffi.h.in: Change void (*)() to void (*)(void). + +2008-02-26 Anthony Green + Thomas Heller + + * src/alpha/ffi.c: Change void (*)() to void (*)(void). + src/alpha/osf.S, src/arm/ffi.c, src/frv/ffi.c, src/ia64/ffi.c, + src/ia64/unix.S, src/java_raw_api.c, src/m32r/ffi.c, + src/mips/ffi.c, src/pa/ffi.c, src/pa/hpux32.S, src/pa/linux.S, + src/powerpc/ffi.c, src/powerpc/ffi_darwin.c, src/raw_api.c, + src/s390/ffi.c, src/sh/ffi.c, src/sh64/ffi.c, src/sparc/ffi.c, + src/x86/ffi.c, src/x86/unix64.S, src/x86/darwin64.S, + src/x86/ffi64.c: Ditto. + +2008-02-24 Anthony Green + + * configure.ac: Accept openbsd*, not just openbsd. + Bump version to 3.0.4. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + * libtool-version: Increment revision. + * README: Update for new release. + +2008-02-22 Anthony Green + + * README: Clean up list of tested platforms. + +2008-02-22 Anthony Green + + * configure.ac: Bump version to 3.0.3. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + * libtool-version: Increment revision. + * README: Update for new release. Clean up test docs. + +2008-02-22 Bjoern Koenig + Andreas Tobler + + * configure.ac: Add amd64-*-freebsd* target. + * configure: Regenerate. + +2008-02-22 Thomas Heller + + * configure.ac: Add x86 OpenBSD support. + * configure: Rebuilt. + +2008-02-21 Thomas Heller + + * README: Change "make test" to "make check". + +2008-02-21 Anthony Green + + * configure.ac: Bump version to 3.0.2. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + * libtool-version: Increment revision. + * README: Update for new release. + +2008-02-21 Björn König + + * src/x86/freebsd.S: New file. + * configure.ac: Add x86 FreeBSD support. + * Makefile.am: Ditto. + +2008-02-15 Anthony Green + + * configure.ac: Bump version to 3.0.1. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + * libtool-version: Increment revision. + * README: Update for new release. + +2008-02-15 David Daney + + * src/mips/ffi.c: Remove extra '>' from include directive. + (ffi_prep_closure_loc): Use clear_location instead of tramp. + +2008-02-15 Anthony Green + + * configure.ac: Bump version to 3.0.0. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + +2008-02-15 David Daney + + * src/mips/ffi.c (USE__BUILTIN___CLEAR_CACHE): + Define (conditionally), and use it to include cachectl.h. + (ffi_prep_closure_loc): Fix cache flushing. + * src/mips/ffitarget.h (_ABIN32, _ABI64, _ABIO32): Define. + +2008-02-15 Anthony Green + + * man/ffi_call.3, man/ffi_prep_cif.3, man/ffi.3: + Update dates and remove all references to ffi_prep_closure. + * configure.ac: Bump version to 2.99.9. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + +2008-02-15 Anthony Green + + * man/ffi_prep_closure.3: Delete. + * man/Makefile.am (EXTRA_DIST): Remove ffi_prep_closure.3. + (man_MANS): Ditto. + * man/Makefile.in: Rebuilt. + * configure.ac: Bump version to 2.99.8. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + +2008-02-14 Anthony Green + + * configure.ac: Bump version to 2.99.7. + * configure, doc/stamp-vti, doc/version.texi: Rebuilt. + * include/ffi.h.in LICENSE src/debug.c src/closures.c + src/ffitest.c src/s390/sysv.S src/s390/ffitarget.h + src/types.c src/m68k/ffitarget.h src/raw_api.c src/frv/ffi.c + src/frv/ffitarget.h src/sh/ffi.c src/sh/sysv.S + src/sh/ffitarget.h src/powerpc/ffitarget.h src/pa/ffi.c + src/pa/ffitarget.h src/pa/linux.S src/java_raw_api.c + src/cris/ffitarget.h src/x86/ffi.c src/x86/sysv.S + src/x86/unix64.S src/x86/win32.S src/x86/ffitarget.h + src/x86/ffi64.c src/x86/darwin.S src/ia64/ffi.c + src/ia64/ffitarget.h src/ia64/ia64_flags.h src/ia64/unix.S + src/sparc/ffi.c src/sparc/v9.S src/sparc/ffitarget.h + src/sparc/v8.S src/alpha/ffi.c src/alpha/ffitarget.h + src/alpha/osf.S src/sh64/ffi.c src/sh64/sysv.S + src/sh64/ffitarget.h src/mips/ffi.c src/mips/ffitarget.h + src/mips/n32.S src/mips/o32.S src/arm/ffi.c src/arm/sysv.S + src/arm/ffitarget.h src/prep_cif.c: Update license text. + +2008-02-14 Anthony Green + + * README: Update tested platforms. + * configure.ac: Bump version to 2.99.6. + * configure: Rebuilt. + +2008-02-14 Anthony Green + + * configure.ac: Bump version to 2.99.5. + * configure: Rebuilt. + * Makefile.am (EXTRA_DIST): Add darwin64.S + * Makefile.in: Rebuilt. + * testsuite/lib/libffi-dg.exp: Remove libstdc++ bits from GCC tree. + * LICENSE: Update WARRANTY. + +2008-02-14 Anthony Green + + * libffi.pc.in (libdir): Fix libdir definition. + * configure.ac: Bump version to 2.99.4. + * configure: Rebuilt. + +2008-02-14 Anthony Green + + * README: Update. + * libffi.info: New file. + * doc/stamp-vti: New file. + * configure.ac: Bump version to 2.99.3. + * configure: Rebuilt. + +2008-02-14 Anthony Green + + * Makefile.am (SUBDIRS): Add man dir. + * Makefile.in: Rebuilt. + * configure.ac: Create Makefile. + * configure: Rebuilt. + * man/ffi_call.3 man/ffi_prep_cif.3 man/ffi_prep_closure.3 + man/Makefile.am man/Makefile.in: New files. + +2008-02-14 Tom Tromey + + * aclocal.m4, Makefile.in, configure, fficonfig.h.in: Rebuilt. + * mdate-sh, texinfo.tex: New files. + * Makefile.am (info_TEXINFOS): New variable. + * doc/libffi.texi: New file. + * doc/version.texi: Likewise. + +2008-02-14 Anthony Green + + * Makefile.am (AM_CFLAGS): Don't compile with -D$(TARGET). + (lib_LTLIBRARIES): Define. + (toolexeclib_LIBRARIES): Undefine. + * Makefile.in: Rebuilt. + * configure.ac: Reset version to 2.99.1. + * configure.in: Rebuilt. + +2008-02-14 Anthony Green + + * libffi.pc.in: Use @PACKAGE_NAME@ and @PACKAGE_VERSION@. + * configure.ac: Reset version to 2.99.1. + * configure.in: Rebuilt. + * Makefile.am (EXTRA_DIST): Add ChangeLog.libffi. + * Makefile.in: Rebuilt. + * LICENSE: Update copyright notice. + +2008-02-14 Anthony Green + + * include/Makefile.am (nodist_includes_HEADERS): Define. Don't + distribute ffitarget.h or ffi.h from the build include dir. + * Makefile.in: Rebuilt. + +2008-02-14 Anthony Green + + * include/Makefile.am (includesdir): Install headers under libdir. + (pkgconfigdir): Define. Install libffi.pc. + * include/Makefile.in: Rebuilt. + * libffi.pc.in: Create. + * libtool-version: Increment CURRENT + * configure.ac: Add libffi.pc.in + * configure: Rebuilt. + +2008-02-03 Anthony Green + + * include/Makefile.am (includesdir): Fix header install with + DESTDIR. + * include/Makefile.in: Rebuilt. + +2008-02-03 Timothy Wall + + * src/x86/ffi.c (FFI_INIT_TRAMPOLINE_STDCALL): Calculate jump return + offset based on code pointer, not data pointer. + +2008-02-01 Anthony Green + + * include/Makefile.am: Fix header installs. + * Makefile.am: Ditto. + * include/Makefile.in: Rebuilt. + * Makefile.in: Ditto. + +2008-02-01 Anthony Green + + * src/x86/ffi.c (FFI_INIT_TRAMPOLINE_STDCALL, + FFI_INIT_TRAMPOLINE): Revert my broken changes to twall's last + patch. + +2008-01-31 Anthony Green + + * Makefile.am (EXTRA_DIST): Add missing files. + * testsuite/Makefile.am: Ditto. + * Makefile.in, testsuite/Makefile.in: Rebuilt. + +2008-01-31 Timothy Wall + + * testsuite/libffi.call/closure_stdcall.c: Add test for stdcall + closures. + * src/x86/ffitarget.h: Increase size of trampoline for stdcall + closures. + * src/x86/win32.S: Add assembly for stdcall closure. + * src/x86/ffi.c: Initialize stdcall closure trampoline. + +2008-01-30 H.J. Lu + + PR libffi/34612 + * src/x86/sysv.S (ffi_closure_SYSV): Pop 4 byte from stack when + returning struct. + + * testsuite/libffi.call/call.exp: Add "-O2 -fomit-frame-pointer" + tests. + +2008-01-30 Anthony Green + + * Makefile.am, include/Makefile.am: Move headers to + libffi_la_SOURCES for new automake. + * Makefile.in, include/Makefile.in: Rebuilt. + + * testsuite/lib/wrapper.exp: Copied from gcc tree to allow for + execution outside of gcc tree. + * testsuite/lib/target-libpath.exp: Ditto. + + * testsuite/lib/libffi-dg.exp: Many changes to allow for execution + outside of gcc tree. + diff --git a/.pc/closure-api-example-doc/doc/libffi.info b/.pc/closure-api-example-doc/doc/libffi.info new file mode 100644 index 00000000..7a8890e6 --- /dev/null +++ b/.pc/closure-api-example-doc/doc/libffi.info @@ -0,0 +1,533 @@ +This is ../libffi/doc/libffi.info, produced by makeinfo version 4.13 +from ../libffi/doc/libffi.texi. + +This manual is for Libffi, a portable foreign-function interface +library. + + Copyright (C) 2008 Red Hat, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2, or + (at your option) any later version. A copy of the license is + included in the section entitled "GNU General Public License". + + +INFO-DIR-SECTION Development +START-INFO-DIR-ENTRY +* libffi: (libffi). Portable foreign-function interface library. +END-INFO-DIR-ENTRY + + +File: libffi.info, Node: Top, Next: Introduction, Up: (dir) + +libffi +****** + +This manual is for Libffi, a portable foreign-function interface +library. + + Copyright (C) 2008 Red Hat, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as + published by the Free Software Foundation; either version 2, or + (at your option) any later version. A copy of the license is + included in the section entitled "GNU General Public License". + + +* Menu: + +* Introduction:: What is libffi? +* Using libffi:: How to use libffi. +* Missing Features:: Things libffi can't do. +* Index:: Index. + + +File: libffi.info, Node: Introduction, Next: Using libffi, Prev: Top, Up: Top + +1 What is libffi? +***************** + +Compilers for high level languages generate code that follow certain +conventions. These conventions are necessary, in part, for separate +compilation to work. One such convention is the "calling convention". +The calling convention is a set of assumptions made by the compiler +about where function arguments will be found on entry to a function. A +calling convention also specifies where the return value for a function +is found. The calling convention is also sometimes called the "ABI" or +"Application Binary Interface". + + Some programs may not know at the time of compilation what arguments +are to be passed to a function. For instance, an interpreter may be +told at run-time about the number and types of arguments used to call a +given function. `Libffi' can be used in such programs to provide a +bridge from the interpreter program to compiled code. + + The `libffi' library provides a portable, high level programming +interface to various calling conventions. This allows a programmer to +call any function specified by a call interface description at run time. + + FFI stands for Foreign Function Interface. A foreign function +interface is the popular name for the interface that allows code +written in one language to call code written in another language. The +`libffi' library really only provides the lowest, machine dependent +layer of a fully featured foreign function interface. A layer must +exist above `libffi' that handles type conversions for values passed +between the two languages. + + +File: libffi.info, Node: Using libffi, Next: Missing Features, Prev: Introduction, Up: Top + +2 Using libffi +************** + +* Menu: + +* The Basics:: The basic libffi API. +* Simple Example:: A simple example. +* Types:: libffi type descriptions. +* Multiple ABIs:: Different passing styles on one platform. +* The Closure API:: Writing a generic function. + + +File: libffi.info, Node: The Basics, Next: Simple Example, Up: Using libffi + +2.1 The Basics +============== + +`Libffi' assumes that you have a pointer to the function you wish to +call and that you know the number and types of arguments to pass it, as +well as the return type of the function. + + The first thing you must do is create an `ffi_cif' object that +matches the signature of the function you wish to call. This is a +separate step because it is common to make multiple calls using a +single `ffi_cif'. The "cif" in `ffi_cif' stands for Call InterFace. +To prepare a call interface object, use the function `ffi_prep_cif'. + + -- Function: ffi_status ffi_prep_cif (ffi_cif *CIF, ffi_abi ABI, + unsigned int NARGS, ffi_type *RTYPE, ffi_type **ARGTYPES) + This initializes CIF according to the given parameters. + + ABI is the ABI to use; normally `FFI_DEFAULT_ABI' is what you + want. *note Multiple ABIs:: for more information. + + NARGS is the number of arguments that this function accepts. + `libffi' does not yet handle varargs functions; see *note Missing + Features:: for more information. + + RTYPE is a pointer to an `ffi_type' structure that describes the + return type of the function. *Note Types::. + + ARGTYPES is a vector of `ffi_type' pointers. ARGTYPES must have + NARGS elements. If NARGS is 0, this argument is ignored. + + `ffi_prep_cif' returns a `libffi' status code, of type + `ffi_status'. This will be either `FFI_OK' if everything worked + properly; `FFI_BAD_TYPEDEF' if one of the `ffi_type' objects is + incorrect; or `FFI_BAD_ABI' if the ABI parameter is invalid. + + To call a function using an initialized `ffi_cif', use the +`ffi_call' function: + + -- Function: void ffi_call (ffi_cif *CIF, void *FN, void *RVALUE, void + **AVALUES) + This calls the function FN according to the description given in + CIF. CIF must have already been prepared using `ffi_prep_cif'. + + RVALUE is a pointer to a chunk of memory that will hold the result + of the function call. This must be large enough to hold the + result and must be suitably aligned; it is the caller's + responsibility to ensure this. If CIF declares that the function + returns `void' (using `ffi_type_void'), then RVALUE is ignored. + If RVALUE is `NULL', then the return value is discarded. + + AVALUES is a vector of `void *' pointers that point to the memory + locations holding the argument values for a call. If CIF declares + that the function has no arguments (i.e., NARGS was 0), then + AVALUES is ignored. + + +File: libffi.info, Node: Simple Example, Next: Types, Prev: The Basics, Up: Using libffi + +2.2 Simple Example +================== + +Here is a trivial example that calls `puts' a few times. + + #include + #include + + int main() + { + ffi_cif cif; + ffi_type *args[1]; + void *values[1]; + char *s; + int rc; + + /* Initialize the argument info vectors */ + args[0] = &ffi_type_pointer; + values[0] = &s; + + /* Initialize the cif */ + if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, + &ffi_type_uint, args) == FFI_OK) + { + s = "Hello World!"; + ffi_call(&cif, puts, &rc, values); + /* rc now holds the result of the call to puts */ + + /* values holds a pointer to the function's arg, so to + call puts() again all we need to do is change the + value of s */ + s = "This is cool!"; + ffi_call(&cif, puts, &rc, values); + } + + return 0; + } + + +File: libffi.info, Node: Types, Next: Multiple ABIs, Prev: Simple Example, Up: Using libffi + +2.3 Types +========= + +* Menu: + +* Primitive Types:: Built-in types. +* Structures:: Structure types. +* Type Example:: Structure type example. + + +File: libffi.info, Node: Primitive Types, Next: Structures, Up: Types + +2.3.1 Primitive Types +--------------------- + +`Libffi' provides a number of built-in type descriptors that can be +used to describe argument and return types: + +`ffi_type_void' + The type `void'. This cannot be used for argument types, only for + return values. + +`ffi_type_uint8' + An unsigned, 8-bit integer type. + +`ffi_type_sint8' + A signed, 8-bit integer type. + +`ffi_type_uint16' + An unsigned, 16-bit integer type. + +`ffi_type_sint16' + A signed, 16-bit integer type. + +`ffi_type_uint32' + An unsigned, 32-bit integer type. + +`ffi_type_sint32' + A signed, 32-bit integer type. + +`ffi_type_uint64' + An unsigned, 64-bit integer type. + +`ffi_type_sint64' + A signed, 64-bit integer type. + +`ffi_type_float' + The C `float' type. + +`ffi_type_double' + The C `double' type. + +`ffi_type_uchar' + The C `unsigned char' type. + +`ffi_type_schar' + The C `signed char' type. (Note that there is not an exact + equivalent to the C `char' type in `libffi'; ordinarily you should + either use `ffi_type_schar' or `ffi_type_uchar' depending on + whether `char' is signed.) + +`ffi_type_ushort' + The C `unsigned short' type. + +`ffi_type_sshort' + The C `short' type. + +`ffi_type_uint' + The C `unsigned int' type. + +`ffi_type_sint' + The C `int' type. + +`ffi_type_ulong' + The C `unsigned long' type. + +`ffi_type_slong' + The C `long' type. + +`ffi_type_longdouble' + On platforms that have a C `long double' type, this is defined. + On other platforms, it is not. + +`ffi_type_pointer' + A generic `void *' pointer. You should use this for all pointers, + regardless of their real type. + + Each of these is of type `ffi_type', so you must take the address +when passing to `ffi_prep_cif'. + + +File: libffi.info, Node: Structures, Next: Type Example, Prev: Primitive Types, Up: Types + +2.3.2 Structures +---------------- + +Although `libffi' has no special support for unions or bit-fields, it +is perfectly happy passing structures back and forth. You must first +describe the structure to `libffi' by creating a new `ffi_type' object +for it. + + -- ffi_type: + The `ffi_type' has the following members: + `size_t size' + This is set by `libffi'; you should initialize it to zero. + + `unsigned short alignment' + This is set by `libffi'; you should initialize it to zero. + + `unsigned short type' + For a structure, this should be set to `FFI_TYPE_STRUCT'. + + `ffi_type **elements' + This is a `NULL'-terminated array of pointers to `ffi_type' + objects. There is one element per field of the struct. + + +File: libffi.info, Node: Type Example, Prev: Structures, Up: Types + +2.3.3 Type Example +------------------ + +The following example initializes a `ffi_type' object representing the +`tm' struct from Linux's `time.h'. + + Here is how the struct is defined: + + struct tm { + int tm_sec; + int tm_min; + int tm_hour; + int tm_mday; + int tm_mon; + int tm_year; + int tm_wday; + int tm_yday; + int tm_isdst; + /* Those are for future use. */ + long int __tm_gmtoff__; + __const char *__tm_zone__; + }; + + Here is the corresponding code to describe this struct to `libffi': + + { + ffi_type tm_type; + ffi_type *tm_type_elements[12]; + int i; + + tm_type.size = tm_type.alignment = 0; + tm_type.elements = &tm_type_elements; + + for (i = 0; i < 9; i++) + tm_type_elements[i] = &ffi_type_sint; + + tm_type_elements[9] = &ffi_type_slong; + tm_type_elements[10] = &ffi_type_pointer; + tm_type_elements[11] = NULL; + + /* tm_type can now be used to represent tm argument types and + return types for ffi_prep_cif() */ + } + + +File: libffi.info, Node: Multiple ABIs, Next: The Closure API, Prev: Types, Up: Using libffi + +2.4 Multiple ABIs +================= + +A given platform may provide multiple different ABIs at once. For +instance, the x86 platform has both `stdcall' and `fastcall' functions. + + `libffi' provides some support for this. However, this is +necessarily platform-specific. + + +File: libffi.info, Node: The Closure API, Prev: Multiple ABIs, Up: Using libffi + +2.5 The Closure API +=================== + +`libffi' also provides a way to write a generic function - a function +that can accept and decode any combination of arguments. This can be +useful when writing an interpreter, or to provide wrappers for +arbitrary functions. + + This facility is called the "closure API". Closures are not +supported on all platforms; you can check the `FFI_CLOSURES' define to +determine whether they are supported on the current platform. + + Because closures work by assembling a tiny function at runtime, they +require special allocation on platforms that have a non-executable +heap. Memory management for closures is handled by a pair of functions: + + -- Function: void *ffi_closure_alloc (size_t SIZE, void **CODE) + Allocate a chunk of memory holding SIZE bytes. This returns a + pointer to the writable address, and sets *CODE to the + corresponding executable address. + + SIZE should be sufficient to hold a `ffi_closure' object. + + -- Function: void ffi_closure_free (void *WRITABLE) + Free memory allocated using `ffi_closure_alloc'. The argument is + the writable address that was returned. + + Once you have allocated the memory for a closure, you must construct +a `ffi_cif' describing the function call. Finally you can prepare the +closure function: + + -- Function: ffi_status ffi_prep_closure_loc (ffi_closure *CLOSURE, + ffi_cif *CIF, void (*FUN) (ffi_cif *CIF, void *RET, void + **ARGS, void *USER_DATA), void *USER_DATA, void *CODELOC) + Prepare a closure function. + + CLOSURE is the address of a `ffi_closure' object; this is the + writable address returned by `ffi_closure_alloc'. + + CIF is the `ffi_cif' describing the function parameters. + + USER_DATA is an arbitrary datum that is passed, uninterpreted, to + your closure function. + + CODELOC is the executable address returned by `ffi_closure_alloc'. + + FUN is the function which will be called when the closure is + invoked. It is called with the arguments: + CIF + The `ffi_cif' passed to `ffi_prep_closure_loc'. + + RET + A pointer to the memory used for the function's return value. + FUN must fill this, unless the function is declared as + returning `void'. + + ARGS + A vector of pointers to memory holding the arguments to the + function. + + USER_DATA + The same USER_DATA that was passed to `ffi_prep_closure_loc'. + + `ffi_prep_closure_loc' will return `FFI_OK' if everything went ok, + and something else on error. + + After calling `ffi_prep_closure_loc', you can cast CODELOC to the + appropriate pointer-to-function type. + + You may see old code referring to `ffi_prep_closure'. This function +is deprecated, as it cannot handle the need for separate writable and +executable addresses. + + +File: libffi.info, Node: Missing Features, Next: Index, Prev: Using libffi, Up: Top + +3 Missing Features +****************** + +`libffi' is missing a few features. We welcome patches to add support +for these. + + * There is no support for calling varargs functions. This may work + on some platforms, depending on how the ABI is defined, but it is + not reliable. + + * There is no support for bit fields in structures. + + * The closure API is + + * The "raw" API is undocumented. + + +File: libffi.info, Node: Index, Prev: Missing Features, Up: Top + +Index +***** + +[index] +* Menu: + +* : Structures. (line 12) +* ABI: Introduction. (line 13) +* Application Binary Interface: Introduction. (line 13) +* calling convention: Introduction. (line 13) +* cif: The Basics. (line 14) +* closure API: The Closure API. (line 13) +* closures: The Closure API. (line 13) +* FFI: Introduction. (line 31) +* ffi_call: The Basics. (line 41) +* ffi_closure_alloca: The Closure API. (line 19) +* ffi_closure_free: The Closure API. (line 26) +* FFI_CLOSURES: The Closure API. (line 13) +* ffi_prep_cif: The Basics. (line 16) +* ffi_prep_closure_loc: The Closure API. (line 34) +* ffi_status <1>: The Closure API. (line 37) +* ffi_status: The Basics. (line 18) +* ffi_type: Structures. (line 11) +* ffi_type_double: Primitive Types. (line 41) +* ffi_type_float: Primitive Types. (line 38) +* ffi_type_longdouble: Primitive Types. (line 71) +* ffi_type_pointer: Primitive Types. (line 75) +* ffi_type_schar: Primitive Types. (line 47) +* ffi_type_sint: Primitive Types. (line 62) +* ffi_type_sint16: Primitive Types. (line 23) +* ffi_type_sint32: Primitive Types. (line 29) +* ffi_type_sint64: Primitive Types. (line 35) +* ffi_type_sint8: Primitive Types. (line 17) +* ffi_type_slong: Primitive Types. (line 68) +* ffi_type_sshort: Primitive Types. (line 56) +* ffi_type_uchar: Primitive Types. (line 44) +* ffi_type_uint: Primitive Types. (line 59) +* ffi_type_uint16: Primitive Types. (line 20) +* ffi_type_uint32: Primitive Types. (line 26) +* ffi_type_uint64: Primitive Types. (line 32) +* ffi_type_uint8: Primitive Types. (line 14) +* ffi_type_ulong: Primitive Types. (line 65) +* ffi_type_ushort: Primitive Types. (line 53) +* ffi_type_void: Primitive Types. (line 10) +* Foreign Function Interface: Introduction. (line 31) +* void <1>: The Closure API. (line 20) +* void: The Basics. (line 43) + + + +Tag Table: +Node: Top700 +Node: Introduction1436 +Node: Using libffi3072 +Node: The Basics3507 +Node: Simple Example6114 +Node: Types7141 +Node: Primitive Types7424 +Node: Structures9244 +Node: Type Example10104 +Node: Multiple ABIs11327 +Node: The Closure API11698 +Node: Missing Features14618 +Node: Index15111 + +End Tag Table diff --git a/.pc/closure-api-example-doc/doc/libffi.texi b/.pc/closure-api-example-doc/doc/libffi.texi new file mode 100644 index 00000000..9a5060d5 --- /dev/null +++ b/.pc/closure-api-example-doc/doc/libffi.texi @@ -0,0 +1,541 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename libffi.info +@settitle libffi +@setchapternewpage off +@c %**end of header + +@c Merge the standard indexes into a single one. +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex ky cp +@syncodeindex pg cp +@syncodeindex tp cp + +@include version.texi + +@copying + +This manual is for Libffi, a portable foreign-function interface +library. + +Copyright @copyright{} 2008 Red Hat, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 2, or (at your option) any +later version. A copy of the license is included in the +section entitled ``GNU General Public License''. + +@end quotation +@end copying + +@dircategory Development +@direntry +* libffi: (libffi). Portable foreign-function interface library. +@end direntry + +@titlepage +@title Libffi +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + + +@ifnottex +@node Top +@top libffi + +@insertcopying + +@menu +* Introduction:: What is libffi? +* Using libffi:: How to use libffi. +* Missing Features:: Things libffi can't do. +* Index:: Index. +@end menu + +@end ifnottex + + +@node Introduction +@chapter What is libffi? + +Compilers for high level languages generate code that follow certain +conventions. These conventions are necessary, in part, for separate +compilation to work. One such convention is the @dfn{calling +convention}. The calling convention is a set of assumptions made by +the compiler about where function arguments will be found on entry to +a function. A calling convention also specifies where the return +value for a function is found. The calling convention is also +sometimes called the @dfn{ABI} or @dfn{Application Binary Interface}. +@cindex calling convention +@cindex ABI +@cindex Application Binary Interface + +Some programs may not know at the time of compilation what arguments +are to be passed to a function. For instance, an interpreter may be +told at run-time about the number and types of arguments used to call +a given function. @samp{Libffi} can be used in such programs to +provide a bridge from the interpreter program to compiled code. + +The @samp{libffi} library provides a portable, high level programming +interface to various calling conventions. This allows a programmer to +call any function specified by a call interface description at run +time. + +@acronym{FFI} stands for Foreign Function Interface. A foreign +function interface is the popular name for the interface that allows +code written in one language to call code written in another language. +The @samp{libffi} library really only provides the lowest, machine +dependent layer of a fully featured foreign function interface. A +layer must exist above @samp{libffi} that handles type conversions for +values passed between the two languages. +@cindex FFI +@cindex Foreign Function Interface + + +@node Using libffi +@chapter Using libffi + +@menu +* The Basics:: The basic libffi API. +* Simple Example:: A simple example. +* Types:: libffi type descriptions. +* Multiple ABIs:: Different passing styles on one platform. +* The Closure API:: Writing a generic function. +@end menu + + +@node The Basics +@section The Basics + +@samp{Libffi} assumes that you have a pointer to the function you wish +to call and that you know the number and types of arguments to pass +it, as well as the return type of the function. + +The first thing you must do is create an @code{ffi_cif} object that +matches the signature of the function you wish to call. This is a +separate step because it is common to make multiple calls using a +single @code{ffi_cif}. The @dfn{cif} in @code{ffi_cif} stands for +Call InterFace. To prepare a call interface object, use the function +@code{ffi_prep_cif}. +@cindex cif + +@findex ffi_prep_cif +@defun ffi_status ffi_prep_cif (ffi_cif *@var{cif}, ffi_abi @var{abi}, unsigned int @var{nargs}, ffi_type *@var{rtype}, ffi_type **@var{argtypes}) +This initializes @var{cif} according to the given parameters. + +@var{abi} is the ABI to use; normally @code{FFI_DEFAULT_ABI} is what +you want. @ref{Multiple ABIs} for more information. + +@var{nargs} is the number of arguments that this function accepts. +@samp{libffi} does not yet handle varargs functions; see @ref{Missing +Features} for more information. + +@var{rtype} is a pointer to an @code{ffi_type} structure that +describes the return type of the function. @xref{Types}. + +@var{argtypes} is a vector of @code{ffi_type} pointers. +@var{argtypes} must have @var{nargs} elements. If @var{nargs} is 0, +this argument is ignored. + +@code{ffi_prep_cif} returns a @code{libffi} status code, of type +@code{ffi_status}. This will be either @code{FFI_OK} if everything +worked properly; @code{FFI_BAD_TYPEDEF} if one of the @code{ffi_type} +objects is incorrect; or @code{FFI_BAD_ABI} if the @var{abi} parameter +is invalid. +@end defun + + +To call a function using an initialized @code{ffi_cif}, use the +@code{ffi_call} function: + +@findex ffi_call +@defun void ffi_call (ffi_cif *@var{cif}, void *@var{fn}, void *@var{rvalue}, void **@var{avalues}) +This calls the function @var{fn} according to the description given in +@var{cif}. @var{cif} must have already been prepared using +@code{ffi_prep_cif}. + +@var{rvalue} is a pointer to a chunk of memory that will hold the +result of the function call. This must be large enough to hold the +result and must be suitably aligned; it is the caller's responsibility +to ensure this. If @var{cif} declares that the function returns +@code{void} (using @code{ffi_type_void}), then @var{rvalue} is +ignored. If @var{rvalue} is @samp{NULL}, then the return value is +discarded. + +@var{avalues} is a vector of @code{void *} pointers that point to the +memory locations holding the argument values for a call. If @var{cif} +declares that the function has no arguments (i.e., @var{nargs} was 0), +then @var{avalues} is ignored. +@end defun + + +@node Simple Example +@section Simple Example + +Here is a trivial example that calls @code{puts} a few times. + +@example +#include +#include + +int main() +@{ + ffi_cif cif; + ffi_type *args[1]; + void *values[1]; + char *s; + int rc; + + /* Initialize the argument info vectors */ + args[0] = &ffi_type_pointer; + values[0] = &s; + + /* Initialize the cif */ + if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, + &ffi_type_uint, args) == FFI_OK) + @{ + s = "Hello World!"; + ffi_call(&cif, puts, &rc, values); + /* rc now holds the result of the call to puts */ + + /* values holds a pointer to the function's arg, so to + call puts() again all we need to do is change the + value of s */ + s = "This is cool!"; + ffi_call(&cif, puts, &rc, values); + @} + + return 0; +@} +@end example + + +@node Types +@section Types + +@menu +* Primitive Types:: Built-in types. +* Structures:: Structure types. +* Type Example:: Structure type example. +@end menu + +@node Primitive Types +@subsection Primitive Types + +@code{Libffi} provides a number of built-in type descriptors that can +be used to describe argument and return types: + +@table @code +@item ffi_type_void +@tindex ffi_type_void +The type @code{void}. This cannot be used for argument types, only +for return values. + +@item ffi_type_uint8 +@tindex ffi_type_uint8 +An unsigned, 8-bit integer type. + +@item ffi_type_sint8 +@tindex ffi_type_sint8 +A signed, 8-bit integer type. + +@item ffi_type_uint16 +@tindex ffi_type_uint16 +An unsigned, 16-bit integer type. + +@item ffi_type_sint16 +@tindex ffi_type_sint16 +A signed, 16-bit integer type. + +@item ffi_type_uint32 +@tindex ffi_type_uint32 +An unsigned, 32-bit integer type. + +@item ffi_type_sint32 +@tindex ffi_type_sint32 +A signed, 32-bit integer type. + +@item ffi_type_uint64 +@tindex ffi_type_uint64 +An unsigned, 64-bit integer type. + +@item ffi_type_sint64 +@tindex ffi_type_sint64 +A signed, 64-bit integer type. + +@item ffi_type_float +@tindex ffi_type_float +The C @code{float} type. + +@item ffi_type_double +@tindex ffi_type_double +The C @code{double} type. + +@item ffi_type_uchar +@tindex ffi_type_uchar +The C @code{unsigned char} type. + +@item ffi_type_schar +@tindex ffi_type_schar +The C @code{signed char} type. (Note that there is not an exact +equivalent to the C @code{char} type in @code{libffi}; ordinarily you +should either use @code{ffi_type_schar} or @code{ffi_type_uchar} +depending on whether @code{char} is signed.) + +@item ffi_type_ushort +@tindex ffi_type_ushort +The C @code{unsigned short} type. + +@item ffi_type_sshort +@tindex ffi_type_sshort +The C @code{short} type. + +@item ffi_type_uint +@tindex ffi_type_uint +The C @code{unsigned int} type. + +@item ffi_type_sint +@tindex ffi_type_sint +The C @code{int} type. + +@item ffi_type_ulong +@tindex ffi_type_ulong +The C @code{unsigned long} type. + +@item ffi_type_slong +@tindex ffi_type_slong +The C @code{long} type. + +@item ffi_type_longdouble +@tindex ffi_type_longdouble +On platforms that have a C @code{long double} type, this is defined. +On other platforms, it is not. + +@item ffi_type_pointer +@tindex ffi_type_pointer +A generic @code{void *} pointer. You should use this for all +pointers, regardless of their real type. +@end table + +Each of these is of type @code{ffi_type}, so you must take the address +when passing to @code{ffi_prep_cif}. + + +@node Structures +@subsection Structures + +Although @samp{libffi} has no special support for unions or +bit-fields, it is perfectly happy passing structures back and forth. +You must first describe the structure to @samp{libffi} by creating a +new @code{ffi_type} object for it. + +@tindex ffi_type +@deftp ffi_type +The @code{ffi_type} has the following members: +@table @code +@item size_t size +This is set by @code{libffi}; you should initialize it to zero. + +@item unsigned short alignment +This is set by @code{libffi}; you should initialize it to zero. + +@item unsigned short type +For a structure, this should be set to @code{FFI_TYPE_STRUCT}. + +@item ffi_type **elements +This is a @samp{NULL}-terminated array of pointers to @code{ffi_type} +objects. There is one element per field of the struct. +@end table +@end deftp + + +@node Type Example +@subsection Type Example + +The following example initializes a @code{ffi_type} object +representing the @code{tm} struct from Linux's @file{time.h}. + +Here is how the struct is defined: + +@example +struct tm @{ + int tm_sec; + int tm_min; + int tm_hour; + int tm_mday; + int tm_mon; + int tm_year; + int tm_wday; + int tm_yday; + int tm_isdst; + /* Those are for future use. */ + long int __tm_gmtoff__; + __const char *__tm_zone__; +@}; +@end example + +Here is the corresponding code to describe this struct to +@code{libffi}: + +@example + @{ + ffi_type tm_type; + ffi_type *tm_type_elements[12]; + int i; + + tm_type.size = tm_type.alignment = 0; + tm_type.elements = &tm_type_elements; + + for (i = 0; i < 9; i++) + tm_type_elements[i] = &ffi_type_sint; + + tm_type_elements[9] = &ffi_type_slong; + tm_type_elements[10] = &ffi_type_pointer; + tm_type_elements[11] = NULL; + + /* tm_type can now be used to represent tm argument types and + return types for ffi_prep_cif() */ + @} +@end example + + +@node Multiple ABIs +@section Multiple ABIs + +A given platform may provide multiple different ABIs at once. For +instance, the x86 platform has both @samp{stdcall} and @samp{fastcall} +functions. + +@code{libffi} provides some support for this. However, this is +necessarily platform-specific. + +@c FIXME: document the platforms + +@node The Closure API +@section The Closure API + +@code{libffi} also provides a way to write a generic function -- a +function that can accept and decode any combination of arguments. +This can be useful when writing an interpreter, or to provide wrappers +for arbitrary functions. + +This facility is called the @dfn{closure API}. Closures are not +supported on all platforms; you can check the @code{FFI_CLOSURES} +define to determine whether they are supported on the current +platform. +@cindex closures +@cindex closure API +@findex FFI_CLOSURES + +Because closures work by assembling a tiny function at runtime, they +require special allocation on platforms that have a non-executable +heap. Memory management for closures is handled by a pair of +functions: + +@findex ffi_closure_alloca +@defun void *ffi_closure_alloc (size_t @var{size}, void **@var{code}) +Allocate a chunk of memory holding @var{size} bytes. This returns a +pointer to the writable address, and sets *@var{code} to the +corresponding executable address. + +@var{size} should be sufficient to hold a @code{ffi_closure} object. +@end defun + +@findex ffi_closure_free +@defun void ffi_closure_free (void *@var{writable}) +Free memory allocated using @code{ffi_closure_alloc}. The argument is +the writable address that was returned. +@end defun + + +Once you have allocated the memory for a closure, you must construct a +@code{ffi_cif} describing the function call. Finally you can prepare +the closure function: + +@findex ffi_prep_closure_loc +@defun ffi_status ffi_prep_closure_loc (ffi_closure *@var{closure}, ffi_cif *@var{cif}, void (*@var{fun}) (ffi_cif *@var{cif}, void *@var{ret}, void **@var{args}, void *@var{user_data}), void *@var{user_data}, void *@var{codeloc}) +Prepare a closure function. + +@var{closure} is the address of a @code{ffi_closure} object; this is +the writable address returned by @code{ffi_closure_alloc}. + +@var{cif} is the @code{ffi_cif} describing the function parameters. + +@var{user_data} is an arbitrary datum that is passed, uninterpreted, +to your closure function. + +@var{codeloc} is the executable address returned by +@code{ffi_closure_alloc}. + +@var{fun} is the function which will be called when the closure is +invoked. It is called with the arguments: +@table @var +@item cif +The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}. + +@item ret +A pointer to the memory used for the function's return value. +@var{fun} must fill this, unless the function is declared as returning +@code{void}. +@c FIXME: is this NULL for void-returning functions? + +@item args +A vector of pointers to memory holding the arguments to the function. + +@item user_data +The same @var{user_data} that was passed to +@code{ffi_prep_closure_loc}. +@end table + +@code{ffi_prep_closure_loc} will return @code{FFI_OK} if everything +went ok, and something else on error. +@c FIXME: what? + +After calling @code{ffi_prep_closure_loc}, you can cast @var{codeloc} +to the appropriate pointer-to-function type. +@end defun + +@c FIXME: example + +You may see old code referring to @code{ffi_prep_closure}. This +function is deprecated, as it cannot handle the need for separate +writable and executable addresses. + + +@node Missing Features +@chapter Missing Features + +@code{libffi} is missing a few features. We welcome patches to add +support for these. + +@itemize @bullet +@item +There is no support for calling varargs functions. This may work on +some platforms, depending on how the ABI is defined, but it is not +reliable. + +@item +There is no support for bit fields in structures. + +@item +The closure API is + +@item +The ``raw'' API is undocumented. +@c argument promotion? +@c unions? +@c anything else? +@end itemize + + +@node Index +@unnumbered Index + +@printindex cp + +@bye diff --git a/ChangeLog.libffi b/ChangeLog.libffi index 3a4a137b..71df1a5e 100644 --- a/ChangeLog.libffi +++ b/ChangeLog.libffi @@ -1,3 +1,8 @@ +2010-01-12 Conrad Irwin + + * doc/libffi.texi: Add closure example. + * doc/libffi.info: Rebuilt. + 2009-12-25 Samuli Suominen * configure.ac: Undefine _AC_ARG_VAR_PRECIOUS for autoconf 2.64. diff --git a/doc/libffi.info b/doc/libffi.info index 7a8890e6..896a5ec0 100644 --- a/doc/libffi.info +++ b/doc/libffi.info @@ -4,7 +4,7 @@ from ../libffi/doc/libffi.texi. This manual is for Libffi, a portable foreign-function interface library. - Copyright (C) 2008 Red Hat, Inc. + Copyright (C) 2008, 2010 Red Hat, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as @@ -27,7 +27,7 @@ libffi This manual is for Libffi, a portable foreign-function interface library. - Copyright (C) 2008 Red Hat, Inc. + Copyright (C) 2008, 2010 Red Hat, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as @@ -89,6 +89,7 @@ File: libffi.info, Node: Using libffi, Next: Missing Features, Prev: Introduc * Types:: libffi type descriptions. * Multiple ABIs:: Different passing styles on one platform. * The Closure API:: Writing a generic function. +* Closure Example:: A closure example.  File: libffi.info, Node: The Basics, Next: Simple Example, Up: Using libffi @@ -368,7 +369,7 @@ instance, the x86 platform has both `stdcall' and `fastcall' functions. necessarily platform-specific.  -File: libffi.info, Node: The Closure API, Prev: Multiple ABIs, Up: Using libffi +File: libffi.info, Node: The Closure API, Next: Closure Example, Prev: Multiple ABIs, Up: Using libffi 2.5 The Closure API =================== @@ -443,6 +444,62 @@ closure function: is deprecated, as it cannot handle the need for separate writable and executable addresses. + +File: libffi.info, Node: Closure Example, Prev: The Closure API, Up: Using libffi + +2.6 Closure Example +=================== + +A trivial example that creates a new `puts' by binding `fputs' with +`stdin'. + + #include + #include + + /* Acts like puts with the file given at time of enclosure. */ + void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[], + FILE *stream) + { + *ret = fputs(*(char **)args[0], stream); + } + + int main() + { + ffi_cif cif; + ffi_type *args[1]; + ffi_closure *closure; + + int (*bound_puts)(char *); + int rc; + + /* Allocate closure and bound_puts */ + closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts); + + if (closure) + { + /* Initialize the argument info vectors */ + args[0] = &ffi_type_pointer; + + /* Initialize the cif */ + if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, + &ffi_type_uint, args) == FFI_OK) + { + /* Initialize the closure, setting stream to stdout */ + if (ffi_prep_closure_loc(closure, &cif, puts_binding, + stdout, bound_puts) == FFI_OK) + { + rc = bound_puts("Hello World!"); + /* rc now holds the result of the call to fputs */ + } + } + } + + /* Deallocate both closure, and bound_puts */ + ffi_closure_free(closure); + + return 0; + } +  File: libffi.info, Node: Missing Features, Next: Index, Prev: Using libffi, Up: Top @@ -516,18 +573,19 @@ Index  Tag Table: -Node: Top700 -Node: Introduction1436 -Node: Using libffi3072 -Node: The Basics3507 -Node: Simple Example6114 -Node: Types7141 -Node: Primitive Types7424 -Node: Structures9244 -Node: Type Example10104 -Node: Multiple ABIs11327 -Node: The Closure API11698 -Node: Missing Features14618 -Node: Index15111 +Node: Top706 +Node: Introduction1448 +Node: Using libffi3084 +Node: The Basics3570 +Node: Simple Example6177 +Node: Types7204 +Node: Primitive Types7487 +Node: Structures9307 +Node: Type Example10167 +Node: Multiple ABIs11390 +Node: The Closure API11761 +Node: Closure Example14705 +Node: Missing Features16264 +Node: Index16757  End Tag Table diff --git a/doc/libffi.texi b/doc/libffi.texi index 9a5060d5..9fa5b17c 100644 --- a/doc/libffi.texi +++ b/doc/libffi.texi @@ -19,7 +19,7 @@ This manual is for Libffi, a portable foreign-function interface library. -Copyright @copyright{} 2008 Red Hat, Inc. +Copyright @copyright{} 2008, 2010 Red Hat, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -106,6 +106,7 @@ values passed between the two languages. * Types:: libffi type descriptions. * Multiple ABIs:: Different passing styles on one platform. * The Closure API:: Writing a generic function. +* Closure Example:: A closure example. @end menu @@ -500,12 +501,66 @@ After calling @code{ffi_prep_closure_loc}, you can cast @var{codeloc} to the appropriate pointer-to-function type. @end defun -@c FIXME: example - You may see old code referring to @code{ffi_prep_closure}. This function is deprecated, as it cannot handle the need for separate writable and executable addresses. +@node Closure Example +@section Closure Example + +A trivial example that creates a new @code{puts} by binding +@code{fputs} with @code{stdin}. + +@example +#include +#include + +/* Acts like puts with the file given at time of enclosure. */ +void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[], + FILE *stream) +@{ + *ret = fputs(*(char **)args[0], stream); +@} + +int main() +@{ + ffi_cif cif; + ffi_type *args[1]; + ffi_closure *closure; + + int (*bound_puts)(char *); + int rc; + + /* Allocate closure and bound_puts */ + closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts); + + if (closure) + @{ + /* Initialize the argument info vectors */ + args[0] = &ffi_type_pointer; + + /* Initialize the cif */ + if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, + &ffi_type_uint, args) == FFI_OK) + @{ + /* Initialize the closure, setting stream to stdout */ + if (ffi_prep_closure_loc(closure, &cif, puts_binding, + stdout, bound_puts) == FFI_OK) + @{ + rc = bound_puts("Hello World!"); + /* rc now holds the result of the call to fputs */ + @} + @} + @} + + /* Deallocate both closure, and bound_puts */ + ffi_closure_free(closure); + + return 0; +@} + +@end example + @node Missing Features @chapter Missing Features @@ -525,6 +580,8 @@ There is no support for bit fields in structures. @item The closure API is +@c FIXME: ... + @item The ``raw'' API is undocumented. @c argument promotion? diff --git a/patches/closure-api-example-doc b/patches/closure-api-example-doc new file mode 100644 index 00000000..7eb1388c --- /dev/null +++ b/patches/closure-api-example-doc @@ -0,0 +1,247 @@ +Index: libffi/doc/libffi.info +=================================================================== +--- libffi.orig/doc/libffi.info ++++ libffi/doc/libffi.info +@@ -4,7 +4,7 @@ from ../libffi/doc/libffi.texi. + This manual is for Libffi, a portable foreign-function interface + library. + +- Copyright (C) 2008 Red Hat, Inc. ++ Copyright (C) 2008, 2010 Red Hat, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as +@@ -27,7 +27,7 @@ libffi + This manual is for Libffi, a portable foreign-function interface + library. + +- Copyright (C) 2008 Red Hat, Inc. ++ Copyright (C) 2008, 2010 Red Hat, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU General Public License as +@@ -89,6 +89,7 @@ File: libffi.info, Node: Using libffi, + * Types:: libffi type descriptions. + * Multiple ABIs:: Different passing styles on one platform. + * The Closure API:: Writing a generic function. ++* Closure Example:: A closure example. + +  + File: libffi.info, Node: The Basics, Next: Simple Example, Up: Using libffi +@@ -368,7 +369,7 @@ instance, the x86 platform has both `std + necessarily platform-specific. + +  +-File: libffi.info, Node: The Closure API, Prev: Multiple ABIs, Up: Using libffi ++File: libffi.info, Node: The Closure API, Next: Closure Example, Prev: Multiple ABIs, Up: Using libffi + + 2.5 The Closure API + =================== +@@ -444,6 +445,62 @@ is deprecated, as it cannot handle the n + executable addresses. + +  ++File: libffi.info, Node: Closure Example, Prev: The Closure API, Up: Using libffi ++ ++2.6 Closure Example ++=================== ++ ++A trivial example that creates a new `puts' by binding `fputs' with ++`stdin'. ++ ++ #include ++ #include ++ ++ /* Acts like puts with the file given at time of enclosure. */ ++ void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[], ++ FILE *stream) ++ { ++ *ret = fputs(*(char **)args[0], stream); ++ } ++ ++ int main() ++ { ++ ffi_cif cif; ++ ffi_type *args[1]; ++ ffi_closure *closure; ++ ++ int (*bound_puts)(char *); ++ int rc; ++ ++ /* Allocate closure and bound_puts */ ++ closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts); ++ ++ if (closure) ++ { ++ /* Initialize the argument info vectors */ ++ args[0] = &ffi_type_pointer; ++ ++ /* Initialize the cif */ ++ if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, ++ &ffi_type_uint, args) == FFI_OK) ++ { ++ /* Initialize the closure, setting stream to stdout */ ++ if (ffi_prep_closure_loc(closure, &cif, puts_binding, ++ stdout, bound_puts) == FFI_OK) ++ { ++ rc = bound_puts("Hello World!"); ++ /* rc now holds the result of the call to fputs */ ++ } ++ } ++ } ++ ++ /* Deallocate both closure, and bound_puts */ ++ ffi_closure_free(closure); ++ ++ return 0; ++ } ++ ++ + File: libffi.info, Node: Missing Features, Next: Index, Prev: Using libffi, Up: Top + + 3 Missing Features +@@ -516,18 +573,19 @@ Index + +  + Tag Table: +-Node: Top700 +-Node: Introduction1436 +-Node: Using libffi3072 +-Node: The Basics3507 +-Node: Simple Example6114 +-Node: Types7141 +-Node: Primitive Types7424 +-Node: Structures9244 +-Node: Type Example10104 +-Node: Multiple ABIs11327 +-Node: The Closure API11698 +-Node: Missing Features14618 +-Node: Index15111 ++Node: Top706 ++Node: Introduction1448 ++Node: Using libffi3084 ++Node: The Basics3570 ++Node: Simple Example6177 ++Node: Types7204 ++Node: Primitive Types7487 ++Node: Structures9307 ++Node: Type Example10167 ++Node: Multiple ABIs11390 ++Node: The Closure API11761 ++Node: Closure Example14705 ++Node: Missing Features16264 ++Node: Index16757 +  + End Tag Table +Index: libffi/doc/libffi.texi +=================================================================== +--- libffi.orig/doc/libffi.texi ++++ libffi/doc/libffi.texi +@@ -19,7 +19,7 @@ + This manual is for Libffi, a portable foreign-function interface + library. + +-Copyright @copyright{} 2008 Red Hat, Inc. ++Copyright @copyright{} 2008, 2010 Red Hat, Inc. + + @quotation + Permission is granted to copy, distribute and/or modify this document +@@ -106,6 +106,7 @@ values passed between the two languages. + * Types:: libffi type descriptions. + * Multiple ABIs:: Different passing styles on one platform. + * The Closure API:: Writing a generic function. ++* Closure Example:: A closure example. + @end menu + + +@@ -500,12 +501,66 @@ After calling @code{ffi_prep_closure_loc + to the appropriate pointer-to-function type. + @end defun + +-@c FIXME: example +- + You may see old code referring to @code{ffi_prep_closure}. This + function is deprecated, as it cannot handle the need for separate + writable and executable addresses. + ++@node Closure Example ++@section Closure Example ++ ++A trivial example that creates a new @code{puts} by binding ++@code{fputs} with @code{stdin}. ++ ++@example ++#include ++#include ++ ++/* Acts like puts with the file given at time of enclosure. */ ++void puts_binding(ffi_cif *cif, unsigned int *ret, void* args[], ++ FILE *stream) ++@{ ++ *ret = fputs(*(char **)args[0], stream); ++@} ++ ++int main() ++@{ ++ ffi_cif cif; ++ ffi_type *args[1]; ++ ffi_closure *closure; ++ ++ int (*bound_puts)(char *); ++ int rc; ++ ++ /* Allocate closure and bound_puts */ ++ closure = ffi_closure_alloc(sizeof(ffi_closure), &bound_puts); ++ ++ if (closure) ++ @{ ++ /* Initialize the argument info vectors */ ++ args[0] = &ffi_type_pointer; ++ ++ /* Initialize the cif */ ++ if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, ++ &ffi_type_uint, args) == FFI_OK) ++ @{ ++ /* Initialize the closure, setting stream to stdout */ ++ if (ffi_prep_closure_loc(closure, &cif, puts_binding, ++ stdout, bound_puts) == FFI_OK) ++ @{ ++ rc = bound_puts("Hello World!"); ++ /* rc now holds the result of the call to fputs */ ++ @} ++ @} ++ @} ++ ++ /* Deallocate both closure, and bound_puts */ ++ ffi_closure_free(closure); ++ ++ return 0; ++@} ++ ++@end example ++ + + @node Missing Features + @chapter Missing Features +@@ -525,6 +580,8 @@ There is no support for bit fields in st + @item + The closure API is + ++@c FIXME: ... ++ + @item + The ``raw'' API is undocumented. + @c argument promotion? +Index: libffi/ChangeLog.libffi +=================================================================== +--- libffi.orig/ChangeLog.libffi ++++ libffi/ChangeLog.libffi +@@ -1,3 +1,8 @@ ++2010-01-12 Conrad Irwin ++ ++ * doc/libffi.texi: Add closure example. ++ * doc/libffi.info: Rebuilt. ++ + 2009-12-25 Samuli Suominen + + * configure.ac: Undefine _AC_ARG_VAR_PRECIOUS for autoconf 2.64. diff --git a/patches/series b/patches/series index e8c461fd..2c872f9e 100644 --- a/patches/series +++ b/patches/series @@ -1 +1,2 @@ stand-alone +closure-api-example-doc