1
.TH AVCALL 3 "14 January 2001"
3
avcall \- build a C argument list incrementally and call a C function on it.
7
.BI "av_alist " alist ";"
9
.BI av_start_ type "(" alist ", " "&func"
17
.BI av_ type "(" alist ", "\c
23
.BI "av_call(" alist ");"
24
.IX "av_alist" "" "\fLav_alist\fP \(em avcall argument list declaration"
25
.IX "av_start_type()" "" "\fLav_start_type()\fP \(em initialize avcall function"
26
.IX "av_type()" "" "\fLav_type()\fP \(em push next argument in avcall list"
27
.IX "av_call()" "" "\fLav_call()\fP \(em finish avcall argument list and call function"
30
This set of macros builds an argument list for a C function and calls
31
the function on it. It significantly reduces the amount of `glue' code
32
required for parsers, debuggers, imbedded interpreters, C extensions to
33
application programs and other situations where collections of functions
34
need to be called on lists of externally-supplied arguments.
36
Function calling conventions differ considerably on different
39
attempts to provide some degree of isolation from such architecture
44
in reverse. All of the macros return 0 for success, < 0 for failure (e.g.,
45
argument list overflow or type-not-supported).
49
.B #include <avcall.h>
51
and declare the argument list structure
52
.BI "av_alist " alist ;
56
Set any special flags. This is architecture and compiler dependent.
57
Compiler options that affect passing conventions may need to be flagged
61
.B "#include <avcall.h>"
62
statement. However, the
64
script should have determined which
66
are needed and put them
71
Initialize the alist with the function address and return value
72
pointer (if any). There is a separate macro for each simple return type
73
([u]char, [u]short, [u]int, [u]long, [u]longlong, float, double, where `u'
74
indicates `unsigned'). The macros for functions returning structures or
75
pointers require an explicit type argument.
79
.BI "av_start_int (" alist ", " &func ", " &int_return );
81
.BI "av_start_double (" alist ", " &func ", " &double_return );
83
.BI "av_start_void (" alist ", " &func );
86
.BI "av_start_struct (" alist ", " &func ", " struct_type ", " splittable ", "
87
.BI " " &struct_return );
91
.BI "av_start_ptr (" alist ", " &func ", " pointer_type ", "
92
.BI " " &pointer_return );
97
flag specifies whether the
99
can be returned in registers such that every struct field fits entirely in
100
a single register. This needs to be specified for structs of size
101
2*sizeof(long). For structs of size <= sizeof(long),
103
is ignored and assumed to be 1. For structs of size > 2*sizeof(long),
105
is ignored and assumed to be 0. There are some handy macros for this:
107
.BI "av_word_splittable_1 (" type1 )
108
.BI "av_word_splittable_2 (" type1 ", " type2 )
109
.BI "av_word_splittable_3 (" type1 ", " type2 ", " type3 )
110
.BI "av_word_splittable_4 (" type1 ", " type2 ", " type3 ", " type4 )
112
For a struct with three slots
114
.BI "struct { " "type1 id1" "; " "type2 id2" "; " "type3 id3" "; }"
119
.BI "av_word_splittable_3 (" type1 ", " type2 ", " type3 )
123
Push the arguments on to the list in order. Again there is a macro
124
for each simple built-in type, and the macros for structure and pointer
125
arguments require an extra type argument:
127
.BI "av_int (" alist ", " int_value );
129
.BI "av_double (" alist ", " double_value );
131
.BI "av_struct (" alist ", " struct_or_union_type ", " struct_value );
133
.BI "av_ptr (" alist ", " pointer_type ", " pointer_value );
136
Call the function, set the return value, and tidy up:
138
.BI "av_call (" alist );
143
(1) Functions whose first declaration is in Kernighan & Ritchie style (i.e.,
144
without a typed argument list) MUST use default K&R C expression promotions
145
(char and short to int, float to double) whether they are compiled by a K&R
146
or an ANSI compiler, because the true argument types may not be known at the
147
call point. Such functions typically back-convert their arguments to the
148
declared types on function entry. (In fact, the only way to pass a true char,
149
short or float in K&R C is by an explicit cast:
150
.B func((char)c,(float)f)
152
Similarly, some K&R compilers (such as Sun cc on the sparc) actually
153
return a float as a double.
155
Hence, for arguments of functions declared in K&R style you should use
164
If you use a K&R compiler, the avcall header files may be able to
165
detect this and define
167
etc, appropriately, but with an ANSI compiler there is no way
169
can know how a function was declared, so you have to correct the
170
argument types yourself.
172
(2) The explicit type arguments of the
176
macros are typically used to calculate size, alignment, and passing
177
conventions. This may not be sufficient for some machines with unusual
178
structure and pointer handling: in this case additional
186
macros may be defined.
189
.BR av_start_longlong(\|) ,
190
.BR av_start_ulonglong(\|) ,
194
work only if the C compiler has a working
198
(4) The struct types used in
199
.B av_start_struct(\|)
202
must only contain (signed or unsigned) int, long, long long or pointer fields.
203
Struct types containing (signed or unsigned) char, short, float, double or
204
other structs are not supported.
212
The current implementations have been tested on a selection of common
213
cases but there are probably still many bugs.
215
There are typically built-in limits on the size of the argument-list,
216
which may also include the size of any structure arguments.
218
The decision whether a struct is to be returned in registers or in memory
219
considers only the struct's size and alignment. This is inaccurate: for
220
example, gcc on m68k-next returns
221
.B "struct { char a,b,c; }"
223
.B "struct { char a[3]; }"
224
in memory, although both types have the same size and the same alignment.
228
All information is passed in CPU registers and the stack. The
230
package is therefore multithread-safe.
234
Ports, bug-fixes, and suggestions are most welcome. The macros required
235
for argument pushing are pretty grungy, but it does seem to be possible
236
to port avcall to a range of machines. Ports to non-standard or
237
non-32-bit machines are especially welcome so we can sort the interface
238
out before it's too late.
240
Knowledge about argument passing conventions can be found in the gcc
242
.RI gcc-2.6.3/config/ cpu / cpu .h,
243
section "Stack layout; function entry, exit and calling."
245
Some of the grunge is usually handled by a C or assembly level glue
246
routine that actually pushes the arguments, calls the function and
247
unpacks any return value.
248
This is called __builtin_avcall(\|). A precompiled assembler version for
249
people without gcc is also made available. The routine should ideally
250
have flags for the passing conventions of other compilers.
252
Many of the current routines waste a lot of stack space and generally do
253
hairy things to stack frames - a bit more assembly code would probably
254
help things along quite a bit here.
258
Bill Triggs <Bill.Triggs@inrialpes.fr>.
262
Some initial ideas were stolen from the C interface to the Zelk
263
extensions to Oliver Laumann's Elk scheme interpreter by J.P.Lewis, NEC
264
C&C Research, <zilla@ccrl.nj.nec.com> (for Sun4 & SGI), and Roy
265
Featherstone's <roy@robots.oxford.ac.uk> personal C interface library
266
for Sun[34] & SGI. I also looked at the machine-dependent parts of the
267
GCC and GDB distributions, and put the gcc asm(\|) extensions to good
270
This work was partly supported by EC-ESPRIT Basic Research Action SECOND.
added
removed
ffcall/avcall/avcall.3
