113 lines
2.9 KiB
Markdown
113 lines
2.9 KiB
Markdown
# Syscall Policies
|
|
|
|
Domain: host ABI operational policy
|
|
Function: normative
|
|
|
|
This chapter defines the operational policies that sit on top of the host ABI.
|
|
|
|
It complements [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md), which defines the structural ABI itself.
|
|
|
|
## 1 Error Model: Faults vs Status Returns
|
|
|
|
Syscalls use a hybrid model.
|
|
|
|
### Fault conditions
|
|
|
|
The VM faults when contract rules are violated, for example:
|
|
|
|
- invalid syscall id;
|
|
- unresolved canonical identity;
|
|
- missing required capability;
|
|
- insufficient argument slots;
|
|
- invalid or dead heap handle.
|
|
|
|
These are not ordinary domain statuses.
|
|
|
|
### Status returns
|
|
|
|
Normal operational conditions should be represented as values in return slots.
|
|
|
|
Examples:
|
|
|
|
- asset not yet loaded;
|
|
- audio voice unavailable;
|
|
- persistent storage full.
|
|
|
|
## 2 Capability System
|
|
|
|
Each syscall requires a declared capability.
|
|
|
|
Example groups:
|
|
|
|
- `gfx`
|
|
- `audio`
|
|
- `input`
|
|
- `asset`
|
|
- `memcard`
|
|
|
|
Capability checks exist to constrain which host-managed surfaces a cartridge may use.
|
|
|
|
## 3 Interaction with the Garbage Collector
|
|
|
|
The VM heap and host-managed memory are separate.
|
|
|
|
### Heap vs host memory
|
|
|
|
| Memory | Managed by | GC scanned |
|
|
| --------------- | ---------- | ---------- |
|
|
| VM heap objects | VM GC | Yes |
|
|
| Asset banks | Host | No |
|
|
| Audio buffers | Host | No |
|
|
| Framebuffers | Host | No |
|
|
|
|
### Host root rule
|
|
|
|
If the host stores a VM heap handle beyond the duration of the syscall, that handle must be treated as a host root according to the runtime contract.
|
|
|
|
This rule applies to VM heap objects, not to host-owned asset identifiers or primitive values.
|
|
|
|
## 4 Determinism Rules
|
|
|
|
Syscalls must obey machine-level determinism.
|
|
|
|
Forbidden patterns:
|
|
|
|
- reading wall-clock time as gameplay state;
|
|
- non-deterministic OS access in the gameplay contract;
|
|
- blocking I/O in the execution slice.
|
|
|
|
Allowed patterns:
|
|
|
|
- frame-based timing;
|
|
- request + poll status models;
|
|
- deterministic event publication at frame boundaries.
|
|
|
|
## 5 Cost Model and Budgeting
|
|
|
|
Each syscall contributes to frame cost.
|
|
|
|
The system may account for:
|
|
|
|
- syscall count;
|
|
- cycles spent in syscalls;
|
|
- allocations triggered by syscalls.
|
|
|
|
This keeps host interaction visible in certification, telemetry, and profiling.
|
|
|
|
## 6 Blocking and Long Operations
|
|
|
|
Syscalls must not block the execution model.
|
|
|
|
Long operations should follow explicit staged patterns such as:
|
|
|
|
1. request;
|
|
2. status polling or completion observation.
|
|
|
|
This keeps the host ABI compatible with a deterministic frame machine.
|
|
|
|
## 7 Relationship to Other Specs
|
|
|
|
- [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) defines the structural ABI.
|
|
- [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) defines VM heap ownership and handles.
|
|
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines visibility of cost and diagnostics.
|