home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / CLISP-2.LHA / CLISP960530-ki.lha / ffcall / avcall / DOC < prev    next >
Encoding:
Text File  |  1996-04-15  |  6.0 KB  |  134 lines
  1.   Copyright 1993 Bill Triggs, <bill@robots.oxford.ac.uk>,
  2.   Oxford University Robotics Group, Oxford OX1 3PJ, U.K.
  3.  
  4.   Copyright 1995 Bruno Haible, <haible@ma2s2.mathematik.uni-karlsruhe.de>
  5.  
  6.   This is free software distributed under the GNU General Public
  7.   Licence described in the file COPYING. Contact the author if 
  8.   you don't have this or can't live with it. There is ABSOLUTELY 
  9.   NO WARRANTY, explicit or implied, on this software.
  10.  
  11. ----------------------------------------------------------------------
  12.     AVCALL --- a foreign function interface to ANSI-C
  13. ----------------------------------------------------------------------
  14.  
  15. This library allows arbitrary C functions to be called from embedded
  16. interpreters, debuggers, RPC calls, etc, by building up a C argument
  17. list incrementally from explicitly typed arguments. This considerably
  18. reduces the amount of boilerplate glue code required for such
  19. applications.
  20.  
  21. The interface is like stdargs/varargs in reverse and is intended to be as
  22. portable as possible, however the details of function calling are highly
  23. machine-dependent so your mileage may vary. At the very least there are
  24. typically built-in limits on the size of the argument-list. The
  25. argument-pushing macros all return 0 for success, < 0 for error (eg,
  26. arg-list overflow).
  27.  
  28. Installation instructions are in the Makefile.
  29.  
  30. ----------------------------------------------------------------------
  31. DECLARE ALIST -> OPEN ALIST -> SET FLAGS -> PUSH ARGS -> CALL FUNCTION
  32. ----------------------------------------------------------------------
  33.  
  34. 1) Declare the argument list structure:
  35.  
  36.     #include "avcall.h"
  37.     {
  38.       av_alist alist;
  39.  
  40. 2) Set any special flags. This is architecture and compiler dependent.
  41. Sometimes, compiler options must be flagged by #defines before the
  42. #include <avcall.h>. Usually, however, the `configure' script should
  43. have determined which #defines are needed and put them at the head of
  44. avcall.h.
  45.  
  46. 3) Initialise the alist with the function address and return type. 
  47. There is a separate macro for each built-in C type (char, int, float, etc).
  48. Eg,
  49.     av_start_int(alist,&func,&return_addr);
  50. or
  51.     av_start_double(alist,&func,&return_addr);
  52. etc.
  53. Functions returning a structure or pointer take an extra type argument:
  54. Eg,
  55.     av_start_struct(alist,&func,STRUCT_OR_UNION_TYPE,SPLITTABLE,&return_addr);
  56. or
  57.     av_start_ptr(alist,&func,POINTER_TYPE,&return_addr);
  58.  
  59.  
  60. 4) Push the arguments one by one in order. There is a macro for each
  61. built-in C type, eg:
  62.     av_int(alist,value);
  63. or
  64.     av_double(alist,value);
  65.  
  66. Structure and pointer arguments require an extra type argument:
  67.  
  68.     av_struct(alist,STRUCT_TYPE,value);
  69. or
  70.     av_ptr(alist,POINTER_TYPE,value);
  71.  
  72. 5) Call the function, set the return value, and tidy up:
  73.  
  74.     av_call(alist);
  75.  
  76. ----------------------------------------------------------------------
  77.             NOTES
  78.  
  79. 1) Functions declared in K&R style (ie, without a typed arglist) must
  80. use default K&R expression promotions (char,short-->int; float-->double)
  81. whether they are compiled by a K&R or an ANSI compiler, because the 
  82. true arg types may not be known at the call point. Such functions
  83. back-convert their arguments to the declared types on function entry.
  84. The only way to pass a true char, short or float (eg, from K&R C to an 
  85. ANSI or varargs function) is by an explicit cast: foo((char)c,(float)f).
  86.  
  87.  !! Hence, for args of functions declared in K&R style you should use
  88.  !! av_int() and av_double() instead of av_{char,short}() and av_float().
  89.  
  90. If you use a K&R compiler, the avcall header files may detect this and 
  91. define av_float, etc, appropriately, but with an ANSI compiler there's 
  92. no way avcall can know how a function was declared, so you have to 
  93. correct the argument types yourself. Similarly, some K&R compilers (such 
  94. as Sun cc on the sparc) actually return a float as a double.
  95.  
  96. 2) There are too many possible structure and pointer types to have a
  97. separate macro for each, so the pointer and structure macros take an
  98. explicit type argument which may be used (eg) to calculate the size of
  99. the structure. On most architectures this provides enough information
  100. for the compiler to make the proper call, but there will always be
  101. machines with odd alignment requirements or argument passing
  102. conventions, unusual reprentations for function, char, or void pointers,
  103. etc, for which this scheme will not suffice.  These machines may define
  104. additional av_start_TYPE and av_TYPE macros.
  105.  
  106. 3) The current implementations are pretty flakey in places. I'm happy to 
  107. accept new ports and (properly tested) fixes and enhancements. In
  108. particular, many of the routines waste a lot of stack space and generally
  109. do hairy things with stack frames - a bit more assembly code would probably 
  110. help things along quite a bit, but I don't speak assembler at all well.
  111.  
  112. 4) The macros required for all this are pretty grungy, but it does seem
  113. to be possible to port avcall to many machines. Some of the grunge is
  114. usually handled by a C or assembly level glue routine that actually
  115. pushes the arguments, calls the function and unpacks any return value.
  116. This is called __builtin_avcall(). A precompiled assembler version for
  117. people without gcc is also made available. The routine should ideally
  118. have flags for the passing conventions of other compilers.
  119. ----------------------------------------------------------------------
  120.         ACKNOWLEDGEMENTS
  121.  
  122. I was aware of two similar but rather more restricted foreign function 
  123. interfaces when the initial version of this library was written, although
  124. (I believe) all of the present code is my own: the C interface in the zelk
  125. extensions to Oliver Laumann's <net@cs.tu-berlin.de> Elk scheme interpreter
  126. by J.P.Lewis, NEC C&C Research, <zilla@ccrl.nj.nec.com> (for Sun4 and SGI); 
  127. and Roy Featherstone's <roy@robots.oxford.ac.uk> personal C interface 
  128. library for Sun3,4 and SGI. I also looked at the comments and some of the 
  129. code in the machine-dependent parts of the GCC and GDB distributions, and 
  130. put the GCC __asm__ extensions to good use. Thanks guys!
  131.  
  132. This work was partly supported by EC-ESPRIT Basic Research Action SECOND.
  133. ----------------------------------------------------------------------
  134.