abi.md

   1 # heap
   2
   3 a heap is allocated at the start, and the address to the next free
   4 space on it is stored in `heap_start`. it needs to be
   5 updated/decremented whenever you put anything on the heap
   6
   7 ## todo
   8 - how should allocation be managed?
   9 make free blocks a doubly linked list. (how big is a block?)
  10 when allocating, use first free block, move up free pointer
  11 when freeing, do ???
  12
  13
  14 # ownership
  15
  16 ```
  17 (let ([s "hello"])  <- s should be a linear string
  18   (mkpair
  19     (lambda () (print s))               <- two references to s?
  20     (lambda () (print (reverse s)))))
  21 ```
  22
  23 # closures
  24
  25 * lambda: actual function containing the code
  26 * closure: reference to the lambda containing captives
  27
  28 closures are stored on the heap. They contain the address to the
  29 lambda along with any "captives", i.e. captured variables. They have
  30 the following layout:
  31
  32 ```
  33 0            8          16        24        32
  34 lambda code  1st        2nd       3rd
  35 address      captive    captive   captive   ...
  36 ```
  37
  38 ## note on recursive closures
  39
  40 The following example shows a recursive lambda, that results in a
  41 closure that captures itself.
  42 ```
  43 (let ([f (closure lambda0 (f))])
  44   (f 42))
  45 ```
  46 When this happens, `codegen-let` will insert `(f . 'self-captive)`
  47 into the environment when codegen'ing the closure. `codegen-closure`
  48 will then pick this up, and use it to insert its own heap address into
  49 its inner environment.
  50
  51 # lambdas
  52
  53 lambdas use the system v amd64 calling convention.
  54
  55 * param 0: the start address of the **1st** captive
  56 * param 1...n: the remaining, regular args.
  57
  58 e.g.
  59 ```
  60 (let [(x 42)] (lambda (y) (+ x y)))
  61 ```
  62
  63 * param 0: pointer to the value of `x`
  64 * param 1: the value of`y`
  65
  66 # inter-function and stack values
  67
  68 ints, bools and closures are passed around within functions in `%rax`.
  69 adts are passed on the stack, at whatever stack index the code generation was called with.