| www.delorie.com/djgpp/doc/ug/asm/calling.html | search |
GCC follows certain rules in generating and calling its functions. If you are writing portable C or C++ code, you never need to know about these rules. However, if you are writing assembly language or nonportable code that depends on these rules, you need to know what they are. This document attemps to describe them, and gives some examples.
This document assumes a familiarity with assembly language. The assembler code used here is written in the AT&T syntax, as used by GNU as. If you're using an Intel-syntax assembler, like nasm, you'll have to translate appropriately.
What's described here are GCC's standard calling conventions. Many can be changed by using options like -mregparm, but that's outside the scope of this document.
These conventions apply to C. C++ introduces several additional complications (such as class pointers and name mangling), some of which can change between compiler versions. Thus, I suggest that asm functions called from C++ code be declared as extern "C". This will cause C calling conventions to be used.
In DJGPP, a function's assembly-language name is the same as its C name, with an underscore ("_") prepended. Thus, the C function foo would be named _foo in assembly language. (This is in fact true for all symbol names, such as variables.) C++ has some much more complicated rules.
GCC requires that some registers not change across a function call. If you want to use these registers in an assembly function, you must save and restore their values. They are:
Other registers are available for your use (though some have other special uses; read on).
If your function returns void (e.g. no value), the contents of these registers are not used.
Very simple; all pointers and addresses are near. You need not worry about segments (unless your asm code has a specific need to do so). Your function should end with a simple ret.
When GCC calls your function, it pushes all its arguments onto the stack, starting with the last one, then issues a call. This means that, on entry to your function, the stack is laid out like this:
Last argument
...
4(%esp) First argument
(%esp) Return address
Sizes and layouts of individual arguments are as follows:
These rules also apply to functions which take a variable number of arguments (like printf). As with any variadic function, the function must find its own way of determining how many arguments were actually passed (usually based on one of the required args).
The stack below the return address is available for temporary storage, but be sure to decrement %esp appropriately. Memory below %esp may be overwritten asynchronously, by interrupt handlers and such. Restore its value when exiting, so that the return works correctly. You may also push and pop at will.
You may modify your arguments in place if you wish; they will not be reused by the caller. Do not, however, attempt to pop them; the caller handles this.
An assembly language function may wish to call a function written in C, either your own or one from the standard library. The same rules already explained apply; you just see them from the other side.
First, you push the function's arguments (if any) onto the stack, last argument first. See above for the formats used. (Floating point values are usually most easily handled by making space on the stack and then executing a store instruction; i.e. subl $8,%esp; fstpl (%esp).)
Use a simple call instruction to call the function.
You are responsible for removing the arguments you have pushed. They may have changed, so you may not reuse them. You need not, however, discard them at once; it may be more convenient when calling several functions to leave the arguments on the stack and pop them all together at the end. addl n,%esp is an efficient way to do this. It may also be convenient in this case to use %ebp as a frame pointer, since it need not change all the time. (The C compiler does this.)
The return value may be found as detailed above.
Expect the registers %eax, %ecx, and %edx, as well as the floating-point stack, to have changed. Standard library functions may modify the %gs register, and the _far* functions may modify %fs. Other registers will be preserved.
These are the basic calling conventions used by GCC; however, there are special cases, optional modifications, etc. that can apply in situations not covered here. In this case, gcc -S is your best friend - from assembly output, you can usually figure out the rules. Also helpful is the GCC source: see i386.h and i386.md in config/i386. They are well commented.
These examples show how some C functions might be rewritten in assembly language. While the functions here are pretty useless themselves, hopefully they demonstrate the principles involved.
This function finds the average of two ints.
int i_avg (int a, int b)
{
return (a + b) / 2;
}
# Stack layout on entry:
#
# 8(%esp) b
# 4(%esp) a
# (%esp) return address
.globl _i_avg
_i_avg:
movl 4(%esp), %eax
addl 8(%esp), %eax # Add the args
sarl $1, %eax # Divide by 2
ret # Return value is in %eax
This function finds the average of two unsigned long longs. (The unsigned-ness is a cop-out to make the division easier, since there is no sard instruction.)
unsigned long long ull_avg (unsigned long long a, unsigned long long b)
{
return (a + b) / 2;
}
# Stack layout on entry:
#
# (high half of b)
# 12(%esp) b
# (high half of a)
# 4(%esp) a
# (%esp) return address
.globl _ull_avg
_ull_avg:
movl 4(%esp), %eax
movl 8(%esp), %edx
addl 12(%esp), %eax # Add low halves
adcl 16(%esp), %edx # Add high halves, with carry
shrdl $1, %edx, %eax
shrl $1, %edx # Divide by 2
ret # Return value is in %edx:%eax
This function finds the average of two long doubles.
long double ld_avg (long double a, long double b)
{
return (a + b) / 2.0;
}
# Stack layout on entry:
#
# 16(%esp) b (12 bytes)
# 4(%esp) a (12 bytes)
# (%esp) return address
two:
.double 0f2.0 # The number 2.0
.globl _ld_avg
_ld_avg:
fldt 4(%esp)
fldt 16(%esp)
faddp %st(1), %st(0) # Add
fdivl two # Divide %st(0) by 2.0
ret # Result is in %st(0)
This function prints a message, allocates an array of a given size, and fills it with 42.
#include <stdio.h>
#include <stdlib.h>
int *array_of_42 (int n)
{
int *p;
int i;
printf("Creating array of %d elements\n", n);
p = malloc(n * sizeof(int));
if (!p)
return NULL;
for (i = 0; i < n; i++)
p[i] = 42;
return p;
}
# Stack layout:
#
# 8(%ebp) n
# 4(%ebp) return address
# (%ebp) pushed %ebp
format:
.string "Creating array of %d elements\n"
.globl _array_of_42
_array_of_42:
# We will use a frame pointer, since %esp will be changing.
pushl %ebp
movl %esp, %ebp
pushl %edi # Save %edi, since we'll be using it.
# First, print the message.
pushl 8(%ebp)
pushl $format
call _printf
addl $8, %esp # Remove printf args from the stack
# Allocate the array.
movl 8(%ebp), %ecx
shll $2, %ecx # Multiply by 4, which is sizeof(int)
pushl %ecx
call _malloc
popl %ecx # Remove malloc args from stack
orl %eax, %eax # Test return value
jz finished
# Fill the array, using stosl.
movl %eax, %edi # Address
movl %eax, %edx # and save a copy
movl 8(%ebp), %ecx # Count
movl $42, %eax # Fill value
rep
stosl
movl %edx, %eax # Return value
finished:
popl %edi # Restore it
popl %ebp
ret
About using %ebp: Note that using -fomit-frame-pointer does not release you from the requirement to preserve %ebp. With this option enabled, the compiler may use %ebp for something else, but it still expects it to be saved across function calls. Furthermore, some functions cannot be compiled by GCC without a frame pointer.
| webmaster donations bookstore | delorie software privacy |
| Copyright © 1999 by DJ Delorie | Updated Jun 1999 |
You can help support this site by visiting the advertisers that sponsor it! (only once each, though)