Calling conventions on the x86 platform

2005/02/13, Andreas Jönsson

This is a document that I wrote as research for the AngelCode Scripting Library. Since the library uses assembly to make the interaction between the script engine and the host application I needed to have complete knowledge of how the calling conventions are implemented by different compilers. To my surprise there were a lot more differences than I had initially thought. Most of the differences are related to C++ features, so the differences can be understood as there were no standard when the compilers were first written. Today there is a standard, but I believe that it doesn't mention how calling conventions should be implemented. Which leads to binary incompatibility between compilers, even though the source code is compatible.

The differences doesn't stop AngelScript from supporting each of the compilers. Though new compilers may have to make a few changes in order to follow the conventions used. As support for more compilers are added to AngelScript I will add those compilers to the article.

• cdecl
• stdcall
• thiscall
• fastcall
• further reading
• revision history

cdecl

This calling convention is the default for C programs and also global functions in C++ programs. Generally the function arguments are passed on the stack in reverse order so that the callee can access them in the correct order. The caller is responsible for popping the arguments after the function returns, which makes it possible to use the ... to send runtime defined arguments. Return values are returned in the registers.

Visual C++ / Win32

• Arguments are pushed on the stack in reverse order.
• The caller pops arguments after return.
• Primitive data types, except floating point values, are returned in EAX or EAX:EDX depending on the size.
• float and double are returned in fp0, i.e. the first floating point register.
• Simple data structures with 8 bytes or less in size are returned in EAX:EDX.
• Class objects that require special treatment by the exception handler are returned in memory. Classes with a defined constructor, destructor, or overloaded assignment operator are examples of these.
• Objects larger than 8 bytes are returned in memory.
• When a return is made in memory the caller passes a pointer to the memory location as the first parameter (hidden). The callee populates the memory, and returns the pointer. The caller pops the hidden pointer together with the rest of the arguments.

MinGW g++ / Win32

• Arguments are pushed on the stack in reverse order.
• The caller pops arguments after return.
• Primitive data types, except floating point values, are returned in EAX or EAX:EDX depending on the size.
• float and double are returned in fp0, i.e. the first floating point register.
• Objects with 8 bytes or less in size are returned in EAX:EDX.
• Objects larger than 8 bytes are returned in memory.
• Classes that have a destructor are returned in memory regardless of size.
• When a return is made in memory the caller passes a pointer to the memory location as the first parameter (hidden). The callee populates the memory, and returns the pointer. The callee pops the hidden pointer from the stack when returning.
• Classes that have a destructor are always passed by reference, even if the parameter is defined to be by value.

GCC g++ / Linux

• Arguments are pushed on the stack in reverse order.
• The caller pops arguments after return.
• Primitive data types, except floating point values, are returned in EAX or EAX:EDX depending on the size.
• float and double are returned in fp0, i.e. the first floating point register.
• All structures and classes are returned in memory regardless of complexity or size.
• When a return is made in memory the caller passes a pointer to the memory location as the first parameter (hidden). The callee populates the memory, and returns the pointer. The callee pops the hidden pointer from the stack when returning.
• Classes that have a destructor are always passed by reference, even if the parameter is defined to be by value.

stdcall

stdcall is the calling conventions used by the Win32 API. It is basically the same as the cdecl convention with the difference in that the callee is responsible for popping the arguments from the stack. This makes the call slightly faster, but also prevents the use of the ... operator.

Visual C++ / Win32

• Arguments are pushed on the stack in reverse order.
• The callee pops arguments when returning.
• Primitive data types, except floating point values, are returned in EAX or EAX:EDX depending on the size.
• float and double are returned in fp0, i.e. the first floating point register.
• Simple data structures with 8 bytes or less in size are returned in EAX:EDX.
• Class objects that require special treatment by the exception handler are returned in memory. Classes with a defined constructor, destructor, or overloaded assignment operator are examples of these.
• Objects larger than 8 bytes are returned in memory.
• When a return is made in memory the caller passes a pointer to the memory location as the first parameter (hidden). The callee populates the memory, and returns the pointer. The callee pops the hidden pointer together with the rest of the arguments.

MinGW g++ / Win32

• Arguments are pushed on the stack in reverse order.
• The callee pops arguments when returning.
• Primitive data types, except floating point values, are returned in EAX or EAX:EDX depending on the size.
• float and double are returned in fp0, i.e. the first floating point register.
• Objects with 8 bytes or less in size are returned in EAX:EDX.
• Objects larger than 8 bytes are returned in memory.
• Classes that have a destructor are returned in memory regardless of size.
• When a return is made in memory the caller passes a pointer to the memory location as the first parameter (hidden). The callee populates the memory, and returns the pointer. The callee pops the hidden pointer from the stack together with the rest of the arguments.
• Classes that have a destructor are always passed by reference, even if the parameter is defined to be by value.

GCC g++ / Linux

• Arguments are pushed on the stack in reverse order.
• The callee pops arguments when returning.
• Primitive data types, except floating point values, are returned in EAX or EAX:EDX depending on the size.
• float and double are returned in fp0, i.e. the first floating point register.
• All structures and classes are returned in memory regardless of complexity and size.
• When a return is made in memory the caller passes a pointer to the memory location as the first parameter (hidden). The callee populates the memory, and returns the pointer. The callee pops the hidden pointer from the stack together with the rest of the arguments.
• Classes that have a destructor are always passed by reference, even if the parameter is defined to be by value.

thiscall

This calling convention was introduced with C++. The only sure thing about it is that arguments are pushed on the stack in reverse order and that the caller passes the object pointer to the function in some way or other.

Visual C++ / Win32

• Arguments are pushed on the stack in reverse order.
• The object pointer is passed in ECX.
• The callee pops arguments when returning.
• Primitive data types, except floating point values, are returned in EAX or EAX:EDX depending on the size.
• float and double are returned in fp0, i.e. the first floating point register.
• Simple data structures with 8 bytes or less in size are returned in EAX:EDX.
• All classes and structures are returned in memory, regardless of size.
• When a return is made in memory the caller passes a pointer to the memory location as the first parameter (hidden). The callee populates the memory, and returns the pointer. The callee pops the hidden pointer together with the rest of the arguments.
• If the method takes variable number of arguments, i.e. is declared with the ... operator, then the calling convention instead becomes that of cdecl. The object pointer is pushed on the stack as the first argument instead of passed in ECX, and all arguments are popped from the stack by the caller when the function returns.

MinGW g++ / Win32

• Arguments are pushed on the stack in reverse order.
• The object pointer is pushed on the stack as the first parameter.
• The caller pops arguments after return.
• Primitive data types, except floating point values, are returned in EAX or EAX:EDX depending on the size.
• float and double are returned in fp0, i.e. the first floating point register.
• Objects with 8 bytes or less in size are returned in EAX:EDX.
• Objects larger than 8 bytes are returned in memory.
• Classes that have a destructor are returned in memory regardless of size.
• When a return is made in memory the caller passes a pointer to the memory location as the first parameter (hidden). The callee populates the memory, and returns the pointer. The callee pops the hidden pointer from the stack when returning.
• Classes that have a destructor are always passed by reference, even if the parameter is defined to be by value.

GCC g++ / Linux

• Arguments are pushed on the stack in reverse order.
• The object pointer is pushed on the stack as the first parameter.
• The caller pops arguments after return.
• Primitive data types, except floating point values, are returned in EAX or EAX:EDX depending on the size.
• float and double are returned in fp0, i.e. the first floating point register.
• All structures and classes are returned in memory regardless of complexity and size.
• When a return is made in memory the caller passes a pointer to the memory location as the first parameter (hidden). The callee populates the memory, and returns the pointer. The callee pops the hidden pointer from the stack when returning.
• Classes that have a destructor are always passed by reference, even if the parameter is defined to be by value.

fastcall

This is a special calling convention that is designed for speed. It is rarely used so I haven't studied it closely, but I understand that the first arguments are passed in registers while the rest are pushed on the stack as normal.

Visual C++ / Win32

• The first two arguments are passed in ECX and EDX. The rest are passed on the stack just like cdecl

Further reading

Not all of these articles are directly related to calling conventions, but they are still a worthy read for anyone interested in interacting with C++ programs on a truly low level.

• Calling conventions
• Microsoft Calling Conventions
• PC Assembly Language
• C++: Under the Hood
• Member Function Pointers and the Fastest Possible C++ Delegates

Revision history

• 2004/08/04 - Article created.
• 2005/01/19 - Added information on GCC/g++ on Linux. Made a few corrections on the way MinGW/g++ handles classes with declared destructors.
• 2005/02/13 - Added information about class methods with variable number of arguments for MSVC++.