In computer science, a calling convention is a scheme for how subroutines receive parameters from their caller and how they return a result; calling conventions can differ in:...
s used on the x86 architecture.
Calling conventions describe the interface of called code:
The order in which atomic (scalar) parameters, or individual parts of a complex parameter, are allocated
How parameters are passed (pushed on the stack, placed in registers, or a mix of both)
Which registers may be used by the callee without first being saved (i.e. pushed)
How the task of setting up for and restoring the stack after a function call is divided between the caller and the callee
This is intimately related with the assignment of sizes and formats to programming-language types.
Another closely related topic is name mangling
Name mangling
In compiler construction, name mangling is a technique used to solve various problems caused by the need to resolve unique names for programming entities in many modern programming languages....
, which determines how symbol names in the code map to symbol names used by the linker. Calling conventions, type representations, and name mangling are all part of what is known as an Application Binary Interface
Application binary interface
In computer software, an application binary interface describes the low-level interface between an application program and the operating system or another application.- Description :...
(ABI).
There are often subtle differences in how various compilers implement these conventions, so it is often difficult to interface code which is compiled by different compilers. On the other hand, conventions which are used as an API standard (such as stdcall) are necessarily very uniformly implemented.
A microcomputer is a computer with a microprocessor as its central processing unit. They are physically small compared to mainframe and minicomputers...
s, the machine manufacturer generally provided an operating system
Operating system
An operating system is a set of programs that manage computer hardware resources and provide common services for application software. The operating system is the most important type of system software in a computer system...
and compilers for several programming languages. The calling conventions adopted for the platform were those defined by the manufacturer's software implementation.
The Apple II series is a set of 8-bit home computers, one of the first highly successful mass-produced microcomputer products, designed primarily by Steve Wozniak, manufactured by Apple Computer and introduced in 1977 with the original Apple II...
generally came "bare" of an OS or compilers, as did the IBM PC
IBM PC
The IBM Personal Computer, commonly known as the IBM PC, is the original version and progenitor of the IBM PC compatible hardware platform. It is IBM model number 5150, and was introduced on August 12, 1981...
IBM PC compatible computers are those generally similar to the original IBM PC, XT, and AT. Such computers used to be referred to as PC clones, or IBM clones since they almost exactly duplicated all the significant features of the PC architecture, facilitated by various manufacturers' ability to...
machines was defined by the Intel processors (8086, 80386) and the literal hardware IBM shipped. Hardware extensions and all software standards
Standards (software)
A software standard is a standard, protocol, or other common format of a document, file, or data transfer accepted and used by one or more software developers while working on one or more than one software programs...
In IBM PC compatible computers, the basic input/output system , also known as the System BIOS or ROM BIOS , is a de facto standard defining a firmware interface....
calling convention) were thrown open to market competition.
A multitude of independent software firms offered operating systems, compilers for many programming languages, and applications. Many different calling schemes were implemented by the firms, often mutually exclusive, based on different requirements, historical practices, and programmer creativity.
After the IBM compatible market shakeout, Microsoft
Microsoft
Microsoft Corporation is an American public multinational corporation headquartered in Redmond, Washington, USA that develops, manufactures, licenses, and supports a wide range of products and services predominantly related to computing through its various product divisions...
operating systems and programming tools (with differing conventions) predominated, while second tier firms like Borland
Borland
Borland Software Corporation is a software company first headquartered in Scotts Valley, California, Cupertino, California and finally Austin, Texas. It is now a Micro Focus subsidiary. It was founded in 1983 by Niels Jensen, Ole Henriksen, Mogens Glad and Philippe Kahn.-The 1980s:...
Novell, Inc. is a multinational software and services company. It is a wholly owned subsidiary of The Attachmate Group. It specializes in network operating systems, such as Novell NetWare; systems management solutions, such as Novell ZENworks; and collaboration solutions, such as Novell Groupwise...
The GNU Compiler Collection is a compiler system produced by the GNU Project supporting various programming languages. GCC is a key component of the GNU toolchain...
, still maintained their own standards. Provisions for inter-operability between vendors and products were eventually adopted, simplifying the problem of choosing a viable convention.
Caller clean-up
In these conventions the caller cleans the arguments from the stack, which allows for variable argument lists, eg. printf.
cdecl
The cdecl calling convention is used by many C systems for the x86 architecture
X86 architecture
The term x86 refers to a family of instruction set architectures based on the Intel 8086 CPU. The 8086 was launched in 1978 as a fully 16-bit extension of Intel's 8-bit based 8080 microprocessor and also introduced segmentation to overcome the 16-bit addressing barrier of such designs...
. In cdecl, function parameters are pushed on the stack
Call stack
In computer science, a call stack is a stack data structure that stores information about the active subroutines of a computer program. This kind of stack is also known as an execution stack, control stack, run-time stack, or machine stack, and is often shortened to just "the stack"...
in a right-to-left order. Function return values are returned in the EAX register
Processor register
In computer architecture, a processor register is a small amount of storage available as part of a CPU or other digital processor. Such registers are addressed by mechanisms other than main memory and can be accessed more quickly...
(except for floating point values, which are returned in the x87 register ST0). Registers EBX, ECX, and EDX are available for use in the function.
On Linux, GCC sets the de facto standard for calling conventions. Since GCC 4.5 the stack must be aligned to a 16-byte boundary when calling a function (previous versions only required a 4-byte alignment).
For instance, the following C code function prototype and function call:
int function_name(int, int, int);
int a, b, c, x;
...
x = function_name(a, b, c);
x86 assembly language is a family of backward-compatible assembly languages, which provide some level of compatibility all the way back to the Intel 8008. x86 assembly languages are used to produce object code for the x86 class of processors, which includes Intel's Core series and AMD's Phenom and...
(written in MASM (intel) syntax, with destination first):
push c ; arg 3
push b ; arg 2
push a ; arg 1
call function_name ; jump to function_name's code
add esp, 12 ; pop function args (a, b, c) off the stack
mov x, eax ; fetch function return value
The calling function cleans the stack after the function call returns.
There are some variations in the interpretation of cdecl, particularly in how to return values. As a result, x86 programs compiled for different operating system platforms and/or by different compilers can be incompatible, even if they both use the "cdecl" convention and do not call out to the underlying environment. Some compilers return simple data structures with the length of 2 registers or less in EAX:EDX, and larger structures and class objects requiring special treatment by the exception handler (e.g., a defined constructor, destructor, or assignment) are returned in memory. To pass "in memory", the caller allocates memory and passes a pointer to it as a hidden first parameter; the callee populates the memory and returns the pointer, popping the hidden pointer when returning.
In Linux/GCC, double/floating point values should be pushed on the stack via the x87
X87
x87 is a floating point-related subset of the x86 architecture instruction set. It originated as an extension of the 8086 instruction set in the form of optional floating point coprocessors that worked in tandem with corresponding x86 CPUs. These microchips had names ending in "87"...
pseudo-stack. Like so:
sub esp,8; make room for the double
fld [ebp+x]; load our double onto the floating point stack
fstp [esp]; push our double onto the stack
call func;
add esp,8;
Using this method ensures it is pushed on the stack in the correct format.
The cdecl calling convention is usually the default calling convention for x86 C compilers, although many compilers provide options to automatically change the calling conventions used. To manually define a function to be cdecl, some support the following syntax:
void _cdecl function_name(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.
syscall
This is similar to cdecl in that arguments are pushed right to left. EAX, ECX, and EDX are not preserved. The size of the parameter list in doublewords is passed in AL.
Syscall is the standard calling convention for 32 bit OS/2
OS/2
OS/2 is a computer operating system, initially created by Microsoft and IBM, then later developed by IBM exclusively. The name stands for "Operating System/2," because it was introduced as part of the same generation change release as IBM's "Personal System/2 " line of second-generation personal...
API.
optlink
Arguments are pushed right to left. The three lexically first (leftmost) arguments are passed in EAX, EDX, and ECX and up to four floating-point arguments are passed in ST(0) through ST(3), although space for them is reserved in the argument list on the stack. Results are returned in EAX or ST(0). Registers EBP, EBX, ESI, and EDI are preserved.
International Business Machines Corporation or IBM is an American multinational technology and consulting corporation headquartered in Armonk, New York, United States. IBM manufactures and sells computer hardware and software, and it offers infrastructure, hosting and consulting services in areas...
VisualAge was the name of a family of computer integrated development environments from IBM, which included support for multiple programming languages. VisualAge was first released in the 1980s and is still available in 2011...
compilers.
Callee clean-up
When the callee cleans the arguments from the stack it needs to be known at compile time how many bytes the stack needs to be adjusted. Therefore, these calling conventions are not compatible with variable argument lists, eg. printf. They may be, however, more space efficient, as the code needed to unwind the stack does not need to be generated for each call.
Functions which utilize these conventions are easy to recognize in ASM code because they will unwind the stack prior to returning. The x86 ret instruction allows an optional 16-bit parameter that specifies the number of stack bytes to unwind before returning to the caller. Such code looks like this:
Pascal is an influential imperative and procedural programming language, designed in 1968/9 and published in 1970 by Niklaus Wirth as a small and efficient language intended to encourage good programming practices using structured programming and data structuring.A derivative known as Object Pascal...
's calling convention, the parameters are pushed on the stack in left-to-right order (opposite of cdecl), and the callee is responsible for balancing the stack before return.
This calling convention was common in the following 16-bit APIs: OS/2
OS/2
OS/2 is a computer operating system, initially created by Microsoft and IBM, then later developed by IBM exclusively. The name stands for "Operating System/2," because it was introduced as part of the same generation change release as IBM's "Personal System/2 " line of second-generation personal...
Microsoft Windows is a series of operating systems produced by Microsoft.Microsoft introduced an operating environment named Windows on November 20, 1985 as an add-on to MS-DOS in response to the growing interest in graphical user interfaces . Microsoft Windows came to dominate the world's personal...
Embarcadero Delphi is an integrated development environment for console, desktop graphical, web, and mobile applications.Delphi's compilers use its own Object Pascal dialect of Pascal and generate native code for 32- and 64-bit Windows operating systems, as well as 32-bit Mac OS X and iOS...
version 1.x.
stdcall
The stdcall calling convention is a variation on the pascal calling convention in which the callee is responsible for cleaning up the stack, but the parameters are pushed onto the stack in right-to-left order, as in the _cdecl calling convention. Registers EAX, ECX, and EDX are designated for use within the function. Return values are stored in the EAX register.
stdcall is the standard calling convention for the Microsoft Win32 API and for Open Watcom C++.
fastcall
Conventions entitled fastcall have not been standardized, and have been implemented differently, depending on the compiler vendor. Typically fastcall calling conventions pass one or more arguments in registers which reduces the number of memory accesses required for the call.
The GNU Compiler Collection is a compiler system produced by the GNU Project supporting various programming languages. GCC is a key component of the GNU toolchain...
__fastcall convention (aka __msfastcall) passes the first two arguments (evaluated left to right) that fit into ECX and EDX. Remaining arguments are pushed onto the stack from right to left.
Borland fastcall
Evaluating arguments from left to right, it passes three arguments via EAX, EDX, ECX. Remaining arguments are pushed onto the stack, also left to right.
It is the default calling convention of the 32 bit compiler of Embarcadero Delphi, where it is known as register.
Watcom International Corporation was founded in 1981 by three former employees of the Computer Systems Group at the University of Waterloo, in Waterloo, Ontario, Canada...
does not support the __fastcall keyword except to alias it to null. The register calling convention may be selected by command line switch. (However, IDA
Interactive Disassembler
The Interactive Disassembler, more commonly known as simply IDA, is a disassembler for computer software which generates assembly language source code from machine-executable code. It supports a variety of executable formats for different processors and operating systems. It also can be used as a...
uses __fastcall anyway for uniformity)
Up to 4 registers are assigned to arguments in the order eax, edx, ebx, ecx. Arguments are assigned to registers from left to right. If any argument cannot be assigned to a register (say it is too large) it, and all subsequent arguments, are assigned to the stack. Arguments assigned to the stack are pushed from right to left. Names are mangled by adding a suffixed underscore.
Variadic functions fall back to the Watcom stack based calling convention.
The Watcom C/C++ compiler also uses the #pragma aux directive that allows the user to specify his own calling convention. As its manual states, "Very few users are likely to need this method, but if it is needed, it can be a lifesaver".
TopSpeed / Clarion / JPI
The first four integer parameters are passed in registers eax, ebx, ecx and edx. Floating point parameters are passed on the floating point stack – registers st0, st1, st2, st3, st4, st5 and st6. Structure parameters are always passed on the stack. Additional parameters are passed on the stack after registers are exhausted. Integer values are returned in eax, pointers in edx and floating point types in st0.
Free Pascal Compiler is a free Pascal and Object Pascal compiler.In addition to its own Object Pascal dialect, Free Pascal supports, to varying degrees, the dialects of several other compilers, including those of Turbo Pascal, Delphi, and some historical Macintosh compilers...
Microsoft Windows is a series of operating systems produced by Microsoft.Microsoft introduced an operating environment named Windows on November 20, 1985 as an add-on to MS-DOS in response to the growing interest in graphical user interfaces . Microsoft Windows came to dominate the world's personal...
Component Object Model is a binary-interface standard for software componentry introduced by Microsoft in 1993. It is used to enable interprocess communication and dynamic object creation in a large range of programming languages...
) error handling, thus exceptions aren't leaked out to the caller, but are reported in the HRESULT
HRESULT
In the field of computer programming, the HRESULT is a data type used in many types of Microsoft technology. HRESULTs are used as function parameters and return values to describe errors and warnings in a program....
return value, as required by COM/OLE. When calling a safecall function from Delphi code, Delphi also automatically checks the returned HRESULT and raises an exception if necessary.
The safecall calling convention is the same as the stdcall calling convention, except that exceptions are passed back to the caller in EAX as a HResult (instead of in FS:[0]), while the function result is passed by reference on the stack as though it were a final "out" parameter. When calling a Delphi function from Delphi this calling convention will appear just like any other calling convention, because although exceptions are passed back in EAX, they are automatically converted back to proper exceptions by the caller. When using COM objects created in other languages, the HResults will be automatically raised as exceptions, and the result for Get functions is in the result rather than a parameter. When creating COM objects in Delphi with safecall, there is no need to worry about HResults, as exceptions can be raised as normal but will be seen as HResults in other languages.
function function_name(a: DWORD): DWORD; safecall;
Returns a result and raises exceptions like a normal Delphi function, but it passes values and exceptions as though it was:
function function_name(a: DWORD; out Result: DWORD): HResult; stdcall;
thiscall
This calling convention is used for calling C++ non-static member functions. There are two primary versions of thiscall used depending on the compiler and whether or not the function uses variable arguments.
For the GCC compiler, thiscall is almost identical to cdecl: the calling function cleans the stack, and the parameters are passed in right-to-left order. The difference is the addition of the this pointer, which is pushed onto the stack last, as if it were the first parameter in the function prototype.
On the Microsoft Visual C++ compiler, the this pointer is passed in ECX and it is the callee that cleans the stack, mirroring the stdcall convention used in C for this compiler and in Windows API functions. When functions use a variable number of arguments, it is the caller that cleans the stack (cf. cdecl).
The thiscall calling convention can only be explicitly specified on Microsoft Visual C++ 2005 and later. On any other compiler thiscall is not a keyword. (Disassemblers like IDA
Interactive Disassembler
The Interactive Disassembler, more commonly known as simply IDA, is a disassembler for computer software which generates assembly language source code from machine-executable code. It supports a variety of executable formats for different processors and operating systems. It also can be used as a...
, however, have to specify it anyway. So IDA uses keyword __thiscall for this.)
Intel ABI
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.
Microsoft x64 calling convention
The Microsoft x64 calling convention (for long mode
Long mode
In the x86-64 computer architecture, long mode is the mode where a 64-bit application can access 64-bit instructions and registers...
x86-64 is an extension of the x86 instruction set. It supports vastly larger virtual and physical address spaces than are possible on x86, thereby allowing programmers to conveniently work with much larger data sets. x86-64 also provides 64-bit general purpose registers and numerous other...
) takes advantage of additional register space in the AMD64/Intel 64 platform. The registers RCX, RDX, R8, R9 are used for integer and pointer arguments (in that order left to right), and XMM0, XMM1, XMM2, XMM3 are used for floating point arguments. Additional arguments are pushed onto the stack (right to left). Integer return values (similar to x86) are returned in RAX if 64 bits or less. Floating point return values are returned in XMM0.
Parameters less than 64 bits long are not zero extended; the high bits contain garbage.
When compiling for the x64 architecture in a Windows context (whether using Microsoft or non-Microsoft tools), there is only one calling convention — the one described here, so that stdcall, thiscall, cdecl, fastcall, etc., are now all one and the same.
In the Microsoft x64 calling convention, it's the caller's responsibility to allocate 32 bytes of "shadow space" on the stack right before calling the function (regardless of the actual number of parameters used), and to pop the stack after the call. The shadow space is used to spill RCX, RDX, R8, and R9.
For example, a function taking 5 integer arguments will take the first to fourth in registers, and the fifth will be pushed on the top of the shadow space. So the stack will be composed (in ascendant order) by the shadow space (32 bytes) followed by the fifth parameter.
x86-64 is an extension of the x86 instruction set. It supports vastly larger virtual and physical address spaces than are possible on x86, thereby allowing programmers to conveniently work with much larger data sets. x86-64 also provides 64-bit general purpose registers and numerous other...
, Visual Studio 2008 stores floating point numbers in XMM6 and XMM7 (as well as XMM8 through XMM15); consequently, for x86-64
X86-64
x86-64 is an extension of the x86 instruction set. It supports vastly larger virtual and physical address spaces than are possible on x86, thereby allowing programmers to conveniently work with much larger data sets. x86-64 also provides 64-bit general purpose registers and numerous other...
, user-written assembly language routines must preserve XMM6 and XMM7 (as compared to x86 wherein user-written assembly language routines did not need to preserve XMM6 and XMM7). In other words, user-written assembly language routines must be updated to save/restore XMM6 and XMM7 before/after the function when being ported from x86 to x86-64
X86-64
x86-64 is an extension of the x86 instruction set. It supports vastly larger virtual and physical address spaces than are possible on x86, thereby allowing programmers to conveniently work with much larger data sets. x86-64 also provides 64-bit general purpose registers and numerous other...
In computer software, an application binary interface describes the low-level interface between an application program and the operating system or another application.- Description :...
Linux is a Unix-like computer operating system assembled under the model of free and open source software development and distribution. The defining component of any Linux system is the Linux kernel, an operating system kernel first released October 5, 1991 by Linus Torvalds...
Microsoft Corporation is an American public multinational corporation headquartered in Redmond, Washington, USA that develops, manufactures, licenses, and supports a wide range of products and services predominantly related to computing through its various product divisions...
operating systems. The registers RDI, RSI, RDX, RCX, R8 and R9 are used for integer and pointer arguments while XMM0, XMM1, XMM2, XMM3, XMM4, XMM5, XMM6 and XMM7 are used for floating point arguments. For system calls, R10 is used instead of RCX. As in the Microsoft
Microsoft
Microsoft Corporation is an American public multinational corporation headquartered in Redmond, Washington, USA that develops, manufactures, licenses, and supports a wide range of products and services predominantly related to computing through its various product divisions...
x64 calling convention, additional arguments are pushed onto the stack and the return value is stored in RAX.
Thunks and calling conventions
A "thunk" means a small block of code, which can be generated dynamically at runtime, in order to be executed before calling the "actual" function. This is sometimes very useful. One common scenario is to convert a C++ functor object to a normal pointer to a function. In general, doing so requires one to insert an additional pointer which presents the "this" pointer to the functor object.
To write such a thunk, understanding of the calling convention the compiler is using is fundamental. One can easily imagine how to provide a general way to adjust the stack for stdcall to thiscall, because stdcall does not use registers and the additional parameter is to be passed through ecx, which is free to use. But how about for example fastcall or x64 calling convention? Those calling conventions uses registers to pass arguments, usually harder to predict the actual size and/or correct register for a specific parameter. However, it does not mean it cannot be done.
For example, if the compiler is using Microsoft x64 calling convention, what we need to do is to look at the convention. It says that 4 integer register and 4 floating point registers were selected as 4 parameter slot, and each parameter must occupy exactly one slot. If you have more than 4 parameters, additional parameters is passed by stack, with 8 bytes for each parameter.
Thus if the number of parameters is from 0 to 3, although we do not know if they occupy the integer registers or the floating point registers, we can shift them both, and result in a general solution.
For function objects that have at least 4 parameters, we need to detect the fourth parameter type. if it is a floating point then we push XMMS3, otherwise push R9. In this case, we can use templates and type traits feature to detect the exact parameter type.
For all other conventions we can do the same. The solution and implementation difficulty may be different, but the concept remains the same.
List of x86 calling conventions
This is a list of x86 calling conventions. Note: These are conventions primarily intended for C/C++ compilers (especially the 64-bit part below), and thus largely special cases. Other languages may use other formats and conventions in their implementations.
Pascal is an influential imperative and procedural programming language, designed in 1968/9 and published in 1970 by Niklaus Wirth as a small and efficient language intended to encourage good programming practices using structured programming and data structuring.A derivative known as Object Pascal...
Turbo C is an Integrated Development Environment and compiler for the C programming language from Borland. First introduced in 1987, it was noted for its integrated development environment, small size, extremely fast compile speed, comprehensive manuals and low price.In May 1990, Borland replaced...
ax, dx, bx
LTR (Pascal)
function
"this" on stack low address. return ptr on stack high address.
Watcom International Corporation was founded in 1981 by three former employees of the Computer Systems Group at the University of Waterloo, in Waterloo, Ontario, Canada...
IA-32 , also known as x86-32, i386 or x86, is the CISC instruction-set architecture of Intel's most commercially successful microprocessors, and was first implemented in the Intel 80386 as a 32-bit extension of x86 architecture...
The GNU Compiler Collection is a compiler system produced by the GNU Project supporting various programming languages. GCC is a key component of the GNU toolchain...
x86-64 is an extension of the x86 instruction set. It supports vastly larger virtual and physical address spaces than are possible on x86, thereby allowing programmers to conveniently work with much larger data sets. x86-64 also provides 64-bit general purpose registers and numerous other...
