From 91145e54f41ee88f1e279a80430b3f5ed4e7a8c6 Mon Sep 17 00:00:00 2001
From: Luke Lau <luke_lau@icloud.com>
Date: Sun, 28 Jul 2019 13:07:00 +0100
Subject: [PATCH] Add some documentation to the abi

---
 abi.md | 35 +++++++++++++++++++++++++++++++++++
 1 file changed, 35 insertions(+)
 create mode 100644 abi.md

diff --git a/abi.md b/abi.md
new file mode 100644
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`
-- 
2.30.2