Paged memory model

src/vm/index.md

@@ -76,7 +76,9 @@ A complete instruction set of the Fuel VM is documented in [the following page](
 
 ## VM Initialization
 
-Every time the VM runs, a single monolithic memory of size `VM_MAX_RAM` bytes is allocated, indexed by individual byte. A stack and heap memory model is used, allowing for dynamic memory allocation in higher-level languages. The stack begins at `0` and grows upward. The heap begins at `VM_MAX_RAM - 1` and grows downward.
+The VM has `VM_MAX_RAM` bytes of ram, indexed by individual byte. A stack and heap memory model is used, allowing for dynamic memory allocation in higher-level languages. The stack begins at `0` and grows upward. The heap begins at `VM_MAX_RAM - 1` and grows downward. Unused memory is initialized to zero.
+
+Memory is gas-metered by usage. It's allocated in 16 KiB pages, which are transparently creted when either stack or heap grows beyond the current page. Both stack and heap are contiguous, and pages for those are allocated separately. The stack and heap are not allowed to overlap, but it's possible for them to share the last available page of memory.
 
 To initialize the VM, the following is pushed on the stack sequentially:
 
@@ -192,3 +194,5 @@ If the context is internal, the owned memory range for a call frame is:
 
 1. `[$ssp, $sp)`: the writable stack area of the call frame.
 1. `[$hp, $fp->$hp)`: the heap area allocated by this call frame.
+
+A single write must fall within a single owned memory range. Even if `$hp == $sp`, a write instruction like `SW` cannot cross the boundary between the stack and the heap.

src/vm/instruction_set.md

@@ -1275,13 +1275,13 @@ All these instructions advance the program counter `$pc` by `4` after performing
 
 ### ALOC: Allocate memory
 
-|             |                                           |
-|-------------|-------------------------------------------|
-| Description | Allocate a number of bytes from the heap. |
-| Operation   | ```$hp = $hp - $rA;```                    |
-| Syntax      | `aloc $rA`                                |
-| Encoding    | `0x00 rA - - -`                           |
-| Notes       | Does not initialize memory.               |
+|             |                                                                                      |
+|-------------|--------------------------------------------------------------------------------------|
+| Description | Allocate a number of bytes from the heap.                                            |
+| Operation   | ```$hp = $hp - $rA;```                                                               |
+| Syntax      | `aloc $rA`                                                                           |
+| Encoding    | `0x00 rA - - -`                                                                      |
+| Notes       | Does not clear memory. After this, `$hp` points to the first byte of the allocation. |
 
 Panic if:
 
@@ -1296,7 +1296,7 @@ Panic if:
 | Operation   | ```$sp = $sp + $rA```                  |
 | Syntax      | `cfei $rA`                             |
 | Encoding    | `0x00 rA - - -`                        |
-| Notes       | Does not initialize memory.            |
+| Notes       | Does not clear memory.                 |
 
 Panic if:
 
@@ -1311,7 +1311,7 @@ Panic if:
 | Operation   | ```$sp = $sp + imm```                                        |
 | Syntax      | `cfei imm`                                                   |
 | Encoding    | `0x00 i i i i`                                               |
-| Notes       | Does not initialize memory.                                  |
+| Notes       | Does not clear memory.                                       |
 
 Panic if:
 
@@ -1487,7 +1487,7 @@ Panic if:
 
 - `$rA + imm + 1` overflows
 - `$rA + imm + 1 > VM_MAX_RAM`
-- The memory range `MEM[$rA + imm, 1]`  does not pass [ownership check](./index.md#ownership)
+- The memory range `MEM[$rA + imm, 1]` does not pass [ownership check](./index.md#ownership)
 
 ### SW: Store word
 
@@ -1503,7 +1503,7 @@ Panic if:
 
 - `$rA + (imm * 8) + 8` overflows
 - `$rA + (imm * 8) + 8 > VM_MAX_RAM`
-- The memory range `MEM[$rA + (imm * 8), 8]`  does not pass [ownership check](./index.md#ownership)
+- The memory range `MEM[$rA + (imm * 8), 8]` does not pass [ownership check](./index.md#ownership)
 
 ## Contract Instructions