In computer science, a calling convention is an implementation-level (low-level) scheme for how subroutines or functions receive parameters from their caller and how they return a result. When some code calls a function, design choices have been taken for where and how parameters are passed to that function, and where and how results are returned from that function, with these transfers typically done via certain registers or within a stack frame on the call stack. There are design choices for how the tasks of preparing for a function call and restoring the environment after the function has completed are divided between the caller and the callee. Some calling conventions specify the way every function should get called. The correct calling convention should be used for every function call, to allow the correct and reliable execution of the whole program using these functions.
Introduction Calling conventions are usually considered part of the application binary interface (ABI). They may be considered a contract between the caller and the called function.
Related concepts The names or meanings of the parameters and return values are defined in the application programming interface (API, as opposed to ABI), which is a separate though related concept to ABI and calling convention. The names of members within passed structures and objects would also be considered part of the API, and not ABI. Sometimes APIs do include keywords to specify the calling convention for functions.
Calling conventions do not typically include information on handling lifespan of dynamically allocated structures and objects. Other supplementary documentation may state where the responsibility for freeing up allocated memory lies.
Calling conventions are unlikely to specify the layout of items within structures and objects, such as byte ordering or structure packing.
For some languages, the calling convention includes details of error or exception handling, (e.g. Go, Java) and for others, it does not (e.g. C++).
For remote procedure calls, there is an analogous concept called Marshalling.
Calling conventions may be related to a particular programming language's evaluation strategy, but most often are not considered part of it (or vice versa), as the evaluation strategy is usually defined on a higher abstraction level and seen as a part of the language rather than as a low-level implementation detail of a particular language's compiler.
Different calling conventions Calling conventions may differ in: Where parameters are placed. Options include registers, on the call stack, a mix of both, or in other memory structures. The order in which parameters are passed. Options include left-to-right order, or right-to-left, or something more complex. How functions that take a variable number of arguments (variadic functions) are handled. Options include just passed in order (presuming the first parameter is in an obvious position) or the variable parts in an array. How return values are delivered from the callee back to the caller. Options include on the stack, in a register, or reference to something allocated on the heap. How long or complex values are handled, perhaps by splitting across multiple registers, within the stack frame, or with reference to memory. Which registers are guaranteed to have the same value when the callee returns as they did when the callee was called. These registers are said to be saved or preserved, so they are not volatile. How the task of setting up for and cleaning up after a function call is divided between the caller and the callee. In particular, how the stack frame is restored so the caller may continue after the callee has finished. Whether and how metadata describing the arguments is passed Where the previous value of the frame pointer is stored, which is used to restore the stack frame when the subroutine ends. Options include within the call stack, or in a specific register. Sometimes frame pointers are not used at all. Where any static scope links for the routine's non-local data access are placed (typically at one or more positions in the stack frame, but sometimes in a general register, or, for some architectures, in special-purpose registers) For object-oriented languages, how the function's object is referenced
Calling conventions within one platform Sometimes multiple calling conventions appear on a single platform; a given platform and language implementation may offer a choice of calling conventions. Reasons for this include performance, adaptation of conventions of other popular languages, and restrictions or conventions imposed by various computing platforms.
Many architectures only have one widely used calling convention, often suggested by the architect. For RISCs including SPARC, MIPS, and RISC-V, registers names based on this calling convention are often used. For example, MIPS registers through have "ABI names" through , reflecting their use for parameter passing in the standard calling convention. (RISC CPUs have many equivalent general-purpose registers so there's typically no hardware reason for giving them names other than numbers.)
The calling convention of a given program's language may differ from the calling convention of the underlying platform, OS, or of some library being linked to. For example, on 32-bit Windows, operating system calls have the stdcall calling convention, whereas many C programs that run there use the cdecl calling convention. To accommodate these differences in calling convention, compilers often permit keywords that specify the calling convention for a given function. The function declarations will include additional platform-specific keywords that indicate the calling convention to be used. When handled correctly, the compiler will generate code to call functions in the appropriate manner.
Some languages allow the calling convention for a function to be explicitly specified with that function; other languages will have some calling convention but it will be hidden from the users of that language, and therefore will not typically be a consideration for the programmer.
Architectures x86 (32-bit)
The 32-bit version of the x86 architecture is used with many different calling conventions. Due to the small number of architectural registers, and historical focus on simplicity and small code-size, many x86 calling conventions pass arguments on the stack. The return value (or a pointer to it) is returned in a register. Some conventions use registers for the first few parameters which may improve performance, especially for short and simple leaf routines very frequently invoked (i.e. routines that do not call other routines).
Example call: push EAX ; pass some register result push dword [EBP+20] ; pass some memory variable (FASM/TASM syntax) push 3 ; pass some constant call calc ; the returned result is now in EAX
Typical callee structure: (some or all (except ret) of the instructions below may be optimized away in simple procedures). Some conventions leave the parameter space allocated, using plain instead of . In that case, the caller could in this example, or otherwise deal with the change to ESP.
calc: push EBP ; save old frame pointer mov EBP,ESP ; get new frame pointer sub ESP,localsize ; reserve stack space for locals . . ; perform calculations, leave result in EAX . mov ESP,EBP ; free space for locals pop EBP ; restore old frame pointer ret paramsize ; free parameter space and return.
x86-64
The 64-bit version of the x86 architecture, known as x86-64, AMD64, and Intel 64, has two calling sequences in common use. One calling sequence, defined by Microsoft, is used on Windows; the other calling sequence, specified in the AMD64 System V ABI, is used by Unix-like systems and, with some changes, by OpenVMS. As x86-64 has more general-purpose registers than 32-bit x86, both conventions pass some arguments in registers.
ARM (A32) The standard 32-bit ARM calling convention allocates the 16 general-purpose registers as:
r15: Program counter (as per the instruction set specification). r14: Link register. The BL instruction, used in a subroutine call, stores the return address in this register. r13: Stack pointer. The Push/Pop instructions in "Thumb" operating mode use this register only. r12: Intra-Procedure-call scratch register. r4 to r11: Local variables. r0 to r3: Argument values passed to a subroutine and results returned from a subroutine.
If the type of value returned is too large to fit in r0 to r3, or whose size cannot be determined statically at compile time, then the caller must allocate space for that value at run time, and pass a pointer to that space in r0.
Subroutines must preserve the contents of r4 to r11 and the stack pointer (perhaps by saving them to the stack in the function prologue, then using them as scratch space, then restoring them from the stack in the function epilogue). In particular, subroutines that call other subroutines must save the return address in the link register r14 to the stack before calling those other subroutines. However, such subroutines do not need to return that value to r14—they merely need to load that value into r15, the program counter, to return.
The ARM calling convention mandates using a full-descending stack. In addition, the stack pointer must always be 4-byte aligned, and must always be 8-byte aligned at a function call with a public interface.
This calling convention causes a "typical" ARM subroutine to: In the prologue, push r4 to r11 to the stack, and push the return address in r14 to the stack (this can be done with a single STM instruction); Copy any passed arguments (in r0 to r3) to the local scratch registers (r4 to r11); Allocate other local variables to the remaining local scratch registers (r4 to r11); Do calculations and call other subroutines as necessary using BL, assuming r0 to r3, r12 and r14 will not be preserved; Put the result in r0; In the epilogue, pull r4 to r11 from the stack, and pull the return address to the program counter r15. This can be done with a single LDM instruction.
ARM (A64) The 64-bit ARM (AArch64) calling convention allocates the 31 general-purpose registers as:
x31 (SP): Stack pointer or a zero register, depending on context. x30 (LR): Procedure link register, used to return from subroutines. x29 (FP): Frame pointer. x19 to x28: Callee-saved. x18 (PR): Platform register. Used for some operating-system-specific special purpose, or an additional caller-saved register. x16 (IP0) and x17 (IP1): Intra-Procedure-call scratch registers. x9 to x15: Local variables, caller saved. x8 (XR): Indirect return value address. x0 to x7: Argument values passed to and results returned from a subroutine.
All registers starting with x have a corresponding 32-bit register prefixed with w. Thus, a 32-bit x0 is called w0.
Similarly, the 32 floating-point registers are allocated as:
v0 to v7: Argument values passed to and results returned from a subroutine. v8 to v15: callee-saved, but only the bottom 64 bits need to be preserved. v16 to v31: Local variables, caller saved.
RISC-V ISA RISC-V has a defined calling convention with two flavors, with or without floating point hardware. It passes arguments in registers whenever possible.
POWER, PowerPC, and Power ISA The POWER, PowerPC, and Power ISA architectures have a large number of registers so most functions can pass all arguments in registers for single level calls. Additional arguments are passed on the stack, and space for register-based arguments is also always allocated on the stack as a convenience to the called function in case multi-level calls are used (recursive or otherwise) and the registers must be saved. This is also of use in variadic functions, such as , where the function's arguments need to be accessed as an array. A single calling convention is used for all procedural languages.