home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Misc / CLISP-2.LHA / CLISP960530-ki.lha / ffcall / avcall / avcall.man < prev    next >
Encoding:
Text File  |  1996-04-15  |  10.7 KB  |  265 lines
  1.  
  2.  
  3.  
  4. AVCALL(3)                                               AVCALL(3)
  5.  
  6.  
  7. NNAAMMEE
  8.        avcall  - build a C argument list incrementally and call a
  9.        C function on it.
  10.  
  11. SSYYNNOOPPSSIISS
  12.        ##iinncclluuddee <<aavvccaallll..hh>>
  13.  
  14.        aavv__aalliisstt _a_l_i_s_t;;
  15.  
  16.        aavv__ssttaarrtt___t_y_p_e((_a_l_i_s_t,, _&_f_u_n_c [[,, _r_e_t_u_r_n___t_y_p_e],, _&_r_e_t_u_r_n___v_a_l_u_e
  17.        ]));;
  18.  
  19.        aavv___t_y_p_e((_a_l_i_s_t,, [_a_r_g___t_y_p_e,,] _v_a_l_u_e));;
  20.  
  21.        aavv__ccaallll((_a_l_i_s_t));;
  22.  
  23. DDEESSCCRRIIPPTTIIOONN
  24.        This  set  of macros builds an argument list for a C func-
  25.        tion and  calls  the  function  on  it.  It  significantly
  26.        reduces  the  amount  of `glue' code required for parsers,
  27.        debuggers, imbedded interpreters, C extensions to applica-
  28.        tion  programs  and  other situations where collections of
  29.        functions need  to  be  called  on  lists  of  externally-
  30.        supplied arguments.
  31.  
  32.        Function  calling  conventions differ considerably on dif-
  33.        ferent machines and _a_v_c_a_l_l attempts to provide some degree
  34.        of isolation from such architecture dependencies.
  35.  
  36.        The  interface  is  like  ssttddaarrgg(3) in reverse. All of the
  37.        macros return 0 for success, < 0 for failure (e.g.,  argu-
  38.        ment list overflow or type-not-supported).
  39.  
  40.        (1)    ##iinncclluuddee <<aavvccaallll..hh>>
  41.               and declare the argument list structure
  42.               aavv__aalliisstt _a_l_i_s_t;;
  43.  
  44.        (2)    Set  any  special  flags.  This is architecture and
  45.               compiler dependent.  Compiler options  that  affect
  46.               passing  conventions  may  need  to  be  flagged by
  47.               ##ddeeffiinnees before the ##iinncclluuddee <<aavvccaallll..hh>>  statement.
  48.               However,  the  _c_o_n_f_i_g_u_r_e  script should have deter-
  49.               mined which ##ddeeffiinnees are needed and put them at the
  50.               top of aavvccaallll..hh.
  51.  
  52.        (3)    Initialize  the alist with the function address and
  53.               return value pointer (if any). There is a  separate
  54.               macro   for   each  simple  return  type  ([u]char,
  55.               [u]short, [u]int, [u]long, float, double, where `u'
  56.               indicates  `unsigned').  The  macros  for functions
  57.               returning  structures  or   pointers   require   an
  58.               explicit type argument.
  59.  
  60.        E.g.,
  61.  
  62.  
  63.  
  64.                           10 March 1995                         1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. AVCALL(3)                                               AVCALL(3)
  71.  
  72.  
  73.        aavv__ssttaarrtt__iinntt ((_a_l_i_s_t,, _&_f_u_n_c,, _&_i_n_t___r_e_t_u_r_n));;
  74.  
  75.        aavv__ssttaarrtt__ddoouubbllee ((_a_l_i_s_t,, _&_f_u_n_c,, _&_d_o_u_b_l_e___r_e_t_u_r_n));;
  76.  
  77.        aavv__ssttaarrtt__vvooiidd ((_a_l_i_s_t,, _&_f_u_n_c));;
  78.  
  79.        aavv__ssttaarrtt__ssttrruucctt ((_a_l_i_s_t,, _&_f_u_n_c,, _s_t_r_u_c_t___t_y_p_e,, _s_p_l_i_t_t_a_b_l_e,,
  80.                         _&_s_t_r_u_c_t___r_e_t_u_r_n));;
  81.  
  82.        aavv__ssttaarrtt__ppttrr ((_a_l_i_s_t,, _&_f_u_n_c,, _p_o_i_n_t_e_r___t_y_p_e,,
  83.                      _&_p_o_i_n_t_e_r___r_e_t_u_r_n));;
  84.  
  85.        The  _s_p_l_i_t_t_a_b_l_e flag specifies whether the _s_t_r_u_c_t___t_y_p_e can
  86.        be returned in registers such that every struct field fits
  87.        entirely  in a single register. This needs to be specified
  88.        for structs of size 2*sizeof(long). For structs of size <=
  89.        sizeof(long),  _s_p_l_i_t_t_a_b_l_e  is ignored and assumed to be 1.
  90.        For  structs  of  size  >  2*sizeof(long),  _s_p_l_i_t_t_a_b_l_e  is
  91.        ignored  and  assumed to be 0. There are some handy macros
  92.        for this:
  93.        aavv__wwoorrdd__sspplliittttaabbllee__11 ((_t_y_p_e_1))
  94.        aavv__wwoorrdd__sspplliittttaabbllee__22 ((_t_y_p_e_1,, _t_y_p_e_2))
  95.        aavv__wwoorrdd__sspplliittttaabbllee__33 ((_t_y_p_e_1,, _t_y_p_e_2,, _t_y_p_e_3))
  96.        aavv__wwoorrdd__sspplliittttaabbllee__44 ((_t_y_p_e_1,, _t_y_p_e_2,, _t_y_p_e_3,, _t_y_p_e_4))
  97.        For a struct with three slots
  98.        ssttrruucctt {{ _t_y_p_e_1 _i_d_1;; _t_y_p_e_2 _i_d_2;; _t_y_p_e_3 _i_d_3;; }}
  99.        you can specify _s_p_l_i_t_t_a_b_l_e as aavv__wwoorrdd__sspplliittttaabbllee__33 ((_t_y_p_e_1,,
  100.        _t_y_p_e_2,, _t_y_p_e_3)) .
  101.  
  102.        (4)    Push  the  arguments on to the list in order. Again
  103.               there is a macro for each simple built-in type, and
  104.               the  macros  for  structure  and  pointer arguments
  105.               require an extra type argument:
  106.  
  107.        aavv__iinntt ((_a_l_i_s_t,, _i_n_t___v_a_l_u_e));;
  108.  
  109.        aavv__ddoouubbllee ((_a_l_i_s_t,, _d_o_u_b_l_e___v_a_l_u_e));;
  110.  
  111.        aavv__ssttrruucctt ((_a_l_i_s_t,, _s_t_r_u_c_t___o_r___u_n_i_o_n___t_y_p_e,, _s_t_r_u_c_t___v_a_l_u_e));;
  112.  
  113.        aavv__ppttrr ((_a_l_i_s_t,, _p_o_i_n_t_e_r___t_y_p_e,, _p_o_i_n_t_e_r___v_a_l_u_e));;
  114.  
  115.        (5)    Call the function, set the return value,  and  tidy
  116.               up:
  117.  
  118.        aavv__ccaallll ((_a_l_i_s_t));;
  119.  
  120.  
  121. NNOOTTEESS
  122.        (1)  Functions  whose  first declaration is in Kernighan &
  123.        Ritchie style (i.e., without a typed argument  list)  MUST
  124.        use default K&R C expression promotions (char and short to
  125.        int, float to double) whether they are compiled by  a  K&R
  126.        or  an  ANSI compiler, because the true argument types may
  127.  
  128.  
  129.  
  130.                           10 March 1995                         2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. AVCALL(3)                                               AVCALL(3)
  137.  
  138.  
  139.        not be known at the call point. Such  functions  typically
  140.        back-convert  their  arguments  to  the  declared types on
  141.        function entry. (In fact, the only  way  to  pass  a  true
  142.        char,  short  or  float  in  K&R C is by an explicit cast:
  143.        ffuunncc((((cchhaarr))cc,,((ffllooaatt))ff)) ).  Similarly, some  K&R  compilers
  144.        (such as Sun cc on the sparc) actually return a float as a
  145.        double.
  146.  
  147.        Hence, for arguments of functions declared  in  K&R  style
  148.        you  should  use  aavv__iinntt(())  and  aavv__ddoouubbllee(())  rather  than
  149.        aavv__cchhaarr(()),, aavv__sshhoorrtt(()) or aavv__ffllooaatt(())..  If  you  use  a  K&R
  150.        compiler,  the  avcall  header files may be able to detect
  151.        this and define aavv__ffllooaatt(()),, etc, appropriately,  but  with
  152.        an  ANSI  compiler  there  is no way _a_v_c_a_l_l can know how a
  153.        function was declared, so you have to correct the argument
  154.        types yourself.
  155.  
  156.        (2)  The  explicit  type  arguments of the aavv__ssttrruucctt(()) and
  157.        aavv__ppttrr(()) macros are  typically  used  to  calculate  size,
  158.        alignment,  and passing conventions.  This may not be suf-
  159.        ficient for  some  machines  with  unusual  structure  and
  160.        pointer  handling: in this case additional aavv__ssttaarrtt___t_y_p_e(())
  161.        and aavv___t_y_p_e(()) macros may be defined.
  162.  
  163.  
  164. SSEEEE AALLSSOO
  165.        ssttddaarrgg(3), vvaarraarrggss(3).
  166.  
  167.  
  168. BBUUGGSS
  169.        The current implementations have been tested on  a  selec-
  170.        tion  of  common  cases  but there are probably still many
  171.        bugs.
  172.  
  173.        There are typically built-in limits on  the  size  of  the
  174.        argument-list,  which  may  also  include  the size of any
  175.        structure arguments.
  176.  
  177.        The decision whether a struct is to be returned in  regis-
  178.        ters  or  in  memory  considers only the struct's size and
  179.        alignment. This is inaccurate: for example, gcc  on  m68k-
  180.        next  returns  ssttrruucctt  {{  cchhaarr  aa,,bb,,cc;;  }} in registers and
  181.        ssttrruucctt {{ cchhaarr aa[[33]];; }} in memory, although both types  have
  182.        the same size and the same alignment.
  183.  
  184.  
  185. PPOORRTTIINNGG AAVVCCAALLLL
  186.        Ports,  bug-fixes,  and  suggestions are most welcome. The
  187.        macros required for argument pushing  are  pretty  grungy,
  188.        but  it does seem to be possible to port avcall to a range
  189.        of machines. Ports to non-standard or non-32-bit  machines
  190.        are  especially  welcome  so we can sort the interface out
  191.        before it's too late.
  192.  
  193.  
  194.  
  195.  
  196.                           10 March 1995                         3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. AVCALL(3)                                               AVCALL(3)
  203.  
  204.  
  205.        Knowledge about argument passing conventions can be  found
  206.        in  the  gcc source, file gcc-2.6.3/config/_c_p_u/_c_p_u.h, sec-
  207.        tion "Stack layout; function entry, exit and calling."
  208.  
  209.        Some of the grunge is usually handled by a C  or  assembly
  210.        level  glue  routine  that  actually pushes the arguments,
  211.        calls the function and unpacks any return value.  This  is
  212.        called __builtin_avcall(). A precompiled assembler version
  213.        for people without gcc is also made available. The routine
  214.        should  ideally  have flags for the passing conventions of
  215.        other compilers.
  216.  
  217.        Many of the current routines waste a lot  of  stack  space
  218.        and generally do hairy things to stack frames - a bit more
  219.        assembly code would probably help things along quite a bit
  220.        here.
  221.  
  222.  
  223. AAUUTTHHOORR
  224.        Bill Triggs <bill@robots.oxford.ac.uk>.
  225.  
  226.  
  227. AACCKKNNOOWWLLEEDDGGEEMMEENNTTSS
  228.        Some initial ideas were stolen from the C interface to the
  229.        Zelk extensions to Oliver Laumann's Elk scheme interpreter
  230.        by  J.P.Lewis,  NEC  C&C Research, <zilla@ccrl.nj.nec.com>
  231.        (for    Sun4    &    SGI),    and    Roy    Featherstone's
  232.        <roy@robots.oxford.ac.uk> personal C interface library for
  233.        Sun[34] & SGI.  I also  looked  at  the  machine-dependent
  234.        parts  of  the  GCC and GDB distributions, and put the gcc
  235.        asm() extensions to good use. Thanks guys!
  236.  
  237.        This work was partly supported by EC-ESPRIT Basic Research
  238.        Action SECOND.
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.                           10 March 1995                         4
  263.  
  264.  
  265.