7.1 KiB
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.
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:
- the caller prepares arguments;
CALLtransfers control;- the callee executes under its frame contract;
RETleaves 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.mddefines the VM execution subsystem at a higher level.02b-vm-function-values-and-closures.mddefines first-class function values.03-memory-stack-heap-and-allocation.mddefines stack/heap and handle-backed objects.16-host-abi-and-syscalls.mdreuses 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. CALL_CLOSURE uses expected FnTypeId to establish parameter/result groups even for unknown concrete targets. GET_CAPTURE accesses typed metadata of the enclosing function; environment is retained by CallFrame without hidden arg0. Known mismatch rejects, Unknown retains runtime checks. 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 v0. 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.
Finite Float and explicit math conversions
Float is binary64 with the VM-owned software semantics in Gameplay Math and Numeric Semantics. NaN/infinity are rejected at image admission and native import, never stored as guest numeric defaults. Preserve signed-zero bits and subnormals; numeric equality treats both zeros equally. Numeric overflow faults by range. Exact Registry/intrinsic carriers prohibit implicit conversion; math/mathf supplies explicit conversions with truncation/range and ties-even rules. Existing arithmetic opcode promotions do not relax typed boundaries.
Random core integration
Random v1 is BuiltinId 0x0016: one nullable HeapRef slot, eight-byte reference storage aligned to eight with GuestReference ownership. Copies alias; only random.new constructs the object.