changes on docs and specs
This commit is contained in:
@@ -0,0 +1,92 @@
|
||||
### Prometeu Bytecode — Core ISA (Minimal, Bytecode‑Only)
|
||||
|
||||
This document defines the minimal, stable Core ISA surface for the Prometeu Virtual Machine at the bytecode level. It specifies instruction encoding, the stack evaluation model, and the instruction set currently available. Higher‑level constructs (closures, coroutines) are intentionally out of scope at this stage.
|
||||
|
||||
#### Encoding Rules
|
||||
|
||||
- Endianness: Little‑endian.
|
||||
- Instruction layout: `[opcode: u16][immediate: spec.imm_bytes]`.
|
||||
- Opcodes are defined in `prometeu_bytecode::isa::core::CoreOpCode`.
|
||||
- Immediate sizes and stack effects are defined by `CoreOpCode::spec()` returning `CoreOpcodeSpec`.
|
||||
- All jump immediates are absolute u32 byte offsets from the start of the current function.
|
||||
|
||||
#### Stack Machine Model
|
||||
|
||||
- The VM is stack‑based. Unless noted, operands are taken from the top of the operand stack and results are pushed back.
|
||||
- Types at the bytecode level are represented by the `Value` enum; the VM may perform numeric promotion where appropriate (e.g., `Int32 + Float -> Float`).
|
||||
- Stack underflow is a trap (TRAP_STACK_UNDERFLOW).
|
||||
- Some operations may trap for other reasons (e.g., division by zero, invalid indices, type mismatches).
|
||||
|
||||
#### Instruction Set (Core)
|
||||
|
||||
- Execution control:
|
||||
- `NOP` — no effect.
|
||||
- `HALT` — terminates execution (block terminator).
|
||||
- `JMP u32` — unconditional absolute jump (block terminator).
|
||||
- `JMP_IF_FALSE u32` — pops `[bool]`, jumps if false.
|
||||
- `JMP_IF_TRUE u32` — pops `[bool]`, jumps if true.
|
||||
- `TRAP` — software trap/breakpoint (block terminator).
|
||||
|
||||
- Stack manipulation:
|
||||
- `PUSH_CONST u32` — load constant by index → _pushes `[value]`.
|
||||
- `PUSH_I64 i64`, `PUSH_F64 f64`, `PUSH_BOOL u8`, `PUSH_I32 i32` — push literals.
|
||||
- `POP` — pops 1.
|
||||
- `POP_N u32` — pops N.
|
||||
- `DUP` — `[x] -> [x, x]`.
|
||||
- `SWAP` — `[a, b] -> [b, a]`.
|
||||
|
||||
- Arithmetic:
|
||||
- `ADD`, `SUB`, `MUL`, `DIV`, `MOD` — binary numeric ops.
|
||||
- `NEG` — unary numeric negation.
|
||||
|
||||
- Comparison and logic:
|
||||
- `EQ`, `NEQ`, `LT`, `LTE`, `GT`, `GTE` — comparisons → `[bool]`.
|
||||
- `AND`, `OR`, `NOT` — boolean logic.
|
||||
- `BIT_AND`, `BIT_OR`, `BIT_XOR`, `SHL`, `SHR` — integer bit operations.
|
||||
|
||||
- Variables:
|
||||
- `GET_GLOBAL u32`, `SET_GLOBAL u32` — access global slots.
|
||||
- `GET_LOCAL u32`, `SET_LOCAL u32` — access local slots (current frame).
|
||||
|
||||
- Functions and scopes:
|
||||
- `CALL u32` — call by function index; argument/result arity per function metadata.
|
||||
- `RET` — return from current function (block terminator).
|
||||
- `PUSH_SCOPE`, `POP_SCOPE` — begin/end lexical scope.
|
||||
|
||||
- System/Timing:
|
||||
- `SYSCALL u32` — platform call; arity/types are verified by the VM/firmware layer.
|
||||
- `FRAME_SYNC` — yield until the next frame boundary (e.g., vblank); explicit safepoint.
|
||||
|
||||
For exact immediates and stack effects, see `CoreOpCode::spec()` which is the single source of truth used by the decoder, disassembler, and (later) verifier.
|
||||
|
||||
#### Canonical Decoder Contract
|
||||
|
||||
- The canonical decoder is `prometeu_bytecode::decode_next(pc, bytes)`.
|
||||
- It uses the Core ISA spec to determine immediate size and the canonical `next_pc`.
|
||||
- Unknown or legacy opcodes must produce a deterministic `UnknownOpcode` error.
|
||||
|
||||
#### Module Boundary
|
||||
|
||||
- Core ISA lives under `prometeu_bytecode::isa::core` and re‑exports:
|
||||
- `CoreOpCode` — the opcode enum of the core profile.
|
||||
- `CoreOpcodeSpec` and `CoreOpCodeSpecExt` — spec with `imm_bytes`, stack effects, and flags.
|
||||
- Consumers (encoder/decoder/disasm/verifier) should import from this module to avoid depending on internal layout.
|
||||
|
||||
#### FRAME_SYNC — Semantics and Placement (Bytecode Level)
|
||||
|
||||
- Semantics:
|
||||
- `FRAME_SYNC` is a zero-operand instruction and does not modify the operand stack.
|
||||
- It marks a VM safepoint for GC and the cooperative scheduler. In `CoreOpcodeSpec` this is exposed as `spec.is_safepoint == true`.
|
||||
- On execution, the VM may suspend the current fiber/coroutine until the next frame boundary (e.g., vsync) and/or perform GC. After resuming, execution continues at the next instruction.
|
||||
|
||||
- Placement rules (representable and checkable):
|
||||
- `FRAME_SYNC` may appear anywhere inside a function body where normal instructions can appear. It is NOT a block terminator (`spec.is_terminator == false`).
|
||||
- Instruction boundaries are canonical: encoders/emitters must only place `FRAME_SYNC` at valid instruction PCs. The verifier already enforces “jump-to-boundary” and end-exclusive `[start, end)` function ranges using the canonical layout routine.
|
||||
- Entrypoints that represent a render/update loop SHOULD ensure at least one reachable `FRAME_SYNC` along every long-running path to provide deterministic safepoints for GC/scheduling. This policy is semantic and may be enforced by higher-level tooling; at the bytecode level it is representable via `spec.is_safepoint` and can be counted by static analyzers.
|
||||
|
||||
- Disassembly:
|
||||
- Disassemblers must print the mnemonic `FRAME_SYNC` verbatim for this opcode.
|
||||
- Tools MAY optionally annotate it as a safepoint in comments, e.g., `FRAME_SYNC ; safepoint`.
|
||||
|
||||
- Verification notes:
|
||||
- The bytecode verifier treats `FRAME_SYNC` as a normal instruction with no stack effect and no control-flow targets. It is permitted before `RET`, between basic blocks, and as the last instruction of a function. Jumps targeting the function end (`pc == end`) remain valid under the end-exclusive rule.
|
||||
@@ -0,0 +1,183 @@
|
||||
PR-1.1 — Bytecode Legacy Inventory & Deletion Map
|
||||
|
||||
Goal
|
||||
- Provide an explicit, reviewable inventory of all RC/HIP-era artifacts (opcodes, traps, types, helpers, docs, tests) and a deletion map for the ISA reset.
|
||||
- No code changes in this PR — documentation only. Follow-up PRs will execute the deletions/edits.
|
||||
|
||||
Repository root
|
||||
- runtime (this file lives at docs/bytecode/RESET_LEGACY_MAP.md)
|
||||
|
||||
Quick grep guide (reviewers)
|
||||
- Use these commands from the project root. They avoid target/ and other generated dirs.
|
||||
|
||||
```
|
||||
# Core RC/HIP signal words
|
||||
grep -RIn --exclude-dir target --exclude-dir dist-staging --exclude-dir dist-workspace \
|
||||
-e '\bHIP\b' -e '\bgate\b' -e 'GATE_' -e '\bretain\b' -e '\brelease\b' -e '\bscope\b' .
|
||||
|
||||
# Legacy opcodes (bytecode + VM handlers)
|
||||
grep -RIn --exclude-dir target \
|
||||
-e 'GateLoad' -e 'GateStore' -e 'GateBeginPeek' -e 'GateEndPeek' \
|
||||
-e 'GateBeginBorrow' -e 'GateEndBorrow' -e 'GateBeginMutate' -e 'GateEndMutate' \
|
||||
-e 'GateRetain' -e 'GateRelease' -e 'Alloc' \
|
||||
crates/console/prometeu-bytecode crates/console/prometeu-vm
|
||||
|
||||
# Scope-related (inventory only; not necessarily to delete)
|
||||
grep -RIn --exclude-dir target -e 'PushScope' -e 'PopScope' crates/console
|
||||
|
||||
# Trap codes inventory (post-reset, check for any lingering gate-specific traps)
|
||||
grep -RIn --exclude-dir target \
|
||||
-e '\bTRAP_\w\+' \
|
||||
crates/console/prometeu-bytecode crates/console/prometeu-vm | grep -Ei 'gate|heap|hip' -n || true
|
||||
|
||||
# Value::Gate usages
|
||||
grep -RIn --exclude-dir target -e 'Value::Gate' crates/console
|
||||
|
||||
# Docs that describe HIP/RC model
|
||||
grep -RIn --exclude-dir target --include '*.md' -e '\bHIP\b' docs files
|
||||
```
|
||||
|
||||
Legend for the deletion map
|
||||
- Remove: file or symbol slated for deletion in follow-up PRs.
|
||||
- Edit: file will survive but needs edits to remove/rename legacy parts.
|
||||
- Keep: file or symbol remains under the GC stack+heap model (not part of RC/HIP removal) — listed here when helpful for context.
|
||||
|
||||
|
||||
1) Legacy opcodes (RC/HIP)
|
||||
|
||||
Remove — OpCode variants (definitions and all references)
|
||||
- prometeu-bytecode
|
||||
- crates/console/prometeu-bytecode/src/opcode.rs
|
||||
- OpCode::Alloc
|
||||
- OpCode::GateLoad
|
||||
- OpCode::GateStore
|
||||
- OpCode::GateBeginPeek, OpCode::GateEndPeek
|
||||
- OpCode::GateBeginBorrow, OpCode::GateEndBorrow
|
||||
- OpCode::GateBeginMutate, OpCode::GateEndMutate
|
||||
- OpCode::GateRetain, OpCode::GateRelease
|
||||
- Notes: also appears in TryFrom<u16> mapping and in cycles() table inside same file.
|
||||
- crates/console/prometeu-bytecode/src/opcode_spec.rs
|
||||
- Spec entries for each of the above (names: GATE_LOAD, GATE_STORE, GATE_BEGIN_PEEK, ... GATE_RELEASE; ALLOC).
|
||||
- crates/console/prometeu-bytecode/src/decoder.rs
|
||||
- Keep file. No direct legacy handling beyond general decoding; remains after removing legacy opcodes.
|
||||
- crates/console/prometeu-bytecode/src/model.rs
|
||||
- Keep file. No opcode definitions here; only payload helpers like imm_u32x2 are generic. No deletion but re-check comments if they reference ALLOC semantics.
|
||||
- crates/console/prometeu-bytecode/src/value.rs
|
||||
- Edit: enum Value includes Gate(usize). This is HIP-only; plan to remove variant and downstream usages when ISA reset lands.
|
||||
- crates/console/prometeu-bytecode/src/program_image.rs
|
||||
- Edit: maps Value to ConstantPoolEntry; has a Value::Gate arm that turns into Null. Will be adjusted once Value::Gate is removed.
|
||||
|
||||
- prometeu-vm (execution semantics for legacy opcodes)
|
||||
- crates/console/prometeu-vm/src/virtual_machine.rs
|
||||
- Match arms for: Alloc, GateLoad/Store, GateBegin*/End* (Peek/Borrow/Mutate), GateRetain/Release.
|
||||
- Gate pool and heap structures (GateEntry, GateId), resolve_gate() helper, and related fields in VM state.
|
||||
- Unit tests tied to HIP/RC model, e.g.:
|
||||
- fn test_hip_traps_oob()
|
||||
- fn test_hip_traps_type()
|
||||
- fn test_invalid_gate_traps()
|
||||
- fn test_gate_ids_distinct_and_round_trip()
|
||||
- crates/console/prometeu-vm/src/scope_frame.rs
|
||||
- Inventory only (scope handling). Scope is not inherently HIP, keep or revise later under GC if needed.
|
||||
|
||||
- prometeu-hal / prometeu-system (touch points)
|
||||
- crates/console/prometeu-hal/src/host_return.rs
|
||||
- Pushes Value::Gate in some host return paths. Will require edits once Value::Gate is removed.
|
||||
- crates/console/prometeu-system/*
|
||||
- No direct HIP opcode handling expected, but grep for Value::Gate and GATE_ in formatting/printing if any.
|
||||
|
||||
|
||||
2) Trap codes (RC/HIP)
|
||||
|
||||
Remove — gate-specific traps (delete constants and all usages)
|
||||
- crates/console/prometeu-bytecode/src/abi.rs
|
||||
- Remove identifiers tied to HIP/gate semantics
|
||||
|
||||
Keep — still meaningful under GC model (names may be revised later, but remain functionally)
|
||||
- crates/console/prometeu-bytecode/src/abi.rs
|
||||
- TRAP_OOB (0x03) — out-of-bounds (generic)
|
||||
- TRAP_INVALID_SYSCALL (0x0000_0007)
|
||||
- TRAP_STACK_UNDERFLOW (0x0000_0008)
|
||||
- TRAP_INVALID_LOCAL (0x0000_0009)
|
||||
- TRAP_DIV_ZERO (0x0000_000A)
|
||||
- TRAP_INVALID_FUNC (0x0000_000B)
|
||||
- TRAP_BAD_RET_SLOTS (0x0000_000C)
|
||||
- TRAP_TYPE — retained; semantics generalized to non-HIP type mismatches
|
||||
|
||||
Usages to edit alongside removal
|
||||
- crates/console/prometeu-vm/src/virtual_machine.rs
|
||||
- Imports: remove any gate-specific trap imports
|
||||
- resolve_gate() and gate handlers construct TrapInfo with those codes
|
||||
- Tests asserting these trap codes
|
||||
|
||||
|
||||
3) Legacy terminology occurrences (inventory)
|
||||
|
||||
Gate/GATE_
|
||||
- Files containing gate-centric logic or names:
|
||||
- crates/console/prometeu-bytecode/src/opcode.rs — Gate* opcodes
|
||||
- crates/console/prometeu-bytecode/src/opcode_spec.rs — GATE_* names
|
||||
- crates/console/prometeu-bytecode/src/value.rs — Value::Gate
|
||||
- crates/console/prometeu-vm/src/virtual_machine.rs — GateEntry, GateId, handlers, tests
|
||||
- docs/specs/pbs/Prometeu VM Memory model.md — extensive HIP/gate sections
|
||||
- docs/specs/pbs/Prometeu Scripting - Prometeu Bytecode Script (PBS).md — HIP/gate model and APIs
|
||||
|
||||
Retain/Release (RC semantics)
|
||||
- Opcode names: GateRetain, GateRelease — bytecode + VM
|
||||
- Docs: reference counting sections in PBS and VM Memory model docs
|
||||
|
||||
Scope
|
||||
- Opcode names: PushScope, PopScope — present in opcode.rs/opcode_spec.rs and executed in VM
|
||||
- VM scope_frame.rs and scope_stack usage — not inherently HIP, but inventoried here per task wording
|
||||
|
||||
HIP (Heap Interface Protocol)
|
||||
- Labelled sections/comments:
|
||||
- crates/console/prometeu-bytecode/src/opcode.rs — comment header “HIP (Heap Interface Protocol)” above Gate* opcodes
|
||||
- docs/specs/pbs/Prometeu VM Memory model.md — HIP-specific architecture
|
||||
- docs/specs/pbs/Prometeu Scripting - Prometeu Bytecode Script (PBS).md — HIP world, borrow/mutate/peek, RC
|
||||
- files/Borrow Mutate - Compiler GC.md — discusses removing RC/HIP in favor of GC; keep as design context but will need text updates after reset
|
||||
|
||||
|
||||
4) Deletion map (by module)
|
||||
|
||||
Will be removed outright (symbols or blocks)
|
||||
- prometeu-bytecode
|
||||
- opcode.rs: all Gate* variants and Alloc variant; TryFrom/encoding IDs and cycles for those
|
||||
- opcode_spec.rs: corresponding spec arms (GATE_*, ALLOC)
|
||||
- abi.rs: gate-specific trap constants
|
||||
- prometeu-vm
|
||||
- virtual_machine.rs: handlers for Alloc and all Gate* opcodes; GateEntry/GateId data structures; resolve_gate(); HIP-focused unit tests listed above
|
||||
|
||||
Will be edited (kept but changed)
|
||||
- prometeu-bytecode
|
||||
- value.rs: remove Value::Gate and update Display/eq code paths
|
||||
- program_image.rs: remove/adjust Value::Gate mapping in constant pool materialization
|
||||
- decoder.rs: no semantic change; ensure UnknownOpcode remains deterministic (already the case)
|
||||
- prometeu-vm
|
||||
- virtual_machine.rs: remove trap imports for legacy codes; update match to exclude removed opcodes; prune gate/heap fields
|
||||
- scope_frame.rs: keep unless later ISA changes require scope model changes (not part of HIP removal)
|
||||
- prometeu-hal
|
||||
- host_return.rs: stop producing Value::Gate once Value enum loses Gate
|
||||
|
||||
Docs to remove or rewrite (architecture reset)
|
||||
- docs/specs/pbs/Prometeu VM Memory model.md — replace HIP/RC model with GC stack+heap model
|
||||
- docs/specs/pbs/Prometeu Scripting - Prometeu Bytecode Script (PBS).md — remove HIP world/RC sections; update storage semantics
|
||||
- Any disasm examples or golden outputs referring to GATE_* or ALLOC — update after opcode removal
|
||||
|
||||
Tests/fixtures affected
|
||||
- Unit tests in prometeu-vm referencing HIP traps or Gate behavior:
|
||||
- test_hip_traps_oob, test_hip_traps_type, test_invalid_gate_traps, test_gate_ids_distinct_and_round_trip
|
||||
- Golden disassemblies under test-cartridges/*/build/program.disasm.txt may include GATE_* lines — grep and update in follow-up PRs
|
||||
|
||||
|
||||
5) Reviewer checklist for follow-up PRs
|
||||
- Bytecode enum/spec cleaned: no Gate*/Alloc variants remain
|
||||
- VM execution has no references to Gate/GateEntry/resolve_gate
|
||||
- Value enum no longer has Gate; all Display/eq/serde paths fixed
|
||||
- Trap ABI contains only GC-era traps (OOB, stack underflow, invalid func/local/syscall, div by zero, bad ret slots, etc.)
|
||||
- Disassembler/printers do not print legacy names (GATE_*, ALLOC)
|
||||
- Docs no longer mention HIP/RC; updated to GC model
|
||||
- All tests green (`cargo test`) after deletions and necessary test updates
|
||||
|
||||
|
||||
6) Notes
|
||||
- This document inventories occurrences proactively, but exact refactors in the reset may slightly shift responsibilities (e.g., how storage allocation appears under GC). Use the grep guide to double-check any stragglers during code deletion PRs.
|
||||
Reference in New Issue
Block a user