103 lines
2.9 KiB
Markdown
103 lines
2.9 KiB
Markdown
# VM Values and Calling Convention
|
|
|
|
Domain: VM values and calling convention
|
|
Function: normative
|
|
|
|
This chapter isolates the slot/value model and the rules for calls, returns, tuples, and frames.
|
|
|
|
## 1 Value Types
|
|
|
|
All runtime values are stored in VM slots as `Value`.
|
|
|
|
### Primitive value types
|
|
|
|
| Type | Description |
|
|
| ------- | --------------------- |
|
|
| `int` | 64-bit signed integer |
|
|
| `bool` | Boolean value |
|
|
| `float` | 64-bit floating point |
|
|
|
|
### Built-in vector and graphics types
|
|
|
|
These are treated as VM values with stable layout semantics.
|
|
|
|
| Type | Description |
|
|
| ------- | --------------------------------- |
|
|
| `vec2` | 2D vector (x, y) |
|
|
| `color` | Packed color value |
|
|
| `pixel` | Combination of position and color |
|
|
|
|
These values:
|
|
|
|
- live on the stack;
|
|
- are copied by value;
|
|
- do not require heap allocation by themselves.
|
|
|
|
### Heap values
|
|
|
|
Heap-resident entities are referenced indirectly through handles.
|
|
|
|
| Type | Description |
|
|
| -------- | -------------------------- |
|
|
| `handle` | Reference to a heap object |
|
|
| `null` | Null handle |
|
|
|
|
Handle semantics are defined in [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md).
|
|
|
|
## 2 Tuples and Multi-Return ABI
|
|
|
|
The PVM supports multi-value returns.
|
|
|
|
Tuple rules:
|
|
|
|
- tuples are stack-only;
|
|
- tuples are not heap objects by default;
|
|
- tuple persistence requires explicit boxing into a heap representation when such a representation exists in the language/toolchain;
|
|
- return shape is part of the function contract.
|
|
|
|
## 3 Call Convention
|
|
|
|
Each function declares a fixed return-slot shape.
|
|
|
|
At call time:
|
|
|
|
1. the caller prepares arguments;
|
|
2. `CALL` transfers control;
|
|
3. the callee executes under its frame contract;
|
|
4. `RET` leaves exactly the declared return-slot shape on the stack.
|
|
|
|
The verifier ensures:
|
|
|
|
- all reachable return paths agree on return-slot count;
|
|
- stack depth remains coherent across the function body.
|
|
|
|
## 4 Call Stack and Frames
|
|
|
|
The VM uses a call stack.
|
|
|
|
Conceptual frame shape:
|
|
|
|
```
|
|
Frame {
|
|
return_pc
|
|
base_pointer
|
|
ret_slots
|
|
}
|
|
```
|
|
|
|
Execution uses the public call instructions:
|
|
|
|
| Opcode | Description |
|
|
| ------ | ---------------------- |
|
|
| `CALL` | Calls a function by id |
|
|
| `RET` | Returns from function |
|
|
|
|
There is no separate public ISA for manual frame stack manipulation.
|
|
|
|
## 5 Relationship to Other Specs
|
|
|
|
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM execution subsystem at a higher level.
|
|
- [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) defines first-class function values.
|
|
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines stack/heap and handle-backed objects.
|
|
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) reuses the same slot-oriented argument/return philosophy for syscalls.
|