184 lines
6.9 KiB
Markdown
184 lines
6.9 KiB
Markdown
# PBS Bytecode and PBX Mapping Specification
|
|
|
|
Status: Draft v1 (Backend Baseline)
|
|
Applies to: mapping from lowered/optimized backend programs into PBX sections, bytecode-facing artifacts, and source-to-artifact invariants required by loader/verifier/runtime
|
|
|
|
## 1. Purpose
|
|
|
|
This document defines the normative mapping between backend-lowered semantics and emitted PBX/bytecode-facing artifacts.
|
|
|
|
Its purpose is to keep artifact emission deterministic and compatible with runtime loader/verifier contracts.
|
|
|
|
## 2. Scope
|
|
|
|
This document defines:
|
|
|
|
- artifact-level obligations at `IRVM -> BytecodeModule` emission boundary,
|
|
- mapping invariants for function layout, code layout, callsite forms, and host-binding declarations,
|
|
- minimum debug/source-attribution hooks for v1 backend/runtime diagnostics and conformance,
|
|
- and deterministic artifact rejection expectations for emitter-side failures.
|
|
|
|
This document does not define:
|
|
|
|
- full ISA semantics,
|
|
- runtime loader patching internals,
|
|
- or one mandatory emitter implementation architecture.
|
|
|
|
## 3. Authority and Precedence
|
|
|
|
Normative precedence:
|
|
|
|
1. Runtime authority (`docs/specs/hardware/topics/chapter-2.md`, `chapter-3.md`, `chapter-9.md`, `chapter-12.md`, `chapter-16.md`)
|
|
2. Bytecode authority (`docs/specs/bytecode/ISA_CORE.md`)
|
|
3. `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
|
|
4. `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
5. `20. IRBackend to IRVM Lowering Specification.md`
|
|
6. `21. IRVM Optimization Pipeline Specification.md`
|
|
7. This document
|
|
|
|
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
|
|
|
## 4. Normative Inputs
|
|
|
|
This document depends on, at minimum:
|
|
|
|
- `docs/specs/compiler-languages/pbs/6.1. Intrinsics and Builtin Types Specification.md`
|
|
- `docs/specs/compiler-languages/pbs/6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
- `20. IRBackend to IRVM Lowering Specification.md`
|
|
- `21. IRVM Optimization Pipeline Specification.md`
|
|
|
|
## 5. Already-Settled Inputs
|
|
|
|
The following are fixed and must not be contradicted:
|
|
|
|
- The compiler emits host-binding declarations in PBX `SYSC`.
|
|
- Host-backed callsites are emitted in pre-load form as `HOSTCALL <sysc_index>`.
|
|
- `SYSC` entries are deduplicated by canonical identity and ordered by first occurrence.
|
|
- The loader resolves host bindings and rewrites `HOSTCALL` to `SYSCALL` before execution.
|
|
- Raw `SYSCALL` in pre-load artifacts is rejected.
|
|
- VM-owned intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
|
|
- `SYSC` section is mandatory in valid PBX artifacts (empty section is valid).
|
|
|
|
## 6. Artifact Mapping Contract (v1)
|
|
|
|
### 6.1 Required module surfaces
|
|
|
|
Emitter output must map to a `BytecodeModule` shape containing:
|
|
|
|
1. `const_pool`,
|
|
2. `functions`,
|
|
3. `code`,
|
|
4. `exports`,
|
|
5. `syscalls`,
|
|
6. optional `debug_info` that still satisfies v1 minimum debug obligations.
|
|
|
|
### 6.2 Function ordering and IDs
|
|
|
|
Function ordering must be deterministic:
|
|
|
|
1. the published wrapper function index is `0`,
|
|
2. function index `0` is owned by the compiler-selected physical wrapper rather than by manifest metadata or nominal export lookup,
|
|
3. remaining functions are ordered by `(moduleId -> modulePool canonical key, callable_name, source_start)`,
|
|
4. identical admitted input graph yields identical function ordering and function ids.
|
|
|
|
For PBS executable publication:
|
|
|
|
- the userland callable marked with `[Frame]` is not itself the physical entrypoint unless it is wrapped by the published synthetic wrapper,
|
|
- final `FRAME_RET` belongs to the wrapper path.
|
|
|
|
### 6.3 Function code layout
|
|
|
|
Emitter must satisfy:
|
|
|
|
1. `code_offset` values are unique and monotonic over function order,
|
|
2. `code_len` exactly matches emitted bytes for each function body,
|
|
3. `code_offset + code_len` stays within `code.len`,
|
|
4. and final code concatenation is deterministic.
|
|
|
|
### 6.4 Instruction encoding
|
|
|
|
Emitter must satisfy:
|
|
|
|
1. little-endian encoding,
|
|
2. instruction layout `[opcode: u16][immediate]`,
|
|
3. jump immediates as `u32` offsets relative to function start,
|
|
4. immediate sizes matching selected Core ISA opcode spec.
|
|
|
|
### 6.5 Host-backed mapping obligations
|
|
|
|
For host-backed operations:
|
|
|
|
1. emit canonical declarations in `SYSC` (`module`, `name`, `version`, `arg_slots`, `ret_slots`),
|
|
2. deduplicate by canonical identity,
|
|
3. order by first occurrence,
|
|
4. emit callsites as `HOSTCALL <sysc_index>` only,
|
|
5. do not emit raw `SYSCALL` in pre-load artifact form.
|
|
|
|
### 6.6 VM-owned intrinsic mapping obligations
|
|
|
|
For VM-owned intrinsic operations:
|
|
|
|
1. emit VM-owned intrinsic call form (`INTRINSIC <id>`),
|
|
2. resolve `<id>` from the canonical ISA-scoped intrinsic registry artifact,
|
|
3. keep intrinsic path distinct from host-binding metadata and host call opcodes,
|
|
4. and do not emit VM-owned builtin/intrinsic semantics through `SYSC`.
|
|
|
|
### 6.7 Internal symbolic-to-index mapping
|
|
|
|
Compilers may use internal symbolic references before final index materialization.
|
|
|
|
If used, symbolic references must be resolved deterministically to final numeric indices before serialization.
|
|
|
|
## 7. Minimum Debug Attribution Contract (v1)
|
|
|
|
For v1 backend/runtime diagnostics and conformance support, emitted artifacts must preserve at minimum:
|
|
|
|
1. `function_names` entries for all emitted function indices,
|
|
2. `pc_to_span` entries for each emitted instruction start PC.
|
|
|
|
This minimum does not require one universal source-map format.
|
|
|
|
## 8. Deterministic Emitter Rejection
|
|
|
|
Emitter-side rejection must be deterministic for malformed or inconsistent artifact candidates, including at minimum:
|
|
|
|
1. inconsistent function layout bounds,
|
|
2. unresolved symbolic references at serialization boundary,
|
|
3. illegal pre-load host call form (`SYSCALL` in pre-load image),
|
|
4. duplicate `SYSC` canonical identities,
|
|
5. and declared host ABI shape mismatch detectable at compile target metadata line.
|
|
|
|
## 9. Conformance-Facing Baseline
|
|
|
|
At minimum, artifact conformance checks should assert:
|
|
|
|
1. canonical `SYSC` declarations for admitted host-backed operations,
|
|
2. deterministic `SYSC` dedup/order,
|
|
3. pre-load `HOSTCALL` callsites for host-backed paths,
|
|
4. no host-binding leakage for VM-owned intrinsic/builtin operations,
|
|
5. minimum debug attribution hooks required by v1,
|
|
6. deterministic function ordering and code layout invariants.
|
|
|
|
## 10. Explicit Deferrals
|
|
|
|
The following remain deferred:
|
|
|
|
- richer optional debug/source-map formats,
|
|
- additional PBX section-level contracts beyond current baseline,
|
|
- and profile-specific binary compatibility policy details beyond current v1 baseline.
|
|
|
|
## 11. Non-Goals
|
|
|
|
- Repeating full ISA/runtime documentation.
|
|
- Mandating one byte-for-byte whole-image golden as sole conformance oracle.
|
|
- Defining loader patching internals already owned elsewhere.
|
|
|
|
## 12. Exit Criteria
|
|
|
|
This document is healthy when:
|
|
|
|
1. artifact mapping obligations are explicit and testable,
|
|
2. host-backed and VM-owned emission boundaries are explicit,
|
|
3. deterministic ordering/layout rules are explicit,
|
|
4. and v1 minimum debug/source attribution contract is explicit.
|