x86 Calling Conventions
x86 Calling Conventions
This article describes the calling conventions used on the x86 architecture.
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, 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 (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 very uniformly implemented.
Historical background
Prior to microcomputers, the machine manufacturer generally provided an operating system and compilers for
several programming languages. The calling conventions adopted for the platform were those defined by the
manufacturer's software implementation.
Early microcomputers before Apple II Computers generally came "bare" of an OS or compilers, as did the IBM
PC. The only hardware standard for IBM PC compatible machines was defined by the Intel processors (8086,
80386) and the literal hardware IBM shipped. Hardware extensions and all software standards (save for a BIOS
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 operating systems and programming tools (with differing
conventions) predominated, while second tier firms like Borland and Novell, and open source projects like GCC,
still maintained their own standards. Provisions for inter-operability between vendors and products were eventually
adopted, simplifying the problem of choosing a viable convention.[1]
Caller clean-up
In these conventions the caller cleans the arguments from the stack, which allows for variable argument lists; e.g.,
printf().
en.wikipedia.org/wiki/X86_calling_conventions 1/11
18/01/2013 x86 calling conventions - Wikipedia, the free encyclopedia
cdecl
The cdecl (which stands for C declaration) is a calling convention that originates from the C programming
language and is used by many C compilers for the x86 architecture.[1] In cdecl, subroutine arguments are passed on
the stack. Integer values and memory addresses are returned in the EAX register, floating point values—in the ST0
x87 register. Registers EAX, ECX, and EDX are caller-saved, and the rest are callee-saved.
In context of the C programming language, function arguments are pushed on the stack in the reverse order. In
GNU/Linux, GCC sets the de facto standard for calling conventions. Since GCC version 4.5, the stack must be
aligned to a 16-byte boundary when calling a function (previous versions only required a 4-byte
alignment.)[citation needed]
int caller(void)
{
register int ret;
.globl caller
caller:
pushl %ebp
movl %esp,%ebp
pushl $3
pushl $2
pushl $1
call callee
addl $12,%esp
addl $5,%eax
leave
ret
The calling function cleans the stack after the function call returns.
There are some variations in the interpretation of cdecl,[2] 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 a length of 2 registers or less in the register pair 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 pseudo-stack. Like so:
en.wikipedia.org/wiki/X86_calling_conventions 2/11
18/01/2013 x86 calling conventions - Wikipedia, the free encyclopedia
fld [ebp + x] ; load our double onto the floating point stack
fstp [esp] ; push our double onto the stack
call funct
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:
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.
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.
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,
e.g. 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 retinstruction 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:
ret 12
pascal
en.wikipedia.org/wiki/X86_calling_conventions 3/11
18/01/2013 x86 calling conventions - Wikipedia, the free encyclopedia
Based on the Pascal programming language'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 1.x, Microsoft Windows 3.x, and Borland
Delphi version 1.x.
register
stdcall
The stdcall[3] 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.[1] Typically fastcall calling conventions pass one or more arguments in registers which reduces the
number of memory accesses required for the call.
Microsoft fastcall
Microsoft or GCC[4] __fastcall[5] 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.[6]
It is the default calling convention of the 32 bit compiler of Embarcadero Delphi, where it is known as register.
Watcom 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 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
en.wikipedia.org/wiki/X86_calling_conventions 4/11
18/01/2013 x86 calling conventions - Wikipedia, the free encyclopedia
Variadic functions fall back to the Watcom stack based calling convention.
The Watcom C/C++ compiler also uses the #pragma aux[8] 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".
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.
safecall
In Embarcadero Delphi and Free Pascal on Microsoft Windows, the safecall calling convention encapsulates COM
(Component Object Model) error handling, thus exceptions aren't leaked out to the caller, but are reported in the
HRESULT 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.
Returns a result and raises exceptions like a normal Delphi function, but it passes values and exceptions as though it
was:
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
en.wikipedia.org/wiki/X86_calling_conventions 5/11
18/01/2013 x86 calling conventions - Wikipedia, the free encyclopedia
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, 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.
The Microsoft x64 calling convention[9] (for long mode on x86-64) 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.[10]
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.
In x86-64, Visual Studio 2008 stores floating point numbers in XMM6 and XMM7 (as well as XMM8 through
XMM15); consequently, for x86-64, 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.
en.wikipedia.org/wiki/X86_calling_conventions 6/11
18/01/2013 x86 calling conventions - Wikipedia, the free encyclopedia
The calling convention of the System V AMD64 ABI[11] is followed on Solaris, GNU/Linux, FreeBSD, and other
non-Microsoft operating systems. The registers RDI, RSI, RDX, RCX, R8, and R9 are used for integer and
memory address 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.[11] As in the Microsoft x64 calling
convention, additional arguments are passed on the stack and the return value is stored in RAX.
en.wikipedia.org/wiki/X86_calling_conventions 7/11
18/01/2013 x86 calling conventions - Wikipedia, the free encyclopedia
POD return
values 32 bits or
smaller are in
the EAX
register
POD return
values 33-64
bits in size are
returned via the
EAX:EDX
registers.
cdecl Microsoft RTL (C) Caller Non-POD
return values or
values larger
IA-32
than 64-bits, the
calling code will
allocate space
and passes a
pointer to this
space via a
hidden
parameter on
the stack. The
called function
writes the return
value to this
address.
References
1. ^ a b c d Agner Fog (2010-02-16) (PDF). Calling conventions for different C++ compilers and operating systems
(http://agner.org/optimize/calling_conventions.pdf) . http://agner.org/optimize/calling_conventions.pdf.
2. ^ Jonathan de Boyne Pollard (2010). "The gen on function calling conventions"
(http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/function-calling-conventions.html) .
http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/function-calling-conventions.html.
3. ^ http://msdn2.microsoft.com/en-us/library/zxk0tw93(vs.71).aspx
4. ^ Ohse, Uwe. "gcc attribute overview: function fastcall" (http://www.ohse.de/uwe/articles/gcc-
attributes.html#func-fastcall) . ohse.de. http://www.ohse.de/uwe/articles/gcc-attributes.html#func-fastcall.
Retrieved 2010-09-27.
5. ^ "__fastcall" (http://msdn2.microsoft.com/en-us/library/Aa271991) . msdn.microsoft.com.
http://msdn2.microsoft.com/en-us/library/Aa271991. Retrieved 2010-09-27.
6. ^ "Program Control: Register Convention"
(http://docwiki.embarcadero.com/RADStudio/en/Program_Control#Register_Convention) .
docwiki.embarcadero.com. 2010-06-01.
http://docwiki.embarcadero.com/RADStudio/en/Program_Control#Register_Convention. Retrieved 2010-09-27.
7. ^ "Add CONFIG for -mregparm=3" (http://lwn.net/Articles/66965/) . http://lwn.net/Articles/66965/.
8. ^ "Calling_Conventions: Specifying_Calling_Conventions_the_Watcom_Way"
(http://www.openwatcom.org/index.php/Calling_Conventions#Specifying_Calling_Conventions_the_Watcom_Way
) . openwatcom.org. 2010-04-27.
http://www.openwatcom.org/index.php/Calling_Conventions#Specifying_Calling_Conventions_the_Watcom_Way.
Retrieved 2010-09-27.
9. ^ a b "x64 Software Conventions: Calling Conventions" (http://msdn.microsoft.com/en-
us/library/9b372w95%28v=VS.80%29.aspx) . msdn.microsoft.com. 2010. http://msdn.microsoft.com/en-
us/library/9b372w95%28v=VS.80%29.aspx. Retrieved 2010-09-27.
10. ^ "x64 Software Conventions - Stack Allocation" (http://msdn.microsoft.com/en-
us/library/ew5tede7(v=VS.90).aspx) . Microsoft. http://msdn.microsoft.com/en-
us/library/ew5tede7(v=VS.90).aspx. Retrieved 2010-03-31.
11. ^ a b c Michael Matz, Jan Hubicka, Andreas Jaeger, and Mark Mitchell (2012-05-15). System V Application Binary
Interface AMD64 Architecture Processor Supplement (http://x86-64.org/documentation/abi.pdf) . 0.99.6.
http://x86-64.org/documentation/abi.pdf.
12. ^ (PDF) Borland C/C++ version 3.1 User Guide
(http://bitsavers.org/pdf/borland/Borland_C%2B%2B_Version_3.1_Users_Guide_1992.pdf) . Borland. 1992.
pp. 158,189–191. http://bitsavers.org/pdf/borland/Borland_C%2B%2B_Version_3.1_Users_Guide_1992.pdf.
http://sco.com/developers/devspecs/abi386-4.pdf.
Nemanja Trifunovic (2001-07-22). "Calling Conventions Demystified"
(http://www.codeproject.com/cpp/calling_conventions_demystified.asp) . In Sean Ewington. The Code
Project. http://www.codeproject.com/cpp/calling_conventions_demystified.asp.
Stephen J. Friedl. "Intel x86 Function-call Conventions — Assembly View"
(http://www.unixwiz.net/techtips/win32-callconv-asm.html) . Steve Friedl's Unixwiz.net Tech Tips.
http://www.unixwiz.net/techtips/win32-callconv-asm.html.
"Visual Studio 2010 — Visual C++ Calling Convention" (http://msdn.microsoft.com/en-
us/library/k2b2ssfy.aspx) . MSDN Library. Microsoft. 2010. http://msdn.microsoft.com/en-
us/library/k2b2ssfy.aspx.
Andreas Jonsson (2005-02-13). "Calling conventions on the x86 platform"
(http://www.angelcode.com/dev/callconv/callconv.html) .
http://www.angelcode.com/dev/callconv/callconv.html.
Raymond Chen (2004-01-02). "The history of calling conventions, part 1"
(http://blogs.msdn.com/oldnewthing/archive/2004/01/02/47184.aspx) . The Old New Thing.
http://blogs.msdn.com/oldnewthing/archive/2004/01/02/47184.aspx.
Raymond Chen (2004-01-07). "The history of calling conventions, part 2"
(http://blogs.msdn.com/oldnewthing/archive/2004/01/07/48303.aspx) . The Old New Thing.
http://blogs.msdn.com/oldnewthing/archive/2004/01/07/48303.aspx.
Raymond Chen (2004-01-08). "The history of calling conventions, part 3"
(http://blogs.msdn.com/oldnewthing/archive/2004/01/08/48616.aspx) . The Old New Thing.
http://blogs.msdn.com/oldnewthing/archive/2004/01/08/48616.aspx.
Raymond Chen (2004-01-13). "The history of calling conventions, part 4: ia64"
(http://blogs.msdn.com/oldnewthing/archive/2004/01/13/58199.aspx) . The Old New Thing.
http://blogs.msdn.com/oldnewthing/archive/2004/01/13/58199.aspx.
Raymond Chen (2004-01-14). "The history of calling conventions, part 5; amd64"
(http://blogs.msdn.com/oldnewthing/archive/2004/01/14/58579.aspx) . The Old New Thing.
http://blogs.msdn.com/oldnewthing/archive/2004/01/14/58579.aspx.
Further reading
Jonathan de Boyne Pollard (2010). "The gen on function calling conventions"
(http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/function-calling-conventions.html) .
Frequently Given Answers. http://homepage.ntlworld.com/jonathan.deboynepollard/FGA/function-calling-
conventions.html.
Kip R. Irvine (2007). "Advanced Procedures". Assembly language for intel-based computers (5th ed.).
Prentice Hall. ISBN 978-0-13-238310-3.
(PDF) Borland C/C++ version 3.1 User Guide
(http://bitsavers.org/pdf/borland/Borland_C%2B%2B_Version_3.1_Users_Guide_1992.pdf) . Borland.
1992. pp. 158,189–191.
http://bitsavers.org/pdf/borland/Borland_C%2B%2B_Version_3.1_Users_Guide_1992.pdf.
Thomas Lauer (1995). "The New __stdcall Calling Sequence". Porting to Win32: A Guide to Making
Your Applications Ready for the 32-Bit Future of Windows. Springer. ISBN 978-0-387-94572-9.
en.wikipedia.org/wiki/X86_calling_conventions 10/11
18/01/2013 x86 calling conventions - Wikipedia, the free encyclopedia
Navigation menu
en.wikipedia.org/wiki/X86_calling_conventions 11/11