Author SHA1 Message Date
bquarkz 22769aa438 docs: close runtime quality review with consolidated lesson
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
2026-10-14 14:09:12 +01:00
bquarkz 3f9d235546 Index string provenance with metered image and session tables 2026-10-14 13:55:16 +01:00
bquarkz bb6f212779 Share asset decoding validation and reject truncated payloads 2026-10-14 13:08:34 +01:00
bquarkz 418e574ac8 ci: enforce a shared strict repository quality gate 2026-10-14 12:14:11 +01:00
bquarkz 461b554c1a perf(audio): reclaim callback owners through bounded return packets 2026-10-14 11:59:47 +01:00
bquarkz 46bbad19c2 perf(vm): eliminate recurring stack and return allocations 2026-10-14 10:54:11 +01:00
bquarkz e09f1197bc fix(audio): preserve full sample boundaries for one-shot playback 2026-10-14 10:46:03 +01:00
bquarkz ff73f8ad39 fix(coverage): restore specialized domain ownership and floors 2026-10-14 10:35:41 +01:00
bquarkz bad942fb25 fix(memcard): preserve watchdog timeout reasons across completion 2026-10-14 10:26:30 +01:00
bquarkz e0e01ed1de feat(audio): add guest voice controls and reliable lifecycle delivery
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-10-14 09:08:27 +01:00
bquarkz 3899b7f12c feat(vm): add resource diagnostics and macOS stability qualification
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-10-14 08:26:07 +01:00
bquarkz 6c2a07e579 feat(runtime): implement shared transactional memcard with async saves
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-10-13 15:24:01 +01:00
bquarkz 0af8b2b1fe feat(runtime): add optional pause and resume lifecycle hooks
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...
2026-10-13 12:18:18 +01:00
bquarkz 23dc6fc66d feat(runtime): add host wall clock and administrative UTC timestamps
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-10-13 09:16:15 +01:00
bquarkz 3e39a90083 feat(vm): add VM-owned PCG64 random and coverage headroom
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Implement GC-managed random generators, next/nextf intrinsics, bounded ranges and deterministic conformance coverage. Publish the runtime contract and producer guidance.

Give coverage domains at least five percentage points of measured headroom while preserving sufficient floors. Record local qualification: make ci-domains passes with 939 tests and all domain gates green.
2026-10-09 12:51:05 +01:00
bquarkz 9318cf7cd3 feat(vm): add deterministic gameplay math and domain coverage gates
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
2026-10-09 10:25:11 +01:00
bquarkz 2e041266f1 fix(vm): enforce return boundaries and amortize budgeted growth
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Validate and complete function-end branches through the shared return path. Handle integer DIV/MOD overflow with wrapping and charge CALL/RET refusals exactly once.

Amortize budgeted vector growth with exact-capacity fallback at quota limits. Add execution and accounting regressions, clarify ISA contracts, and include existing lint cleanups.
2026-10-09 06:35:51 +01:00
bquarkz ec84a6bba5 feat(vm)!: implement typed callables and single-context execution
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Add structural Fn signatures, typed capture environments, indirect calls and Trait dispatch while preserving logical parameter and result groups, ownership and budgets.

Remove guest coroutine execution and legacy loading. Activate bounded sealed PBX v1 with mandatory capture metadata, preserve frame continuations and root return results, and migrate producers and shipped cartridges.

Publish coordinated specs, handoffs and the completed runtime lesson. Validation: 880 workspace tests passed, 9 existing tests ignored; both cartridges completed six production-host frames.
2026-10-09 05:47:24 +01:00
bquarkz 86bade3e1f feat(vm): add typed array and struct guest operations
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Add seven Registry-backed collection opcodes with bounded verification, complete value groups, transactional publication and exact attempt costs. Publish ISA, memory and cycle contracts, producer handoff and the completed lesson.

Validate with 925 workspace tests, optimized collection suites and all eight coverage domain gates. Make headless fixture directory names unique for parallel tests.
2026-10-08 10:36:20 +01:00
bquarkz 8732f4b0f4 test: align coverage baselines with a five-point margin
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-10-08 08:44:39 +01:00
bquarkz 61cf41f088 fix: resolve Clippy warnings across all workspace targets 2026-10-08 08:41:20 +01:00
bquarkz 8381800fce docs: replace ephemeral workflow references with durable lessons 2026-10-08 08:34:32 +01:00
bquarkz d48978988e docs(discussion): close atomic Registry delivery for PLN-0176 step 36 2026-10-08 08:29:39 +01:00
bquarkz dd3594240e perf(registry): record bounded layout load and GC evidence for PLN-0176 step 35 2026-10-07 21:36:16 +01:00
bquarkz c6fff08e7c test(vm): prove Dynamic box roots across safepoint GC for PLN-0176 step 20 2026-10-07 21:32:04 +01:00
bquarkz 7e3d61c52d test(vm): verify typed storage string ownership for PLN-0176 step 18 2026-10-07 21:32:03 +01:00
bquarkz 78b6312d6b test(registry): exercise sealed PBX conformance for PLN-0176 step 32 2026-10-07 21:26:55 +01:00
bquarkz dac72c5e73 docs(registry): publish producer handoff and named argument oracle for PLN-0176 step 31 2026-10-07 21:18:16 +01:00
bquarkz 63e371955a feat(diagnostics): preserve Registry and resource fault context for PLN-0176 step 28 2026-10-07 21:13:59 +01:00
bquarkz 74c7522dd1 feat(vm): integrate metered strings and native retention for PLN-0176 step 19 2026-10-07 20:50:44 +01:00
bquarkz 1124ac10e7 feat(vm): execute reference tests and casts for PLN-0176 step 22 2026-10-07 20:36:28 +01:00
bquarkz c7236f1269 feat(vm): execute Dynamic instructions and exact costs for PLN-0176 step 21 2026-10-07 20:34:11 +01:00
bquarkz ba603ce64a feat(vm): enforce typed CALL RET and native entry boundaries for PLN-0176 step 26 2026-10-07 20:32:09 +01:00
bquarkz a9d91be39e feat(vm): publish validated shared PBX v1 images for PLN-0176 step 14 2026-10-07 20:26:01 +01:00
bquarkz a563f3b456 feat(loader): materialize bounded PBX v1 payloads for PLN-0176 step 09 2026-10-07 20:25:25 +01:00
bquarkz 43b466c813 feat(vm): add metered shared-string infrastructure for PLN-0176 step 19 2026-10-07 19:24:54 +01:00
bquarkz 01112da951 feat(verifier): add conservative type flow for PLN-0176 step 25 2026-10-07 19:09:37 +01:00
bquarkz 8d32fef65c feat(vm): add reference conversion helpers for PLN-0176 step 22 2026-10-07 18:27:10 +01:00
bquarkz 60d66d22a5 feat(verifier): add bounded stack analysis for PLN-0176 step 24 2026-10-07 18:27:09 +01:00
bquarkz 43314573d7 fix(loader): bound PBX input admission for PLN-0176 step 09 2026-10-07 17:58:16 +01:00
bquarkz dff4041de7 feat(bytecode): complete PLN-0176 step 08 typed PBX v1 writer 2026-10-07 17:53:30 +01:00
bquarkz 126a9e50e7 feat(registry): checkpoint PLN-0176 foundations and validated partial integrations 2026-10-07 17:49:46 +01:00
bquarkz 01fab56cc6 Merge pull request 'feat: add headless automation protocol and CLI' (#41) from dev/studio-headless-runtime-ai-first into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #41
2026-09-28 16:29:00 +00:00
bquarkz 4f10f6e584 feat: add headless automation protocol and CLI
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-09-28 15:36:22 +01:00
bquarkz e8e4d64e42 chore: keep only discussion lessons tracked
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-09-24 06:14:02 +01:00
bquarkz 31ad7f9446 bump new version and updates
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-09-24 06:08:53 +01:00
bquarkz 6d185ab97e Merge pull request 'harden deterministic headless runtime control' (#40) from dev/headless-automation-host-hardening into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #40
2026-09-23 06:30:01 +00:00
310 changed files with 51893 additions and 9826 deletions
+17 -7
View File
@@ -15,15 +15,25 @@ jobs:
- uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt, clippy
components: rustfmt, clippy, llvm-tools-preview
- uses: Swatinem/rust-cache@v2
- name: Format check
run: cargo fmt -- --check
- name: Discard reports from previous runs
run: rm -rf target/quality-gate target/llvm-cov
- name: Clippy
run: cargo clippy --workspace --all-features
- name: Provision quality-gate tools and native dependencies
run: bash scripts/provision-quality-gate.sh
- name: Test
run: cargo test --workspace --all-targets --all-features --no-fail-fast
- name: Repository quality gate
run: make ci-domains
- name: Publish gate evidence (including failures)
if: always()
uses: actions/upload-artifact@v4
with:
name: quality-gate-${{ runner.os }}-${{ github.sha }}
path: |
target/quality-gate/**
target/llvm-cov/**
if-no-files-found: warn
+4
View File
@@ -66,3 +66,7 @@ AGENTS.md
.python-version
.venv
discussion/*
!discussion/lessons/
!discussion/lessons/**
Generated
+1148 -348
View File
File diff suppressed because it is too large Load Diff
+18 -7
View File
@@ -1,19 +1,19 @@
.PHONY: fmt fmt-check clippy test-local test-debugger-socket clean coverage coverage-xml coverage-json coverage-report-json coverage-domain-list coverage-domain-evidence coverage-domain-gate test ci ci-domains cobertura
.PHONY: fmt fmt-check clippy test-local test-debugger-socket clean coverage coverage-xml coverage-json coverage-report-json coverage-domain-list coverage-domain-evidence coverage-domain-audit coverage-domain-gate test ci ci-domains test-quality-gate cobertura
fmt:
cargo fmt
cargo fmt --all
fmt-check:
cargo fmt -- --check
cargo fmt --all -- --check
clippy:
cargo clippy --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
test-local:
cargo test --workspace --all-targets --all-features --no-fail-fast
test-debugger-socket:
cargo test -p prometeu-host-desktop-winit --lib -- --ignored
cargo test -p prometeu-host-desktop-winit --lib runner::tests -- --ignored
clean:
cargo llvm-cov clean --workspace
@@ -33,6 +33,9 @@ coverage-json:
coverage-domain-list:
./scripts/coverage-domain-evidence.sh --list
coverage-domain-audit:
python3 scripts/audit-coverage-domains.py --report target/llvm-cov/report.json
coverage-domain-evidence:
@if [ -z "$(DOMAIN)" ]; then \
echo "usage: make coverage-domain-evidence DOMAIN=<domain>"; \
@@ -44,6 +47,14 @@ coverage-domain-gate:
./scripts/coverage-domain-evidence.sh --check-all
test: fmt-check clippy test-local test-debugger-socket
ci: clean fmt-check clippy coverage coverage-report-json
ci-domains: clean fmt-check clippy coverage coverage-report-json coverage-xml coverage-json coverage-domain-gate
# Keep the step list here: CI providers consume the repository contract.
# The runner executes each step serially even if the caller supplies make -j.
CI_DOMAIN_STEPS = clean fmt-check clippy test-quality-gate test-local test-debugger-socket coverage coverage-report-json coverage-xml coverage-json coverage-domain-audit coverage-domain-gate
ci: ci-domains
ci-domains:
python3 scripts/run-quality-gate.py $(CI_DOMAIN_STEPS)
test-quality-gate:
python3 -B -m unittest discover -s scripts/tests -p 'test_quality_gate.py'
cobertura: coverage-xml coverage-json
+14 -19
View File
@@ -107,19 +107,19 @@ Format, lint, and test the workspace:
make test
```
Run the CI-oriented non-domain gate:
Run the shared strict CI gate (`make ci` is an alias):
```bash
make ci
```
Run the CI-oriented domain coverage gate:
The authoritative target used by both GitHub and Jenkins is:
```bash
make ci-domains
```
The debugger socket tests bind localhost sockets and are marked ignored in Rust test metadata; `make test` includes them through the dedicated `test-debugger-socket` target.
The five debugger socket tests bind localhost sockets and are marked ignored in Rust test metadata; both `make test` and `make ci-domains` select only `runner::tests` through `test-debugger-socket`. Physical audio and other manual probes remain opt-in. See [quality-gate prerequisites and commands](docs/vm-arch/COVERAGE_DOMAINS.md#commands-and-ci).
## Coverage Governance
@@ -128,20 +128,14 @@ The repository uses a two-layer runtime-edge coverage model:
- a mandatory CI gate based on canonical runtime-edge domains;
- domain-oriented review evidence for the canonical runtime-edge domains.
Current canonical domains:
- `system/runtime`
- `fs`
- `asset/bank`
- `firmware`
- `host-dependent`
- `host/headless`
The fifteen canonical domains and fixed floors are defined in
[the repository configuration](files/config/runtime-edge-coverage-domains.json).
Use `make coverage-domain-list` or the [ownership documentation](docs/vm-arch/COVERAGE_DOMAINS.md)
to inspect the current map.
Global coverage artifacts:
```bash
make ci
make cobertura
make ci-domains
```
@@ -151,6 +145,7 @@ This produces:
- `target/llvm-cov/report.json`
- `target/llvm-cov/summary.json`
- `target/llvm-cov/cobertura.xml`
- `target/quality-gate/metadata.json` and per-step logs
Domain-oriented evidence helpers:
@@ -161,12 +156,12 @@ make coverage-domain-evidence DOMAIN=host-dependent
make coverage-domain-evidence DOMAIN=host/headless
```
Per-domain baselines currently start around `60`.
That does not waive test obligations. It means the project is adopting explicit domain evidence immediately while tightening quantitative expectations incrementally over time.
`make ci-domains` is the CI entrypoint used by Jenkins.
It runs the standard coverage pipeline, produces the HTML/XML/JSON artifacts, and fails when any canonical domain falls below its configured `baseline_percent`.
The CI gate currently compares domain `lines` coverage against each domain baseline.
`make ci-domains` runs formatting, strict workspace/all-target/all-feature Clippy,
all-target tests, the five debugger socket tests, fresh coverage and every domain
ownership/evidence gate. Both CI providers archive available evidence on failure.
A failing run never lowers a configured floor; local and CI checks use the same
repository-owned commands. Reports identify their revision, source/configuration
and actual execution platform.
When a PR changes the observable contract of a canonical domain, it is expected to:
@@ -24,6 +24,21 @@ pub const TRAP_BAD_RET_SLOTS: u32 = 0x0000_000C;
/// The intrinsic ID provided is not recognized by the runtime, or its metadata is invalid.
pub const TRAP_INVALID_INTRINSIC: u32 = 0x0000_000D;
/// Valid absence used where an instance is required.
pub const TRAP_NULL_REFERENCE: u32 = 0x0000_000E;
/// Invalid, dead or stale generational heap reference.
pub const TRAP_INVALID_HANDLE: u32 = 0x0000_000F;
/// Quota, checked size overflow or recoverable allocation failure.
pub const TRAP_RESOURCE_LIMIT: u32 = 0x0000_0010;
/// Known input query unavailable on this platform.
pub const TRAP_UNAVAILABLE: u32 = 0x0000_0011;
/// Mathematical domain is invalid for the supplied finite arguments.
pub const TRAP_NUMERIC_DOMAIN: u32 = 0x0000_0012;
/// Finite input produces an unrepresentable result or integer destination.
pub const TRAP_NUMERIC_RANGE: u32 = 0x0000_0013;
/// A NaN or infinite input cannot enter guest numeric computation.
pub const TRAP_NON_FINITE: u32 = 0x0000_0014;
use serde::{Deserialize, Serialize};
/// Detailed information about a source code span.
@@ -47,4 +62,9 @@ pub struct TrapInfo {
pub pc: u32,
/// Optional source span information if debug symbols are available.
pub span: Option<SourceSpan>,
/// Machine-readable quota context; messages are not its serialization.
pub resource: Option<crate::ResourceFailure>,
}
/// All 64 unbiased bounded-random candidates were rejected.
pub const TRAP_RANDOM_REJECTION_LIMIT: u32 = 0x0000_0015;
@@ -58,7 +58,7 @@ fn parse_f64_bits(s: &str) -> Result<u64, AsmError> {
}
fn parse_keyvals(s: &str) -> Result<(&str, &str), AsmError> {
// Parses formats like: "fn=123, captures=2" or "fn=3, argc=1"
// Parses keyed u32 immediates such as "fn=123, type=2" or "type=3, method=1"
let mut parts = s.split(',');
let a = parts.next().ok_or_else(|| AsmError::MissingOperand(s.into()))?.trim();
let b = parts.next().ok_or_else(|| AsmError::MissingOperand(s.into()))?.trim();
@@ -102,6 +102,7 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
"NOP" => {
emit_u16(CoreOpCode::Nop as u16, &mut out);
}
"POP" => emit_u16(CoreOpCode::Pop as u16, &mut out),
"HALT" => {
emit_u16(CoreOpCode::Halt as u16, &mut out);
}
@@ -177,8 +178,8 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
"RET" => {
emit_u16(CoreOpCode::Ret as u16, &mut out);
}
"YIELD" => {
emit_u16(CoreOpCode::Yield as u16, &mut out);
"YIELD" | "SLEEP" | "SPAWN" => {
return Err(AsmError::InvalidOperand("retired coroutine instruction".into()))
}
"FRAME_SYNC" => {
emit_u16(CoreOpCode::FrameSync as u16, &mut out);
@@ -284,60 +285,35 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u16(CoreOpCode::Call as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"CALL_CLOSURE" => {
"CALL_CLOSURE" | "GET_CAPTURE" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (k, v) =
ops.split_once('=').ok_or_else(|| AsmError::InvalidOperand(ops.into()))?;
if k.trim() != "argc" {
return Err(AsmError::InvalidOperand(ops.into()));
}
emit_u16(CoreOpCode::CallClosure as u16, &mut out);
emit_u32(parse_u32_any(v)?, &mut out);
}
"MAKE_CLOSURE" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (a, b) = parse_keyvals(ops)?;
// Accept either order but require exact key names
let (fn_id, captures) = if a.starts_with("fn=") && b.starts_with("captures=") {
parse_pair(a, "fn", b, "captures")?
} else if a.starts_with("captures=") && b.starts_with("fn=") {
let (cap, fid) = parse_pair(a, "captures", b, "fn")?;
(fid, cap)
let opcode = if mn == "CALL_CLOSURE" {
CoreOpCode::CallClosure
} else {
return Err(AsmError::InvalidOperand(ops.into()));
CoreOpCode::GetCapture
};
emit_u16(CoreOpCode::MakeClosure as u16, &mut out);
emit_u32(fn_id, &mut out);
emit_u32(captures, &mut out);
}
"SPAWN" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (a, b) = parse_keyvals(ops)?;
let (fn_id, argc) = if a.starts_with("fn=") && b.starts_with("argc=") {
parse_pair(a, "fn", b, "argc")?
} else if a.starts_with("argc=") && b.starts_with("fn=") {
let (ac, fid) = parse_pair(a, "argc", b, "fn")?;
(fid, ac)
} else {
return Err(AsmError::InvalidOperand(ops.into()));
};
emit_u16(CoreOpCode::Spawn as u16, &mut out);
emit_u32(fn_id, &mut out);
emit_u32(argc, &mut out);
}
"SLEEP" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
emit_u16(CoreOpCode::Sleep as u16, &mut out);
emit_u16(opcode as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"MAKE_CLOSURE" | "CALL_TRAIT" => {
let (a, b) = parse_keyvals(ops)?;
let (key_a, key_b, opcode) = if mn == "MAKE_CLOSURE" {
("fn", "type", CoreOpCode::MakeClosure)
} else {
("type", "method", CoreOpCode::CallTrait)
};
let (first, second) = if a.starts_with(&format!("{}=", key_a)) {
parse_pair(a, key_a, b, key_b)?
} else {
let (second, first) = parse_pair(a, key_b, b, key_a)?;
(first, second)
};
emit_u16(opcode as u16, &mut out);
emit_u32(first, &mut out);
emit_u32(second, &mut out);
}
"HOSTCALL" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
@@ -360,6 +336,57 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u32(parse_u32_any(ops)?, &mut out);
}
"STRUCT_GET" | "STRUCT_SET" => {
let (a, b) = parse_keyvals(ops)?;
let (ty, field) = parse_pair(a, "type", b, "field")?;
let op =
if mn == "STRUCT_GET" { CoreOpCode::StructGet } else { CoreOpCode::StructSet };
emit_u16(op as u16, &mut out);
emit_u32(ty, &mut out);
emit_u32(field, &mut out);
}
"STRUCT_NEW" | "ARRAY_NEW" | "ARRAY_LEN" | "ARRAY_GET" | "ARRAY_SET" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let op = match mn {
"STRUCT_NEW" => CoreOpCode::StructNew,
"ARRAY_NEW" => CoreOpCode::ArrayNew,
"ARRAY_LEN" => CoreOpCode::ArrayLen,
"ARRAY_GET" => CoreOpCode::ArrayGet,
_ => CoreOpCode::ArraySet,
};
emit_u16(op as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"DYN_PACK" | "DYN_UNPACK" | "DYN_CAN_UNPACK" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let opcode = match mn {
"DYN_PACK" => CoreOpCode::DynPack,
"DYN_UNPACK" => CoreOpCode::DynUnpack,
_ => CoreOpCode::DynCanUnpack,
};
emit_u16(opcode as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"REF_IS_EXACT" | "REF_IMPLEMENTS" | "REF_TO_TRAIT" | "REF_CAST" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (a, b) = parse_keyvals(ops)?;
let (source, target) = parse_pair(a, "source", b, "target")?;
let opcode = match mn {
"REF_IS_EXACT" => CoreOpCode::RefIsExact,
"REF_IMPLEMENTS" => CoreOpCode::RefImplements,
"REF_TO_TRAIT" => CoreOpCode::RefToTrait,
_ => CoreOpCode::RefCast,
};
emit_u16(opcode as u16, &mut out);
emit_u32(source, &mut out);
emit_u32(target, &mut out);
}
other => return Err(AsmError::UnknownMnemonic(other.into())),
}
}
@@ -90,7 +90,7 @@ impl<'a> DecodedInstr<'a> {
/// Returns the decoded instruction with canonical `next_pc`.
#[inline]
pub fn decode_next(pc: usize, bytes: &'_ [u8]) -> Result<DecodedInstr<'_>, DecodeError> {
if pc + 2 > bytes.len() {
if pc.checked_add(2).is_none_or(|end| end > bytes.len()) {
return Err(DecodeError::TruncatedOpcode { pc });
}
@@ -100,7 +100,13 @@ pub fn decode_next(pc: usize, bytes: &'_ [u8]) -> Result<DecodedInstr<'_>, Decod
let spec: CoreOpcodeSpec = opcode.spec();
let imm_start = pc + 2;
let imm_end = imm_start + (spec.imm_bytes as usize);
let imm_end =
imm_start.checked_add(spec.imm_bytes as usize).ok_or(DecodeError::TruncatedImmediate {
pc,
opcode,
need: spec.imm_bytes as usize,
have: bytes.len().saturating_sub(imm_start),
})?;
if imm_end > bytes.len() {
return Err(DecodeError::TruncatedImmediate {
@@ -10,9 +10,9 @@
//! - `MNEMONIC <imm>` for 1-operand instructions (decimal unless stated).
//! - Special operand formats:
//! - `PUSH_F64 f64:0xhhhhhhhhhhhhhhhh` — exact IEEE-754 bits in hex (little-endian to_bits()).
//! - `MAKE_CLOSURE fn=<u32>, captures=<u32>`
//! - `SPAWN fn=<u32>, argc=<u32>`
//! - `CALL_CLOSURE argc=<u32>`
//! - `MAKE_CLOSURE fn=<u32>, type=<u32>`
//! - Retired SPAWN/YIELD/SLEEP are identified for diagnostics only.
//! - `CALL_CLOSURE <FnTypeId>`
//! - `HOSTCALL <index>` is printed in decimal because it is a `SYSC` table index.
//! - `SYSCALL` is printed as `SYSCALL 0xhhhh` (numeric id in hex) to avoid cross-crate deps.
//!
@@ -60,18 +60,44 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
| CoreOpCode::SetLocal
| CoreOpCode::Call
| CoreOpCode::Sleep
| CoreOpCode::Hostcall => {
| CoreOpCode::GetCapture
| CoreOpCode::CallClosure
| CoreOpCode::Hostcall
| CoreOpCode::DynPack
| CoreOpCode::DynUnpack
| CoreOpCode::DynCanUnpack
| CoreOpCode::StructNew
| CoreOpCode::ArrayNew
| CoreOpCode::ArrayLen
| CoreOpCode::ArrayGet
| CoreOpCode::ArraySet => {
let v = u32::from_le_bytes(imm.try_into().unwrap());
format!("{}", v)
}
CoreOpCode::StructGet | CoreOpCode::StructSet => {
let ty = u32::from_le_bytes(imm[..4].try_into().unwrap());
let field = u32::from_le_bytes(imm[4..].try_into().unwrap());
format!("type={}, field={}", ty, field)
}
CoreOpCode::RefIsExact
| CoreOpCode::RefImplements
| CoreOpCode::RefToTrait
| CoreOpCode::RefCast => {
let source = u32::from_le_bytes(imm[..4].try_into().unwrap());
let target = u32::from_le_bytes(imm[4..].try_into().unwrap());
format!("source={}, target={}", source, target)
}
CoreOpCode::MakeClosure => {
let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap());
let cap = u32::from_le_bytes(imm[4..8].try_into().unwrap());
format!("fn={}, captures={}", fn_id, cap)
format!("fn={}, type={}", fn_id, cap)
}
CoreOpCode::CallClosure => {
let argc = u32::from_le_bytes(imm.try_into().unwrap());
format!("argc={}", argc)
CoreOpCode::CallTrait => {
let (ty, method) = (
u32::from_le_bytes(imm[..4].try_into().unwrap()),
u32::from_le_bytes(imm[4..].try_into().unwrap()),
);
format!("type={}, method={}", ty, method)
}
CoreOpCode::Spawn => {
let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap());
@@ -1,8 +1,9 @@
//! Core ISA profile (bytecode-level, stable, canonical).
//!
//! This profile is the canonical opcode surface used by decoder/disasm and
//! mirrors the runtime-visible instruction set implemented today, including
//! closures, coroutines, intrinsics, and hostcall patching semantics.
//! exposes the canonical encoding for closures, coroutines, intrinsics,
//! hostcall patching and Registry instructions. Recognition by tooling alone
//! does not authorize execution without validated program metadata.
// For PR-1.4 we define the core profile as the current `OpCode` set. We re-export
// the opcode type and spec so downstream tools can import from a stable path:
@@ -1,98 +0,0 @@
//! Shared bytecode layout utilities, used by both compiler (emitter/linker)
//! and the VM (verifier/loader). This ensures a single source of truth for
//! how function ranges, instruction boundaries, and pc→function lookups are
//! interpreted post-link.
use crate::model::FunctionMeta;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FunctionLayout {
pub start: usize,
pub end: usize, // exclusive
}
/// Precompute canonical [start, end) ranges for all functions.
///
/// Contract:
/// - Ranges are computed by sorting functions by `code_offset` (stable),
/// then using the next function's start as the current end; the last
/// function ends at `code_len_total`.
/// - The returned vector is indexed by the original function indices.
pub fn compute_function_layouts(
functions: &[FunctionMeta],
code_len_total: usize,
) -> Vec<FunctionLayout> {
// Build index array and sort by start offset (stable to preserve relative order).
let mut idxs: Vec<usize> = (0..functions.len()).collect();
idxs.sort_by_key(|&i| functions[i].code_offset as usize);
// Optional guard: offsets should be strictly increasing (duplicates are suspicious).
for w in idxs.windows(2) {
if let [a, b] = *w {
let sa = functions[a].code_offset as usize;
let sb = functions[b].code_offset as usize;
debug_assert!(
sa < sb,
"Function code_offset must be strictly increasing: {} vs {} (indices {} and {})",
sa,
sb,
a,
b
);
}
}
let mut out = vec![FunctionLayout { start: 0, end: 0 }; functions.len()];
for (pos, &i) in idxs.iter().enumerate() {
let start = functions[i].code_offset as usize;
let end = if pos + 1 < idxs.len() {
functions[idxs[pos + 1]].code_offset as usize
} else {
code_len_total
};
out[i] = FunctionLayout { start, end };
}
out
}
#[cfg(test)]
mod tests {
use super::*;
fn build_funcs(offsets: &[usize], lens: Option<&[usize]>) -> Vec<FunctionMeta> {
let mut v = Vec::new();
for (i, off) in offsets.iter().copied().enumerate() {
let len_u32 = lens.and_then(|ls| ls.get(i).copied()).unwrap_or(0) as u32;
v.push(FunctionMeta {
code_offset: off as u32,
code_len: len_u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 0,
});
}
v
}
#[test]
fn compute_function_layouts_end_is_next_start() {
// Synthetic functions with known offsets: 0, 10, 25; total_len = 40
let funcs = build_funcs(&[0, 10, 25], None);
let layouts = compute_function_layouts(&funcs, 40);
assert_eq!(layouts.len(), 3);
assert_eq!(layouts[0], FunctionLayout { start: 0, end: 10 });
assert_eq!(layouts[1], FunctionLayout { start: 10, end: 25 });
assert_eq!(layouts[2], FunctionLayout { start: 25, end: 40 });
for i in 0..3 {
let l = &layouts[i];
assert_eq!(
l.end - l.start,
(funcs.get(i + 1).map(|n| n.code_offset as usize).unwrap_or(40))
- (funcs[i].code_offset as usize)
);
}
}
}
+16 -6
View File
@@ -3,22 +3,32 @@ pub mod assembler;
mod decoder;
mod disassembler;
pub mod isa; // canonical ISA boundary (core and future profiles)
mod layout;
pub mod model;
mod opcode;
mod opcode_spec;
mod program_image;
mod resource_failure;
mod value;
pub use abi::{
SourceSpan, TrapInfo, TRAP_BAD_RET_SLOTS, TRAP_DIV_ZERO, TRAP_EXPLICIT,
TRAP_ILLEGAL_INSTRUCTION, TRAP_INVALID_FUNC, TRAP_INVALID_INTRINSIC, TRAP_INVALID_LOCAL,
TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_STACK_UNDERFLOW, TRAP_TYPE,
TRAP_ILLEGAL_INSTRUCTION, TRAP_INVALID_FUNC, TRAP_INVALID_HANDLE, TRAP_INVALID_INTRINSIC,
TRAP_INVALID_LOCAL, TRAP_INVALID_SYSCALL, TRAP_NON_FINITE, TRAP_NULL_REFERENCE,
TRAP_NUMERIC_DOMAIN, TRAP_NUMERIC_RANGE, TRAP_OOB, TRAP_RANDOM_REJECTION_LIMIT,
TRAP_RESOURCE_LIMIT, TRAP_STACK_UNDERFLOW, TRAP_TYPE, TRAP_UNAVAILABLE,
};
pub use assembler::{assemble, AsmError};
pub use decoder::{decode_next, DecodeError};
pub use decoder::{decode_next, DecodeError, DecodedInstr};
pub use disassembler::disassemble;
pub use layout::{compute_function_layouts, FunctionLayout};
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl, PBX_MAGIC};
pub use model::{LoadError, SyscallDecl, PBX_MAGIC};
pub use program_image::ExecutionFunction;
pub use program_image::ProgramImage;
pub use resource_failure::{ResourceFailure, ResourceReason, RuntimeResource};
pub use value::{string_materialization_count, HeapRef, Value};
pub mod load_limits;
pub mod registry;
pub mod registry_codec;
mod registry_instruction;
pub use registry_instruction::RegistryStackEffect;
@@ -0,0 +1,402 @@
//! Shared PBX v1 resource limits and structured validation failures.
//! Counters are deterministic; a failed reservation never changes usage.
use serde::{Deserialize, Serialize};
use std::fmt;
const MIB: u64 = 1_048_576;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum LoadCode {
#[serde(rename = "LOAD_INVALID_FORMAT")]
InvalidFormat,
#[serde(rename = "LOAD_UNSUPPORTED_FORMAT")]
UnsupportedFormat,
#[serde(rename = "LOAD_INVALID_REFERENCE")]
InvalidReference,
#[serde(rename = "LOAD_INVALID_REGISTRY")]
InvalidRegistry,
#[serde(rename = "LOAD_INVALID_CODE")]
InvalidCode,
#[serde(rename = "LOAD_RESOURCE_LIMIT")]
ResourceLimit,
#[serde(rename = "LOAD_INVALID_ENTRYPOINT")]
InvalidEntrypoint,
}
impl LoadCode {
pub const fn tag(self) -> &'static str {
match self {
Self::InvalidFormat => "LOAD_INVALID_FORMAT",
Self::UnsupportedFormat => "LOAD_UNSUPPORTED_FORMAT",
Self::InvalidReference => "LOAD_INVALID_REFERENCE",
Self::InvalidRegistry => "LOAD_INVALID_REGISTRY",
Self::InvalidCode => "LOAD_INVALID_CODE",
Self::ResourceLimit => "LOAD_RESOURCE_LIMIT",
Self::InvalidEntrypoint => "LOAD_INVALID_ENTRYPOINT",
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum LoadReason {
LifecycleRole,
LifecycleSignature,
DuplicateLifecycleRole,
Magic,
Version,
Endianness,
Reserved,
SectionKind,
MissingSection,
DuplicateSection,
Overlap,
Truncated,
TrailingBytes,
InvalidFlag,
Utf8,
Category,
Builtin,
TypeId,
FunctionId,
OwnerCategory,
TraitCategory,
DuplicateBuiltin,
DuplicateArray,
DuplicateFn,
StructuralTypeCycle,
CaptureIndex,
CaptureCount,
CapturedDirectCall,
RemovedOpcode,
ArrayCycle,
DuplicateImplementation,
MethodCount,
Signature,
CodeRange,
FrameSlots,
ReturnSlots,
Overflow,
Limit,
Allocation,
ConstantTag,
NonFiniteValue,
DebugRange,
DuplicateSyscall,
UnknownOpcode,
LocalSlot,
JumpTarget,
InstructionBoundary,
BooleanImmediate,
ConstantIndex,
NativeId,
UnpatchedHostcall,
StackUnderflow,
StackOverflow,
StackJoin,
ReturnHeight,
UnterminatedPath,
UnknownClosureCallee,
NotClosure,
InvalidYield,
TypeMismatch,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[repr(usize)]
pub enum LoadResource {
PbxBytes,
CodeBytes,
Types,
Functions,
Implementations,
NestedRecords,
NameBytes,
RegistryBytes,
TemporaryBytes,
Work,
ConstantEntries,
ConstantStringBytes,
}
const RESOURCE_COUNT: usize = 12;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum IdDomain {
Type,
Function,
Implementation,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct LoadFailure {
pub code: LoadCode,
pub reason: LoadReason,
pub section: Option<u32>,
pub offset: Option<usize>,
pub record: Option<u32>,
pub member: Option<u32>,
pub id_domain: Option<IdDomain>,
pub referenced_id: Option<u32>,
pub function: Option<u32>,
pub pc: Option<u32>,
pub resource: Option<LoadResource>,
pub requested: Option<u64>,
pub limit: Option<u64>,
}
impl LoadFailure {
pub fn new(code: LoadCode, reason: LoadReason) -> Self {
Self {
code,
reason,
section: None,
offset: None,
record: None,
member: None,
id_domain: None,
referenced_id: None,
function: None,
pc: None,
resource: None,
requested: None,
limit: None,
}
}
pub fn at(mut self, section: u32, offset: usize) -> Self {
self.section = Some(section);
self.offset = Some(offset);
self
}
pub fn record(mut self, record: u32) -> Self {
self.record = Some(record);
self
}
pub fn member(mut self, member: u32) -> Self {
self.member = Some(member);
self
}
pub fn in_section(mut self, section: u32) -> Self {
self.section = Some(section);
self
}
pub fn reference(mut self, domain: IdDomain, id: u32) -> Self {
self.id_domain = Some(domain);
self.referenced_id = Some(id);
self
}
pub fn in_function(mut self, function: u32, pc: Option<u32>) -> Self {
self.function = Some(function);
self.pc = pc;
self
}
pub fn resource(resource: LoadResource, requested: u64, limit: u64) -> Self {
Self {
resource: Some(resource),
requested: Some(requested),
limit: Some(limit),
..Self::new(LoadCode::ResourceLimit, LoadReason::Limit)
}
}
}
impl fmt::Display for LoadFailure {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{}: {:?}", self.code.tag(), self.reason)?;
if let Some(section) = self.section {
write!(f, " in section {section}")?;
}
if let Some(offset) = self.offset {
write!(f, " at byte {offset}")?;
}
if let Some(record) = self.record {
write!(f, " (record {record})")?;
}
if let Some(resource) = self.resource {
write!(f, " ({resource:?}: {:?} / {:?})", self.requested, self.limit)?;
}
Ok(())
}
}
impl std::error::Error for LoadFailure {}
/// Product maxima; callers may lower limits but cannot raise the accepted ceilings.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct LoadLimits {
pub pbx_bytes: u64,
pub code_bytes: u64,
pub types: u64,
pub functions: u64,
pub implementations: u64,
pub nested_records: u64,
pub name_bytes: u64,
pub individual_name_bytes: u64,
pub registry_bytes: u64,
pub temporary_bytes: u64,
pub work: u64,
pub frame_slots: u64,
pub result_slots: u64,
pub constant_entries: u64,
pub constant_string_bytes: u64,
pub individual_string_bytes: u64,
}
impl Default for LoadLimits {
fn default() -> Self {
Self {
pbx_bytes: 64 * MIB,
code_bytes: 32 * MIB,
types: 65_536,
functions: 65_536,
implementations: 262_144,
nested_records: 1_048_576,
name_bytes: 4 * MIB,
individual_name_bytes: 4096,
registry_bytes: 64 * MIB,
temporary_bytes: 128 * MIB,
work: 268_435_456,
frame_slots: 16_384,
result_slots: 1024,
constant_entries: 1_048_576,
constant_string_bytes: 64 * MIB,
individual_string_bytes: 4 * MIB,
}
}
}
impl LoadLimits {
fn ceiling(self, r: LoadResource) -> u64 {
match r {
LoadResource::PbxBytes => self.pbx_bytes,
LoadResource::CodeBytes => self.code_bytes,
LoadResource::Types => self.types,
LoadResource::Functions => self.functions,
LoadResource::Implementations => self.implementations,
LoadResource::NestedRecords => self.nested_records,
LoadResource::NameBytes => self.name_bytes,
LoadResource::RegistryBytes => self.registry_bytes,
LoadResource::TemporaryBytes => self.temporary_bytes,
LoadResource::Work => self.work,
LoadResource::ConstantEntries => self.constant_entries,
LoadResource::ConstantStringBytes => self.constant_string_bytes,
}
}
}
/// One load attempt's counters. Successful retained allocations stay charged
/// for the remainder of this attempt; executable-image lifetime accounting is
/// a separate owner. Reuse a budget only when its earlier allocations still live.
#[derive(Debug)]
pub struct LoadBudget {
limits: LoadLimits,
used: [u64; RESOURCE_COUNT],
peak: [u64; RESOURCE_COUNT],
}
impl LoadBudget {
pub fn new(limits: LoadLimits) -> Self {
Self { limits, used: [0; RESOURCE_COUNT], peak: [0; RESOURCE_COUNT] }
}
pub fn limit(&self, r: LoadResource) -> u64 {
self.limits.ceiling(r).min(LoadLimits::default().ceiling(r))
}
pub fn individual_string_limit(&self) -> u64 {
self.limits.individual_string_bytes.min(4 * MIB)
}
pub fn individual_name_limit(&self) -> u64 {
self.limits.individual_name_bytes.min(4096)
}
pub fn frame_limit(&self) -> u64 {
self.limits.frame_slots.min(16_384)
}
pub fn result_limit(&self) -> u64 {
self.limits.result_slots.min(1024)
}
pub fn used(&self, r: LoadResource) -> u64 {
self.used[r as usize]
}
/// Highest admitted reservation total during this budget's lifetime.
/// Refunds and failed load transactions retain this measurement; refused
/// charges do not increase it. This is accounted capacity, not process RSS.
pub fn peak_usage(&self, r: LoadResource) -> u64 {
self.peak[r as usize]
}
pub fn charge(&mut self, r: LoadResource, amount: u64) -> Result<(), LoadFailure> {
let next = self
.used(r)
.checked_add(amount)
.ok_or_else(|| LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Overflow))?;
self.check(r, next)?;
self.used[r as usize] = next;
self.peak[r as usize] = self.peak[r as usize].max(next);
Ok(())
}
pub fn check(&self, r: LoadResource, amount: u64) -> Result<(), LoadFailure> {
if amount > self.limit(r) {
Err(LoadFailure::resource(r, amount, self.limit(r)))
} else {
Ok(())
}
}
pub fn refund(&mut self, r: LoadResource, amount: u64) {
self.used[r as usize] = self.used[r as usize]
.checked_sub(amount)
.expect("internal load budget accounting imbalance");
}
pub fn work(&mut self, amount: usize) -> Result<(), LoadFailure> {
self.charge(LoadResource::Work, amount as u64)
}
pub(crate) fn vector<T>(
&mut self,
count: usize,
r: LoadResource,
) -> Result<Vec<T>, LoadFailure> {
let bytes = count
.checked_mul(std::mem::size_of::<T>())
.ok_or_else(|| LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Overflow))?
as u64;
self.charge(r, bytes)?;
let mut result = Vec::new();
if result.try_reserve_exact(count).is_err() {
self.refund(r, bytes);
return Err(LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Allocation));
}
let actual = (result.capacity() as u64)
.checked_mul(std::mem::size_of::<T>() as u64)
.ok_or_else(|| LoadFailure::new(LoadCode::ResourceLimit, LoadReason::Overflow))?;
if let Err(err) = self.charge(r, actual - bytes) {
self.refund(r, bytes);
return Err(err);
}
Ok(result)
}
/// Roll back retained counters on failure; attempted work remains charged.
pub(crate) fn transaction<T>(
&mut self,
f: impl FnOnce(&mut Self) -> Result<T, LoadFailure>,
) -> Result<T, LoadFailure> {
let before = self.used;
let result = f(self);
if result.is_err() {
let work = self.used(LoadResource::Work);
self.used = before;
self.used[LoadResource::Work as usize] = work;
}
result
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn peak_tracks_admitted_capacity_through_refunds_and_failed_transactions() {
let mut budget = LoadBudget::new(LoadLimits { temporary_bytes: 10, ..Default::default() });
budget.charge(LoadResource::TemporaryBytes, 3).unwrap();
let result: Result<(), LoadFailure> = budget.transaction(|budget| {
budget.charge(LoadResource::TemporaryBytes, 7)?;
budget.work(2)?;
budget.charge(LoadResource::TemporaryBytes, 1)
});
assert!(result.is_err());
assert_eq!(budget.used(LoadResource::TemporaryBytes), 3);
assert_eq!(budget.peak_usage(LoadResource::TemporaryBytes), 10);
assert_eq!(budget.used(LoadResource::Work), 2);
assert_eq!(budget.peak_usage(LoadResource::Work), 2);
budget.refund(LoadResource::TemporaryBytes, 3);
assert_eq!(budget.used(LoadResource::TemporaryBytes), 0);
assert_eq!(budget.peak_usage(LoadResource::TemporaryBytes), 10);
assert!(budget.charge(LoadResource::TemporaryBytes, u64::MAX).is_err());
assert_eq!(budget.peak_usage(LoadResource::TemporaryBytes), 10);
}
}
@@ -1,7 +1,5 @@
use crate::abi::SourceSpan;
use crate::opcode::OpCode;
use serde::{Deserialize, Serialize};
use std::collections::HashSet;
/// An entry in the Constant Pool.
///
@@ -42,16 +40,6 @@ pub enum LoadError {
UnexpectedEof,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct FunctionMeta {
pub code_offset: u32,
pub code_len: u32,
pub param_slots: u16,
pub local_slots: u16,
pub return_slots: u16,
pub max_stack_slots: u16,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct DebugInfo {
pub pc_to_span: Vec<(u32, SourceSpan)>, // Sorted by PC
@@ -73,876 +61,4 @@ pub struct SyscallDecl {
pub ret_slots: u16,
}
const SECTION_KIND_CONST_POOL: u32 = 0;
const SECTION_KIND_FUNCTIONS: u32 = 1;
const SECTION_KIND_CODE: u32 = 2;
const SECTION_KIND_DEBUG: u32 = 3;
const SECTION_KIND_EXPORTS: u32 = 4;
const SECTION_KIND_SYSCALLS: u32 = 5;
pub const PBX_MAGIC: [u8; 4] = *b"PBX\0";
/// Represents the final serialized format of a PBX v0 module.
///
/// This structure is a pure data container for the PBX format. It does NOT
/// contain any linker-like logic (symbol resolution, patching, etc.).
/// All multi-module programs must be flattened and linked by the compiler
/// before being serialized into this format.
#[derive(Debug, Clone, PartialEq)]
pub struct BytecodeModule {
pub version: u16,
pub const_pool: Vec<ConstantPoolEntry>,
pub functions: Vec<FunctionMeta>,
pub code: Vec<u8>,
pub debug_info: Option<DebugInfo>,
pub exports: Vec<Export>,
pub syscalls: Vec<SyscallDecl>,
}
impl BytecodeModule {
pub fn serialize(&self) -> Vec<u8> {
let cp_data = self.serialize_const_pool();
let func_data = self.serialize_functions();
let code_data = self.code.clone();
let debug_data =
self.debug_info.as_ref().map(|di| self.serialize_debug(di)).unwrap_or_default();
let export_data = self.serialize_exports();
let syscall_data = self.serialize_syscalls();
let mut final_sections = Vec::new();
if !cp_data.is_empty() {
final_sections.push((SECTION_KIND_CONST_POOL, cp_data));
}
if !func_data.is_empty() {
final_sections.push((SECTION_KIND_FUNCTIONS, func_data));
}
if !code_data.is_empty() {
final_sections.push((SECTION_KIND_CODE, code_data));
}
if !debug_data.is_empty() {
final_sections.push((SECTION_KIND_DEBUG, debug_data));
}
if !export_data.is_empty() {
final_sections.push((SECTION_KIND_EXPORTS, export_data));
}
final_sections.push((SECTION_KIND_SYSCALLS, syscall_data));
let mut out = Vec::new();
// Magic "PBX\0"
out.extend_from_slice(&PBX_MAGIC);
// Version 0
out.extend_from_slice(&0u16.to_le_bytes());
// Endianness 0 (Little Endian), Reserved
out.extend_from_slice(&[0u8, 0u8]);
// section_count
out.extend_from_slice(&(final_sections.len() as u32).to_le_bytes());
// padding to 32 bytes
out.extend_from_slice(&[0u8; 20]);
let mut current_offset = 32 + (final_sections.len() as u32 * 12);
// Write section table
for (kind, data) in &final_sections {
let k: u32 = *kind;
out.extend_from_slice(&k.to_le_bytes());
out.extend_from_slice(&current_offset.to_le_bytes());
out.extend_from_slice(&(data.len() as u32).to_le_bytes());
current_offset += data.len() as u32;
}
// Write section data
for (_, data) in final_sections {
out.extend_from_slice(&data);
}
out
}
fn serialize_const_pool(&self) -> Vec<u8> {
if self.const_pool.is_empty() {
return Vec::new();
}
let mut data = Vec::new();
data.extend_from_slice(&(self.const_pool.len() as u32).to_le_bytes());
for entry in &self.const_pool {
match entry {
ConstantPoolEntry::Null => data.push(0),
ConstantPoolEntry::Int64(v) => {
data.push(1);
data.extend_from_slice(&v.to_le_bytes());
}
ConstantPoolEntry::Float64(v) => {
data.push(2);
data.extend_from_slice(&v.to_le_bytes());
}
ConstantPoolEntry::Boolean(v) => {
data.push(3);
data.push(if *v { 1 } else { 0 });
}
ConstantPoolEntry::String(v) => {
data.push(4);
let s_bytes = v.as_bytes();
data.extend_from_slice(&(s_bytes.len() as u32).to_le_bytes());
data.extend_from_slice(s_bytes);
}
ConstantPoolEntry::Int32(v) => {
data.push(5);
data.extend_from_slice(&v.to_le_bytes());
}
}
}
data
}
fn serialize_functions(&self) -> Vec<u8> {
if self.functions.is_empty() {
return Vec::new();
}
let mut data = Vec::new();
data.extend_from_slice(&(self.functions.len() as u32).to_le_bytes());
for f in &self.functions {
data.extend_from_slice(&f.code_offset.to_le_bytes());
data.extend_from_slice(&f.code_len.to_le_bytes());
data.extend_from_slice(&f.param_slots.to_le_bytes());
data.extend_from_slice(&f.local_slots.to_le_bytes());
data.extend_from_slice(&f.return_slots.to_le_bytes());
data.extend_from_slice(&f.max_stack_slots.to_le_bytes());
}
data
}
fn serialize_debug(&self, di: &DebugInfo) -> Vec<u8> {
let mut data = Vec::new();
data.extend_from_slice(&(di.pc_to_span.len() as u32).to_le_bytes());
for (pc, span) in &di.pc_to_span {
data.extend_from_slice(&pc.to_le_bytes());
data.extend_from_slice(&span.file_id.to_le_bytes());
data.extend_from_slice(&span.start.to_le_bytes());
data.extend_from_slice(&span.end.to_le_bytes());
}
data.extend_from_slice(&(di.function_names.len() as u32).to_le_bytes());
for (idx, name) in &di.function_names {
data.extend_from_slice(&idx.to_le_bytes());
let n_bytes = name.as_bytes();
data.extend_from_slice(&(n_bytes.len() as u32).to_le_bytes());
data.extend_from_slice(n_bytes);
}
data
}
fn serialize_exports(&self) -> Vec<u8> {
if self.exports.is_empty() {
return Vec::new();
}
let mut data = Vec::new();
data.extend_from_slice(&(self.exports.len() as u32).to_le_bytes());
for exp in &self.exports {
data.extend_from_slice(&exp.func_idx.to_le_bytes());
let s_bytes = exp.symbol.as_bytes();
data.extend_from_slice(&(s_bytes.len() as u32).to_le_bytes());
data.extend_from_slice(s_bytes);
}
data
}
fn serialize_syscalls(&self) -> Vec<u8> {
let mut data = Vec::new();
data.extend_from_slice(&(self.syscalls.len() as u32).to_le_bytes());
for syscall in &self.syscalls {
let module = syscall.module.as_bytes();
let name = syscall.name.as_bytes();
assert!(u16::try_from(module.len()).is_ok(), "SYSC module name exceeds u16 length");
assert!(u16::try_from(name.len()).is_ok(), "SYSC syscall name exceeds u16 length");
data.extend_from_slice(&(module.len() as u16).to_le_bytes());
data.extend_from_slice(module);
data.extend_from_slice(&(name.len() as u16).to_le_bytes());
data.extend_from_slice(name);
data.extend_from_slice(&syscall.version.to_le_bytes());
data.extend_from_slice(&syscall.arg_slots.to_le_bytes());
data.extend_from_slice(&syscall.ret_slots.to_le_bytes());
}
data
}
}
pub struct BytecodeLoader;
impl BytecodeLoader {
pub fn load(bytes: &[u8]) -> Result<BytecodeModule, LoadError> {
if bytes.len() < 32 {
return Err(LoadError::UnexpectedEof);
}
// Magic "PBX\0"
if bytes[0..4] != PBX_MAGIC[..] {
return Err(LoadError::InvalidMagic);
}
let version = u16::from_le_bytes([bytes[4], bytes[5]]);
if version != 0 {
return Err(LoadError::InvalidVersion);
}
let endianness = bytes[6];
if endianness != 0 {
// 0 = Little Endian
return Err(LoadError::InvalidEndianness);
}
let section_count = u32::from_le_bytes([bytes[8], bytes[9], bytes[10], bytes[11]]);
let mut sections = Vec::new();
let mut pos = 32;
for _ in 0..section_count {
if pos + 12 > bytes.len() {
return Err(LoadError::UnexpectedEof);
}
let kind =
u32::from_le_bytes([bytes[pos], bytes[pos + 1], bytes[pos + 2], bytes[pos + 3]]);
let offset = u32::from_le_bytes([
bytes[pos + 4],
bytes[pos + 5],
bytes[pos + 6],
bytes[pos + 7],
]);
let length = u32::from_le_bytes([
bytes[pos + 8],
bytes[pos + 9],
bytes[pos + 10],
bytes[pos + 11],
]);
// Basic bounds check
if (offset as usize) + (length as usize) > bytes.len() {
return Err(LoadError::SectionOutOfBounds);
}
sections.push((kind, offset, length));
pos += 12;
}
// Check for overlapping sections
for i in 0..sections.len() {
for j in i + 1..sections.len() {
let (_, o1, l1) = sections[i];
let (_, o2, l2) = sections[j];
if (o1 < o2 + l2) && (o2 < o1 + l1) {
return Err(LoadError::OverlappingSections);
}
}
}
let mut module = BytecodeModule {
version,
const_pool: Vec::new(),
functions: Vec::new(),
code: Vec::new(),
debug_info: None,
exports: Vec::new(),
syscalls: Vec::new(),
};
let mut has_syscalls = false;
for (kind, offset, length) in sections {
let section_data = &bytes[offset as usize..(offset + length) as usize];
match kind {
SECTION_KIND_CONST_POOL => {
// Const Pool
module.const_pool = parse_const_pool(section_data)?;
}
SECTION_KIND_FUNCTIONS => {
// Functions
module.functions = parse_functions(section_data)?;
}
SECTION_KIND_CODE => {
// Code
module.code = section_data.to_vec();
}
SECTION_KIND_DEBUG => {
// Debug Info
module.debug_info = Some(parse_debug_section(section_data)?);
}
SECTION_KIND_EXPORTS => {
// Exports
module.exports = parse_exports(section_data)?;
}
SECTION_KIND_SYSCALLS => {
module.syscalls = parse_syscalls(section_data)?;
has_syscalls = true;
}
_ => {} // Skip unknown or optional sections
}
}
if !has_syscalls {
return Err(LoadError::MissingSyscallSection);
}
// Additional validations
validate_module(&module)?;
Ok(module)
}
}
fn parse_const_pool(data: &[u8]) -> Result<Vec<ConstantPoolEntry>, LoadError> {
if data.is_empty() {
return Ok(Vec::new());
}
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut cp = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos >= data.len() {
return Err(LoadError::UnexpectedEof);
}
let tag = data[pos];
pos += 1;
match tag {
0 => cp.push(ConstantPoolEntry::Null),
1 => {
// Int64
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let val = i64::from_le_bytes(data[pos..pos + 8].try_into().unwrap());
cp.push(ConstantPoolEntry::Int64(val));
pos += 8;
}
2 => {
// Float64
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let val = f64::from_le_bytes(data[pos..pos + 8].try_into().unwrap());
cp.push(ConstantPoolEntry::Float64(val));
pos += 8;
}
3 => {
// Boolean
if pos >= data.len() {
return Err(LoadError::UnexpectedEof);
}
cp.push(ConstantPoolEntry::Boolean(data[pos] != 0));
pos += 1;
}
4 => {
// String
if pos + 4 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let len = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap()) as usize;
pos += 4;
if pos + len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let s = String::from_utf8_lossy(&data[pos..pos + len]).into_owned();
cp.push(ConstantPoolEntry::String(s));
pos += len;
}
5 => {
// Int32
if pos + 4 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let val = i32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
cp.push(ConstantPoolEntry::Int32(val));
pos += 4;
}
_ => return Err(LoadError::MalformedSection),
}
}
Ok(cp)
}
fn parse_functions(data: &[u8]) -> Result<Vec<FunctionMeta>, LoadError> {
if data.is_empty() {
return Ok(Vec::new());
}
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut functions = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos + 16 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let code_offset = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let code_len = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap());
let param_slots = u16::from_le_bytes(data[pos + 8..pos + 10].try_into().unwrap());
let local_slots = u16::from_le_bytes(data[pos + 10..pos + 12].try_into().unwrap());
let return_slots = u16::from_le_bytes(data[pos + 12..pos + 14].try_into().unwrap());
let max_stack_slots = u16::from_le_bytes(data[pos + 14..pos + 16].try_into().unwrap());
functions.push(FunctionMeta {
code_offset,
code_len,
param_slots,
local_slots,
return_slots,
max_stack_slots,
});
pos += 16;
}
Ok(functions)
}
fn parse_debug_section(data: &[u8]) -> Result<DebugInfo, LoadError> {
if data.is_empty() {
return Ok(DebugInfo::default());
}
if data.len() < 8 {
return Err(LoadError::MalformedSection);
}
let mut pos = 0;
// PC to Span table
let span_count = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap()) as usize;
pos += 4;
let mut pc_to_span = Vec::with_capacity(span_count);
for _ in 0..span_count {
if pos + 16 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let pc = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let file_id = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap());
let start = u32::from_le_bytes(data[pos + 8..pos + 12].try_into().unwrap());
let end = u32::from_le_bytes(data[pos + 12..pos + 16].try_into().unwrap());
pc_to_span.push((pc, SourceSpan { file_id, start, end }));
pos += 16;
}
// Function names table
if pos + 4 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let func_name_count = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap()) as usize;
pos += 4;
let mut function_names = Vec::with_capacity(func_name_count);
for _ in 0..func_name_count {
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let func_idx = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let name_len = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap()) as usize;
pos += 8;
if pos + name_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let name = String::from_utf8_lossy(&data[pos..pos + name_len]).into_owned();
function_names.push((func_idx, name));
pos += name_len;
}
Ok(DebugInfo { pc_to_span, function_names })
}
fn parse_exports(data: &[u8]) -> Result<Vec<Export>, LoadError> {
if data.is_empty() {
return Ok(Vec::new());
}
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut exports = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let func_idx = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let name_len = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap()) as usize;
pos += 8;
if pos + name_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let symbol = String::from_utf8_lossy(&data[pos..pos + name_len]).into_owned();
exports.push(Export { symbol, func_idx });
pos += name_len;
}
Ok(exports)
}
fn parse_syscalls(data: &[u8]) -> Result<Vec<SyscallDecl>, LoadError> {
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut syscalls = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos + 2 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let module_len = u16::from_le_bytes(data[pos..pos + 2].try_into().unwrap()) as usize;
pos += 2;
if pos + module_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let module = std::str::from_utf8(&data[pos..pos + module_len])
.map_err(|_| LoadError::InvalidUtf8)?;
pos += module_len;
if pos + 2 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let name_len = u16::from_le_bytes(data[pos..pos + 2].try_into().unwrap()) as usize;
pos += 2;
if pos + name_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let name =
std::str::from_utf8(&data[pos..pos + name_len]).map_err(|_| LoadError::InvalidUtf8)?;
pos += name_len;
if pos + 6 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let version = u16::from_le_bytes(data[pos..pos + 2].try_into().unwrap());
let arg_slots = u16::from_le_bytes(data[pos + 2..pos + 4].try_into().unwrap());
let ret_slots = u16::from_le_bytes(data[pos + 4..pos + 6].try_into().unwrap());
pos += 6;
syscalls.push(SyscallDecl {
module: module.to_owned(),
name: name.to_owned(),
version,
arg_slots,
ret_slots,
});
}
if pos != data.len() {
return Err(LoadError::MalformedSection);
}
Ok(syscalls)
}
fn validate_module(module: &BytecodeModule) -> Result<(), LoadError> {
let mut syscall_identities = HashSet::with_capacity(module.syscalls.len());
for syscall in &module.syscalls {
if !syscall_identities.insert((
syscall.module.clone(),
syscall.name.clone(),
syscall.version,
)) {
return Err(LoadError::DuplicateSyscallIdentity);
}
}
for func in &module.functions {
// Opcode stream bounds
if (func.code_offset as usize) + (func.code_len as usize) > module.code.len() {
return Err(LoadError::InvalidFunctionIndex);
}
}
// Basic opcode scan for const pool indices
let mut pos = 0;
while pos < module.code.len() {
if pos + 2 > module.code.len() {
break; // Unexpected EOF in middle of opcode, maybe should be error
}
let op_val = u16::from_le_bytes([module.code[pos], module.code[pos + 1]]);
let opcode = OpCode::try_from(op_val).map_err(|_| LoadError::InvalidOpcode)?;
pos += 2;
match opcode {
OpCode::PushConst => {
if pos + 4 > module.code.len() {
return Err(LoadError::UnexpectedEof);
}
let idx =
u32::from_le_bytes(module.code[pos..pos + 4].try_into().unwrap()) as usize;
if idx >= module.const_pool.len() {
return Err(LoadError::InvalidConstIndex);
}
pos += 4;
}
OpCode::PushI32
| OpCode::Jmp
| OpCode::JmpIfFalse
| OpCode::JmpIfTrue
| OpCode::GetGlobal
| OpCode::SetGlobal
| OpCode::GetLocal
| OpCode::SetLocal
| OpCode::PopN
| OpCode::Hostcall
| OpCode::Syscall
| OpCode::Intrinsic => {
pos += 4;
}
OpCode::PushI64 | OpCode::PushF64 => {
pos += 8;
}
OpCode::PushBool => {
pos += 1;
}
OpCode::Call => {
pos += 4;
}
_ => {}
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
fn create_header(section_count: u32) -> Vec<u8> {
let mut h = vec![0u8; 32];
h[0..4].copy_from_slice(&PBX_MAGIC);
h[4..6].copy_from_slice(&0u16.to_le_bytes()); // version
h[6] = 0; // endianness
h[8..12].copy_from_slice(&section_count.to_le_bytes());
h
}
fn minimal_module() -> BytecodeModule {
BytecodeModule {
version: 0,
const_pool: vec![],
functions: vec![],
code: vec![],
debug_info: None,
exports: vec![],
syscalls: vec![],
}
}
fn build_pbx_with_sections(sections: Vec<(u32, Vec<u8>)>) -> Vec<u8> {
let mut data = create_header(sections.len() as u32);
let mut offset = 32 + (sections.len() as u32 * 12);
for (kind, section_data) in &sections {
data.extend_from_slice(&kind.to_le_bytes());
data.extend_from_slice(&offset.to_le_bytes());
data.extend_from_slice(&(section_data.len() as u32).to_le_bytes());
offset += section_data.len() as u32;
}
for (_, section_data) in sections {
data.extend_from_slice(&section_data);
}
data
}
#[test]
fn test_invalid_magic() {
let mut data = create_header(0);
data[0..4].copy_from_slice(b"PBS\0");
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidMagic));
}
#[test]
fn test_invalid_version() {
let mut data = create_header(0);
data[4] = 1;
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidVersion));
}
#[test]
fn test_invalid_endianness() {
let mut data = create_header(0);
data[6] = 1;
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidEndianness));
}
#[test]
fn test_overlapping_sections() {
let mut data = create_header(2);
// Section 1: Kind 0, Offset 64, Length 32
data.extend_from_slice(&0u32.to_le_bytes());
data.extend_from_slice(&64u32.to_le_bytes());
data.extend_from_slice(&32u32.to_le_bytes());
// Section 2: Kind 1, Offset 80, Length 32 (Overlaps with Section 1)
data.extend_from_slice(&1u32.to_le_bytes());
data.extend_from_slice(&80u32.to_le_bytes());
data.extend_from_slice(&32u32.to_le_bytes());
// Ensure data is long enough for the offsets
data.resize(256, 0);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::OverlappingSections));
}
#[test]
fn test_section_out_of_bounds() {
let mut data = create_header(1);
// Section 1: Kind 0, Offset 64, Length 1000
data.extend_from_slice(&0u32.to_le_bytes());
data.extend_from_slice(&64u32.to_le_bytes());
data.extend_from_slice(&1000u32.to_le_bytes());
data.resize(256, 0);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::SectionOutOfBounds));
}
#[test]
fn test_invalid_function_code_offset() {
let mut data = create_header(3);
// Section 1: Functions, Kind 1, Offset 80, Length 20 (Header 4 + 1 entry 16)
data.extend_from_slice(&1u32.to_le_bytes());
data.extend_from_slice(&80u32.to_le_bytes());
data.extend_from_slice(&20u32.to_le_bytes());
// Section 2: Code, Kind 2, Offset 128, Length 10
data.extend_from_slice(&2u32.to_le_bytes());
data.extend_from_slice(&128u32.to_le_bytes());
data.extend_from_slice(&10u32.to_le_bytes());
// Section 3: SYSC, Kind 5, Offset 160, Length 4 (empty)
data.extend_from_slice(&5u32.to_le_bytes());
data.extend_from_slice(&160u32.to_le_bytes());
data.extend_from_slice(&4u32.to_le_bytes());
data.resize(256, 0);
// Setup functions section
let func_data_start = 80;
data[func_data_start..func_data_start + 4].copy_from_slice(&1u32.to_le_bytes()); // 1 function
let entry_start = func_data_start + 4;
data[entry_start..entry_start + 4].copy_from_slice(&5u32.to_le_bytes()); // code_offset = 5
data[entry_start + 4..entry_start + 8].copy_from_slice(&10u32.to_le_bytes()); // code_len = 10
// 5 + 10 = 15 > 10 (code section length)
data[160..164].copy_from_slice(&0u32.to_le_bytes());
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidFunctionIndex));
}
#[test]
fn test_invalid_const_index() {
let mut data = create_header(3);
// Section 1: Const Pool, Kind 0, Offset 80, Length 4 (Empty CP)
data.extend_from_slice(&0u32.to_le_bytes());
data.extend_from_slice(&80u32.to_le_bytes());
data.extend_from_slice(&4u32.to_le_bytes());
// Section 2: Code, Kind 2, Offset 128, Length 6 (PushConst 0)
data.extend_from_slice(&2u32.to_le_bytes());
data.extend_from_slice(&128u32.to_le_bytes());
data.extend_from_slice(&6u32.to_le_bytes());
// Section 3: SYSC, Kind 5, Offset 160, Length 4 (empty)
data.extend_from_slice(&5u32.to_le_bytes());
data.extend_from_slice(&160u32.to_le_bytes());
data.extend_from_slice(&4u32.to_le_bytes());
data.resize(256, 0);
// Setup empty CP
data[80..84].copy_from_slice(&0u32.to_le_bytes());
// Setup code with PushConst 0
data[128..130].copy_from_slice(&(OpCode::PushConst as u16).to_le_bytes());
data[130..134].copy_from_slice(&0u32.to_le_bytes());
data[160..164].copy_from_slice(&0u32.to_le_bytes());
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidConstIndex));
}
#[test]
fn test_missing_sysc_section_is_rejected() {
let data = create_header(0);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MissingSyscallSection));
}
#[test]
fn test_valid_minimal_load_with_empty_sysc() {
let data = minimal_module().serialize();
let module = BytecodeLoader::load(&data).unwrap();
assert_eq!(module.version, 0);
assert!(module.const_pool.is_empty());
assert!(module.functions.is_empty());
assert!(module.code.is_empty());
assert!(module.syscalls.is_empty());
}
#[test]
fn test_valid_sysc_roundtrip() {
let mut module = minimal_module();
module.syscalls = vec![SyscallDecl {
module: "gfx2d".into(),
name: "draw_line".into(),
version: 1,
arg_slots: 4,
ret_slots: 0,
}];
let data = module.serialize();
let loaded = BytecodeLoader::load(&data).unwrap();
assert_eq!(loaded.syscalls, module.syscalls);
}
#[test]
fn test_malformed_sysc_section_is_rejected() {
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, vec![1, 0, 0])]);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MalformedSection));
}
#[test]
fn test_invalid_utf8_in_sysc_section_is_rejected() {
let mut sysc = Vec::new();
sysc.extend_from_slice(&1u32.to_le_bytes());
sysc.extend_from_slice(&1u16.to_le_bytes());
sysc.push(0xFF);
sysc.extend_from_slice(&1u16.to_le_bytes());
sysc.push(b'x');
sysc.extend_from_slice(&1u16.to_le_bytes());
sysc.extend_from_slice(&0u16.to_le_bytes());
sysc.extend_from_slice(&0u16.to_le_bytes());
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, sysc)]);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidUtf8));
}
#[test]
fn test_duplicate_sysc_identity_is_rejected() {
let mut module = minimal_module();
module.syscalls = vec![
SyscallDecl {
module: "system".into(),
name: "has_cart".into(),
version: 1,
arg_slots: 0,
ret_slots: 1,
},
SyscallDecl {
module: "system".into(),
name: "has_cart".into(),
version: 1,
arg_slots: 0,
ret_slots: 1,
},
];
let data = module.serialize();
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::DuplicateSyscallIdentity));
}
}
+70 -38
View File
@@ -143,46 +143,20 @@ pub enum OpCode {
/// Returns from the current function.
/// Stack: [return_val] -> [return_val]
Ret = 0x51,
/// Creates a closure capturing values from the operand stack (Model B).
/// Operands: fn_id (u32), capture_count (u32)
/// Stack before: [..., captured_N, ..., captured_1]
/// Pops capture_count values (top-first), preserves order as [captured_1..captured_N]
/// and stores them inside the closure environment. Pushes a HeapRef to the closure.
/// Create a typed instance: FunctionId, FnTypeId. Captures come from metadata.
MakeClosure = 0x52,
/// Calls a closure value with hidden arg0 semantics (Model B).
/// Operand: arg_count (u32) — number of user-supplied args (excludes hidden arg0)
/// Stack before: [..., argN, ..., arg1, closure_ref]
/// Behavior:
/// - Pops `closure_ref` and validates it is a Closure.
/// - Pops `arg_count` user args.
/// - Fetches `fn_id` from the closure and creates a new call frame.
/// - Injects hidden arg0 = closure_ref, followed by user args as arg1..argN.
/// Invoke with expected FnTypeId; environment belongs to CallFrame, not arg0.
CallClosure = 0x53,
// --- 7.x Concurrency / Coroutines ---
/// Spawns a new coroutine to run a function with arguments.
/// Operands: fn_id (u32), arg_count (u32)
/// Semantics:
/// - Pops `arg_count` arguments from the current operand stack (top-first),
/// preserving user order as arg1..argN for the callee.
/// - Allocates a new Coroutine object with its own stack and a single entry frame
/// pointing at `fn_id`.
/// - Enqueues the coroutine into the scheduler ready queue.
/// - Does NOT switch execution immediately; current coroutine continues.
/// Retired opcode, recognized only for load rejection and diagnostics.
Spawn = 0x54,
/// Cooperatively yields the current coroutine. Execution continues
/// until the next VM safepoint (FRAME_SYNC), where the scheduler
/// may switch to another ready coroutine.
/// Retired opcode, recognized only for load rejection and diagnostics.
Yield = 0x55,
/// Suspends the current coroutine for a number of logical ticks.
/// Operand: duration_ticks (u32)
/// Semantics:
/// - Set the coroutine wake tick to `current_tick + duration_ticks`.
/// - End the current logical frame (as if reaching FRAME_SYNC).
/// - The coroutine will resume execution on or after the wake tick.
/// Retired opcode, recognized only for load rejection and diagnostics.
Sleep = 0x56,
/// Copy complete current-frame capture group by declaration index.
GetCapture = 0x57,
/// Dispatch through an immutable implementation: TraitTypeId, method index.
CallTrait = 0x58,
// --- 6.8 Peripherals and System ---
/// Pre-load host binding call by `SYSC` table index.
@@ -202,6 +176,31 @@ pub enum OpCode {
/// Synchronizes the VM with the hardware frame (usually 60Hz).
/// Execution pauses until the next VSync.
FrameSync = 0x80,
// Registry-dependent typed operations (DEC-0045).
/// DYN_PACK: TypeId:u32; requires validated Registry metadata.
DynPack = 0x90,
/// DYN_UNPACK: TypeId:u32; requires validated Registry metadata.
DynUnpack = 0x91,
/// DYN_CAN_UNPACK: TypeId:u32; requires validated Registry metadata.
DynCanUnpack = 0x92,
/// REF_IS_EXACT: source:TypeId, target:TypeId; requires validated Registry metadata.
RefIsExact = 0x93,
/// REF_IMPLEMENTS: source:TypeId, target:TypeId; requires validated Registry metadata.
RefImplements = 0x94,
/// REF_TO_TRAIT: source:TypeId, target:TypeId; requires validated Registry metadata.
RefToTrait = 0x95,
/// REF_CAST: source:TypeId, target:TypeId; requires validated Registry metadata.
RefCast = 0x96,
// Registry-backed collection operations. cycles() is their base component.
StructNew = 0xA0,
StructGet = 0xA1,
StructSet = 0xA2,
ArrayNew = 0xA3,
ArrayLen = 0xA4,
ArrayGet = 0xA5,
ArraySet = 0xA6,
}
impl TryFrom<u16> for OpCode {
@@ -255,18 +254,36 @@ impl TryFrom<u16> for OpCode {
0x54 => Ok(OpCode::Spawn),
0x55 => Ok(OpCode::Yield),
0x56 => Ok(OpCode::Sleep),
0x57 => Ok(OpCode::GetCapture),
0x58 => Ok(OpCode::CallTrait),
0x70 => Ok(OpCode::Syscall),
0x71 => Ok(OpCode::Hostcall),
0x72 => Ok(OpCode::Intrinsic),
0x80 => Ok(OpCode::FrameSync),
0x90 => Ok(OpCode::DynPack),
0x91 => Ok(OpCode::DynUnpack),
0x92 => Ok(OpCode::DynCanUnpack),
0x93 => Ok(OpCode::RefIsExact),
0x94 => Ok(OpCode::RefImplements),
0x95 => Ok(OpCode::RefToTrait),
0x96 => Ok(OpCode::RefCast),
0xA0 => Ok(OpCode::StructNew),
0xA1 => Ok(OpCode::StructGet),
0xA2 => Ok(OpCode::StructSet),
0xA3 => Ok(OpCode::ArrayNew),
0xA4 => Ok(OpCode::ArrayLen),
0xA5 => Ok(OpCode::ArrayGet),
0xA6 => Ok(OpCode::ArraySet),
_ => Err(format!("Invalid OpCode: 0x{:04X}", value)),
}
}
}
impl OpCode {
/// Returns the cost of the instruction in VM cycles.
/// This is used for performance monitoring and resource limiting (Certification).
/// Returns fixed VM cycles, or the base component for collection operations.
/// Collection execution adds Registry widths and valid construction length;
/// callers must not use this base alone as the complete attempt cost.
pub fn cycles(&self) -> u64 {
match self {
OpCode::Nop => 1,
@@ -311,7 +328,8 @@ impl OpCode {
OpCode::Call => 5,
OpCode::Ret => 4,
OpCode::MakeClosure => 8,
OpCode::CallClosure => 6,
OpCode::CallClosure | OpCode::CallTrait => 6,
OpCode::GetCapture => 2,
OpCode::Spawn => 6,
OpCode::Yield => 1,
OpCode::Sleep => 1,
@@ -319,6 +337,20 @@ impl OpCode {
OpCode::Hostcall => 1,
OpCode::Intrinsic => 1,
OpCode::FrameSync => 1,
OpCode::DynPack => 8,
OpCode::DynUnpack => 4,
OpCode::DynCanUnpack => 3,
OpCode::RefIsExact => 4,
OpCode::RefImplements => 4,
OpCode::RefToTrait => 5,
OpCode::RefCast => 4,
OpCode::StructNew => 8,
OpCode::StructGet => 3,
OpCode::StructSet => 4,
OpCode::ArrayNew => 8,
OpCode::ArrayLen => 3,
OpCode::ArrayGet => 3,
OpCode::ArraySet => 4,
}
}
}
@@ -5,18 +5,24 @@ use crate::opcode::OpCode;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OpcodeSpec {
pub name: &'static str,
pub imm_bytes: u8, // immediate payload size (decode)
pub pops: u16, // slots popped
pub pushes: u16, // slots pushed
pub is_branch: bool, // has a control-flow target
pub imm_bytes: u8, // immediate payload size (decode)
/// None requires Registry resolution; it never means zero slots.
pub pops: Option<u16>, // slots popped
/// None requires Registry resolution; it never means zero slots.
pub pushes: Option<u16>, // slots pushed
pub is_branch: bool, // has a control-flow target
pub is_terminator: bool, // ends basic block: JMP/RET/TRAP/HALT
pub may_trap: bool, // runtime trap possible
/// Marks this opcode as a VM safepoint. Used by GC/scheduler policies.
pub may_trap: bool, // runtime trap possible
/// Marks this opcode as a VM safepoint. Used by GC policies. Last-root RET is also a contextual GC opportunity.
pub is_safepoint: bool,
}
pub trait OpCodeSpecExt {
fn spec(&self) -> OpcodeSpec;
/// These instructions cannot be verified from slot-only ExecutionFunction.
fn requires_registry(&self) -> bool {
self.spec().pops.is_none() || self.spec().pushes.is_none()
}
}
impl OpCodeSpecExt for OpCode {
@@ -25,8 +31,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Nop => OpcodeSpec {
name: "NOP",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -35,8 +41,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Halt => OpcodeSpec {
name: "HALT",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: true,
may_trap: false,
@@ -45,8 +51,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Jmp => OpcodeSpec {
name: "JMP",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: true,
is_terminator: true,
may_trap: false,
@@ -55,8 +61,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::JmpIfFalse => OpcodeSpec {
name: "JMP_IF_FALSE",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: true,
is_terminator: false,
may_trap: true,
@@ -65,8 +71,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::JmpIfTrue => OpcodeSpec {
name: "JMP_IF_TRUE",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: true,
is_terminator: false,
may_trap: true,
@@ -75,8 +81,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Trap => OpcodeSpec {
name: "TRAP",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: true,
may_trap: true,
@@ -85,8 +91,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushConst => OpcodeSpec {
name: "PUSH_CONST",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -95,8 +101,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Pop => OpcodeSpec {
name: "POP",
imm_bytes: 0,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -105,8 +111,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PopN => OpcodeSpec {
name: "POP_N",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -115,8 +121,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Dup => OpcodeSpec {
name: "DUP",
imm_bytes: 0,
pops: 1,
pushes: 2,
pops: Some(1),
pushes: Some(2),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -125,8 +131,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Swap => OpcodeSpec {
name: "SWAP",
imm_bytes: 0,
pops: 2,
pushes: 2,
pops: Some(2),
pushes: Some(2),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -135,8 +141,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushI64 => OpcodeSpec {
name: "PUSH_I64",
imm_bytes: 8,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -145,8 +151,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushF64 => OpcodeSpec {
name: "PUSH_F64",
imm_bytes: 8,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -155,8 +161,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushBool => OpcodeSpec {
name: "PUSH_BOOL",
imm_bytes: 1,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -165,8 +171,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushI32 => OpcodeSpec {
name: "PUSH_I32",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -175,8 +181,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Add => OpcodeSpec {
name: "ADD",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -185,8 +191,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Sub => OpcodeSpec {
name: "SUB",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -195,8 +201,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Mul => OpcodeSpec {
name: "MUL",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -205,8 +211,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Div => OpcodeSpec {
name: "DIV",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -215,8 +221,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Mod => OpcodeSpec {
name: "MOD",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -225,8 +231,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Eq => OpcodeSpec {
name: "EQ",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -235,8 +241,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Neq => OpcodeSpec {
name: "NEQ",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -245,8 +251,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Lt => OpcodeSpec {
name: "LT",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -255,8 +261,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Gt => OpcodeSpec {
name: "GT",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -265,8 +271,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::And => OpcodeSpec {
name: "AND",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -275,8 +281,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Or => OpcodeSpec {
name: "OR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -285,8 +291,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Not => OpcodeSpec {
name: "NOT",
imm_bytes: 0,
pops: 1,
pushes: 1,
pops: Some(1),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -295,8 +301,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitAnd => OpcodeSpec {
name: "BIT_AND",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -305,8 +311,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitOr => OpcodeSpec {
name: "BIT_OR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -315,8 +321,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitXor => OpcodeSpec {
name: "BIT_XOR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -325,8 +331,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Shl => OpcodeSpec {
name: "SHL",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -335,8 +341,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Shr => OpcodeSpec {
name: "SHR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -345,8 +351,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Lte => OpcodeSpec {
name: "LTE",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -355,8 +361,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Gte => OpcodeSpec {
name: "GTE",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -365,8 +371,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Neg => OpcodeSpec {
name: "NEG",
imm_bytes: 0,
pops: 1,
pushes: 1,
pops: Some(1),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -375,8 +381,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::GetGlobal => OpcodeSpec {
name: "GET_GLOBAL",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -385,8 +391,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::SetGlobal => OpcodeSpec {
name: "SET_GLOBAL",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -395,8 +401,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::GetLocal => OpcodeSpec {
name: "GET_LOCAL",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -405,8 +411,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::SetLocal => OpcodeSpec {
name: "SET_LOCAL",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -415,8 +421,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Call => OpcodeSpec {
name: "CALL",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -425,44 +431,41 @@ impl OpCodeSpecExt for OpCode {
OpCode::Ret => OpcodeSpec {
name: "RET",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: true,
may_trap: false,
is_safepoint: false,
},
OpCode::MakeClosure => OpcodeSpec {
name: "MAKE_CLOSURE",
// Two u32 immediates: fn_id and capture_count
imm_bytes: 8,
// Dynamic, depends on capture_count; keep 0 here for verifier-free spec
pops: 0,
pushes: 1,
is_branch: false,
is_terminator: false,
may_trap: false,
is_safepoint: false,
},
OpCode::CallClosure => OpcodeSpec {
name: "CALL_CLOSURE",
// One u32 immediate: arg_count (user args, excludes hidden arg0)
imm_bytes: 4,
// Dynamic: pops closure_ref + arg_count; keep 0 in spec layer
pops: 0,
pushes: 0,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::MakeClosure | OpCode::CallClosure | OpCode::GetCapture | OpCode::CallTrait => {
OpcodeSpec {
name: match self {
OpCode::MakeClosure => "MAKE_CLOSURE",
OpCode::CallClosure => "CALL_CLOSURE",
OpCode::GetCapture => "GET_CAPTURE",
_ => "CALL_TRAIT",
},
imm_bytes: if matches!(self, OpCode::MakeClosure | OpCode::CallTrait) {
8
} else {
4
},
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
}
}
OpCode::Spawn => OpcodeSpec {
name: "SPAWN",
// Two u32 immediates: fn_id and arg_count
imm_bytes: 8,
// Dynamic pops depends on arg_count; keep 0 here in spec layer
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -471,33 +474,33 @@ impl OpCodeSpecExt for OpCode {
OpCode::Yield => OpcodeSpec {
name: "YIELD",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
// Not a block terminator; effect realized at safepoint
// Retired encoding: retained for diagnostic decoding only.
is_terminator: false,
may_trap: false,
// Treated as a safepoint marker for cooperative scheduling
is_safepoint: true,
// Loading rejects this opcode, including unreachable occurrences.
is_safepoint: false,
},
OpCode::Sleep => OpcodeSpec {
name: "SLEEP",
// One u32 immediate: duration_ticks
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
// Ends execution at safepoint after instruction completes
// Retired encoding: retained for diagnostic decoding only.
is_terminator: false,
may_trap: false,
// Considered a safepoint since it forces a frame boundary
is_safepoint: true,
// Loading rejects this opcode, including unreachable occurrences.
is_safepoint: false,
},
OpCode::Hostcall => OpcodeSpec {
name: "HOSTCALL",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -506,8 +509,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Syscall => OpcodeSpec {
name: "SYSCALL",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -516,8 +519,148 @@ impl OpCodeSpecExt for OpCode {
OpCode::Intrinsic => OpcodeSpec {
name: "INTRINSIC",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::DynPack => OpcodeSpec {
name: "DYN_PACK",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::DynUnpack => OpcodeSpec {
name: "DYN_UNPACK",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::DynCanUnpack => OpcodeSpec {
name: "DYN_CAN_UNPACK",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefIsExact => OpcodeSpec {
name: "REF_IS_EXACT",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefImplements => OpcodeSpec {
name: "REF_IMPLEMENTS",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefToTrait => OpcodeSpec {
name: "REF_TO_TRAIT",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefCast => OpcodeSpec {
name: "REF_CAST",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::StructNew => OpcodeSpec {
name: "STRUCT_NEW",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::StructGet => OpcodeSpec {
name: "STRUCT_GET",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::StructSet => OpcodeSpec {
name: "STRUCT_SET",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayNew => OpcodeSpec {
name: "ARRAY_NEW",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayLen => OpcodeSpec {
name: "ARRAY_LEN",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayGet => OpcodeSpec {
name: "ARRAY_GET",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArraySet => OpcodeSpec {
name: "ARRAY_SET",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -526,8 +669,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::FrameSync => OpcodeSpec {
name: "FRAME_SYNC",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -1,43 +1,35 @@
/// Resolved execution widths derived from sealed Registry metadata.
/// This cache is never serialized as a PBX function signature.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ExecutionFunction {
pub code_offset: u32,
pub code_len: u32,
pub param_slots: u16,
pub local_slots: u16,
pub return_slots: u16,
pub max_stack_slots: u16,
}
use crate::abi::TrapInfo;
use crate::model::{BytecodeModule, ConstantPoolEntry, DebugInfo, Export, FunctionMeta};
use crate::model::DebugInfo;
use crate::value::Value;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::sync::Arc;
/// Represents a fully linked, executable PBX program image.
///
/// Under the Prometeu architecture, the ProgramImage is a "closed-world" artifact
/// produced by the compiler. All linking, relocation, and symbol resolution
/// MUST be performed by the compiler before this image is created.
///
/// The runtime (VM) assumes this image is authoritative and performs no
/// additional linking or fixups.
/// Immutable execution payload/cache, produced during sealed image publication.
/// This container does not authorize execution. VM sessions require the private
/// ValidatedProgramImage factory, including bounded Registry/ISA/native checks.
#[derive(Debug, Clone, Default)]
pub struct ProgramImage {
pub rom: Arc<[u8]>,
pub constant_pool: Arc<[Value]>,
pub functions: Arc<[FunctionMeta]>,
pub debug_info: Option<DebugInfo>,
pub functions: Arc<[ExecutionFunction]>,
pub debug_info: Option<Arc<DebugInfo>>,
pub exports: Arc<HashMap<String, u32>>,
}
impl ProgramImage {
pub fn new(
rom: Vec<u8>,
constant_pool: Vec<Value>,
functions: Vec<FunctionMeta>,
debug_info: Option<DebugInfo>,
exports: HashMap<String, u32>,
) -> Self {
Self {
rom: Arc::from(rom),
constant_pool: Arc::from(constant_pool),
functions: Arc::from(functions),
debug_info,
exports: Arc::new(exports),
}
}
pub fn create_trap(&self, code: u32, opcode: u16, mut message: String, pc: u32) -> TrapInfo {
let span = self
.debug_info
@@ -50,7 +42,7 @@ impl ProgramImage {
}
}
TrapInfo { code, opcode, message, pc, span }
TrapInfo { code, opcode, message, pc, span, resource: None }
}
pub fn find_function_index(&self, pc: u32) -> Option<usize> {
@@ -64,61 +56,3 @@ impl ProgramImage {
.map(|(_, name)| name.as_str())
}
}
impl From<BytecodeModule> for ProgramImage {
fn from(module: BytecodeModule) -> Self {
let constant_pool: Vec<Value> = module
.const_pool
.iter()
.map(|entry| match entry {
ConstantPoolEntry::Null => Value::Null,
ConstantPoolEntry::Int64(v) => Value::Int64(*v),
ConstantPoolEntry::Float64(v) => Value::Float(*v),
ConstantPoolEntry::Boolean(v) => Value::Boolean(*v),
ConstantPoolEntry::String(v) => Value::string(v.clone()),
ConstantPoolEntry::Int32(v) => Value::Int32(*v),
})
.collect();
let mut exports = HashMap::new();
for export in module.exports {
exports.insert(export.symbol, export.func_idx);
}
ProgramImage::new(module.code, constant_pool, module.functions, module.debug_info, exports)
}
}
impl From<ProgramImage> for BytecodeModule {
fn from(program: ProgramImage) -> Self {
let const_pool = program
.constant_pool
.iter()
.map(|v| match v {
Value::Null => ConstantPoolEntry::Null,
Value::Int64(v) => ConstantPoolEntry::Int64(*v),
Value::Float(v) => ConstantPoolEntry::Float64(*v),
Value::Boolean(v) => ConstantPoolEntry::Boolean(*v),
Value::String(v) => ConstantPoolEntry::String(v.to_string()),
Value::Int32(v) => ConstantPoolEntry::Int32(*v),
Value::HeapRef(_) => ConstantPoolEntry::Null,
})
.collect();
let exports = program
.exports
.iter()
.map(|(symbol, &func_idx)| Export { symbol: symbol.clone(), func_idx })
.collect();
BytecodeModule {
version: 0,
const_pool,
functions: program.functions.as_ref().to_vec(),
code: program.rom.as_ref().to_vec(),
debug_info: program.debug_info.clone(),
exports,
syscalls: Vec::new(),
}
}
}
@@ -0,0 +1,833 @@
//! Typed PBX declarations and bounded immutable Registry resolution.
//! These declarations do not authorize execution: code and bindings still require verification.
use crate::load_limits::IdDomain;
use crate::load_limits::{
LoadBudget, LoadCode as C, LoadFailure as E, LoadReason as R, LoadResource as Q,
};
use crate::Value;
use std::sync::Arc;
macro_rules! id {
($name:ident) => {
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct $name(pub u32);
};
}
id!(TypeId);
id!(FunctionId);
id!(ImplementationId);
id!(BuiltinId);
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NamedType {
pub type_id: TypeId,
pub name: Option<String>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Signature {
pub parameters: Vec<NamedType>,
pub results: Vec<TypeId>,
}
impl Signature {
pub fn same_types(&self, other: &Self) -> bool {
self.parameters.len() == other.parameters.len()
&& self
.parameters
.iter()
.map(|p| p.type_id)
.eq(other.parameters.iter().map(|p| p.type_id))
&& self.results == other.results
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MethodDecl {
pub name: Option<String>,
pub signature: Signature,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TypeKind {
Builtin(BuiltinId),
Struct(Vec<NamedType>),
Array(TypeId),
Trait(Vec<MethodDecl>),
Fn(Signature),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TypeDecl {
pub name: Option<String>,
pub kind: TypeKind,
}
/// Runtime-owned roles; frontend names and FunctionIds are independent.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[repr(u8)]
pub enum LifecycleRole {
#[default]
None = 0,
BeforePause = 1,
BeforeResume = 2,
MemcardBoot = 3,
}
impl TryFrom<u8> for LifecycleRole {
type Error = E;
fn try_from(value: u8) -> Result<Self, E> {
match value {
0 => Ok(Self::None),
1 => Ok(Self::BeforePause),
2 => Ok(Self::BeforeResume),
3 => Ok(Self::MemcardBoot),
_ => Err(E::new(C::InvalidRegistry, R::LifecycleRole)),
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FunctionDecl {
pub lifecycle_role: LifecycleRole,
pub name: Option<String>,
pub signature: Signature,
pub code_offset: u32,
pub code_len: u32,
pub local_slots: u32,
pub max_stack_slots: u32,
/// Ordered logical capture groups, encoded in the separate PBX section 8.
pub captures: Vec<TypeId>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImplementationDecl {
pub owner: TypeId,
pub trait_id: TypeId,
pub methods: Vec<FunctionId>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct RegistryDeclarations {
pub types: Vec<TypeDecl>,
pub functions: Vec<FunctionDecl>,
pub implementations: Vec<ImplementationDecl>,
}
pub type StringSlot = Option<Arc<str>>;
#[derive(Debug, Clone)]
pub struct DynamicSlot {
pub type_id: Option<TypeId>,
pub payload: Value,
}
impl Default for DynamicSlot {
fn default() -> Self {
Self { type_id: None, payload: Value::Null }
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DefaultKind {
Int32,
Int64,
Float,
Bool,
Null,
Vec2,
Pixel,
Trait,
Dynamic,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Ownership {
Plain,
GuestReference,
NativeString,
TraitReceiver,
Dynamic,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StorageLayout {
pub size: usize,
pub alignment: usize,
pub slots: u32,
pub ownership: Ownership,
pub default: DefaultKind,
}
impl StorageLayout {
fn new(
size: usize,
alignment: usize,
slots: u32,
ownership: Ownership,
default: DefaultKind,
) -> Self {
Self { size, alignment, slots, ownership, default }
}
pub fn nullable(self) -> bool {
!matches!(self.ownership, Ownership::Plain)
}
/// Canonical stack-side defaults, with no allocation or source constructor.
/// Native typed storage still requires its own initialized-slot construction.
pub fn default_values(self) -> &'static [Value] {
match self.default {
DefaultKind::Int32 => &[Value::Int32(0)],
DefaultKind::Int64 => &[Value::Int64(0)],
DefaultKind::Float => &[Value::Float(0.0)],
DefaultKind::Bool => &[Value::Boolean(false)],
DefaultKind::Null => &[Value::Null],
DefaultKind::Vec2 => &[Value::Float(0.0), Value::Float(0.0)],
DefaultKind::Pixel => &[Value::Int64(0), Value::Int64(0), Value::Int64(0)],
DefaultKind::Trait | DefaultKind::Dynamic => &[Value::Null, Value::Null],
}
}
}
impl BuiltinId {
pub const COLOR: Self = Self(1);
pub const VEC2: Self = Self(2);
pub const PIXEL: Self = Self(3);
pub const INT32: Self = Self(0x10);
pub const INT64: Self = Self(0x11);
pub const FLOAT: Self = Self(0x12);
pub const BOOL: Self = Self(0x13);
pub const STRING: Self = Self(0x14);
pub const DYNAMIC: Self = Self(0x15);
pub const RANDOM: Self = Self(0x16);
pub fn layout(self) -> Result<StorageLayout, E> {
use DefaultKind as D;
use Ownership as O;
let (size, alignment, slots, ownership, default) = match self {
Self::COLOR => (4, 4, 1, O::Plain, D::Int64),
Self::VEC2 => (16, 8, 2, O::Plain, D::Vec2),
Self::PIXEL => (24, 8, 3, O::Plain, D::Pixel),
Self::INT32 => (4, 4, 1, O::Plain, D::Int32),
Self::INT64 => (8, 8, 1, O::Plain, D::Int64),
Self::FLOAT => (8, 8, 1, O::Plain, D::Float),
Self::BOOL => (1, 1, 1, O::Plain, D::Bool),
Self::RANDOM => (8, 8, 1, O::GuestReference, D::Null),
Self::STRING => {
(size_of::<StringSlot>(), align_of::<StringSlot>(), 1, O::NativeString, D::Null)
}
Self::DYNAMIC => {
(size_of::<DynamicSlot>(), align_of::<DynamicSlot>(), 2, O::Dynamic, D::Dynamic)
}
_ => return Err(E::new(C::UnsupportedFormat, R::Builtin)),
};
Ok(StorageLayout::new(size, alignment, slots, ownership, default))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FieldLayout {
pub type_id: TypeId,
pub offset: usize,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OwnedField {
pub offset: usize,
pub ownership: Ownership,
}
#[derive(Debug, PartialEq, Eq)]
pub struct StructLayout {
/// Sum of execution-slot widths, resolved once for deterministic NEW charging.
pub initialization_slots: u64,
pub size: usize,
pub alignment: usize,
pub fields: Vec<FieldLayout>,
/// Sorted offsets for fields requiring guest tracing or native ownership handling.
pub owned_fields: Vec<OwnedField>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ArrayLayout {
pub element_type_id: TypeId,
pub stride: usize,
pub element_alignment: usize,
}
#[derive(Debug, PartialEq, Eq)]
pub struct TypeLayout {
pub storage: StorageLayout,
pub instance: Option<StructLayout>,
pub array: Option<ArrayLayout>,
pub callable: Option<FunctionLayout>,
pub methods: Vec<FunctionLayout>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CaptureLayout {
pub type_id: TypeId,
pub slot_offset: u32,
pub slots: u32,
}
#[derive(Debug, PartialEq, Eq)]
pub struct FunctionLayout {
pub parameter_slots: u32,
pub result_slots: u32,
pub capture_slots: u32,
pub captures: Vec<CaptureLayout>,
}
#[derive(Debug)]
pub struct Registry {
lifecycle_hooks: [Option<FunctionId>; 3],
declarations: RegistryDeclarations,
layouts: Vec<TypeLayout>,
functions: Vec<FunctionLayout>,
// Sorted by owner/trait; original implementation IDs are never remapped.
implementations: Vec<(TypeId, TypeId, ImplementationId)>,
}
impl Registry {
pub fn lifecycle_hook(&self, role: LifecycleRole) -> Option<FunctionId> {
match role {
LifecycleRole::None => None,
LifecycleRole::BeforePause => self.lifecycle_hooks[0],
LifecycleRole::BeforeResume => self.lifecycle_hooks[1],
LifecycleRole::MemcardBoot => self.lifecycle_hooks[2],
}
}
pub fn declarations(&self) -> &RegistryDeclarations {
&self.declarations
}
pub fn type_layout(&self, id: TypeId) -> Option<&TypeLayout> {
self.layouts.get(id.0 as usize)
}
pub fn function_layout(&self, id: FunctionId) -> Option<&FunctionLayout> {
self.functions.get(id.0 as usize)
}
pub fn implementation(&self, owner: TypeId, trait_id: TypeId) -> Option<ImplementationId> {
self.implementations
.binary_search_by_key(&(owner, trait_id), |&(a, b, _)| (a, b))
.ok()
.map(|i| self.implementations[i].2)
}
/// Resolves declarations, not code/bindings. The caller must still verify before publication.
/// Declaration allocations are retained and charged here, even for non-PBX producers.
pub fn resolve(
declarations: RegistryDeclarations,
code_len: usize,
budget: &mut LoadBudget,
) -> Result<Self, E> {
budget.transaction(|budget| Self::resolve_inner(declarations, code_len, budget))
}
fn resolve_inner(
d: RegistryDeclarations,
code_len: usize,
b: &mut LoadBudget,
) -> Result<Self, E> {
b.check(Q::Types, d.types.len() as u64)?;
b.check(Q::Functions, d.functions.len() as u64)?;
b.check(Q::Implementations, d.implementations.len() as u64)?;
b.check(Q::CodeBytes, code_len as u64)?;
charge_declarations(&d, b)?;
validate_declarations(&d, b)?;
let mut layouts = b.vector(d.types.len(), Q::RegistryBytes)?;
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
let storage = match t.kind {
TypeKind::Builtin(id) => id.layout().map_err(|e| e.record(i as u32))?,
TypeKind::Trait(_) => {
StorageLayout::new(16, 8, 2, Ownership::TraitReceiver, DefaultKind::Trait)
}
_ => StorageLayout::new(8, 8, 1, Ownership::GuestReference, DefaultKind::Null),
};
layouts.push(TypeLayout {
storage,
instance: None,
array: None,
callable: None,
methods: Vec::new(),
});
}
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
if let TypeKind::Fn(s) = &t.kind {
layouts[i].callable = Some(resolve_signature(s, &layouts, b)?);
}
if let TypeKind::Trait(methods) = &t.kind {
let mut resolved = b.vector(methods.len(), Q::RegistryBytes)?;
for method in methods {
b.work(1)?;
resolved.push(resolve_signature(&method.signature, &layouts, b)?);
}
layouts[i].methods = resolved;
}
if let TypeKind::Array(element_type_id) = t.kind {
let element = layouts[element_type_id.0 as usize].storage;
layouts[i].array = Some(ArrayLayout {
element_type_id,
stride: align(element.size, element.alignment)?,
element_alignment: element.alignment,
});
}
if let TypeKind::Struct(fields) = &t.kind {
let mut offsets = b.vector(fields.len(), Q::RegistryBytes)?;
b.work(fields.len())?;
let owned_count = fields
.iter()
.filter(|f| layouts[f.type_id.0 as usize].storage.ownership != Ownership::Plain)
.count();
let mut owned = b.vector(owned_count, Q::RegistryBytes)?;
let (mut size, mut alignment) = (0, 1);
let mut initialization_slots = 0u64;
for field in fields {
b.work(1)?;
let layout = layouts[field.type_id.0 as usize].storage;
initialization_slots = initialization_slots
.checked_add(u64::from(layout.slots))
.ok_or_else(overflow)?;
size = align(size, layout.alignment)?;
offsets.push(FieldLayout { type_id: field.type_id, offset: size });
if layout.ownership != Ownership::Plain {
owned.push(OwnedField { offset: size, ownership: layout.ownership });
}
size = size.checked_add(layout.size).ok_or_else(overflow)?;
alignment = alignment.max(layout.alignment);
}
layouts[i].instance = Some(StructLayout {
initialization_slots,
size: align(size, alignment)?,
alignment,
fields: offsets,
owned_fields: owned,
});
}
}
let mut lifecycle_hooks = [None; 3];
let mut functions = b.vector(d.functions.len(), Q::RegistryBytes)?;
let mut ranges = b.vector(d.functions.len(), Q::TemporaryBytes)?;
for (i, f) in d.functions.iter().enumerate() {
b.work(1)?;
if f.lifecycle_role != LifecycleRole::None {
let signature_valid = if f.lifecycle_role == LifecycleRole::MemcardBoot {
f.signature.parameters.len() == 1
&& f.signature.results.len() == 1
&& d.types
.get(f.signature.parameters[0].type_id.0 as usize)
.is_some_and(|t| t.kind == TypeKind::Builtin(BuiltinId::INT64))
&& d.types
.get(f.signature.results[0].0 as usize)
.is_some_and(|t| t.kind == TypeKind::Builtin(BuiltinId::INT32))
} else {
f.signature.parameters.is_empty() && f.signature.results.is_empty()
};
let invalid = i == 0 || !signature_valid || !f.captures.is_empty();
if invalid {
return Err(E::new(C::InvalidEntrypoint, R::LifecycleSignature)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
let slot = &mut lifecycle_hooks[f.lifecycle_role as usize - 1];
if slot.replace(FunctionId(i as u32)).is_some() {
return Err(E::new(C::InvalidRegistry, R::DuplicateLifecycleRole)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
}
let params = width(f.signature.parameters.iter().map(|p| p.type_id), &layouts, b)?;
let results = width(f.signature.results.iter().copied(), &layouts, b)?;
let frame = u64::from(params) + u64::from(f.local_slots) + u64::from(f.max_stack_slots);
if frame > b.frame_limit() {
return Err(E::new(C::InvalidCode, R::FrameSlots)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
if u64::from(results) > b.result_limit() {
return Err(E::new(C::InvalidCode, R::ReturnSlots)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
let end = f.code_offset.checked_add(f.code_len).ok_or_else(|| {
E::new(C::InvalidCode, R::CodeRange)
.in_section(1)
.record(i as u32)
.in_function(i as u32, Some(f.code_offset))
})?;
if end as usize > code_len || f.code_len == 0 {
return Err(E::new(C::InvalidCode, R::CodeRange)
.in_section(1)
.record(i as u32)
.in_function(i as u32, Some(f.code_offset)));
}
ranges.push((f.code_offset, end, i as u32));
let mut captures = b.vector(f.captures.len(), Q::RegistryBytes)?;
let mut capture_slots = 0u32;
for &type_id in &f.captures {
b.work(1)?;
let slots = layouts[type_id.0 as usize].storage.slots;
captures.push(CaptureLayout { type_id, slot_offset: capture_slots, slots });
capture_slots = capture_slots.checked_add(slots).ok_or_else(overflow)?;
}
functions.push(FunctionLayout {
parameter_slots: params,
result_slots: results,
capture_slots,
captures,
});
}
sort_work(ranges.len(), b)?;
ranges.sort_unstable();
for pair in ranges.windows(2) {
b.work(1)?;
if pair[0].1 > pair[1].0 {
return Err(E::new(C::InvalidCode, R::CodeRange).record(pair[1].2));
}
}
b.refund(Q::TemporaryBytes, (ranges.capacity() * size_of::<(u32, u32, u32)>()) as u64);
drop(ranges);
let mut implementations = b.vector(d.implementations.len(), Q::RegistryBytes)?;
for (i, imp) in d.implementations.iter().enumerate() {
b.work(1)?;
if !matches!(d.types[imp.owner.0 as usize].kind, TypeKind::Struct(_)) {
return Err(E::new(C::InvalidReference, R::OwnerCategory)
.in_section(7)
.record(i as u32)
.reference(IdDomain::Type, imp.owner.0));
}
let TypeKind::Trait(methods) = &d.types[imp.trait_id.0 as usize].kind else {
return Err(E::new(C::InvalidReference, R::TraitCategory)
.in_section(7)
.record(i as u32)
.reference(IdDomain::Type, imp.trait_id.0));
};
if methods.len() != imp.methods.len() {
return Err(E::new(C::InvalidRegistry, R::MethodCount)
.in_section(7)
.record(i as u32));
}
for (j, (method, id)) in methods.iter().zip(&imp.methods).enumerate() {
let signature = &d.functions[id.0 as usize].signature;
if !d.functions[id.0 as usize].captures.is_empty() {
return Err(E::new(C::InvalidRegistry, R::CapturedDirectCall)
.in_section(7)
.record(i as u32)
.member(j as u32));
}
b.work(signature.parameters.len() + signature.results.len() + 1)?;
if signature.parameters.first().map(|p| p.type_id) != Some(imp.owner)
|| signature.parameters.len() != method.signature.parameters.len() + 1
|| !signature.parameters.iter().skip(1).map(|p| p.type_id).eq(method
.signature
.parameters
.iter()
.map(|p| p.type_id))
|| signature.results != method.signature.results
{
return Err(E::new(C::InvalidRegistry, R::Signature)
.in_section(7)
.record(i as u32)
.member(j as u32));
}
}
implementations.push((imp.owner, imp.trait_id, ImplementationId(i as u32)));
}
sort_work(implementations.len(), b)?;
implementations.sort_unstable();
for pair in implementations.windows(2) {
b.work(1)?;
if (pair[0].0, pair[0].1) == (pair[1].0, pair[1].1) {
return Err(E::new(C::InvalidRegistry, R::DuplicateImplementation)
.in_section(7)
.record(pair[1].2 .0));
}
}
Ok(Self { lifecycle_hooks, declarations: d, layouts, functions, implementations })
}
}
fn overflow() -> E {
E::new(C::ResourceLimit, R::Overflow)
}
fn resolve_signature(
s: &Signature,
layouts: &[TypeLayout],
b: &mut LoadBudget,
) -> Result<FunctionLayout, E> {
let parameter_slots = width(s.parameters.iter().map(|p| p.type_id), layouts, b)?;
let result_slots = width(s.results.iter().copied(), layouts, b)?;
if u64::from(parameter_slots) > b.frame_limit() {
return Err(E::new(C::InvalidRegistry, R::FrameSlots));
}
if u64::from(result_slots) > b.result_limit() {
return Err(E::new(C::InvalidRegistry, R::ReturnSlots));
}
Ok(FunctionLayout { parameter_slots, result_slots, capture_slots: 0, captures: Vec::new() })
}
fn align(n: usize, a: usize) -> Result<usize, E> {
n.checked_add(a - 1).map(|v| v & !(a - 1)).ok_or_else(overflow)
}
fn width(
ids: impl Iterator<Item = TypeId>,
layouts: &[TypeLayout],
b: &mut LoadBudget,
) -> Result<u32, E> {
let mut sum = 0u32;
for id in ids {
b.work(1)?;
sum = sum.checked_add(layouts[id.0 as usize].storage.slots).ok_or_else(overflow)?;
}
Ok(sum)
}
fn sort_work(n: usize, b: &mut LoadBudget) -> Result<(), E> {
let bits = usize::BITS - n.leading_zeros();
b.work(n.checked_mul(bits as usize + 1).ok_or_else(overflow)?)
}
fn type_ref(id: TypeId, d: &RegistryDeclarations) -> Result<(), E> {
if (id.0 as usize) < d.types.len() {
Ok(())
} else {
Err(E::new(C::InvalidReference, R::TypeId).reference(IdDomain::Type, id.0))
}
}
fn name(name: &Option<String>, b: &mut LoadBudget) -> Result<(), E> {
if let Some(name) = name {
if name.len() as u64 > b.individual_name_limit() {
return Err(E::resource(Q::NameBytes, name.len() as u64, b.individual_name_limit()));
}
b.charge(Q::NameBytes, name.len() as u64)?;
b.work(name.len())?;
}
Ok(())
}
fn named(items: &[NamedType], d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::NestedRecords, items.len() as u64)?;
for (i, item) in items.iter().enumerate() {
b.work(1)?;
type_ref(item.type_id, d).map_err(|e| e.member(i as u32))?;
name(&item.name, b)?;
}
Ok(())
}
fn signature(s: &Signature, d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
named(&s.parameters, d, b)?;
b.charge(Q::NestedRecords, s.results.len() as u64)?;
for (i, id) in s.results.iter().enumerate() {
b.work(1)?;
type_ref(*id, d).map_err(|e| e.member(i as u32))?;
}
Ok(())
}
fn signature_order(
a: &Signature,
b: &Signature,
budget: &mut LoadBudget,
) -> Result<std::cmp::Ordering, E> {
use std::cmp::Ordering;
for (a, b) in a.parameters.iter().zip(&b.parameters) {
budget.work(1)?;
let order = a.type_id.cmp(&b.type_id);
if order != Ordering::Equal {
return Ok(order);
}
}
budget.work(1)?;
let order = a.parameters.len().cmp(&b.parameters.len());
if order != Ordering::Equal {
return Ok(order);
}
for (a, b) in a.results.iter().zip(&b.results) {
budget.work(1)?;
let order = a.cmp(b);
if order != Ordering::Equal {
return Ok(order);
}
}
budget.work(1)?;
Ok(a.results.len().cmp(&b.results.len()))
}
/// Validate all edges before indexed layout resolution; IDs remain table positions.
pub(crate) fn validate_declarations(d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::Types, d.types.len() as u64)?;
b.charge(Q::Functions, d.functions.len() as u64)?;
b.charge(Q::Implementations, d.implementations.len() as u64)?;
let mut constructors = b.vector(d.types.len(), Q::TemporaryBytes)?;
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
name(&t.name, b).map_err(|e| e.in_section(6).record(i as u32))?;
let result = (|| match &t.kind {
TypeKind::Builtin(id) => {
id.layout()?;
constructors.push((0, id.0, i as u32));
Ok(())
}
TypeKind::Array(id) => {
type_ref(*id, d)?;
constructors.push((1, id.0, i as u32));
Ok(())
}
TypeKind::Struct(fields) => named(fields, d, b),
TypeKind::Fn(s) => signature(s, d, b),
TypeKind::Trait(methods) => {
b.charge(Q::NestedRecords, methods.len() as u64)?;
for m in methods {
b.work(1)?;
name(&m.name, b)?;
signature(&m.signature, d, b)?;
}
Ok(())
}
})();
result.map_err(|e| e.in_section(6).record(i as u32))?;
}
sort_work(constructors.len(), b)?;
constructors.sort_unstable();
for pair in constructors.windows(2) {
b.work(1)?;
if (pair[0].0, pair[0].1) == (pair[1].0, pair[1].1) {
return Err(E::new(
C::InvalidRegistry,
if pair[1].0 == 0 { R::DuplicateBuiltin } else { R::DuplicateArray },
)
.record(pair[1].2));
}
}
b.refund(Q::TemporaryBytes, (constructors.capacity() * size_of::<(i32, u32, u32)>()) as u64);
drop(constructors);
// Sorted Fn indices use fallible, metered comparisons; names are never keys.
let mut fns = b.vector::<usize>(d.types.len(), Q::TemporaryBytes)?;
for (id, t) in d.types.iter().enumerate() {
b.work(1)?;
let TypeKind::Fn(key) = &t.kind else { continue };
let (mut lo, mut hi) = (0, fns.len());
while lo < hi {
let mid = lo + (hi - lo) / 2;
let TypeKind::Fn(other) = &d.types[fns[mid]].kind else { unreachable!() };
match signature_order(key, other, b)? {
std::cmp::Ordering::Equal => {
return Err(E::new(C::InvalidRegistry, R::DuplicateFn)
.in_section(6)
.record(id as u32))
}
std::cmp::Ordering::Less => hi = mid,
std::cmp::Ordering::Greater => lo = mid + 1,
}
}
b.work(fns.len() - lo + 1)?;
fns.insert(lo, id);
}
b.refund(Q::TemporaryBytes, (fns.capacity() * size_of::<usize>()) as u64);
drop(fns);
// Iterative DFS processes each structural edge once; nominal nodes are leaves.
let mut colors = b.vector::<u8>(d.types.len(), Q::TemporaryBytes)?;
b.work(d.types.len())?;
colors.resize(d.types.len(), 0);
let mut walk = b.vector::<(usize, usize)>(d.types.len(), Q::TemporaryBytes)?;
for start in 0..d.types.len() {
b.work(1)?;
if colors[start] != 0 {
continue;
}
colors[start] = 1;
walk.push((start, 0));
while let Some((node, edge)) = walk.last_mut() {
b.work(1)?;
let next = match &d.types[*node].kind {
TypeKind::Array(id) if *edge == 0 => Some(*id),
TypeKind::Fn(s) => s.parameters.get(*edge).map(|p| p.type_id).or_else(|| {
edge.checked_sub(s.parameters.len()).and_then(|e| s.results.get(e)).copied()
}),
_ => None,
};
*edge += 1;
if let Some(id) = next {
let id = id.0 as usize;
if colors[id] == 1 {
b.work(walk.len())?;
let reason =
if walk.iter().any(|(n, _)| matches!(d.types[*n].kind, TypeKind::Fn(_))) {
R::StructuralTypeCycle
} else {
R::ArrayCycle
};
return Err(E::new(C::InvalidRegistry, reason).in_section(6).record(id as u32));
}
if colors[id] == 0 {
colors[id] = 1;
walk.push((id, 0));
}
} else {
colors[*node] = 2;
walk.pop();
}
}
}
b.refund(Q::TemporaryBytes, colors.capacity() as u64);
b.refund(Q::TemporaryBytes, (walk.capacity() * size_of::<(usize, usize)>()) as u64);
drop(colors);
drop(walk);
for (i, f) in d.functions.iter().enumerate() {
b.work(1)?;
name(&f.name, b).map_err(|e| e.in_section(1).record(i as u32))?;
signature(&f.signature, d, b).map_err(|e| e.in_section(1).record(i as u32))?;
b.charge(Q::NestedRecords, f.captures.len() as u64)?;
for (j, &id) in f.captures.iter().enumerate() {
b.work(1)?;
type_ref(id, d).map_err(|e| e.in_section(8).record(i as u32).member(j as u32))?;
}
}
for (i, imp) in d.implementations.iter().enumerate() {
b.work(1)?;
type_ref(imp.owner, d).map_err(|e| e.in_section(7).record(i as u32))?;
type_ref(imp.trait_id, d).map_err(|e| e.in_section(7).record(i as u32))?;
b.charge(Q::NestedRecords, imp.methods.len() as u64)?;
for (j, id) in imp.methods.iter().enumerate() {
b.work(1)?;
if id.0 as usize >= d.functions.len() {
return Err(E::new(C::InvalidReference, R::FunctionId)
.in_section(7)
.reference(IdDomain::Function, id.0)
.record(i as u32)
.member(j as u32));
}
}
}
Ok(())
}
fn charge_vec<T>(v: &Vec<T>, b: &mut LoadBudget) -> Result<(), E> {
b.charge(
Q::RegistryBytes,
(v.capacity() as u64).checked_mul(size_of::<T>() as u64).ok_or_else(overflow)?,
)
}
fn charge_name(n: &Option<String>, b: &mut LoadBudget) -> Result<(), E> {
if let Some(n) = n {
b.charge(Q::RegistryBytes, n.capacity() as u64)?;
}
Ok(())
}
fn charge_named(v: &Vec<NamedType>, b: &mut LoadBudget) -> Result<(), E> {
charge_vec(v, b)?;
for p in v {
b.work(1)?;
charge_name(&p.name, b)?;
}
Ok(())
}
fn charge_signature(s: &Signature, b: &mut LoadBudget) -> Result<(), E> {
charge_named(&s.parameters, b)?;
charge_vec(&s.results, b)
}
fn charge_declarations(d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::RegistryBytes, size_of::<Registry>() as u64)?;
charge_vec(&d.types, b)?;
charge_vec(&d.functions, b)?;
charge_vec(&d.implementations, b)?;
for t in &d.types {
b.work(1)?;
charge_name(&t.name, b)?;
match &t.kind {
TypeKind::Struct(fields) => charge_named(fields, b)?,
TypeKind::Fn(s) => charge_signature(s, b)?,
TypeKind::Trait(methods) => {
charge_vec(methods, b)?;
for m in methods {
b.work(1)?;
charge_name(&m.name, b)?;
charge_signature(&m.signature, b)?;
}
}
_ => {}
}
}
for f in &d.functions {
b.work(1)?;
charge_name(&f.name, b)?;
charge_signature(&f.signature, b)?;
charge_vec(&f.captures, b)?;
}
for imp in &d.implementations {
b.work(1)?;
charge_vec(&imp.methods, b)?;
}
Ok(())
}
@@ -0,0 +1,515 @@
//! Strict PBX v1 envelope and Registry sections. No legacy fallback.
//! Envelope parsing is structural only: non-Registry sections and instructions
//! must be validated by their consumers before an executable image is published.
use crate::load_limits::{
LoadBudget, LoadCode as C, LoadFailure as E, LoadReason as R, LoadResource as Q,
};
use crate::registry::*;
#[derive(Debug, Clone, Copy)]
pub struct Section<'a> {
pub kind: u32,
pub offset: usize,
pub bytes: &'a [u8],
}
#[derive(Debug)]
pub struct PbxEnvelope<'a> {
sections: [Option<Section<'a>>; 9],
}
impl<'a> PbxEnvelope<'a> {
pub fn section(&self, kind: u32) -> Option<Section<'a>> {
self.sections.get(kind as usize).copied().flatten()
}
pub fn parse(bytes: &'a [u8], b: &mut LoadBudget) -> Result<Self, E> {
b.transaction(|b| Self::parse_inner(bytes, b))
}
fn parse_inner(bytes: &'a [u8], b: &mut LoadBudget) -> Result<Self, E> {
b.check(Q::PbxBytes, bytes.len() as u64)?;
if bytes.len() < 32 {
return Err(E::new(C::InvalidFormat, R::Truncated));
}
b.work(32)?;
if &bytes[..4] != b"PBX\0" {
return Err(E::new(C::InvalidFormat, R::Magic));
}
if bytes[4..6] != [1, 0] {
return Err(E::new(C::UnsupportedFormat, R::Version));
}
if bytes[6] != 0 {
return Err(E::new(C::InvalidFormat, R::Endianness));
}
if bytes[7] != 0 || bytes[12..32].iter().any(|&x| x != 0) {
return Err(E::new(C::InvalidFormat, R::Reserved));
}
let count = u32::from_le_bytes(bytes[8..12].try_into().unwrap()) as usize;
let directory_end =
count.checked_mul(12).and_then(|n| n.checked_add(32)).ok_or_else(overflow)?;
if directory_end > bytes.len() {
return Err(E::new(C::InvalidFormat, R::Truncated));
}
let mut result = Self { sections: [None; 9] };
for i in 0..count {
b.work(13)?;
let pos = 32 + i * 12;
let kind = u32::from_le_bytes(bytes[pos..pos + 4].try_into().unwrap());
if kind > 8 {
return Err(E::new(C::UnsupportedFormat, R::SectionKind).at(kind, pos));
}
if result.sections[kind as usize].is_some() {
return Err(E::new(C::InvalidFormat, R::DuplicateSection).at(kind, pos));
}
let start = u32::from_le_bytes(bytes[pos + 4..pos + 8].try_into().unwrap()) as usize;
let len = u32::from_le_bytes(bytes[pos + 8..pos + 12].try_into().unwrap()) as usize;
let end = start.checked_add(len).ok_or_else(overflow)?;
if end > bytes.len() {
return Err(E::new(C::InvalidFormat, R::Truncated).at(kind, start));
}
if start < directory_end {
return Err(E::new(C::InvalidFormat, R::Overlap).at(kind, start));
}
if kind == 2 {
b.check(Q::CodeBytes, len as u64)?;
}
for other in result.sections.iter().flatten() {
b.work(1)?;
if len > 0
&& !other.bytes.is_empty()
&& start < other.offset + other.bytes.len()
&& other.offset < end
{
return Err(E::new(C::InvalidFormat, R::Overlap).at(kind, start));
}
}
result.sections[kind as usize] =
Some(Section { kind, offset: start, bytes: &bytes[start..end] });
}
for kind in [0, 1, 2, 4, 5, 6, 7, 8] {
if result.sections[kind].is_none() {
return Err(E::new(C::InvalidFormat, R::MissingSection).at(kind as u32, 8));
}
}
Ok(result)
}
/// Decode and resolve Registry metadata only. This is not an executable loader.
pub fn resolve_registry(&self, b: &mut LoadBudget) -> Result<Registry, E> {
b.transaction(|b| {
let resources = [
Q::TemporaryBytes,
Q::Types,
Q::Functions,
Q::Implementations,
Q::NestedRecords,
Q::NameBytes,
];
let before = resources.map(|r| b.used(r));
let types = Reader::new(self.section(6).unwrap(), b).types()?;
let mut functions = Reader::new(self.section(1).unwrap(), b).functions()?;
Reader::new(self.section(8).unwrap(), b).captures(&mut functions)?;
let implementations = Reader::new(self.section(7).unwrap(), b).implementations()?;
// Ownership moves from parse scratch to retained Registry. No clone or
// simultaneous second declaration allocation occurs at this boundary.
for (r, used) in resources.into_iter().zip(before) {
b.refund(r, b.used(r) - used);
}
Registry::resolve(
RegistryDeclarations { types, functions, implementations },
self.section(2).unwrap().bytes.len(),
b,
)
})
}
}
fn overflow() -> E {
E::new(C::ResourceLimit, R::Overflow)
}
struct Reader<'a, 'b> {
section: Section<'a>,
pos: usize,
budget: &'b mut LoadBudget,
}
impl<'a, 'b> Reader<'a, 'b> {
fn new(section: Section<'a>, budget: &'b mut LoadBudget) -> Self {
Self { section, pos: 0, budget }
}
fn error(&self, code: C, reason: R) -> E {
E::new(code, reason).at(self.section.kind, self.section.offset + self.pos)
}
fn take(&mut self, n: usize) -> Result<&'a [u8], E> {
let end = self.pos.checked_add(n).ok_or_else(overflow)?;
let value = self
.section
.bytes
.get(self.pos..end)
.ok_or_else(|| self.error(C::InvalidFormat, R::Truncated))?;
self.budget.work(n)?;
self.pos = end;
Ok(value)
}
fn byte(&mut self) -> Result<u8, E> {
Ok(self.take(1)?[0])
}
fn u32(&mut self) -> Result<u32, E> {
Ok(u32::from_le_bytes(self.take(4)?.try_into().unwrap()))
}
fn finish(&self) -> Result<(), E> {
if self.pos == self.section.bytes.len() {
Ok(())
} else {
Err(self.error(C::InvalidFormat, R::TrailingBytes))
}
}
fn list<T>(&mut self, resource: Q, min_bytes: usize) -> Result<(Vec<T>, usize), E> {
let count = self.u32()? as usize;
self.budget.charge(resource, count as u64)?;
let min = count.checked_mul(min_bytes).ok_or_else(overflow)?;
if min > self.section.bytes.len() - self.pos {
return Err(self.error(C::InvalidFormat, R::Truncated));
}
Ok((self.budget.vector(count, Q::TemporaryBytes)?, count))
}
fn name(&mut self) -> Result<Option<String>, E> {
match self.byte()? {
0 => Ok(None),
1 => {
let len = self.u32()? as usize;
if len as u64 > self.budget.individual_name_limit() {
return Err(E::resource(
Q::NameBytes,
len as u64,
self.budget.individual_name_limit(),
)
.at(self.section.kind, self.section.offset + self.pos));
}
self.budget.charge(Q::NameBytes, len as u64)?;
let bytes = self.take(len)?;
self.budget.work(len)?;
let value = std::str::from_utf8(bytes)
.map_err(|_| self.error(C::InvalidFormat, R::Utf8))?;
self.budget.work(len)?;
let mut storage = self.budget.vector::<u8>(len, Q::TemporaryBytes)?;
storage.extend_from_slice(value.as_bytes());
// UTF-8 was checked above; moving Vec into String performs no allocation.
Ok(Some(
String::from_utf8(storage)
.map_err(|_| self.error(C::InvalidFormat, R::Utf8))?,
))
}
_ => Err(self.error(C::InvalidFormat, R::InvalidFlag)),
}
}
fn named(&mut self) -> Result<Vec<NamedType>, E> {
let (mut out, n) = self.list(Q::NestedRecords, 5)?;
for i in 0..n {
self.budget.work(1)?;
let type_id = TypeId(self.u32()?);
let name = self.name().map_err(|e| e.member(i as u32))?;
out.push(NamedType { type_id, name });
}
Ok(out)
}
fn signature(&mut self) -> Result<Signature, E> {
let parameters = self.named()?;
let (mut results, n) = self.list(Q::NestedRecords, 4)?;
for _ in 0..n {
self.budget.work(1)?;
results.push(TypeId(self.u32()?));
}
Ok(Signature { parameters, results })
}
fn types(mut self) -> Result<Vec<TypeDecl>, E> {
let (mut out, n) = self.list(Q::Types, 6)?;
for i in 0..n {
self.budget.work(1)?;
let record = (|| {
let kind = self.byte()?;
let name = self.name()?;
let kind = match kind {
0 => TypeKind::Builtin(BuiltinId(self.u32()?)),
1 => TypeKind::Struct(self.named()?),
2 => TypeKind::Array(TypeId(self.u32()?)),
4 => TypeKind::Fn(self.signature()?),
3 => {
let (mut methods, n) = self.list(Q::NestedRecords, 9)?;
for j in 0..n {
self.budget.work(1)?;
let name = self.name()?;
let signature = self.signature().map_err(|e| e.member(j as u32))?;
methods.push(MethodDecl { name, signature });
}
TypeKind::Trait(methods)
}
_ => return Err(self.error(C::UnsupportedFormat, R::Category)),
};
Ok(TypeDecl { name, kind })
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(record);
}
self.finish()?;
Ok(out)
}
fn functions(mut self) -> Result<Vec<FunctionDecl>, E> {
let (mut out, n) = self.list(Q::Functions, 26)?;
for i in 0..n {
self.budget.work(1)?;
let f = (|| {
Ok(FunctionDecl {
lifecycle_role: LifecycleRole::try_from(self.byte()?).map_err(|e| {
e.at(1, self.section.offset + self.pos - 1).in_function(i as u32, None)
})?,
name: self.name()?,
signature: self.signature()?,
code_offset: self.u32()?,
code_len: self.u32()?,
local_slots: self.u32()?,
max_stack_slots: self.u32()?,
captures: Vec::new(),
})
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(f);
}
self.finish()?;
Ok(out)
}
fn captures(mut self, functions: &mut [FunctionDecl]) -> Result<(), E> {
let n = self.u32()? as usize;
if n != functions.len() {
let mut error = self.error(C::InvalidFormat, R::CaptureCount);
error.requested = Some(n as u64);
error.limit = Some(functions.len() as u64);
return Err(error);
}
for (i, function) in functions.iter_mut().enumerate() {
self.budget.work(1)?;
let (mut captures, n) =
self.list(Q::NestedRecords, 4).map_err(|e| e.record(i as u32))?;
for _ in 0..n {
self.budget.work(1)?;
captures.push(TypeId(self.u32()?));
}
function.captures = captures;
}
self.finish()
}
fn implementations(mut self) -> Result<Vec<ImplementationDecl>, E> {
let (mut out, n) = self.list(Q::Implementations, 12)?;
for i in 0..n {
self.budget.work(1)?;
let imp = (|| {
let owner = TypeId(self.u32()?);
let trait_id = TypeId(self.u32()?);
let (mut methods, n) = self.list(Q::NestedRecords, 4)?;
for _ in 0..n {
self.budget.work(1)?;
methods.push(FunctionId(self.u32()?));
}
Ok(ImplementationDecl { owner, trait_id, methods })
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(imp);
}
self.finish()?;
Ok(out)
}
}
/// Raw section input for a v1 envelope writer. Non-Registry section bytes must
/// come from their own validated writers; this API never invents defaults.
#[derive(Clone, Copy)]
pub struct SectionData<'a> {
pub kind: u32,
pub bytes: &'a [u8],
}
/// Assemble strict v1 sections. The output buffer is charged to temporary load storage.
pub fn encode_envelope(sections: &[SectionData<'_>], b: &mut LoadBudget) -> Result<Vec<u8>, E> {
b.transaction(|b| {
let mut by_kind = [None; 9];
for section in sections {
b.work(1)?;
if section.kind > 8 {
return Err(E::new(C::UnsupportedFormat, R::SectionKind));
}
if by_kind[section.kind as usize].replace(section.bytes).is_some() {
return Err(E::new(C::InvalidFormat, R::DuplicateSection));
}
}
for k in [0, 1, 2, 4, 5, 6, 7, 8] {
if by_kind[k].is_none() {
return Err(E::new(C::InvalidFormat, R::MissingSection).at(k as u32, 8));
}
}
b.check(Q::CodeBytes, by_kind[2].unwrap().len() as u64)?;
let count = sections.len();
let directory_end = 32 + 12 * count;
let total = sections
.iter()
.try_fold(directory_end, |n, s| n.checked_add(s.bytes.len()).ok_or_else(overflow))?;
b.check(Q::PbxBytes, total as u64)?;
b.work(total)?;
let mut out = b.vector(total, Q::TemporaryBytes)?;
out.extend_from_slice(b"PBX\0");
out.extend_from_slice(&[1, 0, 0, 0]);
out.extend_from_slice(&(count as u32).to_le_bytes());
out.extend_from_slice(&[0; 20]);
let mut offset = directory_end;
for (kind, data) in by_kind.iter().enumerate() {
if let Some(data) = data {
out.extend_from_slice(&(kind as u32).to_le_bytes());
out.extend_from_slice(&(offset as u32).to_le_bytes());
out.extend_from_slice(&(data.len() as u32).to_le_bytes());
offset += data.len();
}
}
for data in by_kind.into_iter().flatten() {
out.extend_from_slice(data);
}
Ok(out)
})
}
#[derive(Debug)]
pub struct RegistrySections {
pub types: Vec<u8>,
pub functions: Vec<u8>,
pub implementations: Vec<u8>,
pub captures: Vec<u8>,
}
/// Field-by-field serialization of already resolved Registry declarations.
/// There is no source-language inference or unsupported-value-to-null fallback.
pub fn encode_registry(registry: &Registry, b: &mut LoadBudget) -> Result<RegistrySections, E> {
b.transaction(|b| {
let d = registry.declarations();
let types = write_section(b, |w| {
w.count(d.types.len())?;
for t in &d.types {
w.byte(match t.kind {
TypeKind::Builtin(_) => 0,
TypeKind::Struct(_) => 1,
TypeKind::Array(_) => 2,
TypeKind::Trait(_) => 3,
TypeKind::Fn(_) => 4,
})?;
w.name(&t.name)?;
match &t.kind {
TypeKind::Builtin(id) => w.u32(id.0)?,
TypeKind::Struct(fields) => w.named(fields)?,
TypeKind::Array(id) => w.u32(id.0)?,
TypeKind::Fn(s) => w.signature(s)?,
TypeKind::Trait(methods) => {
w.count(methods.len())?;
for m in methods {
w.name(&m.name)?;
w.signature(&m.signature)?;
}
}
}
}
Ok(())
})?;
let functions = write_section(b, |w| {
w.count(d.functions.len())?;
for f in &d.functions {
w.byte(f.lifecycle_role as u8)?;
w.name(&f.name)?;
w.signature(&f.signature)?;
w.u32(f.code_offset)?;
w.u32(f.code_len)?;
w.u32(f.local_slots)?;
w.u32(f.max_stack_slots)?;
}
Ok(())
})?;
let implementations = write_section(b, |w| {
w.count(d.implementations.len())?;
for imp in &d.implementations {
w.u32(imp.owner.0)?;
w.u32(imp.trait_id.0)?;
w.count(imp.methods.len())?;
for id in &imp.methods {
w.u32(id.0)?;
}
}
Ok(())
})?;
let captures = write_section(b, |w| {
w.count(d.functions.len())?;
for f in &d.functions {
w.count(f.captures.len())?;
for id in &f.captures {
w.u32(id.0)?;
}
}
Ok(())
})?;
Ok(RegistrySections { types, functions, implementations, captures })
})
}
// Count first so a malicious producer cannot trigger unbounded geometric growth.
struct Writer<'a> {
out: Option<&'a mut Vec<u8>>,
len: usize,
budget: &'a mut LoadBudget,
}
impl Writer<'_> {
fn bytes(&mut self, bytes: &[u8]) -> Result<(), E> {
self.budget.work(bytes.len())?;
self.len = self.len.checked_add(bytes.len()).ok_or_else(overflow)?;
self.budget.check(Q::PbxBytes, self.len as u64)?;
if let Some(out) = self.out.as_mut() {
out.extend_from_slice(bytes);
}
Ok(())
}
fn byte(&mut self, n: u8) -> Result<(), E> {
self.bytes(&[n])
}
fn u32(&mut self, n: u32) -> Result<(), E> {
self.bytes(&n.to_le_bytes())
}
fn count(&mut self, n: usize) -> Result<(), E> {
self.u32(u32::try_from(n).map_err(|_| overflow())?)
}
fn name(&mut self, n: &Option<String>) -> Result<(), E> {
match n {
None => self.byte(0),
Some(n) => {
self.byte(1)?;
self.count(n.len())?;
self.bytes(n.as_bytes())
}
}
}
fn named(&mut self, items: &[NamedType]) -> Result<(), E> {
self.count(items.len())?;
for p in items {
self.u32(p.type_id.0)?;
self.name(&p.name)?;
}
Ok(())
}
fn signature(&mut self, s: &Signature) -> Result<(), E> {
self.named(&s.parameters)?;
self.count(s.results.len())?;
for id in &s.results {
self.u32(id.0)?;
}
Ok(())
}
}
fn write_section(
b: &mut LoadBudget,
write: impl Fn(&mut Writer<'_>) -> Result<(), E>,
) -> Result<Vec<u8>, E> {
let mut counter = Writer { out: None, len: 0, budget: b };
write(&mut counter)?;
let len = counter.len;
let mut out = b.vector(len, Q::TemporaryBytes)?;
write(&mut Writer { out: Some(&mut out), len: 0, budget: b })?;
Ok(out)
}
mod payloads;
pub use payloads::{OwnedPbx, ParsedPbx};
mod writer;
pub use writer::PbxModule;
@@ -0,0 +1,393 @@
//! Validation of unchanged non-Registry section encodings, without allocating
//! guest constants or publishing an executable image.
use super::*;
use crate::abi::SourceSpan;
use crate::load_limits::IdDomain;
use crate::model::{ConstantPoolEntry, DebugInfo, Export, SyscallDecl};
use std::cmp::Ordering;
/// Owned, bounded PBX v1 tables for the executable loader. This is not an
/// executable image: bindings and instruction/type verification are still due.
#[derive(Debug)]
pub struct OwnedPbx {
pub registry: Registry,
pub constants: Vec<ConstantPoolEntry>,
pub code: Vec<u8>,
pub debug: Option<DebugInfo>,
pub exports: Vec<Export>,
pub syscalls: Vec<SyscallDecl>,
}
impl OwnedPbx {
pub fn parse(bytes: &[u8], budget: &mut LoadBudget) -> Result<Self, E> {
budget.transaction(|budget| {
let parsed = ParsedPbx::parse(bytes, budget)?;
let constants = Reader::new(parsed.section(0).unwrap(), budget).owned_constants()?;
let exports = Reader::new(parsed.section(4).unwrap(), budget).owned_exports()?;
let syscalls = Reader::new(parsed.section(5).unwrap(), budget).owned_syscalls()?;
let debug = parsed
.section(3)
.map(|section| Reader::new(section, budget).owned_debug())
.transpose()?;
let section = parsed.section(2).unwrap();
let mut code = budget
.vector(section.bytes.len(), Q::TemporaryBytes)
.map_err(|e| e.at(2, section.offset))?;
budget.work(section.bytes.len()).map_err(|e| e.at(2, section.offset))?;
code.extend_from_slice(section.bytes);
Ok(Self { registry: parsed.registry, constants, code, debug, exports, syscalls })
})
}
}
/// All PBX tables have passed binary and reference validation. Code has NOT
/// passed instruction/type-flow verification and host calls are NOT bound.
#[derive(Debug)]
pub struct ParsedPbx<'a> {
envelope: PbxEnvelope<'a>,
registry: Registry,
}
impl<'a> ParsedPbx<'a> {
pub fn parse(bytes: &'a [u8], budget: &mut LoadBudget) -> Result<Self, E> {
budget.transaction(|budget| {
let envelope = PbxEnvelope::parse(bytes, budget)?;
let registry = envelope.resolve_registry(budget)?;
let functions = registry.declarations().functions.len();
let code_len = envelope.section(2).unwrap().bytes.len();
Reader::new(envelope.section(0).unwrap(), budget).constants()?;
Reader::new(envelope.section(4).unwrap(), budget).exports(functions)?;
Reader::new(envelope.section(5).unwrap(), budget).syscalls()?;
if let Some(debug) = envelope.section(3) {
Reader::new(debug, budget).debug(functions, code_len)?;
}
Ok(Self { envelope, registry })
})
}
pub fn registry(&self) -> &Registry {
&self.registry
}
pub fn section(&self, kind: u32) -> Option<Section<'a>> {
self.envelope.section(kind)
}
/// Re-encode validated tables in canonical directory order; debug absence is preserved.
pub fn encode(&self, budget: &mut LoadBudget) -> Result<Vec<u8>, E> {
let mut sections = [SectionData { kind: 0, bytes: &[] }; 9];
let mut count = 0;
for kind in 0..9 {
if let Some(section) = self.section(kind) {
sections[count] = SectionData { kind, bytes: section.bytes };
count += 1;
}
}
encode_envelope(&sections[..count], budget)
}
}
impl<'a> Reader<'a, '_> {
fn owned_vector<T>(&mut self, count: usize) -> Result<Vec<T>, E> {
self.budget
.vector(count, Q::TemporaryBytes)
.map_err(|e| e.at(self.section.kind, self.section.offset + self.pos))
}
fn owned_text(&mut self, len: usize) -> Result<String, E> {
let value = self.utf8(len)?;
let mut bytes = self.owned_vector(len)?;
self.budget.work(len)?;
bytes.extend_from_slice(value.as_bytes());
Ok(String::from_utf8(bytes).expect("UTF-8 checked before allocation"))
}
fn owned_constants(mut self) -> Result<Vec<ConstantPoolEntry>, E> {
let count = self.raw_count(1)?;
let mut out = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let value = (|| {
Ok(match self.byte()? {
0 => ConstantPoolEntry::Null,
1 => ConstantPoolEntry::Int64(i64::from_le_bytes(
self.take(8)?.try_into().unwrap(),
)),
2 => ConstantPoolEntry::Float64(f64::from_bits(u64::from_le_bytes(
self.take(8)?.try_into().unwrap(),
))),
3 => ConstantPoolEntry::Boolean(self.byte()? == 1),
4 => {
let len = self.u32()? as usize;
ConstantPoolEntry::String(self.owned_text(len)?)
}
5 => ConstantPoolEntry::Int32(i32::from_le_bytes(
self.take(4)?.try_into().unwrap(),
)),
_ => return Err(self.error(C::UnsupportedFormat, R::ConstantTag)),
})
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(value);
}
self.finish()?;
Ok(out)
}
fn owned_exports(mut self) -> Result<Vec<Export>, E> {
let count = self.raw_count(8)?;
let mut out = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let func_idx = self.u32()?;
let len = self.u32()? as usize;
let symbol = self.owned_text(len).map_err(|e| e.record(i as u32))?;
out.push(Export { func_idx, symbol });
}
self.finish()?;
Ok(out)
}
fn owned_syscalls(mut self) -> Result<Vec<SyscallDecl>, E> {
let count = self.raw_count(10)?;
let mut out = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let record = (|| {
let len = self.u16()? as usize;
let module = self.owned_text(len)?;
let len = self.u16()? as usize;
let name = self.owned_text(len)?;
Ok(SyscallDecl {
module,
name,
version: self.u16()?,
arg_slots: self.u16()?,
ret_slots: self.u16()?,
})
})()
.map_err(|e: E| e.record(i as u32))?;
out.push(record);
}
self.finish()?;
Ok(out)
}
fn owned_debug(mut self) -> Result<DebugInfo, E> {
let count = self.raw_count(16)?;
let mut pc_to_span = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let value = (|| {
Ok((
self.u32()?,
SourceSpan { file_id: self.u32()?, start: self.u32()?, end: self.u32()? },
))
})()
.map_err(|e: E| e.record(i as u32))?;
pc_to_span.push(value);
}
let count = self.raw_count(8)?;
let mut function_names = self.owned_vector(count)?;
for i in 0..count {
self.budget.work(1)?;
let id = self.u32()?;
let len = self.u32()? as usize;
let name = self.owned_text(len).map_err(|e| e.record(i as u32))?;
function_names.push((id, name));
}
self.finish()?;
Ok(DebugInfo { pc_to_span, function_names })
}
fn u16(&mut self) -> Result<u16, E> {
Ok(u16::from_le_bytes(self.take(2)?.try_into().unwrap()))
}
fn raw_count(&mut self, minimum: usize) -> Result<usize, E> {
let count = self.u32()? as usize;
if count.checked_mul(minimum).ok_or_else(overflow)? > self.section.bytes.len() - self.pos {
return Err(self.error(C::InvalidFormat, R::Truncated));
}
Ok(count)
}
fn utf8(&mut self, len: usize) -> Result<&'a str, E> {
let bytes = self.take(len)?;
self.budget.work(len)?;
std::str::from_utf8(bytes).map_err(|_| self.error(C::InvalidFormat, R::Utf8))
}
fn text(&mut self, len: usize) -> Result<&'a str, E> {
if len as u64 > self.budget.individual_name_limit() {
return Err(E::resource(Q::NameBytes, len as u64, self.budget.individual_name_limit())
.at(self.section.kind, self.section.offset + self.pos));
}
self.utf8(len)
}
fn function(&self, id: u32, count: usize) -> Result<(), E> {
if id as usize >= count {
Err(self.error(C::InvalidReference, R::FunctionId).reference(IdDomain::Function, id))
} else {
Ok(())
}
}
fn constants(mut self) -> Result<(), E> {
let count = self.u32()? as usize;
self.budget.charge(Q::ConstantEntries, count as u64)?;
if count > self.section.bytes.len() - self.pos {
return Err(self.error(C::InvalidFormat, R::Truncated));
}
for i in 0..count {
self.budget.work(1)?;
(|| {
match self.byte()? {
0 => {}
1 => {
self.take(8)?;
}
2 => {
let at = self.pos;
let bits = u64::from_le_bytes(self.take(8)?.try_into().unwrap());
if bits & 0x7ff0_0000_0000_0000 == 0x7ff0_0000_0000_0000 {
return Err(E::new(C::InvalidFormat, R::NonFiniteValue)
.at(self.section.kind, self.section.offset + at));
}
}
3 => {
if self.byte()? > 1 {
return Err(self.error(C::InvalidFormat, R::InvalidFlag));
}
}
4 => {
let len = self.u32()? as usize;
if len as u64 > self.budget.individual_string_limit() {
return Err(E::resource(
Q::ConstantStringBytes,
len as u64,
self.budget.individual_string_limit(),
)
.at(0, self.section.offset + self.pos));
}
self.budget.charge(Q::ConstantStringBytes, len as u64)?;
self.utf8(len)?;
}
5 => {
self.take(4)?;
}
_ => return Err(self.error(C::UnsupportedFormat, R::ConstantTag)),
}
Ok(())
})()
.map_err(|e: E| e.record(i as u32))?;
}
self.finish()
}
fn exports(mut self, functions: usize) -> Result<(), E> {
let count = self.raw_count(8)?;
for i in 0..count {
self.budget.work(1)?;
let id = self.u32()?;
self.function(id, functions).map_err(|e| e.record(i as u32))?;
let len = self.u32()? as usize;
self.text(len).map_err(|e| e.record(i as u32))?;
}
self.finish()
}
fn debug(mut self, functions: usize, code_len: usize) -> Result<(), E> {
let count = self.raw_count(16)?;
for i in 0..count {
self.budget.work(1)?;
let pc = self.u32()?;
self.u32()?; // source file ID, local to debug information
let start = self.u32()?;
let end = self.u32()?;
if pc as usize >= code_len || end < start {
return Err(self.error(C::InvalidFormat, R::DebugRange).record(i as u32));
}
}
let names = self.raw_count(8)?;
for i in 0..names {
self.budget.work(1)?;
let id = self.u32()?;
self.function(id, functions).map_err(|e| e.record(i as u32))?;
let len = self.u32()? as usize;
self.text(len).map_err(|e| e.record(i as u32))?;
}
self.finish()
}
pub(super) fn syscalls(mut self) -> Result<(), E> {
let count = self.raw_count(10)?;
let mut identities = self.budget.vector(count, Q::TemporaryBytes)?;
for i in 0..count {
self.budget.work(1)?;
let len = self.u16()? as usize;
let module = self.text(len).map_err(|e| e.record(i as u32))?;
let len = self.u16()? as usize;
let name = self.text(len).map_err(|e| e.record(i as u32))?;
let version = self.u16()?;
self.u16()?; // argument slots, unchanged SYSC encoding
self.u16()?; // result slots
identities.push((module, name, version, i as u32));
}
self.finish()?;
// Fallible heapsort bounds both auxiliary storage and comparison work;
// unlike sorting with an error flag it stops immediately at quota refusal.
fallible_sort(&mut identities, |a, b| {
let module = text_cmp(a.0, b.0, self.budget)?;
if module != Ordering::Equal {
return Ok(module);
}
let name = text_cmp(a.1, b.1, self.budget)?;
if name != Ordering::Equal {
return Ok(name);
}
self.budget.work(1)?;
Ok((a.2, a.3).cmp(&(b.2, b.3)))
})?;
for pair in identities.windows(2) {
self.budget.work(1)?;
if text_cmp(pair[0].0, pair[1].0, self.budget)? == Ordering::Equal
&& text_cmp(pair[0].1, pair[1].1, self.budget)? == Ordering::Equal
&& pair[0].2 == pair[1].2
{
return Err(self.error(C::InvalidFormat, R::DuplicateSyscall).record(pair[1].3));
}
}
self.budget.refund(
Q::TemporaryBytes,
(identities.capacity() * size_of::<(&str, &str, u16, u32)>()) as u64,
);
Ok(())
}
}
fn text_cmp(a: &str, b: &str, budget: &mut LoadBudget) -> Result<Ordering, E> {
for (a, b) in a.bytes().zip(b.bytes()) {
budget.work(2)?;
match a.cmp(&b) {
Ordering::Equal => {}
other => return Ok(other),
}
}
budget.work(1)?;
Ok(a.len().cmp(&b.len()))
}
fn fallible_sort<T>(
items: &mut [T],
mut cmp: impl FnMut(&T, &T) -> Result<Ordering, E>,
) -> Result<(), E> {
fn sift<T>(
items: &mut [T],
mut root: usize,
cmp: &mut impl FnMut(&T, &T) -> Result<Ordering, E>,
) -> Result<(), E> {
while let Some(child) =
root.checked_mul(2).and_then(|n| n.checked_add(1)).filter(|&i| i < items.len())
{
let mut child = child;
if child + 1 < items.len() && cmp(&items[child], &items[child + 1])? == Ordering::Less {
child += 1;
}
if cmp(&items[root], &items[child])? != Ordering::Less {
break;
}
items.swap(root, child);
root = child;
}
Ok(())
}
for root in (0..items.len() / 2).rev() {
sift(items, root, &mut cmp)?;
}
for end in (1..items.len()).rev() {
items.swap(0, end);
sift(&mut items[..end], 0, &mut cmp)?;
}
Ok(())
}
@@ -0,0 +1,196 @@
//! Producer-side serialization of a complete typed module. This writer emits
//! only v1; executable consumers still need bindings and code verification.
use super::*;
use crate::load_limits::IdDomain;
use crate::model::{ConstantPoolEntry, DebugInfo, Export, SyscallDecl};
/// Borrowed producer data with already resolved Registry declarations. There
/// is no version selector, inferred signature or generic Value-to-null path.
pub struct PbxModule<'a> {
pub registry: &'a Registry,
pub constants: &'a [ConstantPoolEntry],
pub code: &'a [u8],
pub debug: Option<&'a DebugInfo>,
pub exports: &'a [Export],
pub syscalls: &'a [SyscallDecl],
}
impl PbxModule<'_> {
/// All intermediate sections coexist with the final output and are charged
/// until dropped. On success only the returned Vec capacity remains charged.
pub fn serialize(&self, budget: &mut LoadBudget) -> Result<Vec<u8>, E> {
budget.transaction(|budget| {
let temporary_before = budget.used(Q::TemporaryBytes);
budget.check(Q::CodeBytes, self.code.len() as u64)?;
for (id, function) in self.registry.declarations().functions.iter().enumerate() {
budget.work(1)?;
if u64::from(function.code_offset) + u64::from(function.code_len)
> self.code.len() as u64
{
return Err(E::new(C::InvalidCode, R::CodeRange)
.in_section(2)
.in_function(id as u32, Some(function.code_offset)));
}
}
let registry = encode_registry(self.registry, budget)?;
let constants = write_section(budget, |w| self.write_constants(w))?;
let exports = write_section(budget, |w| self.write_exports(w))?;
let syscalls = write_section(budget, |w| self.write_syscalls(w))?;
// Reuse the bounded identity validator; do not introduce a second
// native-binding catalog or an unbounded duplicate search.
Reader::new(Section { kind: 5, offset: 0, bytes: &syscalls }, budget).syscalls()?;
let debug = self
.debug
.map(|di| write_section(budget, |w| self.write_debug(di, w)))
.transpose()?;
let mut sections = [SectionData { kind: 0, bytes: &[] }; 9];
let mut count = 0;
for (kind, bytes) in [
(0, Some(constants.as_slice())),
(1, Some(registry.functions.as_slice())),
(2, Some(self.code)),
(3, debug.as_deref()),
(4, Some(exports.as_slice())),
(5, Some(syscalls.as_slice())),
(6, Some(registry.types.as_slice())),
(7, Some(registry.implementations.as_slice())),
(8, Some(registry.captures.as_slice())),
] {
if let Some(bytes) = bytes {
sections[count] = SectionData { kind, bytes };
count += 1;
}
}
let out = encode_envelope(&sections[..count], budget)?;
// The borrowed section array and all owned intermediate Vecs die
// before return. Preserve prior scratch plus returned output only.
let retained = out.capacity() as u64;
drop(debug);
drop(syscalls);
drop(exports);
drop(constants);
drop(registry);
budget.refund(
Q::TemporaryBytes,
budget.used(Q::TemporaryBytes) - temporary_before - retained,
);
Ok(out)
})
}
fn write_constants(&self, w: &mut Writer<'_>) -> Result<(), E> {
w.budget.check(Q::ConstantEntries, self.constants.len() as u64)?;
w.count(self.constants.len())?;
let mut string_bytes = 0u64;
for (id, entry) in self.constants.iter().enumerate() {
w.budget.work(1)?;
match entry {
ConstantPoolEntry::Null => w.byte(0)?,
ConstantPoolEntry::Int64(value) => {
w.byte(1)?;
w.bytes(&value.to_le_bytes())?;
}
ConstantPoolEntry::Float64(value) => {
w.byte(2)?;
w.bytes(&value.to_bits().to_le_bytes())?;
}
ConstantPoolEntry::Boolean(value) => {
w.byte(3)?;
w.byte(u8::from(*value))?;
}
ConstantPoolEntry::String(value) => {
if value.len() as u64 > w.budget.individual_string_limit() {
return Err(E::resource(
Q::ConstantStringBytes,
value.len() as u64,
w.budget.individual_string_limit(),
)
.in_section(0)
.record(id as u32));
}
string_bytes =
string_bytes.checked_add(value.len() as u64).ok_or_else(overflow)?;
w.budget.check(Q::ConstantStringBytes, string_bytes)?;
w.byte(4)?;
w.count(value.len())?;
w.bytes(value.as_bytes())?;
}
ConstantPoolEntry::Int32(value) => {
w.byte(5)?;
w.bytes(&value.to_le_bytes())?;
}
}
}
Ok(())
}
fn check_function(&self, id: u32) -> Result<(), E> {
if id as usize >= self.registry.declarations().functions.len() {
Err(E::new(C::InvalidReference, R::FunctionId).reference(IdDomain::Function, id))
} else {
Ok(())
}
}
fn write_exports(&self, w: &mut Writer<'_>) -> Result<(), E> {
w.count(self.exports.len())?;
for (record, export) in self.exports.iter().enumerate() {
w.budget.work(1)?;
self.check_function(export.func_idx)
.map_err(|e| e.in_section(4).record(record as u32))?;
w.u32(export.func_idx)?;
w.text(&export.symbol, 4)?;
}
Ok(())
}
fn write_syscalls(&self, w: &mut Writer<'_>) -> Result<(), E> {
w.count(self.syscalls.len())?;
for syscall in self.syscalls {
w.budget.work(1)?;
w.text(&syscall.module, 2)?;
w.text(&syscall.name, 2)?;
w.bytes(&syscall.version.to_le_bytes())?;
w.bytes(&syscall.arg_slots.to_le_bytes())?;
w.bytes(&syscall.ret_slots.to_le_bytes())?;
}
Ok(())
}
fn write_debug(&self, debug: &DebugInfo, w: &mut Writer<'_>) -> Result<(), E> {
w.count(debug.pc_to_span.len())?;
for (record, (pc, span)) in debug.pc_to_span.iter().enumerate() {
w.budget.work(1)?;
if *pc as usize >= self.code.len() || span.end < span.start {
return Err(E::new(C::InvalidFormat, R::DebugRange)
.in_section(3)
.record(record as u32));
}
w.u32(*pc)?;
w.u32(span.file_id)?;
w.u32(span.start)?;
w.u32(span.end)?;
}
w.count(debug.function_names.len())?;
for (record, (id, name)) in debug.function_names.iter().enumerate() {
w.budget.work(1)?;
self.check_function(*id).map_err(|e| e.in_section(3).record(record as u32))?;
w.u32(*id)?;
w.text(name, 4)?;
}
Ok(())
}
}
impl Writer<'_> {
fn text(&mut self, value: &str, length_bytes: usize) -> Result<(), E> {
if value.len() as u64 > self.budget.individual_name_limit() {
return Err(E::resource(
Q::NameBytes,
value.len() as u64,
self.budget.individual_name_limit(),
));
}
if length_bytes == 2 {
self.bytes(&u16::try_from(value.len()).map_err(|_| overflow())?.to_le_bytes())?;
} else {
self.count(value.len())?;
}
self.bytes(value.as_bytes())
}
}
@@ -0,0 +1,180 @@
//! Registry-aware immediate validation and slot effects for typed instructions.
use crate::decoder::DecodedInstr;
use crate::isa::core::{CoreOpCode as Op, CoreOpCodeSpecExt};
use crate::load_limits::{IdDomain, LoadCode, LoadFailure, LoadReason};
use crate::registry::{FunctionId, Registry, TypeId, TypeKind};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RegistryStackEffect {
pub pops: u32,
pub pushes: u32,
}
impl DecodedInstr<'_> {
/// Capture effects require the enclosing function's resolved environment.
pub fn registry_stack_effect_in(
&self,
registry: &Registry,
function: FunctionId,
) -> Result<Option<RegistryStackEffect>, LoadFailure> {
if self.opcode == Op::GetCapture {
let index = self
.imm_u32()
.map_err(|_| LoadFailure::new(LoadCode::InvalidCode, LoadReason::Truncated))?;
let capture = registry
.function_layout(function)
.and_then(|f| f.captures.get(index as usize))
.ok_or_else(|| {
LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex)
.member(index)
})?;
return Ok(Some(RegistryStackEffect { pops: 0, pushes: capture.slots }));
}
self.registry_stack_effect(registry)
}
/// Resolve an instruction's exact group widths and check immediate domains.
/// None means this is not a Registry instruction, not a zero stack effect.
/// This does not prove that the values on the stack satisfy the signature.
pub fn registry_stack_effect(
&self,
registry: &Registry,
) -> Result<Option<RegistryStackEffect>, LoadFailure> {
if !self.opcode.requires_registry() {
return Ok(None);
}
let malformed = || {
let mut e = LoadFailure::new(LoadCode::InvalidCode, LoadReason::Truncated);
e.pc = u32::try_from(self.pc).ok();
e
};
let type_info = |id: u32| {
let decl = registry.declarations().types.get(id as usize);
let layout = registry.type_layout(TypeId(id));
decl.zip(layout).ok_or_else(|| {
let mut e = LoadFailure::new(LoadCode::InvalidReference, LoadReason::TypeId)
.reference(IdDomain::Type, id);
e.pc = u32::try_from(self.pc).ok();
e
})
};
let bad_category = |id: u32| {
let mut e = LoadFailure::new(LoadCode::InvalidReference, LoadReason::Category)
.reference(IdDomain::Type, id);
e.pc = u32::try_from(self.pc).ok();
e
};
let (pops, pushes) = match self.opcode {
Op::MakeClosure => {
let (function, ty) = self.imm_u32x2().map_err(|_| malformed())?;
let (_, layout) = type_info(ty)?;
if layout.callable.is_none() {
return Err(bad_category(ty));
}
let target = registry.function_layout(FunctionId(function)).ok_or_else(|| {
LoadFailure::new(LoadCode::InvalidReference, LoadReason::FunctionId)
.reference(IdDomain::Function, function)
})?;
(target.capture_slots, 1)
}
Op::CallClosure => {
let ty = self.imm_u32().map_err(|_| malformed())?;
let (_, layout) = type_info(ty)?;
let signature = layout.callable.as_ref().ok_or_else(|| bad_category(ty))?;
(
signature.parameter_slots.checked_add(1).ok_or_else(malformed)?,
signature.result_slots,
)
}
Op::GetCapture => {
return Err(LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex))
}
Op::CallTrait => {
let (ty, method) = self.imm_u32x2().map_err(|_| malformed())?;
let (_, layout) = type_info(ty)?;
let signature = layout
.methods
.get(method as usize)
.ok_or_else(|| bad_category(ty).member(method))?;
(
signature.parameter_slots.checked_add(2).ok_or_else(malformed)?,
signature.result_slots,
)
}
Op::DynPack | Op::DynUnpack | Op::DynCanUnpack => {
let id = self.imm_u32().map_err(|_| malformed())?;
let (_, layout) = type_info(id)?;
match self.opcode {
Op::DynPack => (layout.storage.slots, 2),
Op::DynUnpack => (2, layout.storage.slots),
_ => (2, 1),
}
}
Op::RefIsExact | Op::RefImplements | Op::RefToTrait | Op::RefCast => {
let (source, target) = self.imm_u32x2().map_err(|_| malformed())?;
let (source_decl, source_layout) = type_info(source)?;
let (target_decl, target_layout) = type_info(target)?;
if !matches!(
source_decl.kind,
TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Trait(_)
) {
return Err(bad_category(source));
}
let trait_target = matches!(self.opcode, Op::RefImplements | Op::RefToTrait);
if (trait_target && !matches!(target_decl.kind, TypeKind::Trait(_)))
|| (!trait_target
&& !matches!(target_decl.kind, TypeKind::Struct(_) | TypeKind::Array(_)))
{
return Err(bad_category(target));
}
let pushes = if matches!(self.opcode, Op::RefIsExact | Op::RefImplements) {
1
} else {
target_layout.storage.slots
};
(source_layout.storage.slots, pushes)
}
Op::StructNew
| Op::StructGet
| Op::StructSet
| Op::ArrayNew
| Op::ArrayLen
| Op::ArrayGet
| Op::ArraySet => {
let (id, field) = if matches!(self.opcode, Op::StructGet | Op::StructSet) {
self.imm_u32x2().map_err(|_| malformed())?
} else {
(self.imm_u32().map_err(|_| malformed())?, 0)
};
let (_, layout) = type_info(id)?;
if matches!(self.opcode, Op::StructNew | Op::StructGet | Op::StructSet) {
let instance = layout.instance.as_ref().ok_or_else(|| bad_category(id))?;
match self.opcode {
Op::StructNew => (0, 1),
op => {
let f = instance
.fields
.get(field as usize)
.ok_or_else(|| bad_category(id).member(field))?;
let w = registry.type_layout(f.type_id).unwrap().storage.slots;
if op == Op::StructGet {
(1, w)
} else {
(1 + w, 0)
}
}
}
} else {
let array = layout.array.as_ref().ok_or_else(|| bad_category(id))?;
let w = registry.type_layout(array.element_type_id).unwrap().storage.slots;
match self.opcode {
Op::ArrayNew | Op::ArrayLen => (1, 1),
Op::ArrayGet => (2, w),
_ => (2 + w, 0),
}
}
}
_ => unreachable!("requires_registry is defined by the typed opcode catalogue"),
};
Ok(Some(RegistryStackEffect { pops, pushes }))
}
}
@@ -0,0 +1,40 @@
//! Resource fault context shared by the VM, native boundary and host tooling.
//! Accounting and product ceilings remain owned by the runtime budget.
use serde::{Deserialize, Serialize};
use std::fmt;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[repr(usize)]
pub enum RuntimeResource {
GuestBytes,
HandleSlots,
AuxiliaryBytes,
TemporaryBytes,
StringBytes,
StringAllocations,
IndividualStringBytes,
CallDepth,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ResourceReason {
Limit,
SizeOverflow,
AllocationFailed,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResourceFailure {
pub resource: RuntimeResource,
pub reason: ResourceReason,
pub requested: u64,
pub limit: u64,
}
impl fmt::Display for ResourceFailure {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"{:?}: {:?}, requested {}, limit {}",
self.resource, self.reason, self.requested, self.limit
)
}
}
impl std::error::Error for ResourceFailure {}
+32 -26
View File
@@ -1,7 +1,6 @@
use serde::{Deserialize, Serialize};
use std::cell::Cell;
use std::cmp::Ordering;
use std::fmt::Write;
use std::sync::Arc;
thread_local! {
@@ -10,17 +9,28 @@ thread_local! {
/// Opaque handle that references an object stored in the VM heap.
///
/// This is an index-based handle. It does not imply ownership and carries
/// no lifetime information. GC/allocator integration will come in later PRs.
/// Handles belong to the heap/session that issued them. Native boundaries must
/// preserve that provenance. Generation zero is reserved; compact null is (0, 0).
#[repr(C, align(8))]
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)]
pub struct HeapRef(pub u32);
pub struct HeapRef {
pub index: u32,
pub generation: u32,
}
impl HeapRef {
pub const NULL: Self = Self { index: 0, generation: 0 };
pub const fn is_null(self) -> bool {
self.index == 0 && self.generation == 0
}
}
/// Represents any piece of data that can be stored on the VM stack or in globals.
///
/// The PVM is "dynamically typed" at the bytecode level, meaning a single
/// `Value` enum can hold different primitive types. The VM performs
/// automatic type promotion (e.g., adding an Int32 to a Float64 results
/// in a Float64) to ensure mathematical correctness.
/// This enum is a physical carrier, not a semantic type declaration. Registry
/// boundaries validate exact types and complete multi-slot groups. Arithmetic
/// instructions may have their own numeric promotion rules; those rules do not
/// authorize implicit conversions at typed storage or call boundaries.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum Value {
@@ -108,24 +118,20 @@ impl Value {
}
pub fn append_to_string(&self, out: &mut String) {
self.write_text(out).expect("writing into String is infallible");
}
/// Writes existing Value text without allocating a String, so bounded
/// callers can measure and reserve with their own fmt::Write sink.
pub fn write_text(&self, out: &mut impl std::fmt::Write) -> std::fmt::Result {
match self {
Value::Int32(i) => {
let _ = write!(out, "{}", i);
}
Value::Int64(i) => {
let _ = write!(out, "{}", i);
}
Value::Float(f) => {
let _ = write!(out, "{}", f);
}
Value::Boolean(b) => {
let _ = write!(out, "{}", b);
}
Value::String(s) => out.push_str(s),
Value::HeapRef(r) => {
let _ = write!(out, "[HeapRef {}]", r.0);
}
Value::Null => out.push_str("null"),
Value::Int32(i) => write!(out, "{}", i),
Value::Int64(i) => write!(out, "{}", i),
Value::Float(f) => write!(out, "{}", f),
Value::Boolean(b) => write!(out, "{}", b),
Value::String(s) => out.write_str(s),
Value::HeapRef(r) => write!(out, "[HeapRef {}:{}]", r.index, r.generation),
Value::Null => out.write_str("null"),
}
}
@@ -138,7 +144,7 @@ impl Value {
Value::Int32(i) => i.to_string().len(),
Value::Int64(i) => i.to_string().len(),
Value::Float(f) => f.to_string().len(),
Value::HeapRef(r) => 11 + r.0.to_string().len(),
Value::HeapRef(r) => 11 + r.index.to_string().len() + r.generation.to_string().len(),
}
}
@@ -9,7 +9,7 @@ fn emit(op: CoreOpCode, imm: Option<&[u8]>, out: &mut Vec<u8>) {
}
#[test]
fn roundtrip_disasm_assemble_byte_equal_with_closures_and_coroutines() {
fn roundtrip_disasm_assemble_byte_equal_with_typed_callables() {
// Program: PUSH_I32 7; MAKE_CLOSURE fn=1,captures=0; CALL_CLOSURE argc=1;
// SPAWN fn=2,argc=1; YIELD; SLEEP 3; HOSTCALL 2; SYSCALL 0x1003; FRAME_SYNC; HALT
let mut prog = Vec::new();
@@ -22,15 +22,9 @@ fn roundtrip_disasm_assemble_byte_equal_with_closures_and_coroutines() {
emit(CoreOpCode::MakeClosure, Some(&mc), &mut prog);
// CALL_CLOSURE argc=1
emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog);
// SPAWN (fn=2, argc=1)
let mut sp = [0u8; 8];
sp[0..4].copy_from_slice(&2u32.to_le_bytes());
sp[4..8].copy_from_slice(&1u32.to_le_bytes());
emit(CoreOpCode::Spawn, Some(&sp), &mut prog);
// YIELD
emit(CoreOpCode::Yield, None, &mut prog);
// SLEEP 3
emit(CoreOpCode::Sleep, Some(&3u32.to_le_bytes()), &mut prog);
emit(CoreOpCode::GetCapture, Some(&0u32.to_le_bytes()), &mut prog);
let trait_call = [7u32.to_le_bytes(), 0u32.to_le_bytes()].concat();
emit(CoreOpCode::CallTrait, Some(&trait_call), &mut prog);
// HOSTCALL sysc[2]
emit(CoreOpCode::Hostcall, Some(&2u32.to_le_bytes()), &mut prog);
// SYSCALL gfx2d.draw_line (0x1003)
@@ -17,7 +17,7 @@ fn snapshot_representative_program_is_stable() {
mc[0..4].copy_from_slice(&1u32.to_le_bytes());
mc[4..8].copy_from_slice(&0u32.to_le_bytes());
emit(CoreOpCode::MakeClosure, Some(&mc), &mut prog);
// CALL_CLOSURE argc=1
// CALL_CLOSURE 1
emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog);
// SPAWN (fn=2, argc=1)
let mut sp = [0u8; 8];
@@ -38,6 +38,6 @@ fn snapshot_representative_program_is_stable() {
emit(CoreOpCode::Halt, None, &mut prog);
let text = disassemble(&prog).expect("disasm ok");
let expected = "PUSH_I32 7\nMAKE_CLOSURE fn=1, captures=0\nCALL_CLOSURE argc=1\nSPAWN fn=2, argc=1\nYIELD\nSLEEP 3\nHOSTCALL 2\nSYSCALL 0x1003\nFRAME_SYNC\nHALT";
let expected = "PUSH_I32 7\nMAKE_CLOSURE fn=1, type=0\nCALL_CLOSURE 1\nSPAWN fn=2, argc=1\nYIELD\nSLEEP 3\nHOSTCALL 2\nSYSCALL 0x1003\nFRAME_SYNC\nHALT";
assert_eq!(text, expected);
}
@@ -0,0 +1,206 @@
use prometeu_bytecode::isa::core::{CoreOpCode as Op, CoreOpCodeSpecExt};
use prometeu_bytecode::load_limits::{LoadBudget, LoadCode, LoadLimits, LoadReason};
use prometeu_bytecode::registry::*;
use prometeu_bytecode::{assemble, decode_next, disassemble, DecodeError, RegistryStackEffect};
fn registry() -> Registry {
let types = vec![
TypeKind::Builtin(BuiltinId::INT32),
TypeKind::Builtin(BuiltinId::VEC2),
TypeKind::Builtin(BuiltinId::PIXEL),
TypeKind::Builtin(BuiltinId::DYNAMIC),
TypeKind::Struct(vec![]),
TypeKind::Array(TypeId(0)),
TypeKind::Trait(vec![]),
]
.into_iter()
.map(|kind| TypeDecl { name: None, kind })
.collect();
Registry::resolve(
RegistryDeclarations { types, ..Default::default() },
0,
&mut LoadBudget::new(LoadLimits::default()),
)
.unwrap()
}
#[test]
fn all_typed_instructions_match_independent_bytes_and_costs() {
let cases: &[(&str, &[u8], u64)] = &[
("DYN_PACK 16909060", &[0x90, 0, 4, 3, 2, 1], 8),
("DYN_UNPACK 16909060", &[0x91, 0, 4, 3, 2, 1], 4),
("DYN_CAN_UNPACK 16909060", &[0x92, 0, 4, 3, 2, 1], 3),
("REF_IS_EXACT source=16909060, target=84281096", &[0x93, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
("REF_IMPLEMENTS source=16909060, target=84281096", &[0x94, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
("REF_TO_TRAIT source=16909060, target=84281096", &[0x95, 0, 4, 3, 2, 1, 8, 7, 6, 5], 5),
("REF_CAST source=16909060, target=84281096", &[0x96, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
];
for &(text, bytes, cycles) in cases {
assert_eq!(assemble(text).unwrap(), bytes);
assert_eq!(disassemble(bytes).unwrap(), text);
let decoded = decode_next(0, bytes).unwrap();
assert_eq!(decoded.next_pc, bytes.len());
assert_eq!(decoded.opcode.cycles(), cycles);
assert_eq!(decoded.opcode.spec().pops, None);
assert_eq!(decoded.opcode.spec().pushes, None);
assert!(decoded.opcode.requires_registry());
for n in 0..bytes.len() {
assert!(decode_next(0, &bytes[..n]).is_err(), "{text}, prefix {n}");
}
}
assert!(matches!(
decode_next(0, &[0x97, 0]),
Err(DecodeError::UnknownOpcode { opcode: 0x97, .. })
));
}
#[test]
fn slot_effects_resolve_semantic_widths_and_reference_categories() {
let registry = registry();
for (text, pops, pushes) in [
("DYN_PACK 0", 1, 2),
("DYN_PACK 1", 2, 2),
("DYN_PACK 2", 3, 2),
("DYN_PACK 3", 2, 2),
("DYN_UNPACK 2", 2, 3),
("DYN_CAN_UNPACK 2", 2, 1),
("REF_IS_EXACT source=6, target=4", 2, 1),
("REF_IMPLEMENTS source=5, target=6", 1, 1),
("REF_TO_TRAIT source=4, target=6", 1, 2),
("REF_TO_TRAIT source=6, target=6", 2, 2),
("REF_CAST source=6, target=4", 2, 1),
] {
let bytes = assemble(text).unwrap();
assert_eq!(
decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap(),
Some(RegistryStackEffect { pops, pushes }),
"{text}"
);
}
assert_eq!(decode_next(0, &[0, 0]).unwrap().registry_stack_effect(&registry).unwrap(), None);
}
#[test]
fn invalid_type_immediates_are_contextual_load_errors() {
let registry = registry();
for text in ["DYN_PACK 7", "DYN_UNPACK 4294967295", "REF_CAST source=7, target=4"] {
let bytes = assemble(text).unwrap();
let e = decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap_err();
assert_eq!(
(e.code, e.reason, e.pc),
(LoadCode::InvalidReference, LoadReason::TypeId, Some(0))
);
}
for text in [
"REF_CAST source=3, target=4",
"REF_IS_EXACT source=4, target=6",
"REF_TO_TRAIT source=4, target=0",
"REF_IMPLEMENTS source=0, target=6",
] {
let bytes = assemble(text).unwrap();
let e = decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap_err();
assert_eq!(
(e.code, e.reason),
(LoadCode::InvalidReference, LoadReason::Category),
"{text}"
);
}
}
#[test]
fn assembler_rejects_missing_overflowing_or_ambiguous_type_ids() {
for text in [
"DYN_PACK",
"DYN_PACK -1",
"DYN_PACK 4294967296",
"DYN_PACK 1 2",
"REF_CAST source=4",
"REF_CAST source=4, target=5, target=6",
"REF_CAST source=4, trait=6",
] {
assert!(assemble(text).is_err(), "{text}");
}
}
#[test]
fn decoder_extreme_pc_does_not_overflow() {
assert!(matches!(
decode_next(usize::MAX, &[]),
Err(DecodeError::TruncatedOpcode { pc: usize::MAX })
));
assert_eq!(Op::DynPack as u16, 0x0090);
}
#[test]
fn collection_literal_encodings_roundtrip_and_reject_every_truncation() {
for (text, bytes, base) in [
("STRUCT_NEW 16909060", vec![0xa0, 0, 4, 3, 2, 1], 8),
("STRUCT_GET type=16909060, field=84281096", vec![0xa1, 0, 4, 3, 2, 1, 8, 7, 6, 5], 3),
("STRUCT_SET type=16909060, field=84281096", vec![0xa2, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
("ARRAY_NEW 16909060", vec![0xa3, 0, 4, 3, 2, 1], 8),
("ARRAY_LEN 16909060", vec![0xa4, 0, 4, 3, 2, 1], 3),
("ARRAY_GET 16909060", vec![0xa5, 0, 4, 3, 2, 1], 3),
("ARRAY_SET 16909060", vec![0xa6, 0, 4, 3, 2, 1], 4),
] {
assert_eq!(assemble(text).unwrap(), bytes);
assert_eq!(disassemble(&bytes).unwrap(), text);
let op = decode_next(0, &bytes).unwrap().opcode;
assert_eq!(op.cycles(), base);
assert!(op.requires_registry() && op.spec().may_trap);
assert!(!op.spec().is_safepoint && !op.spec().is_branch && !op.spec().is_terminator);
for n in 0..bytes.len() {
assert!(decode_next(0, &bytes[..n]).is_err());
}
}
for bad in [
"STRUCT_NEW",
"ARRAY_NEW -1",
"ARRAY_GET 4294967296",
"ARRAY_LEN 1 2",
"STRUCT_GET type=1",
"STRUCT_SET type=1, field=2, field=3",
"STRUCT_GET type=1, field=-1",
] {
assert!(assemble(bad).is_err(), "{bad}");
}
}
#[test]
fn collection_effects_and_cached_initialization_width_are_exact() {
let d = RegistryDeclarations {
types: vec![
TypeDecl { name: None, kind: TypeKind::Builtin(BuiltinId::PIXEL) },
TypeDecl {
name: None,
kind: TypeKind::Struct(vec![
NamedType { type_id: TypeId(0), name: None },
NamedType { type_id: TypeId(1), name: None },
]),
},
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
],
..Default::default()
};
let r = Registry::resolve(d, 0, &mut LoadBudget::new(Default::default())).unwrap();
assert_eq!(
r.type_layout(TypeId(1)).unwrap().instance.as_ref().unwrap().initialization_slots,
4
);
for (s, pops, pushes) in [
("STRUCT_NEW 1", 0, 1),
("STRUCT_GET type=1, field=0", 1, 3),
("STRUCT_SET type=1, field=0", 4, 0),
("ARRAY_NEW 2", 1, 1),
("ARRAY_LEN 2", 1, 1),
("ARRAY_GET 2", 2, 3),
("ARRAY_SET 2", 5, 0),
] {
let code = assemble(s).unwrap();
assert_eq!(
decode_next(0, &code).unwrap().registry_stack_effect(&r).unwrap(),
Some(RegistryStackEffect { pops, pushes })
);
}
for s in ["STRUCT_NEW 0", "ARRAY_NEW 1", "STRUCT_GET type=1, field=2", "ARRAY_GET 99"] {
let code = assemble(s).unwrap();
assert_eq!(
decode_next(0, &code).unwrap().registry_stack_effect(&r).unwrap_err().code,
LoadCode::InvalidReference
);
}
}
File diff suppressed because it is too large Load Diff
+101 -235
View File
@@ -1,4 +1,6 @@
#![allow(clippy::collapsible_if)]
mod decode;
mod resumable;
use crate::memory_banks::{GlyphBankPoolInstaller, SceneBankPoolInstaller, SoundBankPoolInstaller};
use prometeu_hal::AssetBridge;
use prometeu_hal::asset::{
@@ -340,6 +342,8 @@ pub struct AssetManager {
// Commits that are ready to be applied at the next frame boundary.
pending_commits: Mutex<Vec<(HandleId, u64)>>,
preload_handles: Mutex<Vec<HandleId>>,
preload_failed: std::sync::atomic::AtomicBool,
}
struct LoadHandleInfo {
@@ -374,6 +378,7 @@ struct AssetLoadQueueState {
pending: VecDeque<AssetLoadJob>,
active: Option<AssetLoadJob>,
shutdown: bool,
scheduled: bool,
}
#[derive(Default)]
@@ -470,6 +475,7 @@ impl AssetLoadQueue {
struct AssetLoadWorker {
queue: Arc<AssetLoadQueue>,
join_handle: Option<thread::JoinHandle<()>>,
shared: Option<(Arc<dyn prometeu_hal::background_work::BackgroundWork>, resumable::Resources)>,
}
impl AssetLoadWorker {
@@ -500,11 +506,15 @@ impl AssetLoadWorker {
}
});
Self { queue, join_handle: Some(join_handle) }
Self { queue, join_handle: Some(join_handle), shared: None }
}
fn submit_counting_superseded(&self, job: AssetLoadJob) -> usize {
self.queue.submit(job)
let removed = self.queue.submit(job);
if let Some((lane, resources)) = &self.shared {
resumable::schedule(self.queue.clone(), lane.clone(), resources.clone());
}
removed
}
fn clear_pending(&self) {
@@ -544,6 +554,25 @@ enum AssetOpMode {
}
impl AssetBridge for AssetManager {
fn bind_background_work(
&mut self,
lane: Arc<dyn prometeu_hal::background_work::BackgroundWork>,
) -> bool {
if self.load_worker.shared.as_ref().is_some_and(|(bound, _)| Arc::ptr_eq(bound, &lane)) {
return true;
}
// Bind only before loading: replacing an active worker could block the main lane.
if self.load_worker.pending_count() != 0 || self.load_worker.active_job().is_some() {
return false;
}
let resources = resumable::Resources::new(self);
self.load_worker = AssetLoadWorker {
queue: Arc::new(AssetLoadQueue::default()),
join_handle: None,
shared: Some((lane, resources)),
};
true
}
fn initialize_for_cartridge(
&self,
assets: Vec<AssetEntry>,
@@ -552,6 +581,12 @@ impl AssetBridge for AssetManager {
) {
self.initialize_for_cartridge(assets, preload, assets_data)
}
fn preloads_ready(&self) -> Result<bool, AssetLoadError> {
if self.preload_failed.load(std::sync::atomic::Ordering::Acquire) {
return Err(AssetLoadError::BackendError);
}
Ok(self.preload_handles.lock().unwrap().is_empty())
}
fn load(&self, asset_id: AssetId, slot_index: usize) -> Result<HandleId, AssetLoadError> {
self.load(asset_id, slot_index)
}
@@ -600,62 +635,13 @@ impl AssetManager {
fn decode_glyph_bank_layout(
entry: &AssetEntry,
) -> Result<(TileSize, usize, usize, usize, usize, usize), String> {
let meta = entry.metadata_as_glyph_bank()?;
let tile_size = match meta.tile_size {
8 => TileSize::Size8,
16 => TileSize::Size16,
32 => TileSize::Size32,
_ => return Err(format!("Invalid tile_size: {}", meta.tile_size)),
};
let palette_count = meta.palette_count as usize;
if !(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count) {
return Err(format!("Invalid palette_count: {}", meta.palette_count));
}
let width = meta.width as usize;
let height = meta.height as usize;
let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?;
let serialized_pixel_bytes = logical_pixels.div_ceil(2);
let palette_bytes = palette_count
.checked_mul(GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
.ok_or("GlyphBank palette size overflow")?;
let serialized_size = serialized_pixel_bytes
.checked_add(palette_bytes)
.ok_or("GlyphBank serialized size overflow")?;
let decoded_size =
logical_pixels.checked_add(palette_bytes).ok_or("GlyphBank decoded size overflow")?;
if entry.size != serialized_size as u64 {
return Err(format!(
"Invalid GLYPHBANK serialized size: expected {}, got {}",
serialized_size, entry.size
));
}
if entry.decoded_size != decoded_size as u64 {
return Err(format!(
"Invalid GLYPHBANK decoded_size: expected {}, got {}",
decoded_size, entry.decoded_size
));
}
Ok((tile_size, width, height, serialized_pixel_bytes, palette_count, palette_bytes))
decode::glyph_layout(entry)
}
fn unpack_glyph_bank_pixels(packed_pixels: &[u8], logical_pixels: usize) -> Vec<u8> {
let mut pixel_indices = Vec::with_capacity(logical_pixels);
for &packed in packed_pixels {
if pixel_indices.len() < logical_pixels {
pixel_indices.push(packed >> 4);
}
if pixel_indices.len() < logical_pixels {
pixel_indices.push(packed & 0x0f);
}
}
pixel_indices
let mut pixels = Vec::with_capacity(logical_pixels);
decode::append_pixels(&mut pixels, packed_pixels, logical_pixels);
pixels
}
fn op_mode_for(entry: &AssetEntry) -> Result<AssetOpMode, String> {
@@ -715,6 +701,8 @@ impl AssetManager {
pipeline_telemetry,
load_worker,
pending_commits: Mutex::new(Vec::new()),
preload_handles: Mutex::new(Vec::new()),
preload_failed: std::sync::atomic::AtomicBool::new(false),
}
}
@@ -734,7 +722,16 @@ impl AssetManager {
}
*self.assets_data.write().unwrap() = assets_data;
// Perform Preload for assets in the preload list
if self.load_worker.shared.is_some() {
for item in preload {
match self.load(item.asset_id, item.slot) {
Ok(handle) => self.preload_handles.lock().unwrap().push(handle),
Err(_) => self.preload_failed.store(true, std::sync::atomic::Ordering::SeqCst),
}
}
return;
}
// Standalone bridges retain their synchronous preload compatibility path.
for item in preload {
let entry_opt = {
let assets = self.assets.read().unwrap();
@@ -1215,17 +1212,7 @@ impl AssetManager {
let palette_data = &buffer[packed_pixel_bytes..packed_pixel_bytes + palette_bytes];
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
for (p, pal) in palettes.iter_mut().enumerate() {
for (c, slot) in pal.iter_mut().enumerate() {
let offset = (p * 16 + c) * 4;
*slot = Color::rgba(
palette_data[offset],
palette_data[offset + 1],
palette_data[offset + 2],
palette_data[offset + 3],
);
}
}
decode::write_palettes(&mut palettes, 0, palette_data);
Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes })
}
@@ -1250,17 +1237,7 @@ impl AssetManager {
.map_err(|_| "Buffer too small for GLYPHBANK".to_string())?;
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
for (p, pal) in palettes.iter_mut().enumerate() {
for (c, slot) in pal.iter_mut().enumerate() {
let offset = (p * 16 + c) * 4;
*slot = Color::rgba(
palette_data[offset],
palette_data[offset + 1],
palette_data[offset + 2],
palette_data[offset + 3],
);
}
}
decode::write_palettes(&mut palettes, 0, &palette_data);
Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes })
}
@@ -1295,7 +1272,7 @@ impl AssetManager {
entry: &AssetEntry,
assets_data: Arc<RwLock<AssetsPayloadSource>>,
) -> Result<SceneBank, String> {
let _ = entry.metadata_as_scene_bank()?;
decode::scene_metadata(entry)?;
let op_mode = Self::op_mode_for(entry)?;
let slice = {
let assets_data = assets_data.read().unwrap();
@@ -1322,152 +1299,25 @@ impl AssetManager {
entry: &AssetEntry,
buffer: &[u8],
) -> Result<SceneBank, String> {
let _ = entry.metadata_as_scene_bank()?;
if buffer.len() < SCENE_HEADER_BYTES_V1 {
return Err("Buffer too small for SCENE".to_string());
}
if buffer[0..4] != SCENE_PAYLOAD_MAGIC_V1 {
return Err("Invalid SCENE magic".to_string());
}
let version = u16::from_le_bytes([buffer[4], buffer[5]]);
if version != SCENE_PAYLOAD_VERSION_V1 {
return Err(format!("Unsupported SCENE version: {}", version));
}
let layer_count = u16::from_le_bytes([buffer[6], buffer[7]]) as usize;
if layer_count != SCENE_LAYER_COUNT_V1 {
return Err(format!("Invalid SCENE layer count: {}", layer_count));
}
decode::scene_metadata(entry)?;
decode::payload_size(entry, buffer.len())?;
decode::scene_header(buffer)?;
let mut offset = SCENE_HEADER_BYTES_V1;
let mut decoded_size = 0_usize;
let layers = std::array::from_fn(|_| SceneLayer {
active: false,
glyph_asset_id: 0,
tile_size: TileSize::Size8,
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap { width: 0, height: 0, tiles: Vec::new() },
});
let mut layers = layers;
let mut decoded = 0;
let mut layers = decode::empty_layers();
for layer in &mut layers {
let header_end = offset
let end = offset
.checked_add(SCENE_LAYER_HEADER_BYTES_V1)
.ok_or("SCENE layer header offset overflow")?;
if header_end > buffer.len() {
return Err("Buffer too small for SCENE layer header".to_string());
}
let flags = buffer[offset];
let glyph_asset_id = i32::from_le_bytes([
buffer[offset + 1],
buffer[offset + 2],
buffer[offset + 3],
buffer[offset + 4],
]);
let tile_size_raw = buffer[offset + 5];
let tile_size = match tile_size_raw {
8 => TileSize::Size8,
16 => TileSize::Size16,
32 => TileSize::Size32,
other => return Err(format!("Invalid SCENE tile size: {}", other)),
};
let parallax_factor_x = f32::from_le_bytes([
buffer[offset + 8],
buffer[offset + 9],
buffer[offset + 10],
buffer[offset + 11],
]);
let parallax_factor_y = f32::from_le_bytes([
buffer[offset + 12],
buffer[offset + 13],
buffer[offset + 14],
buffer[offset + 15],
]);
if !parallax_factor_x.is_finite() || !parallax_factor_y.is_finite() {
return Err("Invalid SCENE parallax_factor".to_string());
}
let width = u32::from_le_bytes([
buffer[offset + 16],
buffer[offset + 17],
buffer[offset + 18],
buffer[offset + 19],
]) as usize;
let height = u32::from_le_bytes([
buffer[offset + 20],
buffer[offset + 21],
buffer[offset + 22],
buffer[offset + 23],
]) as usize;
let tile_count = u32::from_le_bytes([
buffer[offset + 24],
buffer[offset + 25],
buffer[offset + 26],
buffer[offset + 27],
]) as usize;
let expected_tile_count =
width.checked_mul(height).ok_or("SCENE tile count overflow")?;
if tile_count != expected_tile_count {
return Err(format!(
"Invalid SCENE tile count for layer: expected {}, got {}",
expected_tile_count, tile_count
));
}
offset = header_end;
let tile_bytes = tile_count
.checked_mul(SCENE_TILE_RECORD_BYTES_V1)
.ok_or("SCENE tile payload overflow")?;
let tiles_end = offset.checked_add(tile_bytes).ok_or("SCENE payload overflow")?;
if tiles_end > buffer.len() {
return Err("Buffer too small for SCENE tile data".to_string());
}
let mut tiles = Vec::with_capacity(tile_count);
for _ in 0..tile_count {
let tile_flags = buffer[offset];
let palette_id = buffer[offset + 1];
let glyph_id = u16::from_le_bytes([buffer[offset + 2], buffer[offset + 3]]);
tiles.push(Tile {
active: (tile_flags & 0b0000_0001) != 0,
glyph: Glyph { glyph_id, palette_id },
flip_x: (tile_flags & 0b0000_0010) != 0,
flip_y: (tile_flags & 0b0000_0100) != 0,
});
offset += SCENE_TILE_RECORD_BYTES_V1;
}
decoded_size = decoded_size
.checked_add(SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1)
.and_then(|size| size.checked_add(tile_count * size_of::<Tile>()))
.ok_or("SCENE decoded_size overflow")?;
*layer = SceneLayer {
active: (flags & 0b0000_0001) != 0,
glyph_asset_id,
tile_size,
parallax_factor: ParallaxFactor { x: parallax_factor_x, y: parallax_factor_y },
tilemap: TileMap { width, height, tiles },
};
.ok_or("SCENE header offset overflow")?;
let header =
buffer.get(offset..end).ok_or("Buffer too small for SCENE layer header")?;
*layer = decode::scene_layer(header, end, entry.size, &mut decoded)?;
let tile_bytes =
layer.tilemap.width * layer.tilemap.height * SCENE_TILE_RECORD_BYTES_V1;
offset = end + tile_bytes; // checked by scene_layer before allocation
decode::append_tiles(&mut layer.tilemap.tiles, &buffer[end..offset]);
}
if offset != buffer.len() {
return Err("Trailing bytes in SCENE payload".to_string());
}
if entry.decoded_size != decoded_size as u64 {
return Err(format!(
"Invalid SCENE decoded_size: expected {}, got {}",
decoded_size, entry.decoded_size
));
}
decode::scene_finish(entry, offset, decoded)?;
Ok(SceneBank { layers })
}
@@ -1484,15 +1334,10 @@ impl AssetManager {
entry: &AssetEntry,
buffer: &[u8],
) -> Result<SoundBank, String> {
let meta = entry.metadata_as_sound_bank()?;
let sample_rate = meta.sample_rate;
let sample_rate = decode::sound_rate(entry)?;
decode::payload_size(entry, buffer.len())?;
let mut data = Vec::with_capacity(buffer.len() / 2);
for i in (0..buffer.len()).step_by(2) {
if i + 1 < buffer.len() {
data.push(i16::from_le_bytes([buffer[i], buffer[i + 1]]));
}
}
decode::append_pcm(&mut data, buffer);
let sample = Arc::new(Sample::new(sample_rate, data));
Ok(SoundBank::new(vec![sample]))
@@ -1709,6 +1554,19 @@ impl AssetManager {
}
pub fn apply_commits(&self) {
self.preload_handles.lock().unwrap().retain(|&handle| match self.status(handle) {
LoadStatus::READY => {
self.commit(handle);
false
}
LoadStatus::QUEUED | LoadStatus::LOADING | LoadStatus::PENDING | LoadStatus::ACTIVE => {
true
}
_ => {
self.preload_failed.store(true, std::sync::atomic::Ordering::SeqCst);
false
}
});
let mut pending = self.pending_commits.lock().unwrap();
let mut handles = self.handles.write().unwrap();
@@ -1846,16 +1704,20 @@ impl AssetManager {
}
pub fn shutdown(&self) {
// Exclude worker publication while invalidating and clearing the cartridge.
let mut generations = self.target_generations.write().unwrap();
for generation in generations.values_mut() {
*generation += 1;
}
self.gfx_policy.clear();
self.sound_policy.clear();
self.scene_policy.clear();
self.handles.write().unwrap().clear();
self.target_handles.write().unwrap().clear();
for generation in self.target_generations.write().unwrap().values_mut() {
*generation += 1;
}
self.load_worker.clear_pending();
self.pending_commits.lock().unwrap().clear();
self.preload_handles.lock().unwrap().clear();
self.preload_failed.store(false, std::sync::atomic::Ordering::SeqCst);
self.gfx_slots.write().unwrap().fill(None);
self.glyph_slot_index.clear();
self.sound_slots.write().unwrap().fill(None);
@@ -1936,7 +1798,7 @@ mod tests {
}
}
fn test_scene() -> SceneBank {
pub(super) fn test_scene() -> SceneBank {
let make_layer = |glyph_asset_id: AssetId,
active: bool,
parallax_x: f32,
@@ -1999,7 +1861,7 @@ mod tests {
.sum()
}
fn encode_scene_payload(scene: &SceneBank) -> Vec<u8> {
pub(super) fn encode_scene_payload(scene: &SceneBank) -> Vec<u8> {
let mut data = Vec::new();
data.extend_from_slice(&SCENE_PAYLOAD_MAGIC_V1);
data.extend_from_slice(&SCENE_PAYLOAD_VERSION_V1.to_le_bytes());
@@ -2039,7 +1901,11 @@ mod tests {
data
}
fn test_scene_asset_entry(asset_name: &str, data: &[u8], scene: &SceneBank) -> AssetEntry {
pub(super) fn test_scene_asset_entry(
asset_name: &str,
data: &[u8],
scene: &SceneBank,
) -> AssetEntry {
AssetEntry {
asset_id: 2,
asset_name: asset_name.to_string(),
@@ -0,0 +1,187 @@
//! Format authority shared by complete-buffer and bounded resumable decoding.
use super::*;
pub(super) fn glyph_layout(
entry: &AssetEntry,
) -> Result<(TileSize, usize, usize, usize, usize, usize), String> {
let meta = entry.metadata_as_glyph_bank()?;
let tile_size = match meta.tile_size {
8 => TileSize::Size8,
16 => TileSize::Size16,
32 => TileSize::Size32,
_ => return Err(format!("Invalid tile_size: {}", meta.tile_size)),
};
let palette_count = meta.palette_count as usize;
if !(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count) {
return Err(format!("Invalid palette_count: {}", meta.palette_count));
}
let width = meta.width as usize;
let height = meta.height as usize;
let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?;
let serialized_pixel_bytes = logical_pixels.div_ceil(2);
let palette_bytes = palette_count
.checked_mul(GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
.ok_or("GlyphBank palette size overflow")?;
let serialized_size = serialized_pixel_bytes
.checked_add(palette_bytes)
.ok_or("GlyphBank serialized size overflow")?;
let decoded_size =
logical_pixels.checked_add(palette_bytes).ok_or("GlyphBank decoded size overflow")?;
if entry.size != serialized_size as u64 {
return Err(format!(
"Invalid GLYPHBANK serialized size: expected {}, got {}",
serialized_size, entry.size
));
}
if entry.decoded_size != decoded_size as u64 {
return Err(format!(
"Invalid GLYPHBANK decoded_size: expected {}, got {}",
decoded_size, entry.decoded_size
));
}
Ok((tile_size, width, height, serialized_pixel_bytes, palette_count, palette_bytes))
}
pub(super) fn append_pixels(pixels: &mut Vec<u8>, bytes: &[u8], logical: usize) {
for &packed in bytes {
if pixels.len() < logical {
pixels.push(packed >> 4);
}
if pixels.len() < logical {
pixels.push(packed & 15);
}
}
}
pub(super) fn write_palettes(
palettes: &mut [[Color; GLYPH_BANK_COLORS_PER_PALETTE]],
position: usize,
bytes: &[u8],
) {
for (i, rgba) in bytes.as_chunks::<4>().0.iter().enumerate() {
let at = position / 4 + i;
palettes[at / 16][at % 16] = Color::rgba(rgba[0], rgba[1], rgba[2], rgba[3]);
}
}
pub(super) fn sound_rate(entry: &AssetEntry) -> Result<u32, String> {
Ok(entry.metadata_as_sound_bank()?.sample_rate)
}
// Callers split on even chunk boundaries. Only the final odd byte is ignored.
pub(super) fn append_pcm(data: &mut Vec<i16>, bytes: &[u8]) {
data.extend(bytes.as_chunks::<2>().0.iter().map(|p| i16::from_le_bytes(*p)));
}
pub(super) fn payload_size(entry: &AssetEntry, actual: usize) -> Result<(), String> {
if actual as u64 != entry.size {
return Err("Invalid asset payload size".into());
}
Ok(())
}
pub(super) fn scene_metadata(entry: &AssetEntry) -> Result<(), String> {
entry.metadata_as_scene_bank().map(|_| ())
}
pub(super) fn empty_layers() -> [SceneLayer; SCENE_LAYER_COUNT_V1] {
std::array::from_fn(|_| SceneLayer {
active: false,
glyph_asset_id: 0,
tile_size: TileSize::Size8,
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap { width: 0, height: 0, tiles: Vec::new() },
})
}
pub(super) fn scene_header(bytes: &[u8]) -> Result<(), String> {
if bytes.len() < SCENE_HEADER_BYTES_V1 {
return Err("Buffer too small for SCENE".into());
}
if bytes[..4] != SCENE_PAYLOAD_MAGIC_V1 {
return Err("Invalid SCENE magic".into());
}
let version = u16::from_le_bytes([bytes[4], bytes[5]]);
if version != SCENE_PAYLOAD_VERSION_V1 {
return Err(format!("Unsupported SCENE version: {version}"));
}
let count = u16::from_le_bytes([bytes[6], bytes[7]]) as usize;
if count != SCENE_LAYER_COUNT_V1 {
return Err(format!("Invalid SCENE layer count: {count}"));
}
Ok(())
}
pub(super) fn scene_layer(
bytes: &[u8],
position: usize,
payload_len: u64,
decoded: &mut usize,
) -> Result<SceneLayer, String> {
if bytes.len() < SCENE_LAYER_HEADER_BYTES_V1 {
return Err("Buffer too small for SCENE layer header".into());
}
let u32at = |at| u32::from_le_bytes(bytes[at..at + 4].try_into().unwrap());
let tile_size = match bytes[5] {
8 => TileSize::Size8,
16 => TileSize::Size16,
32 => TileSize::Size32,
other => return Err(format!("Invalid SCENE tile size: {other}")),
};
let x = f32::from_le_bytes(bytes[8..12].try_into().unwrap());
let y = f32::from_le_bytes(bytes[12..16].try_into().unwrap());
if !x.is_finite() || !y.is_finite() {
return Err("Invalid SCENE parallax_factor".into());
}
let width = u32at(16) as usize;
let height = u32at(20) as usize;
let count = u32at(24) as usize;
let expected = width.checked_mul(height).ok_or("SCENE tile count overflow")?;
if count != expected {
return Err(format!(
"Invalid SCENE tile count for layer: expected {expected}, got {count}"
));
}
let end = count
.checked_mul(SCENE_TILE_RECORD_BYTES_V1)
.and_then(|n| position.checked_add(n))
.ok_or("SCENE payload overflow")?;
if end as u64 > payload_len {
return Err("Buffer too small for SCENE tile data".into());
}
*decoded = decoded
.checked_add(SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1)
.and_then(|n| count.checked_mul(size_of::<Tile>()).and_then(|b| n.checked_add(b)))
.ok_or("SCENE decoded_size overflow")?;
Ok(SceneLayer {
active: bytes[0] & 1 != 0,
glyph_asset_id: i32::from_le_bytes(bytes[1..5].try_into().unwrap()),
tile_size,
parallax_factor: ParallaxFactor { x, y },
tilemap: TileMap { width, height, tiles: Vec::with_capacity(count) },
})
}
pub(super) fn append_tiles(tiles: &mut Vec<Tile>, bytes: &[u8]) {
tiles.extend(bytes.as_chunks::<SCENE_TILE_RECORD_BYTES_V1>().0.iter().map(|b| Tile {
active: b[0] & 1 != 0,
glyph: Glyph { glyph_id: u16::from_le_bytes([b[2], b[3]]), palette_id: b[1] },
flip_x: b[0] & 2 != 0,
flip_y: b[0] & 4 != 0,
}));
}
pub(super) fn scene_finish(
entry: &AssetEntry,
position: usize,
decoded: usize,
) -> Result<(), String> {
payload_size(entry, position)?;
if decoded as u64 != entry.decoded_size {
return Err(format!(
"Invalid SCENE decoded_size: expected {decoded}, got {}",
entry.decoded_size
));
}
Ok(())
}
#[cfg(test)]
pub(super) mod tests;
@@ -0,0 +1,432 @@
use super::*;
use serde_json::{Value, json};
struct FileFixture(std::path::PathBuf);
impl FileFixture {
fn new(name: &str, bytes: &[u8]) -> Self {
let path = std::env::temp_dir()
.join(format!("prometeu-conformance-{}-{name}", std::process::id()));
std::fs::write(&path, bytes).unwrap();
Self(path)
}
fn source(&self, declared_len: u64) -> Arc<RwLock<AssetsPayloadSource>> {
Arc::new(RwLock::new(AssetsPayloadSource::from_file(self.0.clone(), 0, declared_len)))
}
}
impl Drop for FileFixture {
fn drop(&mut self) {
std::fs::remove_file(&self.0).unwrap();
}
}
fn pcm_entry(size: u64) -> AssetEntry {
AssetEntry {
asset_id: 1,
asset_name: "pcm".into(),
bank_type: BankType::SOUNDS,
offset: 0,
size,
decoded_size: size,
codec: AssetCodec::None,
metadata: json!({"sample_rate": 44100, "channels": 1}),
}
}
#[test]
fn pcm_chunk_edges_and_odd_tails_have_explicit_baseline_outputs() {
for len in [0, 1, 2, 3, 4095, 4096, 4097, 8191, 8192, 8193] {
let bytes: Vec<u8> = (0..len).map(|i| if i % 2 == 0 { 0x34 } else { 0x12 }).collect();
let entry = pcm_entry(len as u64);
let expected = json!([[vec![0x1234_i16; len / 2], 44100, null, null]]);
let buffer = AssetManager::decode_sound_bank_from_buffer(&entry, &bytes).unwrap();
let reader = AssetManager::decode_sound_bank_from_reader(&entry, &mut &bytes[..]).unwrap();
let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes)));
let production = AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap();
assert_eq!(sound_snapshot(&buffer), expected, "buffer len={len}");
assert_eq!(sound_snapshot(&reader), expected, "reader len={len}");
assert_eq!(sound_snapshot(&production), expected, "legacy load len={len}");
assert_eq!(
resumable::conformance_result(&entry, &source).unwrap(),
expected,
"resumable len={len}"
);
}
}
#[test]
fn physically_truncated_pcm_file_is_rejected_by_both_modes() {
// Two actual bytes, three declared bytes: the missing byte is an odd tail.
// The approved rule rejects missing declared bytes, including an odd tail.
let fixture = FileFixture::new("truncated-pcm", &[0x34, 0x12]);
let entry = pcm_entry(3);
let source = fixture.source(3);
assert!(AssetManager::perform_load_sound_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).is_err());
// With the declared byte physically present, both accept and ignore it.
std::fs::write(&fixture.0, [0x34, 0x12, 0xff]).unwrap();
let expected = json!([[[0x1234], 44100, null, null]]);
assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected);
assert_eq!(
sound_snapshot(&AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap()),
expected
);
// Memory carriers reject the range before either decoder can accept it.
let memory = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(vec![0x34, 0x12])));
assert!(AssetManager::perform_load_sound_bank(&entry, memory.clone()).is_err());
assert!(resumable::conformance_result(&entry, &memory).is_err());
}
#[test]
fn physically_short_scene_file_is_rejected_by_both_modes() {
// Minimal scene: four empty layers, 12-byte header + 4 * 32-byte headers.
let mut bytes = vec![0_u8; 140];
bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]);
for start in [12, 44, 76, 108] {
bytes[start + 5] = 8;
}
let fixture = FileFixture::new("short-scene", &bytes);
let mut entry = AssetEntry {
asset_id: 2,
asset_name: "scene".into(),
bank_type: BankType::SCENE,
offset: 0,
size: 141,
decoded_size: 64,
codec: AssetCodec::None,
metadata: json!({}),
};
let expected = json!(vec![json!([false, 0, 8, 0.0, 0.0, 0, 0, []]); 4]);
let source = fixture.source(141);
assert!(AssetManager::perform_load_scene_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).is_err());
// Exact physical/declared size is accepted by both.
entry.size = 140;
assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected);
assert_eq!(
scene_snapshot(&AssetManager::perform_load_scene_bank(&entry, source.clone()).unwrap()),
expected
);
// An actual trailing byte is rejected by both.
entry.size = 141;
bytes.push(0);
std::fs::write(&fixture.0, bytes).unwrap();
assert!(AssetManager::perform_load_scene_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).is_err());
}
// Every mode sees the same declared slice, just as it does in production.
fn check_case(name: &str, entry: &AssetEntry, bytes: Vec<u8>, expected: Option<Value>) {
let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes)));
for mode in 0..4 {
let result = (|| -> Result<Value, String> {
if mode == 3 {
return resumable::conformance_result(entry, &source);
}
if mode == 2 {
return match entry.bank_type {
BankType::GLYPH => AssetManager::perform_load_glyph_bank(entry, source.clone())
.map(|b| glyph_snapshot(&b)),
BankType::SOUNDS => {
AssetManager::perform_load_sound_bank(entry, source.clone())
.map(|b| sound_snapshot(&b))
}
BankType::SCENE => AssetManager::perform_load_scene_bank(entry, source.clone())
.map(|b| scene_snapshot(&b)),
};
}
let slice = source
.read()
.unwrap()
.open_slice(entry.offset, entry.size)
.map_err(|e| e.to_string())?;
let bytes = slice.read_all().map_err(|e| e.to_string())?;
let mut reader = &bytes[..];
match (entry.bank_type, mode) {
(BankType::GLYPH, 0) => AssetManager::decode_glyph_bank_from_buffer(entry, &bytes)
.map(|b| glyph_snapshot(&b)),
(BankType::GLYPH, _) => {
AssetManager::decode_glyph_bank_from_reader(entry, &mut reader)
.map(|b| glyph_snapshot(&b))
}
(BankType::SOUNDS, 0) => AssetManager::decode_sound_bank_from_buffer(entry, &bytes)
.map(|b| sound_snapshot(&b)),
(BankType::SOUNDS, _) => {
AssetManager::decode_sound_bank_from_reader(entry, &mut reader)
.map(|b| sound_snapshot(&b))
}
(BankType::SCENE, 0) => AssetManager::decode_scene_bank_from_buffer(entry, &bytes)
.map(|b| scene_snapshot(&b)),
(BankType::SCENE, _) => {
AssetManager::decode_scene_bank_from_reader(entry, &mut reader)
.map(|b| scene_snapshot(&b))
}
}
})();
assert_eq!(result.ok(), expected, "{name}, mode={mode}");
}
}
#[test]
fn glyph_layout_palette_nibbles_and_chunk_boundaries() {
for pixels in [0_usize, 1, 2, 8191, 8192, 8193, 16385] {
for palettes in [1, 3, 64] {
let mut bytes = vec![0x12; pixels.div_ceil(2)];
bytes.extend(std::iter::repeat_n([0x12, 0x34, 0x56, 0x78], palettes * 16).flatten());
let entry = AssetEntry {
asset_id: 1,
asset_name: "glyph".into(),
bank_type: BankType::GLYPH,
offset: 0,
size: bytes.len() as u64,
decoded_size: (pixels + palettes * 64) as u64,
codec: AssetCodec::None,
metadata: json!({"tile_size":16,"width":pixels,"height":1,"palette_count":palettes,"palette_authored":palettes}),
};
let expected = json!([
16,
pixels,
1,
(0..pixels).map(|i| 1 + i % 2).collect::<Vec<_>>(),
vec![vec![0x12345678_u32; 16]; palettes]
]);
check_case("glyph-valid", &entry, bytes.clone(), Some(expected));
for (key, value) in [
("tile_size", json!(7)),
("palette_count", json!(0)),
("palette_count", json!(65)),
("width", json!(-1)),
("height", json!("bad")),
] {
let mut invalid = entry.clone();
invalid.metadata[key] = value;
check_case(key, &invalid, bytes.clone(), None);
}
let mut invalid = entry.clone();
invalid.decoded_size += 1;
check_case("glyph-decoded-size", &invalid, bytes.clone(), None);
let mut invalid = entry.clone();
invalid.size += 1;
let mut extra = bytes.clone();
extra.push(0);
check_case("glyph-trailing", &invalid, extra, None);
bytes.pop();
check_case("glyph-truncated", &entry, bytes, None);
}
}
}
fn empty_scene() -> (AssetEntry, Vec<u8>, Value) {
let mut bytes = vec![0_u8; 140];
bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]);
for start in [12, 44, 76, 108] {
bytes[start + 5] = 8;
}
let entry = AssetEntry {
asset_id: 2,
asset_name: "scene".into(),
bank_type: BankType::SCENE,
offset: 0,
size: 140,
decoded_size: 64,
codec: AssetCodec::None,
metadata: json!({}),
};
(entry, bytes, json!(vec![json!([false, 0, 8, 0.0, 0.0, 0, 0, []]); 4]))
}
#[test]
fn scene_header_ranges_nonfinite_and_truncation_corpus() {
let (entry, bytes, expected) = empty_scene();
check_case("empty-scene", &entry, bytes.clone(), Some(expected));
for end in 0..bytes.len() {
let mut e = entry.clone();
e.size = end as u64;
check_case("scene-every-truncation", &e, bytes[..end].to_vec(), None);
}
for (offset, value) in [(0, 0xff), (4, 2), (6, 3), (17, 7), (36, 1)] {
let mut invalid = bytes.clone();
invalid[offset] = value;
check_case("scene-invalid-header-field", &entry, invalid, None);
}
for offset in [20, 24] {
for value in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] {
let mut invalid = bytes.clone();
invalid[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
check_case("scene-nonfinite", &entry, invalid, None);
}
}
let mut invalid = bytes.clone();
for offset in [28, 32, 36] {
invalid[offset..offset + 4].copy_from_slice(&u32::MAX.to_le_bytes());
}
check_case("scene-dimensions-overflow-or-count-mismatch", &entry, invalid, None);
let mut invalid = bytes.clone();
for offset in [28, 32, 36] {
invalid[offset..offset + 4].copy_from_slice(&1_u32.to_le_bytes());
}
// Four layer headers no longer fit after the declared tile consumes bytes.
check_case("scene-tile-range", &entry, invalid, None);
let mut sequence_metadata = entry.clone();
sequence_metadata.metadata = json!([]);
check_case(
"scene-empty-sequence-metadata",
&sequence_metadata,
bytes.clone(),
Some(empty_scene().2),
);
let mut e = entry.clone();
e.decoded_size += 1;
check_case("scene-decoded-size", &e, bytes.clone(), None);
e = entry.clone();
e.size += 1;
let mut trailing = bytes.clone();
trailing.push(0);
check_case("scene-trailing", &e, trailing, None);
for metadata in [json!(null), json!("bad")] {
e = entry.clone();
e.metadata = metadata;
check_case("scene-metadata", &e, bytes.clone(), None);
}
}
#[test]
fn scene_tile_chunk_edges_flags_and_reserved_bytes() {
for count in [1_usize, 1023, 1024, 1025, 2049] {
let (mut entry, mut bytes, mut expected) = empty_scene();
bytes[12] = 0xff; // Only the active flag is meaningful.
bytes[13..17].copy_from_slice(&(-7_i32).to_le_bytes());
bytes[17] = 32;
bytes[18..20].copy_from_slice(&[0xff; 2]); // Reserved fields are ignored.
bytes[20..24].copy_from_slice(&(-0.5_f32).to_le_bytes());
bytes[24..28].copy_from_slice(&2.0_f32.to_le_bytes());
bytes[28..32].copy_from_slice(&(count as u32).to_le_bytes());
bytes[32..36].copy_from_slice(&1_u32.to_le_bytes());
bytes[36..40].copy_from_slice(&(count as u32).to_le_bytes());
bytes.splice(44..44, std::iter::repeat_n([0xff, 255, 0x34, 0x12], count).flatten());
entry.size = bytes.len() as u64;
entry.decoded_size += (count * size_of::<Tile>()) as u64;
expected[0] = json!([
true,
-7,
32,
-0.5,
2.0,
count,
1,
vec![(true, 0x1234, 255, true, true); count]
]);
check_case("scene-chunks", &entry, bytes, Some(expected));
}
}
#[test]
fn pcm_metadata_and_source_range_corpus() {
for metadata in [
json!(null),
json!({}),
json!({"sample_rate":-1,"channels":1}),
json!({"sample_rate":44100,"channels":"bad"}),
] {
let mut e = pcm_entry(2);
e.metadata = metadata;
check_case("pcm-metadata", &e, vec![0x34, 0x12], None);
}
// These fields are currently descriptive, not extra PCM layout constraints.
let mut e = pcm_entry(2);
e.metadata = json!({"sample_rate":0,"channels":0});
e.decoded_size = 999;
check_case(
"pcm-permissive-metadata",
&e,
vec![0x34, 0x12],
Some(json!([[[0x1234], 0, null, null]])),
);
for offset in [1, u64::MAX] {
let mut e = pcm_entry(2);
e.offset = offset;
check_case("source-range", &e, vec![0x34, 0x12], None);
}
let mut e = pcm_entry(2);
e.size = u64::MAX;
check_case("source-size-overflow", &e, vec![0x34, 0x12], None);
}
pub(in crate::asset) fn glyph_snapshot(bank: &GlyphBank) -> Value {
json!([
bank.tile_size as u8,
bank.width,
bank.height,
bank.pixel_indices,
bank.palettes
.iter()
.map(|p| p.iter().map(|c| c.raw()).collect::<Vec<_>>())
.collect::<Vec<_>>()
])
}
pub(in crate::asset) fn sound_snapshot(bank: &SoundBank) -> Value {
json!(
bank.samples
.iter()
.map(|s| (&s.data, s.sample_rate, s.loop_start, s.loop_end))
.collect::<Vec<_>>()
)
}
pub(in crate::asset) fn scene_snapshot(bank: &SceneBank) -> Value {
json!(
bank.layers
.iter()
.map(|l| json!([
l.active,
l.glyph_asset_id,
l.tile_size as u8,
l.parallax_factor.x,
l.parallax_factor.y,
l.tilemap.width,
l.tilemap.height,
l.tilemap
.tiles
.iter()
.map(|t| (t.active, t.glyph.glyph_id, t.glyph.palette_id, t.flip_x, t.flip_y))
.collect::<Vec<_>>()
]))
.collect::<Vec<_>>()
)
}
#[test]
fn shared_scene_arithmetic_rejects_overflow_before_allocating() {
let (_, bytes, _) = empty_scene();
let mut header = bytes[12..44].to_vec();
header[16..20].copy_from_slice(&1_u32.to_le_bytes());
header[20..24].copy_from_slice(&1_u32.to_le_bytes());
header[24..28].copy_from_slice(&1_u32.to_le_bytes());
assert!(scene_layer(&header, usize::MAX, u64::MAX, &mut 0).is_err());
let mut decoded = usize::MAX;
assert!(scene_layer(&header, 44, 48, &mut decoded).is_err());
assert!(scene_layer(&header, 44, 47, &mut 0).is_err());
assert!(scene_layer(&header[..31], 44, 48, &mut 0).is_err());
}
#[test]
fn physically_truncated_glyph_palette_is_rejected_by_both_modes() {
let fixture = FileFixture::new("truncated-glyph", &[0; 63]);
let entry = AssetEntry {
asset_id: 3,
asset_name: "empty-glyph".into(),
bank_type: BankType::GLYPH,
offset: 0,
size: 64,
decoded_size: 64,
codec: AssetCodec::None,
metadata: json!({"tile_size":8,"width":0,"height":0,"palette_count":1,"palette_authored":1}),
};
let source = fixture.source(64);
assert!(AssetManager::perform_load_glyph_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).is_err());
std::fs::write(&fixture.0, [0; 64]).unwrap();
let expected = json!([8, 0, 0, [], vec![vec![0; 16]]]);
assert_eq!(
glyph_snapshot(&AssetManager::perform_load_glyph_bank(&entry, source.clone()).unwrap()),
expected
);
assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected);
}
@@ -0,0 +1,572 @@
//! Bounded decoding steps retain progress while the shared lane services saves.
use super::*;
use prometeu_hal::background_work::{BackgroundWork, WorkStep};
use prometeu_hal::cartridge::AssetsPayloadReader;
#[derive(Clone)]
pub(super) struct Resources {
handles: Arc<RwLock<HandleTable>>,
generations: Arc<RwLock<TargetGenerationTable>>,
source: Arc<RwLock<AssetsPayloadSource>>,
telemetry: Arc<Mutex<AssetPipelineTelemetryState>>,
gfx: BankPolicy<GlyphBank>,
sound: BankPolicy<SoundBank>,
scene: BankPolicy<SceneBank>,
}
impl Resources {
pub(super) fn new(m: &AssetManager) -> Self {
Self {
handles: m.handles.clone(),
generations: m.target_generations.clone(),
source: m.assets_data.clone(),
telemetry: m.pipeline_telemetry.clone(),
gfx: m.gfx_policy.clone(),
sound: m.sound_policy.clone(),
scene: m.scene_policy.clone(),
}
}
fn current(&self, job: &AssetLoadJob) -> bool {
AssetManager::is_current_target_generation(
&self.generations,
job.slot,
job.request_generation,
)
}
}
pub(super) fn schedule(
queue: Arc<AssetLoadQueue>,
lane: Arc<dyn BackgroundWork>,
resources: Resources,
) {
{
let mut state = queue.state.lock().unwrap();
if state.scheduled || state.shutdown {
return;
}
state.scheduled = true;
}
let owner = queue.clone();
let failure_queue = queue.clone();
let failures = resources.clone();
let mut active: Option<(AssetLoadJob, Decoder, Instant)> = None;
if lane
.submit_asset(Box::new(move |canceled| {
if canceled || owner.state.lock().unwrap().shutdown {
let mut state = owner.state.lock().unwrap();
state.scheduled = false;
state.active = None;
return WorkStep::Failed;
}
if active.is_none() {
let job = {
let mut state = owner.state.lock().unwrap();
match state.pending.pop_front() {
Some(job) => {
state.active = Some(job.clone());
job
}
None => {
state.scheduled = false;
return WorkStep::Complete;
}
}
};
if !resources.current(&job) {
resources.telemetry.lock().unwrap().record_stale_discard();
owner.complete_active(job.handle_id, job.request_generation);
return WorkStep::Yield;
}
if let Some(handle) = resources.handles.write().unwrap().get_mut(&job.handle_id) {
handle.status = LoadStatus::LOADING;
handle.progress = ASSET_PROGRESS_LOADING;
}
let start = Instant::now();
resources.telemetry.lock().unwrap().record_started(0);
match Decoder::new(&job.entry, &resources.source) {
Ok(decoder) => active = Some((job, decoder, start)),
Err(_) => {
AssetManager::complete_load_job(
&resources.handles,
&job,
LoadStatus::ERROR,
);
AssetManager::record_load_job_finished(
&resources.telemetry,
&job,
start,
LoadStatus::ERROR,
);
owner.complete_active(job.handle_id, job.request_generation);
return WorkStep::Yield;
}
}
return WorkStep::Yield;
}
let (job, decoder, start) = active.as_mut().unwrap();
if !resources.current(job) {
resources.telemetry.lock().unwrap().record_stale_discard();
owner.complete_active(job.handle_id, job.request_generation);
active = None;
return WorkStep::Yield;
}
match decoder.step() {
Ok(None) => WorkStep::Yield,
outcome => {
let generations = resources.generations.read().unwrap();
let status = if let Ok(Some(bank)) = outcome {
if generations.get(&job.slot).copied().unwrap_or(0)
== job.request_generation
{
match bank {
Decoded::Glyph(bank) => {
let resident = resources.gfx.put_resident(
job.asset_id,
Arc::new(bank),
job.entry.decoded_size as usize,
);
resources.gfx.stage(
job.handle_id,
resident,
job.entry.decoded_size as usize,
);
}
Decoded::Sound(bank) => {
let resident = resources.sound.put_resident(
job.asset_id,
Arc::new(bank),
job.entry.decoded_size as usize,
);
resources.sound.stage(
job.handle_id,
resident,
job.entry.decoded_size as usize,
);
}
Decoded::Scene(bank) => {
let resident = resources.scene.put_resident(
job.asset_id,
Arc::new(bank),
job.entry.decoded_size as usize,
);
resources.scene.stage(
job.handle_id,
resident,
job.entry.decoded_size as usize,
);
}
}
LoadStatus::READY
} else {
LoadStatus::ERROR
}
} else {
LoadStatus::ERROR
};
drop(generations);
AssetManager::complete_load_job(&resources.handles, job, status);
AssetManager::record_load_job_finished(
&resources.telemetry,
job,
*start,
status,
);
owner.complete_active(job.handle_id, job.request_generation);
active = None;
WorkStep::Yield
}
}
}))
.is_err()
{
let mut state = failure_queue.state.lock().unwrap();
state.scheduled = false;
for job in state.pending.drain(..) {
AssetManager::complete_load_job(&failures.handles, &job, LoadStatus::ERROR);
}
}
}
enum Decoded {
Glyph(GlyphBank),
Sound(SoundBank),
Scene(SceneBank),
}
enum State {
Glyph {
bank: GlyphBank,
packed: usize,
position: usize,
palette_bytes: usize,
palette_position: usize,
},
Sound {
sample_rate: u32,
data: Vec<i16>,
remaining: usize,
},
Scene {
layers: [SceneLayer; SCENE_LAYER_COUNT_V1],
layer: usize,
tiles_left: usize,
header: bool,
decoded: usize,
},
Done,
}
struct Decoder {
reader: AssetsPayloadReader,
entry: AssetEntry,
state: State,
position: usize,
}
impl Decoder {
fn new(entry: &AssetEntry, source: &Arc<RwLock<AssetsPayloadSource>>) -> Result<Self, String> {
let reader = source
.read()
.unwrap()
.open_slice(entry.offset, entry.size)
.map_err(|e| e.to_string())?
.open_reader()
.map_err(|e| e.to_string())?;
let state = match entry.bank_type {
BankType::GLYPH => {
let (tile_size, width, height, packed, palette_count, palette_bytes) =
AssetManager::decode_glyph_bank_layout(entry)?;
State::Glyph {
bank: GlyphBank {
tile_size,
width,
height,
pixel_indices: Vec::with_capacity(width * height),
palettes: vec![[Color::BLACK; 16]; palette_count],
},
packed,
position: 0,
palette_bytes,
palette_position: 0,
}
}
BankType::SOUNDS => {
let sample_rate = decode::sound_rate(entry)?;
State::Sound {
sample_rate,
data: Vec::with_capacity(entry.size as usize / 2),
remaining: entry.size as usize,
}
}
BankType::SCENE => {
decode::scene_metadata(entry)?;
State::Scene {
layers: decode::empty_layers(),
layer: 0,
tiles_left: 0,
header: false,
decoded: 0,
}
}
};
Ok(Self { reader, entry: entry.clone(), state, position: 0 })
}
fn step(&mut self) -> Result<Option<Decoded>, String> {
let mut bytes = [0; 4096];
match &mut self.state {
State::Glyph { bank, packed, position, palette_bytes, palette_position } => {
if *position < *packed {
let n = (*packed - *position).min(bytes.len());
self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?;
decode::append_pixels(
&mut bank.pixel_indices,
&bytes[..n],
bank.width * bank.height,
);
*position += n;
return Ok(None);
}
if *palette_position < *palette_bytes {
let n = (*palette_bytes - *palette_position).min(bytes.len());
self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?;
decode::write_palettes(&mut bank.palettes, *palette_position, &bytes[..n]);
*palette_position += n;
return Ok(None);
}
let State::Glyph { bank, .. } = std::mem::replace(&mut self.state, State::Done)
else {
unreachable!()
};
Ok(Some(Decoded::Glyph(bank)))
}
State::Sound { sample_rate, data, remaining } => {
if *remaining > 0 {
let n = (*remaining).min(bytes.len());
self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?;
decode::append_pcm(data, &bytes[..n]);
*remaining -= n;
return Ok(None);
}
let rate = *sample_rate;
let data = std::mem::take(data);
self.state = State::Done;
Ok(Some(Decoded::Sound(SoundBank::new(vec![Arc::new(Sample::new(rate, data))]))))
}
State::Scene { layers, layer, tiles_left, header, decoded } => {
if !*header {
self.reader
.read_exact(&mut bytes[..SCENE_HEADER_BYTES_V1])
.map_err(|e| e.to_string())?;
decode::scene_header(&bytes[..SCENE_HEADER_BYTES_V1])?;
self.position += SCENE_HEADER_BYTES_V1;
*header = true;
return Ok(None);
}
if *tiles_left > 0 {
let n = (*tiles_left).min(bytes.len() / SCENE_TILE_RECORD_BYTES_V1);
let count = n * SCENE_TILE_RECORD_BYTES_V1;
self.reader.read_exact(&mut bytes[..count]).map_err(|e| e.to_string())?;
decode::append_tiles(&mut layers[*layer - 1].tilemap.tiles, &bytes[..count]);
*tiles_left -= n;
self.position += count;
return Ok(None);
}
if *layer < layers.len() {
self.reader
.read_exact(&mut bytes[..SCENE_LAYER_HEADER_BYTES_V1])
.map_err(|e| e.to_string())?;
self.position += SCENE_LAYER_HEADER_BYTES_V1;
layers[*layer] = decode::scene_layer(
&bytes[..SCENE_LAYER_HEADER_BYTES_V1],
self.position,
self.entry.size,
decoded,
)?;
let count = layers[*layer].tilemap.width * layers[*layer].tilemap.height;
*layer += 1;
*tiles_left = count;
return Ok(None);
}
decode::scene_finish(&self.entry, self.position, *decoded)?;
let State::Scene { layers, .. } = std::mem::replace(&mut self.state, State::Done)
else {
unreachable!()
};
Ok(Some(Decoded::Scene(SceneBank { layers })))
}
State::Done => Err("Decoder already complete".into()),
}
}
}
// Test-only access to the production state machine; no alternate decode rules.
#[cfg(test)]
pub(super) fn conformance_result(
entry: &AssetEntry,
source: &Arc<RwLock<AssetsPayloadSource>>,
) -> Result<serde_json::Value, String> {
use std::io::Seek;
let mut decoder = Decoder::new(entry, source)?;
for _ in 0..100 {
let before = decoder.reader.stream_position().unwrap();
let result = decoder.step();
let after = decoder.reader.stream_position().unwrap();
assert!(after >= before && after - before <= 4096, "unbounded or rewound decode step");
if let Some(bank) = result? {
return Ok(match bank {
Decoded::Glyph(bank) => super::decode::tests::glyph_snapshot(&bank),
Decoded::Sound(bank) => super::decode::tests::sound_snapshot(&bank),
Decoded::Scene(bank) => super::decode::tests::scene_snapshot(&bank),
});
}
}
panic!("conformance fixture exceeded its step budget")
}
#[cfg(test)]
mod tests {
use super::*;
use prometeu_hal::background_work::{AssetWork, WorkUnavailable};
#[derive(Default)]
struct ManualLane(Mutex<VecDeque<AssetWork>>);
impl BackgroundWork for ManualLane {
fn submit_asset(&self, work: AssetWork) -> Result<(), WorkUnavailable> {
self.0.lock().unwrap().push_back(work);
Ok(())
}
}
impl ManualLane {
fn step(&self) -> bool {
let Some(mut work) = self.0.lock().unwrap().pop_front() else { return false };
if work(false) == WorkStep::Yield {
self.0.lock().unwrap().push_back(work);
}
true
}
}
#[test]
fn shared_decoder_yields_and_matches_existing_glyph_format() {
let mut data = vec![0x12; 32];
data.extend([255; 64]);
let entry = AssetEntry {
asset_id: 7,
asset_name: "glyph".into(),
bank_type: BankType::GLYPH,
codec: AssetCodec::None,
offset: 0,
size: data.len() as u64,
decoded_size: 128,
metadata: serde_json::json!({"tile_size":8,"width":8,"height":8,"palette_count":1,"palette_authored":1}),
};
let expected = AssetManager::decode_glyph_bank_from_buffer(&entry, &data).unwrap();
let banks = Arc::new(crate::memory_banks::MemoryBanks::new());
let mut manager = AssetManager::new(
vec![entry],
AssetsPayloadSource::from_bytes(data),
banks.clone(),
banks.clone(),
banks,
);
let lane = Arc::new(ManualLane::default());
assert!(manager.bind_background_work(lane.clone()));
let handle = manager.load(7, 0).unwrap();
let mut steps = 0;
while lane.step() {
steps += 1;
assert!(steps < 20);
}
assert!(steps >= 4);
assert_eq!(manager.status(handle), LoadStatus::READY);
let staging = manager.gfx_policy.staging.read().unwrap();
let (actual, _) = staging.get(&handle).unwrap();
assert_eq!(actual.pixel_indices, expected.pixel_indices);
assert_eq!(actual.palettes, expected.palettes);
}
fn decode_in_steps(entry: &AssetEntry, bytes: Vec<u8>) -> Decoded {
let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes)));
let mut decoder = Decoder::new(entry, &source).unwrap();
for _ in 0..100 {
if let Some(result) = decoder.step().unwrap() {
return result;
}
}
panic!("decoder did not finish")
}
#[test]
fn resumable_sound_and_scene_preserve_existing_formats() {
let pcm: Vec<i16> = (0..5000).map(|n| n as i16 - 2500).collect();
let bytes: Vec<u8> = pcm.iter().flat_map(|n| n.to_le_bytes()).collect();
let entry = AssetEntry {
asset_id: 1,
asset_name: "pcm".into(),
bank_type: BankType::SOUNDS,
offset: 0,
size: bytes.len() as u64,
decoded_size: bytes.len() as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({"sample_rate":44100,"channels":1}),
};
let Decoded::Sound(bank) = decode_in_steps(&entry, bytes) else { panic!() };
assert_eq!(bank.samples[0].data, pcm);
let scene = crate::asset::tests::test_scene();
let bytes = crate::asset::tests::encode_scene_payload(&scene);
let entry = crate::asset::tests::test_scene_asset_entry("scene", &bytes, &scene);
let Decoded::Scene(actual) = decode_in_steps(&entry, bytes) else { panic!() };
for (a, b) in actual.layers.iter().zip(scene.layers.iter()) {
assert_eq!(a.active, b.active);
assert_eq!(a.glyph_asset_id, b.glyph_asset_id);
assert_eq!(a.tile_size, b.tile_size);
assert_eq!(a.parallax_factor.x, b.parallax_factor.x);
assert_eq!(a.tilemap.width, b.tilemap.width);
assert_eq!(a.tilemap.height, b.tilemap.height);
assert_eq!(a.tilemap.tiles.len(), b.tilemap.tiles.len());
for (x, y) in a.tilemap.tiles.iter().zip(&b.tilemap.tiles) {
assert_eq!(
(x.active, x.glyph.glyph_id, x.glyph.palette_id, x.flip_x, x.flip_y),
(y.active, y.glyph.glyph_id, y.glyph.palette_id, y.flip_x, y.flip_y)
);
}
}
}
#[test]
fn shared_preload_waits_for_worker_and_frame_publication() {
let bytes = vec![0; 8192];
let entry = AssetEntry {
asset_id: 1,
asset_name: "pcm".into(),
bank_type: BankType::SOUNDS,
offset: 0,
size: bytes.len() as u64,
decoded_size: bytes.len() as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({"sample_rate":44100,"channels":1}),
};
let banks = Arc::new(crate::memory_banks::MemoryBanks::new());
let mut manager = AssetManager::new(
vec![],
AssetsPayloadSource::empty(),
banks.clone(),
banks.clone(),
banks,
);
let lane = Arc::new(ManualLane::default());
assert!(manager.bind_background_work(lane.clone()));
manager.initialize_for_cartridge(
vec![entry],
vec![PreloadEntry { asset_id: 1, slot: 0 }],
AssetsPayloadSource::from_bytes(bytes),
);
assert_eq!(manager.preloads_ready(), Ok(false));
while lane.step() {}
assert_eq!(manager.preloads_ready(), Ok(false));
manager.apply_commits();
assert_eq!(manager.preloads_ready(), Ok(true));
assert_eq!(manager.slot_info(SlotRef::audio(0)).asset_id, Some(1));
}
#[test]
fn canceled_and_superseded_partial_decoders_never_publish() {
use crate::memory_banks::SoundBankPoolAccess;
let bytes = vec![0x12; 16384];
let entry = AssetEntry {
asset_id: 1,
asset_name: "pcm".into(),
bank_type: BankType::SOUNDS,
offset: 0,
size: bytes.len() as u64,
decoded_size: bytes.len() as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({"sample_rate":44100,"channels":1}),
};
let mut newer = entry.clone();
newer.asset_id = 2;
let banks = Arc::new(crate::memory_banks::MemoryBanks::new());
let mut manager = AssetManager::new(
vec![entry, newer],
AssetsPayloadSource::from_bytes(bytes),
banks.clone(),
banks.clone(),
banks.clone(),
);
let lane = Arc::new(ManualLane::default());
assert!(manager.bind_background_work(lane.clone()));
let handle = manager.load(1, 0).unwrap();
assert!(lane.step());
assert!(lane.step());
assert_eq!(manager.status(handle), LoadStatus::LOADING);
assert_eq!(manager.cancel(handle), AssetOpStatus::Ok);
while lane.step() {}
assert_eq!(manager.status(handle), LoadStatus::CANCELED);
assert!(manager.sound_policy.staging.read().unwrap().is_empty());
manager.apply_commits();
assert!(banks.sound_bank_slot(0).is_none());
let old = manager.load(1, 0).unwrap();
assert!(lane.step());
assert!(lane.step());
let new = manager.load(2, 0).unwrap();
assert_eq!(old, new); // Stable slot handle, different request generation.
assert!(lane.step()); // Discard the in-flight old decoder.
assert!(manager.sound_policy.staging.read().unwrap().is_empty());
while lane.step() {}
assert_eq!(manager.status(new), LoadStatus::READY);
assert!(banks.sound_bank_slot(0).is_none());
assert_eq!(manager.commit(new), AssetOpStatus::Ok);
manager.apply_commits();
assert_eq!(manager.slot_info(SlotRef::audio(0)).asset_id, Some(2));
assert_eq!(banks.sound_bank_slot(0).unwrap().samples[0].data, vec![0x1212; 8192]);
}
}
+281 -168
View File
@@ -13,8 +13,7 @@ use prometeu_hal::sample::Sample;
/// State of a single playback voice (channel).
///
/// The Core maintains this state to provide information to the App (e.g., is_playing),
/// but the actual real-time mixing is performed by the Host using commands.
/// This state belongs exclusively to the mixer, which observes natural completion.
pub struct Channel {
/// The actual sample data being played.
pub sample: Option<Arc<Sample>>,
@@ -30,7 +29,7 @@ pub struct Channel {
pub pan: u8,
/// Loop configuration for this voice.
pub loop_mode: LoopMode,
/// Playback priority (used for voice stealing policies).
/// Internal priority metadata; the guest explicitly selects its voice.
pub priority: u8,
}
@@ -64,7 +63,7 @@ pub enum AudioCommand {
priority: u8,
loop_mode: LoopMode,
},
/// Immediately stop playback on a voice.
/// Stop playback on a voice when this command is applied.
Stop { voice_id: usize },
/// Update volume of an ongoing playback.
SetVolume { voice_id: usize, volume: u8 },
@@ -72,36 +71,65 @@ pub enum AudioCommand {
SetPan { voice_id: usize, pan: u8 },
/// Update pitch of an ongoing playback.
SetPitch { voice_id: usize, pitch: f64 },
/// Pause all audio processing.
MasterPause,
/// Resume audio processing.
MasterResume,
}
/// PROMETEU Audio Subsystem.
///
/// Models a multi-channel PCM sampler (SPU).
/// The audio system in Prometeu is **command-based**. This means the Core
/// doesn't generate raw audio samples; instead, it sends high-level commands
/// (like `Play`, `Stop`, `SetVolume`) to a queue. The physical host backend
/// (e.g., CPAL on desktop) then consumes these commands and performs the
/// actual mixing at the native hardware sample rate.
///
/// ### Key Features:
/// - **16 Simultaneous Voices**: Independent volume, pan, and pitch.
/// - **Sample-based Synthesis**: Plays PCM data stored in SoundBanks.
/// - **Stereo Output**: 48kHz output target.
mod transport;
pub use transport::{AudioDelivery, AudioTransport};
pub const MAX_COMMANDS_PER_FRAME: usize = 1024;
/// Bounded producer staging. Samples belong to staged/published commands and the
/// mixer, never to a second playback mirror that cannot observe completion.
pub struct Audio {
/// Local state of the hardware voices. This state is used for logic
/// (e.g., checking if a sound is still playing) and is synchronized with the Host.
pub voices: [Channel; MAX_CHANNELS],
/// Queue of pending commands to be processed by the Host mixer.
/// This queue is typically flushed and sent to the Host once per frame.
pub commands: Vec<AudioCommand>,
/// Interface to access sound memory banks (ARAM).
commands: Vec<AudioCommand>,
/// Admission survives an early lifecycle flush of the interrupted frame.
frame_commands_admitted: usize,
lifecycle_commands: Vec<AudioCommand>,
in_lifecycle: bool,
session: Option<u32>,
transport: AudioTransport,
pub sound_banks: Arc<dyn SoundBankPoolAccess>,
}
impl Audio {
pub fn new(sound_banks: Arc<dyn SoundBankPoolAccess>) -> Self {
Self {
commands: Vec::new(),
frame_commands_admitted: 0,
lifecycle_commands: Vec::new(),
in_lifecycle: false,
session: None,
transport: AudioTransport::default(),
sound_banks,
}
}
pub fn transport(&self) -> AudioTransport {
self.transport.clone()
}
fn enqueue(&mut self, voice: usize, command: AudioCommand) -> AudioOpStatus {
if voice >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
let admitted = if self.in_lifecycle {
self.lifecycle_commands.len()
} else {
self.frame_commands_admitted
};
if admitted >= MAX_COMMANDS_PER_FRAME {
return AudioOpStatus::CommandLimit;
}
if self.in_lifecycle {
self.lifecycle_commands.push(command);
} else {
self.commands.push(command);
self.frame_commands_admitted += 1;
}
AudioOpStatus::Ok
}
}
impl AudioBridge for Audio {
fn play(
&mut self,
@@ -112,14 +140,23 @@ impl AudioBridge for Audio {
pan: u8,
pitch: f64,
priority: u8,
loop_mode: prometeu_hal::LoopMode,
loop_mode: LoopMode,
) -> AudioOpStatus {
let lm = match loop_mode {
prometeu_hal::LoopMode::Off => LoopMode::Off,
prometeu_hal::LoopMode::On => LoopMode::On,
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
}
let Some(bank) = self.sound_banks.sound_bank_slot(bank_id as usize) else {
return AudioOpStatus::BankInvalid;
};
self.play(bank_id, sample_id, voice_id, volume, pan, pitch, priority, lm)
let Some(sample) = bank.samples.get(sample_id as usize).cloned() else {
return AudioOpStatus::SampleNotFound;
};
self.play_sample(sample, voice_id, volume, pan, pitch, priority, loop_mode)
}
fn play_sample(
&mut self,
sample: Arc<Sample>,
@@ -128,156 +165,85 @@ impl AudioBridge for Audio {
pan: u8,
pitch: f64,
priority: u8,
loop_mode: prometeu_hal::LoopMode,
) -> AudioOpStatus {
let lm = match loop_mode {
prometeu_hal::LoopMode::Off => LoopMode::Off,
prometeu_hal::LoopMode::On => LoopMode::On,
};
self.play_sample(sample, voice_id, volume, pan, pitch, priority, lm)
}
fn stop(&mut self, voice_id: usize) {
self.stop(voice_id)
}
fn set_volume(&mut self, voice_id: usize, volume: u8) {
self.set_volume(voice_id, volume)
}
fn set_pan(&mut self, voice_id: usize, pan: u8) {
self.set_pan(voice_id, pan)
}
fn set_pitch(&mut self, voice_id: usize, pitch: f64) {
self.set_pitch(voice_id, pitch)
}
fn is_playing(&self, voice_id: usize) -> bool {
self.is_playing(voice_id)
}
fn clear_commands(&mut self) {
self.clear_commands()
}
}
impl Audio {
/// Initializes the audio system with empty voices and sound bank access.
pub fn new(sound_banks: Arc<dyn SoundBankPoolAccess>) -> Self {
Self {
voices: std::array::from_fn(|_| Channel::default()),
commands: Vec::new(),
sound_banks,
}
}
#[allow(clippy::too_many_arguments)]
pub fn play(
&mut self,
bank_id: u8,
sample_id: u16,
voice_id: usize,
volume: u8,
pan: u8,
pitch: f64,
priority: u8,
loop_mode: LoopMode,
) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
// Resolve the sample from the hardware pools
let bank_slot = self.sound_banks.sound_bank_slot(bank_id as usize);
if bank_slot.is_none() {
return AudioOpStatus::BankInvalid;
if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
}
let sample =
bank_slot.and_then(|bank| bank.samples.get(sample_id as usize).map(Arc::clone));
if let Some(s) = sample {
// println!(
// "[Audio] Resolved sample from bank {} sample {}. Playing on voice {}.",
// bank_id, sample_id, voice_id
// );
self.play_sample(s, voice_id, volume, pan, pitch, priority, loop_mode)
} else {
AudioOpStatus::SampleNotFound
}
}
#[allow(clippy::too_many_arguments)]
pub fn play_sample(
&mut self,
sample: Arc<Sample>,
voice_id: usize,
volume: u8,
pan: u8,
pitch: f64,
priority: u8,
loop_mode: LoopMode,
) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
// Update local state
self.voices[voice_id] = Channel {
sample: Some(Arc::clone(&sample)),
active: true,
pos: 0.0,
pitch,
volume,
pan,
loop_mode,
priority,
};
// Push command to the host
self.commands.push(AudioCommand::Play {
sample,
self.enqueue(
voice_id,
volume,
pan,
pitch,
priority,
loop_mode,
});
AudioOpStatus::Ok
AudioCommand::Play { sample, voice_id, volume, pan, pitch, priority, loop_mode },
)
}
pub fn stop(&mut self, voice_id: usize) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].active = false;
self.voices[voice_id].sample = None;
self.commands.push(AudioCommand::Stop { voice_id });
fn stop(&mut self, voice_id: usize) -> AudioOpStatus {
self.enqueue(voice_id, AudioCommand::Stop { voice_id })
}
fn set_volume(&mut self, voice_id: usize, volume: u8) -> AudioOpStatus {
self.enqueue(voice_id, AudioCommand::SetVolume { voice_id, volume })
}
fn set_pan(&mut self, voice_id: usize, pan: u8) -> AudioOpStatus {
self.enqueue(voice_id, AudioCommand::SetPan { voice_id, pan })
}
fn set_pitch(&mut self, voice_id: usize, pitch: f64) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
}
pub fn set_volume(&mut self, voice_id: usize, volume: u8) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].volume = volume;
self.commands.push(AudioCommand::SetVolume { voice_id, volume });
if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
}
self.enqueue(voice_id, AudioCommand::SetPitch { voice_id, pitch })
}
pub fn set_pan(&mut self, voice_id: usize, pan: u8) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].pan = pan;
self.commands.push(AudioCommand::SetPan { voice_id, pan });
}
fn ready(&self) -> bool {
self.transport.ready()
}
pub fn set_pitch(&mut self, voice_id: usize, pitch: f64) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].pitch = pitch;
self.commands.push(AudioCommand::SetPitch { voice_id, pitch });
}
fn begin_frame(&mut self) { /* Staging may already contain debugger steps. */
}
pub fn is_playing(&self, voice_id: usize) -> bool {
if voice_id < MAX_CHANNELS { self.voices[voice_id].active } else { false }
fn finish_frame(&mut self) {
let commands = std::mem::replace(&mut self.commands, self.transport.take_buffer());
self.transport.publish(commands, false);
self.frame_commands_admitted = 0;
}
/// Clears the command queue. The Host should consume this every frame.
pub fn clear_commands(&mut self) {
fn abort_frame(&mut self) {
self.commands.clear();
self.frame_commands_admitted = 0;
}
fn lifecycle_ready(&self) -> bool {
self.transport.lifecycle_ready()
}
fn begin_lifecycle(&mut self) {
self.in_lifecycle = true;
}
fn finish_lifecycle(&mut self, success: bool) {
self.in_lifecycle = false;
if success {
// Publish the earlier frame prefix first so a callback stop cannot
// be undone by an old play on resume. Do not replenish frame quota.
let mut commands = std::mem::replace(&mut self.commands, self.transport.take_buffer());
commands.append(&mut self.lifecycle_commands);
self.transport.publish(commands, true);
} else {
self.lifecycle_commands.clear();
self.abort_frame();
}
}
fn set_session(&mut self, session: Option<u32>) {
if self.session != session {
self.reset();
self.session = session;
}
}
fn reset(&mut self) {
self.abort_frame();
self.lifecycle_commands.clear();
self.in_lifecycle = false;
self.transport.reset();
}
fn set_paused(&mut self, paused: bool) {
self.transport.set_paused(paused);
}
}
@@ -326,7 +292,154 @@ mod tests {
let status = audio.play_sample(sample(), MAX_CHANNELS, 255, 128, 1.0, 0, LoopMode::Off);
assert_eq!(status, AudioOpStatus::VoiceInvalid);
assert!(!audio.voices.iter().any(|voice| voice.active));
assert!(audio.commands.is_empty());
}
}
#[cfg(test)]
mod control_tests {
use super::*;
use crate::MemoryBanks;
fn audio() -> Audio {
Audio::new(Arc::new(MemoryBanks::new()))
}
#[test]
fn quota_is_shared_and_rejections_never_publish_partial_effects() {
let mut audio = audio();
for _ in 0..MAX_COMMANDS_PER_FRAME - 1 {
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
assert_eq!(audio.set_volume(15, 0), AudioOpStatus::Ok);
assert_eq!(audio.set_pan(0, 255), AudioOpStatus::CommandLimit);
assert_eq!(audio.set_pitch(16, f64::NAN), AudioOpStatus::VoiceInvalid);
assert_eq!(audio.set_pitch(0, f64::NAN), AudioOpStatus::ArgRangeInvalid);
let sample = Arc::new(Sample::new(48_000, vec![1]));
assert_eq!(
audio.play_sample(sample.clone(), 0, 255, 0, 1.0, 0, LoopMode::Off),
AudioOpStatus::CommandLimit
);
assert_eq!(Arc::strong_count(&sample), 1);
assert!(audio.transport.try_take().unwrap().frame.is_none());
audio.finish_frame();
assert!(!audio.ready());
assert_eq!(
audio.transport.try_take().unwrap().frame.unwrap().len(),
MAX_COMMANDS_PER_FRAME
);
assert!(audio.ready());
audio.begin_frame();
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
#[test]
fn lifecycle_and_reset_bypass_full_guest_batch_and_release_samples() {
let mut audio = audio();
audio.set_session(Some(1));
let sample = Arc::new(Sample::new(48_000, vec![1]));
let weak = Arc::downgrade(&sample);
assert_eq!(audio.play_sample(sample, 0, 255, 0, 1.0, 0, LoopMode::On), AudioOpStatus::Ok);
for _ in 1..MAX_COMMANDS_PER_FRAME {
audio.stop(1);
}
audio.finish_frame();
assert!(!audio.ready());
assert!(audio.lifecycle_ready());
audio.begin_lifecycle();
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
audio.finish_lifecycle(true);
audio.set_paused(true);
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.paused);
assert_eq!(delivery.frame.as_ref().unwrap().len(), MAX_COMMANDS_PER_FRAME);
assert!(matches!(
delivery.lifecycle.as_ref().unwrap()[0],
AudioCommand::Stop { voice_id: 0 }
));
let old_epoch = delivery.epoch;
drop(delivery);
assert!(weak.upgrade().is_none(), "driver must not retain a playback mirror");
audio.stop(0);
audio.finish_frame();
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(true);
audio.set_session(Some(2));
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.epoch > old_epoch);
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
assert!(audio.ready());
}
#[test]
fn lifecycle_publishes_prefix_first_and_aborted_batches_are_cancelled() {
let mut audio = audio();
audio.set_pan(0, 17);
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(true);
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.frame.is_none());
let lifecycle = delivery.lifecycle.unwrap();
assert!(matches!(lifecycle[0], AudioCommand::SetPan { pan: 17, .. }));
assert!(matches!(lifecycle[1], AudioCommand::Stop { voice_id: 1 }));
audio.set_volume(0, 23);
audio.finish_frame();
let commands = audio.transport.try_take().unwrap().frame.unwrap();
assert_eq!(commands.len(), 1);
assert!(matches!(commands[0], AudioCommand::SetVolume { volume: 23, .. }));
audio.stop(0);
audio.abort_frame();
audio.finish_frame();
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(false);
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
}
#[test]
fn prefix_flush_preserves_quota_and_combined_delivery_is_bounded() {
let mut audio = audio();
for _ in 0..MAX_COMMANDS_PER_FRAME {
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
audio.begin_lifecycle();
for _ in 0..MAX_COMMANDS_PER_FRAME {
assert_eq!(audio.stop(1), AudioOpStatus::Ok);
}
assert_eq!(audio.stop(1), AudioOpStatus::CommandLimit);
audio.finish_lifecycle(true);
let delivery = audio.transport.try_take().unwrap().lifecycle.unwrap();
assert_eq!(delivery.len(), 2 * MAX_COMMANDS_PER_FRAME);
assert!(matches!(delivery[0], AudioCommand::Stop { voice_id: 0 }));
assert!(matches!(delivery[MAX_COMMANDS_PER_FRAME], AudioCommand::Stop { voice_id: 1 }));
assert_eq!(audio.stop(0), AudioOpStatus::CommandLimit);
// Resume and another pause must not replenish the interrupted frame quota.
for _ in 0..2 {
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(true);
audio.transport.consume_silently();
assert_eq!(audio.stop(0), AudioOpStatus::CommandLimit);
}
audio.finish_frame();
assert!(audio.transport.try_take().unwrap().frame.is_none());
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
#[test]
fn failed_callback_cancels_unpublished_prefix_and_its_sample_reference() {
let mut audio = audio();
let sample = Arc::new(Sample::new(48_000, vec![1]));
let weak = Arc::downgrade(&sample);
audio.play_sample(sample, 0, 255, 0, 1.0, 0, LoopMode::On);
audio.begin_lifecycle();
audio.stop(0);
audio.finish_lifecycle(false);
audio.finish_frame();
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
assert!(weak.upgrade().is_none());
}
}
@@ -0,0 +1,144 @@
use super::AudioCommand;
use std::sync::{Arc, Mutex};
/// One pending frame plus an independent lifecycle lane. Control state never
/// competes with guest commands for capacity. The lifecycle batch can include
/// an interrupted frame prefix (at most 1024 + 1024 commands). Only one consumer
/// may drain it.
#[derive(Clone, Default)]
pub struct AudioTransport(Arc<Mutex<Mailbox>>);
#[derive(Default)]
struct Mailbox {
epoch: u64,
paused: bool,
frame: Option<Vec<AudioCommand>>,
lifecycle: Option<Vec<AudioCommand>>,
recycled: [Option<Vec<AudioCommand>>; 4],
}
pub struct AudioDelivery {
pub epoch: u64,
pub paused: bool,
pub frame: Option<Vec<AudioCommand>>,
pub lifecycle: Option<Vec<AudioCommand>>,
}
impl AudioTransport {
/// The real-time consumer never waits for the producer's short critical section.
pub fn try_take(&self) -> Option<AudioDelivery> {
let mut state = self.0.try_lock().ok()?;
Some(AudioDelivery {
epoch: state.epoch,
paused: state.paused,
frame: state.frame.take(),
lifecycle: state.lifecycle.take(),
})
}
pub fn consume_silently(&self) {
if let Some(delivery) = self.try_take() {
for batch in [delivery.frame, delivery.lifecycle].into_iter().flatten() {
self.recycle_commands(batch);
}
}
}
/// Main/service lane only: drop command owners and retain bounded empty storage.
pub fn recycle_commands(&self, mut commands: Vec<AudioCommand>) {
commands.clear();
let mut state = self.0.lock().expect("audio mailbox");
if let Some(slot) = state.recycled.iter_mut().find(|slot| slot.is_none()) {
*slot = Some(commands);
}
// Excess empty buffers are destroyed here, never in the data callback.
}
pub(super) fn take_buffer(&self) -> Vec<AudioCommand> {
self.0
.lock()
.expect("audio mailbox")
.recycled
.iter_mut()
.find_map(Option::take)
.unwrap_or_default()
}
pub fn ready(&self) -> bool {
let state = self.0.lock().expect("audio mailbox");
state.frame.is_none() && state.lifecycle.is_none()
}
pub fn lifecycle_ready(&self) -> bool {
self.0.lock().expect("audio mailbox").lifecycle.is_none()
}
pub(super) fn publish(&self, commands: Vec<AudioCommand>, lifecycle: bool) {
if commands.is_empty() {
return;
}
let mut state = self.0.lock().expect("audio mailbox");
let target = if lifecycle { &mut state.lifecycle } else { &mut state.frame };
assert!(target.is_none(), "audio producer must respect backpressure");
*target = Some(commands);
}
pub(super) fn reset(&self) {
let mut state = self.0.lock().expect("audio mailbox");
state.epoch = state.epoch.checked_add(1).expect("audio epoch exhausted");
state.frame = None;
state.lifecycle = None;
state.paused = false;
}
pub(super) fn set_paused(&self, paused: bool) {
self.0.lock().expect("audio mailbox").paused = paused;
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn realtime_consumer_does_not_wait_for_publication_lock() {
let transport = AudioTransport::default();
let guard = transport.0.lock().unwrap();
assert!(transport.try_take().is_none());
drop(guard);
assert!(transport.try_take().is_some());
}
}
#[cfg(test)]
mod reuse_tests {
use super::*;
#[test]
fn service_recycles_storage_and_releases_sample_owners() {
use prometeu_hal::{LoopMode, sample::Sample};
let transport = AudioTransport::default();
let sample = Arc::new(Sample::new(48000, vec![1]));
let weak = Arc::downgrade(&sample);
let mut batch = Vec::with_capacity(1024);
let allocation = batch.as_ptr();
batch.push(AudioCommand::Play {
sample,
voice_id: 0,
volume: 255,
pan: 0,
pitch: 1.0,
priority: 0,
loop_mode: LoopMode::Off,
});
transport.recycle_commands(batch);
assert!(weak.upgrade().is_none());
let reused = transport.take_buffer();
assert_eq!(reused.as_ptr(), allocation);
assert_eq!(reused.capacity(), 1024);
assert!(reused.is_empty());
for _ in 0..8 {
transport.recycle_commands(Vec::with_capacity(16));
}
assert_eq!(transport.0.lock().unwrap().recycled.iter().flatten().count(), 4);
}
}
@@ -560,9 +560,7 @@ mod tests {
let mut bank =
GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
bank.palette_mut(palette_id).unwrap()[1] = color;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
bank.pixel_indices.fill(1);
bank
}
+28 -20
View File
@@ -12,7 +12,7 @@ use prometeu_hal::cartridge::AssetsPayloadSource;
use prometeu_hal::sprite::Sprite;
use prometeu_hal::{
AssetBridge, AudioBridge, InputPlatform, NoopTelemetryPlatform, PadBridge, RenderBackend,
RuntimePlatform, TelemetryPlatform, TouchBridge,
RuntimePlatform, TelemetryPlatform, TouchBridge, WallClock,
};
use prometeu_hal::{
Game2DFrameComposer, Game2DFramePacket, RenderSubmission, RenderSubmissionPacket,
@@ -33,6 +33,7 @@ use std::sync::Arc;
/// - **Audio**: Stereo, Command-based mixing.
/// - **Input**: 12-button Digital Gamepad + Absolute Touch/Mouse.
pub struct Hardware {
wall_clock: Arc<dyn WallClock>,
/// Shared physical memory bank ownership used by peripherals and worker backends.
pub memory_banks: Arc<MemoryBanks>,
/// The Graphics Processing Unit (GPU). Handles drawing primitives, sprites, and tilemaps.
@@ -49,12 +50,6 @@ pub struct Hardware {
pub assets: AssetManager,
}
impl Default for Hardware {
fn default() -> Self {
Self::new()
}
}
impl Hardware {
fn consume_render_submission(&mut self, submission: &RenderSubmission) {
match &submission.packet {
@@ -159,6 +154,10 @@ impl InputPlatform for Hardware {
static NOOP_TELEMETRY: NoopTelemetryPlatform = NoopTelemetryPlatform;
impl RuntimePlatform for Hardware {
fn wall_clock(&self) -> &dyn WallClock {
self.wall_clock.as_ref()
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self
}
@@ -207,12 +206,15 @@ impl Hardware {
pub const H: usize = 270;
/// Creates a fresh hardware instance with default settings.
pub fn new() -> Self {
Self::new_with_memory_banks(Arc::new(MemoryBanks::new()))
pub fn new(wall_clock: Arc<dyn WallClock>) -> Self {
Self::new_with_memory_banks(Arc::new(MemoryBanks::new()), wall_clock)
}
/// Creates hardware with explicit shared bank ownership.
pub fn new_with_memory_banks(memory_banks: Arc<MemoryBanks>) -> Self {
pub fn new_with_memory_banks(
memory_banks: Arc<MemoryBanks>,
wall_clock: Arc<dyn WallClock>,
) -> Self {
let assets = AssetManager::new(
vec![],
AssetsPayloadSource::empty(),
@@ -222,6 +224,7 @@ impl Hardware {
);
let glyph_slot_index = assets.glyph_asset_slot_index();
Self {
wall_clock,
memory_banks: Arc::clone(&memory_banks),
gfx: Gfx::new(
Self::W,
@@ -266,9 +269,7 @@ mod tests {
fn make_glyph_bank() -> GlyphBank {
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
bank.palette_mut(0).unwrap()[1] = Color::RED;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
bank.pixel_indices.fill(1);
bank
}
@@ -306,7 +307,10 @@ mod tests {
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
banks.install_scene_bank(0, Arc::new(make_scene_with_glyph_asset_id(0)));
let mut hardware = Hardware::new_with_memory_banks(Arc::clone(&banks));
let mut hardware = Hardware::new_with_memory_banks(
Arc::clone(&banks),
Arc::new(crate::ControlledWallClock::default()),
);
let scene = banks.scene_bank_slot(0).expect("scene bank slot 0 should be resident");
let mut cache = SceneViewportCache::new(&scene, 4, 4);
cache.materialize_all_layers(&scene);
@@ -325,7 +329,8 @@ mod tests {
let banks = Arc::new(MemoryBanks::new());
banks.install_scene_bank(2, Arc::new(make_scene()));
let hardware = Hardware::new_with_memory_banks(banks);
let hardware =
Hardware::new_with_memory_banks(banks, Arc::new(crate::ControlledWallClock::default()));
let scene = hardware
.frame_composer
.scene_bank_slot(2)
@@ -342,7 +347,8 @@ mod tests {
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
banks.install_scene_bank(0, Arc::new(make_scene_with_glyph_asset_id(0)));
let mut hardware = Hardware::new_with_memory_banks(banks);
let mut hardware =
Hardware::new_with_memory_banks(banks, Arc::new(crate::ControlledWallClock::default()));
let mut glyph_slots = [None; 16];
glyph_slots[0] = Some(0);
hardware.assets.glyph_asset_slot_index().rebuild_from_slots(&glyph_slots);
@@ -372,7 +378,8 @@ mod tests {
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
banks.install_scene_bank(0, Arc::new(make_scene_with_glyph_asset_id(0)));
let mut hardware = Hardware::new_with_memory_banks(banks);
let mut hardware =
Hardware::new_with_memory_banks(banks, Arc::new(crate::ControlledWallClock::default()));
let mut glyph_slots = [None; 16];
glyph_slots[0] = Some(0);
hardware.assets.glyph_asset_slot_index().rebuild_from_slots(&glyph_slots);
@@ -413,7 +420,7 @@ mod tests {
#[test]
fn render_submission_sink_accepts_owned_game2d_submission() {
let mut hardware = Hardware::new();
let mut hardware = Hardware::new(Arc::new(crate::ControlledWallClock::default()));
let packet = Game2DFramePacket::new(
ComposerFramePacket::default(),
vec![Gfx2dCommand::Clear { color: Color::BLUE }],
@@ -428,7 +435,7 @@ mod tests {
#[test]
fn render_submission_sink_accepts_owned_shell_ui_submission() {
let mut hardware = Hardware::new();
let mut hardware = Hardware::new(Arc::new(crate::ControlledWallClock::default()));
let packet = ShellUiFramePacket::new(vec![GfxUiCommand::Clear { color: Color::RED }]);
let submission = RenderSubmission::shell_ui(FrameId::ZERO, packet);
@@ -442,7 +449,8 @@ mod tests {
fn emit_sprite_rejects_palette_id_outside_loaded_glyph_bank() {
let banks = Arc::new(MemoryBanks::new());
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
let mut hardware = Hardware::new_with_memory_banks(banks);
let mut hardware =
Hardware::new_with_memory_banks(banks, Arc::new(crate::ControlledWallClock::default()));
let status = Game2DFrameComposer::emit_sprite(
&mut hardware,
+8 -1
View File
@@ -8,9 +8,13 @@ mod memory_banks;
mod pad;
mod test_platform;
mod touch;
mod wall_clock;
pub use crate::asset::AssetManager;
pub use crate::audio::{Audio, AudioCommand, Channel, MAX_CHANNELS, OUTPUT_SAMPLE_RATE};
pub use crate::audio::{
Audio, AudioCommand, AudioDelivery, AudioTransport, Channel, MAX_CHANNELS,
MAX_COMMANDS_PER_FRAME, OUTPUT_SAMPLE_RATE,
};
pub use crate::frame_composer::{ComposerBuffer, FrameComposer, SceneStatus, SpriteController};
pub use crate::gfx::Gfx;
pub use crate::local_render_backend::LocalFramebufferRenderBackend;
@@ -20,3 +24,6 @@ pub use crate::memory_banks::{
};
pub use crate::pad::Pad;
pub use crate::test_platform::TestPlatform;
pub use crate::wall_clock::ControlledWallClock;
pub mod memcard;
@@ -0,0 +1,119 @@
//! File-host implementation. IO runs only on the shared worker, never the guest lane.
use prometeu_hal::memcard::{MemcardIoError as Error, MemcardStorage};
use std::fs::{File, OpenOptions};
use std::io::{Read, Seek, SeekFrom, Write};
use std::path::Path;
pub struct FileMemcard {
file: File,
length: u64,
read_only: bool,
}
fn io_error(e: std::io::Error) -> Error {
use std::io::ErrorKind as K;
match e.kind() {
K::NotFound => Error::Unavailable,
K::PermissionDenied => Error::ReadOnly,
K::StorageFull => Error::NoSpace,
K::InvalidInput | K::UnexpectedEof => Error::InvalidRange,
K::Unsupported => Error::Unsupported,
_ => Error::IoError,
}
}
impl FileMemcard {
pub fn open(path: &Path, read_only: bool) -> Result<Self, Error> {
let file = OpenOptions::new().read(true).write(!read_only).open(path).map_err(io_error)?;
let length = file.metadata().map_err(io_error)?.len();
Ok(Self { file, length, read_only })
}
/// Write every byte and verify allocated blocks before formatting/publication.
/// The initializer supplies the runtime-owned format. Existing files are never replaced.
#[cfg(unix)]
pub fn create(
path: &Path,
length: u64,
initialize: impl FnOnce(&mut dyn MemcardStorage, [u8; 16]) -> Result<(), Error>,
) -> Result<Self, Error> {
use std::os::unix::fs::MetadataExt;
let mut id = [0; 16];
File::open("/dev/urandom").and_then(|mut f| f.read_exact(&mut id)).map_err(io_error)?;
let parent =
path.parent().filter(|p| !p.as_os_str().is_empty()).unwrap_or_else(|| Path::new("."));
let suffix: String = id.iter().map(|b| format!("{b:02x}")).collect();
let temporary = parent.join(format!(".memcard-{suffix}.tmp"));
let file = OpenOptions::new()
.read(true)
.write(true)
.create_new(true)
.open(&temporary)
.map_err(io_error)?;
let result = (|| {
let mut card = Self { file, length, read_only: false };
let zeros = [0u8; 65_536];
let mut offset = 0;
while offset < length {
let n = (length - offset).min(zeros.len() as u64) as usize;
card.file.write_all(&zeros[..n]).map_err(io_error)?;
offset += n as u64;
}
card.sync()?;
if card.file.metadata().map_err(io_error)?.blocks().saturating_mul(512) < length {
return Err(Error::Unsupported);
}
initialize(&mut card, id)?;
card.sync()?;
// hard_link publishes without replacing a user file; parent sync makes the name durable.
std::fs::hard_link(&temporary, path).map_err(io_error)?;
File::open(parent).and_then(|f| f.sync_all()).map_err(io_error)?;
Ok(card)
})();
let cleanup =
std::fs::remove_file(&temporary).and_then(|()| File::open(parent)?.sync_all());
match result {
Ok(card) => {
cleanup.map_err(io_error)?;
Ok(card)
}
Err(e) => Err(e),
}
}
#[cfg(not(unix))]
pub fn create(
_path: &Path,
_length: u64,
_initialize: impl FnOnce(&mut dyn MemcardStorage, [u8; 16]) -> Result<(), Error>,
) -> Result<Self, Error> {
Err(Error::Unsupported)
}
fn check(&self, offset: u64, length: usize) -> Result<(), Error> {
if length > 65_536 || offset.checked_add(length as u64).is_none_or(|end| end > self.length)
{
return Err(Error::InvalidRange);
}
Ok(())
}
}
impl MemcardStorage for FileMemcard {
fn len(&self) -> Result<u64, Error> {
Ok(self.length)
}
fn read_only(&self) -> bool {
self.read_only
}
fn read_at(&mut self, offset: u64, target: &mut [u8]) -> Result<(), Error> {
self.check(offset, target.len())?;
self.file.seek(SeekFrom::Start(offset)).map_err(io_error)?;
self.file.read_exact(target).map_err(io_error)
}
fn write_at(&mut self, offset: u64, source: &[u8]) -> Result<(), Error> {
if self.read_only {
return Err(Error::ReadOnly);
}
self.check(offset, source.len())?;
self.file.seek(SeekFrom::Start(offset)).map_err(io_error)?;
self.file.write_all(source).map_err(io_error)
}
fn sync(&mut self) -> Result<(), Error> {
self.file.sync_all().map_err(io_error)
}
}
@@ -1,13 +1,15 @@
use crate::ControlledWallClock;
use crate::hardware::Hardware;
use crate::memory_banks::MemoryBanks;
use prometeu_hal::{
AssetBridge, AudioBridge, Game2DFrameComposer, InputPlatform, RenderBackend,
RenderSubmissionSink, RuntimePlatform, TelemetryPlatform,
RenderSubmissionSink, RuntimePlatform, TelemetryPlatform, WallClock,
};
use std::sync::Arc;
pub struct TestPlatform {
hardware: Hardware,
controlled_wall_clock: Option<Arc<ControlledWallClock>>,
}
impl Default for TestPlatform {
@@ -18,11 +20,24 @@ impl Default for TestPlatform {
impl TestPlatform {
pub fn new() -> Self {
Self { hardware: Hardware::new() }
Self::new_with_memory_banks(Arc::new(MemoryBanks::new()))
}
pub fn new_with_memory_banks(memory_banks: Arc<MemoryBanks>) -> Self {
Self { hardware: Hardware::new_with_memory_banks(memory_banks) }
let clock = Arc::new(ControlledWallClock::default());
Self {
hardware: Hardware::new_with_memory_banks(memory_banks, clock.clone()),
controlled_wall_clock: Some(clock),
}
}
pub fn new_with_wall_clock(clock: Arc<dyn WallClock>) -> Self {
Self { hardware: Hardware::new(clock), controlled_wall_clock: None }
}
/// Native controls for the default clock. Injected providers are controlled by their owner.
pub fn controlled_wall_clock(&self) -> Option<&ControlledWallClock> {
self.controlled_wall_clock.as_deref()
}
pub fn local_hardware(&self) -> &Hardware {
@@ -35,6 +50,10 @@ impl TestPlatform {
}
impl RuntimePlatform for TestPlatform {
fn wall_clock(&self) -> &dyn WallClock {
self.hardware.wall_clock()
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self.hardware.render_submission_sink()
}
@@ -93,8 +112,26 @@ mod tests {
Game2DFramePacket::default(),
))
.expect("test platform render sink should accept local submission");
assert!(!platform.audio().is_playing(0));
assert!(platform.audio().ready());
assert!(!platform.input().pad().any());
assert!(platform.telemetry().telemetry_snapshot().is_none());
}
#[test]
fn selected_clock_is_shared_with_hardware_and_can_be_injected() {
let platform = TestPlatform::new();
assert_eq!(platform.wall_clock().utc_unix_seconds(), 0);
let clock = platform.controlled_wall_clock().expect("default controls");
clock.set(42);
assert_eq!(platform.local_hardware().wall_clock().utc_unix_seconds(), 42);
clock.advance(3);
assert_eq!(platform.wall_clock().utc_unix_seconds(), 45);
let custom = Arc::new(ControlledWallClock::new(900));
let platform = TestPlatform::new_with_wall_clock(custom.clone());
assert!(platform.controlled_wall_clock().is_none());
assert_eq!(platform.wall_clock().utc_unix_seconds(), 900);
custom.set(7);
assert_eq!(platform.local_hardware().wall_clock().utc_unix_seconds(), 7);
}
}
@@ -0,0 +1,57 @@
use prometeu_hal::WallClock;
use std::sync::atomic::{AtomicU64, Ordering};
/// A native harness-controlled civil clock. Reads and runtime ticks never advance it.
#[derive(Debug, Default)]
pub struct ControlledWallClock {
seconds: AtomicU64,
}
impl ControlledWallClock {
pub fn new(seconds: u64) -> Self {
Self { seconds: AtomicU64::new(seconds) }
}
/// Set civil time explicitly, including backwards adjustments.
pub fn set(&self, seconds: u64) {
self.seconds.store(seconds, Ordering::Relaxed);
}
/// Advance civil time explicitly, saturating at the largest timestamp.
pub fn advance(&self, seconds: u64) {
// Harness control may retry on a concurrent update; reads remain a single load.
let _ = self.seconds.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
Some(current.saturating_add(seconds))
});
}
}
impl WallClock for ControlledWallClock {
fn utc_unix_seconds(&self) -> u64 {
self.seconds.load(Ordering::Relaxed)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn explicit_changes_allow_regression_and_saturate_without_advancing_on_read() {
let clock = ControlledWallClock::default();
assert_eq!(clock.utc_unix_seconds(), 0);
clock.set(100);
for _ in 0..10 {
assert_eq!(clock.utc_unix_seconds(), 100);
}
clock.advance(9);
assert_eq!(clock.utc_unix_seconds(), 109);
clock.set(3);
assert_eq!(clock.utc_unix_seconds(), 3);
clock.advance(u64::MAX);
clock.advance(1);
assert_eq!(clock.utc_unix_seconds(), u64::MAX);
clock.set(0);
assert_eq!(clock.utc_unix_seconds(), 0);
}
}
@@ -12,3 +12,4 @@ prometeu-hal = { path = "../prometeu-hal" }
[dev-dependencies]
prometeu-drivers = { path = "../prometeu-drivers" }
prometeu-bytecode = { path = "../prometeu-bytecode" }
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
@@ -3,12 +3,16 @@ use crate::firmware::firmware_state::{
FirmwareState, GameRunningStep, LoadCartridgeStep, ResetStep,
};
use crate::firmware::prometeu_context::PrometeuContext;
#[cfg(test)]
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::Cartridge;
use prometeu_hal::log::LogSource;
use prometeu_hal::telemetry::CertificationConfig;
use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_system::{PrometeuHub, ResidentGameState, SystemOS};
#[cfg(test)]
use prometeu_test_support::program::{TestProgram, int64_signature};
/// PROMETEU Firmware.
///
@@ -57,6 +61,56 @@ impl Firmware {
/// This method is called exactly once per Host frame (60Hz).
/// It updates peripheral signals and delegates the logic to the current state.
pub fn tick(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
self.sync_audio(platform);
self.tick_inner(signals, platform);
self.sync_audio(platform);
}
fn sync_audio(&mut self, platform: &mut dyn RuntimePlatform) {
let task = self.os.lifecycle().resident_game_task().map(|task| task.0);
let suspended = matches!(
self.os.lifecycle().resident_game().map(|game| game.state),
Some(ResidentGameState::PausedSuspended)
);
let paused = self.game_lifecycle_audio_paused() || self.os.vm().paused();
platform.audio_mut().set_session(task);
platform.audio_mut().set_paused(paused);
// Without a pause hook the OS can suspend synchronously, bypassing the
// callback runner. Complete the same audio boundary before resuming.
// A real hook already published its prefix; repeating an empty flush is inert.
if suspended && platform.audio().lifecycle_ready() {
platform.audio_mut().begin_lifecycle();
platform.audio_mut().finish_lifecycle(true);
}
}
fn tick_inner(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
self.os.poll_background_io(platform);
if self.os.memcard().host_faulted() {
// Keep the resident VM, snapshots, and worker-owned buffers alive. A
// stuck host operation cannot be repaired by launching another worker.
self.state = FirmwareState::MemoryIoFault;
self.state_initialized = true;
self.on_update(signals, platform);
return;
}
if self.os.memcard().session.removal_pending()
&& let Some(task) = self.os.lifecycle().resident_game_task()
{
if self.os.lifecycle().task_state(task)
== Some(prometeu_system::task::TaskState::Suspended)
{
if !matches!(
self.state,
FirmwareState::MemoryCardRemoved(_) | FirmwareState::ConfirmDiscard(_)
) {
self.state = FirmwareState::MemoryCardRemoved(Default::default());
self.state_initialized = true;
}
} else {
self.request_home_from_host();
}
}
let barriered_signals = InputSignals::default();
let effective_signals = if self.game_input_barrier_frames > 0 {
self.game_input_barrier_frames -= 1;
@@ -79,6 +133,40 @@ impl Firmware {
self.state_initialized = true;
}
// Hooks run after leaving gameplay and before completing OS suspension/resume.
if let Some((task_id, result)) = self.os.vm().poll_pending_lifecycle(platform) {
if let Err(report) = result {
let _ = self.os.lifecycle().crash_task(task_id, Some(&report));
self.change_state(
FirmwareState::AppCrashes(crate::firmware::firmware_state::AppCrashesStep {
report,
}),
effective_signals,
platform,
);
} else if matches!(self.state, FirmwareState::GameRunning(_))
&& matches!(
self.os.lifecycle().task_state(task_id),
Some(
prometeu_system::task::TaskState::Suspended
| prometeu_system::task::TaskState::Closed
)
)
{
self.os.vm().transition_render_owner(AppMode::Shell, 0);
let state = match self.os.lifecycle().foreground_owner() {
prometeu_system::ForegroundOwner::Shell(task_id) => {
FirmwareState::ShellRunning(
crate::firmware::firmware_state::ShellRunningStep::new(task_id),
)
}
_ => FirmwareState::HubHome(crate::firmware::firmware_state::HubHomeStep),
};
self.change_state(state, effective_signals, platform);
}
return;
}
// 3. Update the current state and check for transitions.
if let Some(next_state) = self.on_update(effective_signals, platform) {
self.change_state(next_state, effective_signals, platform);
@@ -129,8 +217,10 @@ impl Firmware {
FirmwareState::SplashScreen(s) => s.on_enter(&mut req),
FirmwareState::LaunchHub(s) => s.on_enter(&mut req),
FirmwareState::HubHome(s) => s.on_enter(&mut req),
FirmwareState::ConfirmDiscard(s) => s.on_enter(&mut req),
FirmwareState::MemoryCardRemoved(s) => s.on_enter(&mut req),
FirmwareState::LoadCartridge(s) => s.on_enter(&mut req),
FirmwareState::ResumeResidentGame => {}
FirmwareState::ResumeResidentGame | FirmwareState::MemoryIoFault => {}
FirmwareState::GameRunning(s) => s.on_enter(&mut req),
FirmwareState::ShellRunning(s) => s.on_enter(&mut req),
FirmwareState::AppCrashes(s) => s.on_enter(&mut req),
@@ -156,8 +246,32 @@ impl Firmware {
FirmwareState::SplashScreen(s) => s.on_update(&mut req),
FirmwareState::LaunchHub(s) => s.on_update(&mut req),
FirmwareState::HubHome(s) => s.on_update(&mut req),
FirmwareState::ConfirmDiscard(s) => s.on_update(&mut req),
FirmwareState::MemoryCardRemoved(s) => s.on_update(&mut req),
FirmwareState::LoadCartridge(s) => s.on_update(&mut req),
FirmwareState::ResumeResidentGame => None,
FirmwareState::MemoryIoFault => {
use prometeu_hal::color::Color;
use prometeu_hal::{FrameId, GfxUiCommand, RenderSubmission, ShellUiFramePacket};
let lines = [
"Memory-card IO did not stop in time.",
"Save outcome may be unknown.",
"Restart the host before using storage again.",
];
let mut commands = vec![GfxUiCommand::Clear { color: Color::BLACK }];
commands.extend(lines.into_iter().enumerate().map(|(i, text)| {
GfxUiCommand::DrawText {
x: 8,
y: 8 + i as i32 * 20,
text: text.into(),
color: Color::WHITE,
}
}));
let _ = req.platform.render_submission_sink().submit_render_submission(
RenderSubmission::shell_ui(FrameId::ZERO, ShellUiFramePacket::new(commands)),
);
None
}
FirmwareState::GameRunning(s) => s.on_update(&mut req),
FirmwareState::ShellRunning(s) => s.on_update(&mut req),
FirmwareState::AppCrashes(s) => s.on_update(&mut req),
@@ -178,8 +292,10 @@ impl Firmware {
FirmwareState::SplashScreen(s) => s.on_exit(&mut req),
FirmwareState::LaunchHub(s) => s.on_exit(&mut req),
FirmwareState::HubHome(s) => s.on_exit(&mut req),
FirmwareState::ConfirmDiscard(s) => s.on_exit(&mut req),
FirmwareState::MemoryCardRemoved(s) => s.on_exit(&mut req),
FirmwareState::LoadCartridge(s) => s.on_exit(&mut req),
FirmwareState::ResumeResidentGame => {}
FirmwareState::ResumeResidentGame | FirmwareState::MemoryIoFault => {}
FirmwareState::GameRunning(s) => s.on_exit(&mut req),
FirmwareState::ShellRunning(s) => s.on_exit(&mut req),
FirmwareState::AppCrashes(s) => s.on_exit(&mut req),
@@ -252,7 +368,7 @@ mod tests {
use crate::firmware::firmware_state::HubHomeStep;
use crate::firmware::resident_game_termination::{self, ResidentGameTerminationOutcome};
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, FunctionMeta, SyscallDecl};
use prometeu_bytecode::model::SyscallDecl;
use prometeu_drivers::{GlyphBankPoolAccess, SceneBankPoolAccess, TestPlatform};
use prometeu_hal::RuntimePlatform;
use prometeu_hal::app_mode::AppMode;
@@ -345,13 +461,18 @@ mod tests {
fn halting_program() -> Vec<u8> {
let code = assemble("HALT").expect("assemble");
BytecodeModule {
version: 0,
TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
..Default::default()
signature: int64_signature(0, 0),
captures: vec![],
name: None,
local_slots: 0,
max_stack_slots: 256,
}],
code,
debug_info: None,
@@ -367,6 +488,7 @@ mod tests {
fn invalid_game_cartridge() -> Cartridge {
Cartridge {
memcard_slots: None,
app_id: 7,
title: "Broken Cart".into(),
app_version: "1.0.0".into(),
@@ -381,13 +503,18 @@ mod tests {
fn trapping_game_cartridge() -> Cartridge {
let code = assemble("PUSH_BOOL 1\nHOSTCALL 0\nHALT").expect("assemble");
let program = BytecodeModule {
version: 0,
let program = TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
..Default::default()
signature: int64_signature(0, 0),
captures: vec![],
name: None,
local_slots: 0,
max_stack_slots: 256,
}],
code,
debug_info: None,
@@ -403,6 +530,7 @@ mod tests {
.serialize();
Cartridge {
memcard_slots: None,
app_id: 8,
title: "Trap Cart".into(),
app_version: "1.0.0".into(),
@@ -421,6 +549,7 @@ mod tests {
fn valid_cartridge_with(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
Cartridge {
memcard_slots: None,
app_id,
title: title.into(),
app_version: "1.0.0".into(),
@@ -485,6 +614,15 @@ mod tests {
platform.local_hardware().gfx.front_buffer()[index]
}
fn wait_for_cartridge_preload(firmware: &mut Firmware, platform: &mut TestPlatform) {
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(2);
while matches!(firmware.state, FirmwareState::LoadCartridge(_)) {
assert!(std::time::Instant::now() < deadline, "cartridge admission did not complete");
firmware.tick(&InputSignals::default(), platform);
std::thread::yield_now();
}
}
#[test]
fn load_cartridge_transitions_to_app_crashes_when_vm_init_fails() {
let mut firmware = Firmware::new(None);
@@ -497,7 +635,7 @@ mod tests {
match &firmware.state {
FirmwareState::AppCrashes(step) => match &step.report {
CrashReport::VmInit { error } => {
assert!(matches!(error, prometeu_vm::VmInitError::InvalidFormat));
assert!(matches!(error, prometeu_vm::VmInitError::RegistryLoadFailed(_)));
}
other => panic!("expected VmInit crash report, got {:?}", other),
},
@@ -681,7 +819,10 @@ mod tests {
root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let signals = InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
@@ -702,7 +843,10 @@ mod tests {
root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let signals = InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
@@ -720,7 +864,10 @@ mod tests {
root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let launch_click =
@@ -775,7 +922,10 @@ mod tests {
root.add_game_with_identity("zzz-dummy", 43, "Zzz Dummy", "1.0.0", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
@@ -836,7 +986,10 @@ mod tests {
#[test]
fn repository_stress_to_dummy_boy_switch_is_end_to_end() {
let library = discover_games_root(repository_test_cartridges_root());
let library = discover_games_root(
repository_test_cartridges_root(),
&prometeu_drivers::ControlledWallClock::default(),
);
assert!(
library
.entries()
@@ -856,6 +1009,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -954,6 +1108,7 @@ mod tests {
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&stress_click, &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
assert_eq!(firmware.os.lifecycle().task_state(dummy_task), Some(TaskState::Closed));
assert_eq!(
firmware.os.lifecycle().process_state_for_task(dummy_task),
@@ -1024,7 +1179,10 @@ mod tests {
#[test]
fn resident_game_termination_closes_session_and_cleans_runtime_state() {
let library = discover_games_root(repository_test_cartridges_root());
let library = discover_games_root(
repository_test_cartridges_root(),
&prometeu_drivers::ControlledWallClock::default(),
);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(library);
firmware.tick(&InputSignals::default(), &mut platform);
@@ -1034,6 +1192,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -1109,7 +1268,10 @@ mod tests {
#[test]
fn hub_kill_control_click_terminates_resident_game_and_stays_home() {
let library = discover_games_root(repository_test_cartridges_root());
let library = discover_games_root(
repository_test_cartridges_root(),
&prometeu_drivers::ControlledWallClock::default(),
);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(library);
firmware.tick(&InputSignals::default(), &mut platform);
@@ -1119,6 +1281,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -1201,7 +1364,10 @@ mod tests {
root.add_game_with_program("zzz-broken", 43, "Zzz Broken", "1.0.0", Some(vec![0, 0, 0, 0]));
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
@@ -1267,7 +1433,8 @@ mod tests {
root.add_game("broken", false);
let (mut firmware, mut platform) = hub_home_firmware();
let library = discover_games_root(&root.path);
let library =
discover_games_root(&root.path, &prometeu_drivers::ControlledWallClock::default());
assert!(library.is_empty());
assert!(!library.diagnostics().is_empty());
firmware.hub.set_game_library(library);
@@ -1307,7 +1474,10 @@ mod tests {
let cart = root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
fs::remove_file(cart.join("program.pbx")).expect("program should be removable");
firmware.tick(&InputSignals::default(), &mut platform);
@@ -1674,4 +1844,458 @@ mod tests {
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
assert_eq!(firmware.os.vm().current_cartridge_title(), "Valid Cart");
}
fn lifecycle_cartridge(pause: &str, resume: &str) -> Cartridge {
use prometeu_bytecode::registry::LifecycleRole;
let mut program = TestProgram::single(
assemble("FRAME_SYNC\nJMP 0").unwrap(),
int64_signature(0, 0),
0,
8,
);
for (role, source) in
[(LifecycleRole::BeforePause, pause), (LifecycleRole::BeforeResume, resume)]
{
if source.is_empty() {
continue;
}
let code = assemble(source).unwrap();
program.functions.push(FunctionDecl {
lifecycle_role: role,
code_offset: program.code.len() as u32,
code_len: code.len() as u32,
max_stack_slots: 8,
..Default::default()
});
program.code.extend(code);
}
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.program = program.serialize();
cartridge
}
fn load_lifecycle(pause: &str, resume: &str) -> (Firmware, TestPlatform, TaskId) {
let mut firmware = Firmware::new(None);
let mut platform = TestPlatform::new();
firmware.load_cartridge(lifecycle_cartridge(pause, resume));
firmware.tick(&InputSignals::default(), &mut platform);
let task = firmware.os.lifecycle().resident_game_task().unwrap();
(firmware, platform, task)
}
fn check_audio_lifecycle(partial: bool, hooks: bool) {
use prometeu_bytecode::registry::LifecycleRole;
use prometeu_drivers::AudioCommand;
let mut program = TestProgram::single(
assemble("PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\nFRAME_SYNC\nJMP 0").unwrap(),
int64_signature(0, 0),
0,
8,
);
program.syscalls.push(SyscallDecl {
module: "audio".into(),
name: "stop".into(),
version: 1,
arg_slots: 1,
ret_slots: 1,
});
for (role, voice) in [(LifecycleRole::BeforePause, 1), (LifecycleRole::BeforeResume, 2)] {
if !hooks {
continue;
}
let code = assemble(&format!("PUSH_I32 {voice}\nHOSTCALL 0\nPOP_N 1\nRET")).unwrap();
program.functions.push(FunctionDecl {
lifecycle_role: role,
code_offset: program.code.len() as u32,
code_len: code.len() as u32,
max_stack_slots: 8,
..Default::default()
});
program.code.extend(code);
}
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.capabilities = caps::AUDIO;
cartridge.program = program.serialize();
let mut fw = Firmware::new(None);
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
fw.load_cartridge(cartridge);
fw.tick(&signals, &mut platform);
if partial {
for _ in 0..2 {
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
}
} else {
fw.tick(&signals, &mut platform);
}
let task = fw.os.lifecycle().resident_game_task().unwrap();
let transport = platform.local_hardware().audio.transport();
assert_eq!(platform.audio().ready(), partial);
fw.os.lifecycle().suspend_task(task).unwrap();
fw.tick(&signals, &mut platform);
let delivery = transport.try_take().unwrap();
assert!(delivery.paused);
if partial {
assert!(delivery.frame.is_none());
} else {
assert!(matches!(delivery.frame.unwrap()[0], AudioCommand::Stop { voice_id: 0 }));
}
let lifecycle = delivery.lifecycle.unwrap_or_default();
assert_eq!(lifecycle.len(), usize::from(partial) + usize::from(hooks));
if partial {
assert!(matches!(lifecycle[0], AudioCommand::Stop { voice_id: 0 }));
}
if hooks {
assert!(matches!(lifecycle[usize::from(partial)], AudioCommand::Stop { voice_id: 1 }));
}
assert!(fw.resume_resident_game_from_home());
fw.tick(&signals, &mut platform);
let delivery = transport.try_take().unwrap();
assert!(!delivery.paused);
if hooks {
assert!(matches!(delivery.lifecycle.unwrap()[0], AudioCommand::Stop { voice_id: 2 }));
} else {
assert!(delivery.lifecycle.is_none());
assert!(delivery.frame.is_none(), "hookless resume completed the prefix-free frame");
}
let epoch = delivery.epoch;
fw.tick(&signals, &mut platform);
if partial && hooks {
assert!(
platform.audio().ready(),
"prefix must not be published again at frame completion"
);
fw.tick(&signals, &mut platform);
}
assert!(!platform.audio().ready());
fw.change_state(FirmwareState::Reset(ResetStep), &signals, &mut platform);
let delivery = transport.try_take().unwrap();
assert!(delivery.epoch > epoch);
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
assert!(platform.audio().ready());
}
#[test]
fn audio_lifecycle_publishes_with_pending_frame_and_reset_invalidates_session() {
check_audio_lifecycle(false, true);
}
#[test]
fn audio_lifecycle_publishes_interrupted_frame_prefix_before_hook() {
check_audio_lifecycle(true, true);
}
#[test]
fn audio_lifecycle_flushes_prefix_when_optional_hooks_are_absent() {
check_audio_lifecycle(true, false);
}
#[test]
fn lifecycle_home_resume_callbacks_are_outside_frames_and_preserve_pc() {
let (mut fw, mut platform, task) = load_lifecycle("RET", "RET");
let signals = InputSignals::default();
assert!(!fw.os.lifecycle().advance_game_pause_budget(task).unwrap());
assert!(fw.os.vm().poll_pending_lifecycle(&mut platform).is_none());
fw.request_home_from_host();
fw.tick(&signals, &mut platform); // existing handoff tick
let pc = fw.os.vm().active_pc();
let ticks = vm_session_tick_index(&mut fw, task);
let frames = fw.os.vm().completed_logical_frames();
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground));
fw.tick(&signals, &mut platform); // BeforePause only
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
assert_eq!(fw.os.vm().active_pc(), pc);
assert_eq!(vm_session_tick_index(&mut fw, task), ticks);
assert!(fw.resume_resident_game_from_home());
fw.tick(&signals, &mut platform); // BeforeResume only
assert_eq!(fw.os.vm().active_pc(), pc);
assert_eq!(vm_session_tick_index(&mut fw, task), ticks);
assert_eq!(fw.os.vm().completed_logical_frames(), frames);
assert_eq!(fw.os.lifecycle().resident_game().unwrap().state, ResidentGameState::Foreground);
fw.tick(&signals, &mut platform);
assert_eq!(vm_session_tick_index(&mut fw, task), ticks + 1);
}
#[test]
fn lifecycle_direct_suspend_and_shell_handoff_wait_for_callback() {
let (mut fw, mut platform, task) = load_lifecycle("RET", "RET");
fw.os.lifecycle().suspend_task(task).unwrap();
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground));
fw.tick(&InputSignals::default(), &mut platform);
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
assert!(fw.resume_resident_game_from_home());
fw.tick(&InputSignals::default(), &mut platform);
let shell = fw.os.sessions().try_create_native_shell_task(99, "Tools").unwrap();
assert_eq!(fw.os.lifecycle().foreground_owner(), ForegroundOwner::Game(task));
fw.tick(&InputSignals::default(), &mut platform);
assert_eq!(fw.os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
}
#[test]
fn lifecycle_debugger_retains_budget_and_steps_without_game_frames() {
let (mut fw, mut platform, task) = load_lifecycle("PUSH_I32 7\nSET_GLOBAL 0\nRET", "RET");
fw.os.lifecycle().suspend_task(task).unwrap();
let offset = assemble("FRAME_SYNC\nJMP 0").unwrap().len();
fw.os.vm().insert_active_breakpoint(offset);
fw.tick(&InputSignals::default(), &mut platform);
assert!(fw.os.vm().paused());
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground));
let remaining =
fw.os.sessions().vm_session_for_task(task).unwrap().vm.lifecycle_remaining_cycles();
fw.tick(&InputSignals::default(), &mut platform);
assert_eq!(
fw.os.sessions().vm_session_for_task(task).unwrap().vm.lifecycle_remaining_cycles(),
remaining
);
for _ in 0..3 {
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
}
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
}
#[test]
fn lifecycle_faults_exhaustion_and_halt_never_resume_gameplay() {
for body in ["FRAME_SYNC\nRET", "JMP 0", "HALT"] {
let (mut fw, mut platform, task) = load_lifecycle(body, "RET");
fw.os.lifecycle().suspend_task(task).unwrap();
for _ in 0..8 {
fw.tick(&InputSignals::default(), &mut platform);
if fw.os.lifecycle().task_state(task) != Some(TaskState::Foreground) {
break;
}
}
if body == "HALT" {
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Closed));
assert!(matches!(fw.state, FirmwareState::HubHome(_)));
} else {
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Crashed));
let FirmwareState::AppCrashes(step) = &fw.state else { panic!("expected crash") };
assert!(step.report.to_string().contains("BeforePause"));
}
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
}
}
#[test]
fn lifecycle_debugger_hostcalls_use_real_session_handles() {
use prometeu_bytecode::registry::LifecycleRole;
let main = assemble("FRAME_SYNC\nJMP 0").unwrap();
let mut program = TestProgram::single(main, int64_signature(0, 0), 0, 8);
let hook =
assemble("PUSH_CONST 0\nHOSTCALL 0\nPOP_N 1\nPUSH_I32 42\nHOSTCALL 1\nRET").unwrap();
program
.const_pool
.push(prometeu_bytecode::model::ConstantPoolEntry::String("/missing".into()));
program.syscalls.push(SyscallDecl {
module: "fs".into(),
name: "open".into(),
version: 1,
arg_slots: 1,
ret_slots: 1,
});
program.functions.push(FunctionDecl {
lifecycle_role: LifecycleRole::BeforePause,
code_offset: program.code.len() as u32,
code_len: hook.len() as u32,
max_stack_slots: 8,
..Default::default()
});
program.code.extend(hook);
program.syscalls.push(SyscallDecl {
module: "fs".into(),
name: "close".into(),
version: 1,
arg_slots: 1,
ret_slots: 0,
});
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.capabilities = caps::FS;
cartridge.program = program.serialize();
let mut fw = Firmware::new(None);
let mut platform = TestPlatform::new();
fw.load_cartridge(cartridge);
fw.tick(&InputSignals::default(), &mut platform);
let task = fw.os.lifecycle().resident_game_task().unwrap();
fw.os
.sessions()
.vm_session_for_task_mut(task)
.unwrap()
.open_files
.insert(42, "/save".into());
fw.os.lifecycle().suspend_task(task).unwrap();
fw.os.vm().set_paused(true);
assert_eq!(
fw.os.sessions().vm_session_for_task(task).unwrap().fs_state,
prometeu_system::fs::FsState::Unmounted
);
// fs.open returns an ordinary error value on this unmounted session.
for _ in 0..6 {
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
}
assert!(fw.os.sessions().vm_session_for_task(task).unwrap().open_files.is_empty());
let pc = fw.os.vm().active_pc();
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
assert_eq!(fw.os.vm().active_pc(), pc);
assert!(fw.os.vm().tick_session(task, &InputSignals::default(), &mut platform).is_none());
assert_eq!(fw.os.vm().active_pc(), pc);
fw.tick(&InputSignals::default(), &mut platform);
assert!(matches!(fw.state, FirmwareState::HubHome(_)));
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
}
#[test]
fn lifecycle_resume_failure_blocks_gameplay_and_conflicting_pause_request() {
let (mut fw, mut platform, task) = load_lifecycle("RET", "FRAME_SYNC\nRET");
fw.os.lifecycle().suspend_task(task).unwrap();
fw.tick(&InputSignals::default(), &mut platform);
assert!(fw.resume_resident_game_from_home());
assert!(fw.os.lifecycle().request_home_from_game(task).is_err());
assert!(fw.os.lifecycle().suspend_task(task).is_err());
fw.tick(&InputSignals::default(), &mut platform);
let FirmwareState::AppCrashes(step) = &fw.state else { panic!("expected failure") };
assert!(step.report.to_string().contains("BeforeResume"));
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
}
#[test]
fn lifecycle_roles_are_independently_optional() {
for (pause, resume) in [("", "RET"), ("RET", "")] {
let (mut fw, mut platform, task) = load_lifecycle(pause, resume);
fw.request_home_from_host();
for _ in 0..2 {
fw.tick(&InputSignals::default(), &mut platform);
}
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
assert!(fw.resume_resident_game_from_home());
fw.tick(&InputSignals::default(), &mut platform);
assert_eq!(
fw.os.lifecycle().resident_game().unwrap().state,
ResidentGameState::Foreground
);
}
}
#[test]
fn memory_only_admission_runs_typed_guest_boot_and_warns_before_discard() {
for debug in [false, true] {
use prometeu_bytecode::{
load_limits::LoadBudget,
model::{ConstantPoolEntry, SyscallDecl},
registry::{
LifecycleRole, NamedType, Registry, RegistryDeclarations, Signature, TypeDecl,
TypeId, TypeKind,
},
registry_codec::PbxModule,
};
let boot = assemble("HOSTCALL 0\nPOP_N 1\nFRAME_SYNC\nJMP 12").unwrap();
let hook=assemble("PUSH_I64 560\nARRAY_NEW 9\nSET_GLOBAL 0\nGET_LOCAL 0\nPUSH_CONST 0\nPUSH_I32 1\nPUSH_I32 1\nPUSH_I32 1\nGET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 560\nHOSTCALL 1\nPOP_N 1\nGET_LOCAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 560\nHOSTCALL 2\nPOP_N 2\nGET_LOCAL 0\nPUSH_I32 0\nHOSTCALL 3\nPOP_N 2\nPUSH_I32 0\nRET").unwrap();
let mut code = boot.clone();
code.extend(&hook);
let mut types = prometeu_test_support::program::scalar_catalog();
types.push(TypeDecl { name: None, kind: TypeKind::Array(TypeId(1)) });
let registry = Registry::resolve(
RegistryDeclarations {
types,
functions: vec![
FunctionDecl {
code_len: boot.len() as u32,
max_stack_slots: 16,
..Default::default()
},
FunctionDecl {
lifecycle_role: LifecycleRole::MemcardBoot,
code_offset: boot.len() as u32,
code_len: hook.len() as u32,
max_stack_slots: 16,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![TypeId(1)],
},
..Default::default()
},
],
implementations: vec![],
},
code.len(),
&mut LoadBudget::new(Default::default()),
)
.unwrap();
let syscalls = [
("bootstrap", 0, 1),
("presentation", 8, 1),
("slot_write", 6, 2),
("slot_commit", 2, 2),
]
.map(|(name, arg_slots, ret_slots)| SyscallDecl {
module: "mem".into(),
name: name.into(),
version: 1,
arg_slots,
ret_slots,
});
let constants = [ConstantPoolEntry::String("Guest save".into())];
let program = PbxModule {
registry: &registry,
code: &code,
constants: &constants,
debug: None,
exports: &[],
syscalls: &syscalls,
}
.serialize(&mut LoadBudget::new(Default::default()))
.unwrap();
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.program = program;
cartridge.memcard_slots = Some(1);
cartridge.capabilities = prometeu_hal::syscalls::caps::MEMCARD;
let mut firmware = Firmware::new(None);
let mut platform = TestPlatform::new();
firmware.load_cartridge(cartridge);
firmware.tick(&InputSignals::default(), &mut platform);
assert!(matches!(firmware.state, FirmwareState::LoadCartridge(_)));
firmware.tick(&InputSignals { x_signal: true, ..Default::default() }, &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
if debug {
firmware.os.vm().set_paused(true);
for _ in 0..80 {
assert!(firmware.os.vm().debug_step_active_session(&mut platform).is_none());
if !firmware.os.memcard().session.is_boot_active() {
break;
}
}
assert!(!firmware.os.memcard().session.is_boot_active());
firmware.os.vm().set_paused(false);
}
for _ in 0..4 {
firmware.tick(&InputSignals::default(), &mut platform);
}
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
let session = &mut firmware.os.memcard().session;
let context = session.context();
assert_eq!(session.mode(), Some(prometeu_system::memcard::session::Mode::MemoryOnly));
assert_eq!(session.presentation(context).unwrap().unwrap().title, "Guest save");
assert_eq!(session.descriptor(context, 0).unwrap().1, 560);
assert!(session.unsaved());
firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform);
firmware.change_state(
FirmwareState::ConfirmDiscard(
super::super::firmware_state::ConfirmDiscardStep::new(None),
),
&InputSignals::default(),
&mut platform,
);
firmware.tick(&InputSignals::default(), &mut platform);
firmware.tick(&InputSignals { b_signal: true, ..Default::default() }, &mut platform);
assert!(firmware.os.memcard().session.unsaved());
firmware.change_state(
FirmwareState::ConfirmDiscard(
super::super::firmware_state::ConfirmDiscardStep::new(None),
),
&InputSignals::default(),
&mut platform,
);
firmware.tick(&InputSignals::default(), &mut platform);
firmware.tick(&InputSignals { a_signal: true, ..Default::default() }, &mut platform);
assert_eq!(firmware.os.memcard().session.mode(), None);
}
}
}
@@ -1,3 +1,4 @@
pub use crate::firmware::firmware_step_confirm_discard::ConfirmDiscardStep;
pub use crate::firmware::firmware_step_crash_screen::AppCrashesStep;
pub use crate::firmware::firmware_step_game_running::GameRunningStep;
pub use crate::firmware::firmware_step_hub_home::HubHomeStep;
@@ -13,8 +14,11 @@ pub enum FirmwareState {
SplashScreen(SplashScreenStep),
LaunchHub(LaunchHubStep),
HubHome(HubHomeStep),
ConfirmDiscard(ConfirmDiscardStep),
LoadCartridge(LoadCartridgeStep),
ResumeResidentGame,
MemoryIoFault,
MemoryCardRemoved(super::firmware_step_confirm_discard::MemoryCardRemovedStep),
GameRunning(GameRunningStep),
ShellRunning(ShellRunningStep),
AppCrashes(AppCrashesStep),
@@ -0,0 +1,101 @@
use super::{
firmware_state::{FirmwareState, HubHomeStep, LoadCartridgeStep},
prometeu_context::PrometeuContext,
resident_game_termination,
};
use prometeu_hal::{
FrameId, GfxUiCommand, RenderSubmission, ShellUiFramePacket, cartridge::Cartridge, color::Color,
};
/// Player-owned exit decision. It never starts a save implicitly.
#[derive(Debug, Clone)]
pub struct ConfirmDiscardStep {
next: Option<Cartridge>,
released: bool,
}
impl ConfirmDiscardStep {
pub fn new(next: Option<Cartridge>) -> Self {
Self { next, released: false }
}
pub fn on_enter(&mut self, _ctx: &mut PrometeuContext) {}
pub fn on_exit(&mut self, _ctx: &mut PrometeuContext) {}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
let lines = [
"Unsaved progress",
"Leaving this game will discard RAM saves.",
"A: Discard and leave",
"B: Return to Home without leaving the game",
];
let mut commands = vec![GfxUiCommand::Clear { color: Color::BLACK }];
commands.extend(lines.into_iter().enumerate().map(|(i, text)| GfxUiCommand::DrawText {
x: 8,
y: 8 + i as i32 * 20,
text: text.into(),
color: Color::WHITE,
}));
let _ = ctx.platform.render_submission_sink().submit_render_submission(
RenderSubmission::shell_ui(FrameId::ZERO, ShellUiFramePacket::new(commands)),
);
if !ctx.signals.a_signal && !ctx.signals.b_signal {
self.released = true;
}
if self.released && ctx.signals.b_signal {
return Some(FirmwareState::HubHome(HubHomeStep));
}
if self.released && ctx.signals.a_signal {
if resident_game_termination::terminate_resident_game(ctx.os, ctx.platform, true)
.is_err()
{
return None;
}
return Some(match self.next.take() {
Some(card) => {
FirmwareState::LoadCartridge(LoadCartridgeStep::new_game_switch(card))
}
None => FirmwareState::HubHome(HubHomeStep),
});
}
None
}
}
#[derive(Debug, Clone, Default)]
pub struct MemoryCardRemovedStep {
released: bool,
}
impl MemoryCardRemovedStep {
pub fn on_enter(&mut self, _ctx: &mut PrometeuContext) {}
pub fn on_exit(&mut self, _ctx: &mut PrometeuContext) {}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
if !ctx.os.memcard().session.removal_pending() {
return Some(FirmwareState::HubHome(HubHomeStep));
}
let lines = [
"Memory card is unavailable.",
"Progress remains in memory.",
"Reinsert a card through the host, or choose:",
"A: Continue without saving to disk",
"B: Leave the game",
];
let mut commands = vec![GfxUiCommand::Clear { color: Color::BLACK }];
commands.extend(lines.into_iter().enumerate().map(|(i, text)| GfxUiCommand::DrawText {
x: 8,
y: 8 + i as i32 * 20,
text: text.into(),
color: Color::WHITE,
}));
let _ = ctx.platform.render_submission_sink().submit_render_submission(
RenderSubmission::shell_ui(FrameId::ZERO, ShellUiFramePacket::new(commands)),
);
if !ctx.signals.a_signal && !ctx.signals.b_signal {
self.released = true;
}
if self.released && ctx.signals.a_signal && ctx.os.detach_memcard().is_ok() {
return Some(FirmwareState::ResumeResidentGame);
}
if self.released && ctx.signals.b_signal {
return Some(FirmwareState::ConfirmDiscard(ConfirmDiscardStep::new(None)));
}
None
}
}
@@ -23,7 +23,21 @@ impl AppCrashesStep {
// Update peripherals for input on the crash screen
ctx.platform.input_mut().pad_mut().begin_frame(ctx.signals);
let packet = ShellUiFramePacket::new(vec![GfxUiCommand::Clear { color: Color::RED }]);
let mut commands = vec![GfxUiCommand::Clear { color: Color::RED }];
if let CrashReport::VmPanic { message, .. } = &self.report
&& message.starts_with("Memcard")
{
let text: Vec<char> = message.chars().take(240).collect();
commands.extend(text.chunks(48).enumerate().map(|(line, chars)| {
GfxUiCommand::DrawText {
x: 8,
y: 8 + line as i32 * 20,
text: chars.iter().collect(),
color: Color::WHITE,
}
}));
}
let packet = ShellUiFramePacket::new(commands);
ctx.platform
.render_submission_sink()
.submit_render_submission(RenderSubmission::shell_ui(FrameId::ZERO, packet))
@@ -55,6 +69,7 @@ mod tests {
message: "type mismatch".into(),
pc: 0x44,
span: None,
resource: None,
},
},
};
@@ -27,6 +27,15 @@ impl GameRunningStep {
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
};
if matches!(task_state, TaskState::Suspended | TaskState::Closed) {
ctx.os.vm().transition_render_owner(AppMode::Shell, 0);
return Some(match ctx.os.lifecycle().foreground_owner() {
prometeu_system::ForegroundOwner::Shell(task_id) => FirmwareState::ShellRunning(
crate::firmware::firmware_state::ShellRunningStep::new(task_id),
),
_ => FirmwareState::HubHome(HubHomeStep),
});
}
if task_state != TaskState::Foreground {
// TODO: is it panic?
let report = CrashReport::VmPanic {
@@ -56,6 +56,16 @@ impl HubHomeStep {
Some(SystemProfileAction::LaunchGame { target }) => {
match CartridgeLoader::load(&target.path) {
Ok(cartridge) => {
if ctx.os.lifecycle().resident_game_task().is_none()
&& ctx.os.memcard().session.mode().is_some()
{
if ctx.os.memcard().session.unsaved() {
return Some(FirmwareState::ConfirmDiscard(
super::firmware_state::ConfirmDiscardStep::new(Some(cartridge)),
));
}
ctx.os.memcard().session.end_session();
}
if cartridge.app_mode == AppMode::Game
&& let Some(resident_task_id) = ctx.os.lifecycle().resident_game_task()
{
@@ -70,6 +80,11 @@ impl HubHomeStep {
return Some(FirmwareState::ResumeResidentGame);
}
if ctx.os.memcard().session.unsaved() {
return Some(FirmwareState::ConfirmDiscard(
super::firmware_state::ConfirmDiscardStep::new(Some(cartridge)),
));
}
if let Err(error) = resident_game_termination::terminate_resident_game(
ctx.os,
ctx.platform,
@@ -107,6 +122,12 @@ impl HubHomeStep {
}
}
Some(SystemProfileAction::KillResidentGame) => {
if ctx.os.memcard().session.unsaved() {
return Some(FirmwareState::ConfirmDiscard(
super::firmware_state::ConfirmDiscardStep::new(None),
));
}
if let Err(error) =
resident_game_termination::terminate_resident_game(ctx.os, ctx.platform, true)
{
@@ -15,6 +15,10 @@ use prometeu_system::windows::WindowOwner;
pub struct LoadCartridgeStep {
pub cartridge: Cartridge,
init_error: Option<CrashReport>,
awaiting_memcard: bool,
preparing_memcard: bool,
input_released: bool,
memcard_message: String,
loaded_task_id: Option<prometeu_system::task::TaskId>,
loaded_app_mode: Option<AppMode>,
failure_recovery: LoadCartridgeFailureRecovery,
@@ -31,12 +35,20 @@ impl LoadCartridgeStep {
Self {
cartridge,
init_error: None,
awaiting_memcard: false,
preparing_memcard: false,
input_released: false,
memcard_message: String::new(),
loaded_task_id: None,
loaded_app_mode: None,
failure_recovery: LoadCartridgeFailureRecovery::AppCrash,
}
}
pub fn needs_memcard_choice(&self) -> bool {
self.awaiting_memcard && !self.preparing_memcard
}
pub fn new_game_switch(cartridge: Cartridge) -> Self {
Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) }
}
@@ -51,6 +63,15 @@ impl LoadCartridgeStep {
ctx.platform.game2d_frame_composer().unbind_scene();
if self.cartridge.app_mode == AppMode::Game && self.cartridge.memcard_slots.is_some() {
self.awaiting_memcard = true;
ctx.os.vm().transition_render_owner(AppMode::Shell, 0);
return;
}
self.load(ctx);
}
fn load(&mut self, ctx: &mut PrometeuContext) {
// Initialize Asset Manager
ctx.platform.assets_mut().initialize_for_cartridge(
self.cartridge.asset_table.clone(),
@@ -70,6 +91,58 @@ impl LoadCartridgeStep {
}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
if self.awaiting_memcard {
use prometeu_system::memcard::admission::{Choice, PreparationState};
if self.preparing_memcard {
match ctx.os.memcard().admission.state {
PreparationState::Ready => {
self.awaiting_memcard = false;
self.preparing_memcard = false;
self.load(ctx);
}
PreparationState::Failed(error) => {
self.memcard_message = Self::preparation_message(error);
self.preparing_memcard = false;
}
_ => {}
}
}
if self.awaiting_memcard {
let pressed = ctx.signals.a_signal
|| ctx.signals.b_signal
|| ctx.signals.x_signal
|| ctx.signals.y_signal;
if !pressed {
self.input_released = true;
}
if self.input_released && pressed && !self.preparing_memcard {
self.input_released = false;
if ctx.signals.b_signal {
return Some(FirmwareState::HubHome(HubHomeStep));
}
let choice = if ctx.signals.a_signal {
Choice::Persistent
} else if ctx.signals.x_signal {
Choice::MemoryFresh
} else {
Choice::MemoryExisting
};
let created_at = ctx.platform.wall_clock().utc_unix_seconds();
match ctx.os.memcard().choose_for_game(
self.cartridge.app_id,
self.cartridge.memcard_slots.unwrap() as usize,
choice,
created_at,
) {
Ok(()) => self.preparing_memcard = true,
Err(error) => self.memcard_message = Self::preparation_message(error),
}
}
self.draw_memcard(ctx);
return None;
}
}
if let Some(report) = self.init_error.take() {
if self.failure_recovery == LoadCartridgeFailureRecovery::ReturnToHub {
if self.cartridge.app_mode == AppMode::Game
@@ -106,6 +179,18 @@ impl LoadCartridgeStep {
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
}
match ctx.platform.assets().preloads_ready() {
Ok(false) => return None,
Err(error) => {
return Some(FirmwareState::AppCrashes(AppCrashesStep {
report: CrashReport::VmPanic {
message: format!("Cartridge preload failed: {error:?}"),
pc: None,
},
}));
}
Ok(true) => {}
}
let Some(task_id) = self.loaded_task_id.take() else {
let report = CrashReport::VmPanic {
message: format!(
@@ -131,5 +216,67 @@ impl LoadCartridgeStep {
Some(FirmwareState::GameRunning(GameRunningStep::new(task_id)))
}
fn preparation_message(error: prometeu_system::memcard::image::Error) -> String {
use prometeu_system::memcard::image::Error;
match error {
Error::NoSpace => "This memory card has no room for this game.".into(),
Error::Corrupt => "The memory card failed its integrity checks.".into(),
Error::ReadOnly => "This memory card cannot accept saves.".into(),
Error::OutOfMemory => "There is not enough memory to start this game.".into(),
Error::Busy => "The memory card is still busy. Please wait.".into(),
Error::InvalidState => "No usable memory card or existing save is available.".into(),
_ => format!("Memory card unavailable: {error:?}"),
}
}
fn draw_memcard(&self, ctx: &mut PrometeuContext) {
use prometeu_hal::{FrameId, GfxUiCommand, RenderSubmission, ShellUiFramePacket};
let installed = ctx.os.memcard().card_installed();
let existing = ctx.os.memcard().card_has_game(self.cartridge.app_id);
let mut lines = vec!["Save memory".to_string(), self.cartridge.title.clone()];
if let Some((recovered, degraded, blocked)) = ctx.os.memcard().installed_health() {
if recovered {
lines.push("Recovered an older save after an integrity failure.".into());
}
if degraded {
lines.push("Memory card degraded: some blocks are excluded.".into());
}
if blocked {
lines.push("Disk saving is unavailable on this card.".into());
}
}
if let prometeu_system::memcard::admission::PreparationState::Failed(error) =
ctx.os.memcard().admission.state
{
lines.push(Self::preparation_message(error));
}
if self.preparing_memcard {
lines.push("Preparing save memory...".into());
} else {
lines.push(
if installed { "A: Use installed memory card" } else { "No memory card installed" }
.into(),
);
lines.push("X: Start fresh without saving to disk".into());
if existing {
lines.push("Y: Load saves, then play without disk saving".into());
}
lines.push("B: Return to Home".into());
}
if !self.memcard_message.is_empty() {
lines.push(self.memcard_message.clone());
}
let mut commands = vec![GfxUiCommand::Clear { color: Color::BLACK }];
commands.extend(lines.into_iter().enumerate().map(|(i, text)| GfxUiCommand::DrawText {
x: 8,
y: 8 + i as i32 * 20,
text,
color: Color::WHITE,
}));
let _ = ctx.platform.render_submission_sink().submit_render_submission(
RenderSubmission::shell_ui(FrameId::ZERO, ShellUiFramePacket::new(commands)),
);
}
pub fn on_exit(&mut self, _ctx: &mut PrometeuContext) {}
}
@@ -15,6 +15,8 @@ impl ResetStep {
let _ = ctx.os.lifecycle().terminate_resident_game();
ctx.os.sessions().clear_vm_sessions();
ctx.os.vm().reset_global_runtime_state();
ctx.platform.audio_mut().reset();
ctx.platform.audio_mut().set_session(None);
}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
@@ -18,3 +18,5 @@ pub use boot_target::BootTarget;
pub use firmware::Firmware;
pub use firmware_state::FirmwareState;
pub use prometeu_context::PrometeuContext;
pub(crate) mod firmware_step_confirm_discard;
@@ -16,6 +16,7 @@ pub(crate) fn terminate_resident_game(
log_manual_hub_kill: bool,
) -> Result<ResidentGameTerminationOutcome, LifecycleError> {
let Some(task_id) = os.lifecycle().resident_game_task() else {
os.memcard().session.end_session();
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
};
@@ -30,6 +31,8 @@ pub(crate) fn terminate_resident_game(
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
};
os.memcard().session.end_session();
platform.audio_mut().set_session(None);
os.vm().transition_render_owner(AppMode::Shell, 0);
platform.game2d_frame_composer().unbind_scene();
platform.assets_mut().shutdown();
@@ -6,12 +6,25 @@ use crate::asset::{
use crate::cartridge::AssetsPayloadSource;
pub trait AssetBridge {
/// Bind before cartridge preload/loading. Hosts supporting memcard must use
/// this same lane for assets; an unsupported bridge refuses the fast profile.
fn bind_background_work(
&mut self,
_lane: std::sync::Arc<dyn crate::background_work::BackgroundWork>,
) -> bool {
false
}
fn initialize_for_cartridge(
&self,
assets: Vec<AssetEntry>,
preload: Vec<PreloadEntry>,
assets_data: AssetsPayloadSource,
);
/// Admission waits until all preloads are installed. Failure blocks guest boot.
fn preloads_ready(&self) -> Result<bool, AssetLoadError> {
Ok(true)
}
fn load(&self, asset_id: AssetId, slot_index: usize) -> Result<HandleId, AssetLoadError>;
fn status(&self, handle: HandleId) -> LoadStatus;
fn commit(&self, handle: HandleId) -> AssetOpStatus;
@@ -17,6 +17,7 @@ pub enum AudioOpStatus {
AssetNotFound = 4,
NoEffect = 5,
BankInvalid = 6,
CommandLimit = 7,
}
pub trait AudioBridge {
@@ -43,10 +44,22 @@ pub trait AudioBridge {
priority: u8,
loop_mode: LoopMode,
) -> AudioOpStatus;
fn stop(&mut self, voice_id: usize);
fn set_volume(&mut self, voice_id: usize, volume: u8);
fn set_pan(&mut self, voice_id: usize, pan: u8);
fn set_pitch(&mut self, voice_id: usize, pitch: f64);
fn is_playing(&self, voice_id: usize) -> bool;
fn clear_commands(&mut self);
fn stop(&mut self, voice_id: usize) -> AudioOpStatus;
fn set_volume(&mut self, voice_id: usize, volume: u8) -> AudioOpStatus;
fn set_pan(&mut self, voice_id: usize, pan: u8) -> AudioOpStatus;
fn set_pitch(&mut self, voice_id: usize, pitch: f64) -> AudioOpStatus;
/// Pending publication must be consumed before starting another guest frame.
fn ready(&self) -> bool;
fn begin_frame(&mut self);
fn finish_frame(&mut self);
fn abort_frame(&mut self);
/// Lifecycle has independent bounded staging/publication, even with a pending frame.
fn lifecycle_ready(&self) -> bool;
fn begin_lifecycle(&mut self);
/// Success publishes the interrupted frame prefix before callback commands,
/// without replenishing frame quota. Failure cancels both unpublished parts.
fn finish_lifecycle(&mut self, success: bool);
fn set_session(&mut self, session: Option<u32>);
fn reset(&mut self);
fn set_paused(&mut self, paused: bool);
}
@@ -0,0 +1,13 @@
//! Portable submission seam for host-owned cooperative IO execution.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WorkStep {
Yield,
Complete,
Failed,
}
pub type AssetWork = Box<dyn FnMut(bool) -> WorkStep + Send + 'static>;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct WorkUnavailable;
pub trait BackgroundWork: Send + Sync {
fn submit_asset(&self, work: AssetWork) -> Result<(), WorkUnavailable>;
}
+46 -4
View File
@@ -3,7 +3,7 @@ use crate::asset::{AssetEntry, PreloadEntry};
use crate::syscalls::CapFlags;
use serde::{Deserialize, Serialize};
use std::fs::File;
use std::io::{self, Cursor, Read, Seek, SeekFrom};
use std::io::{self, Read, Seek, SeekFrom};
use std::path::PathBuf;
use std::sync::Arc;
@@ -18,6 +18,7 @@ pub struct Cartridge {
pub app_version: String,
pub app_mode: AppMode,
pub capabilities: CapFlags,
pub memcard_slots: Option<u8>,
pub program: Vec<u8>,
pub assets: AssetsPayloadSource,
pub asset_table: Vec<AssetEntry>,
@@ -31,6 +32,7 @@ pub struct CartridgeDTO {
pub app_version: String,
pub app_mode: AppMode,
pub capabilities: CapFlags,
pub memcard_slots: Option<u8>,
pub program: Vec<u8>,
pub assets: AssetsPayloadSource,
pub asset_table: Vec<AssetEntry>,
@@ -45,6 +47,7 @@ impl From<CartridgeDTO> for Cartridge {
app_version: dto.app_version,
app_mode: dto.app_mode,
capabilities: dto.capabilities,
memcard_slots: dto.memcard_slots,
program: dto.program,
assets: dto.assets,
asset_table: dto.asset_table,
@@ -125,8 +128,12 @@ impl AssetsPayloadSlice {
pub fn open_reader(&self) -> io::Result<AssetsPayloadReader> {
match self {
Self::Memory { bytes, start, len } => {
let data = Arc::<[u8]>::from(bytes[*start..*start + *len].to_vec());
Ok(AssetsPayloadReader::Memory(Cursor::new(data)))
Ok(AssetsPayloadReader::Memory(MemorySliceReader {
bytes: Arc::clone(bytes),
start: *start,
len: *len,
position: 0,
}))
}
Self::File { source, offset, size } => {
let mut file = File::open(&source.path)?;
@@ -151,7 +158,7 @@ impl AssetsPayloadSlice {
}
pub enum AssetsPayloadReader {
Memory(Cursor<Arc<[u8]>>),
Memory(MemorySliceReader),
File(FileSliceReader),
}
@@ -173,6 +180,37 @@ impl Seek for AssetsPayloadReader {
}
}
pub struct MemorySliceReader {
bytes: Arc<[u8]>,
start: usize,
len: usize,
position: usize,
}
impl Read for MemorySliceReader {
fn read(&mut self, target: &mut [u8]) -> io::Result<usize> {
let n = target.len().min(self.len.saturating_sub(self.position));
target[..n].copy_from_slice(
&self.bytes[self.start + self.position..self.start + self.position + n],
);
self.position += n;
Ok(n)
}
}
impl Seek for MemorySliceReader {
fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
let next = match pos {
SeekFrom::Start(n) => n as i128,
SeekFrom::Current(n) => self.position as i128 + n as i128,
SeekFrom::End(n) => self.len as i128 + n as i128,
};
if next < 0 || next > self.len as i128 {
return Err(invalid_input("slice seek out of bounds"));
}
self.position = next as usize;
Ok(self.position as u64)
}
}
pub struct FileSliceReader {
file: File,
start: u64,
@@ -278,6 +316,7 @@ pub enum CartridgeError {
MissingProgram,
MissingAssets,
IoError,
ProgramLoadFailed(prometeu_bytecode::load_limits::LoadFailure),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize, Serialize)]
@@ -291,6 +330,7 @@ pub enum Capability {
Gfxui,
Audio,
Fs,
Memcard,
Log,
Asset,
Bank,
@@ -307,4 +347,6 @@ pub struct CartridgeManifest {
pub app_mode: AppMode,
#[serde(default)]
pub capabilities: Vec<Capability>,
#[serde(default)]
pub memcard_slots: Option<u8>,
}
@@ -5,6 +5,9 @@ use crate::cartridge::{
CartridgeManifest,
};
use crate::syscalls::{CapFlags, caps};
use prometeu_bytecode::load_limits::{
LoadBudget, LoadFailure, LoadLimits, LoadReason, LoadResource,
};
use std::collections::HashSet;
use std::fs;
use std::io::{Read, Seek, SeekFrom};
@@ -52,13 +55,20 @@ impl DirectoryCartridgeLoader {
}
let capabilities = normalize_capabilities(&manifest.capabilities)?;
if ((capabilities & caps::MEMCARD) != 0) != manifest.memcard_slots.is_some()
|| manifest.memcard_slots.is_some_and(|n| !(1..=64).contains(&n))
{
return Err(CartridgeError::InvalidManifest);
}
let program_path = path.join("program.pbx");
if !program_path.exists() {
return Err(CartridgeError::MissingProgram);
}
let program = fs::read(program_path).map_err(|_| CartridgeError::IoError)?;
let mut program_file = fs::File::open(program_path).map_err(|_| CartridgeError::IoError)?;
let program_len = program_file.metadata().map_err(|_| CartridgeError::IoError)?.len();
let program = read_program(&mut program_file, program_len, LoadLimits::default())?;
let assets_pa_path = path.join("assets.pa");
let (assets, asset_table, preload) = if assets_pa_path.exists() {
@@ -86,6 +96,7 @@ impl DirectoryCartridgeLoader {
app_version: manifest.app_version,
app_mode: manifest.app_mode,
capabilities,
memcard_slots: manifest.memcard_slots,
program,
assets,
asset_table,
@@ -98,6 +109,59 @@ impl DirectoryCartridgeLoader {
pub struct PackedCartridgeLoader;
/// Admit the PBX input separately from parsing scratch. Metadata rejects an
/// oversized file before reservation; bounded reads also cover file growth.
fn read_program(
reader: &mut impl Read,
size_hint: u64,
limits: LoadLimits,
) -> Result<Vec<u8>, CartridgeError> {
let budget = LoadBudget::new(limits);
let limit = budget.limit(LoadResource::PbxBytes);
budget.check(LoadResource::PbxBytes, size_hint).map_err(CartridgeError::ProgramLoadFailed)?;
let resource_error = |reason, requested| {
let mut error = LoadFailure::resource(LoadResource::PbxBytes, requested, limit);
error.reason = reason;
CartridgeError::ProgramLoadFailed(error)
};
let mut out = Vec::<u8>::new();
let initial =
usize::try_from(size_hint).map_err(|_| resource_error(LoadReason::Overflow, size_hint))?;
out.try_reserve_exact(initial)
.map_err(|_| resource_error(LoadReason::Allocation, size_hint))?;
budget
.check(LoadResource::PbxBytes, out.capacity() as u64)
.map_err(CartridgeError::ProgramLoadFailed)?;
let mut chunk = [0u8; 8192];
loop {
// At the ceiling inspect one extra byte without growing the input.
let remaining = limit - out.len() as u64;
let read_len = remaining.min(chunk.len() as u64).max(1) as usize;
let count = match reader.read(&mut chunk[..read_len]) {
Ok(count) => count,
Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
Err(_) => return Err(CartridgeError::IoError),
};
if count == 0 {
return Ok(out);
}
let requested = (out.len() as u64)
.checked_add(count as u64)
.ok_or_else(|| resource_error(LoadReason::Overflow, u64::MAX))?;
budget
.check(LoadResource::PbxBytes, requested)
.map_err(CartridgeError::ProgramLoadFailed)?;
// Reserve exact growth rather than allowing Vec's geometric growth to
// exceed admission. Existing spare capacity is reused without billing twice.
out.try_reserve_exact(count)
.map_err(|_| resource_error(LoadReason::Allocation, requested))?;
budget
.check(LoadResource::PbxBytes, out.capacity() as u64)
.map_err(CartridgeError::ProgramLoadFailed)?;
out.extend_from_slice(&chunk[..count]);
}
}
impl PackedCartridgeLoader {
pub fn load(_path: &Path) -> Result<Cartridge, CartridgeError> {
Err(CartridgeError::InvalidFormat)
@@ -122,6 +186,7 @@ fn normalize_capabilities(capabilities: &[Capability]) -> Result<CapFlags, Cartr
Capability::Gfxui => caps::GFXUI,
Capability::Audio => caps::AUDIO,
Capability::Fs => caps::FS,
Capability::Memcard => caps::MEMCARD,
Capability::Log => caps::LOG,
Capability::Asset => caps::ASSET,
Capability::Bank => caps::BANK,
@@ -204,6 +269,7 @@ mod tests {
use crate::asset::{AssetCodec, AssetEntry, BankType, PreloadEntry};
use crate::cartridge::{ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude};
use crate::glyph_bank::GLYPH_BANK_MAX_PALETTE_COUNT_V1;
use prometeu_bytecode::load_limits::LoadCode;
use serde_json::json;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
@@ -289,6 +355,76 @@ mod tests {
manifest
}
#[test]
fn program_admission_accepts_exact_limit_and_rejects_growth_after_metadata() {
let limits = LoadLimits { pbx_bytes: 3, ..Default::default() };
for hint in [0, 1, 3] {
assert_eq!(read_program(&mut &b"abc"[..], hint, limits).unwrap(), b"abc");
let error = read_program(&mut &b"abcd"[..], hint, limits).unwrap_err();
let CartridgeError::ProgramLoadFailed(error) = error else {
panic!("typed PBX admission failure expected")
};
assert_eq!((error.code, error.reason), (LoadCode::ResourceLimit, LoadReason::Limit));
assert_eq!(
(error.resource, error.requested, error.limit),
(Some(LoadResource::PbxBytes), Some(4), Some(3))
);
}
}
#[test]
fn program_admission_rejects_oversized_metadata_before_reading() {
struct MustNotRead;
impl Read for MustNotRead {
fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
panic!("must reject before reading")
}
}
let limits = LoadLimits { pbx_bytes: 3, ..Default::default() };
assert!(matches!(
read_program(&mut MustNotRead, 4, limits),
Err(CartridgeError::ProgramLoadFailed(_))
));
}
#[test]
fn program_admission_handles_empty_short_and_interrupted_reads() {
assert!(read_program(&mut &[][..], 0, LoadLimits::default()).unwrap().is_empty());
struct ShortReads {
interrupted: bool,
remaining: &'static [u8],
}
impl Read for ShortReads {
fn read(&mut self, bytes: &mut [u8]) -> std::io::Result<usize> {
if !self.interrupted {
self.interrupted = true;
return Err(std::io::ErrorKind::Interrupted.into());
}
if self.remaining.is_empty() {
return Ok(0);
}
bytes[0] = self.remaining[0];
self.remaining = &self.remaining[1..];
Ok(1)
}
}
let mut reader = ShortReads { interrupted: false, remaining: b"abc" };
assert_eq!(read_program(&mut reader, 2, LoadLimits::default()).unwrap(), b"abc");
}
#[test]
fn directory_loader_rejects_oversized_pbx_with_default_limit() {
let dir = TestCartridgeDir::new(manifest_with_capabilities(None));
let file = fs::OpenOptions::new().write(true).open(dir.path().join("program.pbx")).unwrap();
let limit = LoadLimits::default().pbx_bytes;
file.set_len(limit + 1).unwrap(); // Sparse file; no giant content allocation.
let error = DirectoryCartridgeLoader::load(dir.path()).unwrap_err();
let CartridgeError::ProgramLoadFailed(error) = error else {
panic!("typed PBX admission failure expected")
};
assert_eq!((error.requested, error.limit), (Some(limit + 1), Some(64 * 1_048_576)));
}
#[test]
fn load_without_capabilities_defaults_to_none() {
let dir = TestCartridgeDir::new(manifest_with_capabilities(None));
@@ -318,7 +454,9 @@ mod tests {
#[test]
fn load_with_all_capability_normalizes_to_all_flags() {
let dir = TestCartridgeDir::new(manifest_with_capabilities(Some(vec!["all"])));
let mut manifest = manifest_with_capabilities(Some(vec!["all"]));
manifest["memcard_slots"] = serde_json::json!(1);
let dir = TestCartridgeDir::new(manifest);
dir.write_assets_pa(vec![], vec![], &[]);
let cartridge = DirectoryCartridgeLoader::load(dir.path()).expect("cartridge must load");
@@ -1,4 +1,5 @@
use crate::app_mode::AppMode;
#[cfg(test)]
use prometeu_bytecode::Value;
use serde::{Deserialize, Serialize};
@@ -35,7 +36,7 @@ pub enum DebugResponse {
#[serde(rename = "handshake")]
Handshake { protocol_version: u32, runtime_version: String, cartridge: HandshakeCartridge },
#[serde(rename = "getState")]
GetState { pc: usize, stack_top: Vec<Value>, frame_index: u64, app_id: u32 },
GetState { pc: usize, stack_top: crate::ValueSnapshot, frame_index: u64, app_id: u32 },
#[serde(rename = "breakpoints")]
Breakpoints { pcs: Vec<usize> },
}
@@ -78,6 +79,9 @@ pub enum DebugEvent {
pc: Option<u32>,
trap_code: Option<u32>,
opcode: Option<u16>,
span: Option<prometeu_bytecode::SourceSpan>,
resource: Option<prometeu_bytecode::ResourceFailure>,
init: Option<serde_json::Value>,
},
#[serde(rename = "cert")]
Cert { rule: String, used: u64, limit: u64, frame_index: u64 },
@@ -115,7 +119,8 @@ mod tests {
fn test_get_state_serialization() {
let resp = DebugResponse::GetState {
pc: 42,
stack_top: vec![Value::Int64(10), Value::String("test".into()), Value::Boolean(true)],
stack_top: vec![Value::Int64(10), Value::String("test".into()), Value::Boolean(true)]
.into(),
frame_index: 5,
app_id: 1,
};
@@ -136,6 +141,9 @@ mod tests {
pc: Some(12),
trap_code: Some(4),
opcode: Some(0x70),
span: None,
resource: None,
init: None,
};
let json = serde_json::to_string(&event).unwrap();
+271 -10
View File
@@ -1,27 +1,288 @@
use crate::vm_fault::VmFault;
use prometeu_bytecode::{HeapRef, Value};
use std::sync::Arc;
/// Native producers describe their output before materializing guest content.
/// The VM provides the session allocator; HAL does not own guest quotas.
pub trait GuestStringAllocator {
fn byte_limit(&self) -> u64;
fn build(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault>;
}
/// A bounded, call-scoped Array<Int32> byte carrier. Implementations validate
/// concrete array type, every value and all bounds before exposing mutations.
pub trait GuestByteArrays {
fn validate(&mut self, handle: HeapRef, offset: usize, count: usize) -> Result<(), VmFault>;
fn read(&mut self, handle: HeapRef, offset: usize, target: &mut [u8]) -> Result<(), VmFault>;
fn write(&mut self, handle: HeapRef, offset: usize, bytes: &[u8]) -> Result<(), VmFault>;
}
/// Writes only into result slots reserved by the VM. A native handler cannot
/// grow the operand buffer or exceed its declared result count.
pub struct HostReturn<'a> {
stack: &'a mut Vec<Value>,
remaining: usize,
overflowed: bool,
strings: &'a mut dyn GuestStringAllocator,
failure: Option<VmFault>,
arrays: Option<&'a mut dyn GuestByteArrays>,
}
impl<'a> HostReturn<'a> {
pub fn new(stack: &'a mut Vec<Value>) -> Self {
Self { stack }
fn size_overflow(&mut self) -> VmFault {
let error = VmFault::ResourceLimit(prometeu_bytecode::ResourceFailure {
resource: prometeu_bytecode::RuntimeResource::StringBytes,
reason: prometeu_bytecode::ResourceReason::SizeOverflow,
requested: u64::MAX,
limit: self.strings.byte_limit(),
});
self.failure = Some(error.clone());
error
}
pub fn new(
stack: &'a mut Vec<Value>,
result_slots: usize,
strings: &'a mut dyn GuestStringAllocator,
) -> Self {
Self {
stack,
remaining: result_slots,
overflowed: false,
strings,
failure: None,
arrays: None,
}
}
pub fn with_arrays(mut self, arrays: &'a mut dyn GuestByteArrays) -> Self {
self.arrays = Some(arrays);
self
}
pub fn byte_arrays(&mut self) -> Result<&mut (dyn GuestByteArrays + 'a), VmFault> {
self.arrays.as_deref_mut().ok_or(VmFault::Unavailable)
}
pub fn failure(&self) -> Option<&VmFault> {
self.failure.as_ref()
}
pub fn overflowed(&self) -> bool {
self.overflowed
}
fn admit(&mut self) -> bool {
if self.failure.is_some() {
return false;
}
if self.remaining == 0 || self.stack.len() == self.stack.capacity() {
self.overflowed = true;
false
} else {
self.remaining -= 1;
true
}
}
pub fn push_bool(&mut self, v: bool) {
self.stack.push(Value::Boolean(v));
if self.admit() {
self.stack.push(Value::Boolean(v));
}
}
pub fn push_int(&mut self, v: i64) {
self.stack.push(Value::Int64(v));
if self.admit() {
self.stack.push(Value::Int64(v));
}
}
pub fn push_null(&mut self) {
self.stack.push(Value::Null);
if self.admit() {
self.stack.push(Value::Null);
}
}
pub fn push_gate(&mut self, g: usize) {
// Temporary: cast incoming handle/HeapRef index. Real allocator will provide proper handles.
self.stack.push(Value::HeapRef(HeapRef(g as u32)));
/// Return a handle issued by the current session's heap.
pub fn push_gate(&mut self, handle: HeapRef) {
if self.admit() {
self.stack.push(if handle.is_null() { Value::Null } else { Value::HeapRef(handle) });
}
}
pub fn push_string(&mut self, s: String) {
self.stack.push(Value::string(s));
pub fn push_string(&mut self, text: &str) -> Result<(), VmFault> {
self.push_string_with_len(text.len(), &mut |writer| writer.write_str(text))
}
pub fn push_string_with_len(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<(), VmFault> {
if !self.admit() {
return self.failure.clone().map_or(Ok(()), Err);
}
match self.strings.build(length, writer) {
Ok(content) => {
self.stack.push(Value::String(content));
Ok(())
}
Err(error) => {
self.failure = Some(error.clone());
Err(error)
}
}
}
pub fn push_utf8_lossy(&mut self, bytes: &[u8]) -> Result<(), VmFault> {
let mut length = 0usize;
lossy_chunks(bytes, &mut |part| {
length = length.checked_add(part.len()).ok_or(std::fmt::Error)?;
Ok(())
})
.map_err(|_| self.size_overflow())?;
self.push_string_with_len(length, &mut |writer| {
lossy_chunks(bytes, &mut |part| writer.write_str(part))
})
}
pub fn push_hex(&mut self, bytes: &[u8]) -> Result<(), VmFault> {
const HEX: &[u8; 16] = b"0123456789abcdef";
let length = bytes.len().checked_mul(2).ok_or_else(|| self.size_overflow())?;
self.push_string_with_len(length, &mut |writer| {
for &byte in bytes {
let pair = [HEX[(byte >> 4) as usize], HEX[(byte & 15) as usize]];
writer.write_str(std::str::from_utf8(&pair).expect("ASCII hex"))?;
}
Ok(())
})
}
pub fn push_joined<'s, I: Iterator<Item = &'s str> + Clone>(
&mut self,
parts: I,
separator: &str,
) -> Result<(), VmFault> {
let mut length = 0usize;
for (index, part) in parts.clone().enumerate() {
if index > 0 {
length = length.checked_add(separator.len()).ok_or_else(|| self.size_overflow())?;
}
length = length.checked_add(part.len()).ok_or_else(|| self.size_overflow())?;
}
self.push_string_with_len(length, &mut |writer| {
for (index, part) in parts.clone().enumerate() {
if index > 0 {
writer.write_str(separator)?;
}
writer.write_str(part)?;
}
Ok(())
})
}
}
fn lossy_chunks(
mut bytes: &[u8],
emit: &mut dyn FnMut(&str) -> std::fmt::Result,
) -> std::fmt::Result {
while !bytes.is_empty() {
match std::str::from_utf8(bytes) {
Ok(valid) => {
emit(valid)?;
break;
}
Err(error) => {
let valid = error.valid_up_to();
emit(std::str::from_utf8(&bytes[..valid]).expect("validated prefix"))?;
emit("\u{fffd}")?;
match error.error_len() {
Some(invalid) => bytes = &bytes[valid + invalid..],
None => break,
}
}
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
struct RejectStrings;
impl GuestStringAllocator for RejectStrings {
fn byte_limit(&self) -> u64 {
0
}
fn build(
&mut self,
_length: usize,
_writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault> {
panic!("unexpected string allocation")
}
}
#[test]
fn native_results_cannot_grow_the_reserved_buffer_or_exceed_the_signature() {
let mut stack = Vec::with_capacity(8);
let capacity = stack.capacity();
let mut strings = RejectStrings;
let mut ret = HostReturn::new(&mut stack, 1, &mut strings);
ret.push_int(7);
ret.push_int(8);
assert!(ret.overflowed());
assert_eq!(stack, vec![Value::Int64(7)]);
assert_eq!(stack.capacity(), capacity);
let mut empty = Vec::new();
let mut ret = HostReturn::new(&mut empty, 1, &mut strings);
ret.push_null();
assert!(ret.overflowed());
assert!(empty.is_empty());
assert_eq!(empty.capacity(), 0);
}
struct Collect;
impl GuestStringAllocator for Collect {
fn byte_limit(&self) -> u64 {
u64::MAX
}
fn build(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault> {
let mut text = String::new();
writer(&mut text).unwrap();
assert_eq!(text.len(), length);
Ok(Arc::from(text))
}
}
#[test]
fn measured_native_encoding_matches_utf8_lossy_hex_and_join_semantics() {
for bytes in [
b"plain".as_slice(),
"é猫".as_bytes(),
&[0xff, 0xe2, 0x82],
&[0xf0, 0x80, 0x80, 0x80, 0x61, 0xc2, 0xa9],
&[],
] {
let mut stack = Vec::with_capacity(1);
let mut allocator = Collect;
let mut ret = HostReturn::new(&mut stack, 1, &mut allocator);
ret.push_utf8_lossy(bytes).unwrap();
assert_eq!(stack, vec![Value::string(String::from_utf8_lossy(bytes).as_ref())]);
}
for byte in 0..=255u8 {
let bytes = [b'a', byte, b'b', byte];
let mut stack = Vec::with_capacity(1);
let mut allocator = Collect;
HostReturn::new(&mut stack, 1, &mut allocator).push_utf8_lossy(&bytes).unwrap();
assert_eq!(stack, vec![Value::string(String::from_utf8_lossy(&bytes).as_ref())]);
}
let mut stack = Vec::with_capacity(2);
let mut allocator = Collect;
let mut ret = HostReturn::new(&mut stack, 2, &mut allocator);
ret.push_hex(&[0, 0x12, 0xab, 0xff]).unwrap();
ret.push_joined(["", "é", "猫"].into_iter(), ";").unwrap();
assert_eq!(stack, vec![Value::string("0012abff"), Value::string(";é;猫")]);
}
#[test]
fn full_native_result_buffer_does_not_invoke_string_allocator() {
let mut stack = Vec::with_capacity(1);
let mut allocator = RejectStrings;
let mut ret = HostReturn::new(&mut stack, 0, &mut allocator);
ret.push_string("ignored").unwrap();
assert!(ret.overflowed());
assert!(stack.is_empty());
}
}
+6
View File
@@ -2,6 +2,7 @@ pub mod app_mode;
pub mod asset;
pub mod asset_bridge;
pub mod audio_bridge;
pub mod background_work;
pub mod button;
pub mod cartridge;
pub mod cartridge_loader;
@@ -15,6 +16,7 @@ pub mod host_context;
pub mod host_return;
pub mod input_signals;
pub mod log;
pub mod memcard;
pub mod native_helpers;
pub mod native_interface;
pub mod owned_frame;
@@ -36,7 +38,9 @@ pub mod telemetry;
pub mod tile;
pub mod tilemap;
pub mod touch_bridge;
pub mod value_snapshot;
pub mod vm_fault;
pub mod wall_clock;
pub use asset_bridge::AssetBridge;
pub use audio_bridge::{AudioBridge, AudioOpStatus, LoopMode};
@@ -64,3 +68,5 @@ pub use render_worker::{
RenderWorkerBackend, RenderWorkerError, RenderWorkerFrameSink, RenderWorkerTelemetry,
};
pub use touch_bridge::TouchBridge;
pub use value_snapshot::ValueSnapshot;
pub use wall_clock::WallClock;
@@ -0,0 +1,23 @@
//! Host region IO. Logical mapping, checksums and publication belong to the runtime.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemcardIoError {
Unavailable,
ReadOnly,
InvalidRange,
NoSpace,
Unsupported,
IoError,
}
/// Implementations return success only for a complete transfer. Errors may have
/// partial effects. Instances stay owned by their worker until all IO has ceased.
pub trait MemcardStorage: Send {
fn len(&self) -> Result<u64, MemcardIoError>;
fn is_empty(&self) -> Result<bool, MemcardIoError> {
self.len().map(|length| length == 0)
}
fn read_at(&mut self, offset: u64, target: &mut [u8]) -> Result<(), MemcardIoError>;
fn write_at(&mut self, offset: u64, source: &[u8]) -> Result<(), MemcardIoError>;
fn sync(&mut self) -> Result<(), MemcardIoError>;
fn read_only(&self) -> bool;
}
@@ -6,6 +6,7 @@ use crate::render_submission::{Game2DFramePacket, RenderSubmission};
use crate::sprite::Sprite;
use crate::telemetry::TelemetryFrame;
use crate::touch_bridge::TouchBridge;
use crate::wall_clock::WallClock;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RenderSubmitError {
@@ -60,6 +61,8 @@ pub struct NoopTelemetryPlatform;
impl TelemetryPlatform for NoopTelemetryPlatform {}
pub trait RuntimePlatform {
fn wall_clock(&self) -> &dyn WallClock;
fn display_size(&self) -> (usize, usize) {
(480, 270)
}
@@ -11,6 +11,12 @@ pub use resolver::{
resolve_declared_program_syscalls, resolve_program_syscalls, resolve_syscall,
};
/// Native metadata iteration for bounded image binding. This is not guest
/// reflection; callers account comparisons before examining catalogue entries.
pub fn catalogue() -> impl Iterator<Item = &'static SyscallRegistryEntry> {
domains::all_entries()
}
/// Enumeration of all System Calls (Syscalls) available in the Prometeu environment.
///
/// Syscalls are the primary mechanism for a program running in the Virtual Machine
@@ -49,6 +55,10 @@ pub enum Syscall {
ComposerEmitSprite = 0x1104,
AudioPlaySample = 0x3001,
AudioPlay = 0x3002,
AudioStop = 0x3003,
AudioSetVolume = 0x3004,
AudioSetPan = 0x3005,
AudioSetPitch = 0x3006,
FsOpen = 0x4001,
FsRead = 0x4002,
FsWrite = 0x4003,
@@ -56,12 +66,20 @@ pub enum Syscall {
FsListDir = 0x4005,
FsExists = 0x4006,
FsDelete = 0x4007,
MemBootstrap = 0x4200,
MemSlotCount = 0x4201,
MemSlotStat = 0x4202,
MemSlotRead = 0x4203,
MemSlotWrite = 0x4204,
MemSlotCommit = 0x4205,
MemSlotClear = 0x4206,
MemQuery = 0x4207,
MemRelease = 0x4208,
MemInfo = 0x4209,
MemMetadata = 0x420A,
MemPresentation = 0x420B,
MemDiagnostic = 0x420C,
MemPublishPresentation = 0x420D,
LogWrite = 0x5001,
LogWriteTag = 0x5002,
AssetLoad = 0x6001,
@@ -10,5 +10,7 @@ pub const ASSET: CapFlags = 1 << 5;
pub const BANK: CapFlags = 1 << 6;
pub const GFX2D: CapFlags = 1 << 7;
pub const GFXUI: CapFlags = 1 << 8;
pub const MEMCARD: CapFlags = 1 << 9;
pub const GFX: CapFlags = COMPOSER | GFX2D;
pub const ALL: CapFlags = SYSTEM | COMPOSER | AUDIO | FS | LOG | ASSET | BANK | GFX2D | GFXUI;
pub const ALL: CapFlags =
SYSTEM | COMPOSER | AUDIO | FS | LOG | ASSET | BANK | GFX2D | GFXUI | MEMCARD;
@@ -11,4 +11,24 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioStop, "audio", "stop")
.args(1)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetVolume, "audio", "set_volume")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetPan, "audio", "set_pan")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetPitch, "audio", "set_pitch")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
];
@@ -32,37 +32,4 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
.caps(caps::FS)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotCount, "mem", "slot_count")
.rets(2)
.caps(caps::FS),
SyscallRegistryEntry::builder(Syscall::MemSlotStat, "mem", "slot_stat")
.args(1)
.rets(5)
.caps(caps::FS)
.non_deterministic()
.cost(5),
SyscallRegistryEntry::builder(Syscall::MemSlotRead, "mem", "slot_read")
.args(3)
.rets(3)
.caps(caps::FS)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotWrite, "mem", "slot_write")
.args(3)
.rets(2)
.caps(caps::FS)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotCommit, "mem", "slot_commit")
.args(1)
.rets(1)
.caps(caps::FS)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotClear, "mem", "slot_clear")
.args(1)
.rets(1)
.caps(caps::FS)
.non_deterministic()
.cost(20),
];
@@ -0,0 +1,87 @@
use crate::syscalls::{Syscall, SyscallRegistryEntry, caps};
pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
SyscallRegistryEntry::builder(Syscall::MemBootstrap, "mem", "bootstrap")
.args(0)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotCount, "mem", "slot_count")
.args(1)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotStat, "mem", "slot_stat")
.args(2)
.rets(7)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotRead, "mem", "slot_read")
.args(6)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotWrite, "mem", "slot_write")
.args(6)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotCommit, "mem", "slot_commit")
.args(2)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotClear, "mem", "slot_clear")
.args(2)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemQuery, "mem", "query")
.args(2)
.rets(3)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemRelease, "mem", "release")
.args(2)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemInfo, "mem", "info")
.args(1)
.rets(6)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemMetadata, "mem", "metadata")
.args(1)
.rets(4)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemPresentation, "mem", "presentation")
.args(8)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemDiagnostic, "mem", "diagnostic")
.args(2)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemPublishPresentation, "mem", "publish_presentation")
.args(1)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
];
@@ -18,7 +18,10 @@ pub(crate) fn all_entries() -> impl Iterator<Item = &'static SyscallRegistryEntr
.chain(composer::ENTRIES.iter())
.chain(audio::ENTRIES.iter())
.chain(fs::ENTRIES.iter())
.chain(memcard::ENTRIES.iter())
.chain(log::ENTRIES.iter())
.chain(asset::ENTRIES.iter())
.chain(bank::ENTRIES.iter())
}
mod memcard;
@@ -33,6 +33,10 @@ impl Syscall {
0x1104 => Some(Self::ComposerEmitSprite),
0x3001 => Some(Self::AudioPlaySample),
0x3002 => Some(Self::AudioPlay),
0x3003 => Some(Self::AudioStop),
0x3004 => Some(Self::AudioSetVolume),
0x3005 => Some(Self::AudioSetPan),
0x3006 => Some(Self::AudioSetPitch),
0x4001 => Some(Self::FsOpen),
0x4002 => Some(Self::FsRead),
0x4003 => Some(Self::FsWrite),
@@ -40,6 +44,14 @@ impl Syscall {
0x4005 => Some(Self::FsListDir),
0x4006 => Some(Self::FsExists),
0x4007 => Some(Self::FsDelete),
0x4200 => Some(Self::MemBootstrap),
0x4207 => Some(Self::MemQuery),
0x4208 => Some(Self::MemRelease),
0x4209 => Some(Self::MemInfo),
0x420A => Some(Self::MemMetadata),
0x420B => Some(Self::MemPresentation),
0x420C => Some(Self::MemDiagnostic),
0x420D => Some(Self::MemPublishPresentation),
0x4201 => Some(Self::MemSlotCount),
0x4202 => Some(Self::MemSlotStat),
0x4203 => Some(Self::MemSlotRead),
@@ -94,6 +106,10 @@ impl Syscall {
Self::ComposerEmitSprite => "ComposerEmitSprite",
Self::AudioPlaySample => "AudioPlaySample",
Self::AudioPlay => "AudioPlay",
Self::AudioStop => "AudioStop",
Self::AudioSetVolume => "AudioSetVolume",
Self::AudioSetPan => "AudioSetPan",
Self::AudioSetPitch => "AudioSetPitch",
Self::FsOpen => "FsOpen",
Self::FsRead => "FsRead",
Self::FsWrite => "FsWrite",
@@ -101,6 +117,14 @@ impl Syscall {
Self::FsListDir => "FsListDir",
Self::FsExists => "FsExists",
Self::FsDelete => "FsDelete",
Self::MemBootstrap => "MemBootstrap",
Self::MemQuery => "MemQuery",
Self::MemRelease => "MemRelease",
Self::MemInfo => "MemInfo",
Self::MemMetadata => "MemMetadata",
Self::MemPresentation => "MemPresentation",
Self::MemDiagnostic => "MemDiagnostic",
Self::MemPublishPresentation => "MemPublishPresentation",
Self::MemSlotCount => "MemSlotCount",
Self::MemSlotStat => "MemSlotStat",
Self::MemSlotRead => "MemSlotRead",
@@ -39,7 +39,8 @@ pub enum LoadError {
}
/// Load-time error for PBX-declared syscall resolution.
#[derive(Debug, Clone, PartialEq, Eq)]
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "reason", rename_all = "snake_case")]
pub enum DeclaredLoadError {
UnknownSyscall {
module: String,
@@ -460,29 +460,59 @@ fn declared_resolver_accepts_mixed_status_first_surface_as_a_single_module() {
#[test]
fn memcard_syscall_signatures_are_pinned() {
let slot_count = meta_for(Syscall::MemSlotCount);
assert_eq!(slot_count.module, "mem");
assert_eq!(slot_count.name, "slot_count");
assert_eq!(slot_count.arg_slots, 0);
assert_eq!(slot_count.ret_slots, 2);
for (call, args, results) in [
(Syscall::MemBootstrap, 0, 1),
(Syscall::MemSlotCount, 1, 2),
(Syscall::MemSlotStat, 2, 7),
(Syscall::MemSlotRead, 6, 2),
(Syscall::MemSlotWrite, 6, 2),
(Syscall::MemSlotCommit, 2, 2),
(Syscall::MemSlotClear, 2, 1),
(Syscall::MemQuery, 2, 3),
(Syscall::MemRelease, 2, 1),
(Syscall::MemInfo, 1, 6),
(Syscall::MemMetadata, 1, 4),
(Syscall::MemPresentation, 8, 1),
(Syscall::MemDiagnostic, 2, 1),
(Syscall::MemPublishPresentation, 1, 2),
] {
let meta = meta_for(call);
assert_eq!(meta.module, "mem");
assert_eq!(meta.arg_slots, args);
assert_eq!(meta.ret_slots, results);
assert!(
resolve_program_syscalls(
&[SyscallIdentity { module: "mem", name: meta.name, version: 1 }],
caps::FS
)
.is_err()
);
assert!(
resolve_program_syscalls(
&[SyscallIdentity { module: "mem", name: meta.name, version: 1 }],
caps::MEMCARD
)
.is_ok()
);
}
}
let slot_stat = meta_for(Syscall::MemSlotStat);
assert_eq!(slot_stat.arg_slots, 1);
assert_eq!(slot_stat.ret_slots, 5);
let slot_read = meta_for(Syscall::MemSlotRead);
assert_eq!(slot_read.arg_slots, 3);
assert_eq!(slot_read.ret_slots, 3);
let slot_write = meta_for(Syscall::MemSlotWrite);
assert_eq!(slot_write.arg_slots, 3);
assert_eq!(slot_write.ret_slots, 2);
let slot_commit = meta_for(Syscall::MemSlotCommit);
assert_eq!(slot_commit.arg_slots, 1);
assert_eq!(slot_commit.ret_slots, 1);
let slot_clear = meta_for(Syscall::MemSlotClear);
assert_eq!(slot_clear.arg_slots, 1);
assert_eq!(slot_clear.ret_slots, 1);
#[test]
fn audio_control_abi_and_capability_are_stable() {
for (name, id, args) in [
("stop", 0x3003, 1),
("set_volume", 0x3004, 2),
("set_pan", 0x3005, 2),
("set_pitch", 0x3006, 2),
] {
let entry = resolve_syscall("audio", name, 1).unwrap();
assert_eq!(entry.id, id);
assert_eq!(entry.meta.arg_slots, args);
assert_eq!(entry.meta.ret_slots, 1);
assert_eq!(entry.meta.cost_hint, 5);
assert_eq!(entry.meta.caps, caps::AUDIO);
let identities = [SyscallIdentity { module: "audio", name, version: 1 }];
assert!(resolve_program_syscalls(&identities, 0).is_err());
assert!(resolve_program_syscalls(&identities, caps::AUDIO).is_ok());
}
}
@@ -0,0 +1,62 @@
use prometeu_bytecode::Value;
use serde::{Deserialize, Serialize};
use std::sync::Arc;
/// Native/debug ownership only. Wire data is the ordinary list of values;
/// opaque accounting domains stay alive for every retained string allocation.
#[derive(Clone, Default, Serialize, Deserialize)]
#[serde(transparent)]
pub struct ValueSnapshot {
values: Vec<Value>,
#[serde(skip)]
owners: [Option<Arc<dyn Send + Sync>>; 2],
}
impl ValueSnapshot {
pub fn with_owners(values: Vec<Value>, owners: [Option<Arc<dyn Send + Sync>>; 2]) -> Self {
Self { values, owners }
}
pub fn retained_domains(&self) -> usize {
self.owners.iter().filter(|owner| owner.is_some()).count()
}
}
impl std::ops::Deref for ValueSnapshot {
type Target = [Value];
fn deref(&self) -> &[Value] {
&self.values
}
}
impl std::fmt::Debug for ValueSnapshot {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
self.values.fmt(f)
}
}
impl PartialEq<Vec<Value>> for ValueSnapshot {
fn eq(&self, other: &Vec<Value>) -> bool {
self.values == *other
}
}
impl From<Vec<Value>> for ValueSnapshot {
/// External/native values have no provenance and are copied on guest import.
fn from(values: Vec<Value>) -> Self {
Self::with_owners(values, [None, None])
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn serialization_contains_values_and_never_exports_native_domain_metadata() {
let owner: Arc<dyn Send + Sync> = Arc::new(17u32);
let snapshot = ValueSnapshot::with_owners(
vec![Value::string("shared"), Value::Null],
[Some(owner), None],
);
assert_eq!(snapshot.retained_domains(), 1);
let bytes = serde_json::to_string(&snapshot).unwrap();
assert_eq!(bytes, "[\"shared\",null]");
let imported: ValueSnapshot = serde_json::from_str(&bytes).unwrap();
assert_eq!(imported.retained_domains(), 0);
assert_eq!(&*imported, &*snapshot);
}
}
@@ -1,6 +1,7 @@
#[derive(Debug, PartialEq, Clone)]
pub enum VmFault {
Trap(u32, String),
ResourceLimit(prometeu_bytecode::ResourceFailure),
Panic(String),
Unavailable,
}
@@ -0,0 +1,11 @@
/// Host civil time for administrative timestamps, independent of gameplay and deadlines.
///
/// Reads must be local and bounded, without waiting for IO or clock synchronization.
/// The host always supplies a value, even when its civil clock is incorrect.
pub trait WallClock {
/// Whole UTC seconds since the Unix epoch, with fractions discarded.
///
/// Values outside the unsigned range saturate to zero or `u64::MAX`.
/// Successive reads may go backwards when the host adjusts its clock.
fn utc_unix_seconds(&self) -> u64;
}
@@ -5,6 +5,7 @@ edition = "2024"
license.workspace = true
[dependencies]
serde = { version = "1.0.228", features = ["derive"] }
serde_json = "1.0.149"
prometeu-vm = { path = "../prometeu-vm" }
prometeu-bytecode = { path = "../prometeu-bytecode" }
@@ -12,3 +13,4 @@ prometeu-hal = { path = "../prometeu-hal" }
[dev-dependencies]
prometeu-drivers = { path = "../prometeu-drivers" }
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
@@ -1,6 +1,7 @@
use prometeu_bytecode::TrapInfo;
use prometeu_vm::VmInitError;
use std::fmt;
mod init_diagnostic;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CrashReport {
@@ -10,6 +11,20 @@ pub enum CrashReport {
}
impl CrashReport {
/// The same machine fields serve headless and desktop transports.
pub fn init_diagnostic(&self) -> Option<serde_json::Value> {
match self {
Self::VmInit { error } => Some(init_diagnostic::serialize(error)),
_ => None,
}
}
pub fn resource_failure(&self) -> Option<prometeu_bytecode::ResourceFailure> {
match self {
Self::VmTrap { trap } => trap.resource,
Self::VmInit { error: VmInitError::RuntimeResourceLimit(resource) } => Some(*resource),
_ => None,
}
}
pub fn kind(&self) -> &'static str {
match self {
Self::VmTrap { .. } => "vm_trap",
@@ -0,0 +1,132 @@
use prometeu_vm::VmInitError;
use serde_json::{Value, json};
pub(super) fn serialize(error: &VmInitError) -> Value {
let code = match error {
VmInitError::RegistryLoadFailed(_) => "registry_load_failed",
VmInitError::RuntimeResourceLimit(_) => "runtime_resource_limit",
VmInitError::InvalidFormat => "invalid_format",
VmInitError::UnsupportedFormat => "unsupported_format",
VmInitError::ImageLoadFailed(_) => "image_load_failed",
VmInitError::LoaderPatchFailed(_) => "loader_patch_failed",
VmInitError::EntrypointNotFound => "entrypoint_not_found",
VmInitError::EntrypointArgumentsInvalid { .. } => "entrypoint_arguments_invalid",
VmInitError::VerificationFailed(_) => "verification_failed",
};
let mut result = json!({"code":code,"message":format!("{error:?}")});
match error {
VmInitError::RegistryLoadFailed(load) => {
result["load"] = json!(load);
result["load"]["code"] = json!(load.code.tag());
}
VmInitError::RuntimeResourceLimit(resource) => result["resource"] = json!(resource),
VmInitError::EntrypointArgumentsInvalid { function, slot, trap_code } => {
result["entry"] = json!({"function":function,"slot":slot,"trapCode":trap_code});
}
VmInitError::LoaderPatchFailed(patch) => {
use prometeu_vm::LoaderPatchError as P;
result["binding"] = match patch {
P::ResolveFailed(native) => json!(native),
P::HostcallIndexOutOfBounds { pc, sysc_index, syscalls_len } => {
json!({"reason":"hostcall_index_out_of_bounds","pc":pc,"syscallIndex":sysc_index,"syscallsLength":syscalls_len})
}
P::RawSyscallInPreloadArtifact { pc, syscall_id } => {
json!({"reason":"raw_syscall","pc":pc,"syscallId":syscall_id})
}
P::UnusedSyscallDecl { sysc_index, module, name, version } => {
json!({"reason":"unused_syscall","syscallIndex":sysc_index,"module":module,"name":name,"version":version})
}
P::HostcallRemaining { pc, sysc_index } => {
json!({"reason":"hostcall_remaining","pc":pc,"syscallIndex":sysc_index})
}
P::DecodeFailed(_) => json!({"reason":"decode_failed"}),
};
}
_ => {}
}
result
}
#[cfg(test)]
mod tests {
use super::*;
use crate::CrashReport;
use prometeu_bytecode::{
ResourceFailure, ResourceReason, RuntimeResource,
load_limits::{IdDomain, LoadCode, LoadFailure, LoadReason},
};
#[test]
fn load_tag_and_reference_context_survive_without_fabricating_runtime_pc() {
let error = LoadFailure::new(LoadCode::InvalidReference, LoadReason::TypeId)
.at(6, 159)
.record(4)
.member(2)
.reference(IdDomain::Type, 77)
.in_function(3, Some(18));
let report = CrashReport::VmInit { error: VmInitError::RegistryLoadFailed(error) };
assert_eq!(report.pc(), None);
let wire = report.init_diagnostic().unwrap();
assert_eq!(wire["code"], "registry_load_failed");
assert_eq!(wire["load"]["code"], "LOAD_INVALID_REFERENCE");
for (field, value) in [
("section", 6),
("offset", 159),
("record", 4),
("member", 2),
("referenced_id", 77),
("function", 3),
("pc", 18),
] {
assert_eq!(wire["load"][field], value);
}
assert_eq!(wire["load"]["id_domain"], "Type");
assert_eq!(wire["load"]["reason"], "TypeId");
}
#[test]
fn native_abi_and_resource_context_are_machine_fields() {
let native = prometeu_hal::syscalls::DeclaredLoadError::AbiMismatch {
module: "system".into(),
name: "has_cart".into(),
version: 1,
declared_arg_slots: 0,
declared_ret_slots: 2,
expected_arg_slots: 0,
expected_ret_slots: 1,
};
let wire = serialize(&VmInitError::LoaderPatchFailed(
prometeu_vm::LoaderPatchError::ResolveFailed(native),
));
assert_eq!(wire["binding"]["reason"], "abi_mismatch");
assert_eq!(wire["binding"]["module"], "system");
assert_eq!(wire["binding"]["declared_ret_slots"], 2);
assert_eq!(wire["binding"]["expected_ret_slots"], 1);
let resource = ResourceFailure {
resource: RuntimeResource::CallDepth,
reason: ResourceReason::Limit,
requested: 3,
limit: 2,
};
let report = CrashReport::VmInit { error: VmInitError::RuntimeResourceLimit(resource) };
assert_eq!(report.resource_failure(), Some(resource));
let wire = report.init_diagnostic().unwrap();
assert_eq!(wire["resource"]["resource"], "CallDepth");
assert_eq!(wire["resource"]["reason"], "Limit");
assert_eq!(wire["resource"]["requested"], 3);
assert_eq!(wire["resource"]["limit"], 2);
}
#[test]
fn all_load_codes_serialize_to_the_normative_tags() {
for code in [
LoadCode::InvalidFormat,
LoadCode::UnsupportedFormat,
LoadCode::InvalidReference,
LoadCode::InvalidRegistry,
LoadCode::InvalidCode,
LoadCode::ResourceLimit,
LoadCode::InvalidEntrypoint,
] {
assert_eq!(json!(code), code.tag());
assert_eq!(serde_json::from_value::<LoadCode>(json!(code)).unwrap(), code);
}
}
}
+2 -1
View File
@@ -17,6 +17,7 @@ pub use services::async_work::{
AsyncWorkActiveJob, AsyncWorkCancelToken, AsyncWorkJobContext, AsyncWorkJobId,
AsyncWorkJobKind, AsyncWorkJobOutcome, AsyncWorkLane, AsyncWorkLaneConfig,
AsyncWorkLaneController, AsyncWorkLaneError, AsyncWorkLaneTelemetry, AsyncWorkPriority,
AsyncWorkStep,
};
pub use services::foreground::{
ForegroundOwner, ForegroundStack, ForegroundStackError, ResidentGame, ResidentGameState,
@@ -25,7 +26,7 @@ pub use services::fs;
pub use services::game_library::{
GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, GameSwitchTarget, discover_games_root,
};
pub use services::memcard::MemcardAsyncLaneOperation;
pub use services::memcard;
pub use services::process;
pub use services::task;
pub use services::vm_runtime::{
@@ -9,6 +9,7 @@ use crate::services::foreground::{
ForegroundOwner, ForegroundStackError, ResidentGame, ResidentGameState,
};
use crate::task::{TaskId, TaskKind, TaskState};
use crate::vm_session::LifecycleTransition;
pub struct LifecycleFacade<'a> {
pub(in crate::os) os: &'a mut SystemOS,
@@ -35,6 +36,21 @@ impl<'a> LifecycleFacade<'a> {
}
pub fn set_game_foreground_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
if self.os.memcard.host_faulted()
|| self.os.memcard.session.removal_pending()
|| matches!(
self.os.memcard.admission.state,
crate::memcard::admission::PreparationState::Pending
| crate::memcard::admission::PreparationState::Failed(_)
)
{
return Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::SetForeground,
});
}
let process_id = process_id_for_task(self.os, task_id)?;
if task_kind_for_task(self.os, task_id)? != TaskKind::Game {
@@ -45,6 +61,27 @@ impl<'a> LifecycleFacade<'a> {
});
}
if self
.os
.vm_sessions
.for_task(task_id)
.is_some_and(|session| session.lifecycle_transition.is_some())
{
return Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::SetForeground,
});
}
if self.task_state(task_id) == Some(TaskState::Suspended)
&& self.os.vm_sessions.for_task(task_id).is_some_and(|session| {
session
.vm
.has_lifecycle_hook(prometeu_bytecode::registry::LifecycleRole::BeforeResume)
})
{
return self.resume_task(task_id);
}
self.os.foreground_stack.set_game_foreground(task_id).map_err(map_foreground_error)?;
self.os.task_manager.set_foreground(task_id);
self.os.process_manager.mark_running(process_id);
@@ -67,6 +104,9 @@ impl<'a> LifecycleFacade<'a> {
&& game_task_id != task_id
&& self.task_state(game_task_id) != Some(TaskState::Suspended)
{
if self.defer_pause(game_task_id, LifecycleTransition::PauseToShell(task_id))? {
return Ok(());
}
let game_process_id = process_id_for_task(self.os, game_task_id)?;
self.os.task_manager.mark_suspended(game_task_id);
self.os.process_manager.mark_suspended(game_process_id);
@@ -93,6 +133,19 @@ impl<'a> LifecycleFacade<'a> {
pub fn request_home_from_game(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let _process_id = process_id_for_task(self.os, task_id)?;
if let Some(pending) =
self.os.vm_sessions.for_task(task_id).and_then(|s| s.lifecycle_transition)
{
return if pending == LifecycleTransition::PauseToHub {
Ok(())
} else {
Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::Suspend,
})
};
}
let previous = self.os.foreground_stack.resident_game();
self.os
@@ -113,6 +166,13 @@ impl<'a> LifecycleFacade<'a> {
}
pub fn advance_game_pause_budget(&mut self, task_id: TaskId) -> Result<bool, LifecycleError> {
if self.os.foreground_stack.resident_game().is_some_and(|game| {
game.task_id == task_id
&& game.state == ResidentGameState::PauseRequested { remaining_ticks: 1 }
}) && self.defer_pause(task_id, LifecycleTransition::PauseToHub)?
{
return Ok(false);
}
let expired =
self.os.foreground_stack.advance_pause_budget(task_id).map_err(map_foreground_error)?;
@@ -125,6 +185,34 @@ impl<'a> LifecycleFacade<'a> {
Ok(expired)
}
fn defer_pause(
&mut self,
task_id: TaskId,
transition: LifecycleTransition,
) -> Result<bool, LifecycleError> {
let state = self.task_state(task_id).unwrap_or(TaskState::Closed);
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
return Ok(false);
};
if let Some(pending) = session.lifecycle_transition {
return if pending == transition {
Ok(true)
} else {
Err(LifecycleError::InvalidTransition {
task_id,
from: state,
operation: LifecycleOperation::Suspend,
})
};
}
if session.pause_hook_complete || !session.vm.has_lifecycle_hook(transition.role()) {
return Ok(false);
}
session.lifecycle_transition = Some(transition);
session.lifecycle_started = false;
Ok(true)
}
pub fn pending_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
&self.os.game_lifecycle_events
}
@@ -141,6 +229,11 @@ impl<'a> LifecycleFacade<'a> {
pub fn suspend_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let process_id = process_id_for_task(self.os, task_id)?;
if task_kind_for_task(self.os, task_id)? == TaskKind::Game
&& self.defer_pause(task_id, LifecycleTransition::PauseToHub)?
{
return Ok(());
}
self.os.task_manager.mark_suspended(task_id);
self.os.process_manager.mark_suspended(process_id);
match self.os.foreground_stack.owner() {
@@ -164,6 +257,21 @@ impl<'a> LifecycleFacade<'a> {
}
pub fn resume_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
if self.os.memcard.host_faulted()
|| self.os.memcard.session.removal_pending()
|| matches!(
self.os.memcard.admission.state,
crate::memcard::admission::PreparationState::Pending
| crate::memcard::admission::PreparationState::Failed(_)
)
{
return Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::Resume,
});
}
let task =
self.os.task_manager.get(task_id).ok_or(LifecycleError::TaskNotFound(task_id))?;
@@ -189,6 +297,16 @@ impl<'a> LifecycleFacade<'a> {
task_id,
kind: GameLifecycleEventKind::ResumeForeground,
});
if let Some(session) = self.os.vm_sessions.for_task_mut(task_id) {
session.pause_hook_complete = false;
if session.vm.has_lifecycle_hook(
prometeu_bytecode::registry::LifecycleRole::BeforeResume,
) {
session.lifecycle_transition = Some(LifecycleTransition::Resume);
session.lifecycle_started = false;
return Ok(());
}
}
self.os
.foreground_stack
.complete_resume_game(task_id)
@@ -1,15 +1,15 @@
use crate::CrashReport;
use crate::os::{GameLifecycleEvent, SystemOS};
use crate::task::TaskId;
use crate::vm_session::VmSession;
use crate::vm_session::{LifecycleTransition, VmSession};
use crate::{RenderWorkerConfig, RenderWorkerController};
use prometeu_bytecode::Value;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame};
use prometeu_hal::{
FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError,
RenderWorkerFrameSink, RuntimePlatform,
};
use prometeu_vm::LogicalFrameEndingReason;
use std::sync::atomic::Ordering;
pub struct VmFacade<'a> {
@@ -23,6 +23,12 @@ impl<'a> VmFacade<'a> {
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if self.os.lifecycle().task_state(task_id) != Some(crate::task::TaskState::Foreground) {
return None;
}
if self.os.vm_sessions.for_task(task_id).is_some_and(|s| s.lifecycle_transition.is_some()) {
return self.drive_lifecycle(task_id, platform, false).err();
}
self.deliver_pending_game_lifecycle_events_to_session(task_id);
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
@@ -45,6 +51,112 @@ impl<'a> VmFacade<'a> {
)
}
/// Firmware polls this before dispatching ordinary Game/Shell updates.
pub fn poll_pending_lifecycle(
&mut self,
platform: &mut dyn RuntimePlatform,
) -> Option<(TaskId, Result<(), CrashReport>)> {
let task_id = self.os.foreground_stack.resident_game_task()?;
self.os.vm_sessions.for_task(task_id)?.lifecycle_transition?;
Some((task_id, self.drive_lifecycle(task_id, platform, false)))
}
fn drive_lifecycle(
&mut self,
task_id: TaskId,
platform: &mut dyn RuntimePlatform,
single_step: bool,
) -> Result<(), CrashReport> {
self.deliver_pending_game_lifecycle_events_to_session(task_id);
let session = self.os.vm_sessions.for_task_mut(task_id).expect("pending lifecycle session");
let transition = session.lifecycle_transition.expect("pending lifecycle transition");
let role = transition.role();
// A fatal hook remains failed even if a caller tries to tick the same session again.
if let Some(report) = &session.runtime.last_crash_report {
return Err(report.clone());
}
if !platform.audio().lifecycle_ready() {
return Ok(());
}
let reason = if !session.lifecycle_started {
session.lifecycle_started = true;
match session.vm.begin_lifecycle(role) {
Ok(true) => None,
Ok(false) => {
// Optional hooks still form a successful lifecycle boundary.
platform.audio_mut().begin_lifecycle();
platform.audio_mut().finish_lifecycle(true);
Some(LogicalFrameEndingReason::LifecycleComplete)
}
Err(error) => Some(LogicalFrameEndingReason::Panic(format!("{error:?}"))),
}
} else {
None
};
let reason = reason.unwrap_or_else(|| {
session.runtime.tick_lifecycle(
&mut self.os.log_service,
&mut self.os.fs,
&mut session.fs_state,
&mut self.os.memcard,
&mut session.open_files,
&mut session.next_handle,
&mut session.vm,
platform,
single_step,
)
});
match reason {
LogicalFrameEndingReason::BudgetExhausted | LogicalFrameEndingReason::Breakpoint => {
Ok(())
}
LogicalFrameEndingReason::LifecycleComplete => {
session.lifecycle_transition = None;
session.lifecycle_started = false;
match transition {
LifecycleTransition::PauseToHub => {
session.pause_hook_complete = true;
self.os.lifecycle().suspend_task(task_id).expect("validated suspension");
}
LifecycleTransition::PauseToShell(shell) => {
session.pause_hook_complete = true;
self.os
.lifecycle()
.set_shell_foreground_task(shell)
.expect("validated Shell transition");
}
LifecycleTransition::Resume => {
self.os
.foreground_stack
.complete_resume_game(task_id)
.expect("validated resume");
}
}
Ok(())
}
LogicalFrameEndingReason::Halted => {
// HALT ends the session; it must never restore or resume gameplay.
session.lifecycle_transition = None;
self.os.lifecycle().close_task(task_id).expect("validated task");
Ok(())
}
failure => {
let report = match failure {
LogicalFrameEndingReason::Trap(mut trap) => {
trap.message = format!("{role:?}: {}", trap.message);
CrashReport::VmTrap { trap }
}
other => CrashReport::VmPanic {
message: format!("{role:?} lifecycle failed: {other:?}"),
pc: Some(session.vm.pc() as u32),
},
};
session.runtime.last_crash_report = Some(report.clone());
Err(report)
}
}
}
fn deliver_pending_game_lifecycle_events_to_session(&mut self, task_id: TaskId) {
let Some(session) = self.os.vm_sessions.for_task(task_id) else {
return;
@@ -86,6 +198,12 @@ impl<'a> VmFacade<'a> {
pc: None,
});
};
if self.os.lifecycle().task_state(task_id) != Some(crate::task::TaskState::Foreground) {
return None;
}
if self.os.vm_sessions.for_task(task_id).is_some_and(|s| s.lifecycle_transition.is_some()) {
return self.drive_lifecycle(task_id, platform, true).err();
}
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
return Some(CrashReport::VmPanic {
message: format!("active debug task {:?} has no VM session", task_id),
@@ -93,14 +211,23 @@ impl<'a> VmFacade<'a> {
});
};
session.runtime.debug_step_instruction(&mut self.os.log_service, &mut session.vm, platform)
session.runtime.debug_step_instruction(
&mut self.os.log_service,
&mut self.os.fs,
&mut session.fs_state,
&mut self.os.memcard,
&mut session.open_files,
&mut session.next_handle,
&mut session.vm,
platform,
)
}
pub fn active_pc(&self) -> Option<usize> {
self.active_session().map(|session| session.vm.pc())
}
pub fn active_operand_stack_top(&self, n: usize) -> Vec<Value> {
pub fn active_operand_stack_top(&self, n: usize) -> prometeu_hal::ValueSnapshot {
self.active_session().map(|session| session.vm.operand_stack_top(n)).unwrap_or_default()
}
@@ -28,6 +28,8 @@ pub struct SystemOS {
pub(super) memcard: MemcardService,
pub(super) open_files: HashMap<u32, String>,
pub(super) next_handle: u32,
io_controller: Option<crate::AsyncWorkLaneController>,
io_bound: bool,
}
impl SystemOS {
@@ -50,6 +52,8 @@ impl SystemOS {
memcard: MemcardService::new(),
open_files: HashMap::new(),
next_handle: 1,
io_controller: None,
io_bound: false,
};
os.log(LogLevel::Info, LogSource::Pos, 0, "PrometeuOS starting...".to_string());
@@ -57,6 +61,55 @@ impl SystemOS {
os
}
pub fn memcard(&mut self) -> &mut MemcardService {
&mut self.memcard
}
/// Host/player operations are admitted only while gameplay is suspended.
pub fn replace_memcard(
&mut self,
storage: Box<dyn prometeu_hal::memcard::MemcardStorage>,
load_existing: bool,
) -> crate::memcard::image::Result<()> {
if let Some(task) = self.foreground_stack.resident_game_task()
&& self
.task_manager
.get(task)
.is_none_or(|t| t.state != crate::task::TaskState::Suspended)
{
return Err(crate::memcard::image::Error::AccessDenied);
}
self.memcard.replace_card(storage, load_existing)
}
pub fn detach_memcard(&mut self) -> crate::memcard::image::Result<()> {
if let Some(task) = self.foreground_stack.resident_game_task()
&& self
.task_manager
.get(task)
.is_none_or(|t| t.state != crate::task::TaskState::Suspended)
{
return Err(crate::memcard::image::Error::AccessDenied);
}
if self.memcard.host_faulted() {
return Err(crate::memcard::image::Error::ReadOnly);
}
self.memcard.session.detach()?;
self.memcard.admission.state = crate::memcard::admission::PreparationState::Ready;
Ok(())
}
/// Called outside guest/frame execution, including while a game is suspended.
pub fn poll_background_io(&mut self, platform: &mut dyn prometeu_hal::RuntimePlatform) {
if !self.io_bound && platform.assets_mut().bind_background_work(self.memcard.lane.clone()) {
self.io_controller = Some(crate::AsyncWorkLaneController::start(
crate::AsyncWorkLaneConfig::default(),
self.memcard.lane.clone(),
));
self.io_bound = true;
}
self.memcard.poll(std::time::Instant::now());
}
pub fn log(&mut self, level: LogLevel, source: LogSource, tag: u16, msg: String) {
self.vm_runtime.log(&mut self.log_service, level, source, tag, msg);
}
@@ -136,7 +189,7 @@ impl SystemOS {
pub(super) fn clear_cartridge_service_state(&mut self) {
self.open_files.clear();
self.next_handle = 1;
self.memcard.clear_all_staging();
self.memcard.session.end_session();
}
}
@@ -158,6 +211,7 @@ mod tests {
fn session_test_cartridge(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
Cartridge {
memcard_slots: None,
app_id,
title: title.to_string(),
app_version: "1.0.0".to_string(),
@@ -607,6 +607,7 @@ mod tests {
fn game_row_click_emits_launch_game_action() {
let entry = crate::GameLibraryEntry {
manifest: prometeu_hal::cartridge::CartridgeManifest {
memcard_slots: None,
magic: "PMTU".to_string(),
cartridge_version: 1,
app_id: 42,
@@ -619,7 +620,7 @@ mod tests {
app_id: 42,
app_version: "1.0.0".to_string(),
path: PathBuf::from("test-cartridges/stress-console"),
discovered_at: std::time::SystemTime::UNIX_EPOCH,
discovered_at: 0,
};
let action = action_for_click(
@@ -172,7 +172,13 @@ impl AsyncWorkJobContext {
}
}
type AsyncWorkFn = Box<dyn FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static>;
/// A step must release the executor when yielding; it retains its own bounded progress.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AsyncWorkStep {
Yield,
Complete(AsyncWorkJobOutcome),
}
type AsyncWorkFn = Box<dyn FnMut(AsyncWorkJobContext) -> AsyncWorkStep + Send + 'static>;
struct PendingAsyncWorkJob {
id: AsyncWorkJobId,
@@ -180,6 +186,7 @@ struct PendingAsyncWorkJob {
priority: AsyncWorkPriority,
cancel_token: AsyncWorkCancelToken,
work: AsyncWorkFn,
started: bool,
}
struct RunningAsyncWorkJob {
@@ -188,11 +195,13 @@ struct RunningAsyncWorkJob {
priority: AsyncWorkPriority,
cancel_token: AsyncWorkCancelToken,
work: AsyncWorkFn,
started: bool,
}
#[derive(Default)]
struct AsyncWorkLaneState {
next_job_id: u64,
progress: u64,
pending: VecDeque<PendingAsyncWorkJob>,
active: Option<AsyncWorkActiveJob>,
active_cancel_token: Option<AsyncWorkCancelToken>,
@@ -204,9 +213,25 @@ struct AsyncWorkLaneState {
pub struct AsyncWorkLane {
state: Mutex<AsyncWorkLaneState>,
ready: Condvar,
progressed: Condvar,
}
impl AsyncWorkLane {
pub fn progress_stamp(&self) -> u64 {
self.state.lock().unwrap().progress
}
/// Used by synchronous headless boot admission, never by a guest/frame tick.
/// Wakes on actual IO progress; timeout lets the caller run its watchdog.
pub fn wait_for_progress(&self, stamp: u64, timeout: Duration) {
let state = self.state.lock().unwrap();
let _guard = self
.progressed
.wait_timeout_while(state, timeout, |s| {
s.progress == stamp && (!s.pending.is_empty() || s.active.is_some())
})
.unwrap();
}
pub fn submit(
&self,
kind: AsyncWorkJobKind,
@@ -220,16 +245,36 @@ impl AsyncWorkLane {
kind: AsyncWorkJobKind,
priority: AsyncWorkPriority,
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
let mut once = Some(work);
self.submit_steps(kind, priority, move |context| {
AsyncWorkStep::Complete(once.take().expect("one-shot job executed once")(context))
})
}
pub fn submit_steps(
&self,
kind: AsyncWorkJobKind,
priority: AsyncWorkPriority,
work: impl FnMut(AsyncWorkJobContext) -> AsyncWorkStep + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
let mut state = self.state.lock().map_err(|_| AsyncWorkLaneError::InternalFailure)?;
if state.shutdown_requested {
return Err(AsyncWorkLaneError::Shutdown);
}
state.next_job_id += 1;
state.next_job_id =
state.next_job_id.checked_add(1).ok_or(AsyncWorkLaneError::InternalFailure)?;
let id = AsyncWorkJobId::new(state.next_job_id);
let cancel_token = AsyncWorkCancelToken::new();
let job = PendingAsyncWorkJob { id, kind, priority, cancel_token, work: Box::new(work) };
let job = PendingAsyncWorkJob {
id,
kind,
priority,
cancel_token,
work: Box::new(work),
started: false,
};
let insert_at = state
.pending
.iter()
@@ -340,13 +385,19 @@ impl AsyncWorkLane {
state.active = Some(active);
state.active_cancel_token = Some(pending.cancel_token.clone());
let pending_depth = state.pending.len();
state.telemetry.record_started(pending.id, pending_depth);
if !pending.started {
state.telemetry.record_started(pending.id, pending_depth);
} else {
state.telemetry.active_job_id = Some(pending.id);
state.telemetry.pending_depth = pending_depth;
}
return Some(RunningAsyncWorkJob {
id: pending.id,
kind: pending.kind,
priority: pending.priority,
cancel_token: pending.cancel_token,
work: pending.work,
started: true,
});
}
@@ -355,6 +406,33 @@ impl AsyncWorkLane {
}
}
fn yield_job(&self, job: RunningAsyncWorkJob) {
let mut state = self.state.lock().unwrap();
state.active = None;
state.active_cancel_token = None;
state.telemetry.active_job_id = None;
let at = state
.pending
.iter()
.position(|p| job.priority.rank() < p.priority.rank())
.unwrap_or(state.pending.len());
state.pending.insert(
at,
PendingAsyncWorkJob {
id: job.id,
kind: job.kind,
priority: job.priority,
cancel_token: job.cancel_token,
work: job.work,
started: job.started,
},
);
state.telemetry.pending_depth = state.pending.len();
state.progress = state.progress.saturating_add(1);
self.progressed.notify_all();
self.ready.notify_one();
}
fn record_finished(&self, job_id: AsyncWorkJobId, outcome: AsyncWorkJobOutcome) {
let mut state = self.state.lock().unwrap();
if state.active.is_some_and(|active| active.id == job_id) {
@@ -362,6 +440,8 @@ impl AsyncWorkLane {
state.active_cancel_token = None;
}
state.telemetry.record_closed(job_id, outcome);
state.progress = state.progress.saturating_add(1);
self.progressed.notify_all();
}
}
@@ -415,16 +495,19 @@ impl Drop for AsyncWorkLaneController {
}
fn run_async_work_loop(lane: Arc<AsyncWorkLane>) {
while let Some(job) = lane.wait_take() {
while let Some(mut job) = lane.wait_take() {
let context = AsyncWorkJobContext {
job_id: job.id,
kind: job.kind,
priority: job.priority,
cancel_token: job.cancel_token,
cancel_token: job.cancel_token.clone(),
};
let result = catch_unwind(AssertUnwindSafe(|| (job.work)(context)))
.unwrap_or(AsyncWorkJobOutcome::Failed);
lane.record_finished(job.id, result);
.unwrap_or(AsyncWorkStep::Complete(AsyncWorkJobOutcome::Failed));
match result {
AsyncWorkStep::Yield => lane.yield_job(job),
AsyncWorkStep::Complete(outcome) => lane.record_finished(job.id, outcome),
}
}
}
@@ -599,3 +682,63 @@ mod tests {
assert_eq!(lane.telemetry().shutdown_discards, 1);
}
}
#[cfg(test)]
mod step_tests {
use super::*;
#[test]
fn yielded_asset_resumes_same_job_after_priority_save() {
let lane = Arc::new(AsyncWorkLane::default());
let events = Arc::new(Mutex::new(Vec::new()));
let nested = lane.clone();
let log = events.clone();
let mut step = 0;
let mut identity = None;
lane.submit_steps(AsyncWorkJobKind::Asset, AsyncWorkPriority::AssetLoad, move |context| {
assert_eq!(*identity.get_or_insert(context.job_id), context.job_id);
if step == 0 {
log.lock().unwrap().push("asset first");
let log = log.clone();
nested
.submit_memcard_commit_write(move |_| {
log.lock().unwrap().push("save");
AsyncWorkJobOutcome::Completed
})
.unwrap();
step += 1;
AsyncWorkStep::Yield
} else {
log.lock().unwrap().push("asset resumes");
AsyncWorkStep::Complete(AsyncWorkJobOutcome::Completed)
}
})
.unwrap();
let mut controller =
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), lane.clone());
let deadline = std::time::Instant::now() + Duration::from_secs(1);
while lane.telemetry().completed_jobs < 2 {
assert!(std::time::Instant::now() < deadline);
std::thread::yield_now();
}
controller.stop().unwrap();
assert_eq!(*events.lock().unwrap(), vec!["asset first", "save", "asset resumes"]);
}
}
impl prometeu_hal::background_work::BackgroundWork for AsyncWorkLane {
fn submit_asset(
&self,
mut work: prometeu_hal::background_work::AssetWork,
) -> Result<(), prometeu_hal::background_work::WorkUnavailable> {
use prometeu_hal::background_work::{WorkStep, WorkUnavailable};
self.submit_steps(AsyncWorkJobKind::Asset, AsyncWorkPriority::AssetLoad, move |context| {
match work(context.is_canceled()) {
WorkStep::Yield => AsyncWorkStep::Yield,
WorkStep::Complete => AsyncWorkStep::Complete(AsyncWorkJobOutcome::Completed),
WorkStep::Failed => AsyncWorkStep::Complete(AsyncWorkJobOutcome::Failed),
}
})
.map(|_| ())
.map_err(|_| WorkUnavailable)
}
}
@@ -1,8 +1,8 @@
use prometeu_hal::WallClock;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::CartridgeManifest;
use std::fs;
use std::path::{Path, PathBuf};
use std::time::SystemTime;
#[derive(Debug, Clone)]
pub struct GameLibraryEntry {
@@ -11,11 +11,12 @@ pub struct GameLibraryEntry {
pub app_id: u32,
pub app_version: String,
pub path: PathBuf,
pub discovered_at: SystemTime,
/// UTC seconds sampled once for the discovery scan, from the selected host clock.
pub discovered_at: u64,
}
impl GameLibraryEntry {
fn new(path: PathBuf, manifest: CartridgeManifest, discovered_at: SystemTime) -> Self {
fn new(path: PathBuf, manifest: CartridgeManifest, discovered_at: u64) -> Self {
Self {
title: manifest.title.clone(),
app_id: manifest.app_id,
@@ -91,9 +92,9 @@ impl GameLibrary {
}
}
pub fn discover_games_root(root: impl AsRef<Path>) -> GameLibrary {
pub fn discover_games_root(root: impl AsRef<Path>, wall_clock: &dyn WallClock) -> GameLibrary {
let root = root.as_ref();
let discovered_at = SystemTime::now();
let discovered_at = wall_clock.utc_unix_seconds();
if !root.is_dir() {
return GameLibrary {
@@ -153,7 +154,7 @@ pub fn discover_games_root(root: impl AsRef<Path>) -> GameLibrary {
fn discover_candidate(
path: &Path,
discovered_at: SystemTime,
discovered_at: u64,
) -> Result<GameLibraryEntry, GameLibraryDiagnosticReason> {
let manifest_path = path.join("manifest.json");
if !manifest_path.exists() {
@@ -185,8 +186,26 @@ fn discover_candidate(
mod tests {
use super::*;
use serde_json::json;
use std::cell::Cell;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::UNIX_EPOCH;
struct CountingClock {
seconds: Cell<u64>,
calls: Cell<usize>,
}
impl CountingClock {
fn new(seconds: u64) -> Self {
Self { seconds: Cell::new(seconds), calls: Cell::new(0) }
}
}
impl WallClock for CountingClock {
fn utc_unix_seconds(&self) -> u64 {
self.calls.set(self.calls.get() + 1);
self.seconds.get()
}
}
static TEST_DIR_COUNTER: AtomicU64 = AtomicU64::new(0);
@@ -254,7 +273,7 @@ mod tests {
fs::write(nested_parent.join("nested-game").join("program.pbx"), [0_u8])
.expect("nested program should be written");
let library = discover_games_root(&root.path);
let library = discover_games_root(&root.path, &CountingClock::new(123));
assert_eq!(library.entries().len(), 2);
assert_eq!(library.entries()[0].title, "Alpha");
@@ -262,7 +281,7 @@ mod tests {
assert_eq!(library.entries()[0].app_version, "1.0.0");
assert_eq!(library.entries()[0].manifest.app_mode, AppMode::Game);
assert!(library.entries()[0].path.ends_with("alpha"));
assert!(library.entries()[0].discovered_at >= UNIX_EPOCH);
assert_eq!(library.entries()[0].discovered_at, 123);
assert_eq!(library.entries()[1].title, "Zeta");
assert!(library.diagnostics().iter().any(|diagnostic| {
@@ -285,6 +304,7 @@ mod tests {
let entry = GameLibraryEntry::new(
path.clone(),
CartridgeManifest {
memcard_slots: None,
magic: "PMTU".to_string(),
cartridge_version: 1,
app_id: 42,
@@ -293,7 +313,7 @@ mod tests {
app_mode: AppMode::Game,
capabilities: vec![],
},
UNIX_EPOCH,
0,
);
let target = entry.switch_target();
@@ -309,7 +329,7 @@ mod tests {
let root = TestRoot::new();
let missing = root.path.join("missing");
let library = discover_games_root(&missing);
let library = discover_games_root(&missing, &CountingClock::new(0));
assert!(library.is_empty());
assert_eq!(library.diagnostics().len(), 1);
@@ -321,7 +341,7 @@ mod tests {
let games_root =
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges");
let library = discover_games_root(games_root);
let library = discover_games_root(games_root, &CountingClock::new(0));
let entries = library.entries();
assert!(entries.iter().any(|entry| {
@@ -333,4 +353,24 @@ mod tests {
entry.app_id == 2 && entry.title == "Dummy Boy" && entry.path.ends_with("dummy-boy")
}));
}
#[test]
fn discovery_samples_once_per_scan_and_preserves_adjustments_and_full_range() {
let root = TestRoot::new();
root.add_candidate("zeta", manifest("Zeta", 2, "Game"), true);
root.add_candidate("alpha", manifest("Alpha", 1, "Game"), true);
let clock = CountingClock::new(u64::MAX);
let first = discover_games_root(&root.path, &clock);
assert_eq!(clock.calls.get(), 1);
assert_eq!(first.entries().len(), 2);
assert!(first.entries().iter().all(|entry| entry.discovered_at == u64::MAX));
clock.seconds.set(7);
let second = discover_games_root(&root.path, &clock);
assert_eq!(clock.calls.get(), 2);
assert!(second.entries().iter().all(|entry| entry.discovered_at == 7));
assert_eq!(second.entries()[0].app_id, 1);
assert_eq!(second.entries()[1].app_id, 2);
assert!(first.entries().iter().all(|entry| entry.discovered_at == u64::MAX));
}
}
@@ -1,481 +1,21 @@
use crate::fs::{FsError, VirtualFS};
use crate::services::async_work::{AsyncWorkJobKind, AsyncWorkPriority};
use std::collections::HashMap;
pub const MEMCARD_SLOT_COUNT: usize = 32;
pub const MEMCARD_SLOT_CAPACITY_BYTES: usize = 32 * 1024;
const SLOT_FILE_MAGIC: &[u8; 4] = b"PMMS";
const SLOT_FILE_VERSION: u8 = 1;
const SLOT_HEADER_SIZE: usize = 4 + 1 + 16 + 8 + 4 + 4;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
pub enum MemcardStatus {
Ok = 0,
Empty = 1,
NotFound = 2,
NoSpace = 3,
AccessDenied = 4,
Corrupt = 5,
Conflict = 6,
Unavailable = 7,
InvalidState = 8,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
pub enum MemcardSlotState {
Empty = 0,
Staged = 1,
Committed = 2,
Corrupt = 3,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MemcardSlotStat {
pub state: MemcardSlotState,
pub used_bytes: u32,
pub generation: u64,
pub checksum: u32,
}
pub struct MemcardReadResult {
pub status: MemcardStatus,
pub bytes: Vec<u8>,
pub bytes_read: u32,
}
pub struct MemcardWriteResult {
pub status: MemcardStatus,
pub bytes_written: u32,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemcardAsyncLaneOperation {
SlotWrite,
SlotCommit,
SlotClear,
SlotRead,
SlotStat,
}
impl MemcardAsyncLaneOperation {
pub const fn job_kind(self) -> AsyncWorkJobKind {
AsyncWorkJobKind::Memcard
}
pub const fn priority(self) -> AsyncWorkPriority {
match self {
Self::SlotWrite | Self::SlotCommit | Self::SlotClear => {
AsyncWorkPriority::MemcardCommitWrite
}
Self::SlotRead | Self::SlotStat => AsyncWorkPriority::NonCriticalReadList,
}
}
}
#[derive(Debug, Clone)]
struct SlotImage {
payload: Vec<u8>,
generation: u64,
checksum: u32,
save_uuid: [u8; 16],
}
//! Shared image-backed memory cards. Guest operations use RAM snapshots; only the
//! shared IO worker owns storage during a publication. Legacy per-slot files are
//! intentionally neither read nor migrated by this service.
pub mod admission;
pub mod guest;
pub mod image;
pub mod session;
pub mod transaction;
#[derive(Default)]
pub struct MemcardService {
staged: HashMap<(u32, u8), Vec<u8>>,
pub session: session::Session,
pub lane: std::sync::Arc<crate::AsyncWorkLane>,
pub admission: admission::Admission,
pub diagnostic: String,
}
impl MemcardService {
pub fn new() -> Self {
Self::default()
}
pub fn clear_all_staging(&mut self) {
self.staged.clear();
}
pub fn slot_count(&self) -> usize {
MEMCARD_SLOT_COUNT
}
pub fn slot_stat(&self, fs: &VirtualFS, app_id: u32, slot: u8) -> MemcardSlotStat {
if let Some(staged_payload) = self.staged.get(&(app_id, slot)) {
let generation = match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => committed.generation.saturating_add(1),
_ => 1,
};
return MemcardSlotStat {
state: MemcardSlotState::Staged,
used_bytes: staged_payload.len() as u32,
generation,
checksum: checksum32(staged_payload),
};
}
match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => MemcardSlotStat {
state: MemcardSlotState::Committed,
used_bytes: committed.payload.len() as u32,
generation: committed.generation,
checksum: committed.checksum,
},
Ok(None) => MemcardSlotStat {
state: MemcardSlotState::Empty,
used_bytes: 0,
generation: 0,
checksum: 0,
},
Err(MemcardStatus::Corrupt) => MemcardSlotStat {
state: MemcardSlotState::Corrupt,
used_bytes: 0,
generation: 0,
checksum: 0,
},
Err(_) => MemcardSlotStat {
state: MemcardSlotState::Empty,
used_bytes: 0,
generation: 0,
checksum: 0,
},
}
}
pub fn slot_read(
&self,
fs: &VirtualFS,
app_id: u32,
slot: u8,
offset: usize,
max_bytes: usize,
) -> MemcardReadResult {
if let Some(staged_payload) = self.staged.get(&(app_id, slot)) {
return Self::slice_payload(staged_payload, offset, max_bytes);
}
match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => Self::slice_payload(&committed.payload, offset, max_bytes),
Ok(None) => {
MemcardReadResult { status: MemcardStatus::Empty, bytes: Vec::new(), bytes_read: 0 }
}
Err(status) => MemcardReadResult { status, bytes: Vec::new(), bytes_read: 0 },
}
}
pub fn slot_write(
&mut self,
fs: &VirtualFS,
app_id: u32,
slot: u8,
offset: usize,
data: &[u8],
) -> MemcardWriteResult {
let end = match offset.checked_add(data.len()) {
Some(v) => v,
None => {
return MemcardWriteResult { status: MemcardStatus::NoSpace, bytes_written: 0 };
}
};
if end > MEMCARD_SLOT_CAPACITY_BYTES {
return MemcardWriteResult { status: MemcardStatus::NoSpace, bytes_written: 0 };
}
let mut payload = if let Some(staged_payload) = self.staged.get(&(app_id, slot)) {
staged_payload.clone()
} else {
match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => committed.payload,
Ok(None) => Vec::new(),
Err(status) => {
return MemcardWriteResult { status, bytes_written: 0 };
}
}
};
if offset > payload.len() {
payload.resize(offset, 0);
}
if end > payload.len() {
payload.resize(end, 0);
}
payload[offset..end].copy_from_slice(data);
self.staged.insert((app_id, slot), payload);
MemcardWriteResult { status: MemcardStatus::Ok, bytes_written: data.len() as u32 }
}
pub fn slot_commit(&mut self, fs: &mut VirtualFS, app_id: u32, slot: u8) -> MemcardStatus {
let Some(staged_payload) = self.staged.get(&(app_id, slot)).cloned() else {
return MemcardStatus::InvalidState;
};
let (save_uuid, generation) = match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => (committed.save_uuid, committed.generation.saturating_add(1)),
Ok(None) => (make_save_uuid(app_id, slot), 1),
Err(status) => return status,
};
let checksum = checksum32(&staged_payload);
let encoded = encode_slot_file(SlotImage {
payload: staged_payload,
generation,
checksum,
save_uuid,
});
let path = slot_path(app_id, slot);
match fs.write_file(&path, &encoded) {
Ok(()) => {
self.staged.remove(&(app_id, slot));
MemcardStatus::Ok
}
Err(err) => map_fs_error(err),
}
}
pub fn slot_clear(&mut self, fs: &mut VirtualFS, app_id: u32, slot: u8) -> MemcardStatus {
self.staged.remove(&(app_id, slot));
let path = slot_path(app_id, slot);
match fs.delete(&path) {
Ok(()) => MemcardStatus::Ok,
Err(FsError::NotFound) => MemcardStatus::Empty,
Err(err) => map_fs_error(err),
}
}
fn slice_payload(payload: &[u8], offset: usize, max_bytes: usize) -> MemcardReadResult {
if offset >= payload.len() || max_bytes == 0 {
return MemcardReadResult {
status: MemcardStatus::Ok,
bytes: Vec::new(),
bytes_read: 0,
};
}
let end = payload.len().min(offset.saturating_add(max_bytes));
let bytes = payload[offset..end].to_vec();
MemcardReadResult { status: MemcardStatus::Ok, bytes_read: bytes.len() as u32, bytes }
}
fn load_committed(
&self,
fs: &VirtualFS,
app_id: u32,
slot: u8,
) -> Result<Option<SlotImage>, MemcardStatus> {
let path = slot_path(app_id, slot);
match fs.read_file(&path) {
Ok(bytes) => decode_slot_file(&bytes).map(Some),
Err(FsError::NotFound) => Ok(None),
Err(err) => Err(map_fs_error(err)),
}
}
}
fn slot_path(app_id: u32, slot: u8) -> String {
format!("/user/games/{}/memcard/slot_{:02}.pmem", app_id, slot)
}
fn map_fs_error(err: FsError) -> MemcardStatus {
match err {
FsError::NotFound => MemcardStatus::NotFound,
FsError::AlreadyExists => MemcardStatus::Conflict,
FsError::PermissionDenied => MemcardStatus::AccessDenied,
FsError::NotMounted | FsError::IOError(_) | FsError::Other(_) | FsError::InvalidPath(_) => {
MemcardStatus::Unavailable
}
}
}
fn checksum32(data: &[u8]) -> u32 {
let mut a: u32 = 1;
let mut b: u32 = 0;
const MOD: u32 = 65521;
for &byte in data {
a = (a + byte as u32) % MOD;
b = (b + a) % MOD;
}
(b << 16) | a
}
fn make_save_uuid(app_id: u32, slot: u8) -> [u8; 16] {
let mut out = [0u8; 16];
out[0..4].copy_from_slice(&app_id.to_le_bytes());
out[4] = slot;
out[5..13].copy_from_slice(
&(std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_nanos() as u64)
.unwrap_or(0))
.to_le_bytes(),
);
out[13] = 0x50;
out[14] = 0x4D;
out[15] = 0x31;
out
}
fn encode_slot_file(slot: SlotImage) -> Vec<u8> {
let mut out = Vec::with_capacity(SLOT_HEADER_SIZE + slot.payload.len());
out.extend_from_slice(SLOT_FILE_MAGIC);
out.push(SLOT_FILE_VERSION);
out.extend_from_slice(&slot.save_uuid);
out.extend_from_slice(&slot.generation.to_le_bytes());
out.extend_from_slice(&slot.checksum.to_le_bytes());
out.extend_from_slice(&(slot.payload.len() as u32).to_le_bytes());
out.extend_from_slice(&slot.payload);
out
}
fn decode_slot_file(bytes: &[u8]) -> Result<SlotImage, MemcardStatus> {
if bytes.len() < SLOT_HEADER_SIZE {
return Err(MemcardStatus::Corrupt);
}
if &bytes[0..4] != SLOT_FILE_MAGIC {
return Err(MemcardStatus::Corrupt);
}
if bytes[4] != SLOT_FILE_VERSION {
return Err(MemcardStatus::Corrupt);
}
let mut save_uuid = [0u8; 16];
save_uuid.copy_from_slice(&bytes[5..21]);
let generation =
u64::from_le_bytes(bytes[21..29].try_into().map_err(|_| MemcardStatus::Corrupt)?);
let checksum =
u32::from_le_bytes(bytes[29..33].try_into().map_err(|_| MemcardStatus::Corrupt)?);
let payload_size =
u32::from_le_bytes(bytes[33..37].try_into().map_err(|_| MemcardStatus::Corrupt)?) as usize;
if payload_size > MEMCARD_SLOT_CAPACITY_BYTES {
return Err(MemcardStatus::Corrupt);
}
if bytes.len() != SLOT_HEADER_SIZE + payload_size {
return Err(MemcardStatus::Corrupt);
}
let payload = bytes[SLOT_HEADER_SIZE..].to_vec();
if checksum32(&payload) != checksum {
return Err(MemcardStatus::Corrupt);
}
Ok(SlotImage { payload, generation, checksum, save_uuid })
}
#[cfg(test)]
mod tests {
use super::*;
use crate::fs::{FsBackend, FsEntry};
use std::collections::HashMap;
struct MockBackend {
files: HashMap<String, Vec<u8>>,
}
impl MockBackend {
fn new() -> Self {
Self { files: HashMap::new() }
}
}
impl FsBackend for MockBackend {
fn mount(&mut self) -> Result<(), FsError> {
Ok(())
}
fn unmount(&mut self) {}
fn list_dir(&self, _path: &str) -> Result<Vec<FsEntry>, FsError> {
Ok(Vec::new())
}
fn read_file(&self, path: &str) -> Result<Vec<u8>, FsError> {
self.files.get(path).cloned().ok_or(FsError::NotFound)
}
fn write_file(&mut self, path: &str, data: &[u8]) -> Result<(), FsError> {
self.files.insert(path.to_string(), data.to_vec());
Ok(())
}
fn delete(&mut self, path: &str) -> Result<(), FsError> {
self.files.remove(path).map(|_| ()).ok_or(FsError::NotFound)
}
fn exists(&self, path: &str) -> bool {
self.files.contains_key(path)
}
fn is_healthy(&self) -> bool {
true
}
}
#[test]
fn slot_roundtrip_commit_and_generation() {
let mut fs = VirtualFS::new();
fs.mount(Box::new(MockBackend::new())).expect("mount");
let mut mem = MemcardService::new();
let write = mem.slot_write(&fs, 10, 0, 0, b"hello");
assert_eq!(write.status, MemcardStatus::Ok);
assert_eq!(write.bytes_written, 5);
let staged = mem.slot_stat(&fs, 10, 0);
assert_eq!(staged.state, MemcardSlotState::Staged);
assert_eq!(staged.generation, 1);
assert_eq!(mem.slot_commit(&mut fs, 10, 0), MemcardStatus::Ok);
let committed = mem.slot_stat(&fs, 10, 0);
assert_eq!(committed.state, MemcardSlotState::Committed);
assert_eq!(committed.generation, 1);
let write2 = mem.slot_write(&fs, 10, 0, 5, b"!");
assert_eq!(write2.status, MemcardStatus::Ok);
assert_eq!(mem.slot_commit(&mut fs, 10, 0), MemcardStatus::Ok);
let committed2 = mem.slot_stat(&fs, 10, 0);
assert_eq!(committed2.generation, 2);
let read = mem.slot_read(&fs, 10, 0, 0, 10);
assert_eq!(read.status, MemcardStatus::Ok);
assert_eq!(read.bytes, b"hello!");
assert_eq!(read.bytes_read, 6);
}
#[test]
fn slot_clear_missing_is_empty() {
let mut fs = VirtualFS::new();
fs.mount(Box::new(MockBackend::new())).expect("mount");
let mut mem = MemcardService::new();
assert_eq!(mem.slot_clear(&mut fs, 1, 1), MemcardStatus::Empty);
}
#[test]
fn slot_stat_reports_corruption() {
let mut fs = VirtualFS::new();
let mut backend = MockBackend::new();
backend.files.insert(slot_path(7, 2), vec![0, 1, 2, 3, 4]);
fs.mount(Box::new(backend)).expect("mount");
let mem = MemcardService::new();
let stat = mem.slot_stat(&fs, 7, 2);
assert_eq!(stat.state, MemcardSlotState::Corrupt);
}
#[test]
fn memcard_async_lane_operations_classify_priority_without_changing_public_api() {
assert_eq!(MemcardAsyncLaneOperation::SlotWrite.job_kind(), AsyncWorkJobKind::Memcard);
assert_eq!(
MemcardAsyncLaneOperation::SlotWrite.priority(),
AsyncWorkPriority::MemcardCommitWrite
);
assert_eq!(
MemcardAsyncLaneOperation::SlotCommit.priority(),
AsyncWorkPriority::MemcardCommitWrite
);
assert_eq!(
MemcardAsyncLaneOperation::SlotClear.priority(),
AsyncWorkPriority::MemcardCommitWrite
);
assert_eq!(
MemcardAsyncLaneOperation::SlotRead.priority(),
AsyncWorkPriority::NonCriticalReadList
);
assert_eq!(
MemcardAsyncLaneOperation::SlotStat.priority(),
AsyncWorkPriority::NonCriticalReadList
);
}
}
@@ -0,0 +1,363 @@
//! External SO/Hub choices prepare the snapshot before any game boot execution.
use super::{
MemcardService,
image::*,
session::Session,
transaction::{Card, PublicationControl},
};
use prometeu_hal::memcard::MemcardStorage;
use std::sync::{Arc, Mutex, mpsc};
use std::time::{Duration, Instant};
pub const DEFAULT_SNAPSHOT_BUDGET: usize = 5 * 1024 * 1024;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Choice {
Persistent,
MemoryFresh,
MemoryExisting,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PreparationState {
Idle,
Pending,
Ready,
Failed(Error),
}
enum Prepared {
Card(Result<Card>),
Session(Session, Result<()>),
Replacement(Session, Result<()>),
Maintenance(Card, Result<()>),
}
pub struct Admission {
installed: Option<Card>,
receiver: Option<mpsc::Receiver<Prepared>>,
admitted: Option<Instant>,
control: Option<Arc<PublicationControl>>,
pub state: PreparationState,
pub snapshot_budget: usize,
faulted: bool,
}
impl Default for Admission {
fn default() -> Self {
Self {
installed: None,
receiver: None,
admitted: None,
control: None,
state: PreparationState::Idle,
snapshot_budget: DEFAULT_SNAPSHOT_BUDGET,
faulted: false,
}
}
}
impl MemcardService {
pub fn host_faulted(&self) -> bool {
self.admission.faulted || self.session.host_faulted()
}
pub fn card_installed(&self) -> bool {
self.admission.installed.is_some()
}
pub fn installed_health(&self) -> Option<(bool, bool, bool)> {
self.admission.installed.as_ref().map(|card| {
(card.recovered, card.degraded, card.write_blocked || card.storage_read_only())
})
}
pub fn card_has_game(&self, app_id: u32) -> bool {
self.admission
.installed
.as_ref()
.is_some_and(|c| c.catalog.games.iter().any(|g| g.app_id == app_id))
}
pub fn uninstall_card(&mut self) -> Result<()> {
if self.session.mode().is_some()
|| self.session.has_in_flight()
|| self.admission.receiver.is_some()
{
return Err(Error::Busy);
}
self.admission.installed = None;
self.admission.state = PreparationState::Idle;
Ok(())
}
pub fn mount_card(&mut self, storage: Box<dyn MemcardStorage>) -> Result<()> {
self.mount_card_with(move || Ok(storage))
}
pub fn mount_card_with(
&mut self,
open: impl FnOnce() -> Result<Box<dyn MemcardStorage>> + Send + 'static,
) -> Result<()> {
if self.admission.installed.is_some()
|| self.admission.receiver.is_some()
|| self.session.mode().is_some()
|| self.session.has_in_flight()
{
return Err(Error::Busy);
}
if self.admission.faulted {
return Err(Error::ReadOnly);
}
let (tx, rx) = mpsc::channel();
self.lane
.submit_memcard_commit_write(move |_| {
let _ = tx.send(Prepared::Card(open().and_then(Card::mount)));
crate::AsyncWorkJobOutcome::Completed
})
.map_err(|_| Error::InvalidState)?;
self.admission.receiver = Some(rx);
self.admission.admitted = Some(Instant::now());
self.admission.state = PreparationState::Pending;
Ok(())
}
pub fn choose_for_game(
&mut self,
app_id: u32,
count: usize,
choice: Choice,
created_at: u64,
) -> Result<()> {
if self.admission.receiver.is_some()
|| self.session.mode().is_some()
|| self.session.has_in_flight()
{
return Err(Error::Busy);
}
if self.admission.faulted {
return Err(Error::ReadOnly);
}
if choice != Choice::MemoryFresh && self.admission.installed.is_none() {
return Err(Error::InvalidState);
}
if Session::required_bytes(count)? > self.admission.snapshot_budget {
return Err(Error::OutOfMemory);
}
if let Some(card) = &self.admission.installed {
let owned =
card.catalog.games.iter().find(|g| g.app_id == app_id).map_or(0, |g| g.slots.len());
if choice == Choice::Persistent {
if card.storage_read_only() || card.write_blocked {
return Err(Error::ReadOnly);
}
if count.saturating_sub(owned)
> card.current().slots.iter().filter(|s| !s.assigned).count()
{
return Err(Error::NoSpace);
}
}
if choice == Choice::MemoryExisting && owned == 0 {
return Err(Error::InvalidState);
}
}
let handoff = Arc::new(Mutex::new(self.admission.installed.take()));
let worker_handoff = handoff.clone();
let control = Arc::new(PublicationControl::default());
let worker_control = control.clone();
let budget = self.admission.snapshot_budget;
let (tx, rx) = mpsc::channel();
let submitted = self.lane.submit_memcard_commit_write(move |_| {
let mut card = worker_handoff.lock().unwrap().take();
let mut session = Session::default();
let result = (|| {
if worker_control.canceled() {
session.retain_idle_card_opt(card.take());
return Err(Error::Canceled);
}
match choice {
Choice::MemoryFresh => {
session.start_memory_with_card(app_id, count, budget, card.take())?;
}
Choice::MemoryExisting => {
session.load_card_memory(card.take().unwrap(), app_id, count, budget)?;
}
Choice::Persistent => {
let mut card = card.take().unwrap();
if card.storage_read_only() || card.write_blocked {
session.retain_idle_card(card);
return Err(Error::ReadOnly);
}
if card.catalog.games.iter().any(|g| g.app_id == app_id) {
if let Err(e) = card.grow(app_id, count, &worker_control) {
session.retain_idle_card(card);
return Err(e);
}
session.load_card(card, app_id, count, budget)?;
} else {
session.prepare_new_card(card, app_id, count, created_at, budget)?;
}
}
}
session.begin_boot();
Ok(())
})();
let _ = tx.send(Prepared::Session(session, result));
crate::AsyncWorkJobOutcome::Completed
});
if submitted.is_err() {
self.admission.installed = handoff.lock().unwrap().take();
return Err(Error::InvalidState);
}
self.admission.control = Some(control);
self.admission.receiver = Some(rx);
self.admission.admitted = Some(Instant::now());
self.admission.state = PreparationState::Pending;
Ok(())
}
/// Whole-game removal is only available outside a resident game session.
pub fn remove_game(&mut self, app_id: u32) -> Result<()> {
self.maintain_card(move |card, control| card.remove_game(app_id, control))
}
pub fn revalidate_card(&mut self) -> Result<()> {
self.maintain_card(|card, control| card.revalidate(control))
}
pub fn reintegrate_block(&mut self, block: u8) -> Result<()> {
self.maintain_card(move |card, control| card.reintegrate(block, control))
}
fn maintain_card(
&mut self,
operation: impl FnOnce(&mut Card, &PublicationControl) -> Result<()> + Send + 'static,
) -> Result<()> {
if self.admission.receiver.is_some()
|| self.session.mode().is_some()
|| self.session.has_in_flight()
{
return Err(Error::Busy);
}
if self.admission.faulted {
return Err(Error::ReadOnly);
}
let card = self.admission.installed.take().ok_or(Error::InvalidState)?;
let handoff = Arc::new(Mutex::new(Some(card)));
let worker = handoff.clone();
let control = Arc::new(PublicationControl::default());
let worker_control = control.clone();
let (tx, rx) = mpsc::channel();
if self
.lane
.submit_memcard_commit_write(move |_| {
let mut card = worker.lock().unwrap().take().unwrap();
let result = operation(&mut card, &worker_control);
let _ = tx.send(Prepared::Maintenance(card, result));
crate::AsyncWorkJobOutcome::Completed
})
.is_err()
{
self.admission.installed = handoff.lock().unwrap().take();
return Err(Error::InvalidState);
}
self.admission.control = Some(control);
self.admission.receiver = Some(rx);
self.admission.admitted = Some(Instant::now());
self.admission.state = PreparationState::Pending;
Ok(())
}
/// Caller must suspend gameplay and obtain the player's keep-RAM/load-existing choice.
/// Once admitted, the resident continuation must wait for `PreparationState::Ready`.
pub fn replace_card(
&mut self,
storage: Box<dyn MemcardStorage>,
load_existing: bool,
) -> Result<()> {
if self.admission.receiver.is_some()
|| self.session.has_in_flight()
|| self.session.is_boot_active()
{
return Err(Error::Busy);
}
if self.admission.faulted {
return Err(Error::ReadOnly);
}
let handoff = Arc::new(Mutex::new(Some(std::mem::take(&mut self.session))));
let worker = handoff.clone();
let control = Arc::new(PublicationControl::default());
let worker_control = control.clone();
let (tx, rx) = mpsc::channel();
if self
.lane
.submit_memcard_commit_write(move |_| {
let mut session = worker.lock().unwrap().take().unwrap();
let result = session.replace_storage(storage, load_existing, &worker_control);
let _ = tx.send(Prepared::Replacement(session, result));
crate::AsyncWorkJobOutcome::Completed
})
.is_err()
{
self.session = handoff.lock().unwrap().take().unwrap();
return Err(Error::InvalidState);
}
self.admission.control = Some(control);
self.admission.receiver = Some(rx);
self.admission.admitted = Some(Instant::now());
self.admission.state = PreparationState::Pending;
Ok(())
}
pub fn poll(&mut self, now: Instant) {
self.session.poll(now);
if let Some(rx) = &self.admission.receiver {
match rx.try_recv() {
Ok(prepared) => {
if !self.admission.faulted {
self.admission.state = match prepared {
Prepared::Card(Ok(card)) => {
self.admission.installed = Some(card);
PreparationState::Ready
}
Prepared::Maintenance(card, result) => {
self.admission.installed = Some(card);
match result {
Ok(()) => PreparationState::Ready,
Err(e) => PreparationState::Failed(e),
}
}
Prepared::Replacement(session, result) => {
self.session = session;
match result {
Ok(()) => PreparationState::Ready,
Err(e) => PreparationState::Failed(e),
}
}
Prepared::Session(session, Ok(())) => {
self.session = session;
PreparationState::Ready
}
Prepared::Card(Err(e)) => PreparationState::Failed(e),
Prepared::Session(mut session, Err(e)) => {
session.end_session();
self.admission.installed = session.take_idle_card().ok().flatten();
PreparationState::Failed(e)
}
};
} else if let Prepared::Replacement(session, _) = prepared {
self.session = session;
}
self.admission.receiver = None;
self.admission.control = None;
}
Err(mpsc::TryRecvError::Disconnected) => {
self.admission.state = PreparationState::Failed(Error::InvalidState);
self.admission.receiver = None;
}
Err(mpsc::TryRecvError::Empty) => {
if self.admission.admitted.is_some_and(|at| {
now.saturating_duration_since(at) >= Duration::from_millis(500)
}) && let Some(control) = &self.admission.control
{
control.cancel();
}
if self.admission.admitted.is_some_and(|at| {
now.saturating_duration_since(at) >= Duration::from_secs(1)
}) {
self.admission.faulted = true;
self.admission.state = PreparationState::Failed(Error::Indeterminate);
}
}
}
}
if self.session.mode().is_none()
&& !self.session.has_in_flight()
&& self.admission.installed.is_none()
&& let Ok(card) = self.session.take_idle_card()
{
self.admission.installed = card;
}
}
}
@@ -0,0 +1,256 @@
//! Guest mem ABI. Only bounded copies cross the VM/native ownership boundary.
use super::{
MemcardService,
image::Error,
session::{Mode, RequestReason, RequestState},
};
use prometeu_bytecode::{HeapRef, TRAP_OOB, TRAP_TYPE, Value};
use prometeu_hal::{HostReturn, expect_int, syscalls::Syscall, vm_fault::VmFault};
use std::time::Instant;
fn index(args: &[Value], n: usize) -> Result<usize, VmFault> {
usize::try_from(expect_int(args, n)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Negative memcard range".into()))
}
fn opaque(args: &[Value], n: usize) -> Result<u64, VmFault> {
u64::try_from(expect_int(args, n)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Negative memcard identity".into()))
}
fn handle(args: &[Value], n: usize) -> Result<HeapRef, VmFault> {
match args.get(n) {
Some(Value::HeapRef(h)) => Ok(*h),
_ => Err(VmFault::Trap(TRAP_TYPE, "Expected Array<Int32>".into())),
}
}
fn text(args: &[Value], n: usize) -> Result<&str, VmFault> {
match args.get(n) {
Some(Value::String(s)) => Ok(s),
_ => Err(VmFault::Trap(TRAP_TYPE, "Expected String".into())),
}
}
pub fn status(e: Error) -> i64 {
use prometeu_hal::memcard::MemcardIoError as I;
match e {
Error::NoSpace | Error::Io(I::NoSpace) => 3,
Error::AccessDenied => 4,
Error::Corrupt => 5,
Error::Indeterminate => 6,
Error::Io(I::Unavailable) => 7,
Error::InvalidState | Error::Canceled => 8,
Error::Busy => 9,
Error::ReadOnly | Error::CounterExhausted | Error::Io(I::ReadOnly) => 10,
Error::InvalidRange | Error::Io(I::InvalidRange) => 11,
Error::Unsupported | Error::Io(I::Unsupported) => 12,
Error::Io(I::IoError) => 13,
Error::OutOfMemory => 16,
}
}
fn error(ret: &mut HostReturn, syscall: Syscall, e: Error) {
ret.push_int(status(e));
for _ in 1..syscall.results_count() {
ret.push_null();
}
}
impl MemcardService {
pub fn guest(
&mut self,
syscall: Syscall,
args: &[Value],
ret: &mut HostReturn,
app_id: u32,
timestamp: u64,
game_profile: bool,
) -> Result<(), VmFault> {
let authorized = game_profile && self.session.app_id() == Some(app_id);
if syscall == Syscall::MemBootstrap {
if !authorized || !self.session.is_boot_active() {
return Err(VmFault::Trap(
TRAP_TYPE,
"Memcard snapshot is not admitted for bootstrap".into(),
));
}
ret.push_int(self.session.context() as i64);
return Ok(());
}
let context = opaque(args, 0)?;
if !authorized || context != self.session.context() {
error(ret, syscall, Error::AccessDenied);
return Ok(());
}
match syscall {
Syscall::MemSlotCount => {
ret.push_int(0);
ret.push_int(self.session.count() as i64);
}
Syscall::MemSlotStat => match self.session.descriptor(context, index(args, 1)?) {
Ok((d, used, dirty)) => {
ret.push_int(0);
ret.push_int(i64::from(used > 0));
ret.push_int(used as i64);
ret.push_int(d.generation as i64);
ret.push_int(d.update_at as i64);
ret.push_int(d.crc as i64);
ret.push_bool(dirty);
}
Err(e) => error(ret, syscall, e),
},
Syscall::MemSlotRead | Syscall::MemSlotWrite => {
let local = index(args, 1)?;
let offset = index(args, 2)?;
let array = handle(args, 3)?;
let array_offset = index(args, 4)?;
let count = index(args, 5)?;
if count > 4096 {
return Err(VmFault::Trap(
TRAP_OOB,
"Memcard transfer exceeds 4096 bytes".into(),
));
}
if let Err(e) = self.session.descriptor(context, local) {
error(ret, syscall, e);
return Ok(());
}
if offset.checked_add(count).is_none_or(|end| end > 65536) {
error(ret, syscall, Error::InvalidRange);
return Ok(());
}
ret.byte_arrays()?.validate(array, array_offset, count)?;
let mut bytes = [0; 4096];
if syscall == Syscall::MemSlotRead {
match self.session.read(context, local, offset, &mut bytes[..count]) {
Ok(n) => {
ret.byte_arrays()?.write(array, array_offset, &bytes[..n])?;
ret.push_int(0);
ret.push_int(n as i64)
}
Err(e) => error(ret, syscall, e),
}
} else {
ret.byte_arrays()?.read(array, array_offset, &mut bytes[..count])?;
match self.session.write(context, local, offset, &bytes[..count]) {
Ok(()) => {
ret.push_int(0);
ret.push_int(count as i64)
}
Err(e) => error(ret, syscall, e),
}
}
}
Syscall::MemSlotCommit => {
match self.session.commit(
context,
index(args, 1)?,
timestamp,
Instant::now(),
&self.lane,
) {
Ok(id) => {
ret.push_int(0);
ret.push_int(id as i64)
}
Err(e) => error(ret, syscall, e),
}
}
Syscall::MemSlotClear => match self.session.clear(context, index(args, 1)?) {
Ok(()) => ret.push_int(0),
Err(e) => error(ret, syscall, e),
},
Syscall::MemQuery => match self.session.query(context, opaque(args, 1)?) {
Ok(r) => {
ret.push_int(0);
ret.push_int(match r.state {
RequestState::Pending => 0,
RequestState::Success => 1,
RequestState::Failure => 2,
RequestState::Indeterminate => 3,
RequestState::MemoryOnly => 4,
});
ret.push_int(match r.reason {
RequestReason::None => 0,
RequestReason::Storage(e) => status(e),
RequestReason::Timeout | RequestReason::RestartRequired => 15,
});
}
Err(e) => error(ret, syscall, e),
},
Syscall::MemRelease => match self.session.release_request(context, opaque(args, 1)?) {
Ok(()) => ret.push_int(0),
Err(e) => error(ret, syscall, e),
},
Syscall::MemInfo => {
ret.push_int(0);
ret.push_int(i64::from(self.session.mode() == Some(Mode::MemoryOnly)));
ret.push_bool(self.session.is_new());
let (recovered, degraded, blocked) = self.session.health();
ret.push_bool(recovered);
ret.push_bool(degraded);
ret.push_bool(blocked);
}
Syscall::MemMetadata => match self.session.presentation(context) {
Ok(Some(g)) => {
ret.push_int(0);
ret.push_string(&g.title)?;
ret.push_int(g.data_format_version as i64);
ret.push_int(g.created_at as i64)
}
Ok(None) => {
ret.push_int(0);
ret.push_string("")?;
ret.push_int(0);
ret.push_int(timestamp as i64)
}
Err(e) => error(ret, syscall, e),
},
Syscall::MemPresentation => {
let title = text(args, 1)?;
let version = u32::try_from(index(args, 2)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Invalid dataFormatVersion".into()))?;
let frames = u8::try_from(index(args, 3)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Invalid icon frames".into()))?;
let duration = u16::try_from(index(args, 4)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Invalid icon duration".into()))?;
let array = handle(args, 5)?;
let offset = index(args, 6)?;
let count = index(args, 7)?;
if count > 2096 || title.len() > 128 {
error(ret, syscall, Error::InvalidRange);
return Ok(());
}
let mut bytes = [0; 2096];
ret.byte_arrays()?.read(array, offset, &mut bytes[..count])?;
match self.session.set_presentation(
context,
title,
version,
frames,
duration,
&bytes[..count],
timestamp,
) {
Ok(()) => ret.push_int(0),
Err(e) => error(ret, syscall, e),
}
}
Syscall::MemDiagnostic => {
let message = text(args, 1)?;
if message.len() > 1024 {
error(ret, syscall, Error::InvalidRange)
} else {
self.diagnostic.clear();
self.diagnostic.push_str(message);
ret.push_int(0)
}
}
Syscall::MemPublishPresentation => {
match self.session.publish_presentation(context, &self.lane, Instant::now()) {
Ok(id) => {
ret.push_int(0);
ret.push_int(id as i64)
}
Err(e) => error(ret, syscall, e),
}
}
_ => return Err(VmFault::Trap(TRAP_TYPE, "Invalid memcard operation".into())),
}
Ok(())
}
}
@@ -0,0 +1,452 @@
//! Fixed shared-card codec. All offsets and CRC coverage are defined in the save spec.
use prometeu_hal::memcard::{MemcardIoError, MemcardStorage};
use serde::{Deserialize, Serialize};
pub const SLOT_COUNT: usize = 64;
pub const BLOCK_COUNT: usize = 68;
pub const SLOT_BYTES: usize = 65_536;
pub const PAGE_BYTES: usize = 4096;
pub const CATALOG_BYTES: usize = 131_072;
pub const ICON_BYTES: usize = 262_144;
pub const CATALOG_OFFSETS: [u64; 2] = [16_384, 409_600];
pub const ICON_OFFSETS: [u64; 2] = [147_456, 540_672];
pub const MAP_OFFSETS: [u64; 2] = [8192, 12_288];
pub const DATA_OFFSET: u64 = 802_816;
pub const IMAGE_BYTES: u64 = DATA_OFFSET + (BLOCK_COUNT * SLOT_BYTES) as u64;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Error {
Io(MemcardIoError),
Corrupt,
Unsupported,
NoSpace,
InvalidRange,
CounterExhausted,
ReadOnly,
Indeterminate,
Busy,
Canceled,
OutOfMemory,
AccessDenied,
InvalidState,
}
impl From<MemcardIoError> for Error {
fn from(e: MemcardIoError) -> Self {
Self::Io(e)
}
}
pub type Result<T> = std::result::Result<T, Error>;
pub fn crc32c(bytes: &[u8]) -> u32 {
crc_extend(!0, bytes) ^ !0
}
pub fn crc_extend(mut crc: u32, bytes: &[u8]) -> u32 {
for &byte in bytes {
crc ^= byte as u32;
for _ in 0..8 {
crc = (crc >> 1) ^ (0x82f6_3b78 & 0u32.wrapping_sub(crc & 1));
}
}
crc
}
fn u32_at(b: &[u8], p: usize) -> u32 {
u32::from_le_bytes(b[p..p + 4].try_into().unwrap())
}
fn u64_at(b: &[u8], p: usize) -> u64 {
u64::from_le_bytes(b[p..p + 8].try_into().unwrap())
}
fn put32(b: &mut [u8], p: usize, n: u32) {
b[p..p + 4].copy_from_slice(&n.to_le_bytes());
}
fn put64(b: &mut [u8], p: usize, n: u64) {
b[p..p + 8].copy_from_slice(&n.to_le_bytes());
}
fn zero(b: &[u8]) -> Result<()> {
if b.iter().any(|&v| v != 0) { Err(Error::Corrupt) } else { Ok(()) }
}
fn page_crc(b: &[u8; PAGE_BYTES]) -> Result<()> {
if crc32c(&b[..4092]) != u32_at(b, 4092) {
return Err(Error::Corrupt);
}
Ok(())
}
fn seal(b: &mut [u8; PAGE_BYTES]) {
let crc = crc32c(&b[..4092]);
put32(b, 4092, crc);
}
pub fn identity_page(id: [u8; 16]) -> [u8; PAGE_BYTES] {
let mut b = [0; PAGE_BYTES];
b[..8].copy_from_slice(b"PMCARD1\0");
put32(&mut b, 8, 1);
put32(&mut b, 12, IMAGE_BYTES as u32);
b[16..32].copy_from_slice(&id);
seal(&mut b);
b
}
pub fn decode_identity(b: &[u8; PAGE_BYTES]) -> Result<[u8; 16]> {
if &b[..8] != b"PMCARD1\0" || u32_at(b, 8) != 1 {
return Err(Error::Unsupported);
}
page_crc(b)?;
if u32_at(b, 12) != IMAGE_BYTES as u32 {
return Err(Error::Corrupt);
}
zero(&b[32..4092])?;
Ok(b[16..32].try_into().unwrap())
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Icon {
pub offset: u32,
pub frames: u8,
pub duration: u16,
pub crc32c: u32,
}
impl Icon {
pub fn length(&self) -> Result<usize> {
if !(1..=4).contains(&self.frames)
|| self.duration == 0
|| (self.frames == 1 && self.duration != 1)
{
return Err(Error::Corrupt);
}
Ok(48 + 512 * self.frames as usize)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Game {
pub app_id: u32,
pub title: String,
#[serde(rename = "dataFormatVersion")]
pub data_format_version: u32,
pub created_at: u64,
pub slots: Vec<u8>,
pub icon: Icon,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Catalog {
#[serde(rename = "metadataVersion")]
pub metadata_version: u32,
pub games: Vec<Game>,
}
impl Default for Catalog {
fn default() -> Self {
Self { metadata_version: 1, games: Vec::new() }
}
}
impl Catalog {
pub fn validate(&self, icons_used: usize) -> Result<[bool; SLOT_COUNT]> {
if self.metadata_version != 1 || self.games.len() > 64 || icons_used > ICON_BYTES {
return Err(Error::Corrupt);
}
let mut assigned = [false; SLOT_COUNT];
let mut spans = Vec::with_capacity(64);
for (index, g) in self.games.iter().enumerate() {
if g.title.trim().is_empty()
|| g.title.len() > 128
|| g.slots.is_empty()
|| g.slots.len() > 64
|| self.games[..index].iter().any(|prior| prior.app_id == g.app_id)
{
return Err(Error::Corrupt);
}
for &slot in &g.slots {
let used = assigned.get_mut(slot as usize).ok_or(Error::Corrupt)?;
if *used {
return Err(Error::Corrupt);
}
*used = true;
}
let start = g.icon.offset as usize;
let end = start.checked_add(g.icon.length()?).ok_or(Error::Corrupt)?;
if end > icons_used || spans.iter().any(|&(a, b)| start < b && a < end) {
return Err(Error::Corrupt);
}
spans.push((start, end));
}
Ok(assigned)
}
pub fn encode(&self, icons_used: usize) -> Result<Vec<u8>> {
self.validate(icons_used)?;
let b = serde_json::to_vec(self).map_err(|_| Error::Corrupt)?;
if b.len() > CATALOG_BYTES {
return Err(Error::NoSpace);
}
Ok(b)
}
pub fn decode(b: &[u8], icons_used: usize) -> Result<Self> {
if b.len() > CATALOG_BYTES {
return Err(Error::Corrupt);
}
// Bound nesting before serde; strings (including escaped quotes) do not count.
let (mut depth, mut quoted, mut escaped) = (0u8, false, false);
for &v in b {
if quoted {
if escaped {
escaped = false;
} else if v == b'\\' {
escaped = true;
} else if v == b'"' {
quoted = false;
}
} else {
match v {
b'"' => quoted = true,
b'[' | b'{' => {
depth = depth.checked_add(1).ok_or(Error::Corrupt)?;
if depth > 8 {
return Err(Error::Corrupt);
}
}
b']' | b'}' => depth = depth.checked_sub(1).ok_or(Error::Corrupt)?,
_ => {}
}
}
}
let catalog: Self = serde_json::from_slice(b).map_err(|_| Error::Corrupt)?;
catalog.validate(icons_used)?;
Ok(catalog)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Slot {
pub assigned: bool,
pub block: Option<u8>,
pub used: u32,
pub generation: u64,
pub update_at: u64,
pub crc: u32,
}
impl Slot {
fn validate(&self) -> Result<()> {
if !self.assigned && *self != Self::default() {
return Err(Error::Corrupt);
}
if self.generation == 0 && (self.update_at != 0 || self.block.is_some()) {
return Err(Error::Corrupt);
}
match self.block {
Some(id)
if id as usize >= BLOCK_COUNT
|| self.used == 0
|| self.used as usize > SLOT_BYTES =>
{
Err(Error::Corrupt)
}
None if self.used != 0 || self.crc != 0 => Err(Error::Corrupt),
_ => Ok(()),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Map {
pub card_id: [u8; 16],
pub sequence: u64,
pub public_copy: usize,
pub catalog_len: u32,
pub catalog_crc: u32,
pub icons_len: u32,
pub icons_crc: u32,
pub order: [u8; BLOCK_COUNT],
pub quarantine: [bool; BLOCK_COUNT],
pub slots: [Slot; SLOT_COUNT],
}
impl Map {
pub fn new(card_id: [u8; 16]) -> Self {
Self {
card_id,
sequence: 1,
public_copy: 0,
catalog_len: 0,
catalog_crc: 0,
icons_len: 0,
icons_crc: 0,
order: std::array::from_fn(|i| i as u8),
quarantine: [false; BLOCK_COUNT],
slots: [Slot::default(); SLOT_COUNT],
}
}
pub fn encode(&self) -> Result<[u8; PAGE_BYTES]> {
if self.sequence == 0
|| self.public_copy > 1
|| self.catalog_len as usize > CATALOG_BYTES
|| self.icons_len as usize > ICON_BYTES
{
return Err(Error::Corrupt);
}
let mut seen = [false; BLOCK_COUNT];
for &id in &self.order {
let v = seen.get_mut(id as usize).ok_or(Error::Corrupt)?;
if *v {
return Err(Error::Corrupt);
}
*v = true;
}
let mut owned = [false; BLOCK_COUNT];
let mut b = [0; PAGE_BYTES];
b[..8].copy_from_slice(b"PMMAP1\0\0");
put64(&mut b, 8, self.sequence);
put32(&mut b, 16, self.public_copy as u32);
put32(&mut b, 20, self.catalog_len);
put32(&mut b, 24, self.catalog_crc);
put32(&mut b, 28, self.icons_len);
put32(&mut b, 32, self.icons_crc);
b[36..52].copy_from_slice(&self.card_id);
b[64..132].copy_from_slice(&self.order);
for i in 0..BLOCK_COUNT {
b[132 + i] = self.quarantine[i] as u8;
}
for (i, s) in self.slots.iter().enumerate() {
s.validate()?;
if let Some(id) = s.block {
if owned[id as usize] || self.quarantine[id as usize] {
return Err(Error::Corrupt);
}
owned[id as usize] = true;
}
let p = 256 + i * 40;
b[p] = if !s.assigned {
0
} else if s.block.is_none() {
1
} else {
2
};
b[p + 1] = s.block.unwrap_or(255);
put32(&mut b, p + 4, s.used);
put64(&mut b, p + 8, s.generation);
put64(&mut b, p + 16, s.update_at);
put32(&mut b, p + 24, s.crc);
}
seal(&mut b);
Ok(b)
}
pub fn decode(b: &[u8; PAGE_BYTES], card_id: [u8; 16]) -> Result<Self> {
page_crc(b)?;
if &b[..8] != b"PMMAP1\0\0" || b[36..52] != card_id {
return Err(Error::Corrupt);
}
zero(&b[52..64])?;
zero(&b[200..256])?;
zero(&b[2816..4092])?;
let mut m = Self::new(card_id);
m.sequence = u64_at(b, 8);
m.public_copy = u32_at(b, 16) as usize;
m.catalog_len = u32_at(b, 20);
m.catalog_crc = u32_at(b, 24);
m.icons_len = u32_at(b, 28);
m.icons_crc = u32_at(b, 32);
m.order.copy_from_slice(&b[64..132]);
for i in 0..BLOCK_COUNT {
if b[132 + i] > 1 {
return Err(Error::Corrupt);
}
m.quarantine[i] = b[132 + i] != 0;
}
for i in 0..SLOT_COUNT {
let p = 256 + i * 40;
zero(&b[p + 2..p + 4])?;
zero(&b[p + 28..p + 40])?;
if b[p] > 2 || (b[p] != 2 && b[p + 1] != 255) || (b[p] == 2 && b[p + 1] == 255) {
return Err(Error::Corrupt);
}
m.slots[i] = Slot {
assigned: b[p] != 0,
block: if b[p] == 2 { Some(b[p + 1]) } else { None },
used: u32_at(b, p + 4),
generation: u64_at(b, p + 8),
update_at: u64_at(b, p + 16),
crc: u32_at(b, p + 24),
};
}
if m.encode()? != *b {
return Err(Error::Corrupt);
}
Ok(m)
}
pub fn game_update_at(&self, game: &Game) -> Option<u64> {
game.slots
.iter()
.filter_map(|&i| self.slots.get(i as usize))
.filter(|s| s.generation > 0)
.map(|s| s.update_at)
.max()
}
}
pub fn read_region(io: &mut dyn MemcardStorage, offset: u64, out: &mut [u8]) -> Result<()> {
for (i, b) in out.chunks_mut(SLOT_BYTES).enumerate() {
io.read_at(offset + (i * SLOT_BYTES) as u64, b)?;
}
Ok(())
}
pub fn write_region(io: &mut dyn MemcardStorage, offset: u64, bytes: &[u8]) -> Result<()> {
for (i, b) in bytes.chunks(SLOT_BYTES).enumerate() {
io.write_at(offset + (i * SLOT_BYTES) as u64, b)?;
}
Ok(())
}
pub fn block_offset(id: u8) -> Result<u64> {
if id as usize >= BLOCK_COUNT {
return Err(Error::InvalidRange);
}
Ok(DATA_OFFSET + id as u64 * SLOT_BYTES as u64)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn crc_vectors_and_identity_golden() {
assert_eq!(crc32c(b""), 0);
assert_eq!(crc32c(b"123456789"), 0xe3069283);
let p = identity_page([7; 16]);
assert_eq!(&p[..16], b"PMCARD1\0\x01\0\0\0\0\x40\x50\0");
assert_eq!(decode_identity(&p), Ok([7; 16]));
}
#[test]
fn descriptor_roundtrip_rejects_reserved_and_alias() {
let mut m = Map::new([1; 16]);
m.slots[2] =
Slot { assigned: true, block: Some(3), used: 7, generation: 1, update_at: 0, crc: 12 };
assert_eq!(Map::decode(&m.encode().unwrap(), [1; 16]), Ok(m.clone()));
m.slots[4] = m.slots[2];
assert_eq!(m.encode(), Err(Error::Corrupt));
let mut b = Map::new([1; 16]).encode().unwrap();
b[3000] = 1;
seal(&mut b);
assert_eq!(Map::decode(&b, [1; 16]), Err(Error::Corrupt));
}
#[test]
fn closed_catalog_rejects_duplicates_and_deep_input() {
for s in [
r#"{"metadataVersion":1,"metadataVersion":1,"games":[]}"#,
r#"{"metadataVersion":1,"games":[],"extra":0}"#,
r#"[[[[[[[[[]]]]]]]]]"#,
] {
assert_eq!(Catalog::decode(s.as_bytes(), 0), Err(Error::Corrupt));
}
}
#[test]
fn maximum_catalog_and_icons_fit_and_preserve_uint64() {
let mut c = Catalog::default();
for i in 0..64 {
c.games.push(Game {
app_id: u32::MAX - i,
title: "\u{1}".repeat(127) + "a",
data_format_version: u32::MAX,
created_at: u64::MAX,
slots: vec![i as u8],
icon: Icon { offset: i * 2096, frames: 4, duration: u16::MAX, crc32c: u32::MAX },
});
}
let b = c.encode(64 * 2096).unwrap();
assert!(b.len() < CATALOG_BYTES);
assert_eq!(Catalog::decode(&b, 64 * 2096), Ok(c));
}
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,610 @@
//! Worker-owned transaction engine. Main-lane callers exchange owned requests/results.
use super::image::*;
use prometeu_hal::memcard::MemcardStorage;
use std::sync::atomic::{AtomicU8, Ordering};
/// Publication entry and pre-publication cancellation share a single linearization point.
#[derive(Default)]
pub struct PublicationControl(AtomicU8);
impl PublicationControl {
pub fn cancel(&self) {
self.0.fetch_or(2, Ordering::SeqCst);
}
pub fn canceled(&self) -> bool {
self.0.load(Ordering::SeqCst) & 2 != 0
}
pub fn publication_attempted(&self) -> bool {
self.0.load(Ordering::SeqCst) & 1 != 0
}
fn enter(&self) -> Result<()> {
self.0
.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |state| {
if state & 2 == 0 { Some(state | 1) } else { None }
})
.map(|_| ())
.map_err(|_| Error::Canceled)
}
fn check(&self) -> Result<()> {
if self.canceled() { Err(Error::Canceled) } else { Ok(()) }
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DurableResult {
Success,
Failure,
Indeterminate,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CommitResult {
pub durable: DurableResult,
pub error: Option<Error>,
pub sequence: u64,
}
pub struct Card {
io: Box<dyn MemcardStorage>,
pub maps: [Option<Map>; 2],
pub active: usize,
pub catalog: Catalog,
scratch: Box<[u8; SLOT_BYTES]>,
pub recovered: bool,
pub degraded: bool,
pub uncertain: bool,
pub(super) attempted_publication: Option<Map>,
pub write_blocked: bool,
known_quarantine: [bool; BLOCK_COUNT],
}
impl Card {
pub fn format(io: &mut dyn MemcardStorage, id: [u8; 16]) -> Result<()> {
if io.len()? != IMAGE_BYTES {
return Err(Error::InvalidRange);
}
let identity = identity_page(id);
io.write_at(0, &identity)?;
io.write_at(PAGE_BYTES as u64, &identity)?;
let catalog = Catalog::default().encode(0)?;
write_region(io, CATALOG_OFFSETS[0], &catalog)?;
let mut map = Map::new(id);
map.catalog_len = catalog.len() as u32;
map.catalog_crc = crc32c(&catalog);
let encoded = map.encode()?;
io.write_at(MAP_OFFSETS[0], &encoded)?;
io.write_at(MAP_OFFSETS[1], &encoded)?;
io.sync()?;
Ok(())
}
pub fn mount(mut io: Box<dyn MemcardStorage>) -> Result<Self> {
if io.len()? != IMAGE_BYTES {
return Err(Error::Unsupported);
}
let mut page = [0; PAGE_BYTES];
let mut identities = [None; 2];
let mut recognized = false;
for (i, item) in identities.iter_mut().enumerate() {
io.read_at((i * PAGE_BYTES) as u64, &mut page)?;
recognized |= &page[..8] == b"PMCARD1\0"
&& u32::from_le_bytes(page[8..12].try_into().unwrap()) == 1;
*item = decode_identity(&page).ok();
}
let id = identities[0].or(identities[1]).ok_or(if recognized {
Error::Corrupt
} else {
Error::Unsupported
})?;
if identities.iter().flatten().any(|other| *other != id) {
return Err(Error::Corrupt);
}
let mut maps: [Option<Map>; 2] = [None, None];
let mut unknown_metadata = false;
for i in 0..2 {
io.read_at(MAP_OFFSETS[i], &mut page)?;
maps[i] = Map::decode(&page, id).ok();
// A zero page is a verified retirement. An undecodable nonzero page
// may have lost quarantine information; do not silently reuse its pool.
unknown_metadata |= maps[i].is_none() && page.iter().any(|&byte| byte != 0);
}
if let (Some(a), Some(b)) = (&maps[0], &maps[1])
&& a.sequence == b.sequence
&& a != b
{
return Err(Error::Corrupt);
}
let highest = maps.iter().flatten().map(|m| m.sequence).max().unwrap_or(0);
let mut known = [false; BLOCK_COUNT];
for m in maps.iter().flatten() {
for (i, &bad) in m.quarantine.iter().enumerate() {
known[i] |= bad;
}
}
let mut scratch = Box::new([0; SLOT_BYTES]);
let mut catalogs: [Option<Catalog>; 2] = [None, None];
let mut lost_map = false;
for i in 0..2 {
if let Some(m) = &maps[i] {
match Self::validate_map(io.as_mut(), m, scratch.as_mut()) {
Ok(c) => catalogs[i] = Some(c),
Err(Error::Corrupt) => {
maps[i] = None;
lost_map = true
}
Err(e) => return Err(e),
}
}
}
let active = match (&maps[0], &maps[1]) {
(Some(a), Some(b)) => usize::from(b.sequence > a.sequence),
(Some(_), None) => 0,
(None, Some(_)) => 1,
_ => return Err(Error::Corrupt),
};
let m = maps[active].as_ref().unwrap();
let recovered = m.sequence < highest || lost_map || unknown_metadata;
let write_blocked =
unknown_metadata || known.iter().zip(m.quarantine.iter()).any(|(&a, &b)| a && !b);
let degraded = identities.iter().any(Option::is_none)
|| maps.iter().any(Option::is_none)
|| known.iter().any(|v| *v);
Ok(Self {
io,
maps,
active,
catalog: catalogs[active].take().unwrap(),
scratch,
recovered,
degraded,
uncertain: false,
attempted_publication: None,
write_blocked,
known_quarantine: known,
})
}
fn validate_map(
io: &mut dyn MemcardStorage,
m: &Map,
scratch: &mut [u8; SLOT_BYTES],
) -> Result<Catalog> {
let mut raw = vec![0; m.catalog_len as usize];
read_region(io, CATALOG_OFFSETS[m.public_copy], &mut raw)?;
if crc32c(&raw) != m.catalog_crc {
return Err(Error::Corrupt);
}
let catalog = Catalog::decode(&raw, m.icons_len as usize)?;
let assigned = catalog.validate(m.icons_len as usize)?;
for (s, &expected) in m.slots.iter().zip(&assigned) {
if s.assigned != expected {
return Err(Error::Corrupt);
}
if let Some(id) = s.block {
io.read_at(block_offset(id)?, &mut scratch[..s.used as usize])?;
if crc32c(&scratch[..s.used as usize]) != s.crc {
return Err(Error::Corrupt);
}
}
}
let mut crc = !0;
let mut at = 0usize;
while at < m.icons_len as usize {
let n = (m.icons_len as usize - at).min(SLOT_BYTES);
io.read_at(ICON_OFFSETS[m.public_copy] + at as u64, &mut scratch[..n])?;
crc = crc_extend(crc, &scratch[..n]);
at += n;
}
if crc ^ !0 != m.icons_crc {
return Err(Error::Corrupt);
}
for game in &catalog.games {
let n = game.icon.length()?;
io.read_at(ICON_OFFSETS[m.public_copy] + game.icon.offset as u64, &mut scratch[..n])?;
if crc32c(&scratch[..n]) != game.icon.crc32c {
return Err(Error::Corrupt);
}
}
Ok(catalog)
}
pub fn current(&self) -> &Map {
self.maps[self.active].as_ref().unwrap()
}
pub(super) fn known_exclusions(&self) -> [bool; BLOCK_COUNT] {
self.known_quarantine
}
pub(super) fn remember_exclusions(&mut self, known: [bool; BLOCK_COUNT]) {
for (i, bad) in known.into_iter().enumerate() {
self.known_quarantine[i] |= bad;
self.write_blocked |= bad && !self.current().quarantine[i];
}
self.degraded |= self.known_quarantine.iter().any(|&bad| bad);
}
pub fn storage_read_only(&self) -> bool {
self.io.read_only()
}
pub fn into_storage(self) -> Box<dyn MemcardStorage> {
self.io
}
pub fn read_slot(&mut self, slot: usize, target: &mut [u8]) -> Result<usize> {
let s = *self.current().slots.get(slot).ok_or(Error::InvalidRange)?;
if !s.assigned || target.len() < s.used as usize {
return Err(Error::InvalidRange);
}
if let Some(id) = s.block {
self.io.read_at(block_offset(id)?, &mut target[..s.used as usize])?;
if crc32c(&target[..s.used as usize]) != s.crc {
return Err(Error::Corrupt);
}
}
Ok(s.used as usize)
}
fn writable(&self) -> Result<()> {
if self.uncertain {
return Err(Error::Indeterminate);
}
if self.write_blocked || self.io.read_only() {
return Err(Error::ReadOnly);
}
if self.current().sequence == u64::MAX {
return Err(Error::CounterExhausted);
}
Ok(())
}
fn retire_inactive(&mut self, control: &PublicationControl) -> Result<()> {
control.check()?;
let inactive = 1 - self.active;
// Also invalidate torn/unknown pages before a previously referenced region is reused.
self.io.write_at(MAP_OFFSETS[inactive], &[0; PAGE_BYTES])?;
self.io.sync()?;
self.io.read_at(MAP_OFFSETS[inactive], &mut self.scratch[..PAGE_BYTES])?;
if self.scratch[..PAGE_BYTES].iter().any(|&v| v != 0) {
self.write_blocked = true;
return Err(Error::Corrupt);
}
self.maps[inactive] = None;
control.check()
}
fn publish(&mut self, next: Map, control: &PublicationControl) -> Result<()> {
let b = next.encode()?;
control.enter()?;
self.uncertain = true;
self.attempted_publication = Some(next.clone());
let inactive = 1 - self.active;
self.io.write_at(MAP_OFFSETS[inactive], &b)?;
self.io.sync()?;
self.io.read_at(MAP_OFFSETS[inactive], &mut self.scratch[..PAGE_BYTES])?;
if self.scratch[..PAGE_BYTES] != b {
return Err(Error::Corrupt);
}
self.maps[inactive] = Some(next);
self.active = inactive;
self.uncertain = false;
Ok(())
}
pub fn commit(
&mut self,
slot: usize,
payload: &[u8],
timestamp: u64,
control: &PublicationControl,
) -> CommitResult {
let outcome = self.commit_inner(slot, payload, timestamp, control);
CommitResult {
durable: if outcome.is_ok() {
DurableResult::Success
} else if self.uncertain {
DurableResult::Indeterminate
} else {
DurableResult::Failure
},
error: outcome.err(),
sequence: self.current().sequence,
}
}
fn commit_inner(
&mut self,
slot: usize,
payload: &[u8],
timestamp: u64,
control: &PublicationControl,
) -> Result<()> {
self.writable()?;
self.attempted_publication = None;
control.check()?;
let old =
*self.current().slots.get(slot).filter(|s| s.assigned).ok_or(Error::InvalidRange)?;
if payload.len() > SLOT_BYTES {
return Err(Error::InvalidRange);
}
let generation = old.generation.checked_add(1).ok_or(Error::CounterExhausted)?;
self.retire_inactive(control)?;
let mut next = self.current().clone();
next.sequence += 1;
let block = if payload.is_empty() {
None
} else {
let mut protected = self.known_quarantine;
for m in self.maps.iter().flatten() {
for s in &m.slots {
if let Some(b) = s.block {
protected[b as usize] = true;
}
}
}
let id =
*next.order.iter().find(|&&id| !protected[id as usize]).ok_or(Error::NoSpace)?;
control.check()?;
self.io.write_at(block_offset(id)?, payload)?;
self.io.sync()?;
control.check()?;
self.io.read_at(block_offset(id)?, &mut self.scratch[..payload.len()])?;
if self.scratch[..payload.len()] != *payload {
return Err(Error::Corrupt);
}
Some(id)
};
if let Some(id) = block {
move_last(&mut next.order, id)
}
if let Some(id) = old.block {
move_last(&mut next.order, id)
}
next.slots[slot] = Slot {
assigned: true,
block,
used: payload.len() as u32,
generation,
update_at: timestamp,
crc: crc32c(payload),
};
self.publish(next, control)
}
/// Runtime-authorized catalog mutation; userland cannot provide global ownership.
/// Existing icon data streams between copies through the single scratch buffer.
pub fn publish_catalog(
&mut self,
mut catalog: Catalog,
slots: [Slot; SLOT_COUNT],
new_icon: Option<(u32, &[u8])>,
control: &PublicationControl,
) -> Result<()> {
self.writable()?;
self.attempted_publication = None;
control.check()?;
let mut next = self.current().clone();
next.sequence += 1;
next.public_copy = 1 - next.public_copy;
next.slots = slots;
let mut offset = 0usize;
for game in &mut catalog.games {
let len = game.icon.length()?;
game.icon.offset = offset as u32;
offset = offset.checked_add(len).ok_or(Error::NoSpace)?;
}
catalog.validate(offset)?;
let raw = catalog.encode(offset)?;
let assigned = catalog.validate(offset)?;
if slots.iter().zip(assigned).any(|(s, a)| s.assigned != a) {
return Err(Error::Corrupt);
}
next.catalog_len = raw.len() as u32;
next.catalog_crc = crc32c(&raw);
next.icons_len = offset as u32;
// Reject invalid descriptors before any administrative IO.
next.encode()?;
self.retire_inactive(control)?;
let mut crc = !0;
for game in &catalog.games {
control.check()?;
let len = game.icon.length()?;
if let Some((id, bytes)) = new_icon.filter(|(id, _)| *id == game.app_id) {
let _ = id;
if bytes.len() != len || crc32c(bytes) != game.icon.crc32c {
return Err(Error::Corrupt);
}
self.scratch[..len].copy_from_slice(bytes);
} else {
let old = self
.catalog
.games
.iter()
.find(|g| g.app_id == game.app_id)
.ok_or(Error::InvalidRange)?;
if old.icon.length()? != len || old.icon.crc32c != game.icon.crc32c {
return Err(Error::Corrupt);
}
self.io.read_at(
ICON_OFFSETS[self.current().public_copy] + old.icon.offset as u64,
&mut self.scratch[..len],
)?;
if crc32c(&self.scratch[..len]) != old.icon.crc32c {
return Err(Error::Corrupt);
}
}
crc = crc_extend(crc, &self.scratch[..len]);
self.io.write_at(
ICON_OFFSETS[next.public_copy] + game.icon.offset as u64,
&self.scratch[..len],
)?;
}
next.icons_crc = crc ^ !0;
write_region(self.io.as_mut(), CATALOG_OFFSETS[next.public_copy], &raw)?;
self.io.sync()?;
Self::validate_map(self.io.as_mut(), &next, self.scratch.as_mut())?;
self.publish(next, control)?;
self.catalog = catalog;
Ok(())
}
pub fn register(
&mut self,
mut game: Game,
icon: &[u8],
control: &PublicationControl,
) -> Result<()> {
if self.catalog.games.iter().any(|g| g.app_id == game.app_id) {
return Err(Error::InvalidRange);
}
let n = game.slots.len();
if !(1..=64).contains(&n) {
return Err(Error::InvalidRange);
}
let mut slots = self.current().slots;
let free: Vec<u8> = slots
.iter()
.enumerate()
.filter(|(_, s)| !s.assigned)
.map(|(i, _)| i as u8)
.take(n)
.collect();
if free.len() != n {
return Err(Error::NoSpace);
}
game.slots = free;
for &id in &game.slots {
slots[id as usize] = Slot { assigned: true, ..Slot::default() };
}
let app_id = game.app_id;
let mut c = self.catalog.clone();
c.games.push(game);
self.publish_catalog(c, slots, Some((app_id, icon)), control)
}
pub fn remove_game(&mut self, app_id: u32, control: &PublicationControl) -> Result<()> {
let game =
self.catalog.games.iter().find(|g| g.app_id == app_id).ok_or(Error::InvalidRange)?;
let mut slots = self.current().slots;
for &id in &game.slots {
slots[id as usize] = Slot::default();
}
let mut c = self.catalog.clone();
c.games.retain(|g| g.app_id != app_id);
self.publish_catalog(c, slots, None, control)
}
pub fn grow(&mut self, app_id: u32, count: usize, control: &PublicationControl) -> Result<()> {
if !(1..=64).contains(&count) {
return Err(Error::InvalidRange);
}
let mut c = self.catalog.clone();
let g = c.games.iter_mut().find(|g| g.app_id == app_id).ok_or(Error::InvalidRange)?;
if count <= g.slots.len() {
return Ok(());
}
let need = count - g.slots.len();
let mut slots = self.current().slots;
let free: Vec<u8> = slots
.iter()
.enumerate()
.filter(|(_, s)| !s.assigned)
.map(|(i, _)| i as u8)
.take(need)
.collect();
if free.len() != need {
return Err(Error::NoSpace);
}
for &id in &free {
slots[id as usize] = Slot { assigned: true, ..Slot::default() };
}
g.slots.extend(free);
self.publish_catalog(c, slots, None, control)
}
/// Explicit host maintenance after coherent mount. Unknown exclusion history
/// can only be cleared after every reusable, non-quarantined block is tested.
pub fn revalidate(&mut self, control: &PublicationControl) -> Result<()> {
if self.uncertain {
return Err(Error::Indeterminate);
}
if self.io.read_only() {
return Err(Error::ReadOnly);
}
if self.current().sequence == u64::MAX {
return Err(Error::CounterExhausted);
}
self.write_blocked = true;
self.retire_inactive(control)?;
for block in 0..BLOCK_COUNT {
if !self.known_quarantine[block]
&& !self.current().slots.iter().any(|s| s.block == Some(block as u8))
{
self.test_free_block(block as u8, control)?;
}
}
let mut next = self.current().clone();
next.sequence += 1;
next.quarantine = self.known_quarantine;
self.publish(next, control)?;
self.write_blocked = false;
self.degraded = self.known_quarantine.iter().any(|&bad| bad);
Ok(())
}
fn test_free_block(&mut self, block: u8, control: &PublicationControl) -> Result<()> {
for pattern in [0x55, 0xaa] {
control.check()?;
self.scratch.fill(pattern);
self.io.write_at(block_offset(block)?, self.scratch.as_ref())?;
self.io.sync()?;
control.check()?;
self.io.read_at(block_offset(block)?, self.scratch.as_mut())?;
if self.scratch.iter().any(|&byte| byte != pattern) {
return Err(Error::Corrupt);
}
}
Ok(())
}
/// Reintegrating a known excluded block is a separate, explicit operation.
pub fn reintegrate(&mut self, block: u8, control: &PublicationControl) -> Result<()> {
self.writable()?;
if block as usize >= BLOCK_COUNT
|| self.current().slots.iter().any(|s| s.block == Some(block))
{
return Err(Error::InvalidRange);
}
self.retire_inactive(control)?;
self.test_free_block(block, control)?;
let mut next = self.current().clone();
next.sequence += 1;
next.quarantine[block as usize] = false;
self.publish(next, control)?;
self.known_quarantine[block as usize] = false;
self.degraded = self.known_quarantine.iter().any(|&bad| bad);
Ok(())
}
pub fn read_icon(&mut self, app_id: u32) -> Result<Vec<u8>> {
let icon = &self
.catalog
.games
.iter()
.find(|g| g.app_id == app_id)
.ok_or(Error::InvalidRange)?
.icon;
let mut bytes = vec![0; icon.length()?];
self.io
.read_at(ICON_OFFSETS[self.current().public_copy] + icon.offset as u64, &mut bytes)?;
if crc32c(&bytes) != icon.crc32c {
return Err(Error::Corrupt);
}
Ok(bytes)
}
pub fn quarantine(&mut self, block: u8, control: &PublicationControl) -> Result<()> {
if block as usize >= BLOCK_COUNT {
return Err(Error::InvalidRange);
}
self.known_quarantine[block as usize] = true;
self.degraded = true;
let result = (|| {
self.writable()?;
if self.current().slots.iter().any(|s| s.block == Some(block)) {
return Err(Error::Corrupt);
}
self.retire_inactive(control)?;
let mut next = self.current().clone();
next.sequence += 1;
next.quarantine = self.known_quarantine;
self.publish(next, control)
})();
if result.is_err() {
self.write_blocked = true;
}
result
}
}
fn move_last(order: &mut [u8; BLOCK_COUNT], id: u8) {
let pos = order.iter().position(|&b| b == id).unwrap();
order[pos..].rotate_left(1);
}
#[cfg(test)]
mod tests;
File diff suppressed because it is too large Load Diff
@@ -1,9 +1,9 @@
use super::*;
use crate::fs::{FsState, VirtualFS};
use crate::services::memcard::{MemcardService, MemcardSlotState, MemcardStatus};
use crate::services::memcard::MemcardService;
use prometeu_bytecode::{TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_TYPE, Value};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType, SlotRef};
use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::log::{LogLevel, LogSource};
@@ -495,15 +495,17 @@ impl NativeInterface for VmRuntimeHost<'_> {
Ok(())
}
Syscall::AudioPlay => {
let bank_id = expect_int(args, 0)? as u8;
let bank_id_raw = expect_int(args, 0)?;
let sample_id_raw = expect_int(args, 1)?;
let voice_id_raw = expect_int(args, 2)?;
let volume_raw = expect_int(args, 3)?;
let pan_raw = expect_int(args, 4)?;
let pitch = expect_number(args, 5, "pitch")?;
let loop_mode = match expect_int(args, 6)? {
0 => prometeu_hal::LoopMode::Off,
_ => prometeu_hal::LoopMode::On,
let loop_raw = expect_int(args, 6)?;
let loop_mode = if loop_raw == 0 {
prometeu_hal::LoopMode::Off
} else {
prometeu_hal::LoopMode::On
};
if !(0..16).contains(&voice_id_raw) {
@@ -511,18 +513,18 @@ impl NativeInterface for VmRuntimeHost<'_> {
return Ok(());
}
if platform.assets().slot_info(SlotRef::audio(bank_id as usize)).asset_id.is_none()
{
if !(0..16).contains(&bank_id_raw) {
ret.push_int(AudioOpStatus::BankInvalid as i64);
return Ok(());
}
let bank_id = bank_id_raw as u8;
if sample_id_raw < 0
|| sample_id_raw > u16::MAX as i64
|| !(0..=255).contains(&volume_raw)
|| !(0..=255).contains(&pan_raw)
|| !pitch.is_finite()
|| pitch <= 0.0
|| !(0..=1).contains(&loop_raw)
{
ret.push_int(AudioOpStatus::ArgRangeInvalid as i64);
return Ok(());
@@ -541,6 +543,38 @@ impl NativeInterface for VmRuntimeHost<'_> {
ret.push_int(status as i64);
Ok(())
}
Syscall::AudioStop
| Syscall::AudioSetVolume
| Syscall::AudioSetPan
| Syscall::AudioSetPitch => {
let voice = expect_int(args, 0)?;
// Decode all types before reporting operational validation failures.
let value = match syscall {
Syscall::AudioSetVolume | Syscall::AudioSetPan => expect_int(args, 1)?,
_ => 0,
};
let pitch = if syscall == Syscall::AudioSetPitch {
expect_number(args, 1, "pitch")?
} else {
1.0
};
let status = if !(0..16).contains(&voice) {
AudioOpStatus::VoiceInvalid
} else if !(0..=255).contains(&value) || !pitch.is_finite() || pitch <= 0.0 {
AudioOpStatus::ArgRangeInvalid
} else {
let audio = platform.audio_mut();
match syscall {
Syscall::AudioStop => audio.stop(voice as usize),
Syscall::AudioSetVolume => audio.set_volume(voice as usize, value as u8),
Syscall::AudioSetPan => audio.set_pan(voice as usize, value as u8),
Syscall::AudioSetPitch => audio.set_pitch(voice as usize, pitch),
_ => unreachable!(),
}
};
ret.push_int(status as i64);
Ok(())
}
Syscall::FsOpen => {
let path = expect_string(args, 0, "path")?;
if *self.fs_state != FsState::Mounted {
@@ -561,7 +595,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
.ok_or_else(|| VmFault::Panic("Invalid handle".into()))?
.clone();
match self.fs.read_file(&path) {
Ok(data) => ret.push_string(String::from_utf8_lossy(&data).into_owned()),
Ok(data) => ret.push_utf8_lossy(&data)?,
Err(_) => ret.push_null(),
}
Ok(())
@@ -588,8 +622,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
let path = expect_string(args, 0, "path")?;
match self.fs.list_dir(&path) {
Ok(entries) => {
let names: Vec<String> = entries.into_iter().map(|e| e.name).collect();
ret.push_string(names.join(";"));
ret.push_joined(entries.iter().map(|entry| entry.name.as_str()), ";")?;
}
Err(_) => ret.push_null(),
}
@@ -606,101 +639,24 @@ impl NativeInterface for VmRuntimeHost<'_> {
}
Ok(())
}
Syscall::MemSlotCount => {
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_int(0);
return Ok(());
}
ret.push_int(MemcardStatus::Ok as i64);
ret.push_int(self.memcard.slot_count() as i64);
Ok(())
}
Syscall::MemSlotStat => {
let slot = expect_slot_index(args, 0)?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_int(MemcardSlotState::Empty as i64);
ret.push_int(0);
ret.push_int(0);
ret.push_int(0);
return Ok(());
}
let stat = self.memcard.slot_stat(self.fs, self.current_app_id, slot);
let status = if stat.state == MemcardSlotState::Corrupt {
MemcardStatus::Corrupt
} else {
MemcardStatus::Ok
};
ret.push_int(status as i64);
ret.push_int(stat.state as i64);
ret.push_int(stat.used_bytes as i64);
ret.push_int(stat.generation as i64);
ret.push_int(stat.checksum as i64);
Ok(())
}
Syscall::MemSlotRead => {
let slot = expect_slot_index(args, 0)?;
let offset = expect_non_negative_usize(args, 1, "offset")?;
let max_bytes = expect_non_negative_usize(args, 2, "max_bytes")?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_string(String::new());
ret.push_int(0);
return Ok(());
}
let read =
self.memcard.slot_read(self.fs, self.current_app_id, slot, offset, max_bytes);
ret.push_int(read.status as i64);
ret.push_string(hex_encode(&read.bytes));
ret.push_int(read.bytes_read as i64);
Ok(())
}
Syscall::MemSlotWrite => {
let slot = expect_slot_index(args, 0)?;
let offset = expect_non_negative_usize(args, 1, "offset")?;
let payload_hex = expect_string(args, 2, "payload_hex")?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_int(0);
return Ok(());
}
let payload = hex_decode(&payload_hex)?;
Syscall::MemBootstrap
| Syscall::MemSlotCount
| Syscall::MemSlotStat
| Syscall::MemSlotRead
| Syscall::MemSlotWrite
| Syscall::MemSlotCommit
| Syscall::MemSlotClear
| Syscall::MemQuery
| Syscall::MemRelease
| Syscall::MemInfo
| Syscall::MemMetadata
| Syscall::MemPresentation
| Syscall::MemDiagnostic
| Syscall::MemPublishPresentation => {
let timestamp = platform.wall_clock().utc_unix_seconds();
let app_id = self.current_app_id;
let write = self.memcard.slot_write(self.fs, app_id, slot, offset, &payload);
ret.push_int(write.status as i64);
ret.push_int(write.bytes_written as i64);
Ok(())
}
Syscall::MemSlotCommit => {
let slot = expect_slot_index(args, 0)?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
return Ok(());
}
let status = {
let app_id = self.current_app_id;
let memcard = &mut self.memcard;
let fs = &mut self.fs;
memcard.slot_commit(fs, app_id, slot)
};
ret.push_int(status as i64);
Ok(())
}
Syscall::MemSlotClear => {
let slot = expect_slot_index(args, 0)?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
return Ok(());
}
let status = {
let app_id = self.current_app_id;
let memcard = &mut self.memcard;
let fs = &mut self.fs;
memcard.slot_clear(fs, app_id, slot)
};
ret.push_int(status as i64);
Ok(())
let game_profile = self.current_cartridge_app_mode == AppMode::Game;
self.memcard.guest(syscall, args, ret, app_id, timestamp, game_profile)
}
Syscall::LogWrite => {
self.syscall_log_write(
@@ -850,14 +806,6 @@ fn expect_number(args: &[Value], index: usize, field: &str) -> Result<f64, VmFau
}
}
fn expect_slot_index(args: &[Value], index: usize) -> Result<u8, VmFault> {
let slot = expect_int(args, index)?;
if !(0..32).contains(&slot) {
return Err(VmFault::Trap(TRAP_OOB, format!("slot index out of bounds: {}", slot)));
}
Ok(slot as u8)
}
fn expect_non_negative_usize(args: &[Value], index: usize, field: &str) -> Result<usize, VmFault> {
let val = expect_int(args, index)?;
if val < 0 {
@@ -865,42 +813,3 @@ fn expect_non_negative_usize(args: &[Value], index: usize, field: &str) -> Resul
}
Ok(val as usize)
}
fn hex_encode(bytes: &[u8]) -> String {
const HEX: &[u8; 16] = b"0123456789abcdef";
let mut out = String::with_capacity(bytes.len() * 2);
for &b in bytes {
out.push(HEX[(b >> 4) as usize] as char);
out.push(HEX[(b & 0x0f) as usize] as char);
}
out
}
fn hex_decode(s: &str) -> Result<Vec<u8>, VmFault> {
fn nibble(c: u8) -> Option<u8> {
match c {
b'0'..=b'9' => Some(c - b'0'),
b'a'..=b'f' => Some(10 + c - b'a'),
b'A'..=b'F' => Some(10 + c - b'A'),
_ => None,
}
}
let bytes = s.as_bytes();
if !bytes.len().is_multiple_of(2) {
return Err(VmFault::Trap(TRAP_TYPE, "payload_hex must have even length".to_string()));
}
let mut out = Vec::with_capacity(bytes.len() / 2);
let mut i = 0usize;
while i < bytes.len() {
let hi = nibble(bytes[i]).ok_or_else(|| {
VmFault::Trap(TRAP_TYPE, "payload_hex contains invalid hex".to_string())
})?;
let lo = nibble(bytes[i + 1]).ok_or_else(|| {
VmFault::Trap(TRAP_TYPE, "payload_hex contains invalid hex".to_string())
})?;
out.push((hi << 4) | lo);
i += 2;
}
Ok(out)
}
@@ -219,6 +219,22 @@ impl VirtualMachineRuntime {
match vm.initialize(cartridge.program.clone()) {
Ok(_) => {
if let Some(count) = cartridge.memcard_slots {
if !(1..=64).contains(&count)
|| cartridge.capabilities & prometeu_hal::syscalls::caps::MEMCARD == 0
{
return Err(CrashReport::VmPanic {
message: "Invalid memcard capability/count".into(),
pc: None,
});
}
vm.require_memcard_boot().map_err(|error| CrashReport::VmInit { error })?;
} else if cartridge.capabilities & prometeu_hal::syscalls::caps::MEMCARD != 0 {
return Err(CrashReport::VmPanic {
message: "Memcard capability requires a slot count".into(),
pc: None,
});
}
self.current_app_id = cartridge.app_id;
self.current_cartridge_title = cartridge.title.clone();
self.current_cartridge_app_version = cartridge.app_version.clone();
@@ -1,10 +1,11 @@
use super::*;
use crate::fs::{FsBackend, FsEntry, FsError, FsState, VirtualFS};
use crate::fs::{FsState, VirtualFS};
use crate::services::memcard::MemcardService;
use prometeu_bytecode::TRAP_TYPE;
use prometeu_bytecode::Value;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, ConstantPoolEntry, FunctionMeta, SyscallDecl};
use prometeu_bytecode::model::{ConstantPoolEntry, SyscallDecl};
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_drivers::TestPlatform;
use prometeu_drivers::{GlyphBankPoolInstaller, MemoryBanks, SceneBankPoolInstaller};
use prometeu_hal::AudioOpStatus;
@@ -22,55 +23,19 @@ use prometeu_hal::syscalls::caps;
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_test_support::program::{TestProgram, int64_signature};
use prometeu_vm::VmInitError;
use std::collections::HashMap;
use std::sync::Arc;
use std::sync::atomic::Ordering;
#[derive(Default)]
struct MemFsBackend {
files: HashMap<String, Vec<u8>>,
}
impl FsBackend for MemFsBackend {
fn mount(&mut self) -> Result<(), FsError> {
Ok(())
}
fn unmount(&mut self) {}
fn list_dir(&self, _path: &str) -> Result<Vec<FsEntry>, FsError> {
Ok(Vec::new())
}
fn read_file(&self, path: &str) -> Result<Vec<u8>, FsError> {
self.files.get(path).cloned().ok_or(FsError::NotFound)
}
fn write_file(&mut self, path: &str, data: &[u8]) -> Result<(), FsError> {
self.files.insert(path.to_string(), data.to_vec());
Ok(())
}
fn delete(&mut self, path: &str) -> Result<(), FsError> {
self.files.remove(path).map(|_| ()).ok_or(FsError::NotFound)
}
fn exists(&self, path: &str) -> bool {
self.files.contains_key(path)
}
fn is_healthy(&self) -> bool {
true
}
}
fn cartridge_with_program_and_mode(
program: Vec<u8>,
capabilities: u64,
app_mode: AppMode,
) -> Cartridge {
Cartridge {
memcard_slots: None,
app_id: 42,
title: "Test Cart".into(),
app_version: "1.0.0".into(),
@@ -96,13 +61,18 @@ fn serialized_single_function_module_with_consts(
const_pool: Vec<ConstantPoolEntry>,
syscalls: Vec<SyscallDecl>,
) -> Vec<u8> {
BytecodeModule {
version: 0,
TestProgram {
const_pool,
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
..Default::default()
signature: int64_signature(0, 0),
captures: vec![],
name: None,
local_slots: 0,
max_stack_slots: 256,
}],
code,
debug_info: None,
@@ -151,9 +121,7 @@ fn runtime_test_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) ->
let size = tile_size as usize;
let mut bank = GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
bank.palette_mut(palette_id).unwrap()[1] = color;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
bank.pixel_indices.fill(1);
bank
}
@@ -235,6 +203,8 @@ fn initialize_vm_succeeds_when_cartridge_capabilities_cover_hostcalls() {
assert!(res.is_ok());
assert_eq!(runtime.current_app_id, 42);
assert!(vm.is_halted());
vm.prepare_boot_call().unwrap();
assert!(!vm.is_halted());
}
@@ -681,40 +651,11 @@ fn tick_system_profile_can_use_shared_log_transport() {
}
#[test]
fn tick_returns_panic_report_distinct_from_trap() {
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
let mut vm = VirtualMachine::new(assemble("HOSTCALL 0\nHALT").expect("assemble"), vec![]);
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
let report = runtime
.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
)
.expect("panic must surface as runtime error");
match report {
CrashReport::VmPanic { message, pc } => {
assert!(message.contains("HOSTCALL 0 reached execution without loader patching"));
assert!(pc.is_some());
}
other => panic!("expected VmPanic crash report, got {:?}", other),
}
assert!(matches!(runtime.last_crash_report, Some(CrashReport::VmPanic { .. })));
fn unpatched_hostcall_is_rejected_before_tick() {
let bytes = serialized_single_function_module(assemble("HOSTCALL 0\nHALT").unwrap(), vec![]);
let mut vm = VirtualMachine::default();
assert!(vm.initialize(bytes).is_err());
assert!(vm.is_halted());
}
#[test]
@@ -1661,3 +1602,6 @@ fn tick_composer_emit_sprite_type_mismatch_surfaces_trap_not_panic() {
}
assert!(matches!(runtime.last_crash_report, Some(CrashReport::VmTrap { .. })));
}
#[path = "tests_audio.rs"]
mod audio_controls;
@@ -0,0 +1,218 @@
use super::*;
use prometeu_drivers::{AudioCommand, AudioTransport};
struct Harness {
runtime: VirtualMachineRuntime,
vm: VirtualMachine,
platform: TestPlatform,
log: LogService,
fs: VirtualFS,
fs_state: FsState,
memcard: MemcardService,
files: HashMap<u32, String>,
next: u32,
}
impl Harness {
fn new(code: &str, name: &str, args: u16) -> Self {
let mut runtime = VirtualMachineRuntime::new(None);
let mut vm = VirtualMachine::default();
let mut log = LogService::new(4096);
let program = serialized_single_function_module(
assemble(code).unwrap(),
vec![SyscallDecl {
module: "audio".into(),
name: name.into(),
version: 1,
arg_slots: args,
ret_slots: 1,
}],
);
runtime
.initialize_vm(&mut log, &mut vm, &cartridge_with_program(program, caps::AUDIO))
.unwrap();
Self {
runtime,
vm,
log,
platform: TestPlatform::new(),
fs: VirtualFS::new(),
fs_state: FsState::Unmounted,
memcard: MemcardService::new(),
files: HashMap::new(),
next: 1,
}
}
fn tick(&mut self) -> Option<CrashReport> {
self.runtime.tick(
&mut self.log,
&mut self.fs,
&mut self.fs_state,
&mut self.memcard,
&mut self.files,
&mut self.next,
&mut self.vm,
&InputSignals::default(),
&mut self.platform,
)
}
fn transport(&self) -> AudioTransport {
self.platform.local_hardware().audio.transport()
}
fn step(&mut self) -> Option<CrashReport> {
self.runtime.debug_step_instruction(
&mut self.log,
&mut self.fs,
&mut self.fs_state,
&mut self.memcard,
&mut self.files,
&mut self.next,
&mut self.vm,
&mut self.platform,
)
}
}
#[test]
fn guest_audio_status_matrix_and_type_traps() {
for (name, args, inputs, expected) in [
("stop", 1, "PUSH_I32 0", 0),
("stop", 1, "PUSH_I32 15", 0),
("stop", 1, "PUSH_I32 -1", 1),
("stop", 1, "PUSH_I32 16", 1),
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 0", 0),
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 255", 0),
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 256", 3),
("set_pan", 2, "PUSH_I32 0\nPUSH_I32 -1", 3),
("set_pan", 2, "PUSH_I32 16\nPUSH_I32 -1", 1),
("set_pan", 2, "PUSH_I32 15\nPUSH_I32 255", 0),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 1", 0),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 0", 3),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 -1", 3),
(
"play",
7,
"PUSH_I32 256\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 255\nPUSH_I32 0\nPUSH_I32 1\nPUSH_I32 0",
6,
),
] {
let mut h = Harness::new(&format!("{inputs}\nHOSTCALL 0\nFRAME_SYNC\nHALT"), name, args);
assert!(h.tick().is_none(), "{name}: {inputs}");
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(expected)], "{name}: {inputs}");
let batch = h.transport().try_take().unwrap().frame;
assert_eq!(batch.map_or(0, |v| v.len()), usize::from(expected == 0));
}
for name in ["set_volume", "set_pan", "set_pitch"] {
let mut h = Harness::new("PUSH_I32 -1\nPUSH_BOOL 1\nHOSTCALL 0\nFRAME_SYNC\nHALT", name, 2);
assert!(matches!(h.tick(), Some(CrashReport::VmTrap { .. })));
assert!(h.transport().try_take().unwrap().frame.is_none());
}
}
#[test]
fn frame_publication_backpressure_abort_and_debug_steps() {
let mut h = Harness::new(
"PUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nPUSH_I32 1\nHOSTCALL 0\nFRAME_SYNC\nHALT",
"stop",
1,
);
assert!(h.tick().is_none());
let pc = h.vm.pc();
assert!(h.tick().is_none());
assert_eq!(h.vm.pc(), pc, "pending batch stalls guest");
let batch = h.transport().try_take().unwrap().frame.unwrap();
assert!(matches!(batch[0], AudioCommand::Stop { voice_id: 0 }));
assert!(h.tick().is_none());
assert!(matches!(
h.transport().try_take().unwrap().frame.unwrap()[0],
AudioCommand::Stop { voice_id: 1 }
));
for end in ["HALT", "PUSH_BOOL 1\nHOSTCALL 0\nHALT"] {
let mut h = Harness::new(&format!("PUSH_I32 0\nHOSTCALL 0\n{end}"), "stop", 1);
let _ = h.tick();
h.platform.audio_mut().finish_frame();
assert!(h.transport().try_take().unwrap().frame.is_none(), "abort cancels admitted stop");
}
let mut h = Harness::new("PUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nHALT", "stop", 1);
assert!(h.step().is_none());
assert!(h.step().is_none());
assert!(h.transport().try_take().unwrap().frame.is_none());
// Switching from stepping to running must preserve previously staged commands.
assert!(h.tick().is_none());
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
#[test]
fn guest_quota_is_deterministic_and_resets_on_next_frame() {
let repeated = "PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\n".repeat(1024);
let mut h = Harness::new(
&format!(
"{repeated}PUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nPUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nHALT"
),
"stop",
1,
);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(7)]);
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1024);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(0)]);
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
#[test]
fn guest_play_validates_raw_bank_loop_and_preserves_both_play_forms() {
use prometeu_drivers::SoundBankPoolInstaller;
use prometeu_hal::{sample::Sample, sound_bank::SoundBank};
for (bank, loop_mode, expected) in
[(0, 0, 0), (0, 1, 0), (0, -1, 3), (0, 2, 3), (256, 0, 6), (-256, 0, 6), (16, 0, 6)]
{
let mut h = Harness::new(
&format!(
"PUSH_I32 {bank}\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 255\nPUSH_I32 127\nPUSH_I32 1\nPUSH_I32 {loop_mode}\nHOSTCALL 0\nFRAME_SYNC\nHALT"
),
"play",
7,
);
let banks = Arc::new(MemoryBanks::new());
banks.install_sound_bank(
0,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![1, 2, 3]))])),
);
h.platform = TestPlatform::new_with_memory_banks(banks);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(expected)]);
let batch = h.transport().try_take().unwrap().frame;
assert_eq!(batch.map_or(0, |v| v.len()), usize::from(expected == 0));
}
let mut h = Harness::new(
"PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 255\nPUSH_I32 127\nPUSH_I32 1\nHOSTCALL 0\nFRAME_SYNC\nHALT",
"play_sample",
5,
);
let banks = Arc::new(MemoryBanks::new());
banks.install_sound_bank(
0,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![1]))])),
);
h.platform = TestPlatform::new_with_memory_banks(banks);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(0)]);
assert!(matches!(
h.transport().try_take().unwrap().frame.unwrap()[0],
AudioCommand::Play { loop_mode: prometeu_hal::LoopMode::Off, .. }
));
}
#[test]
fn normal_entry_return_is_a_successful_implicit_audio_frame() {
let mut h = Harness::new("PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\nRET", "stop", 1);
for _ in 0..2 {
assert!(h.tick().is_none());
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
let mut h = Harness::new("PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\nRET", "stop", 1);
for _ in 0..4 {
assert!(h.step().is_none());
}
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
@@ -1,129 +1,155 @@
use super::*;
use prometeu_bytecode::registry::{LifecycleRole, NamedType, Signature, TypeId};
#[test]
fn tick_memcard_slot_roundtrip_for_game_profile() {
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
runtime.mount_fs(&mut log_service, &mut fs, &mut fs_state, Box::new(MemFsBackend::default()));
let mut vm = VirtualMachine::default();
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
let code = assemble(
"PUSH_I32 0\nPUSH_I32 0\nPUSH_CONST 0\nHOSTCALL 0\nPOP_N 2\nPUSH_I32 0\nHOSTCALL 1\nPOP_N 1\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 10\nHOSTCALL 2\nHALT",
)
.expect("assemble");
let program = serialized_single_function_module_with_consts(
fn memcard_cartridge(app_mode: AppMode, hook: &str) -> Cartridge {
let boot =
assemble("HOSTCALL 0\nPOP_N 1\nGET_GLOBAL 0\nGET_GLOBAL 1\nFRAME_SYNC\nHALT").unwrap();
let callback = assemble(hook).unwrap();
let mut code = boot.clone();
code.extend(&callback);
let program = TestProgram {
code,
vec![ConstantPoolEntry::String("6869".into())],
vec![
functions: vec![
FunctionDecl { code_len: boot.len() as u32, max_stack_slots: 16, ..Default::default() },
FunctionDecl {
lifecycle_role: LifecycleRole::MemcardBoot,
code_offset: boot.len() as u32,
code_len: callback.len() as u32,
max_stack_slots: 16,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![TypeId(1)],
},
..Default::default()
},
],
syscalls: vec![
SyscallDecl {
module: "mem".into(),
name: "slot_write".into(),
name: "bootstrap".into(),
version: 1,
arg_slots: 3,
arg_slots: 0,
ret_slots: 1,
},
SyscallDecl {
module: "mem".into(),
name: "slot_count".into(),
version: 1,
arg_slots: 1,
ret_slots: 2,
},
SyscallDecl {
module: "mem".into(),
name: "slot_commit".into(),
version: 1,
arg_slots: 1,
ret_slots: 1,
},
SyscallDecl {
module: "mem".into(),
name: "slot_read".into(),
version: 1,
arg_slots: 3,
ret_slots: 3,
arg_slots: 2,
ret_slots: 2,
},
],
);
let cartridge = Cartridge {
..Default::default()
};
Cartridge {
memcard_slots: Some(2),
app_id: 42,
title: "Memcard Game".into(),
app_version: "1.0.0".into(),
app_mode: AppMode::Game,
capabilities: caps::FS,
program,
title: "Memcard test".into(),
app_version: "1".into(),
app_mode,
capabilities: caps::MEMCARD,
program: program.serialize(),
assets: AssetsPayloadSource::empty(),
asset_table: vec![],
preload: vec![],
};
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
let report = runtime.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
);
assert!(report.is_none(), "memcard roundtrip must not crash");
assert!(vm.is_halted());
assert_eq!(
vm.operand_stack_top(3),
vec![Value::Int64(2), Value::String("6869".into()), Value::Int64(0)]
);
}
}
#[test]
fn tick_memcard_access_is_denied_for_non_game_profile() {
fn tick_memcard_boot_receives_admitted_context_and_precedes_first_frame() {
let cartridge = memcard_cartridge(
AppMode::Game,
"GET_LOCAL 0\nHOSTCALL 1\nSET_GLOBAL 0\nPOP_N 1\nGET_LOCAL 0\nPUSH_I32 0\nHOSTCALL 2\nSET_GLOBAL 1\nPOP_N 1\nPUSH_I32 0\nRET",
);
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
let mut log = LogService::new(4096);
let mut vm = VirtualMachine::default();
runtime.initialize_vm(&mut log, &mut vm, &cartridge).unwrap();
let mut memcard = MemcardService::new();
let context = memcard.session.start_memory(42, 2, 1024 * 1024).unwrap();
memcard.session.begin_boot();
memcard.session.set_presentation(context, "Test", 1, 1, 1, &[0; 560], 0).unwrap();
let mut fs = VirtualFS::new();
let mut state = FsState::Unmounted;
let mut files = HashMap::new();
let mut next = 1;
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
let code = assemble("HOSTCALL 0\nHALT").expect("assemble");
let program = serialized_single_function_module(
code,
vec![SyscallDecl {
module: "mem".into(),
name: "slot_count".into(),
version: 1,
arg_slots: 0,
ret_slots: 2,
}],
for expected in [None, Some(0)] {
assert!(
runtime
.tick(
&mut log,
&mut fs,
&mut state,
&mut memcard,
&mut files,
&mut next,
&mut vm,
&signals,
&mut platform
)
.is_none()
);
assert_eq!(vm.memcard_boot_result(), expected);
assert_eq!(runtime.logical_frame_index, 0);
}
let request = 1;
assert_eq!(
memcard.session.query(context, request).unwrap().state,
crate::memcard::session::RequestState::MemoryOnly
);
let cartridge = Cartridge {
app_id: 101,
title: "System App".into(),
app_version: "1.0.0".into(),
app_mode: AppMode::Shell,
capabilities: caps::FS,
program,
assets: AssetsPayloadSource::empty(),
asset_table: vec![],
preload: vec![],
};
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
let report = runtime.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
assert!(
runtime
.tick(
&mut log,
&mut fs,
&mut state,
&mut memcard,
&mut files,
&mut next,
&mut vm,
&signals,
&mut platform
)
.is_none()
);
assert!(report.is_none(), "non-game memcard call must return status");
assert!(vm.is_halted());
assert_eq!(vm.operand_stack_top(2), vec![Value::Int64(0), Value::Int64(4)]);
assert_eq!(runtime.logical_frame_index, 1);
assert_eq!(vm.operand_stack_top(2), vec![Value::Int64(1), Value::Int64(2)]);
assert!(vm.begin_memcard_boot(context as i64).is_err());
}
#[test]
fn tick_memcard_boot_is_denied_for_non_game_profile() {
let cartridge = memcard_cartridge(
AppMode::Shell,
"GET_LOCAL 0\nHOSTCALL 1\nPOP_N 2\nGET_LOCAL 0\nPUSH_I32 0\nHOSTCALL 2\nPOP_N 2\nPUSH_I32 0\nRET",
);
let mut runtime = VirtualMachineRuntime::new(None);
let mut log = LogService::new(4096);
let mut vm = VirtualMachine::default();
runtime.initialize_vm(&mut log, &mut vm, &cartridge).unwrap();
let mut memcard = MemcardService::new();
memcard.session.start_memory(42, 2, 1024 * 1024).unwrap();
memcard.session.begin_boot();
let report = runtime.tick(
&mut log,
&mut VirtualFS::new(),
&mut FsState::Unmounted,
&mut memcard,
&mut HashMap::new(),
&mut 1,
&mut vm,
&InputSignals::default(),
&mut TestPlatform::new(),
);
assert!(matches!(report, Some(CrashReport::VmTrap { .. })));
assert_eq!(vm.memcard_boot_result(), None);
}
@@ -70,38 +70,103 @@ impl VirtualMachineRuntime {
(glyph, sounds, scenes)
}
#[allow(clippy::too_many_arguments)]
pub fn debug_step_instruction(
&mut self,
log_service: &mut LogService,
fs: &mut VirtualFS,
fs_state: &mut FsState,
memcard: &mut MemcardService,
open_files: &mut HashMap<u32, String>,
next_handle: &mut u32,
vm: &mut VirtualMachine,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if vm.call_stack_is_empty() {
vm.prepare_boot_call();
if !platform.audio().ready() {
return None;
}
if vm.memcard_boot_result() == Some(0) && memcard.session.boot_pending() {
return None;
}
let was_memcard_boot = vm.memcard_boot_active();
if was_memcard_boot {
platform.audio_mut().begin_lifecycle();
}
if vm.call_stack_is_empty()
&& let Err(error) = vm.prepare_boot_call()
{
let report = CrashReport::VmInit { error };
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
let step_result = {
let mut ctx = HostContext::new_platform(Some(platform));
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files = HashMap::new();
let mut next_handle = 1;
let mut host = VmRuntimeHost {
runtime: self,
log_service,
fs: &mut fs,
fs_state: &mut fs_state,
memcard: &mut memcard,
open_files: &mut open_files,
next_handle: &mut next_handle,
fs,
fs_state,
memcard,
open_files,
next_handle,
};
vm.step(&mut host, &mut ctx)
};
// run_budget derives these terminal reasons after executing an instruction;
// single stepping must observe the same publication/cancellation boundary.
let step_result = if step_result.is_ok() && vm.is_halted() {
Err(LogicalFrameEndingReason::Halted)
} else if step_result.is_ok() && !was_memcard_boot && vm.call_stack_is_empty() {
Err(LogicalFrameEndingReason::EndOfRom)
} else {
step_result
};
if was_memcard_boot
&& step_result == Err(LogicalFrameEndingReason::LifecycleComplete)
&& let Err(error) = memcard.session.finish_boot(
vm.memcard_boot_result() == Some(0),
&memcard.lane,
Instant::now(),
)
{
let report = CrashReport::VmPanic {
message: format!("Memcard bootstrap failed: {error:?}: {}", memcard.diagnostic),
pc: Some(vm.pc() as u32),
};
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
if was_memcard_boot {
match &step_result {
Err(LogicalFrameEndingReason::LifecycleComplete) => {
platform.audio_mut().finish_lifecycle(true)
}
Err(
LogicalFrameEndingReason::Trap(_)
| LogicalFrameEndingReason::Panic(_)
| LogicalFrameEndingReason::Halted,
) => platform.audio_mut().finish_lifecycle(false),
_ => {}
}
}
match &step_result {
Err(LogicalFrameEndingReason::FrameSync | LogicalFrameEndingReason::EndOfRom) => {
platform.audio_mut().finish_frame()
}
Err(LogicalFrameEndingReason::Halted) => platform.audio_mut().reset(),
Err(LogicalFrameEndingReason::Trap(_) | LogicalFrameEndingReason::Panic(_)) => {
platform.audio_mut().abort_frame()
}
_ => {}
}
match step_result {
Ok(())
| Err(
LogicalFrameEndingReason::FrameSync
LogicalFrameEndingReason::LifecycleComplete
| LogicalFrameEndingReason::FrameSync
| LogicalFrameEndingReason::BudgetExhausted
| LogicalFrameEndingReason::Halted
| LogicalFrameEndingReason::EndOfRom
@@ -116,6 +181,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
format!("PVM Fault during Step: {}", report),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
Some(report)
}
@@ -128,12 +194,76 @@ impl VirtualMachineRuntime {
report.log_tag(),
format!("PVM Fault during Step: {}", report),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
Some(report)
}
}
}
/// Uses the session's real services, outside logical-frame accounting.
#[allow(clippy::too_many_arguments)]
pub(crate) fn tick_lifecycle(
&mut self,
log_service: &mut LogService,
fs: &mut VirtualFS,
fs_state: &mut FsState,
memcard: &mut MemcardService,
open_files: &mut HashMap<u32, String>,
next_handle: &mut u32,
vm: &mut VirtualMachine,
platform: &mut dyn RuntimePlatform,
single_step: bool,
) -> LogicalFrameEndingReason {
if self.paused && !single_step && !self.debug_step_request {
return LogicalFrameEndingReason::Breakpoint;
}
if !platform.audio().lifecycle_ready() {
return LogicalFrameEndingReason::BudgetExhausted;
}
platform.audio_mut().begin_lifecycle();
let result = catch_unwind(AssertUnwindSafe(|| {
let mut ctx = HostContext::new_platform(Some(platform));
let mut host = VmRuntimeHost {
runtime: self,
log_service,
fs,
fs_state,
memcard,
open_files,
next_handle,
};
if single_step {
vm.step(&mut host, &mut ctx)
.err()
.unwrap_or(LogicalFrameEndingReason::BudgetExhausted)
} else {
vm.run_budget(VirtualMachine::LIFECYCLE_SLICE, &mut host, &mut ctx)
.map(|report| report.reason)
.unwrap_or_else(LogicalFrameEndingReason::Panic)
}
}));
let reason = result.unwrap_or_else(|payload| {
LogicalFrameEndingReason::Panic(Self::host_panic_payload_to_string(payload))
});
match &reason {
LogicalFrameEndingReason::LifecycleComplete => {
platform.audio_mut().finish_lifecycle(true)
}
LogicalFrameEndingReason::BudgetExhausted | LogicalFrameEndingReason::Breakpoint => {}
_ => {
platform.audio_mut().finish_lifecycle(false);
platform.audio_mut().abort_frame();
}
}
if reason == LogicalFrameEndingReason::Breakpoint || single_step || self.debug_step_request
{
self.paused = true;
self.debug_step_request = false;
}
reason
}
#[allow(clippy::too_many_arguments)]
pub fn tick(
&mut self,
@@ -147,6 +277,56 @@ impl VirtualMachineRuntime {
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if vm.memcard_boot_active() {
let reason = self.tick_lifecycle(
log_service,
fs,
fs_state,
mem_card,
open_files,
next_handle,
vm,
platform,
false,
);
let failure = match reason {
LogicalFrameEndingReason::LifecycleComplete => {
let ready = vm.memcard_boot_result() == Some(0);
mem_card.session.finish_boot(ready, &mem_card.lane, Instant::now()).err().map(
|error| CrashReport::VmPanic {
message: format!(
"Memcard bootstrap failed: {error:?}: {}",
mem_card.diagnostic
),
pc: Some(vm.pc() as u32),
},
)
}
LogicalFrameEndingReason::BudgetExhausted
| LogicalFrameEndingReason::Breakpoint => None,
LogicalFrameEndingReason::Trap(trap) => Some(CrashReport::VmTrap { trap }),
other => Some(CrashReport::VmPanic {
message: format!("Memcard bootstrap stopped: {other:?}"),
pc: Some(vm.pc() as u32),
}),
};
if let Some(report) = &failure {
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
}
return failure;
}
if vm.memcard_boot_result() == Some(0) {
if let Some(error) = mem_card.session.boot_error() {
return Some(CrashReport::VmPanic {
message: format!("Memcard registration failed: {error:?}"),
pc: Some(vm.pc() as u32),
});
}
if mem_card.session.boot_pending() {
return None;
}
}
let start = Instant::now();
self.tick_index += 1;
@@ -154,6 +334,9 @@ impl VirtualMachineRuntime {
return None;
}
if !platform.audio().ready() {
return None;
}
self.update_fs(log_service, fs, fs_state);
if !self.logical_frame_active {
if RenderManager::policy_for_app_mode(self.current_cartridge_app_mode)
@@ -168,7 +351,12 @@ impl VirtualMachineRuntime {
self.begin_logical_frame(signals, platform);
if self.needs_prepare_entry_call || vm.call_stack_is_empty() {
vm.prepare_boot_call();
if let Err(error) = vm.prepare_boot_call() {
let report = CrashReport::VmInit { error };
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
self.needs_prepare_entry_call = false;
}
@@ -214,6 +402,9 @@ impl VirtualMachineRuntime {
self.atomic_telemetry.cycles_used.fetch_add(run.cycles_used, Ordering::Relaxed);
self.atomic_telemetry.vm_steps.fetch_add(run.steps_executed, Ordering::Relaxed);
if run.reason == LogicalFrameEndingReason::Halted {
platform.audio_mut().reset();
}
if run.reason == LogicalFrameEndingReason::Breakpoint {
self.paused = true;
self.debug_step_request = false;
@@ -236,6 +427,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
report.summary(),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -249,6 +441,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
report.summary(),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -373,6 +566,8 @@ impl VirtualMachineRuntime {
log_service.reset_count();
// Entry return is the runtime's successful implicit frame end.
platform.audio_mut().finish_frame();
self.logical_frame_index += 1;
self.logical_frame_active = false;
self.logical_frame_remaining_cycles = 0;
@@ -382,9 +577,8 @@ impl VirtualMachineRuntime {
self.frame_scheduler.complete_game_frame();
}
if run.reason == LogicalFrameEndingReason::FrameSync {
self.needs_prepare_entry_call = true;
}
self.needs_prepare_entry_call =
run.reason == LogicalFrameEndingReason::EndOfRom;
if self.debug_step_request {
self.paused = true;
@@ -406,6 +600,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
report.summary(),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -456,7 +651,7 @@ impl VirtualMachineRuntime {
platform: &mut dyn RuntimePlatform,
) {
platform.game2d_frame_composer().begin_frame();
platform.audio_mut().clear_commands();
platform.audio_mut().begin_frame();
self.logs_written_this_frame.clear();
}
}
@@ -20,7 +20,27 @@ pub enum VmSessionError {
ProcessIsNotVmBacked(ProcessId),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum LifecycleTransition {
PauseToHub,
PauseToShell(TaskId),
Resume,
}
impl LifecycleTransition {
pub(crate) fn role(self) -> prometeu_bytecode::registry::LifecycleRole {
use prometeu_bytecode::registry::LifecycleRole;
match self {
Self::Resume => LifecycleRole::BeforeResume,
_ => LifecycleRole::BeforePause,
}
}
}
pub struct VmSession {
pub(crate) lifecycle_transition: Option<LifecycleTransition>,
pub(crate) lifecycle_started: bool,
pub(crate) pause_hook_complete: bool,
pub id: VmSessionId,
pub task_id: TaskId,
pub process_id: ProcessId,
@@ -45,6 +65,9 @@ impl VmSession {
logs_count: Arc<AtomicU32>,
) -> Self {
Self {
lifecycle_transition: None,
lifecycle_started: false,
pause_hook_complete: false,
id: VmSessionId(task.id),
task_id: task.id,
process_id: process.id,
+12
View File
@@ -4,9 +4,21 @@ version = "0.1.0"
edition = "2024"
license.workspace = true
[features]
resource-diagnostics = []
[[example]]
name = "resource_qualification"
required-features = ["resource-diagnostics"]
[dependencies]
prometeu-bytecode = { path = "../prometeu-bytecode" }
prometeu-hal = { path = "../prometeu-hal" }
fpmath = { version = "=0.1.1", features = ["soft-float"] }
[dev-dependencies]
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
[[example]]
name = "string_provenance_benchmark"
required-features = ["resource-diagnostics"]
@@ -0,0 +1,7 @@
fn main() {
if std::env::args().nth(1).as_deref() == Some("constants") {
print!("{}", prometeu_vm::builtin_constant_catalog_csv());
} else {
print!("{}", prometeu_vm::intrinsic_catalog_csv());
}
}
@@ -0,0 +1,49 @@
//! Local host timing only; these measurements never define guest cycles.
use prometeu_bytecode::Value;
use prometeu_vm::{HostContext, lookup_intrinsic_by_id};
use std::hint::black_box;
use std::time::Instant;
fn main() {
let iterations: u32 =
std::env::args().nth(1).unwrap_or_else(|| "20000".into()).parse().unwrap();
for (id, args) in [
(0x3010, vec![Value::Float(2.)]),
(0x3011, vec![Value::Float(f64::from_bits(0x6974e718d7d7625a))]),
(0x3012, vec![Value::Float(f64::from_bits(0x7fefffffffffffff))]),
(0x3013, vec![Value::Float(1.), Value::Float(3.)]),
(0x1000, vec![Value::Float(1.), Value::Float(2.), Value::Float(3.), Value::Float(4.)]),
(0x1001, vec![Value::Float(1e200), Value::Float(1e200)]),
] {
let m = lookup_intrinsic_by_id(id).unwrap();
let mut ctx = HostContext::new(None);
for _ in 0..100 {
black_box(
(m.implementation.host_callback().expect("host intrinsic"))(
black_box(&args),
&mut ctx,
)
.unwrap(),
);
}
let start = Instant::now();
for _ in 0..iterations {
black_box(
(m.implementation.host_callback().expect("host intrinsic"))(
black_box(&args),
&mut ctx,
)
.unwrap(),
);
}
let elapsed = start.elapsed().as_nanos();
println!(
"{}.{} iterations={} total_ns={} ns_per_call={:.2} virtual_cycles={}",
m.owner,
m.name,
iterations,
elapsed,
elapsed as f64 / f64::from(iterations),
m.cost_cycles
);
}
}

Some files were not shown because too many files have changed in this diff Show More