pr5
This commit is contained in:
@@ -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) >
|
||||
Reference in New Issue
Block a user