Provided by: libffcall-dev_2.1-1_amd64 
NAME
avcall - build a C argument list incrementally and call a C function on it.
SYNOPSIS
#include <avcall.h>
av_alist alist;
av_start_type(alist, &func [[, return_type], &return_value ]);
av_type(alist, [arg_type,] value);
av_call(alist);
DESCRIPTION
This set of macros builds an argument list for a C function and calls the function on it.
It significantly reduces the amount of `glue' code required for parsers, debuggers,
imbedded interpreters, C extensions to application programs and other situations where
collections of functions need to be called on lists of externally-supplied arguments.
Function calling conventions differ considerably on different machines and avcall attempts
to provide some degree of isolation from such architecture dependencies.
The interface is like stdarg(3) in reverse. All of the macros return 0 for success, < 0
for failure (e.g., argument list overflow or type-not-supported).
(1) #include <avcall.h>
and declare the argument list structure
av_alist alist;
(2) Set any special flags. This is architecture and compiler dependent. Compiler
options that affect passing conventions may need to be flagged by #defines before
the #include <avcall.h> statement. However, the configure script should have
determined which #defines are needed and put them at the top of avcall.h.
(3) Initialize the alist with the function address and return value pointer (if any).
There is a separate macro for each simple return type ([u]char, [u]short, [u]int,
[u]long, [u]longlong, float, double, where `u' indicates `unsigned'). The macros
for functions returning structures or pointers require an explicit type argument.
E.g.,
av_start_int (alist, &func, &int_return);
av_start_double (alist, &func, &double_return);
av_start_void (alist, &func);
av_start_struct (alist, &func, struct_type, splittable,
&struct_return);
av_start_ptr (alist, &func, pointer_type,
&pointer_return);
The splittable flag specifies whether the struct_type can be returned in registers such
that every struct field fits entirely in a single register. This needs to be specified for
structs of size 2*sizeof(long). For structs of size <= sizeof(long), splittable is ignored
and assumed to be 1. For structs of size > 2*sizeof(long), splittable is ignored and
assumed to be 0. There are some handy macros for this:
av_word_splittable_1 (type1)
av_word_splittable_2 (type1, type2)
av_word_splittable_3 (type1, type2, type3)
av_word_splittable_4 (type1, type2, type3, type4)
For a struct with three slots
struct { type1 id1; type2 id2; type3 id3; }
you can specify splittable as av_word_splittable_3 (type1, type2, type3) .
(4) Push the arguments on to the list in order. Again there is a macro for each simple
built-in type, and the macros for structure and pointer arguments require an extra
type argument:
av_int (alist, int_value);
av_double (alist, double_value);
av_struct (alist, struct_or_union_type, struct_value);
av_ptr (alist, pointer_type, pointer_value);
(5) Call the function, set the return value, and tidy up:
av_call (alist);
NOTES
(1) Functions whose first declaration is in Kernighan & Ritchie style (i.e., without a
typed argument list) MUST use default K&R C expression promotions (char and short to int,
float to double) whether they are compiled by a K&R or an ANSI compiler, because the true
argument types may not be known at the call point. Such functions typically back-convert
their arguments to the declared types on function entry. (In fact, the only way to pass a
true char, short or float in K&R C is by an explicit cast: func((char)c,(float)f) ).
Similarly, some K&R compilers (such as Sun cc on the sparc) actually return a float as a
double.
Hence, for arguments of functions declared in K&R style you should use av_int() and
av_double() rather than av_char(), av_short() or av_float(). If you use a K&R compiler,
the avcall header files may be able to detect this and define av_float(), etc,
appropriately, but with an ANSI compiler there is no way avcall can know how a function
was declared, so you have to correct the argument types yourself.
(2) The explicit type arguments of the av_struct() and av_ptr() macros are typically used
to calculate size, alignment, and passing conventions. This may not be sufficient for
some machines with unusual structure and pointer handling: in this case additional
av_start_type() and av_type() macros may be defined.
(3) The macros av_start_longlong(), av_start_ulonglong(), av_longlong() and av_ulonglong()
work only if the C compiler has a working long long 64-bit integer type.
(4) The struct types used in av_start_struct() and av_struct() must only contain (signed
or unsigned) int, long, long long or pointer fields. Struct types containing (signed or
unsigned) char, short, float, double or other structs are not supported.
SEE ALSO
stdarg(3), varargs(3).
BUGS
The current implementations have been tested on a selection of common cases but there are
probably still many bugs.
There are typically built-in limits on the size of the argument-list, which may also
include the size of any structure arguments.
The decision whether a struct is to be returned in registers or in memory considers only
the struct's size and alignment. This is inaccurate: for example, gcc on m68k-next returns
struct { char a,b,c; } in registers and struct { char a[3]; } in memory, although both
types have the same size and the same alignment.
NON-BUGS
All information is passed in CPU registers and the stack. The avcall package is therefore
multithread-safe.
PORTING AVCALL
Ports, bug-fixes, and suggestions are most welcome. The macros required for argument
pushing are pretty grungy, but it does seem to be possible to port avcall to a range of
machines. Ports to non-standard or non-32-bit machines are especially welcome so we can
sort the interface out before it's too late.
Knowledge about argument passing conventions can be found in the gcc source, file
gcc-2.6.3/config/cpu/cpu.h, section "Stack layout; function entry, exit and calling."
Some of the grunge is usually handled by a C or assembly level glue routine that actually
pushes the arguments, calls the function and unpacks any return value. This is called
avcall_call(). A precompiled assembler version for people without gcc is also made
available. The routine should ideally have flags for the passing conventions of other
compilers.
Many of the current routines waste a lot of stack space and generally do hairy things to
stack frames - a bit more assembly code would probably help things along quite a bit here.
AUTHOR
Bill Triggs <Bill.Triggs@inrialpes.fr>.
ACKNOWLEDGEMENTS
Some initial ideas were stolen from the C interface to the Zelk extensions to Oliver
Laumann's Elk scheme interpreter by J.P.Lewis, NEC C&C Research, <zilla@ccrl.nj.nec.com>
(for Sun4 & SGI), and Roy Featherstone's <roy@robots.oxford.ac.uk> personal C interface
library for Sun[34] & SGI. I also looked at the machine-dependent parts of the GCC and
GDB distributions, and put the gcc asm() extensions to good use. Thanks guys!
This work was partly supported by EC-ESPRIT Basic Research Action SECOND.
23 July 2017 AVCALL(3)