2
<TITLE> AVCALL manual page </TITLE>
5
<H1>AVCALL manual page</H1>
8
<LI> <A HREF="#Name">Name</A>
9
<LI> <A HREF="#Synopsis">Synopsis</A>
10
<LI> <A HREF="#Description">Description</A>
11
<LI> <A HREF="#Notes">Notes</A>
12
<LI> <A HREF="#See also">See also</A>
13
<LI> <A HREF="#Bugs">Bugs</A>
14
<LI> <A HREF="#Non-Bugs">Non-Bugs</A>
15
<LI> <A HREF="#Porting AVCALL">Porting AVCALL</A>
16
<LI> <A HREF="#Author">Author</A>
17
<LI> <A HREF="#Acknowledgements">Acknowledgements</A>
27
avcall - build a C argument list incrementally and call a
35
<CODE>#include <avcall.h></CODE>
36
<CODE>av_alist <VAR>alist</VAR>;</CODE>
37
<CODE>av_start_<VAR>type</VAR> (<VAR>alist</VAR>, &<VAR>func</VAR>, [[<VAR>return_type</VAR>,] &<VAR>return_value</VAR>]);</CODE>
38
<CODE>av_<VAR>type</VAR> (<VAR>alist</VAR>, [<VAR>arg_type</VAR>,] <VAR>value</VAR>);</CODE>
39
<CODE>av_call(<VAR>alist</VAR>);</CODE>
42
<A NAME="Description">
46
This set of macros builds an argument list for a C function
47
and calls the function on it. It significantly
48
reduces the amount of `glue' code required for parsers,
49
debuggers, imbedded interpreters, C extensions to application
50
programs and other situations where collections of
51
functions need to be called on lists of externally-
54
Function calling conventions differ considerably on different
55
machines and <CODE>avcall</CODE> attempts to provide some degree
56
of isolation from such architecture dependencies.
58
The interface is like <A HREF="stdarg(3)"><CODE><B>stdarg</B></CODE></A>(3) in reverse. All of the
59
macros return 0 for success, < 0 for failure (e.g., argument
60
list overflow or type-not-supported).
63
<LI> <CODE>#include <avcall.h></CODE> and declare the argument list
64
structure <CODE>av_alist <VAR>alist</VAR>;</CODE>
66
<LI> Set any special flags. This is architecture and compiler
68
Compiler options that affect passing conventions may need
69
to be flagged by <CODE>#define</CODE>s before the <CODE>#include <avcall.h></CODE>
70
statement. However, the <SAMP>configure</SAMP> script should have
71
determined which <CODE>#define</CODE>s are needed and put them
72
at the top of <SAMP>avcall.h</SAMP>.
74
<LI> Initialize the alist with the function address and
75
return value pointer (if any). There is a separate macro
76
for each simple return type ([u]char, [u]short, [u]int,
77
[u]long, [u]longlong, float, double, where `u' indicates
78
`unsigned'). The macros for functions returning structures
79
or pointers require an explicit type argument.
83
<CODE>av_start_int (<VAR>alist</VAR>, &<VAR>func</VAR>, &<VAR>int_return</VAR>);</CODE>
84
<CODE>av_start_double (<VAR>alist</VAR>, &<VAR>func</VAR>, &<VAR>double_return</VAR>);</CODE>
85
<CODE>av_start_void (<VAR>alist</VAR>, &<VAR>func</VAR>);</CODE>
86
<CODE>av_start_struct (<VAR>alist</VAR>, &<VAR>func</VAR>, <VAR>struct_type</VAR>, <VAR>splittable</VAR>, &<VAR>struct_return</VAR>);</CODE>
87
<CODE>av_start_ptr (<VAR>alist</VAR>, &<VAR>func</VAR>, <VAR>pointer_type</VAR>, &<VAR>pointer_return</VAR>);</CODE>
89
The <VAR>splittable</VAR> flag specifies whether the <VAR>struct_type</VAR> can
90
be returned in registers such that every struct field fits
91
entirely in a single register. This needs to be specified
92
for structs of size <SAMP>2*sizeof(long)</SAMP>. For structs of size
93
<= <SAMP>sizeof(long)</SAMP>, splittable is ignored and assumed to be 1.
94
For structs of size > <SAMP>2*sizeof(long)</SAMP>, splittable is
95
ignored and assumed to be 0. There are some handy macros
98
<CODE>av_word_splittable_1 (<VAR>type1</VAR>)</CODE>
99
<CODE>av_word_splittable_2 (<VAR>type1</VAR>, <VAR>type2</VAR>)</CODE>
100
<CODE>av_word_splittable_3 (<VAR>type1</VAR>, <VAR>type2</VAR>, <VAR>type3</VAR>)</CODE>
101
<CODE>av_word_splittable_4 (<VAR>type1</VAR>, <VAR>type2</VAR>, <VAR>type3</VAR>, <VAR>type4</VAR>)</CODE>
103
For a struct with three slots
105
<CODE>struct { <VAR>type1 id1</VAR>; <VAR>type2 id2</VAR>; <VAR>type3 id3</VAR>; }</CODE>
107
you can specify <VAR>splittable</VAR> as
108
<CODE>av_word_splittable_3 (<VAR>type1</VAR>, <VAR>type2</VAR>, <VAR>type3</VAR>)</CODE>.
110
<LI> Push the arguments on to the list in order. Again
111
there is a macro for each simple built-in type, and the
112
macros for structure and pointer arguments require an
115
<CODE>av_int (<VAR>alist</VAR>, <VAR>int_value</VAR>);</CODE>
116
<CODE>av_double (<VAR>alist</VAR>, <VAR>double_value</VAR>);</CODE>
117
<CODE>av_struct (<VAR>alist</VAR>, <VAR>struct_or_union_type</VAR>, <VAR>struct_value</VAR>);</CODE>
118
<CODE>av_ptr (<VAR>alist</VAR>, <VAR>pointer_type</VAR>, <VAR>pointer_value</VAR>);</CODE>
120
<LI> Call the function, set the return value, and tidy up:
121
<CODE>av_call (<VAR>alist</VAR>);</CODE>
129
<LI> Functions whose first declaration is in Kernighan &
130
Ritchie style (i.e., without a typed argument list) MUST
131
use default K&R C expression promotions (<CODE>char</CODE> and <CODE>short</CODE> to
132
<CODE>int</CODE>, <CODE>float</CODE> to <CODE>double</CODE>) whether they are compiled by a K&R
133
or an ANSI compiler, because the true argument types may
134
not be known at the call point. Such functions typically
135
back-convert their arguments to the declared types on
136
function entry. (In fact, the only way to pass a true
137
<CODE>char</CODE>, <CODE>short</CODE> or <CODE>float</CODE> in K&R C is by an explicit cast:
138
<CODE>func((char)c,(float)f)</CODE> ). Similarly, some K&R compilers
139
(such as Sun <SAMP>cc</SAMP> on the sparc) actually return a <CODE>float</CODE> as a
142
Hence, for arguments of functions declared in K&R style
143
you should use <CODE>av_int()</CODE> and </CODE>av_double()</CODE> rather than
144
<CODE>av_char()</CODE>, <CODE>av_short()</CODE> or <CODE>av_float()</CODE>. If you use a K&R
145
compiler, the avcall header files may be able to detect
146
this and define <CODE>av_float()</CODE>, etc, appropriately, but with
147
an ANSI compiler there is no way <B>avcall</B> can know how a
148
function was declared, so you have to correct the argument
151
<LI> The explicit type arguments of the <CODE>av_struct()</CODE> and
152
<CODE>av_ptr()</CODE> macros are typically used to calculate size,
153
alignment, and passing conventions. This may not be sufficient for some machines with unusual structure and
154
pointer handling: in this case additional <CODE>av_start_<VAR>type</VAR>()</CODE>
155
and <CODE>av_<VAR>type</VAR>()</CODE> macros may be defined.
157
<LI> The macros <CODE>av_start_longlong()</CODE>,
158
<CODE>av_start_ulonglong()</CODE>, <CODE>av_longlong()</CODE> and
159
<CODE>av_ulonglong()</CODE> work only if the C compiler has a working
160
<CODE>long long</CODE> 64-bit integer type.
162
<LI> The struct types used in <CODE>av_start_struct()</CODE> and
163
<CODE>av_struct()</CODE> must only contain (signed or unsigned) int,
164
long, long long or pointer fields. Struct types containing
165
(signed or unsigned) char, short, float, double or other
166
structs are not supported.
173
<A HREF="stdarg(3)"><CODE><B>stdarg</B></CODE></A>(3), <A HREF="varargs(3)"><CODE><B>varargs</B></CODE></A>(3).
181
The current implementations have been tested on a selection
182
of common cases but there are probably still many
185
There are typically built-in limits on the size of the
186
argument-list, which may also include the size of any
189
The decision whether a struct is to be returned in registers or in memory
190
considers only the struct's size and alignment. This is inaccurate: for
191
example, gcc on m68k-next returns
192
<CODE>struct { char a,b,c; }</CODE>
194
<CODE>struct { char a[3]; }</CODE>
195
in memory, although both types have the same size and the same alignment.
202
All information is passed in CPU registers and the stack.
203
The <CODE><B>avcall</B></CODE> package is therefore multithread-safe.
205
<A NAME="Porting AVCALL">
206
<H2>Porting AVCALL</H2>
209
Ports, bug-fixes, and suggestions are most welcome. The
210
macros required for argument pushing are pretty grungy,
211
but it does seem to be possible to port avcall to a range
212
of machines. Ports to non-standard or non-32-bit machines
213
are especially welcome so we can sort the interface out
214
before it's too late.
216
Knowledge about argument passing conventions can be found
217
in the gcc source, file <SAMP>gcc-2.6.3/config/<VAR>cpu</VAR>/<VAR>cpu</VAR>.h</SAMP>, section
218
<SAMP>"Stack layout; function entry, exit and calling."</SAMP>
220
Some of the grunge is usually handled by a C or assembly
221
level glue routine that actually pushes the arguments,
222
calls the function and unpacks any return value. This is
223
called <CODE>__builtin_avcall()</CODE>. A precompiled assembler version for
224
people without gcc is also made available. The routine should ideally
225
have flags for the passing conventions of other compilers.
227
Many of the current routines waste a lot of stack space
228
and generally do hairy things to stack frames - a bit more
229
assembly code would probably help things along quite a bit
237
Bill Triggs <Bill.Triggs@inrialpes.fr>, <Bill.Triggs@imag.fr>.
239
<A NAME="Acknowledgements">
240
<H2>Acknowledgements</H2>
243
Some initial ideas were stolen from the C interface to the
244
Zelk extensions to Oliver Laumann's Elk scheme interpreter
245
by J.P.Lewis, NEC C&C Research, <zilla@ccrl.nj.nec.com>
246
(for Sun4 & SGI), and Roy Featherstone's
247
<roy@robots.oxford.ac.uk> personal C interface library for
248
Sun3, Sun4 & SGI. I also looked at the machine-dependent
249
parts of the GCC and GDB distributions, and put the gcc
250
<CODE>asm()</CODE> extensions to good use. Thanks guys!
252
This work was partly supported by EC-ESPRIT Basic Research
258
<ADDRESS>AVCALL manual page<BR>
259
Bruno Haible <bruno@clisp.org>
262
Last modified: 14 January 2001.
added
removed
avcall/avcall.html
