Calling convention

A Calling Convention is a method for a programming language to send data to a function, and receive data back from functions. When writing a piece of software in multiple languages and modules, it is necessary for all modules to use compatible calling conventions.

Calling conventions differ in the method for sending data to a function, receiving return data from a function, and methods of Name mangling.

cdecl

The cdecl calling convention is the standard convention used by C and C++. In cdecl, function parameters are passed on the stack in a Right-to-Left order. Function return values are returned in the EAX register (for x86 architecture. Registers EAX, ECX, and EDX are available for use in the function. The calling function cleans the stack, so functions may utilize a variable-length argument list (printf is the canonical example of a function with a variable argument list).

For instance, the following C code function prototype and function call:

int function(int, int, int);
int a, b, c, x;
...
x = function(a, b, c);

will produce the following x86 Assembly code*:

push c
push b
push a
call function
add esp, 12
mov x, eax

The calling function cleans the stack after the function call returns.

As an example, the following function call with a variable argument list:

#include <stdarg.h> //for variable argument lists
int function(int, ...);
int a, b, c, x;
...
x = function(a, b, c);

will produce the same exact x86 Assembly code*:

push c
push b
push a
call function
add esp, 12
mov x, eax

The cdecl calling convention is the default calling convention in C, although many compilers provide options to automatically change the calling conventions used. To manually define a function to be cdecl, the following syntax may be used:

void _cdecl function(params);

The _cdecl modifier must be included in the function prototype, and in the function declaration to override any other settings that might be in place.

*assembly code written with MASM syntax

Pascal

The Pascal calling convention is the reverse of the C calling convention. The parameters are pushed on the stack in left-to-right order and the callee is responsible for balancing the stack before return.

Register

The Register or FastCall calling convention is compiler specific, for specific information, consult a compilers documentation. In general however, the register calling convention states that the first 2 or 3 function arguments with a size of 32 bits or lower will be passed in the EAX, EDX, and possibly ECX registers instead of on the stack. The remaining arguments are passed right-to-left on the stack similar to cdecl. Return values are passed in the AL, AX, or EAX register.

stdcall

The stdcall calling convention is the de facto standard calling convention for Microsoft Windows NT programming API. Function parameters are passed Right-to-Left. Registers EAX, ECX, and EDX are preserved for use within the function. Return values are stored in the EAX register. Unlike cdecl, the called function cleans the stack, unlike the calling function. Because of this fact, stdcall functions cannot support variable-length argument lists.

On a Microsoft Windows system, a function may be declared to be stdcall using the following syntax in the function prototype, and in the function declaration:

void _stdcall function(params);

safecall

thiscall

The thiscall calling convention is the default calling convention for the C++ programming language. In the thiscall calling convention, function parameters are passed on the stack from right to left, and the this pointer is passed in the ECX register. Function results are returned in the AL, AX, or the EAX register.

Intel ABI

The Intel Application Binary Interface is a computer programming standard that most compilers and languages follow. According to the Intel ABI, the EAX, EDX, and ECX are to be free for use within a procedure or function, and need not be preserved.

Standard Exit and Entry Sequences

The standard entry sequence to a function is as follows:

_function:
    push ebp       ;store the old base pointer
    mov ebp, esp   ;make the base pointer point to the current stack location
                   ;which is where the parameters are
    add esp, x     ;x is the size, in bytes, of all "automatic variables"
                   ;in the function

This sequence preserves the original base pointer ebp, points ebp to the location of the function parameters on the stack, and creates space for automatic variables on the stack. Local variables are created on the stack with each call to the function, and are cleaned up at the end of each function. This behavior allows for functions to be called recursively. In C and C++, variables declared "automatic" are created in this way.

The Standard Exit Sequence goes as follows:

    mov esp, ebp   ;reset the stack to "clean" away the local variables
    pop ebp        ;restore the original base pointer
    ret            ;return from the function

The following C function:

int _cdecl MyFunction(int i){ 
    int k;
    return i + k;
}

would produce the equivalent asm code:

    ;entry sequence
    push ebp
    mov ebp, esp
    add esp, 4     ;create space for "int k"

    ;function code
    mov eax, [ebp + 0] 
                   ;move parameter i to accumulator
    add eax, [esp + 0]
                   ;add k to i
                   ;answer is returned in eax

    ;exit sequence
    mov esp, ebp
    pop ebp
    ret

External links

The Code Project—Calling Conventions Demystified