Files
prometeu-runtime/docs/specs/runtime/02a-vm-values-and-calling-convention.md
T

132 lines
6.1 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 |
| ------- | --------------------- |
| `Int32` | 32-bit signed integer |
| `Int64` | 64-bit signed integer |
| `bool` | Boolean value |
| `float` | 64-bit floating point |
### String values
PROMETEU supports string values in the VM language surface.
String rules:
- hardcoded strings may be materialized once during build/load through constant-pool-backed storage;
- runtime-created strings may materialize at the point where a new string value is semantically created;
- the public value model does not require repeated payload copies after first materialization;
- reducing repeated string copy pressure is an internal runtime concern and MUST NOT be interpreted as a guest-visible ABI distinction.
### 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 RGBA8888 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.
The canonical `color` raw channel order is RGBA. RGB565 is not a public VM
color contract.
### 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.
## Typed signatures and frames
Derive P=sum(parameter widths), L=local_slots and R=sum(result widths). A frame contains parameters, L extra locals then temporaries. GET/SET_LOCAL address only P+L; operand operations cannot consume below the temporary base. CALL consumes P caller temporaries in signature/component order and validates complete groups before publishing the frame. Concrete method receiver is the first declared parameter. No hidden closure receiver is invented by this rule.
RET requires exactly R temporaries, validates ordered types, releases frame owners and returns R slots. Wrong height uses TRAP_BAD_RET_SLOTS; unproved runtime type mismatch uses TRAP_TYPE. Locals begin as Value::Null, not numeric defaults or Uninitialized. Parameter/local slots can be reused after entry; SET_LOCAL updates abstract knowledge. Definite assignment/source variable types remain frontend concerns. Do not introduce silent Int32/Int64, concrete/trait or concrete/Dynamic conversions at boundaries.
Verifier decodes every function range, validates instruction boundaries/IDs/jump destinations, and analyzes structurally reachable control flow. Track temporary height and local/temporary facts in a finite domain: Unknown, known null, carrier facts and proven semantic/multi-slot groups. Initial parameters follow signatures; other locals start null. GET copies facts; SET replaces. Equal facts survive joins; conflicting facts become Unknown, while unequal heights are rejected. Do not require one permanent local type or infer unbounded unions/branch conditions.
Use a bounded worklist to fixed point, reprocessing widened states; decide state-dependent type errors after convergence so visitation order cannot cause rejection. Signature contracts suffice for calls; no interprocedural body inference is required. Partial group mutation invalidates relational facts. Unknown is not proof of compatibility and does not alone reject code: retain complete runtime checks. Type knowledge alone does not eliminate null/generation/bounds checks. Retain current UnknownClosureCallee protection until the separate callable/closure/coroutine contract provides a replacement contract. Exceeding memory/work budget rejects loading, never skips verification.
Builtin IDs, exact slot carriers, nullable defaults and stored layouts are defined in [Program Registry and PBX v1](02c-program-registry-and-pbx-v1.md#values-storage-and-initialization). A fixed list of results does not imply a tuple object or boxing. Parameter names are optional signature metadata; frontend argument reordering must preserve source evaluation order.