---

7.2.1 Memory Layout ¶

The VM maintains three core structures:

• The operand stack
• The callstack
• Three specific registers

1. Operand Stack

   Stores temporary computation values, variables and function return values.

   ┌─────────────┬─────────────┬─────────────┐
   │  Element 0  │  Element 1  │  Element 2  │
   │  (8 bytes)  │  (8 bytes)  │  (8 bytes)  │
   └─────────────┴─────────────┴─────────────┘
         ↑
       Stack Top
   

   Properties: - Type: ‘[Word8]’ (list of bytes) - Element size: 8 bytes (64-bit) - Initial state: One zero element ‘[0x00 × 8]’ - Max size: 1,000,000 elements (8 MB) - Operations: PUSH (prepend), POP (drop first 8 bytes)

2. Call Stack

   Manages function call frames.

   ┌─────────────────────────────────┐
   │  Frame: (PC: 0, SP: 0)          │  ← Entry
   ├─────────────────────────────────┤
   │  Frame: (PC: 12, SP: 16)        │
   ├─────────────────────────────────┤
   │  Frame: (PC: 57, SP: 24)        │  ← Current
   └─────────────────────────────────┘
   

   Properties: - Type: ‘[(PC, SP)]’ (list of tuples) - Frame content: Return address (PC) + Stack pointer (SP) - Initial state: Empty ‘[]’ - Max depth: 1,000,000 frames

   Behavior: - ‘CALL’: Push ‘(PC+1, SP)’, jump to function - ‘RET’: Pop frame, restore context, trim stack - Termination: Empty call stack after ‘RET’ → program ends

3. Registers

   Program Counter (PC) - Points to current instruction in bytecode - Initial: 8 (after 4-byte magic number) - Updates: ‘+1’ (normal), ‘+9’ (with data), or jump target

   Stack Pointer (SP) - Marks base of current function’s stack frame - Used for local variable access via ‘PUSHREL=/=POPREL’ - Modified during ‘CALL’ and ‘RET’

   Zero Flag (ZF) - Type: ‘Word8’ (0 or 1) - Initial: 1 (true) - Semantics: ‘0’ if stack top = 0, else ‘1’ - Set by ‘ZFLAG’, tested by ‘ZJMP’