pr 50
This commit is contained in:
@@ -0,0 +1,167 @@
|
||||
# PBS v0 — Module & Linking Model (Self‑Contained Blob)
|
||||
|
||||
## Status
|
||||
|
||||
**Accepted (v0)** — This specification defines the authoritative execution and linking model for PBS v0.
|
||||
|
||||
---
|
||||
|
||||
## 1. Motivation
|
||||
|
||||
PBS is designed to be executed by a small, deterministic virtual machine embedded in PrometeuOS. To keep the VM **simple, secure, and optimizable**, all *semantic linking* must happen **before runtime**, in the compiler/tooling layer.
|
||||
|
||||
The VM is **not a linker**. It is an executor with validation guarantees.
|
||||
|
||||
---
|
||||
|
||||
## 2. Core Principle
|
||||
|
||||
> **A PBS module must be fully self‑contained and executable as a single blob.**
|
||||
|
||||
There is **no runtime linking** in PBS v0.
|
||||
|
||||
The VM only performs:
|
||||
|
||||
```
|
||||
load → verify → execute
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. What “Linking” Means in PBS
|
||||
|
||||
In PBS, *linking* refers to resolving all symbolic or relative references into a **final, index‑based layout**.
|
||||
|
||||
This includes:
|
||||
|
||||
* Function call resolution
|
||||
* Control‑flow targets (JMP / conditional branches)
|
||||
* Constant pool indexing
|
||||
* Syscall signature binding
|
||||
|
||||
All of this must be **fully resolved by the compiler/toolchain**.
|
||||
|
||||
---
|
||||
|
||||
## 4. PBS v0 Module Structure
|
||||
|
||||
A PBS v0 module consists of:
|
||||
|
||||
* `code: [u8]` — final bytecode stream
|
||||
* `functions: [FunctionMeta]` — function table
|
||||
* `const_pool: [Const]` — constant pool
|
||||
* (optional) metadata (build id, debug info, hashes)
|
||||
|
||||
The module is **self‑contained**: no external symbols, imports, or relocations.
|
||||
|
||||
---
|
||||
|
||||
## 5. Function Table and CALL Semantics
|
||||
|
||||
### 5.1 Function Identification
|
||||
|
||||
Functions are identified **by index** in the function table.
|
||||
|
||||
```text
|
||||
CALL <u32 func_id>
|
||||
```
|
||||
|
||||
There are **no address‑based calls** in PBS v0.
|
||||
|
||||
### 5.2 FunctionMeta
|
||||
|
||||
Each function is described by `FunctionMeta`:
|
||||
|
||||
* `code_offset`
|
||||
* `code_len`
|
||||
* `param_slots`
|
||||
* `local_slots`
|
||||
* `return_slots`
|
||||
* (optional) `max_stack_slots` (precomputed)
|
||||
|
||||
The compiler is responsible for emitting **correct metadata**.
|
||||
|
||||
---
|
||||
|
||||
## 6. Control Flow (JMP / Branches)
|
||||
|
||||
* All jump targets are **relative to the start of the current function**.
|
||||
* Targets must land on **valid instruction boundaries**.
|
||||
|
||||
This eliminates the need for global relocations.
|
||||
|
||||
---
|
||||
|
||||
## 7. Role of the Compiler / Tooling
|
||||
|
||||
The compiler (or offline tooling) is responsible for:
|
||||
|
||||
* Resolving all calls to `func_id`
|
||||
* Emitting the final function table
|
||||
* Laying out code contiguously
|
||||
* Emitting valid jump targets
|
||||
* Computing stack effects (optionally embedding `max_stack_slots`)
|
||||
* Ensuring ABI‑correct syscall usage
|
||||
|
||||
The output must be a **ready‑to‑run PBS module**.
|
||||
|
||||
---
|
||||
|
||||
## 8. Role of the VM
|
||||
|
||||
The VM **does not perform linking**.
|
||||
|
||||
It is responsible for:
|
||||
|
||||
* Parsing the module
|
||||
* Verifying structural and semantic correctness
|
||||
* Executing bytecode deterministically
|
||||
|
||||
### 8.1 Mandatory Runtime Verification
|
||||
|
||||
The VM must always verify:
|
||||
|
||||
* Bytecode truncation / corruption
|
||||
* Stack underflow / overflow
|
||||
* Invalid `func_id`
|
||||
* Invalid jump targets
|
||||
* Syscall signature mismatches
|
||||
|
||||
These checks exist for **safety and determinism**, not for late binding.
|
||||
|
||||
---
|
||||
|
||||
## 9. Legacy and Compatibility Policies
|
||||
|
||||
Legacy formats (e.g. PPBC) may be supported behind explicit policies.
|
||||
|
||||
Example:
|
||||
|
||||
* Legacy `CALL addr` encodings are **rejected** under Policy (A)
|
||||
* Only `CALL func_id` is valid in PBS v0
|
||||
|
||||
Compatibility handling is **orthogonal** to the linking model.
|
||||
|
||||
---
|
||||
|
||||
## 10. Future Evolution (Non‑Goals for v0)
|
||||
|
||||
PBS v0 explicitly does **not** define:
|
||||
|
||||
* Multi‑module linking
|
||||
* Dynamic imports
|
||||
* Runtime symbol resolution
|
||||
* Relocation tables
|
||||
|
||||
These may appear in future versions (v1+), but **v0 is closed and static by design**.
|
||||
|
||||
---
|
||||
|
||||
## 11. Summary
|
||||
|
||||
* PBS modules are **single, self‑contained blobs**
|
||||
* All linking happens **before runtime**
|
||||
* The VM is a **verifying executor**, not a linker
|
||||
* This model enables aggressive optimization, predictability, and simplicity
|
||||
|
||||
This specification is **normative** for PBS v0.
|
||||
@@ -1388,6 +1388,23 @@ This avoids overloading the meaning of `TypeName.member`.
|
||||
|
||||
### 8.7 Summary of Struct Rules
|
||||
|
||||
Full example of `struct`:
|
||||
```pbs
|
||||
declare struct Vector(x: float, y: float)
|
||||
[
|
||||
(): (0.0, 0.0) as default { }
|
||||
(a: float): (a, a) as square { }
|
||||
]
|
||||
[[
|
||||
ZERO: default()
|
||||
]]
|
||||
{
|
||||
pub fn len(self: this): float { ... }
|
||||
pub fn scale(self: mut this): void { ... }
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
* Structs are declared with `declare struct`.
|
||||
* Fields are private and cannot be accessed directly.
|
||||
* Constructor aliases exist only inside the type and are called as `Type.alias(...)`.
|
||||
|
||||
@@ -20,23 +20,6 @@
|
||||
|
||||
---
|
||||
|
||||
## PR-13 — Optional: Refactor Value representation (tagged slots) for clarity
|
||||
|
||||
**Why:** If current `Value` representation is the source of complexity/bugs, refactor now.
|
||||
|
||||
### Scope (only if needed)
|
||||
|
||||
* Make `Slot` explicit:
|
||||
|
||||
* `Slot::I32`, `Slot::I64`, `Slot::U32`, `Slot::Bool`, `Slot::ConstId`, `Slot::GateId`, `Slot::Unit`
|
||||
* Multi-slot types become sequences of slots.
|
||||
|
||||
### Acceptance
|
||||
|
||||
* Simpler, more verifiable runtime.
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done (DoD) for PBS v0 “minimum executable”
|
||||
|
||||
A single canonical cartridge runs end-to-end:
|
||||
|
||||
Reference in New Issue
Block a user