132 lines
6.1 KiB
Markdown
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.
|