Overview

The dyncall library encapsulates architecture-, OS- and compiler-speciﬁc function call semantics in a virtual bind argument parameters from left to right and then call interface allowing programmers to call C functions in a completely dynamic manner. In other words, instead of calling a function directly, the dyncall library provides a mechanism to push the function parameters manually and to issue the call afterwards.
Since the idea behind this concept is similar to call dispatching mechanisms of virtual machines, the object that can be dynamically loaded with arguments, and then used to actually invoke the call, is called CallVM. It is possible to change the calling convention used by the CallVM at run-time. Due to the fact that nearly every platform comes with one or more distinct calling conventions, the dyncall library project intends to be a portable and open-source approach to the variety of compiler-speciﬁc binary interfaces, platform speciﬁc subtleties, and so on…

The core of the library consists of dynamic implementations of diﬀerent calling conventions written in assembler. Although the library aims to be highly portable, some assembler code needs to be written for nearly every platform/compiler/OS combination. Unfortunately, there are architectures we just don’t have at home or work. If you want to see dyncall running on such a platform, feel free to send in code and patches, or even to donate hardware you don’t need anymore. Check the supported platforms section for an overview of the supported platforms and the diﬀerent calling convention sections for details about the support.

Features

A portable and extendable function call interface for the C programming language.
Ports to major platforms including Windows, Mac OS X, Linux, BSD derivates, iPhone and embedded devices and more, including lesser known and/or older platforms like Plan 9, Playstation Portable, Nintendo DS, etc..
Add-on language bindings to Python, R, Ruby, Go, Erlang, Java, Lua, sh, ...
High-level state machine design using C to model calling convention parameter transfer.
One assembly hybrid call routine per calling convention.
Formatted call, vararg function API.
Comprehensive test suite.

Showcase

Foreign function call in C

This section demonstrates how the foreign function call is issued without, and then with, the help of the dyncall library and scripting language bindings.

double call_as_sqrt(void* funptr, double x)
{
return ( ( double (*)(double) )funptr)(x);
}

Listing 3: Foreign function call in C

Dyncall C library example

The same operation can be broken down into atomic pieces (specify calling convention, binding arguments, invoking the call) using the dyncall library.

#include <dyncall.h>
double call_as_sqrt(void* funptr, double x)
{
  double r;
  DCCallVM* vm = dcNewCallVM(4096);
  dcMode(vm, DC_CALL_C_DEFAULT);
  dcReset(vm);
  dcArgDouble(vm, x);
  r = dcCallDouble(vm, funptr);
  dcFree(vm);
  return r;
}

Listing 4: Dyncall C library example

This is more code than a direct, hardcoded function call, however it’s completely dynamic. Also, despite this coming with an overhead of more executed code per single function call, compared to function interface wrapper tools that generate per call glue-code less code is used overall, .

The following are examples from script bindings: Python example

import pydc
def call_as_sqrt(funptr,x):
return pydc.call(funptr,"d)d", x)

Listing 5: Dyncall Python bindings example

R example

call.as.sqrt <- function(funptr,x)
.dyncall(funptr,"d)d", x)

Listing 6: Dyncall R bindings example

Supported platforms/architectures

The feature matrix below gives a brief overview of the currently supported platforms. Diﬀerent colors are used, where a green cell indicates a supported platform, with both, call and callback support, yellow a platform that might work (but is untested) and red a platform that is currently unsupported. Gray cells are combinations that don’t exist at the time of writing, or that are not taken into account.
Light green cells mark complete feature support, including passing aggregates (struct, union) by value. Dark green means basic support but lacking lesser used features (e.g. no aggregate-by-value support). Please note that a green cell (even a light-green one) doesn’t imply that all existing calling conventions/features/build tools are supported for that platform (but the most important).

| | | | | | | | | | | |
| | | | | | | | | | | |
| | | | | | | | | | | |
| | | | | | | | | | | |
| | | | | | | | | | | |
| | | | | | | | | | | |
| | | | | | | | | | | |
| | | | | | | | | | | |
| | | | | | | | | | | |
| | | | | | | | | | | |
Windows family Linux | macOS /|iOS / DarwFinreeBSD | NetBSD | OpenBSD | DragonFlyBSD Solaris / SunOS Plan 9 / 9front Haiku / BeOS Minix | Playstation Portable (NEiAnBtIe)ndo DS
| -EB----cellcolorgray1---|--cellcoloryellow---|--cellcolorgray1--|--cellcoloryellow---|--cellcoloryellow---|-cellcoloryellow---|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---
ARM EL cellcoloryellow | cellcolordarkgreen |cellcolordarkgreen | cellcolordarkgreen |cellcolordarkgreen |cellcolordarkgreen | cellcolorgray1 | cellcolorgray1 | cellcolorred | cellcolorgray1 | cellcoloryellow | cellcolorgray1 | cellcolordarkgreen
-------------------------------|----------------|---------------|----------------|----------------|---------------|----------------|---------------|----------------|---------------|----------------|---------------|-----------------
| ARM64 -EB----cellcolorgray1---|--cellcoloryellow---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---
------------EL--cellcolordarkgreen-|-cellcolordarkgreen-|cellcolordarkgreen-|-cellcolordarkgreen-|--cellcoloryellow---|cellcolordarkgreen-|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1----
| -EB----cellcolorgray1---|-cellcolordarkgreen-|--cellcolorgray1--|-cellcolordarkgreen-|--cellcoloryellow---|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1--|---cellcolorred----|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---
MIPS EL cellcolorgray1 | cellcoloryellow | cellcolorgray1 | cellcolordarkgreen |cellcolordarkgreen | cellcoloryellow | cellcolorgray1 | cellcolorgray1 | cellcolorred | cellcolorgray1 | cellcolorgray1 |cellcolordarkgreen | cellcolorgray1
-------------------------------|----------------|---------------|----------------|----------------|---------------|----------------|---------------|----------------|---------------|----------------|---------------|-----------------
| MIPS64 -EB----cellcolorgray1---|--cellcoloryellow---|--cellcolorgray1--|-cellcolordarkgreen-|--cellcoloryellow---|cellcolordarkgreen-|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---
------------EL----cellcolorgray1---|-cellcolordarkgreen-|--cellcolorgray1--|-cellcolordarkgreen-|--cellcoloryellow---|-cellcoloryellow---|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1----
| -EB----cellcolorgray1---|---cellcolorred----|--cellcolorgray1--|--cellcolorgray1---|---cellcolorred----|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---
SuperH EL cellcolorgray1 | cellcolorred | cellcolorgray1 | cellcolorgray1 | cellcolorred | cellcolorred | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1
-------------------------------|----------------|---------------|----------------|----------------|---------------|----------------|---------------|----------------|---------------|----------------|---------------|-----------------
| PowerPC -EB----cellcolorgray1---|-cellcolordarkgreen-|cellcolordarkgreen-|-cellcolordarkgreen-|cellcolordarkgreen--|-cellcoloryellow---|--cellcolorgray1---|--cellcolorgray1--|---cellcolorred----|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---
------------EL----cellcolorgray1---|--cellcoloryellow---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1----
| -EB----cellcolorgray1---|-cellcolordarkgreen-|--cellcoloryellow---|-cellcolordarkgreen-|--cellcolorgray1---|-cellcoloryellow---|--cellcolorgray1---|--cellcolorgray1--|---cellcolorred----|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---
PowerPC64 EL cellcolorgray1 | cellcolordarkgreen | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1
-------------------------------|----------------|---------------|----------------|----------------|---------------|----------------|---------------|----------------|---------------|----------------|---------------|-----------------
------m68k--------cellcolorgray1---|---cellcolorred----|--cellcolorgray1--|--cellcolorgray1---|---cellcolorred----|---cellcolorred----|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1----
------m88k--------cellcolorgray1---|---cellcolorred----|--cellcolorgray1--|--cellcolorgray1---|---cellcolorred----|---cellcolorred----|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1----
-------x86------cellcolordarkgreen---cellcolordarkgreen--cellcolordarkgreen---cellcolordarkgreen--cellcolordarkgreen---cellcolordarkgreen--cellcolordarkgreen--cellcolordarkgreen---cellcolordarkgreen--cellcolordarkgreen---cellcolordarkgreen----cellcolorgray1-----cellcolorgray1----
x64 cellcolorlightgreen | cellcolorlightgreen |cellcolorlightgreen | cellcolorlightgreen |cellcolorlightgreen |cellcolorlightgreen |cellcolorlightgreen |cellcolorlightgreen | cellcolorred |cellcolorlightgreen | cellcolorgray1 | cellcolorgray1 | cellcolorgray1
-------------------------------|----------------|---------------|----------------|----------------|---------------|----------------|---------------|----------------|---------------|----------------|---------------|-----------------
----Itanium---------cellcolorred----|---cellcolorred----|--cellcolorgray1--|---cellcolorred----|---cellcolorred----|---cellcolorred----|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1----
----SPARC---------cellcolorgray1---|-cellcolordarkgreen-|--cellcolorgray1--|--cellcolorgray1---|cellcolordarkgreen--|cellcolordarkgreen-|--cellcolorgray1---|cellcolordarkgreen-|---cellcolorred----|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1----
SPARC64 cellcolorgray1 | cellcolordarkgreen | cellcolorgray1 | cellcolordarkgreen |cellcolordarkgreen |cellcolordarkgreen | cellcolorgray1 |cellcolordarkgreen | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1
----RISC-V--------cellcolorgray1---|---cellcolorred----|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1---|--cellcolorgray1--|--cellcolorgray1----
-------------------------------|----------------|---------------|----------------|----------------|---------------|----------------|---------------|----------------|---------------|----------------|---------------|-----------------
RISC -V 64 cellcolorgray1 | cellcolorred | cellcolorgray1 | cellcolorred | cellcolorgray1 | cellcolorred | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1 | cellcolorgray1

Table 1: Supported platforms

Build Requirements

The library needs at least a c99 compiler with additional support for anonymous structs/unions (which were introduced oﬃcially in c11). Given that those are generally supported by pretty much all major c99 conforming compilers (as default extension), it should build ﬁne with a c99 toolchain.

index