pr 37
This commit is contained in:
@@ -1,6 +1,28 @@
|
||||
> **Hard constraints:**
|
||||
> **Status:** Ready to copy/paste to Junie
|
||||
>
|
||||
> * `ir_core` and `ir_vm` remain **fully decoupled**.
|
||||
> * The only contact point is lowering (`core_to_vm`).
|
||||
> * **No placeholders**, no guessed offsets, no runtime inference of language semantics.
|
||||
> * Every PR must include tests.
|
||||
> **Goal:** expose hardware types **1:1** to PBS and VM as **SAFE builtins** (stack/value), *not* HIP.
|
||||
>
|
||||
> **Key constraint:** Prometeu does **not** have `u16` as a primitive. Use `bounded` for 16-bit-ish hardware scalars.
|
||||
>
|
||||
> **Deliverables (in order):**
|
||||
>
|
||||
> 1. VM hostcall ABI supports returning **flattened SAFE structs** (multi-slot).
|
||||
> 2. PBS prelude defines `Color`, `ButtonState`, `Pad`, `Touch` using `bounded`.
|
||||
> 3. Lowering emits deterministic syscalls for `Gfx.clear(Color)` and `Input.pad()/touch()`.
|
||||
> 4. Runtime implements the syscalls and an integration cartridge validates behavior.
|
||||
>
|
||||
> **Hard rules (do not break):**
|
||||
>
|
||||
> * No heap, no gates, no HIP for these types.
|
||||
> * No `u16` anywhere in PBS surface.
|
||||
> * Returned structs are *values*, copied by stack.
|
||||
> * Every PR must include tests.
|
||||
> * No renumbering opcodes; append only.
|
||||
|
||||
## Notes / Forbidden
|
||||
|
||||
* DO NOT introduce `u16` into PBS.
|
||||
* DO NOT allocate heap for these types.
|
||||
* DO NOT encode `Pad`/`Touch` as gates.
|
||||
* DO NOT change unrelated opcodes.
|
||||
* DO NOT add “convenient” APIs not listed above.
|
||||
|
||||
@@ -1,47 +1,234 @@
|
||||
## PR-11 — Cross-Layer Conformance Tests: Core→VM→Bytecode (HIP)
|
||||
## PR-02 — PBS Prelude: Add SAFE builtins for Color / ButtonState / Pad / Touch (bounded)
|
||||
|
||||
### Goal
|
||||
|
||||
Prove end-to-end determinism and stability.
|
||||
Expose hardware types to PBS scripts as **value structs** using `bounded` (no `u16`).
|
||||
|
||||
### Required Tests
|
||||
### Required PBS definitions (in prelude / hardware module)
|
||||
|
||||
1. PBS snippet (or Core IR fixture) that:
|
||||
> Put these in the standard library surface that PBS sees without user creating them.
|
||||
|
||||
* allocates a storage struct
|
||||
* mutates a field
|
||||
* peeks value
|
||||
```pbs
|
||||
pub declare struct Color(value: bounded)
|
||||
[
|
||||
(r: int, g: int, b: int): (0b) as rgb
|
||||
{
|
||||
...
|
||||
}
|
||||
]
|
||||
[[
|
||||
BLACK: (...) {}
|
||||
WHITE: (...) {}
|
||||
RED: (...) {}
|
||||
GREEN: (...) {}
|
||||
BLUE: (...) {}
|
||||
MAGENTA: (...) {}
|
||||
TRANSPARENT: (...) {}
|
||||
COLOR_KEY: (...) {}
|
||||
]]
|
||||
{
|
||||
pub fn raw(self: Color): bounded;
|
||||
}
|
||||
|
||||
Assert:
|
||||
pub declare struct ButtonState(
|
||||
pressed: bool,
|
||||
released: bool,
|
||||
down: bool,
|
||||
hold_frames: bounded
|
||||
)
|
||||
|
||||
* VM IR contains:
|
||||
pub declare struct Pad(
|
||||
up: ButtonState,
|
||||
down: ButtonState,
|
||||
left: ButtonState,
|
||||
right: ButtonState,
|
||||
a: ButtonState,
|
||||
b: ButtonState,
|
||||
x: ButtonState,
|
||||
y: ButtonState,
|
||||
l: ButtonState,
|
||||
r: ButtonState,
|
||||
start: ButtonState,
|
||||
select: ButtonState
|
||||
)
|
||||
{
|
||||
pub fn any(self: Pad): bool;
|
||||
}
|
||||
|
||||
* `Alloc(type_id, slots)`
|
||||
* `GateBeginMutate/EndMutate`
|
||||
* `GateStore(offset)`
|
||||
* `GateBeginPeek/EndPeek`
|
||||
* `GateLoad(offset)`
|
||||
* RC ops (retain/release)
|
||||
pub declare struct Touch(
|
||||
f: ButtonState,
|
||||
x: int,
|
||||
y: int
|
||||
)
|
||||
```
|
||||
|
||||
2. Bytecode golden output for the same program:
|
||||
### Semantics / constraints
|
||||
|
||||
* assert the exact bytes match the frozen ISA/ABI.
|
||||
* `Color.value` stores the hardware RGB565 *raw* as `bounded`.
|
||||
* `hold_frames` is `bounded`.
|
||||
* `x/y` remain `int`.
|
||||
|
||||
### Implementation notes (binding)
|
||||
|
||||
* `Color.rgb(r,g,b)` must clamp inputs to 0..255 and then pack to RGB565.
|
||||
* `Color.raw()` returns the internal bounded.
|
||||
* `Pad.any()` must be a **pure SAFE** function compiled normally (no hostcall).
|
||||
|
||||
### Tests (mandatory)
|
||||
|
||||
* FE/typecheck: `Color.WHITE` is a `Color`.
|
||||
* FE/typecheck: `Gfx.clear(Color.WHITE)` typechecks.
|
||||
* FE/typecheck: `let p: Pad = Input.pad(); if p.any() { }` typechecks.
|
||||
|
||||
### Non-goals
|
||||
|
||||
* No runtime execution
|
||||
* No heap types
|
||||
* No gates
|
||||
|
||||
---
|
||||
|
||||
## STOP POINT (Hard Gate)
|
||||
## PR-03 — Lowering: Host Contracts for Gfx/Input using deterministic syscalls
|
||||
|
||||
* HIP access is fully deterministic
|
||||
* RC events are explicit and testable
|
||||
* HIP ISA/ABI v0 is frozen with golden bytecode tests
|
||||
### Goal
|
||||
|
||||
Only after this point may we implement/tune:
|
||||
Map PBS host contracts to stable syscalls with a deterministic ABI.
|
||||
|
||||
### Required host contracts in PBS surface
|
||||
|
||||
```pbs
|
||||
pub declare contract Gfx host
|
||||
{
|
||||
fn clear(color: Color): void;
|
||||
}
|
||||
|
||||
pub declare contract Input host
|
||||
{
|
||||
fn pad(): Pad;
|
||||
fn touch(): Touch;
|
||||
}
|
||||
```
|
||||
|
||||
### Required lowering rules
|
||||
|
||||
1. `Gfx.clear(color)`
|
||||
|
||||
* Emit `SYSCALL_GFX_CLEAR`
|
||||
* ABI: args = [Color.raw] as `bounded`
|
||||
* returns: void
|
||||
|
||||
2. `Input.pad()`
|
||||
|
||||
* Emit `SYSCALL_INPUT_PAD`
|
||||
* args: none
|
||||
* returns: flattened `Pad` in field order as declared
|
||||
|
||||
3. `Input.touch()`
|
||||
|
||||
* Emit `SYSCALL_INPUT_TOUCH`
|
||||
* args: none
|
||||
* returns: flattened `Touch` in field order as declared
|
||||
|
||||
### Flattening order (binding)
|
||||
|
||||
**ButtonState** returns 4 slots in order:
|
||||
|
||||
1. pressed (bool)
|
||||
2. released (bool)
|
||||
3. down (bool)
|
||||
4. hold_frames (bounded)
|
||||
|
||||
**Pad** returns 12 ButtonState blocks in this exact order:
|
||||
`up, down, left, right, a, b, x, y, l, r, start, select`
|
||||
|
||||
**Touch** returns:
|
||||
|
||||
1. f (ButtonState block)
|
||||
2. x (int)
|
||||
3. y (int)
|
||||
|
||||
### Tests (mandatory)
|
||||
|
||||
* Lowering golden test: `Gfx.clear(Color.WHITE)` emits `SYSCALL_GFX_CLEAR` with 1 arg.
|
||||
* Lowering golden test: `Input.pad()` emits `SYSCALL_INPUT_PAD` and assigns to local.
|
||||
* Lowering golden test: `Input.touch()` emits `SYSCALL_INPUT_TOUCH`.
|
||||
|
||||
### Non-goals
|
||||
|
||||
* No runtime changes
|
||||
* No VM heap
|
||||
|
||||
---
|
||||
|
||||
## PR-04 — Runtime: Implement syscalls for Color/Gfx and Input pad/touch + integration cartridge
|
||||
|
||||
### Goal
|
||||
|
||||
Make the new syscalls actually work and prove them with an integration test cartridge.
|
||||
|
||||
### Required syscall implementations
|
||||
|
||||
#### 1) `SYSCALL_GFX_CLEAR`
|
||||
|
||||
* Read 1 arg: `bounded` raw color
|
||||
* Convert to `u16` internally (runtime-only)
|
||||
|
||||
* If raw > 0xFFFF, trap `TRAP_OOB` or `TRAP_TYPE` (choose one and document)
|
||||
* Fill framebuffer with that RGB565 value
|
||||
|
||||
#### 2) `SYSCALL_INPUT_PAD`
|
||||
|
||||
* No args
|
||||
* Snapshot the current runtime `Pad` and push a flattened `Pad` return:
|
||||
|
||||
* For each button: pressed, released, down, hold_frames
|
||||
* hold_frames pushed as `bounded`
|
||||
|
||||
#### 3) `SYSCALL_INPUT_TOUCH`
|
||||
|
||||
* No args
|
||||
* Snapshot `Touch` and push flattened `Touch` return:
|
||||
|
||||
* f ButtonState
|
||||
* x int
|
||||
* y int
|
||||
|
||||
### Integration cartridge (mandatory)
|
||||
|
||||
Add `test-cartridges/hw_hello` (or similar) with:
|
||||
|
||||
```pbs
|
||||
fn frame(): void
|
||||
{
|
||||
// 1) clear screen white
|
||||
Gfx.clear(Color.WHITE);
|
||||
|
||||
// 2) read pad and branch
|
||||
let p: Pad = Input.pad();
|
||||
if p.any() {
|
||||
Gfx.clear(Color.MAGENTA);
|
||||
}
|
||||
|
||||
// 3) read touch and branch on f.down
|
||||
let t: Touch = Input.touch();
|
||||
if t.f.down {
|
||||
// choose a third color to prove the struct returned correctly
|
||||
Gfx.clear(Color.BLUE);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Acceptance criteria
|
||||
|
||||
* Cartridge runs without VM faults.
|
||||
* With no input: screen is WHITE.
|
||||
* With any pad button held: screen becomes MAGENTA.
|
||||
* With touch f.down: screen becomes BLUE.
|
||||
|
||||
### Tests (mandatory)
|
||||
|
||||
* Runtime unit test: `SYSCALL_GFX_CLEAR` rejects raw > 0xFFFF deterministically.
|
||||
* Runtime unit test: `SYSCALL_INPUT_PAD` returns correct number of stack slots (48).
|
||||
* Runtime unit test: `SYSCALL_INPUT_TOUCH` returns correct number of stack slots (4 + 2 = 6).
|
||||
|
||||
---
|
||||
|
||||
* Gate Pool
|
||||
* Heap allocation
|
||||
* RC counters + safe point reclaim
|
||||
* Traps at runtime
|
||||
|
||||
Reference in New Issue
Block a user