.. -*- coding: utf-8; -*-

============
 Binary ABI
============
.. contents::
   :local:

Caller vs callee
================

If routine A calls routine B then routine A is the caller and routine B is the
callee. i.e. the caller is the routine which is calling the callee.

The routine that initiates the call is the caller and the routine that is
being called is is the callee.

Argument vs parameter
=====================

From the perspective of the caller the thing which is passed is an argument.
From the perspective of the routine that receives the call, i.e. the callee,
the thing which is passed is a parameter.

Linkage convention
==================

A linkage convention is computing term that means an agreement which is made
between a caller and a callee. The agreement describes:

- how the caller should pass parameters to the callee

- what assumptions the callee is allowed to make about the values in the
  machine registers at the moment of the call

- who should preserve registers which are modified by the callee and/or which
  are important to the caller so that their original values are available
  when the caller needs them

- how and where registers should be preserved

- how the callee knows where to return to when it is ready to return to the
  caller

- how the callee returns a value to the caller if the routine is a function
  (as opposed to a subroutine which has no return value)

- how a debugger will find the information necessary to obtain a stack trace