diff -r 78357d58b7ab -r fba288d59662 binary.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/binary.rst	Mon Feb 22 12:46:36 2016 +0200
@@ -0,0 +1,49 @@
+.. -*- coding: utf-8; -*-
+.. include:: HEADER.rst
+
+============
+ 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