168 lines
3.8 KiB
Markdown
168 lines
3.8 KiB
Markdown
# 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.
|