previous
index
next

Dyncall C library API

The library provides low-level functionality to make foreign function calls from different run-time environments. The flexibility is constrained by the set of supported types. C interface style conventions

This manual and the dyncall library’s C interface "dyncall.h" use the following C source code style.

Subject C symbol Details Example




Types DC<type name> lower-case DCint, DCfloat, DClong, …
Structures DC<structure name> camel-case DCCallVM
Functions dc<function name> camel-case dcNewCallVM, dcArgInt, …
Table 9: C interface conventions

Supported C/C++ argument and return types

Type alias C/C++ data type


DCbool _Bool, bool
DCchar char
DCshort short
DCint int
DClong long
DClonglong long long
DCfloat float
DCdouble double
DCpointer void*
DCvoid void
Table 10: Supported C/C++ argument and return types

Call Virtual Machine - CallVM

This CallVM is the main entry to the functionality of the library. Types

typedef void DCCallVM; /* abstract handle */
Details

The CallVM is a state machine that manages all aspects of a function call from configuration, argument passing up the actual function call on the processor.

Allocation

Functions
DCCallVM* dcNewCallVM (DCsize size); 
void      dcFree(DCCallVM* vm);

dcNewCallVM creates a new CallVM object, where size specifies the max size of the internal stack that will be allocated and used to bind arguments to. Use dcFree to destroy the CallVM object.

This will allocate memory using the system allocators or custom ones provided custom dcAllocMem and dcFreeMem macros are defined to override the default behaviour. See dyncall_alloc.h for defails.

Error Reporting

Function
DCint dcGetError(DCCallVM* vm);

Returns the most recent error state code out of the following: Errors

Constant Description


DC_ERROR_NONE No error occured.
DC_ERROR_UNSUPPORTED_MODE Unsupported mode, caused by dcMode()
Table 11: CallVM calling convention modes

Configuration

Function
void dcMode (DCCallVM* vm, DCint mode);

Sets the calling convention to use. Note that some mode/platform combination don’t make any sense (e.g. using a PowerPC calling convention on a MIPS platform) and are silently ignored. Modes

Constant Description


DC_CALL_C_DEFAULT C default function call for current platform
DC_CALL_C_ELLIPSIS C ellipsis function call (named arguments (before ’...’))
DC_CALL_C_ELLIPSIS_VARARGS C ellipsis function call (variable/unnamed arguments (after ’...’))
DC_CALL_C_X86_CDECL C x86 platforms standard call
DC_CALL_C_X86_WIN32_STD C x86 Windows standard call
DC_CALL_C_X86_WIN32_FAST_MS C x86 Windows Microsoft fast call
DC_CALL_C_X86_WIN32_FAST_GNU C x86 Windows GCC fast call
DC_CALL_C_X86_WIN32_THIS_MS C x86 Windows Microsoft this call
DC_CALL_C_X86_WIN32_THIS_GNU C x86 Windows GCC this call
DC_CALL_C_X86_PLAN9 C x86 Plan9 call
DC_CALL_C_X64_WIN64 C x64 Windows standard call
DC_CALL_C_X64_SYSV C x64 System V standard call
DC_CALL_C_PPC32_DARWIN C ppc32 Mac OS X standard call
DC_CALL_C_PPC32_OSX alias for DC_CALL_C_PPC32_DARWIN
DC_CALL_C_PPC32_SYSV C ppc32 SystemV standard call
DC_CALL_C_PPC32_LINUX alias for DC_CALL_C_PPC32_SYSV
DC_CALL_C_PPC64 C ppc64 SystemV standard call
DC_CALL_C_PPC64_LINUX alias for DC_CALL_C_PPC64
DC_CALL_C_ARM_ARM C arm call (arm mode)
DC_CALL_C_ARM_THUMB C arm call (thumb mode)
DC_CALL_C_ARM_ARM_EABI C arm eabi call (arm mode)
DC_CALL_C_ARM_THUMB_EABI C arm eabi call (thumb mode)
DC_CALL_C_ARM_ARMHF C arm call (arm hardfloat - e.g. raspberry pi)
DC_CALL_C_ARM64 C arm64 call (AArch64)
DC_CALL_C_MIPS32_EABI C mips32 eabi call
DC_CALL_C_MIPS32_PSPSDK alias for DC_CALL_C_MIPS32_EABI (deprecated)
DC_CALL_C_MIPS32_O32 C mips32 o32 call
DC_CALL_C_MIPS64_N64 C mips64 n64 call
DC_CALL_C_MIPS64_N32 C mips64 n32 call
DC_CALL_C_SPARC32 C sparc32 call
DC_CALL_C_SPARC64 C sparc64 call
DC_CALL_SYS_DEFAULT C default syscall for current platform
DC_CALL_SYS_X86_INT80H_BSD C syscall for x86 BSD platforms
DC_CALL_SYS_X86_INT80H_LINUX C syscall for x86 Linux
DC_CALL_SYS_PPC32 C syscall for ppc32
DC_CALL_SYS_PPC64 C syscall for ppc64
Table 12: CallVM calling convention modes
Details

DC_CALL_C_DEFAULT is the default standard C call on the target platform. It uses the standard C calling convention. DC_CALL_C_ELLIPSIS is used for C ellipsis calls which allow to build up a variable argument list. On many platforms, there is only one C calling convention. The X86 platform provides a rich family of different calling conventions.

Machine state reset

void dcReset(DCCallVM* vm);

Resets the internal stack of arguments and prepares it for a new call. This function should be called after setting the call mode (using dcMode), but prior to binding arguments to the CallVM. Use it also when reusing a CallVM, as arguments don’t get flushed automatically after a function call invocation.
Note: you should also call this function after initial creation of the a CallVM object, as dcNewCallVM doesn’t do this, implicitly.

Argument binding

Functions
void dcArgBool    (DCCallVM* vm, DCbool     arg); 
void dcArgChar    (DCCallVM* vm, DCchar     arg); 
void dcArgShort   (DCCallVM* vm, DCshort    arg); 
void dcArgInt     (DCCallVM* vm, DCint      arg); 
void dcArgLong    (DCCallVM* vm, DClong     arg); 
void dcArgLongLong(DCCallVM* vm, DClonglong arg); 
void dcArgFloat   (DCCallVM* vm, DCfloat    arg); 
void dcArgDouble  (DCCallVM* vm, DCdouble   arg); 
void dcArgPointer (DCCallVM* vm, DCpointer  arg);
Details

Used to bind arguments of the named types to the CallVM object. Arguments should be bound in left-to-right order regarding the C function prototype.

Call invocation

Functions
DCvoid     dcCallVoid    (DCCallVM* vm, DCpointer funcptr); 
DCbool     dcCallBool    (DCCallVM* vm, DCpointer funcptr); 
DCchar     dcCallChar    (DCCallVM* vm, DCpointer funcptr); 
DCshort    dcCallShort   (DCCallVM* vm, DCpointer funcptr); 
DCint      dcCallInt     (DCCallVM* vm, DCpointer funcptr); 
DClong     dcCallLong    (DCCallVM* vm, DCpointer funcptr); 
DClonglong dcCallLongLong(DCCallVM* vm, DCpointer funcptr); 
DCfloat    dcCallFloat   (DCCallVM* vm, DCpointer funcptr); 
DCdouble   dcCallDouble  (DCCallVM* vm, DCpointer funcptr); 
DCpointer  dcCallPointer (DCCallVM* vm, DCpointer funcptr);
Details

Calls the function specified by funcptr with the arguments bound to the CallVM and returns. Use the function that corresponds to the dynamically called function’s return value.

After the invocation of the foreign function call, the argument values are still bound and a second call using the same arguments can be issued. If you need to clear the argument bindings, you have to reset the CallVM.

Formatted argument binding and calls (ANSI C ellipsis interface)

Functions
void dcArgF  (DCCallVM* vm, const DCsigchar* signature, ...); 
void dcVArgF (DCCallVM* vm, const DCsigchar* signature, va_list args); 
void dcCallF (DCCallVM* vm, DCValue* result, DCpointer funcptr, 
              const DCsigchar* signature, ...); 
void dcVCallF(DCCallVM* vm, DCValue* result, DCpointer funcptr, 
              const DCsigchar* signature, va_list args);
Details

These functions can be used to operate dyncall via a printf-style functional interface, using a signature string encoding the argument types and return type. dcArgF() and dcVArgF() just bind arguments to the DCCallVM object, so any return value specified in the signature is ignored. dcCallF() and dcVCallF() also take a function pointer to call after binding the arguments. The return value will be stored in what result points to. For more information about the signature format, refer to 2.


previous
index
next