Add some documentation to the abi

diff --git a/abi.md b/abi.md
new file mode 100644 (file)
index 0000000..5f09227
--- /dev/null
+++ b/abi.md
@@ -0,0 +1,35 @@
+# heap
+
+a heap is allocated at the start, and the address to the next free
+space on it is stored in `heap_start`. it needs to be
+updated/decremented whenever you put anything on the heap
+
+# closures
+
+* lambda: actual function containing the code
+* closure: reference to the lambda containing captives
+
+closures are stored on the heap. They contain the address to the
+lambda along with any "captives", i.e. captured variables. They have
+the following layout:
+
+```
+0            8          16        24        32
+lambda code  1st        2nd       3rd
+address      captive    captive   captive   ...
+```
+
+# lambdas
+
+lambdas use the system v amd64 calling convention.
+
+* param 0: the start address of the **1st** captive
+* param 1...n: the remaining, regular args.
+
+e.g.
+```
+(let [(x 42)] (lambda (y) (+ x y)))
+```
+
+* param 0: pointer to the value of `x`
+* param 1: the value of`y`