93 lines
3.6 KiB
Markdown
93 lines
3.6 KiB
Markdown
# PBS Bytecode and PBX Mapping Specification
|
|
|
|
Status: Draft v0 (Skeleton)
|
|
Applies to: mapping from lowered PBS programs into PBX sections, bytecode-facing artifacts, and related source-to-artifact invariants
|
|
|
|
## 1. Purpose
|
|
|
|
This document will define the normative mapping between lowered PBS semantics and emitted PBX/bytecode-facing artifacts.
|
|
|
|
## 2. Scope
|
|
|
|
This document is intended to define:
|
|
|
|
- artifact-level obligations after lowering,
|
|
- mapping of semantic constructs into PBX-visible structures,
|
|
- source-to-artifact invariants required by verifier and loader stages,
|
|
- interaction points with host-binding metadata such as `SYSC`,
|
|
- interaction points with VM-owned builtin and intrinsic metadata.
|
|
|
|
This document does not define:
|
|
|
|
- the full bytecode ISA,
|
|
- UI/tooling presentation,
|
|
- one compiler's internal IR representation.
|
|
|
|
## 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. `6.1. Intrinsics and Builtin Types Specification.md`
|
|
4. `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
5. `12. IR and Lowering Specification.md`
|
|
6. This document
|
|
|
|
If a rule here conflicts with higher-precedence authorities, it is invalid.
|
|
|
|
## 4. Normative Inputs
|
|
|
|
This document depends on, at minimum:
|
|
|
|
- `6.1. Intrinsics and Builtin Types Specification.md`
|
|
- `6.2. Host ABI Binding and Loader Resolution Specification.md`
|
|
- `12. IR and Lowering Specification.md`
|
|
|
|
## 5. Already-Settled Inputs
|
|
|
|
The following inputs are already fixed elsewhere and must not be contradicted here:
|
|
|
|
- The compiler emits host-binding declarations into 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` into `SYSCALL`.
|
|
- VM-owned builtin projections, builtin constants, and intrinsic callsites do not emit host-binding metadata.
|
|
- VM-owned intrinsic artifacts are distinct from `SYSC`, `HOSTCALL`, and `SYSCALL`.
|
|
|
|
## 6. Initial Section Targets
|
|
|
|
At minimum, the completed document should contain normative sections for:
|
|
|
|
1. artifact mapping goals,
|
|
2. section-level invariants,
|
|
3. callsite and control-flow mapping invariants,
|
|
4. metadata mapping obligations,
|
|
5. intrinsic and builtin artifact obligations,
|
|
6. source-attribution hooks for diagnostics/conformance.
|
|
|
|
## 7. A Ver
|
|
|
|
The following items remain to be closed in future agenda discussion.
|
|
|
|
- Which PBX sections beyond `SYSC` are part of the PBS-facing contract.
|
|
- Whether a distinct intrinsic declaration section is part of the PBS-facing contract in v1.
|
|
- Which source-level constructs require dedicated artifact patterns versus implementation freedom.
|
|
- How much of artifact ordering, numbering, and layout is normative at PBS level versus owned purely by PBX authority.
|
|
- Whether compilers should emit final `INTRINSIC <id>` directly for a selected VM line or may emit a declaration-based preload form such as `INTRCALL <decl_index>`.
|
|
- Whether a separate debug/source-map surface is part of v1.
|
|
|
|
## 8. Non-Goals
|
|
|
|
- Repeating the full PBX or ISA documentation.
|
|
- Mandating one binary-emitter implementation strategy.
|
|
- Defining loader patching internals already owned elsewhere.
|
|
|
|
## 9. Exit Criteria
|
|
|
|
This document is ready to move beyond skeleton status only when:
|
|
|
|
1. the PBS-to-artifact boundary is explicit,
|
|
2. artifact-level invariants needed by verifier and loader are normative,
|
|
3. the document no longer relies on unresolved `A Ver` items for ordinary v1 artifact mapping behavior.
|