This commit is contained in:
2026-03-24 13:40:39 +00:00
parent b9723cfc40
commit a7ddbcabb2
4 changed files with 427 additions and 311 deletions
+106 -28
View File
@@ -2,7 +2,7 @@
# **Host ABI and Syscalls**
This chapter defines the Application Binary Interface (ABI) between the Prometeu Virtual Machine (PVM) and the host environment. It specifies how syscalls are encoded, invoked, verified, and accounted for.
This chapter defines the Application Binary Interface (ABI) between the Prometeu Virtual Machine (PVM) and the host environment. It specifies how syscalls are identified, resolved, invoked, verified, and accounted for.
Syscalls provide controlled access to host-managed subsystems such as graphics, audio, input, asset banks, and persistent storage.
@@ -20,10 +20,89 @@ The syscall system follows these rules:
4. **Capability-gated**: Each syscall requires a declared capability.
5. **Stack-based ABI**: Arguments and return values are passed via VM slots.
6. **Not first-class**: Syscalls are callable but cannot be stored as values.
7. **Language-agnostic identity**: Syscalls are identified by canonical names, not language syntax.
---
## 2 Syscall Instruction Semantics
## 2 Canonical Syscall Identity
Syscalls are identified by a **canonical triple**:
```
(module, name, version)
```
Example:
```
("gfx", "present", 1)
("input", "state", 1)
("audio", "play", 2)
```
This identity is:
* Independent of language syntax.
* Stable across languages and toolchains.
* Used for capability checks and linking.
### Language independence
Different languages may reference the same syscall using different syntax:
| Language style | Reference form |
| -------------- | --------------- |
| Dot-based | `gfx.present` |
| Namespace | `gfx::present` |
| Object-style | `Gfx.present()` |
| Functional | `present(gfx)` |
All of these map to the same canonical identity:
```
("gfx", "present", 1)
```
The compiler is responsible for this mapping.
---
## 3 Syscall Resolution
The host maintains a **Syscall Registry**:
```
(module, name, version) -> syscall_id
```
Example:
```
("gfx", "present", 1) -> 0x0101
("gfx", "submit", 1) -> 0x0102
("audio", "play", 1) -> 0x0201
```
### Resolution process
At cartridge load time:
1. The cartridge declares required syscalls using canonical identities.
2. The host verifies capabilities.
3. The host resolves each canonical identity to a numeric `syscall_id`.
4. The VM stores the resolved table for fast execution.
At runtime, the VM executes:
```
SYSCALL <id>
```
Only numeric IDs are used during execution.
---
## 4 Syscall Instruction Semantics
The VM provides a single instruction:
@@ -37,7 +116,7 @@ Where:
Execution steps:
1. The VM looks up the syscall metadata using `<id>`.
1. The VM looks up syscall metadata using `<id>`.
2. The VM verifies that enough arguments exist on the stack.
3. The VM checks capability requirements.
4. The syscall executes in the host environment.
@@ -47,7 +126,7 @@ If any contract rule is violated, the VM traps.
---
## 3 Syscall Metadata Table
## 5 Syscall Metadata Table
Each syscall is defined by a metadata entry.
@@ -56,7 +135,9 @@ Each syscall is defined by a metadata entry.
```
SyscallMeta {
id: u32
module: string
name: string
version: u16
arg_slots: u8
ret_slots: u8
capability: CapabilityId
@@ -69,19 +150,21 @@ Fields:
| Field | Description |
| -------------- | ------------------------------------------------ |
| `id` | Unique syscall identifier |
| `name` | Human-readable name |
| `id` | Unique numeric syscall identifier |
| `module` | Canonical module name |
| `name` | Canonical syscall name |
| `version` | ABI version of the syscall |
| `arg_slots` | Number of input stack slots |
| `ret_slots` | Number of return stack slots |
| `capability` | Required capability |
| `may_allocate` | Whether the syscall may allocate VM heap objects |
| `cost_hint` | Expected cycle cost (for analysis/profiling) |
| `cost_hint` | Expected cycle cost |
The verifier uses this table to validate stack effects.
---
## 4 Arguments and Return Values
## 6 Arguments and Return Values
Syscalls use the same slot-based ABI as functions.
@@ -109,21 +192,11 @@ SYSCALL input_state
// after: [held, pressed, released]
```
### Slot types
Each slot contains one of the VM value types:
* int
* bool
* float
* handle
* null
Composite return values are represented as multiple slots (stack tuples).
---
## 5 Syscalls as Callable Entities (Not First-Class)
## 7 Syscalls as Callable Entities (Not First-Class)
Syscalls behave like functions in terms of arguments and return values, but they are **not first-class values**.
@@ -136,7 +209,7 @@ This means:
Only user-defined functions and closures are first-class.
### Example declaration (conceptual)
### Conceptual declaration
```
host fn input_state() -> (int, int, int)
@@ -146,7 +219,7 @@ This represents a syscall with three return values, but it cannot be treated as
---
## 6 Error Model: Traps vs Status Codes
## 8 Error Model: Traps vs Status Codes
Syscalls use a hybrid error model.
@@ -155,11 +228,12 @@ Syscalls use a hybrid error model.
The VM traps when:
* The syscall id is invalid.
* The canonical identity cannot be resolved.
* The required capability is missing.
* The stack does not contain enough arguments.
* A handle is invalid or dead.
These are considered fatal contract violations.
These are fatal contract violations.
### Status returns (domain conditions)
@@ -175,7 +249,7 @@ These are represented by status codes in return slots.
---
## 7 Capability System
## 9 Capability System
Each syscall requires a capability.
@@ -195,7 +269,7 @@ If a syscall is invoked without the required capability:
---
## 8 Interaction with the Garbage Collector
## 10 Interaction with the Garbage Collector
The VM heap is managed by the GC. Host-managed memory is separate.
@@ -220,7 +294,7 @@ This rule applies only to VM heap objects (such as closures or user objects), no
---
## 9 Determinism Rules
## 11 Determinism Rules
Syscalls must obey deterministic execution rules.
@@ -238,7 +312,7 @@ Allowed patterns:
---
## 10 Cost Model and Budgeting
## 12 Cost Model and Budgeting
Each syscall contributes to frame cost.
@@ -261,7 +335,7 @@ Nothing is free.
---
## 11 Blocking and Long Operations
## 13 Blocking and Long Operations
Syscalls must not block.
@@ -280,15 +354,19 @@ status, progress = asset.status(id)
---
## 12 Summary
## 14 Summary
* Syscalls are deterministic, synchronous, and non-blocking.
* They use the same slot-based ABI as functions.
* They are callable but not first-class.
* They are identified canonically by `(module, name, version)`.
* Language syntax does not affect the ABI.
* The host resolves canonical identities to numeric syscall IDs.
* Capabilities control access to host subsystems.
* GC only manages VM heap objects.
* Host-held heap objects must be registered as roots.
* All syscall costs are tracked per frame.
< [Back](chapter-15.md) | [Summary](table-of-contents.md) >