◄ Back to index

# Specificities of GTC

# Application binary interface (ABI)

## Calling convention

A calling convention specifies where arguments to a function are placed, and where the function places its return value. You shouldn't worry about it, unless you are an assembly programmer trying to call assembly functions from C code or vice-versa.

### Default calling convention (`regparm`)

Unless otherwise specified, GTC uses the most efficient calling convention, `regparm`. Basically, it consists of placing as many arguments as possible into a small set of registers for maximum efficiency, and when they are all used, place the remaining arguments on the stack, which is less efficient.

More precisely, here is the specific algorithm for placing arguments:

- for each argument `a`, from left to right

- if all registers {`d0`,`d1`,`d2`,`a0`,`a1`} are already used by other arguments

- place `a` on the stack

- else

- if there is at least one of {`d0`,`d1`,`d2`} unused and one of {`a0`,`a1`} unused

- if `a`'s type is a pointer

- place `a` in the next free address register

- else

- place `a` in the next free data register

- else

- if one of {`a0`,`a1`} is unused

- place `a` in the next free address register

- else

- place `a` in the next free data register

Here is how the placement of an argument is done:

- how to place `a` in the next free data register:

- place `a` in `d0` if it is unused
- or if it is used

- place `a` in `d1` if it is unused
- or if it is used place `a` in `d2`

- how to place `a` in the next free address register:

- place `a` in `a0` if it is unused
- or if it is used place `a` in `a1`

- how to place `a` on the stack:

- see `stkparm`

Here is the algorithm for placing the return value:

- if the return value's type is a pointer

- the function should return the value in `a0`

- if the return value's type is an integer

- the function should return the value in `d0`

- if the return value's type is a `struct` or a `union`

- if the structure is 4 bytes long or shorter

- the function should return the contents of the structure in `d0` (not the address!)

- else

- the ABI is not specified in this case, you should avoid it

Note that `regparm` requires the function to have a fixed number of arguments: otherwise, for variable-argument functions, no arguments are placed in registers, and the `stkparm` convention is used instead.

Note that TIGCC uses the same algorithm, as long as you specify the function attribute `__attribute__((regparm(2,1)))`.

You can also use a different set of variables than `d0`-`d2`/`a0`-`a1` thanks to the `regparm` function attribute, but it is not recommended.

### AMS calling convention (`stkparm`)

The `stkparm` convention is less efficient, but is useful because it is the one used internally by AMS. It is also much simpler to describe.

The arguments are pushed one after the other onto the stack, starting from the rightmost argument. `char`s and `unsigned char`s should be widened to an `int` before being pushed.