78 Commits
Author SHA1 Message Date
bquarkz c2bf8d055c feat(stress): add a deterministic particle demo with sequenced music
Move Storm Eagle playback and source assets to Stress Console and keep Dummy Boy silent. Exercise VM math, seeded Random and persistent typed particles with a projected tunnel, bounded 512-sprite heavy workload, reproducible replays and measured costs.
2026-11-20 22:15:47 +00:00
bquarkz 8510c5b00d feat(audio): add 32-voice PCM mixing and native music sequencing
Add self-contained SoundBanks and MusicBanks with per-sample PCM16 and IMA ADPCM storage, materialized to resident PCM16. Integrate instrument envelopes, automation, shared DSP and host lifecycle controls while preserving staged real-time execution.
2026-11-20 22:15:24 +00:00
bquarkz a32f834b2b feat(graphics): migrate native target to 640x360
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Centralize the fixed 640x360 RGBA8888/60 Hz contract in the existing HAL.
Preserve 8/16/32 tiles and composition, cover partial edges and mixed-size
camera movement, and adapt firmware, fixtures, hosts and native tests.

Share nearest-neighbor presentation geometry with pointer input. Measure
actual framebuffer publications and successful host presentations separately
from VM ticks, with bounded opt-in diagnostics and release harnesses.

Validated with the complete tooling verify gate, native rendering tests,
GPU readback, headless/process integration, formatting and strict clippy.
The existing synchronous session path is documented; no worker/session
architecture replacement or format compatibility layer is introduced.

Work: WRK-0016 / DEC-0001 / PLN-0001
Commit and push explicitly authorized by the user after completion.
2026-11-20 10:34:45 +00:00
bquarkz f1adf86dd5 feat(runtime): support Studio Play and separate integration gates
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Add the windowless Studio host with authenticated binary control/frame channels,
managed input, pause/resume/stop, frame ownership and save-aware shutdown.
Preserve deterministic headless execution and add protocol/process fixtures.
Separate unit CI and coverage from opt-in integration/socket qualification,
retaining the prior combined coverage floors in the configuration history.

Validation: tooling make verify passed runtime ci-domains and integration.
2026-11-19 17:32:02 +00:00
bquarkz 2d5735cb13 chore: retire Discussion Framework workflow and retain lessons
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-11-16 16:45:34 +00:00
bquarkz dccf4d0775 fix(ci): declare llvm-tools-preview in pinned toolchain
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-11-16 10:00:49 +00:00
bquarkz c3589be1ad fix(headless): wait for memcard bootstrap IO progress
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
Coordinate bounded native publication progress during frame advance while preserving watchdogs, guest budgets and resource ownership. Add controlled and packaged reopen regressions, clarify the runtime specs, and retain qualification evidence.
2026-11-10 23:26:40 +00:00
bquarkz 49d7fca0b7 chore(toolchain): pin Rust to 1.98.1
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
2026-11-10 22:39:19 +00:00
bquarkz c649e02816 feat(headless): expose negotiated native log observation 2026-11-10 21:57:34 +00:00
bquarkz 09d8778f04 fix(runtime): support older stable Rust atomic updates
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-11-05 09:00:19 +00:00
bquarkz 1aa939eca8 fix(runtime): replace deprecated atomic fetch_update calls
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
2026-11-03 00:01:58 +00:00
bquarkz a4bec5bc45 feat(host): expose memcard controls and qualify process persistence
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-10-30 10:10:07 +00:00
bquarkz dcf6561ea7 refactor(vm)!: remove publication and logical guard opcodes
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Remove INDEX_GUARD, ARRAY_CHECK_LENGTH, STORAGE_PUBLISH and FIELDS_PUBLISH
from decoding, metadata, tooling, verification and execution. Keep ARRAY_LEN
and overlap-safe ARRAY_COPY with complete-group ownership and early charging
of calculable copy work, including refused attempts.

Update specifications, producer handoff, qualification evidence and lessons.
Share collection test support and remove redundant Copy clones for Clippy.

Validation: make ci-domains passed with 1,095 workspace tests, five separately
executed debugger socket tests and all 15 unchanged coverage domain gates.
VM release, resource diagnostics and layer/quality suites also passed.

BREAKING CHANGE: PBX using opcodes 0xA7, 0xA8, 0xAA or 0xAB is rejected,
including unreachable instructions. Consumers must adapt their emission and
collection algorithms or operational guarantees.
2026-10-23 23:37:56 +01:00
bquarkz 69ad1931de feat(vm): add reference identity and deterministic value hashing 2026-10-23 14:29:00 +01:00
Nilton Constantino 57992cf214 feat(vm): publish typed fields across multiple structs atomically
Add schema-driven FIELDS_PUBLISH without collection-specific runtime behavior. Validate every nullable destination and complete field group before allocation-free publication, with neutral ownership, malformed-input and quota coverage.
2026-10-23 09:53:40 +01:00
bquarkz d9b9eeb171 Add generic logical guards and atomic storage publication 2026-10-22 22:24:28 +01:00
bquarkz f7d7c16753 docs: include Random in registry handoff builtin list
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-10-14 15:04:07 +01:00
bquarkz 07b69314b1 Merge pull request 'Dev/runtime improvements for games' (#42) from dev/runtime-improvements-for-games into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #42
2026-10-14 13:58:56 +00:00
bquarkz 4669ced98e fix(ci): accept installed llvm-tools component name
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-10-14 14:43:09 +01:00
bquarkz a2275932a5 Keep PBX at v0 and simplify Jenkins quality gate
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
2026-10-14 14:35:44 +01:00
bquarkz 39468740c3 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:24:14 +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
bquarkz 89101d1b20 harden deterministic headless runtime control
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-09-23 07:09:46 +01:00
bquarkz 2516fae4fc Merge pull request 'add headless automation' (#39) from dev/headless-automation-host-and-deterministic-runtime-control into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #39
2026-09-22 12:59:28 +00:00
bquarkz e0c08c8b00 add headless automation
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-09-22 13:28:31 +01:00
bquarkz 5b106af0f3 Merge pull request 'multi-frontend-pvm-neutrality' (#38) from dev/multi-frontend-pvm-neutrality into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #38
2026-09-18 23:35:26 +00:00
bquarkz 6ef376763c multi-frontend-pvm-neutrality
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-09-18 23:16:26 +01:00
bquarkz f50a3f127f regenerate PBX test cartridges
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-07-15 08:04:29 +01:00
bquarkz f0f3f972ce fix PBX executable format identity 2026-07-15 08:01:47 +01:00
bquarkz b2d2533acb Fix PBX problems 2026-07-15 07:55:52 +01:00
bquarkz 4b499288e2 Portable Host Backend Strategy
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-07-14 16:39:46 +01:00
bquarkz aa3b31deb5 Merge pull request 'dev/runtime-owned-variable-glyph-bank-palette-protocol' (#37) from dev/runtime-owned-variable-glyph-bank-palette-protocol into master
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Reviewed-on: #37
2026-07-14 15:25:05 +00:00
bquarkz f784ccd774 Runtime-Owned Variable Glyph Bank Palette Protocol
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
2026-07-14 16:16:05 +01:00
458 changed files with 97534 additions and 10083 deletions
+19 -9
View File
@@ -13,17 +13,27 @@ jobs:
with: with:
submodules: recursive submodules: recursive
- uses: dtolnay/rust-toolchain@stable - name: Install repository Rust toolchain
with: run: |
components: rustfmt, clippy toolchain=$(python3 -c 'import tomllib; print(tomllib.load(open("rust-toolchain.toml", "rb"))["toolchain"]["channel"])')
rustup toolchain install "$toolchain" --profile minimal
- uses: Swatinem/rust-cache@v2 - uses: Swatinem/rust-cache@v2
- name: Format check - name: Discard reports from previous runs
run: cargo fmt -- --check run: rm -rf target/llvm-cov
- name: Clippy - name: Provision quality-gate tools and native dependencies
run: cargo clippy --workspace --all-features run: bash scripts/provision-quality-gate.sh
- name: Test - name: Repository quality gate
run: cargo test --workspace --all-targets --all-features --no-fail-fast 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/llvm-cov/**
if-no-files-found: warn
Generated
+1163 -348
View File
File diff suppressed because it is too large Load Diff
+1
View File
@@ -7,6 +7,7 @@ members = [
"crates/console/prometeu-system", "crates/console/prometeu-system",
"crates/console/prometeu-vm", "crates/console/prometeu-vm",
"crates/host/prometeu-host-desktop-winit", "crates/host/prometeu-host-desktop-winit",
"crates/host/prometeu-host-headless",
"crates/tools/prometeu-cli", "crates/tools/prometeu-cli",
"crates/tools/pbxgen-dummy-boy", "crates/tools/pbxgen-dummy-boy",
"crates/tools/pbxgen-stress", "crates/tools/pbxgen-stress",
+27 -11
View File
@@ -1,25 +1,32 @@
.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-unit test-local test-integration 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 cobertura
fmt: fmt:
cargo fmt cargo fmt --all
fmt-check: fmt-check:
cargo fmt -- --check cargo fmt --all -- --check
clippy: clippy:
cargo clippy --workspace --all-features cargo clippy --workspace --all-targets --all-features -- -D warnings
test-local: test-unit:
cargo test --workspace --all-targets --all-features --no-fail-fast cargo test --workspace --lib --bins --all-features --no-fail-fast
# Compatibility entry point: repository-local verification is unit-only.
test-local: test-unit
# Explicit opt-in, orchestrated by ../tooling; test sources stay in this repository.
test-integration:
cargo test --workspace --tests --all-features --no-fail-fast
test-debugger-socket: test-debugger-socket:
cargo test -p prometeu-host-desktop-winit --lib -- --ignored cargo test -p prometeu-host-desktop-winit --lib runner::tests -- --ignored
clean: clean:
cargo llvm-cov clean --workspace cargo llvm-cov clean --workspace
coverage: coverage:
cargo llvm-cov --workspace --all-features --html --output-dir target/llvm-cov cargo llvm-cov --workspace --lib --bins --all-features --html --output-dir target/llvm-cov
coverage-report-json: coverage-report-json:
cargo llvm-cov report --json --output-path target/llvm-cov/report.json cargo llvm-cov report --json --output-path target/llvm-cov/report.json
@@ -33,6 +40,9 @@ coverage-json:
coverage-domain-list: coverage-domain-list:
./scripts/coverage-domain-evidence.sh --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: coverage-domain-evidence:
@if [ -z "$(DOMAIN)" ]; then \ @if [ -z "$(DOMAIN)" ]; then \
echo "usage: make coverage-domain-evidence DOMAIN=<domain>"; \ echo "usage: make coverage-domain-evidence DOMAIN=<domain>"; \
@@ -43,7 +53,13 @@ coverage-domain-evidence:
coverage-domain-gate: coverage-domain-gate:
./scripts/coverage-domain-evidence.sh --check-all ./scripts/coverage-domain-evidence.sh --check-all
test: fmt-check clippy test-local test-debugger-socket test: fmt-check clippy test-unit
ci: clean fmt-check clippy coverage coverage-report-json # Local and GitHub entry point; Jenkins exposes the same targets as stages.
ci-domains: clean fmt-check clippy coverage coverage-report-json coverage-xml coverage-json coverage-domain-gate CI_DOMAIN_STEPS = clean fmt-check clippy test-unit coverage coverage-report-json coverage-xml coverage-json coverage-domain-audit coverage-domain-gate
ci: ci-domains
ci-domains:
rm -rf target/llvm-cov
+@set -e; for step in $(CI_DOMAIN_STEPS); do $(MAKE) --no-print-directory -j1 $$step; done
cobertura: coverage-xml coverage-json cobertura: coverage-xml coverage-json
+41 -24
View File
@@ -1,14 +1,14 @@
# PROMETEU Runtime # PROMETEU Runtime
PROMETEU is an educational and experimental fantasy handheld / fantasy console. PROMETEU is an educational and experimental fantasy handheld / fantasy console.
This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, firmware/system services, host integration, CLI entrypoints, development utilities, specs, and discussion artifacts. This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, firmware/system services, host integration, CLI entrypoints, development utilities, specs, and engineering lessons.
The VM is only one subsystem of the machine. The canonical docs in this repository intentionally distinguish: The VM is only one subsystem of the machine. The canonical docs in this repository intentionally distinguish:
- machine-level specs; - machine-level specs;
- VM/runtime internal architecture; - VM/runtime internal architecture;
- implementation crates; - implementation crates;
- discussion workflow and lessons learned. - engineering lessons learned.
## What This Repository Contains ## What This Repository Contains
@@ -19,7 +19,7 @@ The VM is only one subsystem of the machine. The canonical docs in this reposito
- `docs/specs/runtime/`: canonical PROMETEU machine specs - `docs/specs/runtime/`: canonical PROMETEU machine specs
- `docs/vm-arch/`: canonical VM/runtime architecture and ISA references - `docs/vm-arch/`: canonical VM/runtime architecture and ISA references
- `devtools/`: debugger protocol material - `devtools/`: debugger protocol material
- `discussion/`: agendas, decisions, plans, and lessons for architectural work - `discussion/lessons/`: published engineering lessons and supporting assets
- `test-cartridges/`: cartridge fixtures used for validation and manual runs - `test-cartridges/`: cartridge fixtures used for validation and manual runs
## Canonical Documentation ## Canonical Documentation
@@ -29,7 +29,11 @@ Use these entrypoints instead of inferring the model from isolated source files:
- [Machine specs](docs/specs/runtime/README.md): authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI - [Machine specs](docs/specs/runtime/README.md): authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI
- [VM architecture](docs/vm-arch/ARCHITECTURE.md): authoritative internal architecture for VM/runtime invariants - [VM architecture](docs/vm-arch/ARCHITECTURE.md): authoritative internal architecture for VM/runtime invariants
- [ISA reference](docs/vm-arch/ISA_CORE.md): bytecode-level instruction set authority - [ISA reference](docs/vm-arch/ISA_CORE.md): bytecode-level instruction set authority
- [Discussion workflow](discussion/index.ndjson): architectural agenda, decision, and execution traceability - [Engineering lessons](discussion/lessons/): published results and rationale
Engineering discussions, decisions, plans and execution evidence are maintained in
the enclosing [Prometeu Engineering workspace](../README.md) using
[AI Engineering](../.ai-engineering/README.md).
## Workspace Layout ## Workspace Layout
@@ -60,11 +64,21 @@ Other ecosystem commands, such as build, pack, and verification tooling, are not
## Requirements ## Requirements
- Rust toolchain from [rust-toolchain.toml](rust-toolchain.toml) - Rust **1.98.1**, pinned in [rust-toolchain.toml](rust-toolchain.toml)
- `rustup` for toolchain installation and management - `rustup` for toolchain installation and management
- `cargo-llvm-cov` for coverage targets such as `make coverage` and `make ci-domains` - `cargo-llvm-cov` for coverage targets such as `make coverage` and `make ci-domains`
- a local graphical environment for desktop runtime commands - a local graphical environment for desktop runtime commands
From the repository root, install and verify the pinned toolchain:
```bash
rustup toolchain install 1.98.1 --profile minimal --component rustfmt,clippy
rustc --version
```
Rustup selects the pinned version automatically for commands run in this repository.
CI installs the toolchain from the same file.
## Quick Start ## Quick Start
Build the workspace: Build the workspace:
@@ -107,19 +121,26 @@ Format, lint, and test the workspace:
make test make test
``` ```
Run the CI-oriented non-domain gate: Run the shared strict CI gate (`make ci` is an alias):
```bash ```bash
make ci make ci
``` ```
Run the CI-oriented domain coverage gate: The authoritative target used by both GitHub and Jenkins is:
```bash ```bash
make ci-domains 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. `make test-unit` selects library and binary unit-test harnesses with
`--lib --bins --all-features`; `test-local` remains an alias. Both `make test`
and `make ci-domains` run only this suite. Integration targets under `tests/`,
installed-process qualification and the five ignored debugger socket tests are
excluded from the pipeline. They remain available explicitly through
`make test-integration` and `make test-debugger-socket`, orchestrated by
`../tooling`. Tests and fixtures stay in this repository. Physical audio and manual probes remain opt-in. See
[quality-gate prerequisites and commands](docs/vm-arch/COVERAGE_DOMAINS.md#commands-and-ci).
## Coverage Governance ## Coverage Governance
@@ -128,19 +149,14 @@ The repository uses a two-layer runtime-edge coverage model:
- a mandatory CI gate based on canonical runtime-edge domains; - a mandatory CI gate based on canonical runtime-edge domains;
- domain-oriented review evidence for the canonical runtime-edge domains. - domain-oriented review evidence for the canonical runtime-edge domains.
Current canonical domains: The fifteen canonical domains and fixed floors are defined in
[the repository configuration](files/config/runtime-edge-coverage-domains.json).
- `system/runtime` Use `make coverage-domain-list` or the [ownership documentation](docs/vm-arch/COVERAGE_DOMAINS.md)
- `fs` to inspect the current map.
- `asset/bank`
- `firmware`
- `host-dependent`
Global coverage artifacts: Global coverage artifacts:
```bash ```bash
make ci
make cobertura
make ci-domains make ci-domains
``` ```
@@ -157,14 +173,15 @@ Domain-oriented evidence helpers:
make coverage-domain-list make coverage-domain-list
make coverage-domain-evidence DOMAIN=firmware make coverage-domain-evidence DOMAIN=firmware
make coverage-domain-evidence DOMAIN=host-dependent make coverage-domain-evidence DOMAIN=host-dependent
make coverage-domain-evidence DOMAIN=host/headless
``` ```
Per-domain baselines currently start around `60`. `make ci-domains` runs formatting, strict workspace/all-target/all-feature Clippy,
That does not waive test obligations. It means the project is adopting explicit domain evidence immediately while tightening quantitative expectations incrementally over time. library/binary unit tests, fresh unit-only coverage and every domain
ownership/evidence gate. Both CI providers archive available evidence on failure.
`make ci-domains` is the CI entrypoint used by Jenkins. A failing run never lowers a configured floor; local and CI checks use the same
It runs the standard coverage pipeline, produces the HTML/XML/JSON artifacts, and fails when any canonical domain falls below its configured `baseline_percent`. repository-owned commands. Reports identify their revision, source/configuration
The CI gate currently compares domain `lines` coverage against each domain baseline. and actual execution platform.
When a PR changes the observable contract of a canonical domain, it is expected to: When a PR changes the observable contract of a canonical domain, it is expected to:
@@ -177,7 +194,7 @@ Improving the global percentage alone is not sufficient review evidence when the
The project is still in active architectural and implementation convergence. The project is still in active architectural and implementation convergence.
- the machine contract is being clarified through the specs and discussion workflow; - the machine contract is being clarified through the specs and AI Engineering;
- the workspace already contains concrete runtime and host code; - the workspace already contains concrete runtime and host code;
- the CLI dispatcher currently exposes the runtime paths that are backed by binaries in this workspace. - the CLI dispatcher currently exposes the runtime paths that are backed by binaries in this workspace.
@@ -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. /// The intrinsic ID provided is not recognized by the runtime, or its metadata is invalid.
pub const TRAP_INVALID_INTRINSIC: u32 = 0x0000_000D; 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}; use serde::{Deserialize, Serialize};
/// Detailed information about a source code span. /// Detailed information about a source code span.
@@ -47,4 +62,9 @@ pub struct TrapInfo {
pub pc: u32, pub pc: u32,
/// Optional source span information if debug symbols are available. /// Optional source span information if debug symbols are available.
pub span: Option<SourceSpan>, 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> { 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 mut parts = s.split(',');
let a = parts.next().ok_or_else(|| AsmError::MissingOperand(s.into()))?.trim(); let a = parts.next().ok_or_else(|| AsmError::MissingOperand(s.into()))?.trim();
let b = 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" => { "NOP" => {
emit_u16(CoreOpCode::Nop as u16, &mut out); emit_u16(CoreOpCode::Nop as u16, &mut out);
} }
"POP" => emit_u16(CoreOpCode::Pop as u16, &mut out),
"HALT" => { "HALT" => {
emit_u16(CoreOpCode::Halt as u16, &mut out); emit_u16(CoreOpCode::Halt as u16, &mut out);
} }
@@ -177,8 +178,8 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
"RET" => { "RET" => {
emit_u16(CoreOpCode::Ret as u16, &mut out); emit_u16(CoreOpCode::Ret as u16, &mut out);
} }
"YIELD" => { "YIELD" | "SLEEP" | "SPAWN" => {
emit_u16(CoreOpCode::Yield as u16, &mut out); return Err(AsmError::InvalidOperand("retired coroutine instruction".into()));
} }
"FRAME_SYNC" => { "FRAME_SYNC" => {
emit_u16(CoreOpCode::FrameSync as u16, &mut out); 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_u16(CoreOpCode::Call as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out); emit_u32(parse_u32_any(ops)?, &mut out);
} }
"CALL_CLOSURE" => { "CALL_CLOSURE" | "GET_CAPTURE" => {
if ops.is_empty() { if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into())); return Err(AsmError::MissingOperand(line.into()));
} }
let (k, v) = let opcode = if mn == "CALL_CLOSURE" {
ops.split_once('=').ok_or_else(|| AsmError::InvalidOperand(ops.into()))?; CoreOpCode::CallClosure
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)
} else { } else {
return Err(AsmError::InvalidOperand(ops.into())); CoreOpCode::GetCapture
}; };
emit_u16(CoreOpCode::MakeClosure as u16, &mut out); emit_u16(opcode 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_u32(parse_u32_any(ops)?, &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" => { "HOSTCALL" => {
if ops.is_empty() { if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into())); return Err(AsmError::MissingOperand(line.into()));
@@ -360,6 +336,66 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u32(parse_u32_any(ops)?, &mut out); 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" | "ARRAY_COPY" => {
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,
"ARRAY_COPY" => CoreOpCode::ArrayCopy,
_ => CoreOpCode::ArraySet,
};
emit_u16(op as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"DYN_PACK" | "DYN_UNPACK" | "DYN_CAN_UNPACK" | "REF_IDENTITY_HASH" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let opcode = match mn {
"DYN_PACK" => CoreOpCode::DynPack,
"DYN_UNPACK" => CoreOpCode::DynUnpack,
"REF_IDENTITY_HASH" => CoreOpCode::RefIdentityHash,
_ => CoreOpCode::DynCanUnpack,
};
emit_u16(opcode as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"REF_IDENTITY_EQ" => {
let (a, b) = parse_keyvals(ops)?;
let (left, right) = parse_pair(a, "left", b, "right")?;
emit_u16(CoreOpCode::RefIdentityEq as u16, &mut out);
emit_u32(left, &mut out);
emit_u32(right, &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())), other => return Err(AsmError::UnknownMnemonic(other.into())),
} }
} }
@@ -90,7 +90,7 @@ impl<'a> DecodedInstr<'a> {
/// Returns the decoded instruction with canonical `next_pc`. /// Returns the decoded instruction with canonical `next_pc`.
#[inline] #[inline]
pub fn decode_next(pc: usize, bytes: &'_ [u8]) -> Result<DecodedInstr<'_>, DecodeError> { 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 }); 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 spec: CoreOpcodeSpec = opcode.spec();
let imm_start = pc + 2; 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() { if imm_end > bytes.len() {
return Err(DecodeError::TruncatedImmediate { return Err(DecodeError::TruncatedImmediate {
@@ -10,9 +10,9 @@
//! - `MNEMONIC <imm>` for 1-operand instructions (decimal unless stated). //! - `MNEMONIC <imm>` for 1-operand instructions (decimal unless stated).
//! - Special operand formats: //! - Special operand formats:
//! - `PUSH_F64 f64:0xhhhhhhhhhhhhhhhh` — exact IEEE-754 bits in hex (little-endian to_bits()). //! - `PUSH_F64 f64:0xhhhhhhhhhhhhhhhh` — exact IEEE-754 bits in hex (little-endian to_bits()).
//! - `MAKE_CLOSURE fn=<u32>, captures=<u32>` //! - `MAKE_CLOSURE fn=<u32>, type=<u32>`
//! - `SPAWN fn=<u32>, argc=<u32>` //! - Retired SPAWN/YIELD/SLEEP are identified for diagnostics only.
//! - `CALL_CLOSURE argc=<u32>` //! - `CALL_CLOSURE <FnTypeId>`
//! - `HOSTCALL <index>` is printed in decimal because it is a `SYSC` table index. //! - `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. //! - `SYSCALL` is printed as `SYSCALL 0xhhhh` (numeric id in hex) to avoid cross-crate deps.
//! //!
@@ -60,18 +60,51 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
| CoreOpCode::SetLocal | CoreOpCode::SetLocal
| CoreOpCode::Call | CoreOpCode::Call
| CoreOpCode::Sleep | CoreOpCode::Sleep
| CoreOpCode::Hostcall => { | CoreOpCode::GetCapture
| CoreOpCode::CallClosure
| CoreOpCode::Hostcall
| CoreOpCode::DynPack
| CoreOpCode::DynUnpack
| CoreOpCode::RefIdentityHash
| CoreOpCode::DynCanUnpack
| CoreOpCode::StructNew
| CoreOpCode::ArrayNew
| CoreOpCode::ArrayLen
| CoreOpCode::ArrayGet
| CoreOpCode::ArraySet
| CoreOpCode::ArrayCopy => {
let v = u32::from_le_bytes(imm.try_into().unwrap()); let v = u32::from_le_bytes(imm.try_into().unwrap());
format!("{}", v) 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::RefIdentityEq => {
let left = u32::from_le_bytes(imm[..4].try_into().unwrap());
let right = u32::from_le_bytes(imm[4..].try_into().unwrap());
format!("left={}, right={}", left, right)
}
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 => { CoreOpCode::MakeClosure => {
let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap()); 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()); 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 => { CoreOpCode::CallTrait => {
let argc = u32::from_le_bytes(imm.try_into().unwrap()); let (ty, method) = (
format!("argc={}", argc) 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 => { CoreOpCode::Spawn => {
let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap()); let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap());
@@ -1,8 +1,9 @@
//! Core ISA profile (bytecode-level, stable, canonical). //! Core ISA profile (bytecode-level, stable, canonical).
//! //!
//! This profile is the canonical opcode surface used by decoder/disasm and //! This profile is the canonical opcode surface used by decoder/disasm and
//! mirrors the runtime-visible instruction set implemented today, including //! exposes the canonical encoding for closures, coroutines, intrinsics,
//! closures, coroutines, intrinsics, and hostcall patching semantics. //! 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 // 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: // 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)
);
}
}
}
+17 -7
View File
@@ -3,22 +3,32 @@ pub mod assembler;
mod decoder; mod decoder;
mod disassembler; mod disassembler;
pub mod isa; // canonical ISA boundary (core and future profiles) pub mod isa; // canonical ISA boundary (core and future profiles)
mod layout;
pub mod model; pub mod model;
mod opcode; mod opcode;
mod opcode_spec; mod opcode_spec;
mod program_image; mod program_image;
mod resource_failure;
mod value; mod value;
pub use abi::{ pub use abi::{
TrapInfo, TRAP_BAD_RET_SLOTS, TRAP_DIV_ZERO, TRAP_EXPLICIT, TRAP_ILLEGAL_INSTRUCTION, SourceSpan, TrapInfo, TRAP_BAD_RET_SLOTS, TRAP_DIV_ZERO, TRAP_EXPLICIT,
TRAP_INVALID_FUNC, TRAP_INVALID_INTRINSIC, TRAP_INVALID_LOCAL, TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_ILLEGAL_INSTRUCTION, TRAP_INVALID_FUNC, TRAP_INVALID_HANDLE, TRAP_INVALID_INTRINSIC,
TRAP_STACK_UNDERFLOW, TRAP_TYPE, 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 assembler::{assemble, AsmError};
pub use decoder::{decode_next, DecodeError}; pub use decoder::{decode_next, DecodeError, DecodedInstr};
pub use disassembler::disassemble; pub use disassembler::disassemble;
pub use layout::{compute_function_layouts, FunctionLayout}; pub use model::{LoadError, SyscallDecl, PBX_MAGIC};
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl}; pub use program_image::ExecutionFunction;
pub use program_image::ProgramImage; pub use program_image::ProgramImage;
pub use resource_failure::{ResourceFailure, ResourceReason, RuntimeResource};
pub use value::{string_materialization_count, HeapRef, Value}; 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 v0 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 -883
View File
@@ -1,7 +1,5 @@
use crate::abi::SourceSpan; use crate::abi::SourceSpan;
use crate::opcode::OpCode;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use std::collections::HashSet;
/// An entry in the Constant Pool. /// An entry in the Constant Pool.
/// ///
@@ -42,16 +40,6 @@ pub enum LoadError {
UnexpectedEof, 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)] #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct DebugInfo { pub struct DebugInfo {
pub pc_to_span: Vec<(u32, SourceSpan)>, // Sorted by PC pub pc_to_span: Vec<(u32, SourceSpan)>, // Sorted by PC
@@ -73,874 +61,4 @@ pub struct SyscallDecl {
pub ret_slots: u16, pub ret_slots: u16,
} }
const SECTION_KIND_CONST_POOL: u32 = 0; pub const PBX_MAGIC: [u8; 4] = *b"PBX\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;
/// Represents the final serialized format of a PBS v0 module.
///
/// This structure is a pure data container for the PBS 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 "PBS\0"
out.extend_from_slice(b"PBS\0");
// 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 "PBS\0"
if &bytes[0..4] != b"PBS\0" {
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(b"PBS\0");
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_pbs_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] = b'X';
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_pbs_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_pbs_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));
}
}
+82 -38
View File
@@ -143,46 +143,20 @@ pub enum OpCode {
/// Returns from the current function. /// Returns from the current function.
/// Stack: [return_val] -> [return_val] /// Stack: [return_val] -> [return_val]
Ret = 0x51, Ret = 0x51,
/// Creates a closure capturing values from the operand stack (Model B). /// Create a typed instance: FunctionId, FnTypeId. Captures come from metadata.
/// 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.
MakeClosure = 0x52, MakeClosure = 0x52,
/// Calls a closure value with hidden arg0 semantics (Model B). /// Invoke with expected FnTypeId; environment belongs to CallFrame, not arg0.
/// 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.
CallClosure = 0x53, CallClosure = 0x53,
/// Retired opcode, recognized only for load rejection and diagnostics.
// --- 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.
Spawn = 0x54, Spawn = 0x54,
/// Retired opcode, recognized only for load rejection and diagnostics.
/// Cooperatively yields the current coroutine. Execution continues
/// until the next VM safepoint (FRAME_SYNC), where the scheduler
/// may switch to another ready coroutine.
Yield = 0x55, Yield = 0x55,
/// Retired opcode, recognized only for load rejection and diagnostics.
/// 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.
Sleep = 0x56, 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 --- // --- 6.8 Peripherals and System ---
/// Pre-load host binding call by `SYSC` table index. /// Pre-load host binding call by `SYSC` table index.
@@ -202,6 +176,37 @@ pub enum OpCode {
/// Synchronizes the VM with the hardware frame (usually 60Hz). /// Synchronizes the VM with the hardware frame (usually 60Hz).
/// Execution pauses until the next VSync. /// Execution pauses until the next VSync.
FrameSync = 0x80, 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,
/// Query a complete typed reference identity; source TypeId.
RefIdentityHash = 0x97,
/// Compare two complete typed references; left/right TypeIds.
RefIdentityEq = 0x98,
// Registry-backed collection operations. cycles() is their base component.
StructNew = 0xA0,
StructGet = 0xA1,
StructSet = 0xA2,
ArrayNew = 0xA3,
ArrayLen = 0xA4,
ArrayGet = 0xA5,
ArraySet = 0xA6,
/// Complete stored groups, overlap-safe; Array TypeId:u32.
ArrayCopy = 0xA9,
} }
impl TryFrom<u16> for OpCode { impl TryFrom<u16> for OpCode {
@@ -255,18 +260,39 @@ impl TryFrom<u16> for OpCode {
0x54 => Ok(OpCode::Spawn), 0x54 => Ok(OpCode::Spawn),
0x55 => Ok(OpCode::Yield), 0x55 => Ok(OpCode::Yield),
0x56 => Ok(OpCode::Sleep), 0x56 => Ok(OpCode::Sleep),
0x57 => Ok(OpCode::GetCapture),
0x58 => Ok(OpCode::CallTrait),
0x70 => Ok(OpCode::Syscall), 0x70 => Ok(OpCode::Syscall),
0x71 => Ok(OpCode::Hostcall), 0x71 => Ok(OpCode::Hostcall),
0x72 => Ok(OpCode::Intrinsic), 0x72 => Ok(OpCode::Intrinsic),
0x80 => Ok(OpCode::FrameSync), 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),
0x97 => Ok(OpCode::RefIdentityHash),
0x98 => Ok(OpCode::RefIdentityEq),
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),
0xA9 => Ok(OpCode::ArrayCopy),
_ => Err(format!("Invalid OpCode: 0x{:04X}", value)), _ => Err(format!("Invalid OpCode: 0x{:04X}", value)),
} }
} }
} }
impl OpCode { impl OpCode {
/// Returns the cost of the instruction in VM cycles. /// Returns fixed VM cycles, or the base component for collection operations.
/// This is used for performance monitoring and resource limiting (Certification). /// 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 { pub fn cycles(&self) -> u64 {
match self { match self {
OpCode::Nop => 1, OpCode::Nop => 1,
@@ -311,7 +337,8 @@ impl OpCode {
OpCode::Call => 5, OpCode::Call => 5,
OpCode::Ret => 4, OpCode::Ret => 4,
OpCode::MakeClosure => 8, OpCode::MakeClosure => 8,
OpCode::CallClosure => 6, OpCode::CallClosure | OpCode::CallTrait => 6,
OpCode::GetCapture => 2,
OpCode::Spawn => 6, OpCode::Spawn => 6,
OpCode::Yield => 1, OpCode::Yield => 1,
OpCode::Sleep => 1, OpCode::Sleep => 1,
@@ -319,6 +346,23 @@ impl OpCode {
OpCode::Hostcall => 1, OpCode::Hostcall => 1,
OpCode::Intrinsic => 1, OpCode::Intrinsic => 1,
OpCode::FrameSync => 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::RefIdentityHash => 8,
OpCode::RefIdentityEq => 4,
OpCode::StructNew => 8,
OpCode::StructGet => 3,
OpCode::StructSet => 4,
OpCode::ArrayNew => 8,
OpCode::ArrayLen => 3,
OpCode::ArrayGet => 3,
OpCode::ArraySet => 4,
OpCode::ArrayCopy => 4,
} }
} }
} }
@@ -5,18 +5,24 @@ use crate::opcode::OpCode;
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OpcodeSpec { pub struct OpcodeSpec {
pub name: &'static str, pub name: &'static str,
pub imm_bytes: u8, // immediate payload size (decode) pub imm_bytes: u8, // immediate payload size (decode)
pub pops: u16, // slots popped /// None requires Registry resolution; it never means zero slots.
pub pushes: u16, // slots pushed pub pops: Option<u16>, // slots popped
pub is_branch: bool, // has a control-flow target /// 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 is_terminator: bool, // ends basic block: JMP/RET/TRAP/HALT
pub may_trap: bool, // runtime trap possible pub may_trap: bool, // runtime trap possible
/// Marks this opcode as a VM safepoint. Used by GC/scheduler policies. /// 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 is_safepoint: bool,
} }
pub trait OpCodeSpecExt { pub trait OpCodeSpecExt {
fn spec(&self) -> OpcodeSpec; 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 { impl OpCodeSpecExt for OpCode {
@@ -25,8 +31,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Nop => OpcodeSpec { OpCode::Nop => OpcodeSpec {
name: "NOP", name: "NOP",
imm_bytes: 0, imm_bytes: 0,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -35,8 +41,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Halt => OpcodeSpec { OpCode::Halt => OpcodeSpec {
name: "HALT", name: "HALT",
imm_bytes: 0, imm_bytes: 0,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: true, is_terminator: true,
may_trap: false, may_trap: false,
@@ -45,8 +51,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Jmp => OpcodeSpec { OpCode::Jmp => OpcodeSpec {
name: "JMP", name: "JMP",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: true, is_branch: true,
is_terminator: true, is_terminator: true,
may_trap: false, may_trap: false,
@@ -55,8 +61,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::JmpIfFalse => OpcodeSpec { OpCode::JmpIfFalse => OpcodeSpec {
name: "JMP_IF_FALSE", name: "JMP_IF_FALSE",
imm_bytes: 4, imm_bytes: 4,
pops: 1, pops: Some(1),
pushes: 0, pushes: Some(0),
is_branch: true, is_branch: true,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -65,8 +71,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::JmpIfTrue => OpcodeSpec { OpCode::JmpIfTrue => OpcodeSpec {
name: "JMP_IF_TRUE", name: "JMP_IF_TRUE",
imm_bytes: 4, imm_bytes: 4,
pops: 1, pops: Some(1),
pushes: 0, pushes: Some(0),
is_branch: true, is_branch: true,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -75,8 +81,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Trap => OpcodeSpec { OpCode::Trap => OpcodeSpec {
name: "TRAP", name: "TRAP",
imm_bytes: 0, imm_bytes: 0,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: true, is_terminator: true,
may_trap: true, may_trap: true,
@@ -85,8 +91,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushConst => OpcodeSpec { OpCode::PushConst => OpcodeSpec {
name: "PUSH_CONST", name: "PUSH_CONST",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -95,8 +101,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Pop => OpcodeSpec { OpCode::Pop => OpcodeSpec {
name: "POP", name: "POP",
imm_bytes: 0, imm_bytes: 0,
pops: 1, pops: Some(1),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -105,8 +111,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PopN => OpcodeSpec { OpCode::PopN => OpcodeSpec {
name: "POP_N", name: "POP_N",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -115,8 +121,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Dup => OpcodeSpec { OpCode::Dup => OpcodeSpec {
name: "DUP", name: "DUP",
imm_bytes: 0, imm_bytes: 0,
pops: 1, pops: Some(1),
pushes: 2, pushes: Some(2),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -125,8 +131,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Swap => OpcodeSpec { OpCode::Swap => OpcodeSpec {
name: "SWAP", name: "SWAP",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 2, pushes: Some(2),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -135,8 +141,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushI64 => OpcodeSpec { OpCode::PushI64 => OpcodeSpec {
name: "PUSH_I64", name: "PUSH_I64",
imm_bytes: 8, imm_bytes: 8,
pops: 0, pops: Some(0),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -145,8 +151,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushF64 => OpcodeSpec { OpCode::PushF64 => OpcodeSpec {
name: "PUSH_F64", name: "PUSH_F64",
imm_bytes: 8, imm_bytes: 8,
pops: 0, pops: Some(0),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -155,8 +161,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushBool => OpcodeSpec { OpCode::PushBool => OpcodeSpec {
name: "PUSH_BOOL", name: "PUSH_BOOL",
imm_bytes: 1, imm_bytes: 1,
pops: 0, pops: Some(0),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -165,8 +171,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushI32 => OpcodeSpec { OpCode::PushI32 => OpcodeSpec {
name: "PUSH_I32", name: "PUSH_I32",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -175,8 +181,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Add => OpcodeSpec { OpCode::Add => OpcodeSpec {
name: "ADD", name: "ADD",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -185,8 +191,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Sub => OpcodeSpec { OpCode::Sub => OpcodeSpec {
name: "SUB", name: "SUB",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -195,8 +201,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Mul => OpcodeSpec { OpCode::Mul => OpcodeSpec {
name: "MUL", name: "MUL",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -205,8 +211,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Div => OpcodeSpec { OpCode::Div => OpcodeSpec {
name: "DIV", name: "DIV",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -215,8 +221,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Mod => OpcodeSpec { OpCode::Mod => OpcodeSpec {
name: "MOD", name: "MOD",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -225,8 +231,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Eq => OpcodeSpec { OpCode::Eq => OpcodeSpec {
name: "EQ", name: "EQ",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -235,8 +241,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Neq => OpcodeSpec { OpCode::Neq => OpcodeSpec {
name: "NEQ", name: "NEQ",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -245,8 +251,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Lt => OpcodeSpec { OpCode::Lt => OpcodeSpec {
name: "LT", name: "LT",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -255,8 +261,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Gt => OpcodeSpec { OpCode::Gt => OpcodeSpec {
name: "GT", name: "GT",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -265,8 +271,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::And => OpcodeSpec { OpCode::And => OpcodeSpec {
name: "AND", name: "AND",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -275,8 +281,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Or => OpcodeSpec { OpCode::Or => OpcodeSpec {
name: "OR", name: "OR",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -285,8 +291,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Not => OpcodeSpec { OpCode::Not => OpcodeSpec {
name: "NOT", name: "NOT",
imm_bytes: 0, imm_bytes: 0,
pops: 1, pops: Some(1),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -295,8 +301,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitAnd => OpcodeSpec { OpCode::BitAnd => OpcodeSpec {
name: "BIT_AND", name: "BIT_AND",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -305,8 +311,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitOr => OpcodeSpec { OpCode::BitOr => OpcodeSpec {
name: "BIT_OR", name: "BIT_OR",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -315,8 +321,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitXor => OpcodeSpec { OpCode::BitXor => OpcodeSpec {
name: "BIT_XOR", name: "BIT_XOR",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -325,8 +331,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Shl => OpcodeSpec { OpCode::Shl => OpcodeSpec {
name: "SHL", name: "SHL",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -335,8 +341,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Shr => OpcodeSpec { OpCode::Shr => OpcodeSpec {
name: "SHR", name: "SHR",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -345,8 +351,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Lte => OpcodeSpec { OpCode::Lte => OpcodeSpec {
name: "LTE", name: "LTE",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -355,8 +361,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Gte => OpcodeSpec { OpCode::Gte => OpcodeSpec {
name: "GTE", name: "GTE",
imm_bytes: 0, imm_bytes: 0,
pops: 2, pops: Some(2),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -365,8 +371,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Neg => OpcodeSpec { OpCode::Neg => OpcodeSpec {
name: "NEG", name: "NEG",
imm_bytes: 0, imm_bytes: 0,
pops: 1, pops: Some(1),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -375,8 +381,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::GetGlobal => OpcodeSpec { OpCode::GetGlobal => OpcodeSpec {
name: "GET_GLOBAL", name: "GET_GLOBAL",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -385,8 +391,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::SetGlobal => OpcodeSpec { OpCode::SetGlobal => OpcodeSpec {
name: "SET_GLOBAL", name: "SET_GLOBAL",
imm_bytes: 4, imm_bytes: 4,
pops: 1, pops: Some(1),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -395,8 +401,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::GetLocal => OpcodeSpec { OpCode::GetLocal => OpcodeSpec {
name: "GET_LOCAL", name: "GET_LOCAL",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 1, pushes: Some(1),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -405,8 +411,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::SetLocal => OpcodeSpec { OpCode::SetLocal => OpcodeSpec {
name: "SET_LOCAL", name: "SET_LOCAL",
imm_bytes: 4, imm_bytes: 4,
pops: 1, pops: Some(1),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -415,8 +421,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Call => OpcodeSpec { OpCode::Call => OpcodeSpec {
name: "CALL", name: "CALL",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -425,44 +431,41 @@ impl OpCodeSpecExt for OpCode {
OpCode::Ret => OpcodeSpec { OpCode::Ret => OpcodeSpec {
name: "RET", name: "RET",
imm_bytes: 0, imm_bytes: 0,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: true, is_terminator: true,
may_trap: false, may_trap: false,
is_safepoint: false, is_safepoint: false,
}, },
OpCode::MakeClosure => OpcodeSpec { OpCode::MakeClosure | OpCode::CallClosure | OpCode::GetCapture | OpCode::CallTrait => {
name: "MAKE_CLOSURE", OpcodeSpec {
// Two u32 immediates: fn_id and capture_count name: match self {
imm_bytes: 8, OpCode::MakeClosure => "MAKE_CLOSURE",
// Dynamic, depends on capture_count; keep 0 here for verifier-free spec OpCode::CallClosure => "CALL_CLOSURE",
pops: 0, OpCode::GetCapture => "GET_CAPTURE",
pushes: 1, _ => "CALL_TRAIT",
is_branch: false, },
is_terminator: false, imm_bytes: if matches!(self, OpCode::MakeClosure | OpCode::CallTrait) {
may_trap: false, 8
is_safepoint: false, } else {
}, 4
OpCode::CallClosure => OpcodeSpec { },
name: "CALL_CLOSURE", pops: None,
// One u32 immediate: arg_count (user args, excludes hidden arg0) pushes: None,
imm_bytes: 4, is_branch: false,
// Dynamic: pops closure_ref + arg_count; keep 0 in spec layer is_terminator: false,
pops: 0, may_trap: true,
pushes: 0, is_safepoint: false,
is_branch: false, }
is_terminator: false, }
may_trap: true,
is_safepoint: false,
},
OpCode::Spawn => OpcodeSpec { OpCode::Spawn => OpcodeSpec {
name: "SPAWN", name: "SPAWN",
// Two u32 immediates: fn_id and arg_count // Two u32 immediates: fn_id and arg_count
imm_bytes: 8, imm_bytes: 8,
// Dynamic pops depends on arg_count; keep 0 here in spec layer // Dynamic pops depends on arg_count; keep 0 here in spec layer
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -471,33 +474,33 @@ impl OpCodeSpecExt for OpCode {
OpCode::Yield => OpcodeSpec { OpCode::Yield => OpcodeSpec {
name: "YIELD", name: "YIELD",
imm_bytes: 0, imm_bytes: 0,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
// Not a block terminator; effect realized at safepoint // Retired encoding: retained for diagnostic decoding only.
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
// Treated as a safepoint marker for cooperative scheduling // Loading rejects this opcode, including unreachable occurrences.
is_safepoint: true, is_safepoint: false,
}, },
OpCode::Sleep => OpcodeSpec { OpCode::Sleep => OpcodeSpec {
name: "SLEEP", name: "SLEEP",
// One u32 immediate: duration_ticks // One u32 immediate: duration_ticks
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
// Ends execution at safepoint after instruction completes // Retired encoding: retained for diagnostic decoding only.
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
// Considered a safepoint since it forces a frame boundary // Loading rejects this opcode, including unreachable occurrences.
is_safepoint: true, is_safepoint: false,
}, },
OpCode::Hostcall => OpcodeSpec { OpCode::Hostcall => OpcodeSpec {
name: "HOSTCALL", name: "HOSTCALL",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: false, may_trap: false,
@@ -506,8 +509,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Syscall => OpcodeSpec { OpCode::Syscall => OpcodeSpec {
name: "SYSCALL", name: "SYSCALL",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -516,8 +519,178 @@ impl OpCodeSpecExt for OpCode {
OpCode::Intrinsic => OpcodeSpec { OpCode::Intrinsic => OpcodeSpec {
name: "INTRINSIC", name: "INTRINSIC",
imm_bytes: 4, imm_bytes: 4,
pops: 0, pops: Some(0),
pushes: 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::RefIdentityHash => OpcodeSpec {
name: "REF_IDENTITY_HASH",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefIdentityEq => OpcodeSpec {
name: "REF_IDENTITY_EQ",
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,
is_safepoint: false,
},
OpCode::ArrayCopy => OpcodeSpec {
name: "ARRAY_COPY",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: true, may_trap: true,
@@ -526,8 +699,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::FrameSync => OpcodeSpec { OpCode::FrameSync => OpcodeSpec {
name: "FRAME_SYNC", name: "FRAME_SYNC",
imm_bytes: 0, imm_bytes: 0,
pops: 0, pops: Some(0),
pushes: 0, pushes: Some(0),
is_branch: false, is_branch: false,
is_terminator: false, is_terminator: false,
may_trap: 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::abi::TrapInfo;
use crate::model::{BytecodeModule, ConstantPoolEntry, DebugInfo, Export, FunctionMeta}; use crate::model::DebugInfo;
use crate::value::Value; use crate::value::Value;
use serde::{Deserialize, Serialize};
use std::collections::HashMap; use std::collections::HashMap;
use std::sync::Arc; use std::sync::Arc;
/// Represents a fully linked, executable PBS program image. /// Immutable execution payload/cache, produced during sealed image publication.
/// /// This container does not authorize execution. VM sessions require the private
/// Under the Prometeu architecture, the ProgramImage is a "closed-world" artifact /// ValidatedProgramImage factory, including bounded Registry/ISA/native checks.
/// 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.
#[derive(Debug, Clone, Default)] #[derive(Debug, Clone, Default)]
pub struct ProgramImage { pub struct ProgramImage {
pub rom: Arc<[u8]>, pub rom: Arc<[u8]>,
pub constant_pool: Arc<[Value]>, pub constant_pool: Arc<[Value]>,
pub functions: Arc<[FunctionMeta]>, pub functions: Arc<[ExecutionFunction]>,
pub debug_info: Option<DebugInfo>, pub debug_info: Option<Arc<DebugInfo>>,
pub exports: Arc<HashMap<String, u32>>, pub exports: Arc<HashMap<String, u32>>,
} }
impl ProgramImage { 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 { pub fn create_trap(&self, code: u32, opcode: u16, mut message: String, pc: u32) -> TrapInfo {
let span = self let span = self
.debug_info .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> { pub fn find_function_index(&self, pc: u32) -> Option<usize> {
@@ -64,61 +56,3 @@ impl ProgramImage {
.map(|(_, name)| name.as_str()) .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,846 @@
//! 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),
}
impl TypeKind {
/// Categories supported by identity queries, not by legacy REF_* conversions.
pub fn is_identity_reference(&self) -> bool {
matches!(
self,
Self::Struct(_)
| Self::Array(_)
| Self::Fn(_)
| Self::Trait(_)
| Self::Builtin(BuiltinId::RANDOM)
)
}
}
#[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 v0 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] != [0, 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 v0 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 v0 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(&[0, 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 v0 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 v0; 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,203 @@
//! 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::RefIdentityHash | Op::RefIdentityEq => {
let (left, right) = if self.opcode == Op::RefIdentityHash {
(self.imm_u32().map_err(|_| malformed())?, None)
} else {
let (a, b) = self.imm_u32x2().map_err(|_| malformed())?;
(a, Some(b))
};
let mut pops = 0;
for id in std::iter::once(left).chain(right) {
let (decl, layout) = type_info(id)?;
if !decl.kind.is_identity_reference() {
return Err(bad_category(id));
}
pops += layout.storage.slots;
}
(pops, 1)
}
Op::ArrayCopy => {
let array = self.imm_u32().map_err(|_| malformed())?;
let (_, layout) = type_info(array)?;
layout.array.ok_or_else(|| bad_category(array))?;
(5, 0)
}
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 serde::{Deserialize, Serialize};
use std::cell::Cell; use std::cell::Cell;
use std::cmp::Ordering; use std::cmp::Ordering;
use std::fmt::Write;
use std::sync::Arc; use std::sync::Arc;
thread_local! { thread_local! {
@@ -10,17 +9,28 @@ thread_local! {
/// Opaque handle that references an object stored in the VM heap. /// Opaque handle that references an object stored in the VM heap.
/// ///
/// This is an index-based handle. It does not imply ownership and carries /// Handles belong to the heap/session that issued them. Native boundaries must
/// no lifetime information. GC/allocator integration will come in later PRs. /// 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)] #[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. /// 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 /// This enum is a physical carrier, not a semantic type declaration. Registry
/// `Value` enum can hold different primitive types. The VM performs /// boundaries validate exact types and complete multi-slot groups. Arithmetic
/// automatic type promotion (e.g., adding an Int32 to a Float64 results /// instructions may have their own numeric promotion rules; those rules do not
/// in a Float64) to ensure mathematical correctness. /// authorize implicit conversions at typed storage or call boundaries.
#[derive(Debug, Clone, Serialize, Deserialize)] #[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)] #[serde(untagged)]
pub enum Value { pub enum Value {
@@ -108,24 +118,20 @@ impl Value {
} }
pub fn append_to_string(&self, out: &mut String) { 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 { match self {
Value::Int32(i) => { Value::Int32(i) => write!(out, "{}", i),
let _ = write!(out, "{}", i); Value::Int64(i) => write!(out, "{}", i),
} Value::Float(f) => write!(out, "{}", f),
Value::Int64(i) => { Value::Boolean(b) => write!(out, "{}", b),
let _ = write!(out, "{}", i); Value::String(s) => out.write_str(s),
} Value::HeapRef(r) => write!(out, "[HeapRef {}:{}]", r.index, r.generation),
Value::Float(f) => { Value::Null => out.write_str("null"),
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"),
} }
} }
@@ -138,7 +144,7 @@ impl Value {
Value::Int32(i) => i.to_string().len(), Value::Int32(i) => i.to_string().len(),
Value::Int64(i) => i.to_string().len(), Value::Int64(i) => i.to_string().len(),
Value::Float(f) => f.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] #[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; // 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 // SPAWN fn=2,argc=1; YIELD; SLEEP 3; HOSTCALL 2; SYSCALL 0x1003; FRAME_SYNC; HALT
let mut prog = Vec::new(); 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); emit(CoreOpCode::MakeClosure, Some(&mc), &mut prog);
// CALL_CLOSURE argc=1 // CALL_CLOSURE argc=1
emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog); emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog);
// SPAWN (fn=2, argc=1) emit(CoreOpCode::GetCapture, Some(&0u32.to_le_bytes()), &mut prog);
let mut sp = [0u8; 8]; let trait_call = [7u32.to_le_bytes(), 0u32.to_le_bytes()].concat();
sp[0..4].copy_from_slice(&2u32.to_le_bytes()); emit(CoreOpCode::CallTrait, Some(&trait_call), &mut prog);
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);
// HOSTCALL sysc[2] // HOSTCALL sysc[2]
emit(CoreOpCode::Hostcall, Some(&2u32.to_le_bytes()), &mut prog); emit(CoreOpCode::Hostcall, Some(&2u32.to_le_bytes()), &mut prog);
// SYSCALL gfx2d.draw_line (0x1003) // 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[0..4].copy_from_slice(&1u32.to_le_bytes());
mc[4..8].copy_from_slice(&0u32.to_le_bytes()); mc[4..8].copy_from_slice(&0u32.to_le_bytes());
emit(CoreOpCode::MakeClosure, Some(&mc), &mut prog); emit(CoreOpCode::MakeClosure, Some(&mc), &mut prog);
// CALL_CLOSURE argc=1 // CALL_CLOSURE 1
emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog); emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog);
// SPAWN (fn=2, argc=1) // SPAWN (fn=2, argc=1)
let mut sp = [0u8; 8]; let mut sp = [0u8; 8];
@@ -38,6 +38,6 @@ fn snapshot_representative_program_is_stable() {
emit(CoreOpCode::Halt, None, &mut prog); emit(CoreOpCode::Halt, None, &mut prog);
let text = disassemble(&prog).expect("disasm ok"); 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); assert_eq!(text, expected);
} }
@@ -0,0 +1,276 @@
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),
("REF_IDENTITY_HASH 16909060", &[0x97, 0, 4, 3, 2, 1], 8),
("REF_IDENTITY_EQ left=16909060, right=84281096", &[0x98, 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, &[0x99, 0]),
Err(DecodeError::UnknownOpcode { opcode: 0x99, .. })
));
}
#[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),
("REF_IDENTITY_HASH 6", 2, 1),
("REF_IDENTITY_EQ left=6, right=4", 3, 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",
"REF_IDENTITY_HASH 0",
"REF_IDENTITY_HASH 3",
"REF_IDENTITY_EQ left=4, right=1",
] {
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",
"REF_IDENTITY_HASH",
"REF_IDENTITY_HASH -1",
"REF_IDENTITY_EQ left=4",
"REF_IDENTITY_EQ left=4, target=5",
] {
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
);
}
}
#[test]
fn removed_storage_encodings_and_mnemonics_are_unsupported() {
for opcode in [0xa7u16, 0xa8, 0xaa, 0xab] {
assert!(Op::try_from(opcode).is_err());
let bytes = opcode.to_le_bytes();
assert!(
matches!(decode_next(0,&bytes),Err(DecodeError::UnknownOpcode{pc:0,opcode: actual}) if actual == opcode)
);
assert!(disassemble(&bytes).is_err());
}
for text in
["INDEX_GUARD", "ARRAY_CHECK_LENGTH 1", "STORAGE_PUBLISH 1,2,0,1", "FIELDS_PUBLISH 1"]
{
assert!(assemble(text).is_err(), "{text}");
}
}
#[test]
fn range_copy_encoding_effects_and_registry_categories_are_independent_oracles() {
let bytes = [0xa9, 0, 4, 3, 2, 1];
assert_eq!(assemble("ARRAY_COPY 16909060").unwrap(), bytes);
assert_eq!(disassemble(&bytes).unwrap(), "ARRAY_COPY 16909060");
let instruction = decode_next(0, &bytes).unwrap();
assert_eq!(instruction.opcode, Op::ArrayCopy);
assert_eq!(instruction.opcode.cycles(), 4);
let spec = instruction.opcode.spec();
assert_eq!((spec.imm_bytes, spec.pops, spec.pushes), (4, None, None));
assert!(instruction.opcode.requires_registry() && spec.may_trap);
assert!(!spec.is_safepoint && !spec.is_branch && !spec.is_terminator);
for end in 0..6 {
assert!(decode_next(0, &bytes[..end]).is_err());
}
let registry = registry();
let bytes = assemble("ARRAY_COPY 5").unwrap();
assert_eq!(
decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap(),
Some(RegistryStackEffect { pops: 5, pushes: 0 })
);
for (id, reason) in [
(0, LoadReason::Category),
(4, LoadReason::Category),
(6, LoadReason::Category),
(99, LoadReason::TypeId),
] {
let bytes = assemble(&format!("ARRAY_COPY {id}")).unwrap();
let error = decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap_err();
assert_eq!(
(error.code, error.reason, error.pc),
(LoadCode::InvalidReference, reason, Some(0))
);
}
for text in ["ARRAY_COPY", "ARRAY_COPY -1", "ARRAY_COPY 4294967296", "ARRAY_COPY 1 2"] {
assert!(assemble(text).is_err());
}
// These are legal immediate bytes, not instruction boundaries.
let bytes = assemble("PUSH_I64 18735214094965159\nHALT").unwrap();
assert!(disassemble(&bytes).is_ok());
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,256 @@
//! Repeatable CPU/memory observations, not a handheld or physical-device guarantee.
use prometeu_drivers::{
Audio, MemoryBanks, SoundBankPoolInstaller,
bank_format::{decode_audio_bank, encode_ima_wav4},
engine::{AudioMixer, Packet},
};
use prometeu_hal::{
AudioBridge, LoopMode,
audio_bridge::AudioControl,
music_bank::{Instrument, MusicBank, MusicEvent},
sample::Sample,
sound_bank::SoundBank,
};
use serde_json::{Value, json};
use std::{
alloc::{GlobalAlloc, Layout, System},
sync::{
Arc,
atomic::{AtomicUsize, Ordering},
},
time::Instant,
};
struct Counter;
static LIVE: AtomicUsize = AtomicUsize::new(0);
static PEAK: AtomicUsize = AtomicUsize::new(0);
unsafe impl GlobalAlloc for Counter {
unsafe fn alloc(&self, l: Layout) -> *mut u8 {
let p = unsafe { System.alloc(l) };
if !p.is_null() {
let n = LIVE.fetch_add(l.size(), Ordering::Relaxed) + l.size();
PEAK.fetch_max(n, Ordering::Relaxed);
}
p
}
unsafe fn dealloc(&self, p: *mut u8, l: Layout) {
LIVE.fetch_sub(l.size(), Ordering::Relaxed);
unsafe { System.dealloc(p, l) }
}
}
#[global_allocator]
static ALLOCATOR: Counter = Counter;
fn stats(values: &mut [u64]) -> Value {
values.sort_unstable();
let n = values.len();
json!({"p50_ns":values[n/2],"p95_ns":values[n*95/100],"p99_ns":values[n*99/100],"max_ns":values[n-1]})
}
fn music(channels: u8) -> Arc<MusicBank> {
let pcm = (0..4096)
.flat_map(|i| {
std::iter::repeat_n(((i as f64 * 0.05).sin() * 800.0) as i16, channels as usize)
})
.collect();
let sample =
Arc::new(Sample::new(48000, pcm).with_channels(channels).unwrap().with_loop(0, 4096));
let events = (0..12)
.map(|id| MusicEvent { kind: 1, a: id, c: 60 + id as i32, d: 180, ..Default::default() })
.collect();
Arc::new(
MusicBank::compile(
"measure".into(),
vec![sample],
vec![Instrument {
looping: true,
attack_us: 1000,
decay_us: 10_000,
sustain: 50000,
release_us: 10_000,
send: 20000,
vibrato_cents: 10,
vibrato_millihz: 5000,
tremolo_depth: 1000,
tremolo_millihz: 3000,
..Default::default()
}],
events,
960,
500000,
3840,
None,
1,
)
.unwrap(),
)
}
fn scenario(channels: u8, dsp: bool, replacement: bool) -> Value {
let banks = Arc::new(MemoryBanks::new());
let mut audio = Audio::new(banks.clone());
banks.install_music_bank(0, music(channels));
banks.install_music_bank(1, music(channels));
audio.music_play(0, 0, true);
audio.music_play(1, 1, true);
let sample = Arc::new(
Sample::new(48000, vec![500; 4096 * channels as usize])
.with_channels(channels)
.unwrap()
.with_loop(0, 4096),
);
for voice in 0..8 {
audio.play_sample(sample.clone(), voice, 255, 128, 1.0, 0, LoopMode::On);
audio.control(AudioControl::SfxSend { voice, gain: 100 });
}
if dsp {
for group in 0..3 {
audio.control(AudioControl::Effect {
group,
cutoff_hz: 6000,
delay_frames: 4800,
feedback: 0.5,
wet: 0.3,
dry: 0.7,
});
}
}
audio.finish_frame();
let mut mixer = AudioMixer::new();
let mut packet = Packet::new();
mixer.apply_delivery_into(audio.transport().try_take().unwrap(), &mut packet);
packet.recycle(&audio.transport());
let mut pcm = [0.0; 512];
let mut timings = Vec::with_capacity(1000);
let mut overruns = 0;
let mut max_retired = 0;
let baseline = LIVE.load(Ordering::Relaxed);
PEAK.store(baseline, Ordering::Relaxed);
for iteration in 0..1000 {
if replacement && iteration % 10 == 0 {
banks.install_music_bank(0, music(channels));
audio.music_play(0, 0, true);
audio.control(AudioControl::MusicFade {
group: 1,
gain: 180,
frames: 2400,
smooth: true,
});
audio.finish_frame();
}
let start = Instant::now();
mixer.retire_inactive(&mut packet);
if let Some(delivery) = audio.transport().try_take() {
mixer.apply_delivery_into(delivery, &mut packet);
}
mixer.mix(&mut pcm);
mixer.retire_inactive(&mut packet);
let elapsed = start.elapsed().as_nanos() as u64;
if elapsed > 5_333_333 {
overruns += 1;
}
timings.push(elapsed);
max_retired = max_retired.max(packet.retained_pcm_bytes());
packet.recycle(&audio.transport());
std::hint::black_box(&pcm);
}
json!({"channels_per_voice":channels,"dsp":dsp,"replacement_every_10_buffers":replacement,"buffers":1000,"frames_per_buffer":256,"nominal_buffer_ns":5_333_333,"observed_budget_overruns":overruns,"timing":stats(&mut timings),"maximum_active_voices":mixer.diagnostics.maximum_voices,"engine_prepared_bytes":mixer.prepared_bytes(),"maximum_retired_pcm_bytes":max_retired,"baseline_allocated_bytes":baseline,"peak_allocated_bytes":PEAK.load(Ordering::Relaxed)})
}
fn codec_and_memory() -> Value {
let pcm: Vec<i16> = (0..480_000)
.flat_map(|i| {
[((i as f64 * 0.04).sin() * 12000.0) as i16, ((i as f64 * 0.06).cos() * 9000.0) as i16]
})
.collect();
let start = Instant::now();
let compressed = encode_ima_wav4(&pcm, 2, 512).unwrap();
let encode_ns = start.elapsed().as_nanos();
let mut bytes = vec![0u8; 88];
bytes[..4].copy_from_slice(b"SBNK");
bytes[4] = 1;
bytes[48] = 1;
bytes[49] = 2;
bytes[80] = 255;
bytes[81] = 128;
for (at, n) in [
(8, 1u32),
(20, 960),
(24, 500000),
(32, u32::MAX),
(52, 48000),
(56, 480000),
(68, 88),
(72, compressed.len() as u32),
(84, 65536),
] {
bytes[at..at + 4].copy_from_slice(&n.to_le_bytes());
}
bytes[76..78].copy_from_slice(&512u16.to_le_bytes());
bytes[78..80].copy_from_slice(&505u16.to_le_bytes());
bytes.extend(&compressed);
let mut decode = Vec::with_capacity(20);
let baseline = LIVE.load(Ordering::Relaxed);
PEAK.store(baseline, Ordering::Relaxed);
for _ in 0..20 {
let start = Instant::now();
let bank = decode_audio_bank(&bytes, false).unwrap();
decode.push(start.elapsed().as_nanos() as u64);
std::hint::black_box(bank);
}
let decode_peak = PEAK.load(Ordering::Relaxed);
let banks = MemoryBanks::new();
for slot in 0..16 {
banks.install_sound_bank(
slot,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48000, vec![0; 1_048_576]))])),
);
}
let large_music = || {
let sample = Arc::new(Sample::new(48000, vec![0; 1_048_576]).with_loop(0, 1_048_576));
Arc::new(
MusicBank::compile(
"large".into(),
vec![sample],
vec![Instrument { looping: true, ..Default::default() }],
vec![MusicEvent { kind: 1, a: 1, c: 60, d: 255, ..Default::default() }],
960,
500000,
3840,
None,
1,
)
.unwrap(),
)
};
for slot in 0..16 {
banks.install_music_bank(slot, large_music());
}
let snapshot = banks.audio_memory();
let mut mixer = AudioMixer::new();
let mut packet = Packet::new();
use prometeu_drivers::SoundBankPoolAccess;
mixer.apply_delivery_into(
prometeu_drivers::AudioDelivery {
epoch: 0,
paused: false,
frame: Some(vec![prometeu_drivers::AudioCommand::MusicPlay {
group: 0,
bank: banks.music_bank_slot(0).unwrap(),
looping: true,
}]),
lifecycle: None,
},
&mut packet,
);
packet.recycle(&prometeu_drivers::AudioTransport::default());
mixer.mix(&mut [0.0; 2]);
let before = LIVE.load(Ordering::Relaxed);
PEAK.store(before, Ordering::Relaxed);
banks.install_music_bank(0, large_music());
mixer.retire_inactive(&mut packet);
let retired = packet.retained_pcm_bytes();
let replacement_peak = PEAK.load(Ordering::Relaxed);
packet.recycle(&prometeu_drivers::AudioTransport::default());
let after = LIVE.load(Ordering::Relaxed);
json!({"source_frames":480000,"channels":2,"pcm_bytes":pcm.len()*2,"cartridge_sample_bytes":compressed.len(),"compression_ratio":compressed.len()as f64/(pcm.len()*2)as f64,"encode_ns":encode_ns,"decode_timing":stats(&mut decode),"decode_baseline_allocated_bytes":baseline,"decode_peak_allocated_bytes":decode_peak,"large_bank_count":snapshot.banks.len(),"large_banks_unique_pcm_bytes":snapshot.unique_pcm_bytes,"replacement_baseline_allocated_bytes":before,"replacement_peak_allocated_bytes":replacement_peak,"replacement_after_reclamation_bytes":after,"retained_replaced_pcm_bytes":retired,"resident_accounted_metadata_bytes":snapshot.metadata_bytes,"resident_total_accounted_bytes":snapshot.total_accounted_bytes})
}
fn main() {
println!("{}",serde_json::to_string_pretty(&json!({"arch":std::env::consts::ARCH,"os":std::env::consts::OS,"observations":[scenario(1,false,false),scenario(2,false,false),scenario(2,true,false),scenario(2,true,true)],"codecs_and_memory":codec_and_memory()})).unwrap());
}
@@ -0,0 +1,185 @@
//! Controlled graphics measurement. This is not a cartridge stress-suite replacement.
use prometeu_drivers::{Gfx, GlyphBankPoolInstaller, MemoryBanks, hardware::Hardware};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{GlyphBank, TileSize};
use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::scene_viewport_cache::SceneViewportCache;
use prometeu_hal::scene_viewport_resolver::SceneViewportResolver;
use prometeu_hal::sprite::Sprite;
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use prometeu_hal::{FrameId, OwnedRgba8888Frame, RenderOwnership, app_mode::AppMode};
use std::alloc::{GlobalAlloc, Layout, System};
use std::sync::{
Arc,
atomic::{AtomicUsize, Ordering},
};
use std::time::Instant;
struct CountingAllocator;
static LIVE: AtomicUsize = AtomicUsize::new(0);
static PEAK: AtomicUsize = AtomicUsize::new(0);
static ALLOCATIONS: AtomicUsize = AtomicUsize::new(0);
// Only the measurement executable pays the atomic allocation instrumentation cost.
unsafe impl GlobalAlloc for CountingAllocator {
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
let ptr = unsafe { System.alloc(layout) };
if !ptr.is_null() {
let live = LIVE.fetch_add(layout.size(), Ordering::Relaxed) + layout.size();
PEAK.fetch_max(live, Ordering::Relaxed);
ALLOCATIONS.fetch_add(1, Ordering::Relaxed);
}
ptr
}
unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
LIVE.fetch_sub(layout.size(), Ordering::Relaxed);
unsafe { System.dealloc(ptr, layout) };
}
}
#[global_allocator]
static ALLOCATOR: CountingAllocator = CountingAllocator;
fn summary(samples: &mut [u64]) -> serde_json::Value {
samples.sort_unstable();
let n = samples.len();
serde_json::json!({"mean_us": samples.iter().sum::<u64>() as f64 / n as f64 / 1000.0,
"p95_us": samples[(n * 95).div_ceil(100) - 1] as f64 / 1000.0,
"p99_us": samples[(n * 99).div_ceil(100) - 1] as f64 / 1000.0,
"max_us": samples[n-1] as f64 / 1000.0,
"over_60hz_budget": samples.iter().filter(|&&v| v > 1_000_000_000 / 60).count()})
}
fn main() {
let count: usize =
std::env::args().nth(1).map(|v| v.parse().expect("frame count")).unwrap_or(600);
assert!(count > 0);
let (w, h) = (Hardware::W, Hardware::H);
let banks = Arc::new(MemoryBanks::new());
let mixed = std::env::args().nth(2).as_deref() == Some("mixed");
let sizes = if mixed {
[TileSize::Size8, TileSize::Size16, TileSize::Size32, TileSize::Size8]
} else {
[TileSize::Size16; 4]
};
for (i, size) in sizes.iter().enumerate() {
let edge = *size as usize;
let mut bank = GlyphBank::new(*size, edge, edge);
bank.palettes[0][1] = Color::rgba((i * 47 + 30) as u8, 120, 210, 255);
// Transparent holes make all four layers participate in the visible output.
for (p, pixel) in bank.pixel_indices.iter_mut().enumerate() {
*pixel = u8::from(i == 0 || (p + i) % 3 != 0);
}
banks.install_glyph_bank(i, Arc::new(bank));
}
let scene = SceneBank {
layers: std::array::from_fn(|i| SceneLayer {
active: true,
glyph_asset_id: i as i32,
tile_size: sizes[i],
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap {
width: 160,
height: 100,
tiles: vec![
Tile {
active: true,
glyph: Glyph { glyph_id: 0, palette_id: 0 },
flip_x: false,
flip_y: false,
};
160 * 100
],
},
}),
};
let min_tile = if mixed { 8 } else { 16 };
let (cw, ch) = (w.div_ceil(min_tile) + 5, h.div_ceil(min_tile) + 4);
let mut cache = SceneViewportCache::new(&scene, cw, ch);
let mut resolver = SceneViewportResolver::new(
w as i32,
h as i32,
cw,
ch,
min_tile as i32 - 4,
min_tile as i32 + 4,
);
let mut gfx = Gfx::new(w, h, banks);
let sprites: Vec<_> = (0..512)
.map(|i| Sprite {
glyph: Glyph { glyph_id: 0, palette_id: 0 },
x: ((i * 37) % w) as i32,
y: ((i * 53) % h) as i32,
layer: (i % 4) as u8,
bank_id: (i % 4) as u8,
active: true,
flip_x: i % 2 == 0,
flip_y: i % 3 == 0,
priority: (i % 4) as u8,
})
.collect();
gfx.load_frame_sprites(&sprites);
let mut compose = Vec::with_capacity(count);
let mut publish = Vec::with_capacity(count);
let mut upload = Vec::with_capacity(count);
let mut total = Vec::with_capacity(count);
let mut rgba = vec![0u8; w * h * 4];
let ownership = RenderOwnership::new(1, AppMode::Game, 1);
let mut checksum = 0u32;
for frame_id in 0..(count + 120) {
// Resolve/materialize cache outside the raster timing; total includes it.
let start = Instant::now();
let update = resolver.update(&scene, (frame_id % 71) as i32, (frame_id % 43) as i32);
for request in &update.copy_requests {
cache.move_layer_window_to(
request.layer_index,
request.cache_origin_tile_x,
request.cache_origin_tile_y,
);
}
cache.materialize_all_layers(&scene);
let t = Instant::now();
gfx.render_scene_from_cache(&cache, &update, &[0, 1, 2, 3]);
gfx.fill_rect(0, h as i32 - 8, w as i32, 8, Color::WHITE);
let raster = t.elapsed().as_nanos() as u64;
let t = Instant::now();
gfx.present();
let frame = OwnedRgba8888Frame::packed(
FrameId::new(frame_id as u64),
ownership,
w,
h,
gfx.front_buffer().to_vec(),
)
.unwrap();
let publication = t.elapsed().as_nanos() as u64;
let t = Instant::now();
for (pixel, bytes) in frame.pixels.iter().zip(rgba.as_chunks_mut::<4>().0.iter_mut()) {
bytes.copy_from_slice(&pixel.to_be_bytes());
}
std::hint::black_box(&rgba);
let staging = t.elapsed().as_nanos() as u64;
checksum ^= frame.pixels[(frame_id * 173) % (w * h)];
if frame_id >= 120 {
compose.push(raster);
publish.push(publication);
upload.push(staging);
total.push(start.elapsed().as_nanos() as u64);
}
}
let live = LIVE.load(Ordering::Relaxed);
let peak = PEAK.load(Ordering::Relaxed);
let allocations = ALLOCATIONS.load(Ordering::Relaxed);
println!(
"{}",
serde_json::json!({"schema":1,"width":w,"height":h,"frames":count,
"warmup_frames":120,"tiles":sizes.map(|s|s as u32),"sprites_accepted":512,"layers":4,
"framebuffer_bytes":w*h*4,"front_back_bytes":w*h*8,"host_staging_bytes":rgba.len(),
"compose":summary(&mut compose),"publish_owned":summary(&mut publish),
"rgba_staging":summary(&mut upload),"total":summary(&mut total),
"allocated_live_bytes":live,"allocated_peak_bytes":peak,"allocation_count":allocations,
"checksum":checksum,"vm_hz":null,"physical_display_hz":null,
"limitations":"unpaced controlled raster/cache/owned publication/staging; no VM, IPC or GPU present; allocator instrumented; RSS is measured by the process wrapper"})
);
}
+349 -258
View File
@@ -1,4 +1,7 @@
#![allow(clippy::collapsible_if)] #![allow(clippy::collapsible_if)]
mod decode;
mod resumable;
use crate::audio::bank_format::{DecodedAudioBank, decode_audio_bank};
use crate::memory_banks::{GlyphBankPoolInstaller, SceneBankPoolInstaller, SoundBankPoolInstaller}; use crate::memory_banks::{GlyphBankPoolInstaller, SceneBankPoolInstaller, SoundBankPoolInstaller};
use prometeu_hal::AssetBridge; use prometeu_hal::AssetBridge;
use prometeu_hal::asset::{ use prometeu_hal::asset::{
@@ -12,7 +15,7 @@ use prometeu_hal::cartridge::AssetsPayloadSource;
use prometeu_hal::color::Color; use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph; use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{GlyphBank, TileSize}; use prometeu_hal::glyph_bank::{GlyphBank, TileSize};
use prometeu_hal::sample::Sample; use prometeu_hal::music_bank::MusicBank;
use prometeu_hal::scene_bank::SceneBank; use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer}; use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::sound_bank::SoundBank; use prometeu_hal::sound_bank::SoundBank;
@@ -59,6 +62,7 @@ pub struct AssetPipelineTelemetry {
pub active_progress: u16, pub active_progress: u16,
pub glyph_latency: AssetLatencyPercentiles, pub glyph_latency: AssetLatencyPercentiles,
pub sound_latency: AssetLatencyPercentiles, pub sound_latency: AssetLatencyPercentiles,
pub music_latency: AssetLatencyPercentiles,
pub scene_latency: AssetLatencyPercentiles, pub scene_latency: AssetLatencyPercentiles,
pub last_asset_id: Option<AssetId>, pub last_asset_id: Option<AssetId>,
pub last_asset_latency: AssetLatencyPercentiles, pub last_asset_latency: AssetLatencyPercentiles,
@@ -128,6 +132,7 @@ impl AssetPipelineTelemetryState {
); );
self.snapshot.glyph_latency = percentile_snapshot(self.bank_samples.get(&BankType::GLYPH)); self.snapshot.glyph_latency = percentile_snapshot(self.bank_samples.get(&BankType::GLYPH));
self.snapshot.sound_latency = percentile_snapshot(self.bank_samples.get(&BankType::SOUNDS)); self.snapshot.sound_latency = percentile_snapshot(self.bank_samples.get(&BankType::SOUNDS));
self.snapshot.music_latency = percentile_snapshot(self.bank_samples.get(&BankType::MUSIC));
self.snapshot.scene_latency = percentile_snapshot(self.bank_samples.get(&BankType::SCENE)); self.snapshot.scene_latency = percentile_snapshot(self.bank_samples.get(&BankType::SCENE));
self.snapshot.last_asset_id = Some(asset_id); self.snapshot.last_asset_id = Some(asset_id);
self.snapshot.last_asset_latency = percentile_snapshot(self.asset_samples.get(&asset_id)); self.snapshot.last_asset_latency = percentile_snapshot(self.asset_samples.get(&asset_id));
@@ -327,12 +332,14 @@ pub struct AssetManager {
gfx_slots: Arc<RwLock<[Option<AssetId>; 16]>>, gfx_slots: Arc<RwLock<[Option<AssetId>; 16]>>,
glyph_slot_index: GlyphAssetSlotIndex, glyph_slot_index: GlyphAssetSlotIndex,
sound_slots: Arc<RwLock<[Option<AssetId>; 16]>>, sound_slots: Arc<RwLock<[Option<AssetId>; 16]>>,
music_slots: Arc<RwLock<[Option<AssetId>; 16]>>,
scene_slots: Arc<RwLock<[Option<AssetId>; 16]>>, scene_slots: Arc<RwLock<[Option<AssetId>; 16]>>,
/// Residency policy for GFX glyph banks. /// Residency policy for GFX glyph banks.
gfx_policy: BankPolicy<GlyphBank>, gfx_policy: BankPolicy<GlyphBank>,
/// Residency policy for sound banks. /// Residency policy for sound banks.
sound_policy: BankPolicy<SoundBank>, sound_policy: BankPolicy<SoundBank>,
music_policy: BankPolicy<MusicBank>,
/// Residency policy for scene banks. /// Residency policy for scene banks.
scene_policy: BankPolicy<SceneBank>, scene_policy: BankPolicy<SceneBank>,
@@ -340,6 +347,8 @@ pub struct AssetManager {
// Commits that are ready to be applied at the next frame boundary. // Commits that are ready to be applied at the next frame boundary.
pending_commits: Mutex<Vec<(HandleId, u64)>>, pending_commits: Mutex<Vec<(HandleId, u64)>>,
preload_handles: Mutex<Vec<HandleId>>,
preload_failed: std::sync::atomic::AtomicBool,
} }
struct LoadHandleInfo { struct LoadHandleInfo {
@@ -366,6 +375,7 @@ struct AssetLoadJobResources<'a> {
pipeline_telemetry: &'a Arc<Mutex<AssetPipelineTelemetryState>>, pipeline_telemetry: &'a Arc<Mutex<AssetPipelineTelemetryState>>,
gfx_policy: &'a BankPolicy<GlyphBank>, gfx_policy: &'a BankPolicy<GlyphBank>,
sound_policy: &'a BankPolicy<SoundBank>, sound_policy: &'a BankPolicy<SoundBank>,
music_policy: &'a BankPolicy<MusicBank>,
scene_policy: &'a BankPolicy<SceneBank>, scene_policy: &'a BankPolicy<SceneBank>,
} }
@@ -374,6 +384,7 @@ struct AssetLoadQueueState {
pending: VecDeque<AssetLoadJob>, pending: VecDeque<AssetLoadJob>,
active: Option<AssetLoadJob>, active: Option<AssetLoadJob>,
shutdown: bool, shutdown: bool,
scheduled: bool,
} }
#[derive(Default)] #[derive(Default)]
@@ -470,9 +481,11 @@ impl AssetLoadQueue {
struct AssetLoadWorker { struct AssetLoadWorker {
queue: Arc<AssetLoadQueue>, queue: Arc<AssetLoadQueue>,
join_handle: Option<thread::JoinHandle<()>>, join_handle: Option<thread::JoinHandle<()>>,
shared: Option<(Arc<dyn prometeu_hal::background_work::BackgroundWork>, resumable::Resources)>,
} }
impl AssetLoadWorker { impl AssetLoadWorker {
#[allow(clippy::too_many_arguments)]
fn new( fn new(
handles: Arc<RwLock<HandleTable>>, handles: Arc<RwLock<HandleTable>>,
target_generations: Arc<RwLock<TargetGenerationTable>>, target_generations: Arc<RwLock<TargetGenerationTable>>,
@@ -480,6 +493,7 @@ impl AssetLoadWorker {
pipeline_telemetry: Arc<Mutex<AssetPipelineTelemetryState>>, pipeline_telemetry: Arc<Mutex<AssetPipelineTelemetryState>>,
gfx_policy: BankPolicy<GlyphBank>, gfx_policy: BankPolicy<GlyphBank>,
sound_policy: BankPolicy<SoundBank>, sound_policy: BankPolicy<SoundBank>,
music_policy: BankPolicy<MusicBank>,
scene_policy: BankPolicy<SceneBank>, scene_policy: BankPolicy<SceneBank>,
) -> Self { ) -> Self {
let queue = Arc::new(AssetLoadQueue::default()); let queue = Arc::new(AssetLoadQueue::default());
@@ -492,6 +506,7 @@ impl AssetLoadWorker {
pipeline_telemetry: &pipeline_telemetry, pipeline_telemetry: &pipeline_telemetry,
gfx_policy: &gfx_policy, gfx_policy: &gfx_policy,
sound_policy: &sound_policy, sound_policy: &sound_policy,
music_policy: &music_policy,
scene_policy: &scene_policy, scene_policy: &scene_policy,
}; };
while let Some(job) = worker_queue.next_job() { while let Some(job) = worker_queue.next_job() {
@@ -500,11 +515,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 { 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) { fn clear_pending(&self) {
@@ -544,6 +563,28 @@ enum AssetOpMode {
} }
impl AssetBridge for AssetManager { impl AssetBridge for AssetManager {
fn unload_audio(&self, music: bool, slot: usize) -> AssetOpStatus {
self.unload_audio(music, slot)
}
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( fn initialize_for_cartridge(
&self, &self,
assets: Vec<AssetEntry>, assets: Vec<AssetEntry>,
@@ -552,6 +593,12 @@ impl AssetBridge for AssetManager {
) { ) {
self.initialize_for_cartridge(assets, preload, assets_data) 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> { fn load(&self, asset_id: AssetId, slot_index: usize) -> Result<HandleId, AssetLoadError> {
self.load(asset_id, slot_index) self.load(asset_id, slot_index)
} }
@@ -600,69 +647,21 @@ impl AssetManager {
fn decode_glyph_bank_layout( fn decode_glyph_bank_layout(
entry: &AssetEntry, entry: &AssetEntry,
) -> Result<(TileSize, usize, usize, usize, usize, usize), String> { ) -> Result<(TileSize, usize, usize, usize, usize, usize), String> {
let meta = entry.metadata_as_glyph_bank()?; decode::glyph_layout(entry)
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))
} }
fn unpack_glyph_bank_pixels(packed_pixels: &[u8], logical_pixels: usize) -> Vec<u8> { fn unpack_glyph_bank_pixels(packed_pixels: &[u8], logical_pixels: usize) -> Vec<u8> {
let mut pixel_indices = Vec::with_capacity(logical_pixels); let mut pixels = Vec::with_capacity(logical_pixels);
for &packed in packed_pixels { decode::append_pixels(&mut pixels, packed_pixels, logical_pixels);
if pixel_indices.len() < logical_pixels { pixels
pixel_indices.push(packed >> 4);
}
if pixel_indices.len() < logical_pixels {
pixel_indices.push(packed & 0x0f);
}
}
pixel_indices
} }
fn op_mode_for(entry: &AssetEntry) -> Result<AssetOpMode, String> { fn op_mode_for(entry: &AssetEntry) -> Result<AssetOpMode, String> {
match (entry.bank_type, entry.codec) { match (entry.bank_type, entry.codec) {
(BankType::GLYPH, AssetCodec::None) => Ok(AssetOpMode::StageInMemory), (BankType::GLYPH, AssetCodec::None) => Ok(AssetOpMode::StageInMemory),
(BankType::SOUNDS, AssetCodec::None) => Ok(AssetOpMode::DirectFromSlice), (BankType::SOUNDS, AssetCodec::None) | (BankType::MUSIC, AssetCodec::None) => {
Ok(AssetOpMode::DirectFromSlice)
}
(BankType::SCENE, AssetCodec::None) => Ok(AssetOpMode::DirectFromSlice), (BankType::SCENE, AssetCodec::None) => Ok(AssetOpMode::DirectFromSlice),
} }
} }
@@ -685,6 +684,7 @@ impl AssetManager {
let pipeline_telemetry = Arc::new(Mutex::new(AssetPipelineTelemetryState::default())); let pipeline_telemetry = Arc::new(Mutex::new(AssetPipelineTelemetryState::default()));
let gfx_policy = BankPolicy::new(); let gfx_policy = BankPolicy::new();
let sound_policy = BankPolicy::new(); let sound_policy = BankPolicy::new();
let music_policy = BankPolicy::new();
let scene_policy = BankPolicy::new(); let scene_policy = BankPolicy::new();
let load_worker = AssetLoadWorker::new( let load_worker = AssetLoadWorker::new(
Arc::clone(&handles), Arc::clone(&handles),
@@ -693,6 +693,7 @@ impl AssetManager {
Arc::clone(&pipeline_telemetry), Arc::clone(&pipeline_telemetry),
gfx_policy.clone(), gfx_policy.clone(),
sound_policy.clone(), sound_policy.clone(),
music_policy.clone(),
scene_policy.clone(), scene_policy.clone(),
); );
@@ -704,9 +705,11 @@ impl AssetManager {
gfx_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), gfx_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
glyph_slot_index: GlyphAssetSlotIndex::new(), glyph_slot_index: GlyphAssetSlotIndex::new(),
sound_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), sound_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
music_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
scene_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), scene_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
gfx_policy, gfx_policy,
sound_policy, sound_policy,
music_policy,
scene_policy, scene_policy,
handles, handles,
target_handles: Arc::new(RwLock::new(HashMap::new())), target_handles: Arc::new(RwLock::new(HashMap::new())),
@@ -716,6 +719,8 @@ impl AssetManager {
pipeline_telemetry, pipeline_telemetry,
load_worker, load_worker,
pending_commits: Mutex::new(Vec::new()), pending_commits: Mutex::new(Vec::new()),
preload_handles: Mutex::new(Vec::new()),
preload_failed: std::sync::atomic::AtomicBool::new(false),
} }
} }
@@ -735,7 +740,16 @@ impl AssetManager {
} }
*self.assets_data.write().unwrap() = assets_data; *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 { for item in preload {
let entry_opt = { let entry_opt = {
let assets = self.assets.read().unwrap(); let assets = self.assets.read().unwrap();
@@ -780,6 +794,23 @@ impl AssetManager {
} }
} }
} }
BankType::MUSIC => {
if let Ok(bank) =
Self::perform_load_music_bank(&entry, self.assets_data.clone())
{
let bank_arc = Arc::new(bank);
self.music_policy.put_resident(
entry.asset_id,
Arc::clone(&bank_arc),
entry.decoded_size as usize,
);
self.sound_installer.install_music_bank(slot_index, bank_arc);
let mut slots = self.music_slots.write().unwrap();
if slot_index < slots.len() {
slots[slot_index] = Some(entry.asset_id);
}
}
}
BankType::SCENE => { BankType::SCENE => {
if let Ok(bank) = if let Ok(bank) =
Self::perform_load_scene_bank(&entry, self.assets_data.clone()) Self::perform_load_scene_bank(&entry, self.assets_data.clone())
@@ -844,6 +875,7 @@ impl AssetManager {
fn clear_staging_for_handle(&self, handle_id: HandleId) { fn clear_staging_for_handle(&self, handle_id: HandleId) {
self.gfx_policy.take_staging(handle_id); self.gfx_policy.take_staging(handle_id);
self.sound_policy.take_staging(handle_id); self.sound_policy.take_staging(handle_id);
self.music_policy.take_staging(handle_id);
self.scene_policy.take_staging(handle_id); self.scene_policy.take_staging(handle_id);
} }
@@ -859,6 +891,7 @@ impl AssetManager {
match slot.asset_type { match slot.asset_type {
BankType::GLYPH => self.gfx_slots.read().unwrap().get(slot.index).and_then(|s| *s), BankType::GLYPH => self.gfx_slots.read().unwrap().get(slot.index).and_then(|s| *s),
BankType::SOUNDS => self.sound_slots.read().unwrap().get(slot.index).and_then(|s| *s), BankType::SOUNDS => self.sound_slots.read().unwrap().get(slot.index).and_then(|s| *s),
BankType::MUSIC => self.music_slots.read().unwrap().get(slot.index).and_then(|s| *s),
BankType::SCENE => self.scene_slots.read().unwrap().get(slot.index).and_then(|s| *s), BankType::SCENE => self.scene_slots.read().unwrap().get(slot.index).and_then(|s| *s),
} }
} }
@@ -878,6 +911,7 @@ impl AssetManager {
let slot = match entry.bank_type { let slot = match entry.bank_type {
BankType::GLYPH => SlotRef::gfx(slot_index), BankType::GLYPH => SlotRef::gfx(slot_index),
BankType::SOUNDS => SlotRef::audio(slot_index), BankType::SOUNDS => SlotRef::audio(slot_index),
BankType::MUSIC => SlotRef::music(slot_index),
BankType::SCENE => SlotRef::scene(slot_index), BankType::SCENE => SlotRef::scene(slot_index),
}; };
@@ -903,6 +937,14 @@ impl AssetManager {
false false
} }
} }
BankType::MUSIC => {
if let Some(bank) = self.music_policy.get_resident(asset_id) {
self.music_policy.stage(handle_id, bank, entry.decoded_size as usize);
true
} else {
false
}
}
BankType::SCENE => { BankType::SCENE => {
if let Some(bank) = self.scene_policy.get_resident(asset_id) { if let Some(bank) = self.scene_policy.get_resident(asset_id) {
self.scene_policy.stage(handle_id, bank, entry.decoded_size as usize); self.scene_policy.stage(handle_id, bank, entry.decoded_size as usize);
@@ -1085,6 +1127,57 @@ impl AssetManager {
} }
} }
} }
BankType::MUSIC => {
let result =
Self::perform_load_music_bank(&job.entry, Arc::clone(resources.assets_data));
match result {
Ok(musicbank) => {
if !Self::is_current_target_generation(
resources.target_generations,
job.slot,
job.request_generation,
) {
resources.pipeline_telemetry.lock().unwrap().record_stale_discard();
return;
}
let bank_arc = Arc::new(musicbank);
let resident_arc = resources.music_policy.put_resident(
job.asset_id,
bank_arc,
job.entry.decoded_size as usize,
);
if !Self::is_current_target_generation(
resources.target_generations,
job.slot,
job.request_generation,
) {
resources.pipeline_telemetry.lock().unwrap().record_stale_discard();
return;
}
resources.music_policy.stage(
job.handle_id,
resident_arc,
job.entry.decoded_size as usize,
);
Self::complete_load_job(resources.handles, &job, LoadStatus::READY);
Self::record_load_job_finished(
resources.pipeline_telemetry,
&job,
started_at,
LoadStatus::READY,
);
}
Err(_) => {
Self::complete_load_job(resources.handles, &job, LoadStatus::ERROR);
Self::record_load_job_finished(
resources.pipeline_telemetry,
&job,
started_at,
LoadStatus::ERROR,
);
}
}
}
BankType::SCENE => { BankType::SCENE => {
let result = let result =
Self::perform_load_scene_bank(&job.entry, Arc::clone(resources.assets_data)); Self::perform_load_scene_bank(&job.entry, Arc::clone(resources.assets_data));
@@ -1213,22 +1306,10 @@ impl AssetManager {
let logical_pixels = width * height; let logical_pixels = width * height;
let packed_pixels = &buffer[0..packed_pixel_bytes]; let packed_pixels = &buffer[0..packed_pixel_bytes];
let pixel_indices = Self::unpack_glyph_bank_pixels(packed_pixels, logical_pixels); let pixel_indices = Self::unpack_glyph_bank_pixels(packed_pixels, logical_pixels);
let palette_data = let palette_data = &buffer[packed_pixel_bytes..packed_pixel_bytes + palette_bytes];
&buffer[packed_pixel_bytes..packed_pixel_bytes + palette_bytes];
let mut palettes = let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count]; decode::write_palettes(&mut palettes, 0, palette_data);
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],
);
}
}
Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes }) Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes })
} }
@@ -1252,19 +1333,8 @@ impl AssetManager {
.read_exact(&mut palette_data) .read_exact(&mut palette_data)
.map_err(|_| "Buffer too small for GLYPHBANK".to_string())?; .map_err(|_| "Buffer too small for GLYPHBANK".to_string())?;
let mut palettes = let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count]; decode::write_palettes(&mut palettes, 0, &palette_data);
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],
);
}
}
Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes }) Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes })
} }
@@ -1295,11 +1365,37 @@ impl AssetManager {
} }
} }
fn perform_load_music_bank(
entry: &AssetEntry,
assets_data: Arc<RwLock<AssetsPayloadSource>>,
) -> Result<MusicBank, String> {
let op_mode = Self::op_mode_for(entry)?;
let slice = {
let assets_data = assets_data.read().unwrap();
assets_data
.open_slice(entry.offset, entry.size)
.map_err(|_| "Asset offset/size out of bounds".to_string())?
};
match op_mode {
AssetOpMode::DirectFromSlice => {
let mut reader =
slice.open_reader().map_err(|_| "Asset payload read failed".to_string())?;
Self::decode_music_bank_from_reader(entry, &mut reader)
}
AssetOpMode::StageInMemory => {
let buffer =
slice.read_all().map_err(|_| "Asset payload read failed".to_string())?;
Self::decode_music_bank_from_buffer(entry, &buffer)
}
}
}
fn perform_load_scene_bank( fn perform_load_scene_bank(
entry: &AssetEntry, entry: &AssetEntry,
assets_data: Arc<RwLock<AssetsPayloadSource>>, assets_data: Arc<RwLock<AssetsPayloadSource>>,
) -> Result<SceneBank, String> { ) -> Result<SceneBank, String> {
let _ = entry.metadata_as_scene_bank()?; decode::scene_metadata(entry)?;
let op_mode = Self::op_mode_for(entry)?; let op_mode = Self::op_mode_for(entry)?;
let slice = { let slice = {
let assets_data = assets_data.read().unwrap(); let assets_data = assets_data.read().unwrap();
@@ -1326,152 +1422,25 @@ impl AssetManager {
entry: &AssetEntry, entry: &AssetEntry,
buffer: &[u8], buffer: &[u8],
) -> Result<SceneBank, String> { ) -> Result<SceneBank, String> {
let _ = entry.metadata_as_scene_bank()?; decode::scene_metadata(entry)?;
decode::payload_size(entry, buffer.len())?;
if buffer.len() < SCENE_HEADER_BYTES_V1 { decode::scene_header(buffer)?;
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));
}
let mut offset = SCENE_HEADER_BYTES_V1; let mut offset = SCENE_HEADER_BYTES_V1;
let mut decoded_size = 0_usize; let mut decoded = 0;
let layers = std::array::from_fn(|_| SceneLayer { let mut layers = decode::empty_layers();
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;
for layer in &mut layers { for layer in &mut layers {
let header_end = offset let end = offset
.checked_add(SCENE_LAYER_HEADER_BYTES_V1) .checked_add(SCENE_LAYER_HEADER_BYTES_V1)
.ok_or("SCENE layer header offset overflow")?; .ok_or("SCENE header offset overflow")?;
if header_end > buffer.len() { let header =
return Err("Buffer too small for SCENE layer header".to_string()); 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 =
let flags = buffer[offset]; layer.tilemap.width * layer.tilemap.height * SCENE_TILE_RECORD_BYTES_V1;
let glyph_asset_id = i32::from_le_bytes([ offset = end + tile_bytes; // checked by scene_layer before allocation
buffer[offset + 1], decode::append_tiles(&mut layer.tilemap.tiles, &buffer[end..offset]);
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 },
};
} }
decode::scene_finish(entry, offset, decoded)?;
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
));
}
Ok(SceneBank { layers }) Ok(SceneBank { layers })
} }
@@ -1488,18 +1457,32 @@ impl AssetManager {
entry: &AssetEntry, entry: &AssetEntry,
buffer: &[u8], buffer: &[u8],
) -> Result<SoundBank, String> { ) -> Result<SoundBank, String> {
let meta = entry.metadata_as_sound_bank()?; decode::payload_size(entry, buffer.len())?;
let sample_rate = meta.sample_rate; let bank = decode_audio_bank(buffer, false)?;
if bank.decoded_size() as u64 != entry.decoded_size {
let mut data = Vec::with_capacity(buffer.len() / 2); return Err("audio decoded_size mismatch".into());
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]]));
}
} }
if let DecodedAudioBank::Sound(bank) = bank {
Ok(bank)
} else {
Err("audio bank type mismatch".into())
}
}
let sample = Arc::new(Sample::new(sample_rate, data)); fn decode_music_bank_from_buffer(
Ok(SoundBank::new(vec![sample])) entry: &AssetEntry,
buffer: &[u8],
) -> Result<MusicBank, String> {
decode::payload_size(entry, buffer.len())?;
let bank = decode_audio_bank(buffer, true)?;
if bank.decoded_size() as u64 != entry.decoded_size {
return Err("audio decoded_size mismatch".into());
}
if let DecodedAudioBank::Music(bank) = bank {
Ok(bank)
} else {
Err("audio bank type mismatch".into())
}
} }
fn decode_sound_bank_from_reader( fn decode_sound_bank_from_reader(
@@ -1511,6 +1494,15 @@ impl AssetManager {
Self::decode_sound_bank_from_buffer(entry, &raw) Self::decode_sound_bank_from_buffer(entry, &raw)
} }
fn decode_music_bank_from_reader(
entry: &AssetEntry,
reader: &mut impl Read,
) -> Result<MusicBank, String> {
let mut raw = Vec::new();
reader.read_to_end(&mut raw).map_err(|_| "Asset payload read failed".to_string())?;
Self::decode_music_bank_from_buffer(entry, &raw)
}
pub fn status(&self, handle: HandleId) -> LoadStatus { pub fn status(&self, handle: HandleId) -> LoadStatus {
if let Some(status) = self.handles.read().unwrap().get(&handle).map(|h| h.status) { if let Some(status) = self.handles.read().unwrap().get(&handle).map(|h| h.status) {
return status; return status;
@@ -1639,6 +1631,7 @@ impl AssetManager {
let slot_ref = match bank_type { let slot_ref = match bank_type {
BankType::GLYPH => SlotRef::gfx(slot), BankType::GLYPH => SlotRef::gfx(slot),
BankType::SOUNDS => SlotRef::audio(slot), BankType::SOUNDS => SlotRef::audio(slot),
BankType::MUSIC => SlotRef::music(slot),
BankType::SCENE => SlotRef::scene(slot), BankType::SCENE => SlotRef::scene(slot),
}; };
let handle = self.handle_for_slot(slot_ref); let handle = self.handle_for_slot(slot_ref);
@@ -1713,6 +1706,19 @@ impl AssetManager {
} }
pub fn apply_commits(&self) { 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 pending = self.pending_commits.lock().unwrap();
let mut handles = self.handles.write().unwrap(); let mut handles = self.handles.write().unwrap();
@@ -1741,6 +1747,16 @@ impl AssetManager {
h.status = LoadStatus::COMMITTED; h.status = LoadStatus::COMMITTED;
} }
} }
BankType::MUSIC => {
if let Some((bank, _)) = self.music_policy.take_staging(handle_id) {
self.sound_installer.install_music_bank(h.slot.index, bank);
let mut slots = self.music_slots.write().unwrap();
if h.slot.index < slots.len() {
slots[h.slot.index] = Some(h._asset_id);
}
h.status = LoadStatus::COMMITTED;
}
}
BankType::SCENE => { BankType::SCENE => {
if let Some((bank, _)) = self.scene_policy.take_staging(handle_id) { if let Some((bank, _)) = self.scene_policy.take_staging(handle_id) {
self.scene_installer.install_scene_bank(h.slot.index, bank); self.scene_installer.install_scene_bank(h.slot.index, bank);
@@ -1755,12 +1771,57 @@ impl AssetManager {
} }
} }
} }
self.reap_audio_cache();
}
fn reap_audio_cache(&self) {
fn reap<T>(policy: &BankPolicy<T>, slots: &[Option<AssetId>; 16]) {
let mut resident = policy.resident.write().unwrap();
resident.retain(|id, entry| {
let keep = slots.contains(&Some(*id)) || Arc::strong_count(&entry.value) > 1;
if !keep {
policy.used_bytes.fetch_sub(entry.bytes, Ordering::Relaxed);
}
keep
});
}
reap(&self.sound_policy, &self.sound_slots.read().unwrap());
reap(&self.music_policy, &self.music_slots.read().unwrap());
}
pub fn unload_audio(&self, music: bool, slot: usize) -> AssetOpStatus {
if slot >= 16 {
return AssetOpStatus::InvalidState;
}
let target = if music { SlotRef::music(slot) } else { SlotRef::audio(slot) };
self.bump_target_generation(target);
if let Some(handle) = self.target_handles.read().unwrap().get(&target).copied() {
self.clear_staging_for_handle(handle);
if let Some(h) = self.handles.write().unwrap().get_mut(&handle) {
h.status = LoadStatus::CANCELED;
}
}
let slots = if music { &self.music_slots } else { &self.sound_slots };
let mut ids = slots.write().unwrap();
let previous = ids[slot].take();
self.sound_installer.unload_audio_bank(music, slot);
if let Some(id) = previous.filter(|id| !ids.contains(&Some(*id))) {
if music {
if let Some(old) = self.music_policy.resident.write().unwrap().remove(&id) {
self.music_policy.used_bytes.fetch_sub(old.bytes, Ordering::Relaxed);
}
} else if let Some(old) = self.sound_policy.resident.write().unwrap().remove(&id) {
self.sound_policy.used_bytes.fetch_sub(old.bytes, Ordering::Relaxed);
}
}
AssetOpStatus::Ok
} }
pub fn bank_telemetry(&self) -> Vec<BankTelemetry> { pub fn bank_telemetry(&self) -> Vec<BankTelemetry> {
vec![ vec![
self.bank_telemetry_for(BankType::GLYPH), self.bank_telemetry_for(BankType::GLYPH),
self.bank_telemetry_for(BankType::SOUNDS), self.bank_telemetry_for(BankType::SOUNDS),
self.bank_telemetry_for(BankType::MUSIC),
self.bank_telemetry_for(BankType::SCENE), self.bank_telemetry_for(BankType::SCENE),
] ]
} }
@@ -1773,6 +1834,9 @@ impl AssetManager {
BankType::SOUNDS => { BankType::SOUNDS => {
self.sound_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count() self.sound_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count()
} }
BankType::MUSIC => {
self.music_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count()
}
BankType::SCENE => { BankType::SCENE => {
self.scene_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count() self.scene_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count()
} }
@@ -1825,6 +1889,27 @@ impl AssetManager {
SlotStats { asset_id, asset_name, generation: 0, resident_bytes: bytes } SlotStats { asset_id, asset_name, generation: 0, resident_bytes: bytes }
} }
BankType::MUSIC => {
let slots = self.music_slots.read().unwrap();
let asset_id = slots.get(slot.index).and_then(|s| *s);
let (bytes, asset_name) = if let Some(id) = &asset_id {
let bytes = self
.music_policy
.resident
.read()
.unwrap()
.get(id)
.map(|entry| entry.bytes)
.unwrap_or(0);
let name = self.assets.read().unwrap().get(id).map(|e| e.asset_name.clone());
(bytes, name)
} else {
(0, None)
};
SlotStats { asset_id, asset_name, generation: 0, resident_bytes: bytes }
}
BankType::SCENE => { BankType::SCENE => {
let slots = self.scene_slots.read().unwrap(); let slots = self.scene_slots.read().unwrap();
let asset_id = slots.get(slot.index).and_then(|s| *s); let asset_id = slots.get(slot.index).and_then(|s| *s);
@@ -1850,22 +1935,29 @@ impl AssetManager {
} }
pub fn shutdown(&self) { 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.gfx_policy.clear();
self.sound_policy.clear(); self.sound_policy.clear();
self.music_policy.clear();
self.scene_policy.clear(); self.scene_policy.clear();
self.handles.write().unwrap().clear(); self.handles.write().unwrap().clear();
self.target_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.load_worker.clear_pending();
self.pending_commits.lock().unwrap().clear(); 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.gfx_slots.write().unwrap().fill(None);
self.glyph_slot_index.clear(); self.glyph_slot_index.clear();
self.sound_slots.write().unwrap().fill(None); self.sound_slots.write().unwrap().fill(None);
self.music_slots.write().unwrap().fill(None);
self.scene_slots.write().unwrap().fill(None); self.scene_slots.write().unwrap().fill(None);
self.gfx_installer.clear_glyph_banks(); self.gfx_installer.clear_glyph_banks();
self.sound_installer.clear_sound_banks(); self.sound_installer.clear_sound_banks();
self.sound_installer.clear_music_banks();
self.scene_installer.clear_scene_banks(); self.scene_installer.clear_scene_banks();
} }
@@ -1903,10 +1995,7 @@ mod tests {
fn test_glyph_asset_data_with_palette_count(palette_count: usize) -> Vec<u8> { fn test_glyph_asset_data_with_palette_count(palette_count: usize) -> Vec<u8> {
let mut data = vec![0x11u8; 128]; let mut data = vec![0x11u8; 128];
data.extend_from_slice(&vec![ data.extend_from_slice(&vec![0u8; palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE]);
0u8;
palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE
]);
data data
} }
@@ -1943,7 +2032,7 @@ mod tests {
} }
} }
fn test_scene() -> SceneBank { pub(super) fn test_scene() -> SceneBank {
let make_layer = |glyph_asset_id: AssetId, let make_layer = |glyph_asset_id: AssetId,
active: bool, active: bool,
parallax_x: f32, parallax_x: f32,
@@ -2006,7 +2095,7 @@ mod tests {
.sum() .sum()
} }
fn encode_scene_payload(scene: &SceneBank) -> Vec<u8> { pub(super) fn encode_scene_payload(scene: &SceneBank) -> Vec<u8> {
let mut data = Vec::new(); let mut data = Vec::new();
data.extend_from_slice(&SCENE_PAYLOAD_MAGIC_V1); data.extend_from_slice(&SCENE_PAYLOAD_MAGIC_V1);
data.extend_from_slice(&SCENE_PAYLOAD_VERSION_V1.to_le_bytes()); data.extend_from_slice(&SCENE_PAYLOAD_VERSION_V1.to_le_bytes());
@@ -2046,7 +2135,11 @@ mod tests {
data 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 { AssetEntry {
asset_id: 2, asset_id: 2,
asset_name: asset_name.to_string(), asset_name: asset_name.to_string(),
@@ -2109,8 +2202,8 @@ mod tests {
let from_buffer = let from_buffer =
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("buffer decode"); AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("buffer decode");
let mut reader = std::io::Cursor::new(data); let mut reader = std::io::Cursor::new(data);
let from_reader = let from_reader = AssetManager::decode_glyph_bank_from_reader(&entry, &mut reader)
AssetManager::decode_glyph_bank_from_reader(&entry, &mut reader).expect("reader decode"); .expect("reader decode");
assert_eq!(from_buffer.palette_count(), from_reader.palette_count()); assert_eq!(from_buffer.palette_count(), from_reader.palette_count());
assert_eq!(from_buffer.pixel_indices, from_reader.pixel_indices); assert_eq!(from_buffer.pixel_indices, from_reader.pixel_indices);
@@ -2120,10 +2213,8 @@ mod tests {
#[test] #[test]
fn test_decode_glyph_bank_rejects_short_packed_buffer() { fn test_decode_glyph_bank_rejects_short_packed_buffer() {
let entry = test_glyph_asset_entry("glyphs", 16, 16); let entry = test_glyph_asset_entry("glyphs", 16, 16);
let data = vec![ let data =
0u8; vec![0u8; expected_glyph_payload_size(16, 16, GLYPH_BANK_MAX_PALETTE_COUNT_V1) - 1];
expected_glyph_payload_size(16, 16, GLYPH_BANK_MAX_PALETTE_COUNT_V1) - 1
];
let err = match AssetManager::decode_glyph_bank_from_buffer(&entry, &data) { let err = match AssetManager::decode_glyph_bank_from_buffer(&entry, &data) {
Ok(_) => panic!("glyph decode should reject short buffer"), Ok(_) => panic!("glyph decode should reject short buffer"),
@@ -2655,7 +2746,7 @@ mod tests {
let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>; let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>;
// 100 samples of 16-bit PCM (zeros) // 100 samples of 16-bit PCM (zeros)
let data = vec![0u8; 200]; let data = crate::bank_format::test_pcm_bank(&[0u8; 200], 44100);
let asset_entry = AssetEntry { let asset_entry = AssetEntry {
asset_id: 1, asset_id: 1,
@@ -2701,7 +2792,7 @@ mod tests {
let sound_installer = Arc::clone(&banks) as Arc<dyn SoundBankPoolInstaller>; let sound_installer = Arc::clone(&banks) as Arc<dyn SoundBankPoolInstaller>;
let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>; let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>;
let data = vec![0u8; 200]; let data = crate::bank_format::test_pcm_bank(&[0u8; 200], 44100);
let asset_entry = AssetEntry { let asset_entry = AssetEntry {
asset_id: 2, asset_id: 2,
@@ -0,0 +1,180 @@
//! 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 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,461 @@
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_validate_all_declared_frames_and_reject_odd_tails() {
for len in [0, 1, 2, 3, 4095, 4096, 4097, 8191, 8192, 8193] {
let raw: Vec<u8> = (0..len).map(|i| if i % 2 == 0 { 0x34 } else { 0x12 }).collect();
let bytes = crate::bank_format::test_pcm_bank(&raw, 44100);
let expected = if len % 2 == 0 {
Some(json!([[vec![0x1234_i16; len / 2], 44100, null, null]]))
} else {
None
};
check_case("pcm-chunk", &pcm_entry(bytes.len() as u64), bytes, expected);
}
}
#[test]
fn physically_truncated_pcm_file_is_rejected_by_all_modes() {
let bytes = crate::bank_format::test_pcm_bank(&[0x34, 0x12], 44100);
let entry = pcm_entry(bytes.len() as u64);
let fixture = FileFixture::new("truncated-pcm", &bytes[..bytes.len() - 1]);
let source = fixture.source(bytes.len() as u64);
assert!(AssetManager::perform_load_sound_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).is_err());
std::fs::write(&fixture.0, &bytes).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).unwrap()),
expected
);
}
#[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::MUSIC => AssetManager::perform_load_music_bank(entry, source.clone())
.map(|b| music_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::MUSIC, _) => AssetManager::decode_music_bank_from_buffer(entry, &bytes)
.map(|b| music_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_descriptor_and_source_range_corpus() {
let bytes = crate::bank_format::test_pcm_bank(&[0x34, 0x12], 44100);
let entry = pcm_entry(bytes.len() as u64);
// Audio metadata lives in the versioned payload, so it can vary per sample.
for (offset, value) in
[(48, 99u32), (49, 0), (52, 0), (56, 2), (60, 1), (68, 0), (72, 3), (84, 0)]
{
let mut invalid = bytes.clone();
if offset == 48 || offset == 49 {
invalid[offset] = value as u8;
} else {
invalid[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
}
check_case("descriptor", &entry, invalid, None);
}
for offset in [1, u64::MAX] {
let mut invalid = entry.clone();
invalid.offset = offset;
check_case("source-range", &invalid, bytes.clone(), None);
}
let mut invalid = entry;
invalid.decoded_size += 1;
check_case("decoded-size", &invalid, bytes, 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);
}
pub(in crate::asset) fn music_snapshot(bank: &prometeu_hal::music_bank::MusicBank) -> Value {
json!({"name": bank.name, "events": bank.events.len(), "pcm": bank.metrics.pcm_bytes})
}
#[test]
fn mixed_audio_fixtures_conform_across_all_asset_decode_modes() {
for (music, bytes) in [
(
false,
&include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-sound.sbnk"
))[..],
),
(
true,
&include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-music.mbnk"
))[..],
),
] {
let decoded = crate::bank_format::decode_audio_bank(bytes, music).unwrap();
let size = decoded.decoded_size();
let expected = match decoded {
DecodedAudioBank::Sound(b) => sound_snapshot(&b),
DecodedAudioBank::Music(b) => music_snapshot(&b),
};
let entry = AssetEntry {
asset_id: 7,
asset_name: "mixed".into(),
bank_type: if music { BankType::MUSIC } else { BankType::SOUNDS },
offset: 0,
size: bytes.len() as u64,
decoded_size: size as u64,
codec: AssetCodec::None,
metadata: json!({"version":1}),
};
check_case("mixed-audio", &entry, bytes.to_vec(), Some(expected));
let mut invalid = bytes.to_vec();
invalid[0] = 0;
check_case("mixed-bad-magic", &entry, invalid, None);
}
}
@@ -0,0 +1,612 @@
//! 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>,
music: BankPolicy<MusicBank>,
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(),
music: m.music_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::Music(bank) => {
let resident = resources.music.put_resident(
job.asset_id,
Arc::new(bank),
job.entry.decoded_size as usize,
);
resources.music.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),
Music(MusicBank),
Scene(SceneBank),
}
enum State {
Glyph {
bank: GlyphBank,
packed: usize,
position: usize,
palette_bytes: usize,
palette_position: usize,
},
Sound {
raw: Vec<u8>,
remaining: usize,
music: bool,
},
Audio(Box<crate::bank_format::AudioBankMaterializer<'static>>),
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 | BankType::MUSIC => {
let mut raw = Vec::new();
raw.try_reserve_exact(
usize::try_from(entry.size).map_err(|_| "audio size overflow")?,
)
.map_err(|_| "audio allocation failed")?;
State::Sound {
raw,
remaining: entry.size as usize,
music: entry.bank_type == BankType::MUSIC,
}
}
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 { raw, remaining, music } => {
if *remaining > 0 {
let n = (*remaining).min(4096);
let mut buffer = [0; 4096];
self.reader.read_exact(&mut buffer[..n]).map_err(|e| e.to_string())?;
raw.extend_from_slice(&buffer[..n]);
*remaining -= n;
return Ok(None);
}
let decoder = crate::bank_format::AudioBankMaterializer::new(
std::borrow::Cow::Owned(std::mem::take(raw)),
*music,
)?;
self.state = State::Audio(Box::new(decoder));
Ok(None)
}
State::Audio(decoder) => {
let Some(bank) = decoder.step()? else {
return Ok(None);
};
if bank.decoded_size() as u64 != self.entry.decoded_size {
return Err("audio decoded_size mismatch".into());
}
self.state = State::Done;
Ok(Some(match bank {
DecodedAudioBank::Sound(b) => Decoded::Sound(b),
DecodedAudioBank::Music(b) => Decoded::Music(b),
}))
}
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),
Decoded::Music(bank) => super::decode::tests::music_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_audio_bank_and_scene_use_canonical_formats() {
let pcm: Vec<i16> = (0..5000).map(|n| n as i16 - 2500).collect();
let bytes = crate::bank_format::test_pcm_bank(
&pcm.iter().flat_map(|n| n.to_le_bytes()).collect::<Vec<_>>(),
44100,
);
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 = crate::bank_format::test_pcm_bank(&[0; 8192], 44100);
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 = crate::bank_format::test_pcm_bank(&[0x12; 16384], 44100);
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]);
}
}
+373 -175
View File
@@ -1,8 +1,14 @@
use prometeu_hal::{AudioBridge, AudioOpStatus}; use prometeu_hal::music_bank::MusicBank;
use prometeu_hal::{AudioBridge, AudioOpStatus, audio_bridge::AudioControl};
use std::sync::Arc; use std::sync::Arc;
use std::sync::atomic::AtomicBool;
pub mod bank_format;
/// Maximum number of simultaneous audio voices supported by the hardware. /// Maximum number of simultaneous audio voices supported by the hardware.
pub const MAX_CHANNELS: usize = 16; pub const MAX_CHANNELS: usize = 32;
pub const SFX_CHANNELS: usize = 8;
pub const SFX_START: usize = 24;
pub mod engine;
/// Standard sample rate for the final audio output. /// Standard sample rate for the final audio output.
pub const OUTPUT_SAMPLE_RATE: u32 = 48000; pub const OUTPUT_SAMPLE_RATE: u32 = 48000;
@@ -13,24 +19,24 @@ use prometeu_hal::sample::Sample;
/// State of a single playback voice (channel). /// State of a single playback voice (channel).
/// ///
/// The Core maintains this state to provide information to the App (e.g., is_playing), /// This state belongs exclusively to the mixer, which observes natural completion.
/// but the actual real-time mixing is performed by the Host using commands.
pub struct Channel { pub struct Channel {
/// The actual sample data being played. /// The actual sample data being played.
pub sample: Option<Arc<Sample>>, pub sample: Option<Arc<Sample>>,
/// Whether this channel is currently active. /// Whether this channel is currently active.
pub active: bool, pub active: bool,
pub alive: Option<Arc<AtomicBool>>,
/// Current playback position within the sample (fractional for pitch shifting). /// Current playback position within the sample (fractional for pitch shifting).
pub pos: f64, pub pos: f64,
/// Playback speed multiplier (1.0 = original speed). /// Playback speed multiplier (1.0 = original speed).
pub pitch: f64, pub pitch: f64,
/// Voice volume (0-255). /// Voice volume (0-255).
pub volume: u8, pub volume: u8,
/// Stereo panning (0=Full Left, 127=Center, 255=Full Right). /// Stereo panning (0=Full Left, 128=Center, 255=Full Right).
pub pan: u8, pub pan: u8,
/// Loop configuration for this voice. /// Loop configuration for this voice.
pub loop_mode: LoopMode, pub loop_mode: LoopMode,
/// Playback priority (used for voice stealing policies). /// Internal priority metadata; the guest explicitly selects its voice.
pub priority: u8, pub priority: u8,
} }
@@ -39,10 +45,11 @@ impl Default for Channel {
Self { Self {
sample: None, sample: None,
active: false, active: false,
alive: None,
pos: 0.0, pos: 0.0,
pitch: 1.0, pitch: 1.0,
volume: 255, volume: 255,
pan: 127, pan: 128,
loop_mode: LoopMode::Off, loop_mode: LoopMode::Off,
priority: 0, priority: 0,
} }
@@ -54,9 +61,16 @@ impl Default for Channel {
/// Because the Core logic runs at 60Hz and Audio is generated at 48kHz, /// Because the Core logic runs at 60Hz and Audio is generated at 48kHz,
/// we use an asynchronous command queue to synchronize them. /// we use an asynchronous command queue to synchronize them.
pub enum AudioCommand { pub enum AudioCommand {
MusicPlay {
group: usize,
bank: Arc<MusicBank>,
looping: bool,
},
Control(AudioControl),
/// Start playing a sample on a specific voice. /// Start playing a sample on a specific voice.
Play { Play {
sample: Arc<Sample>, sample: Arc<Sample>,
alive: Option<Arc<AtomicBool>>,
voice_id: usize, voice_id: usize,
volume: u8, volume: u8,
pan: u8, pan: u8,
@@ -64,44 +78,84 @@ pub enum AudioCommand {
priority: u8, priority: u8,
loop_mode: LoopMode, loop_mode: LoopMode,
}, },
/// Immediately stop playback on a voice. /// Stop playback on a voice when this command is applied.
Stop { voice_id: usize }, Stop {
voice_id: usize,
},
/// Update volume of an ongoing playback. /// Update volume of an ongoing playback.
SetVolume { voice_id: usize, volume: u8 }, SetVolume {
voice_id: usize,
volume: u8,
},
/// Update panning of an ongoing playback. /// Update panning of an ongoing playback.
SetPan { voice_id: usize, pan: u8 }, SetPan {
voice_id: usize,
pan: u8,
},
/// Update pitch of an ongoing playback. /// Update pitch of an ongoing playback.
SetPitch { voice_id: usize, pitch: f64 }, SetPitch {
/// Pause all audio processing. voice_id: usize,
MasterPause, pitch: f64,
/// Resume audio processing. },
MasterResume,
} }
/// PROMETEU Audio Subsystem. mod transport;
/// pub use transport::{AudioDelivery, AudioTransport};
/// Models a multi-channel PCM sampler (SPU).
/// The audio system in Prometeu is **command-based**. This means the Core pub const MAX_COMMANDS_PER_FRAME: usize = 1024;
/// doesn't generate raw audio samples; instead, it sends high-level commands
/// (like `Play`, `Stop`, `SetVolume`) to a queue. The physical host backend /// Bounded producer staging. Samples belong to staged/published commands and the
/// (e.g., CPAL on desktop) then consumes these commands and performs the /// mixer, never to a second playback mirror that cannot observe completion.
/// 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.
pub struct Audio { pub struct Audio {
/// Local state of the hardware voices. This state is used for logic commands: Vec<AudioCommand>,
/// (e.g., checking if a sound is still playing) and is synchronized with the Host. /// Admission survives an early lifecycle flush of the interrupted frame.
pub voices: [Channel; MAX_CHANNELS], frame_commands_admitted: usize,
/// Queue of pending commands to be processed by the Host mixer. lifecycle_commands: Vec<AudioCommand>,
/// This queue is typically flushed and sent to the Host once per frame. in_lifecycle: bool,
pub commands: Vec<AudioCommand>, session: Option<u32>,
/// Interface to access sound memory banks (ARAM). transport: AudioTransport,
pub sound_banks: Arc<dyn SoundBankPoolAccess>, 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 >= SFX_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 { impl AudioBridge for Audio {
fn play( fn play(
&mut self, &mut self,
@@ -112,14 +166,35 @@ impl AudioBridge for Audio {
pan: u8, pan: u8,
pitch: f64, pitch: f64,
priority: u8, priority: u8,
loop_mode: prometeu_hal::LoopMode, loop_mode: LoopMode,
) -> AudioOpStatus { ) -> AudioOpStatus {
let lm = match loop_mode { if voice_id >= SFX_CHANNELS {
prometeu_hal::LoopMode::Off => LoopMode::Off, return AudioOpStatus::VoiceInvalid;
prometeu_hal::LoopMode::On => LoopMode::On, }
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.enqueue(
voice_id,
AudioCommand::Play {
sample,
alive: Some(bank.alive.clone()),
voice_id,
volume,
pan,
pitch,
priority,
loop_mode,
},
)
} }
fn play_sample( fn play_sample(
&mut self, &mut self,
sample: Arc<Sample>, sample: Arc<Sample>,
@@ -128,156 +203,132 @@ impl AudioBridge for Audio {
pan: u8, pan: u8,
pitch: f64, pitch: f64,
priority: u8, 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, loop_mode: LoopMode,
) -> AudioOpStatus { ) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS { if voice_id >= SFX_CHANNELS {
return AudioOpStatus::VoiceInvalid; return AudioOpStatus::VoiceInvalid;
} }
if !pitch.is_finite() || pitch <= 0.0 {
// Resolve the sample from the hardware pools return AudioOpStatus::ArgRangeInvalid;
let bank_slot = self.sound_banks.sound_bank_slot(bank_id as usize);
if bank_slot.is_none() {
return AudioOpStatus::BankInvalid;
} }
self.enqueue(
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,
voice_id, voice_id,
volume, AudioCommand::Play {
pan, sample,
pitch, alive: None,
priority, voice_id,
loop_mode, volume,
}); pan,
AudioOpStatus::Ok pitch,
priority,
loop_mode,
},
)
} }
pub fn stop(&mut self, voice_id: usize) { fn music_play(&mut self, group: usize, bank: usize, looping: bool) -> AudioOpStatus {
if voice_id < MAX_CHANNELS { if group > 1 {
self.voices[voice_id].active = false; return AudioOpStatus::ArgRangeInvalid;
self.voices[voice_id].sample = None;
self.commands.push(AudioCommand::Stop { voice_id });
} }
let Some(bank) = self.sound_banks.music_bank_slot(bank) else {
return AudioOpStatus::BankInvalid;
};
self.enqueue(0, AudioCommand::MusicPlay { group, bank, looping })
} }
fn control(&mut self, control: AudioControl) -> AudioOpStatus {
pub fn set_volume(&mut self, voice_id: usize, volume: u8) { let valid = match control {
if voice_id < MAX_CHANNELS { AudioControl::MusicStop { group }
self.voices[voice_id].volume = volume; | AudioControl::MusicPause { group, .. }
self.commands.push(AudioCommand::SetVolume { voice_id, volume }); | AudioControl::MusicVolume { group, .. }
| AudioControl::MusicFade { group, .. } => group < 2,
AudioControl::Crossfade { source, target, .. } => {
source < 2 && target < 2 && source != target
}
AudioControl::BusVolume { bus, .. } => bus < 3,
AudioControl::GroupVolume { group, .. } => group < 3,
AudioControl::SfxSend { voice, .. } => voice < SFX_CHANNELS,
AudioControl::Effect { group, cutoff_hz, delay_frames, feedback, wet, dry } => {
group < 3
&& cutoff_hz <= OUTPUT_SAMPLE_RATE / 2
&& delay_frames <= 96_000
&& feedback.is_finite()
&& feedback.abs() < 1.0
&& wet.is_finite()
&& dry.is_finite()
&& (0.0..=1.0).contains(&wet)
&& (0.0..=1.0).contains(&dry)
}
};
if !valid {
return AudioOpStatus::ArgRangeInvalid;
} }
self.enqueue(0, AudioCommand::Control(control))
} }
fn stop(&mut self, voice_id: usize) -> AudioOpStatus {
pub fn set_pan(&mut self, voice_id: usize, pan: u8) { self.enqueue(voice_id, AudioCommand::Stop { voice_id })
if voice_id < MAX_CHANNELS { }
self.voices[voice_id].pan = pan; fn set_volume(&mut self, voice_id: usize, volume: u8) -> AudioOpStatus {
self.commands.push(AudioCommand::SetPan { voice_id, pan }); 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 >= SFX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
} }
} if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
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 });
} }
self.enqueue(voice_id, AudioCommand::SetPitch { voice_id, pitch })
} }
fn ready(&self) -> bool {
pub fn is_playing(&self, voice_id: usize) -> bool { self.transport.ready()
if voice_id < MAX_CHANNELS { self.voices[voice_id].active } else { false }
} }
fn begin_frame(&mut self) { /* Staging may already contain debugger steps. */
/// Clears the command queue. The Host should consume this every frame. }
pub fn clear_commands(&mut self) { 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;
}
fn abort_frame(&mut self) {
self.commands.clear(); 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 +377,154 @@ mod tests {
let status = audio.play_sample(sample(), MAX_CHANNELS, 255, 128, 1.0, 0, LoopMode::Off); let status = audio.play_sample(sample(), MAX_CHANNELS, 255, 128, 1.0, 0, LoopMode::Off);
assert_eq!(status, AudioOpStatus::VoiceInvalid); assert_eq!(status, AudioOpStatus::VoiceInvalid);
assert!(!audio.voices.iter().any(|voice| voice.active));
assert!(audio.commands.is_empty()); 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(7, 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,592 @@
//! SBNK/MBNK v1. IMA WAVE4 algorithm implemented here from the published Intel
//! format, not copied from a third-party decoder. Project MIT license applies.
use prometeu_hal::{
music_bank::{Instrument, MusicBank, MusicCompiler, MusicEvent},
sample::Sample,
sound_bank::{AudioBankMetrics, SoundBank},
};
use std::sync::Arc;
pub const HEADER_BYTES: usize = 48;
pub const SAMPLE_BYTES: usize = 40;
pub const INSTRUMENT_BYTES: usize = 64;
pub const EVENT_BYTES: usize = 32;
pub enum DecodedAudioBank {
Sound(SoundBank),
Music(MusicBank),
}
impl DecodedAudioBank {
pub fn decoded_size(&self) -> usize {
match self {
Self::Sound(b) => b.metrics.canonical_decoded_bytes,
Self::Music(b) => b.metrics.canonical_decoded_bytes,
}
}
}
fn bytes(data: &[u8], offset: usize, len: usize) -> Result<&[u8], String> {
data.get(offset..offset.checked_add(len).ok_or("audio offset overflow")?)
.ok_or_else(|| "truncated audio bank".into())
}
fn u16le(b: &[u8], o: usize) -> Result<u16, String> {
Ok(u16::from_le_bytes(bytes(b, o, 2)?.try_into().unwrap()))
}
fn u32le(b: &[u8], o: usize) -> Result<u32, String> {
Ok(u32::from_le_bytes(bytes(b, o, 4)?.try_into().unwrap()))
}
fn zero(b: &[u8]) -> Result<(), String> {
if b.iter().any(|&x| x != 0) { Err("nonzero audio reserved bytes".into()) } else { Ok(()) }
}
fn vector<T>(n: usize) -> Result<Vec<T>, String> {
let mut v = Vec::new();
v.try_reserve_exact(n).map_err(|_| "audio allocation failed")?;
Ok(v)
}
/// One bank owns its serialized bytes while materializing. IO and CPU preparation
/// yield separately; no partially decoded bank escapes this object.
pub struct AudioBankMaterializer<'a> {
data: std::borrow::Cow<'a, [u8]>,
music: bool,
ns: usize,
ni: usize,
ne: usize,
ppq: u32,
tempo: u32,
duration: u32,
loop_tick: Option<u32>,
tracks: usize,
name: String,
samples_at: usize,
metadata: usize,
payload_end: usize,
samples: Vec<Arc<Sample>>,
instruments: Vec<Instrument>,
events: Vec<MusicEvent>,
current: Option<SampleMaterializer>,
compiler: Option<MusicCompiler>,
pcm_bytes: usize,
started: std::time::Instant,
}
struct SampleMaterializer {
sample: Sample,
codec: u8,
frames: usize,
offset: usize,
size: usize,
align: usize,
spb: usize,
consumed: usize,
}
impl<'a> AudioBankMaterializer<'a> {
pub fn new(data: std::borrow::Cow<'a, [u8]>, music: bool) -> Result<Self, String> {
let started = std::time::Instant::now();
bytes(&data, 0, HEADER_BYTES)?;
if &data[..4] != if music { b"MBNK" } else { b"SBNK" }
|| u16le(&data, 4)? != 1
|| u16le(&data, 6)? != 0
{
return Err("unsupported audio bank magic/version/flags".into());
}
let ns = u32le(&data, 8)? as usize;
let ni = u32le(&data, 12)? as usize;
let ne = u32le(&data, 16)? as usize;
let ppq = u32le(&data, 20)?;
let tempo = u32le(&data, 24)?;
let duration = u32le(&data, 28)?;
let lp = u32le(&data, 32)?;
let tracks = u32le(&data, 36)? as usize;
let name_len = u32le(&data, 40)? as usize;
zero(bytes(&data, 44, 4)?)?;
if ns > 65536
|| ppq != 960
|| tempo == 0
|| (!music
&& (ns == 0
|| ni != 0
|| ne != 0
|| duration != 0
|| tracks != 0
|| lp != u32::MAX))
{
return Err("invalid audio bank counts/clock".into());
}
if music
&& (duration == 0 || !(1..=256).contains(&tracks) || (lp != u32::MAX && lp >= duration))
{
return Err("invalid music clock/tracks/loop".into());
}
let mut offset = HEADER_BYTES.checked_add(name_len).ok_or("audio name overflow")?;
let samples_at = offset;
for (n, size) in [(ns, SAMPLE_BYTES), (ni, INSTRUMENT_BYTES), (ne, EVENT_BYTES)] {
offset = offset
.checked_add(n.checked_mul(size).ok_or("audio table overflow")?)
.ok_or("audio table overflow")?;
}
bytes(&data, 0, offset)?;
let text = std::str::from_utf8(bytes(&data, HEADER_BYTES, name_len)?)
.map_err(|_| "audio name UTF-8")?;
let mut name = String::new();
name.try_reserve_exact(text.len()).map_err(|_| "audio allocation failed")?;
name.push_str(text);
Ok(Self {
data,
music,
ns,
ni,
ne,
ppq,
tempo,
duration,
loop_tick: (lp != u32::MAX).then_some(lp),
tracks,
name,
samples_at,
metadata: offset,
payload_end: offset,
samples: vector(ns)?,
instruments: vector(ni)?,
events: vector(ne)?,
current: None,
compiler: None,
pcm_bytes: 0,
started,
})
}
fn start_sample(&mut self) -> Result<(), String> {
let d =
bytes(&self.data, self.samples_at + self.samples.len() * SAMPLE_BYTES, SAMPLE_BYTES)?;
let codec = d[0];
let channels = d[1];
let flags = u16le(d, 2)?;
let rate = u32le(d, 4)?;
let frames = u32le(d, 8)? as usize;
let start = u32le(d, 12)?;
let end = u32le(d, 16)?;
let offset = u32le(d, 20)? as usize;
let size = u32le(d, 24)? as usize;
let align = u16le(d, 28)? as usize;
let spb = u16le(d, 30)? as usize;
let pitch = u32le(d, 36)?;
zero(bytes(d, 34, 2)?)?;
if !(1..=2).contains(&channels)
|| rate == 0
|| pitch == 0
|| flags & !1 != 0
|| offset != self.payload_end
|| (flags == 0 && (start != 0 || end != 0))
|| (flags == 1 && (start >= end || end as usize > frames))
{
return Err("invalid audio sample descriptor/loop".into());
}
let scalar = frames.checked_mul(channels as usize).ok_or("PCM frame overflow")?;
let resident = scalar.checked_mul(2).ok_or("PCM byte overflow")?;
bytes(&self.data, offset, size)?;
match codec {
0 => {
if size != resident || align != 0 || spb != 0 {
return Err("PCM payload/frame count mismatch".into());
}
}
1 => {
let c = channels as usize;
if align < 8 * c
|| !align.is_multiple_of(4 * c)
|| spb != 1 + (align - 4 * c) * 2 / c
|| !size.is_multiple_of(align)
|| size / align != frames.div_ceil(spb)
{
return Err("IMA block layout/frame count".into());
}
}
_ => return Err("unsupported sample codec".into()),
}
let mut sample = Sample::new(rate, vector(scalar)?).with_channels(channels)?;
if flags == 1 {
sample = sample.with_loop(start, end);
}
sample.default_volume = d[32];
sample.default_pan = d[33];
sample.default_pitch = pitch as f64 / 65536.0;
self.pcm_bytes =
self.pcm_bytes.checked_add(resident).ok_or("resident audio size overflow")?;
self.current = Some(SampleMaterializer {
sample,
codec,
frames,
offset,
size,
align,
spb,
consumed: 0,
});
Ok(())
}
/// Decode at most 4096 PCM bytes or one independently bounded IMA block;
/// parse at most 64 metadata records; compile at most 64 music records.
pub fn step(&mut self) -> Result<Option<DecodedAudioBank>, String> {
if let Some(compiler) = &mut self.compiler {
return match compiler.step()? {
Some(mut bank) => {
bank.metrics = self.metrics()?;
Ok(Some(DecodedAudioBank::Music(bank)))
}
None => Ok(None),
};
}
if self.samples.len() < self.ns {
if self.current.is_none() {
self.start_sample()?;
}
let current = self.current.as_mut().unwrap();
if current.consumed < current.size {
if current.codec == 0 {
let count = (current.size - current.consumed).min(4096);
let part = bytes(&self.data, current.offset + current.consumed, count)?;
current
.sample
.data
.extend(part.as_chunks::<2>().0.iter().map(|p| i16::from_le_bytes(*p)));
current.consumed += count;
} else {
let frames = (current.frames - current.sample.frames_len()).min(current.spb);
let pcm = decode_ima_wav4(
bytes(&self.data, current.offset + current.consumed, current.align)?,
current.sample.channels,
frames,
current.align,
current.spb,
)?;
current.sample.data.extend(pcm);
current.consumed += current.align;
}
}
if current.consumed == current.size {
self.payload_end = current.offset + current.size;
let current = self.current.take().unwrap();
self.samples.push(Arc::new(current.sample));
}
return Ok(None);
}
if self.payload_end != self.data.len() {
return Err("audio trailing/unreferenced payload".into());
}
if !self.music {
let mut bank = SoundBank::new(std::mem::take(&mut self.samples));
bank.name = std::mem::take(&mut self.name);
bank.metrics = self.metrics()?;
return Ok(Some(DecodedAudioBank::Sound(bank)));
}
let inst_at = self.samples_at + self.ns * SAMPLE_BYTES;
if self.instruments.len() < self.ni {
for _ in 0..64 {
if self.instruments.len() == self.ni {
break;
}
let d = bytes(
&self.data,
inst_at + self.instruments.len() * INSTRUMENT_BYTES,
INSTRUMENT_BYTES,
)?;
if d[7] & !1 != 0 {
return Err("instrument flags".into());
}
zero(bytes(d, 22, 2)?)?;
zero(bytes(d, 43, 21)?)?;
self.instruments.push(Instrument {
id: u16le(d, 0)?,
sample: u16le(d, 2)?,
low: d[4],
high: d[5],
root: d[6],
looping: d[7] & 1 != 0,
tuning_cents: u16le(d, 8)? as i16,
pan: d[10],
gain: d[11],
attack_us: u32le(d, 12)?,
decay_us: u32le(d, 16)?,
sustain: u16le(d, 20)?,
release_us: u32le(d, 24)?,
vibrato_millihz: u32le(d, 28)?,
vibrato_cents: u16le(d, 32)?,
tremolo_depth: u16le(d, 34)?,
tremolo_millihz: u32le(d, 36)?,
send: u16le(d, 40)?,
curve: d[42],
});
}
return Ok(None);
}
if self.events.len() < self.ne {
let at = inst_at + self.ni * INSTRUMENT_BYTES;
for _ in 0..64 {
if self.events.len() == self.ne {
break;
}
let d = bytes(&self.data, at + self.events.len() * EVENT_BYTES, EVENT_BYTES)?;
self.events.push(MusicEvent {
tick: u32le(d, 0)?,
kind: d[4],
track: d[5],
flags: u16le(d, 6)?,
a: u32le(d, 8)?,
b: u32le(d, 12)?,
c: u32le(d, 16)? as i32,
d: u32le(d, 20)? as i32,
duration_frames: u32le(d, 24)?,
curve: u32le(d, 28)?,
});
}
return Ok(None);
}
self.compiler = Some(MusicCompiler::new(
std::mem::take(&mut self.name),
std::mem::take(&mut self.samples),
std::mem::take(&mut self.instruments),
std::mem::take(&mut self.events),
self.ppq,
self.tempo,
self.duration,
self.loop_tick,
self.tracks,
)?);
Ok(None)
}
fn metrics(&self) -> Result<AudioBankMetrics, String> {
Ok(AudioBankMetrics {
cartridge_bytes: self.data.len(),
pcm_bytes: self.pcm_bytes,
canonical_decoded_bytes: self
.metadata
.checked_add(self.pcm_bytes)
.ok_or("decoded audio size overflow")?,
materialization_ns: self.started.elapsed().as_nanos().min(u64::MAX as u128) as u64,
})
}
}
pub fn decode_audio_bank(data: &[u8], music: bool) -> Result<DecodedAudioBank, String> {
let mut decoder = AudioBankMaterializer::new(std::borrow::Cow::Borrowed(data), music)?;
loop {
if let Some(bank) = decoder.step()? {
return Ok(bank);
}
}
}
const STEP: [i32; 89] = [
7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66,
73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190, 209, 230, 253, 279, 307, 337, 371, 408, 449,
494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272,
2499, 2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493,
10442, 11487, 12635, 13899, 15289, 16818, 18500, 20350, 22385, 24623, 27086, 29794, 32767,
];
const INDEX: [i32; 8] = [-1, -1, -1, -1, 2, 4, 6, 8];
fn ima_code(code: u8, predictor: &mut i32, index: &mut usize) -> i16 {
let step = STEP[*index];
let mut diff = step >> 3;
if code & 1 != 0 {
diff += step >> 2;
}
if code & 2 != 0 {
diff += step >> 1;
}
if code & 4 != 0 {
diff += step;
}
*predictor = (*predictor + if code & 8 != 0 { -diff } else { diff }).clamp(-32768, 32767);
*index = (*index as i32 + INDEX[(code & 7) as usize]).clamp(0, 88) as usize;
*predictor as i16
}
pub fn decode_ima_wav4(
data: &[u8],
channels: u8,
frames: usize,
align: usize,
spb: usize,
) -> Result<Vec<i16>, String> {
let c = channels as usize;
if !(1..=2).contains(&channels)
|| align > u16::MAX as usize
|| align < 8 * c
|| !align.is_multiple_of(4 * c)
|| spb != 1 + (align - 4 * c) * 2 / c
|| !data.len().is_multiple_of(align)
|| data.len() / align != frames.div_ceil(spb)
{
return Err("invalid IMA WAVE4 block/frame layout".into());
}
let mut out = vector(frames.checked_mul(c).ok_or("IMA frame overflow")?)?;
for (block_index, block) in data.chunks_exact(align).enumerate() {
let mut pred = [0i32; 2];
let mut index = [0usize; 2];
for ch in 0..c {
pred[ch] = i16::from_le_bytes([block[ch * 4], block[ch * 4 + 1]]) as i32;
index[ch] = block[ch * 4 + 2] as usize;
if index[ch] > 88 || block[ch * 4 + 3] != 0 {
return Err("IMA predictor index/reserved".into());
}
out.push(pred[ch] as i16);
}
let remaining = (frames - block_index * spb).min(spb);
for group in 0..(spb - 1) / 8 {
let mut decoded = [[0i16; 8]; 2];
for ch in 0..c {
for n in 0..8 {
let b = block[4 * c + group * 4 * c + ch * 4 + n / 2];
let code = (b >> ((n % 2) * 4)) & 15;
if 1 + group * 8 + n >= remaining && code != 0 {
return Err("nonzero IMA padding".into());
}
decoded[ch][n] = ima_code(code, &mut pred[ch], &mut index[ch]);
}
}
for n in 0..8 {
if 1 + group * 8 + n < remaining {
for channel in decoded.iter().take(c) {
out.push(channel[n]);
}
}
}
}
}
Ok(out)
}
/// Deterministic storage encoder used by conformance tools/fixtures (never RT).
pub fn encode_ima_wav4(pcm: &[i16], channels: u8, align: usize) -> Result<Vec<u8>, String> {
let c = channels as usize;
if !(1..=2).contains(&channels)
|| !pcm.len().is_multiple_of(c)
|| align > u16::MAX as usize
|| align < 8 * c
|| !align.is_multiple_of(4 * c)
{
return Err("IMA encoder shape".into());
}
let spb = 1 + (align - 4 * c) * 2 / c;
if spb > u16::MAX as usize {
return Err("IMA block exceeds descriptor range".into());
}
let frames = pcm.len() / c;
let nblocks = frames.div_ceil(spb);
let mut out = vector(nblocks.checked_mul(align).ok_or("IMA encoded size overflow")?)?;
for block in 0..nblocks {
let first = block * spb;
let count = (frames - first).min(spb);
let mut pred = [0i32; 2];
let mut index = [0usize; 2];
for ch in 0..c {
pred[ch] = pcm[first * c + ch] as i32;
let n = (count - 1).min(32);
let sum: i32 = (1..=n)
.map(|i| {
(pcm[(first + i) * c + ch] as i32 - pcm[(first + i - 1) * c + ch] as i32).abs()
})
.sum();
let mean = if n == 0 { 0 } else { sum / n as i32 };
index[ch] = STEP.iter().position(|&s| s >= mean).unwrap_or(88);
out.extend_from_slice(&(pred[ch] as i16).to_le_bytes());
out.push(index[ch] as u8);
out.push(0);
}
for group in 0..(spb - 1) / 8 {
for ch in 0..c {
for byte in 0..4 {
let mut packed = 0;
for nibble in 0..2 {
let f = 1 + group * 8 + byte * 2 + nibble;
let code = if f >= count {
0
} else {
let diff = pcm[(first + f) * c + ch] as i32 - pred[ch];
let mut magnitude = diff.abs();
let step = STEP[index[ch]];
let mut code = if diff < 0 { 8 } else { 0 };
if magnitude >= step {
code |= 4;
magnitude -= step;
}
if magnitude >= step >> 1 {
code |= 2;
magnitude -= step >> 1;
}
if magnitude >= step >> 2 {
code |= 1;
}
code
};
ima_code(code, &mut pred[ch], &mut index[ch]);
packed |= code << (nibble * 4);
}
out.push(packed);
}
}
}
}
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn ima_known_nibbles_and_stereo_headers() {
let block = [0, 0, 0, 0, 0x11, 0, 0, 0];
assert_eq!(decode_ima_wav4(&block, 1, 3, 8, 9).unwrap(), [0, 1, 2]);
let mut stereo = vec![0, 0, 0, 0, 100, 0, 0, 0];
stereo.extend([0u8; 8]);
let decoded = decode_ima_wav4(&stereo, 2, 9, 16, 9).unwrap();
assert_eq!(&decoded[..6], [0, 100, 0, 100, 0, 100]);
stereo[2] = 89;
assert!(decode_ima_wav4(&stereo, 2, 9, 16, 9).is_err());
}
#[test]
fn ima_partial_block_padding_round_trip_is_deterministic() {
let pcm: Vec<i16> = (0..1111)
.flat_map(|i| {
[
((i as f64 * 0.03).sin() * 12000.0) as i16,
((i as f64 * 0.02).cos() * 9000.0) as i16,
]
})
.collect();
let encoded = encode_ima_wav4(&pcm, 2, 512).unwrap();
assert_eq!(encoded, encode_ima_wav4(&pcm, 2, 512).unwrap());
let decoded = decode_ima_wav4(&encoded, 2, 1111, 512, 505).unwrap();
assert_eq!(decoded.len(), pcm.len());
assert_eq!(decoded[1010], pcm[1010]);
assert!(decode_ima_wav4(&encoded[..encoded.len() - 1], 2, 1111, 512, 505).is_err());
let error: f64 =
pcm.iter().zip(decoded).map(|(&a, b)| (a as f64 - b as f64).powi(2)).sum::<f64>()
/ pcm.len() as f64;
assert!(error.sqrt() < 400.0, "RMS error {error}");
}
}
#[cfg(test)]
pub(crate) fn test_pcm_bank(raw: &[u8], rate: u32) -> Vec<u8> {
let mut bytes = vec![0u8; 88];
bytes[..4].copy_from_slice(b"SBNK");
bytes[4] = 1;
for (at, value) in [
(8, 1),
(20, 960),
(24, 500000),
(32, u32::MAX),
(52, rate),
(56, (raw.len() / 2) as u32),
(68, 88),
(72, raw.len() as u32),
(84, 65536),
] {
bytes[at..at + 4].copy_from_slice(&value.to_le_bytes());
}
bytes[49] = 1;
bytes[80] = 255;
bytes[81] = 128;
bytes.extend_from_slice(raw);
bytes
}
#[cfg(test)]
#[path = "bank_tests.rs"]
mod bank_tests;
@@ -0,0 +1,182 @@
use super::*;
use crate::{AssetManager, MemoryBanks, SoundBankPoolAccess};
use prometeu_hal::{
asset::{AssetCodec, AssetEntry, AssetOpStatus, BankType, LoadStatus, SlotRef},
cartridge::AssetsPayloadSource,
};
use std::time::{Duration, Instant};
fn fixtures() -> Vec<(&'static [u8], bool)> {
vec![
(
include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/pcm-only.sbnk"
)),
false,
),
(
include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/ima-only.sbnk"
)),
false,
),
(
include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-sound.sbnk"
)),
false,
),
(
include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-music.mbnk"
)),
true,
),
]
}
#[test]
fn packer_binary_fixtures_materialize_mixed_stereo_banks_and_separate_encoded_from_pcm_sizes() {
for (index, (bytes, music)) in fixtures().into_iter().enumerate() {
let decoded = decode_audio_bank(bytes, music).unwrap();
let (samples, metrics) = match &decoded {
DecodedAudioBank::Sound(b) => (&b.samples, b.metrics),
DecodedAudioBank::Music(b) => {
assert_eq!(b.events.len(), 4);
assert_eq!(b.instruments.len(), 2);
assert_eq!(b.tracks, 2);
(&b.samples, b.metrics)
}
};
assert_eq!(metrics.cartridge_bytes, bytes.len());
assert_eq!(metrics.pcm_bytes, if index < 2 { 2000 } else { 6000 });
assert_eq!(samples[0].frames_len(), 1000);
assert_eq!(samples[0].loop_end, Some(1000));
if index >= 2 {
assert_eq!(samples[1].channels, 2);
assert_eq!(samples[1].frames_len(), 1000);
}
if index != 0 {
assert!(decoded.decoded_size() > bytes.len());
}
}
}
#[test]
fn complete_validation_rejects_truncation_unknown_codec_bad_loops_and_reserved_bytes() {
for (bytes, music) in fixtures() {
for cut in [0, 4, 47, 48, bytes.len() - 1] {
assert!(decode_audio_bank(&bytes[..cut], music).is_err());
}
let name = u32le(bytes, 40).unwrap() as usize;
let sample = 48 + name;
for (at, value) in
[(4, 2), (44, 1), (sample, 99), (sample + 1, 3), (sample + 2, 2), (sample + 34, 1)]
{
let mut bad = bytes.to_vec();
bad[at] = value;
assert!(decode_audio_bank(&bad, music).is_err(), "{at}");
}
let mut bad = bytes.to_vec();
bad[sample + 12..sample + 16].copy_from_slice(&1001u32.to_le_bytes());
assert!(decode_audio_bank(&bad, music).is_err());
let mut bad = bytes.to_vec();
bad.push(0);
assert!(decode_audio_bank(&bad, music).is_err());
// Mutating every byte must produce either a validated bank or a clean error.
for i in 0..bytes.len() {
let mut changed = bytes.to_vec();
changed[i] ^= 0xff;
let _ = decode_audio_bank(&changed, music);
}
}
}
fn entry(id: i32, offset: usize, bytes: &[u8], music: bool) -> AssetEntry {
AssetEntry {
asset_id: id,
asset_name: format!("bank{id}"),
bank_type: if music { BankType::MUSIC } else { BankType::SOUNDS },
offset: offset as u64,
size: bytes.len() as u64,
decoded_size: decode_audio_bank(bytes, music).unwrap().decoded_size() as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({"version":1}),
}
}
fn ready(manager: &AssetManager, handle: u32) {
let end = Instant::now() + Duration::from_secs(3);
while matches!(
manager.status(handle),
LoadStatus::QUEUED | LoadStatus::LOADING | LoadStatus::PENDING | LoadStatus::ACTIVE
) {
assert!(Instant::now() < end);
std::thread::yield_now();
}
assert_eq!(manager.status(handle), LoadStatus::READY);
}
#[test]
fn audio_loading_commit_replacement_and_unload_are_atomic_and_type_isolated() {
let fixtures = fixtures();
let sound = fixtures[2].0;
let music = fixtures[3].0;
let mut payload = sound.to_vec();
payload.extend_from_slice(music);
let bad_at = payload.len();
let mut corrupt = sound.to_vec();
corrupt[0] = 0;
payload.extend(&corrupt);
let mut bad = entry(3, bad_at, sound, false);
bad.decoded_size += 1;
let banks = Arc::new(MemoryBanks::new());
let manager = AssetManager::new(
vec![entry(1, 0, sound, false), entry(2, sound.len(), music, true), bad],
AssetsPayloadSource::from_bytes(payload),
banks.clone(),
banks.clone(),
banks.clone(),
);
let s = manager.load(1, 0).unwrap();
ready(&manager, s);
assert!(banks.sound_bank_slot(0).is_none());
assert_eq!(manager.commit(s), AssetOpStatus::Ok);
manager.apply_commits();
let old = banks.sound_bank_slot(0).unwrap();
let m = manager.load(2, 0).unwrap();
ready(&manager, m);
manager.commit(m);
manager.apply_commits();
assert!(old.alive.load(std::sync::atomic::Ordering::Acquire));
assert!(banks.music_bank_slot(0).is_some());
let failing = manager.load(3, 0).unwrap();
let end = Instant::now() + Duration::from_secs(3);
while manager.status(failing) != LoadStatus::ERROR {
assert!(Instant::now() < end);
std::thread::yield_now();
}
manager.apply_commits();
assert!(Arc::ptr_eq(&old, &banks.sound_bank_slot(0).unwrap()));
let replacement = manager.load(1, 0).unwrap();
ready(&manager, replacement);
assert!(old.alive.load(std::sync::atomic::Ordering::Acquire));
manager.commit(replacement);
manager.apply_commits();
assert!(!old.alive.load(std::sync::atomic::Ordering::Acquire));
assert_eq!(manager.unload_audio(true, 0), AssetOpStatus::Ok);
assert!(banks.music_bank_slot(0).is_none());
assert!(banks.sound_bank_slot(0).is_some());
assert_eq!(manager.slot_info(SlotRef::music(0)).asset_id, None);
assert_eq!(manager.unload_audio(false, 0), AssetOpStatus::Ok);
assert!(banks.sound_bank_slot(0).is_none());
assert_eq!(manager.unload_audio(false, 16), AssetOpStatus::InvalidState);
}
#[test]
fn codec_tooling_rejects_overflowing_block_parameters_without_panicking() {
for align in [0, 4, usize::MAX - 3, usize::MAX] {
assert!(encode_ima_wav4(&[1, 2], 1, align).is_err());
assert!(decode_ima_wav4(&[0; 8], 1, 9, align, 9).is_err());
}
assert!(encode_ima_wav4(&[1], 1, 65532).is_err());
assert!(decode_ima_wav4(&[0; 8], 1, usize::MAX, 8, 9).is_err());
assert!(encode_ima_wav4(&[1], 0, 256).is_err());
}
@@ -0,0 +1,924 @@
//! Host-independent bounded PCM engine. Construct resources off the render lane.
use super::{
AudioCommand, AudioDelivery, AudioTransport, Channel, LoopMode, MAX_CHANNELS,
MAX_COMMANDS_PER_FRAME, SFX_CHANNELS, SFX_START,
};
use prometeu_hal::{
audio_bridge::AudioControl,
music_bank::{Instrument, MAX_MUSIC_TRACKS, MusicBank, MusicEvent},
sample::Sample,
};
use std::{
sync::{
Arc,
atomic::{AtomicBool, Ordering},
},
time::{Duration, Instant},
};
pub const RETIRED_CAPACITY: usize = 2 * (3 * MAX_COMMANDS_PER_FRAME + MAX_CHANNELS + 2);
/// Owning resources leave the real-time lane in a preallocated packet.
#[allow(dead_code)]
enum Retired {
Sample(Arc<Sample>),
Bank(Arc<MusicBank>),
Token(Arc<AtomicBool>),
}
pub struct Packet {
retired: Vec<Retired>,
pub batches: [Option<Vec<AudioCommand>>; 2],
}
impl Default for Packet {
fn default() -> Self {
Self::new()
}
}
impl Packet {
pub fn new() -> Self {
Self { retired: Vec::with_capacity(RETIRED_CAPACITY), batches: [None, None] }
}
fn push(&mut self, owner: Retired) {
assert!(self.retired.len() < RETIRED_CAPACITY, "audio retirement bound");
self.retired.push(owner);
}
fn voice(&mut self, voice: &mut Channel) {
if let Some(s) = voice.sample.take() {
self.push(Retired::Sample(s));
}
if let Some(t) = voice.alive.take() {
self.push(Retired::Token(t));
}
voice.active = false;
}
pub fn recycle(&mut self, transport: &AudioTransport) {
self.retired.clear();
for batch in &mut self.batches {
if let Some(batch) = batch.take() {
transport.recycle_commands(batch);
}
}
}
/// Service thread only: count distinct retired PCM payloads, excluding Arc overhead.
pub fn retained_pcm_bytes(&self) -> usize {
let mut seen = std::collections::HashSet::new();
let mut bytes = 0;
let mut add = |sample: &Arc<Sample>| {
if seen.insert(Arc::as_ptr(sample)) {
bytes += sample.data.capacity() * 2;
}
};
for owner in &self.retired {
match owner {
Retired::Sample(sample) => add(sample),
Retired::Bank(bank) => {
for sample in bank.samples.iter() {
add(sample);
}
}
Retired::Token(_) => {}
}
}
for batch in self.batches.iter().flatten() {
for command in batch {
match command {
AudioCommand::Play { sample, .. } => add(sample),
AudioCommand::MusicPlay { bank, .. } => {
for sample in bank.samples.iter() {
add(sample);
}
}
_ => {}
}
}
}
bytes
}
pub fn is_empty(&self) -> bool {
self.retired.is_empty() && self.batches.iter().all(Option::is_none)
}
pub fn capacity(&self) -> usize {
self.retired.capacity()
}
}
#[derive(Clone, Copy)]
struct Ramp {
from: f64,
to: f64,
start: u64,
duration: u32,
smooth: bool,
}
impl Ramp {
fn constant(value: f64) -> Self {
Self { from: value, to: value, start: 0, duration: 0, smooth: false }
}
fn at(self, now: u64) -> f64 {
if self.duration == 0 {
return self.to;
}
let elapsed = now.saturating_sub(self.start);
if elapsed >= self.duration as u64 {
return self.to;
}
let x = elapsed as f64 / self.duration as f64;
let x = if self.smooth { x * x * (3.0 - 2.0 * x) } else { x };
self.from + (self.to - self.from) * x
}
fn set(&mut self, value: f64, now: u64, duration: u32, smooth: bool) {
*self = Self { from: self.at(now), to: value, start: now, duration, smooth };
}
fn done(self, now: u64) -> bool {
now.saturating_sub(self.start) >= self.duration as u64
}
}
#[derive(Clone, Copy)]
struct SendRamp {
base: Ramp,
scale: Ramp,
}
impl Default for SendRamp {
fn default() -> Self {
Self { base: Ramp::constant(0.0), scale: Ramp::constant(1.0) }
}
}
impl SendRamp {
fn at(self, now: u64, instrument_default: f64) -> f64 {
self.base.at(now) + self.scale.at(now) * instrument_default
}
fn set(&mut self, to: f64, now: u64, frames: u32, smooth: bool) {
self.base.set(to, now, frames, smooth);
self.scale.set(0.0, now, frames, smooth);
}
}
#[derive(Clone, Copy)]
struct Track {
gain: Ramp,
pan: Ramp,
pitch: Ramp,
send: SendRamp,
vibrato: Option<(u32, f64)>,
tremolo: Option<(u32, f64)>,
}
impl Default for Track {
fn default() -> Self {
Self {
gain: Ramp::constant(1.0),
pan: Ramp::constant(128.0),
pitch: Ramp::constant(0.0),
send: SendRamp::default(),
vibrato: None,
tremolo: None,
}
}
}
struct MusicGroup {
bank: Option<Arc<MusicBank>>,
active: bool,
paused: bool,
looping: bool,
time: u128,
cursor: usize,
frame: u64,
iteration: u64,
tracks: [Track; MAX_MUSIC_TRACKS],
gain: Ramp,
stop_after_fade: bool,
}
impl Default for MusicGroup {
fn default() -> Self {
Self {
bank: None,
active: false,
paused: false,
looping: false,
time: 0,
cursor: 0,
frame: 0,
iteration: 0,
tracks: [Track::default(); MAX_MUSIC_TRACKS],
gain: Ramp::constant(1.0),
stop_after_fade: false,
}
}
}
#[derive(Clone, Copy)]
struct VoiceState {
inst: Instrument,
track: usize,
note_id: u32,
iteration: u64,
born: u64,
age: u64,
release_age: Option<u64>,
release_level: f64,
release_order: Option<u64>,
level: f64,
cached_cents: f64,
pitch_factor: f64,
glide: Ramp,
send: f64,
zone: usize,
}
impl Default for VoiceState {
fn default() -> Self {
Self {
inst: Instrument::default(),
track: 0,
note_id: 0,
iteration: 0,
born: 0,
age: 0,
release_age: None,
release_level: 0.0,
release_order: None,
level: 1.0,
cached_cents: f64::INFINITY,
pitch_factor: 1.0,
glide: Ramp::constant(0.0),
send: 0.0,
zone: 0,
}
}
}
struct Effect {
delay: Vec<[f32; 2]>,
write: usize,
history: usize,
frames: usize,
feedback: f32,
wet: f32,
dry: f32,
coefficient: f32,
filter: [f32; 2],
}
impl Effect {
fn new() -> Self {
Self {
delay: vec![[0.0; 2]; 96_000],
write: 0,
history: 0,
frames: 0,
feedback: 0.0,
wet: 0.0,
dry: 1.0,
coefficient: 1.0,
filter: [0.0; 2],
}
}
fn reset(&mut self) {
self.write = 0;
self.history = 0;
self.filter = [0.0; 2];
}
fn process(&mut self, input: [f32; 2], send: [f32; 2]) -> [f32; 2] {
if self.frames == 0 && self.coefficient == 1.0 {
self.filter = input;
return [input[0] * self.dry, input[1] * self.dry];
}
let mut out = [0.0; 2];
for c in 0..2 {
self.filter[c] += self.coefficient * (input[c] - self.filter[c]);
// Flush subnormals without denormal-sensitive host settings.
if self.filter[c].abs() < 1e-20 {
self.filter[c] = 0.0;
}
let echo = if self.frames != 0 && self.history >= self.frames {
self.delay[(self.write + 96_000 - self.frames) % 96_000][c]
} else {
0.0
};
out[c] = self.filter[c] * self.dry + echo * self.wet;
self.delay[self.write][c] = send[c] + echo * self.feedback;
if self.delay[self.write][c].abs() < 1e-20 {
self.delay[self.write][c] = 0.0;
}
}
self.write = (self.write + 1) % 96_000;
self.history = (self.history + 1).min(96_000);
out
}
}
#[derive(Debug, Clone, Copy, Default)]
pub struct AudioDiagnostics {
pub frames: u64,
pub active_voices: usize,
pub maximum_voices: usize,
pub last_render_us: u64,
pub maximum_render_us: u64,
}
pub struct AudioMixer {
pub voices: [Channel; MAX_CHANNELS],
states: [VoiceState; MAX_CHANNELS],
groups: [MusicGroup; 2],
effects: [Effect; 3],
bus: [f32; 3],
sfx_gain: f32,
exponential: [f64; 1025],
sine: [f64; 4097],
pub last_processing_time: Duration,
paused: bool,
epoch: u64,
pub diagnostics: AudioDiagnostics,
note_serial: u64,
}
impl Default for AudioMixer {
fn default() -> Self {
Self::new()
}
}
impl AudioMixer {
pub fn new() -> Self {
Self {
voices: std::array::from_fn(|_| Channel::default()),
states: [VoiceState::default(); MAX_CHANNELS],
groups: std::array::from_fn(|_| MusicGroup::default()),
effects: std::array::from_fn(|_| Effect::new()),
bus: [1.0; 3],
sfx_gain: 1.0,
exponential: std::array::from_fn(|i| {
((-6.0 * i as f64 / 1024.0).exp() - (-6.0f64).exp()) / (1.0 - (-6.0f64).exp())
}),
sine: std::array::from_fn(|i| (std::f64::consts::TAU * i as f64 / 4096.0).sin()),
last_processing_time: Duration::ZERO,
paused: false,
epoch: 0,
diagnostics: AudioDiagnostics::default(),
note_serial: 0,
}
}
pub fn prepared_bytes(&self) -> usize {
std::mem::size_of::<Self>()
+ self
.effects
.iter()
.map(|e| e.delay.capacity() * std::mem::size_of::<[f32; 2]>())
.sum::<usize>()
}
fn stop_group(&mut self, group: usize, packet: &mut Packet) {
for v in &mut self.voices[group * 12..group * 12 + 12] {
packet.voice(v);
}
if let Some(bank) = self.groups[group].bank.take() {
packet.push(Retired::Bank(bank));
}
let gain = self.groups[group].gain.at(self.groups[group].frame);
self.groups[group] = MusicGroup::default();
self.groups[group].gain = Ramp::constant(gain);
self.effects[group].reset();
}
pub fn retire_inactive(&mut self, packet: &mut Packet) {
for g in 0..2 {
if self.groups[g].bank.as_ref().is_some_and(|b| !b.alive.load(Ordering::Acquire))
|| (self.groups[g].stop_after_fade && !self.groups[g].active)
{
self.stop_group(g, packet);
}
}
for v in &mut self.voices {
if !v.active || v.alive.as_ref().is_some_and(|a| !a.load(Ordering::Acquire)) {
packet.voice(v);
}
}
}
pub fn apply_delivery_into(&mut self, delivery: AudioDelivery, packet: &mut Packet) {
if delivery.epoch < self.epoch {
packet.batches = [delivery.frame, delivery.lifecycle];
return;
}
if delivery.epoch != self.epoch {
for group in 0..2 {
self.stop_group(group, packet);
}
for voice in &mut self.voices {
packet.voice(voice);
*voice = Channel::default();
}
for group in &mut self.groups {
group.gain = Ramp::constant(1.0);
}
for effect in &mut self.effects {
effect.reset();
effect.frames = 0;
effect.feedback = 0.0;
effect.wet = 0.0;
effect.dry = 1.0;
effect.coefficient = 1.0;
}
self.bus = [1.0; 3];
self.sfx_gain = 1.0;
self.epoch = delivery.epoch;
}
packet.batches = [delivery.frame, delivery.lifecycle];
for index in 0..2 {
if let Some(mut batch) = packet.batches[index].take() {
for command in &mut batch {
let command =
std::mem::replace(command, AudioCommand::Stop { voice_id: SFX_CHANNELS });
self.process_command(command, packet);
}
packet.batches[index] = Some(batch);
}
}
self.paused = delivery.paused;
}
/// Convenience for non-real-time signal tests/offline owners.
pub fn apply_delivery(&mut self, delivery: AudioDelivery) {
self.apply_delivery_into(delivery, &mut Packet::new());
}
pub fn fill_buffer(&mut self, buffer: &mut [f32]) {
self.mix(buffer);
self.retire_inactive(&mut Packet::new());
}
fn process_command(&mut self, command: AudioCommand, packet: &mut Packet) {
match command {
AudioCommand::Play {
sample,
alive,
voice_id,
volume,
pan,
pitch,
priority,
loop_mode,
} => {
if voice_id >= SFX_CHANNELS
|| alive.as_ref().is_some_and(|a| !a.load(Ordering::Acquire))
{
packet.push(Retired::Sample(sample));
if let Some(t) = alive {
packet.push(Retired::Token(t));
}
return;
}
let index = SFX_START + voice_id;
packet.voice(&mut self.voices[index]);
self.voices[index] = Channel {
sample: Some(sample),
alive,
active: true,
pos: 0.0,
pitch,
volume,
pan,
loop_mode,
priority,
};
self.states[index] = VoiceState::default();
}
AudioCommand::Stop { voice_id } => {
if voice_id < SFX_CHANNELS {
packet.voice(&mut self.voices[SFX_START + voice_id]);
}
}
AudioCommand::SetVolume { voice_id, volume } => {
if voice_id < SFX_CHANNELS {
self.voices[SFX_START + voice_id].volume = volume;
}
}
AudioCommand::SetPan { voice_id, pan } => {
if voice_id < SFX_CHANNELS {
self.voices[SFX_START + voice_id].pan = pan;
}
}
AudioCommand::SetPitch { voice_id, pitch } => {
if voice_id < SFX_CHANNELS {
self.voices[SFX_START + voice_id].pitch = pitch;
}
}
AudioCommand::MusicPlay { group, bank, looping } => {
if group >= 2 || !bank.alive.load(Ordering::Acquire) {
packet.push(Retired::Bank(bank));
return;
}
self.stop_group(group, packet);
self.groups[group].bank = Some(bank);
self.groups[group].active = true;
self.groups[group].looping = looping;
}
AudioCommand::Control(control) => match control {
AudioControl::GroupVolume { group, gain } => {
if group == 2 {
self.sfx_gain = gain as f32 / 255.0;
} else {
self.groups[group].gain = Ramp::constant(gain as f64 / 255.0);
self.groups[group].stop_after_fade = false;
}
}
AudioControl::MusicStop { group } => self.stop_group(group, packet),
AudioControl::MusicPause { group, paused } => self.groups[group].paused = paused,
AudioControl::MusicVolume { group, gain } => {
self.groups[group].gain = Ramp::constant(gain as f64 / 255.0);
self.groups[group].stop_after_fade = false;
}
AudioControl::MusicFade { group, gain, frames, smooth } => {
let g = &mut self.groups[group];
g.gain.set(gain as f64 / 255.0, g.frame, frames, smooth);
g.stop_after_fade = false;
}
AudioControl::Crossfade { source, target, frames, smooth } => {
if !self.groups[source].active || !self.groups[target].active {
return;
}
for (g, value) in [(source, 0.0), (target, 1.0)] {
let group = &mut self.groups[g];
group.gain.set(value, group.frame, frames, smooth);
group.stop_after_fade = g == source;
}
}
AudioControl::BusVolume { bus, gain } => self.bus[bus] = gain as f32 / 255.0,
AudioControl::SfxSend { voice, gain } => {
self.states[SFX_START + voice].send = gain as f64 / 255.0
}
AudioControl::Effect { group, cutoff_hz, delay_frames, feedback, wet, dry } => {
let effect = &mut self.effects[group];
effect.coefficient = if cutoff_hz == 0 {
1.0
} else {
(1.0 - (-std::f32::consts::TAU * cutoff_hz as f32 / 48_000.0).exp())
.clamp(0.0, 1.0)
};
if effect.frames != delay_frames as usize {
effect.reset();
}
effect.frames = delay_frames as usize;
effect.feedback = feedback;
effect.wet = wet;
effect.dry = dry;
}
},
}
}
fn release(&mut self, index: usize) {
let state = &mut self.states[index];
if state.release_age.is_none() {
let level = envelope(state, &self.exponential);
state.release_age = Some(state.age);
state.release_order = Some(self.note_serial);
self.note_serial = self.note_serial.wrapping_add(1);
state.release_level = level;
}
}
fn event(&mut self, group: usize, event: MusicEvent, zone: usize) {
let frame = self.groups[group].frame;
let track = event.track as usize;
if event.kind == 1 {
let bank = self.groups[group].bank.as_ref().unwrap();
let inst = bank.instruments[zone];
let cents = (event.c - inst.root as i32) as f64 * 100.0 + inst.tuning_cents as f64;
let range = group * 12..group * 12 + 12;
self.note_serial = self.note_serial.wrapping_add(1);
let legato = if event.flags & 1 != 0 {
range
.clone()
.filter(|&i| {
self.voices[i].active
&& self.states[i].track == track
&& self.states[i].release_age.is_none()
})
.max_by_key(|&i| (self.states[i].born, i))
} else {
None
};
if let Some(index) = legato.filter(|&i| self.states[i].zone == zone) {
let state = &mut self.states[index];
state.glide.set(cents, frame, event.duration_frames, event.curve == 1);
state.note_id = event.a;
state.born = self.note_serial;
state.iteration = self.groups[group].iteration;
self.voices[index].volume = ((inst.gain as u16 * event.d as u16 + 127) / 255) as u8;
return;
}
let index = legato.unwrap_or_else(|| {
range.clone().find(|&i| !self.voices[i].active).unwrap_or_else(|| {
range
.min_by_key(|&i| {
(
self.states[i].release_age.is_none(),
self.states[i].release_order.unwrap_or(self.states[i].born),
i,
)
})
.unwrap()
})
});
// Music samples always have an owner in this group's retained bank.
self.voices[index] = Channel {
sample: Some(bank.samples[inst.sample as usize].clone()),
alive: None,
active: true,
pos: 0.0,
pitch: 1.0,
volume: ((inst.gain as u16 * event.d as u16 + 127) / 255) as u8,
pan: inst.pan,
loop_mode: if inst.looping { LoopMode::On } else { LoopMode::Off },
priority: 0,
};
self.states[index] = VoiceState {
inst,
track,
note_id: event.a,
iteration: self.groups[group].iteration,
born: self.note_serial,
glide: Ramp::constant(cents),
send: inst.send as f64 / 65535.0,
zone,
..VoiceState::default()
};
} else if event.kind == 2 {
for index in group * 12..group * 12 + 12 {
let state = &self.states[index];
if self.voices[index].active
&& state.track == track
&& state.note_id == event.a
&& state.iteration == self.groups[group].iteration
{
self.release(index);
}
}
} else {
let t = &mut self.groups[group].tracks[track];
let smooth = event.curve == 1;
match event.kind {
4 => t.gain.set(event.c as f64 / 65535.0, frame, event.duration_frames, smooth),
5 => t.pan.set(event.c as f64, frame, event.duration_frames, smooth),
6 => t.pitch.set(event.c as f64, frame, event.duration_frames, smooth),
7 => t.vibrato = Some((event.a, event.c as f64)),
8 => t.tremolo = Some((event.a, event.c as f64 / 65535.0)),
9 => t.send.set(event.c as f64 / 65535.0, frame, event.duration_frames, smooth),
_ => {} // Tempo/instrument selection were resolved during compilation.
}
}
}
fn sequence(&mut self, group: usize) {
if !self.groups[group].active || self.groups[group].paused {
return;
}
loop {
let g = &self.groups[group];
let bank = g.bank.as_ref().unwrap();
if let Some(event) = bank.events.get(g.cursor).filter(|e| e.time <= g.time) {
let event = *event;
self.groups[group].cursor += 1;
self.event(group, event.event, event.zone);
continue;
}
if g.time < bank.end_time {
break;
}
let loop_start = bank.loop_time.unwrap_or(0);
let loop_event = if bank.loop_time.is_some() { bank.loop_event } else { 0 };
let loop_length = bank.end_time - loop_start;
for index in group * 12..group * 12 + 12 {
self.release(index);
}
let g = &mut self.groups[group];
if !g.looping {
g.active = false;
break;
}
g.time -= loop_length;
g.cursor = loop_event;
g.iteration = g.iteration.wrapping_add(1);
}
}
pub fn mix(&mut self, buffer: &mut [f32]) {
let start = Instant::now();
buffer.fill(0.0);
if self.paused {
self.last_processing_time = start.elapsed();
return;
}
for frame in buffer.as_chunks_mut::<2>().0 {
// Invalidated resources stay owned until a reclamation packet is available.
for g in 0..2 {
if self.groups[g].bank.as_ref().is_some_and(|b| !b.alive.load(Ordering::Acquire)) {
self.groups[g].active = false;
for v in &mut self.voices[g * 12..g * 12 + 12] {
v.active = false;
}
self.effects[g].reset();
}
self.sequence(g);
}
let mut dry = [[0.0f32; 2]; 3];
let mut send = [[0.0f32; 2]; 3];
let mut active = 0;
for index in 0..MAX_CHANNELS {
let group = if index < 12 {
0
} else if index < 24 {
1
} else {
2
};
if group < 2 && self.groups[group].paused {
continue;
}
let voice = &mut self.voices[index];
if !voice.active {
continue;
}
if voice.alive.as_ref().is_some_and(|a| !a.load(Ordering::Acquire)) {
voice.active = false;
continue;
}
let Some(sample) = &voice.sample else {
continue;
};
let len = sample.frames_len();
if len == 0 {
voice.active = false;
continue;
}
active += 1;
let state = &mut self.states[index];
let mut volume = voice.volume as f64 / 255.0;
let mut pan = voice.pan as f64;
let mut pitch = voice.pitch;
let mut amount = state.send;
if group < 2 {
let g = &self.groups[group];
let track = g.tracks[state.track];
state.level = envelope(state, &self.exponential);
if state.release_age.is_some() && state.level <= 0.0 {
voice.active = false;
continue;
}
let vib = track
.vibrato
.unwrap_or((state.inst.vibrato_millihz, state.inst.vibrato_cents as f64));
let trem = track.tremolo.unwrap_or((
state.inst.tremolo_millihz,
state.inst.tremolo_depth as f64 / 65535.0,
));
let cents = state.glide.at(g.frame)
+ track.pitch.at(g.frame)
+ lfo(&self.sine, state.age, vib.0) * vib.1;
if cents != state.cached_cents {
state.pitch_factor = (cents / 1200.0).exp2();
state.cached_cents = cents;
}
pitch *= state.pitch_factor;
volume *= state.level
* track.gain.at(g.frame)
* (1.0 - trem.1 * (lfo(&self.sine, state.age, trem.0) + 1.0) * 0.5);
pan = (pan + track.pan.at(g.frame) - 128.0).clamp(0.0, 255.0);
amount = track.send.at(g.frame, state.send);
state.age = state.age.wrapping_add(1);
}
let channels = sample.channels as usize;
let (loop_start, end) = match (voice.loop_mode, sample.loop_start, sample.loop_end)
{
(LoopMode::On, Some(a), Some(b)) if a < b && b as usize <= len => {
(a as f64, b as f64)
}
_ => (0.0, len as f64),
};
let pos = voice.pos as usize;
if pos >= len {
voice.active = false;
continue;
}
let next = if voice.loop_mode == LoopMode::On && (pos + 1) as f64 >= end {
loop_start as usize
} else {
pos + 1
};
let frac = (voice.pos - pos as f64) as f32;
let value = |c: usize| {
let a = sample.data[pos * channels + c] as f32 / 32768.0;
let b =
sample.data.get(next * channels + c).copied().unwrap_or(0) as f32 / 32768.0;
a + (b - a) * frac
};
if volume != 0.0 {
let normalized_pan =
if pan <= 128.0 { pan / 256.0 } else { 0.5 + (pan - 128.0) / 254.0 };
let gains = if channels == 1 {
[(1.0 - normalized_pan).sqrt(), normalized_pan.sqrt()]
} else {
[
if pan <= 128.0 { 1.0 } else { (255.0 - pan) / 127.0 },
if pan >= 128.0 { 1.0 } else { pan / 128.0 },
]
};
for c in 0..2 {
let v =
value(if channels == 1 { 0 } else { c }) * (volume * gains[c]) as f32;
dry[group][c] += v;
send[group][c] += v * amount as f32;
}
}
let ratio = sample.sample_rate as f64 / 48_000.0;
if ratio > 0.0 {
if pitch >= (end - voice.pos) / ratio {
if voice.loop_mode == LoopMode::Off {
voice.active = false;
} else {
let length = end - loop_start;
let step = (pitch % (length / ratio)) * ratio;
voice.pos =
loop_start + (voice.pos - loop_start + step).rem_euclid(length);
if voice.pos >= end {
voice.pos = loop_start;
}
}
} else {
voice.pos += pitch * ratio;
}
}
}
self.diagnostics.active_voices = active;
self.diagnostics.maximum_voices = self.diagnostics.maximum_voices.max(active);
for group in 0..3 {
if group < 2 && self.groups[group].paused {
continue;
}
let gain = if group < 2 {
self.groups[group].gain.at(self.groups[group].frame) as f32 * self.bus[0]
} else {
self.bus[1] * self.sfx_gain
};
let values = self.effects[group].process(dry[group], send[group]);
for c in 0..2 {
frame[c] += values[c] * gain;
}
}
for value in frame {
*value = (*value * self.bus[2]).clamp(-1.0, 1.0);
}
for group in &mut self.groups {
if !group.paused
&& let Some(bank) = &group.bank
{
group.frame = group.frame.wrapping_add(1);
if group.active {
group.time += bank.denominator;
}
if group.stop_after_fade && group.gain.done(group.frame) {
group.active = false;
}
}
}
// Crossfade completion silences/relinquishes notes; bank reclamation is deferred.
for g in 0..2 {
if self.groups[g].stop_after_fade && !self.groups[g].active {
for voice in &mut self.voices[g * 12..g * 12 + 12] {
voice.active = false;
}
self.effects[g].reset();
}
}
self.diagnostics.frames += 1;
}
self.last_processing_time = start.elapsed();
self.diagnostics.last_render_us = self.last_processing_time.as_micros() as u64;
self.diagnostics.maximum_render_us =
self.diagnostics.maximum_render_us.max(self.diagnostics.last_render_us);
}
}
fn lfo(table: &[f64; 4097], age: u64, millihz: u32) -> f64 {
let phase = ((age % 48_000_000) * millihz as u64 % 48_000_000) as f64 / 48_000_000.0 * 4096.0;
let index = phase as usize;
table[index] + (table[index + 1] - table[index]) * (phase - index as f64)
}
fn micros_frames(value: u32) -> u64 {
(value as u64 * 48_000).div_ceil(1_000_000)
}
fn envelope(state: &VoiceState, table: &[f64; 1025]) -> f64 {
let curve = |x: f64| {
if state.inst.curve == 0 {
1.0 - x
} else {
let p = x.clamp(0.0, 1.0) * 1024.0;
let i = (p as usize).min(1023);
table[i] + (table[i + 1] - table[i]) * (p - i as f64)
}
};
if let Some(start) = state.release_age {
let duration = micros_frames(state.inst.release_us);
let elapsed = state.age - start;
return if duration == 0 || elapsed >= duration {
0.0
} else {
state.release_level * curve(elapsed as f64 / duration as f64)
};
}
let attack = micros_frames(state.inst.attack_us);
let decay = micros_frames(state.inst.decay_us);
if state.age < attack {
return state.age as f64 / attack as f64;
}
let sustain = state.inst.sustain as f64 / 65535.0;
if state.age - attack < decay {
sustain + (1.0 - sustain) * curve((state.age - attack) as f64 / decay as f64)
} else {
sustain
}
}
#[cfg(test)]
#[path = "engine_tests.rs"]
mod tests;
@@ -0,0 +1,508 @@
use super::*;
use crate::{Audio, MemoryBanks, SoundBankPoolAccess, SoundBankPoolInstaller};
use prometeu_hal::{AudioBridge, AudioOpStatus, music_bank::AUDIO_PPQ, sound_bank::SoundBank};
fn note(tick: u32, id: u32) -> MusicEvent {
MusicEvent { tick, kind: 1, a: id, c: 60, d: 255, ..Default::default() }
}
fn bank(events: Vec<MusicEvent>, inst: Instrument, tempo: u32, duration: u32) -> Arc<MusicBank> {
Arc::new(
MusicBank::compile(
"test".into(),
vec![Arc::new(
Sample::new(48_000, vec![1024, -2048, 1024, -2048])
.with_channels(2)
.unwrap()
.with_loop(0, 2),
)],
vec![inst],
events,
AUDIO_PPQ,
tempo,
duration,
None,
1,
)
.unwrap(),
)
}
fn pair() -> (Arc<MemoryBanks>, Audio, AudioMixer) {
let banks = Arc::new(MemoryBanks::new());
(banks.clone(), Audio::new(banks), AudioMixer::new())
}
fn publish(audio: &mut Audio, mixer: &mut AudioMixer) {
audio.finish_frame();
mixer.apply_delivery(audio.transport().try_take().unwrap());
}
fn install(banks: &MemoryBanks, slot: usize, events: Vec<MusicEvent>) {
banks.install_music_bank(
slot,
bank(events, Instrument { looping: true, ..Default::default() }, 20_000, 100_000),
);
}
#[test]
fn thirty_two_stereo_voices_have_fixed_group_ownership_and_safe_clipping() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, (0..12).map(|n| note(0, n)).collect());
assert_eq!(audio.music_play(0, 0, true), AudioOpStatus::Ok);
assert_eq!(audio.music_play(1, 0, true), AudioOpStatus::Ok);
let sample = Arc::new(Sample::new(48_000, vec![1024, -2048]));
// Stereo uses one cursor/slot; no channel consumes a second voice.
let sample = Arc::new(
Sample::new(48_000, sample.data.clone()).with_channels(2).unwrap().with_loop(0, 1),
);
for i in 0..8 {
assert_eq!(
audio.play_sample(sample.clone(), i, 255, 128, 1.0, 0, LoopMode::On),
AudioOpStatus::Ok
);
}
assert_eq!(audio.stop(8), AudioOpStatus::VoiceInvalid);
publish(&mut audio, &mut mixer);
let mut pcm = [0.0; 2];
mixer.mix(&mut pcm);
assert_eq!(mixer.voices.iter().filter(|v| v.active).count(), 32);
assert_eq!(mixer.diagnostics.maximum_voices, 32);
assert_eq!(pcm, [1.0, -1.0]);
audio.control(AudioControl::MusicStop { group: 0 });
publish(&mut audio, &mut mixer);
assert!(mixer.voices[..12].iter().all(|v| !v.active));
assert!(mixer.voices[12..].iter().all(|v| v.active));
for i in 0..8 {
audio.stop(i);
}
publish(&mut audio, &mut mixer);
assert!(mixer.voices[12..24].iter().all(|v| v.active));
}
#[test]
fn audio_time_does_not_wait_for_frame_sync_and_buffer_partition_is_invariant() {
let (banks, mut audio, mut a) = pair();
install(&banks, 0, vec![note(17, 1)]);
audio.music_play(0, 0, false);
publish(&mut audio, &mut a);
let mut b = AudioMixer::new();
let resident = banks.music_bank_slot(0).unwrap();
b.process_command(
AudioCommand::MusicPlay { group: 0, bank: resident, looping: false },
&mut Packet::new(),
);
let mut whole = vec![0.0; 4000];
a.mix(&mut whole);
let mut pieces = vec![0.0; 4000];
for piece in pieces.chunks_mut(14) {
b.mix(piece);
}
assert_eq!(whole, pieces);
assert!(whole[..34].iter().all(|&v| v == 0.0));
assert_ne!(whole[34], 0.0);
assert_eq!(a.groups[0].frame, 2000);
}
#[test]
fn fractional_tempo_changes_and_loop_remainder_have_no_cumulative_drift() {
let events = vec![MusicEvent { tick: 2, kind: 3, a: 30_001, ..Default::default() }, note(3, 1)];
let music = bank(events, Instrument::default(), 20_001, 5);
assert_eq!(music.events[1].time, 2 * 20_001u128 * 48_000 + 30_001u128 * 48_000);
let mut mixer = AudioMixer::new();
let end = music.end_time;
let den = music.denominator;
mixer.process_command(
AudioCommand::MusicPlay { group: 0, bank: music, looping: true },
&mut Packet::new(),
);
let n = 100_000;
mixer.mix(&mut vec![0.0; n * 2]);
// The first event of a loop is evaluated before the rendered frame.
assert_eq!(mixer.groups[0].iteration, ((n - 1) as u128 * den / end) as u64);
assert_eq!(mixer.groups[0].time, n as u128 * den - mixer.groups[0].iteration as u128 * end);
}
#[test]
fn music_allocator_uses_free_then_release_then_oldest_and_stale_off_does_not_stop_reuse() {
let (banks, mut audio, mut mixer) = pair();
let mut events: Vec<_> = (0..12).map(|n| note(0, n)).collect();
events.push(MusicEvent { tick: 1, kind: 2, a: 3, ..Default::default() });
events.push(note(2, 12));
events.push(MusicEvent { tick: 3, kind: 2, a: 3, ..Default::default() });
events.push(note(4, 13));
banks.install_music_bank(
0,
bank(
events,
Instrument { looping: true, release_us: 1_000_000, ..Default::default() },
20_000,
1000,
),
);
audio.music_play(0, 0, false);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 10]);
assert_eq!(mixer.states[3].note_id, 12);
assert_eq!(mixer.states[0].note_id, 13);
assert!(mixer.states[3].release_age.is_none());
}
#[test]
fn envelopes_have_exact_endpoints_and_note_off_releases() {
let mut state = VoiceState {
inst: Instrument {
attack_us: 1000,
decay_us: 1000,
sustain: 32768,
release_us: 1000,
curve: 0,
..Default::default()
},
..Default::default()
};
let mut mixer = AudioMixer::new();
for (age, value) in [(0, 0.0), (24, 0.5), (48, 1.0), (96, 32768.0 / 65535.0)] {
state.age = age;
assert!((envelope(&state, &mixer.exponential) - value).abs() < 1e-12);
}
state.release_age = Some(96);
state.release_level = 0.5;
for (age, value) in [(96, 0.5), (120, 0.25), (144, 0.0)] {
state.age = age;
assert!((envelope(&state, &mixer.exponential) - value).abs() < 1e-12);
}
for i in 0..10_000 {
let x = i as f64 / 10_000.0;
state.inst.curve = 1;
state.inst.release_us = 1_000_000;
state.release_age = Some(0);
state.release_level = 1.0;
state.age = (x * 48_000.0) as u64;
let x = state.age as f64 / 48_000.0;
let expected = ((-6.0 * x).exp() - (-6.0f64).exp()) / (1.0 - (-6.0f64).exp());
assert!((envelope(&state, &mixer.exponential) - expected).abs() < 1e-4);
}
let music = bank(
vec![note(0, 1), MusicEvent { tick: 2, kind: 2, a: 1, ..Default::default() }],
Instrument { looping: true, release_us: 1000, ..Default::default() },
20_000,
1000,
);
mixer.process_command(
AudioCommand::MusicPlay { group: 0, bank: music, looping: false },
&mut Packet::new(),
);
mixer.mix(&mut [0.0; 8]);
assert!(mixer.voices[0].active);
mixer.mix(&mut [0.0; 100]);
assert!(!mixer.voices[0].active);
}
#[test]
fn legato_retains_cursor_and_envelope_only_for_same_zone() {
let (banks, mut audio, mut mixer) = pair();
let mut legato = note(1, 2);
legato.flags = 1;
legato.c = 72;
legato.duration_frames = 10;
legato.curve = 1;
install(&banks, 0, vec![note(0, 1), legato]);
audio.music_play(0, 0, false);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 8]);
assert_eq!(mixer.voices[..12].iter().filter(|v| v.active).count(), 1);
assert_eq!(mixer.states[0].age, 4);
assert!((mixer.states[0].cached_cents - 124.8).abs() < 1e-10);
assert_eq!(mixer.states[0].note_id, 2);
assert_eq!(mixer.states[0].glide.to, 1200.0);
}
#[test]
fn pause_freezes_sequence_envelopes_fade_and_effect_timeline() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
audio.music_play(0, 0, true);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 6]);
audio.control(AudioControl::MusicPause { group: 0, paused: true });
publish(&mut audio, &mut mixer);
let before = (mixer.groups[0].time, mixer.states[0].age, mixer.effects[0].write);
let mut pcm = [1.0; 200];
mixer.mix(&mut pcm);
assert_eq!(pcm, [0.0; 200]);
assert_eq!(before, (mixer.groups[0].time, mixer.states[0].age, mixer.effects[0].write));
audio.control(AudioControl::MusicPause { group: 0, paused: false });
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 2]);
assert_eq!(mixer.states[0].age, before.1 + 1);
}
#[test]
fn crossfade_stops_outgoing_group_and_target_keeps_its_sequence() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
audio.music_play(0, 0, true);
audio.music_play(1, 0, true);
audio.control(AudioControl::MusicVolume { group: 1, gain: 0 });
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 10]);
audio.control(AudioControl::Crossfade { source: 0, target: 1, frames: 10, smooth: true });
publish(&mut audio, &mut mixer);
mixer.fill_buffer(&mut [0.0; 20]);
assert!(mixer.groups[0].bank.is_none());
assert_eq!(mixer.groups[1].frame, 15);
assert_eq!(mixer.groups[1].gain.at(15), 1.0);
assert!(mixer.voices[12].active);
}
#[test]
fn shared_delay_has_selective_sends_and_sfx_tails_survive_unload() {
let (banks, mut audio, mut mixer) = pair();
banks.install_sound_bank(
0,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![16384]))])),
);
audio.control(AudioControl::Effect {
group: 2,
cutoff_hz: 0,
delay_frames: 2,
feedback: 0.5,
wet: 1.0,
dry: 0.0,
});
audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::Off);
audio.control(AudioControl::SfxSend { voice: 0, gain: 255 });
publish(&mut audio, &mut mixer);
let mut first = [0.0; 2];
mixer.mix(&mut first);
assert_eq!(first, [0.0; 2]);
banks.unload_audio_bank(false, 0);
let mut tail = [0.0; 8];
mixer.fill_buffer(&mut tail);
assert_eq!(tail, [0.0, 0.0, 0.5, 0.0, 0.0, 0.0, 0.25, 0.0]);
}
#[test]
fn replacing_or_unloading_bank_invalidates_queued_play_and_only_its_resident_instance() {
let (banks, mut audio, mut mixer) = pair();
let source = Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![16384; 4]))]));
banks.install_sound_bank(0, source.clone());
banks.install_sound_bank(1, source);
audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::On);
audio.play(1, 0, 1, 255, 0, 1.0, 0, LoopMode::On);
audio.finish_frame();
banks.unload_audio_bank(false, 0);
mixer.apply_delivery(audio.transport().try_take().unwrap());
assert!(!mixer.voices[24].active);
assert!(mixer.voices[25].active);
install(&banks, 0, vec![note(0, 1)]);
audio.music_play(0, 0, true);
audio.music_play(1, 0, true);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 2]);
banks.unload_audio_bank(true, 0);
mixer.fill_buffer(&mut [0.0; 2]);
assert!(mixer.voices[..24].iter().all(|v| !v.active));
assert!(mixer.groups.iter().all(|g| g.bank.is_none()));
assert!(mixer.voices[25].active);
}
#[test]
fn stealing_respects_release_order_and_serialized_onsets_within_one_frame() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, (0..14).map(|n| note(0, n)).collect());
audio.music_play(0, 0, false);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 2]);
assert_eq!(mixer.states[0].note_id, 12);
assert_eq!(mixer.states[1].note_id, 13);
let mut events: Vec<_> = (0..12).map(|n| note(0, n)).collect();
events.push(MusicEvent { tick: 1, kind: 2, a: 4, ..Default::default() });
events.push(MusicEvent { tick: 2, kind: 2, a: 2, ..Default::default() });
events.push(note(3, 20));
banks.install_music_bank(
0,
bank(
events,
Instrument { looping: true, release_us: 1_000_000, ..Default::default() },
20000,
1000,
),
);
audio.music_play(0, 0, false);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 8]);
assert_eq!(mixer.states[4].note_id, 20);
assert!(mixer.states[2].release_age.is_some());
}
#[test]
fn incompatible_legato_retriggers_the_same_voice_with_no_hidden_polyphony() {
let sample = Arc::new(Sample::new(48000, vec![1000; 8]).with_loop(0, 8));
let mut legato = note(2, 2);
legato.flags = 1;
legato.c = 72;
let music = MusicBank::compile(
"zones".into(),
vec![sample.clone(), sample],
vec![
Instrument { low: 0, high: 63, looping: true, ..Default::default() },
Instrument { low: 64, high: 127, sample: 1, looping: true, ..Default::default() },
],
vec![note(0, 1), legato],
960,
20000,
1000,
None,
1,
)
.unwrap();
let mut mixer = AudioMixer::new();
mixer.process_command(
AudioCommand::MusicPlay { group: 0, bank: Arc::new(music), looping: false },
&mut Packet::new(),
);
mixer.mix(&mut [0.0; 6]);
assert_eq!(mixer.voices[..12].iter().filter(|v| v.active).count(), 1);
assert_eq!(mixer.states[0].age, 1);
assert_eq!(mixer.states[0].zone, 1);
assert_eq!(mixer.states[0].note_id, 2);
}
#[test]
fn parameter_ramps_lfos_and_send_override_use_the_current_audio_value() {
let mut send = SendRamp::default();
assert_eq!(send.at(0, 0.8), 0.8);
send.set(0.0, 0, 100, false);
assert_eq!(send.at(50, 0.8), 0.4);
send.set(1.0, 50, 100, false);
assert_eq!(send.at(50, 0.8), 0.4);
assert!((send.at(100, 0.8) - 0.7).abs() < 1e-12);
assert_eq!(send.at(150, 0.8), 1.0);
let events = vec![
note(0, 1),
MusicEvent { kind: 4, c: 0, duration_frames: 480, ..Default::default() },
MusicEvent { kind: 5, c: 255, duration_frames: 480, ..Default::default() },
MusicEvent { kind: 6, c: 1200, duration_frames: 480, ..Default::default() },
MusicEvent { kind: 7, a: 100000, c: 1200, ..Default::default() },
MusicEvent { kind: 8, a: 100000, c: 65535, ..Default::default() },
];
let mut mixer = AudioMixer::new();
mixer.process_command(
AudioCommand::MusicPlay {
group: 0,
bank: bank(events, Instrument { looping: true, ..Default::default() }, 20000, 1000),
looping: false,
},
&mut Packet::new(),
);
let mut pcm = [0.0; 962];
mixer.mix(&mut pcm);
assert_eq!(&pcm[..2], &[1.0 / 64.0, -1.0 / 32.0]);
assert!(pcm[240].abs() < 1e-8 && pcm[241].abs() < 1e-8);
assert_eq!(&pcm[960..], &[0.0, 0.0]);
assert!(mixer.voices[0].active);
assert_eq!(mixer.groups[0].tracks[0].gain.at(240), 0.5);
assert_eq!(mixer.groups[0].tracks[0].pan.at(240), 191.5);
assert_eq!(mixer.groups[0].tracks[0].pitch.at(240), 600.0);
let mut ramp = Ramp::constant(0.0);
ramp.set(1.0, 0, 100, true);
assert_eq!(ramp.at(0), 0.0);
assert_eq!(ramp.at(50), 0.5);
assert_eq!(ramp.at(100), 1.0);
let endpoint = 1.0 / 65535.0;
ramp.set(endpoint, 100, 100, false);
assert_eq!(ramp.at(200), endpoint);
assert_eq!(ramp.at(1000), endpoint);
}
#[test]
fn music_sfx_and_master_gains_remain_independent_of_group_gain() {
let (_, mut audio, mut mixer) = pair();
audio.play_sample(
Arc::new(Sample::new(48000, vec![16384; 4])),
0,
255,
0,
1.0,
0,
LoopMode::On,
);
audio.control(AudioControl::GroupVolume { group: 2, gain: 128 });
audio.control(AudioControl::BusVolume { bus: 1, gain: 128 });
audio.control(AudioControl::BusVolume { bus: 2, gain: 128 });
publish(&mut audio, &mut mixer);
let mut pcm = [0.0; 2];
mixer.mix(&mut pcm);
assert!((pcm[0] - 0.5 * (128.0f32 / 255.0).powi(3)).abs() < 1e-7);
assert_eq!(pcm[1], 0.0);
}
#[test]
fn invalidating_one_music_slot_clears_only_its_effect_history() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
install(&banks, 1, vec![note(0, 1)]);
audio.music_play(0, 0, true);
audio.music_play(1, 1, true);
for group in 0..2 {
audio.control(AudioControl::Effect {
group,
cutoff_hz: 6000,
delay_frames: 48,
feedback: 0.5,
wet: 0.3,
dry: 0.7,
});
}
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 100]);
banks.unload_audio_bank(true, 0);
mixer.retire_inactive(&mut Packet::new());
assert_eq!(mixer.effects[0].history, 0);
assert_eq!(mixer.effects[1].history, 50);
assert!(mixer.voices[12].active);
}
#[test]
fn crossfade_with_absent_target_does_not_silence_the_active_source() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
audio.music_play(0, 0, true);
audio.control(AudioControl::Crossfade { source: 0, target: 1, frames: 0, smooth: false });
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 2]);
assert!(mixer.groups[0].active);
assert_eq!(mixer.groups[0].gain.at(1), 1.0);
}
#[test]
fn resident_memory_diagnostics_deduplicate_shared_pcm_across_all_slots() {
let banks = MemoryBanks::new();
let sample = Arc::new(Sample::new(48000, vec![1, 2, 3, 4]));
let source = Arc::new(SoundBank::new(vec![sample]));
for slot in 0..16 {
banks.install_sound_bank(slot, source.clone());
banks.install_music_bank(slot, bank(vec![note(0, 1)], Instrument::default(), 20000, 1000));
}
let snapshot = banks.audio_memory();
assert_eq!(snapshot.banks.len(), 32);
assert_eq!(snapshot.unique_pcm_bytes, 8 + 16 * 8);
assert!(snapshot.metadata_bytes > 0);
assert_eq!(
snapshot.total_accounted_bytes,
snapshot.allocated_pcm_bytes + snapshot.metadata_bytes
);
}
#[test]
fn group_configuration_survives_play_stop_and_replacement_but_not_session_reset() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
audio.control(AudioControl::MusicVolume { group: 0, gain: 0 });
audio.music_play(0, 0, true);
publish(&mut audio, &mut mixer);
let mut pcm = [1.0; 2];
mixer.mix(&mut pcm);
assert_eq!(pcm, [0.0; 2]);
assert_eq!(mixer.groups[0].gain.at(0), 0.0);
audio.control(AudioControl::Effect {
group: 0,
cutoff_hz: 1000,
delay_frames: 48,
feedback: 0.5,
wet: 0.5,
dry: 0.5,
});
audio.control(AudioControl::MusicStop { group: 0 });
audio.music_play(0, 0, true);
publish(&mut audio, &mut mixer);
assert_eq!(mixer.groups[0].gain.at(0), 0.0);
assert_eq!(mixer.effects[0].frames, 48);
audio.reset();
mixer.apply_delivery(audio.transport().try_take().unwrap());
assert_eq!(mixer.groups[0].gain.at(0), 1.0);
assert_eq!(mixer.effects[0].frames, 0);
assert_eq!(mixer.effects[0].coefficient, 1.0);
assert_eq!(mixer.effects[0].wet, 0.0);
assert_eq!(mixer.effects[0].dry, 1.0);
}
@@ -0,0 +1,145 @@
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,
alive: None,
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 = let mut bank =
GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1); GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
bank.palette_mut(palette_id).unwrap()[1] = color; bank.palette_mut(palette_id).unwrap()[1] = color;
for pixel in &mut bank.pixel_indices { bank.pixel_indices.fill(1);
*pixel = 1;
}
bank bank
} }
@@ -666,7 +664,7 @@ mod tests {
assert!(frame_composer.bind_scene(0)); assert!(frame_composer.bind_scene(0));
let cache = frame_composer.cache().expect("cache should exist for bound scene"); let cache = frame_composer.cache().expect("cache should exist for bound scene");
assert_eq!((cache.width(), cache.height()), (65, 38)); assert_eq!((cache.width(), cache.height()), (85, 49));
} }
#[test] #[test]
@@ -43,6 +43,8 @@ pub struct Gfx {
front: Vec<u32>, front: Vec<u32>,
/// Back buffer: the working buffer where canonical game frames are composed /// Back buffer: the working buffer where canonical game frames are composed
back: Vec<u32>, back: Vec<u32>,
/// Complete local framebuffer publications, including native Hub/Shell output.
publication_count: u64,
/// Shared access to graphical memory banks (tiles and palettes). /// Shared access to graphical memory banks (tiles and palettes).
pub glyph_banks: Arc<dyn GlyphBankPoolAccess>, pub glyph_banks: Arc<dyn GlyphBankPoolAccess>,
@@ -321,6 +323,7 @@ impl Gfx {
h, h,
front: vec![0; len], front: vec![0; len],
back: vec![0; len], back: vec![0; len],
publication_count: 0,
glyph_banks, glyph_banks,
sprites: [EMPTY_SPRITE; 512], sprites: [EMPTY_SPRITE; 512],
sprite_count: 0, sprite_count: 0,
@@ -570,6 +573,11 @@ impl Gfx {
/// Typically called by the Host when it's time to display the finished frame. /// Typically called by the Host when it's time to display the finished frame.
pub fn present(&mut self) { pub fn present(&mut self) {
std::mem::swap(&mut self.front, &mut self.back); std::mem::swap(&mut self.front, &mut self.back);
self.publication_count = self.publication_count.wrapping_add(1);
}
pub fn publication_count(&self) -> u64 {
self.publication_count
} }
pub fn load_frame_sprites(&mut self, sprites: &[Sprite]) { pub fn load_frame_sprites(&mut self, sprites: &[Sprite]) {
+31 -23
View File
@@ -12,7 +12,7 @@ use prometeu_hal::cartridge::AssetsPayloadSource;
use prometeu_hal::sprite::Sprite; use prometeu_hal::sprite::Sprite;
use prometeu_hal::{ use prometeu_hal::{
AssetBridge, AudioBridge, InputPlatform, NoopTelemetryPlatform, PadBridge, RenderBackend, AssetBridge, AudioBridge, InputPlatform, NoopTelemetryPlatform, PadBridge, RenderBackend,
RuntimePlatform, TelemetryPlatform, TouchBridge, RuntimePlatform, TelemetryPlatform, TouchBridge, WallClock,
}; };
use prometeu_hal::{ use prometeu_hal::{
Game2DFrameComposer, Game2DFramePacket, RenderSubmission, RenderSubmissionPacket, Game2DFrameComposer, Game2DFramePacket, RenderSubmission, RenderSubmissionPacket,
@@ -28,11 +28,12 @@ use std::sync::Arc;
/// for easier testing and different host implementations (Desktop, Web, etc.). /// for easier testing and different host implementations (Desktop, Web, etc.).
/// ///
/// ### Console Specifications: /// ### Console Specifications:
/// - **Resolution**: 480x270 (16:9 Aspect Ratio). /// - **Resolution**: 640x360 (16:9 Aspect Ratio).
/// - **Color Format**: RGBA8888. /// - **Color Format**: RGBA8888.
/// - **Audio**: Stereo, Command-based mixing. /// - **Audio**: Stereo, Command-based mixing.
/// - **Input**: 12-button Digital Gamepad + Absolute Touch/Mouse. /// - **Input**: 12-button Digital Gamepad + Absolute Touch/Mouse.
pub struct Hardware { pub struct Hardware {
wall_clock: Arc<dyn WallClock>,
/// Shared physical memory bank ownership used by peripherals and worker backends. /// Shared physical memory bank ownership used by peripherals and worker backends.
pub memory_banks: Arc<MemoryBanks>, pub memory_banks: Arc<MemoryBanks>,
/// The Graphics Processing Unit (GPU). Handles drawing primitives, sprites, and tilemaps. /// The Graphics Processing Unit (GPU). Handles drawing primitives, sprites, and tilemaps.
@@ -49,12 +50,6 @@ pub struct Hardware {
pub assets: AssetManager, pub assets: AssetManager,
} }
impl Default for Hardware {
fn default() -> Self {
Self::new()
}
}
impl Hardware { impl Hardware {
fn consume_render_submission(&mut self, submission: &RenderSubmission) { fn consume_render_submission(&mut self, submission: &RenderSubmission) {
match &submission.packet { match &submission.packet {
@@ -159,6 +154,10 @@ impl InputPlatform for Hardware {
static NOOP_TELEMETRY: NoopTelemetryPlatform = NoopTelemetryPlatform; static NOOP_TELEMETRY: NoopTelemetryPlatform = NoopTelemetryPlatform;
impl RuntimePlatform for Hardware { impl RuntimePlatform for Hardware {
fn wall_clock(&self) -> &dyn WallClock {
self.wall_clock.as_ref()
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink { fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self self
} }
@@ -202,17 +201,20 @@ impl RuntimePlatform for Hardware {
impl Hardware { impl Hardware {
/// Internal hardware width in pixels. /// Internal hardware width in pixels.
pub const W: usize = 480; pub const W: usize = prometeu_hal::graphics_contract::WIDTH;
/// Internal hardware height in pixels. /// Internal hardware height in pixels.
pub const H: usize = 270; pub const H: usize = prometeu_hal::graphics_contract::HEIGHT;
/// Creates a fresh hardware instance with default settings. /// Creates a fresh hardware instance with default settings.
pub fn new() -> Self { pub fn new(wall_clock: Arc<dyn WallClock>) -> Self {
Self::new_with_memory_banks(Arc::new(MemoryBanks::new())) Self::new_with_memory_banks(Arc::new(MemoryBanks::new()), wall_clock)
} }
/// Creates hardware with explicit shared bank ownership. /// 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( let assets = AssetManager::new(
vec![], vec![],
AssetsPayloadSource::empty(), AssetsPayloadSource::empty(),
@@ -222,6 +224,7 @@ impl Hardware {
); );
let glyph_slot_index = assets.glyph_asset_slot_index(); let glyph_slot_index = assets.glyph_asset_slot_index();
Self { Self {
wall_clock,
memory_banks: Arc::clone(&memory_banks), memory_banks: Arc::clone(&memory_banks),
gfx: Gfx::new( gfx: Gfx::new(
Self::W, Self::W,
@@ -266,9 +269,7 @@ mod tests {
fn make_glyph_bank() -> GlyphBank { fn make_glyph_bank() -> GlyphBank {
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8); let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
bank.palette_mut(0).unwrap()[1] = Color::RED; bank.palette_mut(0).unwrap()[1] = Color::RED;
for pixel in &mut bank.pixel_indices { bank.pixel_indices.fill(1);
*pixel = 1;
}
bank bank
} }
@@ -306,7 +307,10 @@ mod tests {
banks.install_glyph_bank(0, Arc::new(make_glyph_bank())); banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
banks.install_scene_bank(0, Arc::new(make_scene_with_glyph_asset_id(0))); 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 scene = banks.scene_bank_slot(0).expect("scene bank slot 0 should be resident");
let mut cache = SceneViewportCache::new(&scene, 4, 4); let mut cache = SceneViewportCache::new(&scene, 4, 4);
cache.materialize_all_layers(&scene); cache.materialize_all_layers(&scene);
@@ -325,7 +329,8 @@ mod tests {
let banks = Arc::new(MemoryBanks::new()); let banks = Arc::new(MemoryBanks::new());
banks.install_scene_bank(2, Arc::new(make_scene())); 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 let scene = hardware
.frame_composer .frame_composer
.scene_bank_slot(2) .scene_bank_slot(2)
@@ -342,7 +347,8 @@ mod tests {
banks.install_glyph_bank(0, Arc::new(make_glyph_bank())); banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
banks.install_scene_bank(0, Arc::new(make_scene_with_glyph_asset_id(0))); 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]; let mut glyph_slots = [None; 16];
glyph_slots[0] = Some(0); glyph_slots[0] = Some(0);
hardware.assets.glyph_asset_slot_index().rebuild_from_slots(&glyph_slots); 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_glyph_bank(0, Arc::new(make_glyph_bank()));
banks.install_scene_bank(0, Arc::new(make_scene_with_glyph_asset_id(0))); 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]; let mut glyph_slots = [None; 16];
glyph_slots[0] = Some(0); glyph_slots[0] = Some(0);
hardware.assets.glyph_asset_slot_index().rebuild_from_slots(&glyph_slots); hardware.assets.glyph_asset_slot_index().rebuild_from_slots(&glyph_slots);
@@ -413,7 +420,7 @@ mod tests {
#[test] #[test]
fn render_submission_sink_accepts_owned_game2d_submission() { 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( let packet = Game2DFramePacket::new(
ComposerFramePacket::default(), ComposerFramePacket::default(),
vec![Gfx2dCommand::Clear { color: Color::BLUE }], vec![Gfx2dCommand::Clear { color: Color::BLUE }],
@@ -428,7 +435,7 @@ mod tests {
#[test] #[test]
fn render_submission_sink_accepts_owned_shell_ui_submission() { 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 packet = ShellUiFramePacket::new(vec![GfxUiCommand::Clear { color: Color::RED }]);
let submission = RenderSubmission::shell_ui(FrameId::ZERO, packet); let submission = RenderSubmission::shell_ui(FrameId::ZERO, packet);
@@ -442,7 +449,8 @@ mod tests {
fn emit_sprite_rejects_palette_id_outside_loaded_glyph_bank() { fn emit_sprite_rejects_palette_id_outside_loaded_glyph_bank() {
let banks = Arc::new(MemoryBanks::new()); let banks = Arc::new(MemoryBanks::new());
banks.install_glyph_bank(0, Arc::new(make_glyph_bank())); 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( let status = Game2DFrameComposer::emit_sprite(
&mut hardware, &mut hardware,
+13 -1
View File
@@ -5,12 +5,19 @@ mod gfx;
pub mod hardware; pub mod hardware;
mod local_render_backend; mod local_render_backend;
mod memory_banks; mod memory_banks;
#[cfg(test)]
mod native_graphics_tests;
mod pad; mod pad;
mod test_platform; mod test_platform;
mod touch; mod touch;
mod wall_clock;
pub use crate::asset::AssetManager; pub use crate::asset::AssetManager;
pub use crate::audio::{Audio, AudioCommand, Channel, MAX_CHANNELS, OUTPUT_SAMPLE_RATE}; pub use crate::audio::bank_format;
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::frame_composer::{ComposerBuffer, FrameComposer, SceneStatus, SpriteController};
pub use crate::gfx::Gfx; pub use crate::gfx::Gfx;
pub use crate::local_render_backend::LocalFramebufferRenderBackend; pub use crate::local_render_backend::LocalFramebufferRenderBackend;
@@ -20,3 +27,8 @@ pub use crate::memory_banks::{
}; };
pub use crate::pad::Pad; pub use crate::pad::Pad;
pub use crate::test_platform::TestPlatform; pub use crate::test_platform::TestPlatform;
pub use crate::wall_clock::ControlledWallClock;
pub mod memcard;
pub use crate::audio::{SFX_CHANNELS, SFX_START, engine};
@@ -0,0 +1,130 @@
//! 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::AccessDenied,
K::AlreadyExists => Error::AlreadyExists,
K::StorageFull => Error::NoSpace,
K::InvalidInput | K::UnexpectedEof => Error::InvalidRange,
K::Unsupported => Error::Unsupported,
_ => Error::IoError,
}
}
impl FileMemcard {
fn lock(file: &File) -> Result<(), Error> {
file.try_lock().map_err(|error| match error {
std::fs::TryLockError::WouldBlock => Error::Busy,
std::fs::TryLockError::Error(error) => io_error(error),
})
}
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)?;
Self::lock(&file)?;
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 mut published = false;
let result = (|| {
Self::lock(&file)?;
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)?;
published = true;
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(|_| Error::Indeterminate)?;
Ok(card)
}
Err(e) => Err(if published { Error::Indeterminate } else { 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)
}
}
@@ -7,6 +7,7 @@
//! the render read surface. //! the render read surface.
use prometeu_hal::glyph_bank::GlyphBank; use prometeu_hal::glyph_bank::GlyphBank;
use prometeu_hal::music_bank::MusicBank;
use prometeu_hal::render_resources::RenderResourceAccess as HalRenderResourceAccess; use prometeu_hal::render_resources::RenderResourceAccess as HalRenderResourceAccess;
use prometeu_hal::scene_bank::SceneBank; use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::sound_bank::SoundBank; use prometeu_hal::sound_bank::SoundBank;
@@ -30,6 +31,7 @@ pub trait GlyphBankPoolInstaller: Send + Sync {
/// Non-generic interface for peripherals to access sound banks. /// Non-generic interface for peripherals to access sound banks.
pub trait SoundBankPoolAccess: Send + Sync { pub trait SoundBankPoolAccess: Send + Sync {
fn music_bank_slot(&self, slot: usize) -> Option<Arc<MusicBank>>;
/// Returns a reference to the resident SoundBank in the specified slot, if any. /// Returns a reference to the resident SoundBank in the specified slot, if any.
fn sound_bank_slot(&self, slot: usize) -> Option<Arc<SoundBank>>; fn sound_bank_slot(&self, slot: usize) -> Option<Arc<SoundBank>>;
/// Returns the total number of slots available in this bank. /// Returns the total number of slots available in this bank.
@@ -38,6 +40,9 @@ pub trait SoundBankPoolAccess: Send + Sync {
/// Non-generic interface for the AssetManager to install sound banks. /// Non-generic interface for the AssetManager to install sound banks.
pub trait SoundBankPoolInstaller: Send + Sync { pub trait SoundBankPoolInstaller: Send + Sync {
fn install_music_bank(&self, slot: usize, bank: Arc<MusicBank>);
fn clear_music_banks(&self);
fn unload_audio_bank(&self, music: bool, slot: usize);
/// Atomically swaps the resident SoundBank in the specified slot. /// Atomically swaps the resident SoundBank in the specified slot.
fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>); fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>);
/// Clears all resident SoundBank slots. /// Clears all resident SoundBank slots.
@@ -68,6 +73,7 @@ pub trait SceneBankPoolInstaller: Send + Sync {
pub struct MemoryBanks { pub struct MemoryBanks {
glyph_bank_pool: Arc<RwLock<[Option<Arc<GlyphBank>>; 16]>>, glyph_bank_pool: Arc<RwLock<[Option<Arc<GlyphBank>>; 16]>>,
sound_bank_pool: Arc<RwLock<[Option<Arc<SoundBank>>; 16]>>, sound_bank_pool: Arc<RwLock<[Option<Arc<SoundBank>>; 16]>>,
music_bank_pool: Arc<RwLock<[Option<Arc<MusicBank>>; 16]>>,
scene_bank_pool: Arc<RwLock<[Option<Arc<SceneBank>>; 16]>>, scene_bank_pool: Arc<RwLock<[Option<Arc<SceneBank>>; 16]>>,
} }
@@ -83,6 +89,7 @@ impl MemoryBanks {
Self { Self {
glyph_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), glyph_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
sound_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), sound_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
music_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
scene_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), scene_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
} }
} }
@@ -113,6 +120,9 @@ impl GlyphBankPoolInstaller for MemoryBanks {
} }
impl SoundBankPoolAccess for MemoryBanks { impl SoundBankPoolAccess for MemoryBanks {
fn music_bank_slot(&self, slot: usize) -> Option<Arc<MusicBank>> {
self.music_bank_pool.read().unwrap().get(slot).and_then(Clone::clone)
}
fn sound_bank_slot(&self, slot: usize) -> Option<Arc<SoundBank>> { fn sound_bank_slot(&self, slot: usize) -> Option<Arc<SoundBank>> {
let pool = self.sound_bank_pool.read().unwrap(); let pool = self.sound_bank_pool.read().unwrap();
pool.get(slot).and_then(|s| s.as_ref().map(Arc::clone)) pool.get(slot).and_then(|s| s.as_ref().map(Arc::clone))
@@ -124,15 +134,61 @@ impl SoundBankPoolAccess for MemoryBanks {
} }
impl SoundBankPoolInstaller for MemoryBanks { impl SoundBankPoolInstaller for MemoryBanks {
fn install_music_bank(&self, slot: usize, bank: Arc<MusicBank>) {
if slot >= 16 {
return;
}
let prepared = Arc::new(bank.resident_copy());
let mut pool = self.music_bank_pool.write().unwrap();
if let Some(target) = pool.get_mut(slot) {
if let Some(old) = target.take() {
old.invalidate();
}
*target = Some(prepared);
}
}
fn clear_music_banks(&self) {
let mut pool = self.music_bank_pool.write().unwrap();
for bank in pool.iter_mut() {
if let Some(old) = bank.take() {
old.invalidate();
}
}
}
fn unload_audio_bank(&self, music: bool, slot: usize) {
if music {
if let Some(bank) =
self.music_bank_pool.write().unwrap().get_mut(slot).and_then(Option::take)
{
bank.invalidate();
}
} else if let Some(bank) =
self.sound_bank_pool.write().unwrap().get_mut(slot).and_then(Option::take)
{
bank.invalidate();
}
}
fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>) { fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>) {
if slot >= 16 {
return;
}
let prepared = Arc::new(bank.resident_copy());
let mut pool = self.sound_bank_pool.write().unwrap(); let mut pool = self.sound_bank_pool.write().unwrap();
if slot < 16 { if slot < 16 {
pool[slot] = Some(bank); if let Some(old) = pool[slot].take() {
old.invalidate();
}
pool[slot] = Some(prepared);
} }
} }
fn clear_sound_banks(&self) { fn clear_sound_banks(&self) {
self.sound_bank_pool.write().unwrap().fill(None); let mut pool = self.sound_bank_pool.write().unwrap();
for bank in pool.iter_mut() {
if let Some(old) = bank.take() {
old.invalidate();
}
}
} }
} }
@@ -246,3 +302,84 @@ mod tests {
assert_eq!(HalRenderResourceAccess::scene_bank_count(&banks), 16); assert_eq!(HalRenderResourceAccess::scene_bank_count(&banks), 16);
} }
} }
/// Owner-thread diagnostics: canonical bank costs and unique PCM allocation costs
/// are separate, so loading the same asset in two slots does not double-count RAM.
#[derive(Debug, Clone)]
pub struct AudioSlotMemory {
pub music: bool,
pub slot: usize,
pub name: String,
pub metrics: prometeu_hal::sound_bank::AudioBankMetrics,
}
#[derive(Debug, Default)]
pub struct AudioMemorySnapshot {
pub banks: Vec<AudioSlotMemory>,
pub unique_pcm_bytes: usize,
pub allocated_pcm_bytes: usize,
/// Resident Rust structs/vector/string capacities; excludes allocator/Arc headers and host caches.
pub metadata_bytes: usize,
pub total_accounted_bytes: usize,
}
impl MemoryBanks {
pub fn audio_memory(&self) -> AudioMemorySnapshot {
let mut snapshot = AudioMemorySnapshot::default();
let mut seen = std::collections::HashSet::new();
let mut metadata = 0usize;
let mut vectors = std::collections::HashSet::new();
let mut add =
|music, slot, name: String, metrics, samples: &[Arc<prometeu_hal::sample::Sample>]| {
for sample in samples {
if seen.insert(Arc::as_ptr(sample)) {
metadata += std::mem::size_of::<prometeu_hal::sample::Sample>();
snapshot.unique_pcm_bytes += sample.data.len() * 2;
snapshot.allocated_pcm_bytes += sample.data.capacity() * 2;
}
}
snapshot.banks.push(AudioSlotMemory { music, slot, name, metrics });
};
for (slot, bank) in self.sound_bank_pool.read().unwrap().iter().enumerate() {
if let Some(b) = bank {
add(false, slot, b.name.clone(), b.metrics, &b.samples);
snapshot.metadata_bytes += std::mem::size_of::<SoundBank>()
+ b.name.capacity()
+ std::mem::size_of::<std::sync::atomic::AtomicBool>();
if vectors.insert(Arc::as_ptr(&b.samples) as usize) {
snapshot.metadata_bytes += std::mem::size_of::<
Vec<Arc<prometeu_hal::sample::Sample>>,
>() + b.samples.capacity()
* std::mem::size_of::<Arc<prometeu_hal::sample::Sample>>();
}
}
}
for (slot, bank) in self.music_bank_pool.read().unwrap().iter().enumerate() {
if let Some(b) = bank {
add(true, slot, b.name.clone(), b.metrics, &b.samples);
snapshot.metadata_bytes += std::mem::size_of::<MusicBank>()
+ b.name.capacity()
+ std::mem::size_of::<std::sync::atomic::AtomicBool>();
if vectors.insert(Arc::as_ptr(&b.samples) as usize) {
snapshot.metadata_bytes += std::mem::size_of::<
Vec<Arc<prometeu_hal::sample::Sample>>,
>() + b.samples.capacity()
* std::mem::size_of::<Arc<prometeu_hal::sample::Sample>>();
}
if vectors.insert(Arc::as_ptr(&b.instruments) as usize) {
snapshot.metadata_bytes += std::mem::size_of::<
Vec<prometeu_hal::music_bank::Instrument>,
>() + b.instruments.capacity()
* std::mem::size_of::<prometeu_hal::music_bank::Instrument>();
}
if vectors.insert(Arc::as_ptr(&b.events) as usize) {
snapshot.metadata_bytes += std::mem::size_of::<
Vec<prometeu_hal::music_bank::TimedMusicEvent>,
>() + b.events.capacity()
* std::mem::size_of::<prometeu_hal::music_bank::TimedMusicEvent>();
}
}
}
snapshot.metadata_bytes += metadata;
snapshot.total_accounted_bytes = snapshot.allocated_pcm_bytes + snapshot.metadata_bytes;
snapshot
}
}
@@ -0,0 +1,109 @@
use crate::{Gfx, GlyphBankPoolInstaller, MemoryBanks};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{GlyphBank, TileSize};
use prometeu_hal::graphics_contract::{FRAME_BYTES, HEIGHT, PIXELS, WIDTH};
use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::scene_viewport_cache::SceneViewportCache;
use prometeu_hal::scene_viewport_resolver::SceneViewportResolver;
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use std::sync::Arc;
#[test]
fn native_allocation_stride_corners_and_external_coordinates() {
let mut gfx = Gfx::new(WIDTH, HEIGHT, Arc::new(MemoryBanks::new()));
assert_eq!(gfx.publication_count(), 0);
gfx.clear(Color::BLACK);
for (x, y) in [(0, 0), (639, 0), (0, 359), (639, 359)] {
gfx.draw_pixel(x, y, Color::RED);
}
for (x, y) in [(-1, 0), (640, 359), (639, 360), (0, -1)] {
gfx.draw_pixel(x, y, Color::GREEN);
}
assert_eq!(gfx.publication_count(), 0, "drawing is not a complete publication");
gfx.present();
assert_eq!(gfx.publication_count(), 1);
let front = gfx.front_buffer();
assert_eq!(gfx.size(), (640, 360));
assert_eq!(front.len(), PIXELS);
assert_eq!(std::mem::size_of_val(front), FRAME_BYTES);
for index in [0, 639, 359 * WIDTH, PIXELS - 1] {
assert_eq!(front[index], Color::RED.raw());
}
assert_eq!(front.iter().filter(|&&p| p == Color::RED.raw()).count(), 4);
gfx.present();
assert_eq!(gfx.publication_count(), 2, "each complete swap is a publication");
}
#[test]
fn native_tile_edges_and_mixed_camera_layers_cover_every_corner() {
for sizes in [
[TileSize::Size8; 4],
[TileSize::Size16; 4],
[TileSize::Size32; 4],
[TileSize::Size8, TileSize::Size16, TileSize::Size32, TileSize::Size8],
] {
let banks = Arc::new(MemoryBanks::new());
let colors = [Color::RED, Color::GREEN, Color::BLUE, Color::WHITE];
for i in 0..4 {
let n = sizes[i] as usize;
let mut bank = GlyphBank::new(sizes[i], n, n);
bank.palettes[0][1] = colors[i];
bank.pixel_indices.fill(1);
banks.install_glyph_bank(i, Arc::new(bank));
}
let scene = SceneBank {
layers: std::array::from_fn(|i| SceneLayer {
active: true,
glyph_asset_id: i as i32,
tile_size: sizes[i],
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap {
width: 160,
height: 120,
tiles: vec![
Tile {
active: true,
glyph: Glyph { glyph_id: 0, palette_id: 0 },
flip_x: true,
flip_y: true,
};
160 * 120
],
},
}),
};
let min = sizes.iter().map(|s| *s as usize).min().unwrap();
let (cw, ch) = (WIDTH.div_ceil(min) + 5, HEIGHT.div_ceil(min) + 4);
let mut cache = SceneViewportCache::new(&scene, cw, ch);
let mut resolver = SceneViewportResolver::new(
WIDTH as i32,
HEIGHT as i32,
cw,
ch,
min as i32 - 4,
min as i32 + 4,
);
let mut gfx = Gfx::new(WIDTH, HEIGHT, banks);
for (x, y) in [(0, 0), (1, 1), (7, 7), (15, 15), (31, 31), (400, 300), (2, 3)] {
let update = resolver.update(&scene, x, y);
for request in &update.copy_requests {
cache.move_layer_window_to(
request.layer_index,
request.cache_origin_tile_x,
request.cache_origin_tile_y,
);
}
cache.materialize_all_layers(&scene);
gfx.render_scene_from_cache(&cache, &update, &[0, 1, 2, 3]);
gfx.present();
// Every pixel, including rows 352..359, must be supplied by the last layer.
assert!(
gfx.front_buffer().iter().all(|&p| p == Color::WHITE.raw()),
"sizes={sizes:?}, camera=({x},{y})"
);
}
}
}
@@ -1,13 +1,15 @@
use crate::ControlledWallClock;
use crate::hardware::Hardware; use crate::hardware::Hardware;
use crate::memory_banks::MemoryBanks; use crate::memory_banks::MemoryBanks;
use prometeu_hal::{ use prometeu_hal::{
AssetBridge, AudioBridge, Game2DFrameComposer, InputPlatform, RenderBackend, AssetBridge, AudioBridge, Game2DFrameComposer, InputPlatform, RenderBackend,
RenderSubmissionSink, RuntimePlatform, TelemetryPlatform, RenderSubmissionSink, RuntimePlatform, TelemetryPlatform, WallClock,
}; };
use std::sync::Arc; use std::sync::Arc;
pub struct TestPlatform { pub struct TestPlatform {
hardware: Hardware, hardware: Hardware,
controlled_wall_clock: Option<Arc<ControlledWallClock>>,
} }
impl Default for TestPlatform { impl Default for TestPlatform {
@@ -18,11 +20,24 @@ impl Default for TestPlatform {
impl TestPlatform { impl TestPlatform {
pub fn new() -> Self { 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 { 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 { pub fn local_hardware(&self) -> &Hardware {
@@ -35,6 +50,10 @@ impl TestPlatform {
} }
impl RuntimePlatform for TestPlatform { impl RuntimePlatform for TestPlatform {
fn wall_clock(&self) -> &dyn WallClock {
self.hardware.wall_clock()
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink { fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self.hardware.render_submission_sink() self.hardware.render_submission_sink()
} }
@@ -93,8 +112,26 @@ mod tests {
Game2DFramePacket::default(), Game2DFramePacket::default(),
)) ))
.expect("test platform render sink should accept local submission"); .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.input().pad().any());
assert!(platform.telemetry().telemetry_snapshot().is_none()); 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,59 @@
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.
// `try_update` requires Rust 1.95; keep older stable CI toolchains compatible.
#[allow(deprecated)]
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] [dev-dependencies]
prometeu-drivers = { path = "../prometeu-drivers" } prometeu-drivers = { path = "../prometeu-drivers" }
prometeu-bytecode = { path = "../prometeu-bytecode" } 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, FirmwareState, GameRunningStep, LoadCartridgeStep, ResetStep,
}; };
use crate::firmware::prometeu_context::PrometeuContext; use crate::firmware::prometeu_context::PrometeuContext;
#[cfg(test)]
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_hal::app_mode::AppMode; use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::Cartridge; use prometeu_hal::cartridge::Cartridge;
use prometeu_hal::log::LogSource; use prometeu_hal::log::LogSource;
use prometeu_hal::telemetry::CertificationConfig; use prometeu_hal::telemetry::CertificationConfig;
use prometeu_hal::{InputSignals, RuntimePlatform}; use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_system::{PrometeuHub, ResidentGameState, SystemOS}; use prometeu_system::{PrometeuHub, ResidentGameState, SystemOS};
#[cfg(test)]
use prometeu_test_support::program::{TestProgram, int64_signature};
/// PROMETEU Firmware. /// PROMETEU Firmware.
/// ///
@@ -57,6 +61,56 @@ impl Firmware {
/// This method is called exactly once per Host frame (60Hz). /// This method is called exactly once per Host frame (60Hz).
/// It updates peripheral signals and delegates the logic to the current state. /// It updates peripheral signals and delegates the logic to the current state.
pub fn tick(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) { 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 barriered_signals = InputSignals::default();
let effective_signals = if self.game_input_barrier_frames > 0 { let effective_signals = if self.game_input_barrier_frames > 0 {
self.game_input_barrier_frames -= 1; self.game_input_barrier_frames -= 1;
@@ -79,6 +133,40 @@ impl Firmware {
self.state_initialized = true; 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. // 3. Update the current state and check for transitions.
if let Some(next_state) = self.on_update(effective_signals, platform) { if let Some(next_state) = self.on_update(effective_signals, platform) {
self.change_state(next_state, 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::SplashScreen(s) => s.on_enter(&mut req),
FirmwareState::LaunchHub(s) => s.on_enter(&mut req), FirmwareState::LaunchHub(s) => s.on_enter(&mut req),
FirmwareState::HubHome(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::LoadCartridge(s) => s.on_enter(&mut req),
FirmwareState::ResumeResidentGame => {} FirmwareState::ResumeResidentGame | FirmwareState::MemoryIoFault => {}
FirmwareState::GameRunning(s) => s.on_enter(&mut req), FirmwareState::GameRunning(s) => s.on_enter(&mut req),
FirmwareState::ShellRunning(s) => s.on_enter(&mut req), FirmwareState::ShellRunning(s) => s.on_enter(&mut req),
FirmwareState::AppCrashes(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::SplashScreen(s) => s.on_update(&mut req),
FirmwareState::LaunchHub(s) => s.on_update(&mut req), FirmwareState::LaunchHub(s) => s.on_update(&mut req),
FirmwareState::HubHome(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::LoadCartridge(s) => s.on_update(&mut req),
FirmwareState::ResumeResidentGame => None, 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::GameRunning(s) => s.on_update(&mut req),
FirmwareState::ShellRunning(s) => s.on_update(&mut req), FirmwareState::ShellRunning(s) => s.on_update(&mut req),
FirmwareState::AppCrashes(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::SplashScreen(s) => s.on_exit(&mut req),
FirmwareState::LaunchHub(s) => s.on_exit(&mut req), FirmwareState::LaunchHub(s) => s.on_exit(&mut req),
FirmwareState::HubHome(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::LoadCartridge(s) => s.on_exit(&mut req),
FirmwareState::ResumeResidentGame => {} FirmwareState::ResumeResidentGame | FirmwareState::MemoryIoFault => {}
FirmwareState::GameRunning(s) => s.on_exit(&mut req), FirmwareState::GameRunning(s) => s.on_exit(&mut req),
FirmwareState::ShellRunning(s) => s.on_exit(&mut req), FirmwareState::ShellRunning(s) => s.on_exit(&mut req),
FirmwareState::AppCrashes(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::firmware_state::HubHomeStep;
use crate::firmware::resident_game_termination::{self, ResidentGameTerminationOutcome}; use crate::firmware::resident_game_termination::{self, ResidentGameTerminationOutcome};
use prometeu_bytecode::assembler::assemble; 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_drivers::{GlyphBankPoolAccess, SceneBankPoolAccess, TestPlatform};
use prometeu_hal::RuntimePlatform; use prometeu_hal::RuntimePlatform;
use prometeu_hal::app_mode::AppMode; use prometeu_hal::app_mode::AppMode;
@@ -345,13 +461,18 @@ mod tests {
fn halting_program() -> Vec<u8> { fn halting_program() -> Vec<u8> {
let code = assemble("HALT").expect("assemble"); let code = assemble("HALT").expect("assemble");
BytecodeModule { TestProgram {
version: 0,
const_pool: vec![], const_pool: vec![],
functions: vec![FunctionMeta { functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0, code_offset: 0,
code_len: code.len() as u32, 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, code,
debug_info: None, debug_info: None,
@@ -367,6 +488,7 @@ mod tests {
fn invalid_game_cartridge() -> Cartridge { fn invalid_game_cartridge() -> Cartridge {
Cartridge { Cartridge {
memcard_slots: None,
app_id: 7, app_id: 7,
title: "Broken Cart".into(), title: "Broken Cart".into(),
app_version: "1.0.0".into(), app_version: "1.0.0".into(),
@@ -381,13 +503,18 @@ mod tests {
fn trapping_game_cartridge() -> Cartridge { fn trapping_game_cartridge() -> Cartridge {
let code = assemble("PUSH_BOOL 1\nHOSTCALL 0\nHALT").expect("assemble"); let code = assemble("PUSH_BOOL 1\nHOSTCALL 0\nHALT").expect("assemble");
let program = BytecodeModule { let program = TestProgram {
version: 0,
const_pool: vec![], const_pool: vec![],
functions: vec![FunctionMeta { functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0, code_offset: 0,
code_len: code.len() as u32, 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, code,
debug_info: None, debug_info: None,
@@ -403,6 +530,7 @@ mod tests {
.serialize(); .serialize();
Cartridge { Cartridge {
memcard_slots: None,
app_id: 8, app_id: 8,
title: "Trap Cart".into(), title: "Trap Cart".into(),
app_version: "1.0.0".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 { fn valid_cartridge_with(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
Cartridge { Cartridge {
memcard_slots: None,
app_id, app_id,
title: title.into(), title: title.into(),
app_version: "1.0.0".into(), app_version: "1.0.0".into(),
@@ -480,11 +609,20 @@ mod tests {
} }
fn front_buffer_pixel(platform: &TestPlatform, x: i32, y: i32) -> u32 { fn front_buffer_pixel(platform: &TestPlatform, x: i32, y: i32) -> u32 {
const FRAMEBUFFER_WIDTH: usize = 480; const FRAMEBUFFER_WIDTH: usize = prometeu_hal::graphics_contract::WIDTH;
let index = x as usize + y as usize * FRAMEBUFFER_WIDTH; let index = x as usize + y as usize * FRAMEBUFFER_WIDTH;
platform.local_hardware().gfx.front_buffer()[index] 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] #[test]
fn load_cartridge_transitions_to_app_crashes_when_vm_init_fails() { fn load_cartridge_transitions_to_app_crashes_when_vm_init_fails() {
let mut firmware = Firmware::new(None); let mut firmware = Firmware::new(None);
@@ -497,7 +635,7 @@ mod tests {
match &firmware.state { match &firmware.state {
FirmwareState::AppCrashes(step) => match &step.report { FirmwareState::AppCrashes(step) => match &step.report {
CrashReport::VmInit { error } => { 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), other => panic!("expected VmInit crash report, got {:?}", other),
}, },
@@ -579,6 +717,8 @@ mod tests {
assert_eq!(firmware.os.sessions().vm_session_count(), 0); assert_eq!(firmware.os.sessions().vm_session_count(), 0);
assert_eq!(firmware.os.vm().current_cartridge_title(), ""); assert_eq!(firmware.os.vm().current_cartridge_title(), "");
assert_eq!(firmware.os.lifecycle().resident_game(), None);
assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
} }
#[test] #[test]
@@ -679,7 +819,10 @@ mod tests {
root.add_game("stress", true); root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware(); 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); firmware.tick(&InputSignals::default(), &mut platform);
let signals = InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() }; let signals = InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
@@ -700,7 +843,10 @@ mod tests {
root.add_game("stress", true); root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware(); 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); firmware.tick(&InputSignals::default(), &mut platform);
let signals = InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() }; let signals = InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
@@ -718,7 +864,10 @@ mod tests {
root.add_game("stress", true); root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware(); 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); firmware.tick(&InputSignals::default(), &mut platform);
let launch_click = let launch_click =
@@ -773,7 +922,10 @@ mod tests {
root.add_game_with_identity("zzz-dummy", 43, "Zzz Dummy", "1.0.0", true); root.add_game_with_identity("zzz-dummy", 43, "Zzz Dummy", "1.0.0", true);
let (mut firmware, mut platform) = hub_home_firmware(); 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); firmware.tick(&InputSignals::default(), &mut platform);
let stress_click = let stress_click =
@@ -834,7 +986,10 @@ mod tests {
#[test] #[test]
fn repository_stress_to_dummy_boy_switch_is_end_to_end() { 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!( assert!(
library library
.entries() .entries()
@@ -854,6 +1009,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform); firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state { let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id, FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other), other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -868,6 +1024,10 @@ mod tests {
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id, platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1) Some(1)
); );
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::MUSIC, index: 0 }).asset_id,
Some(201)
);
firmware.request_home_from_host(); firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
@@ -882,6 +1042,10 @@ mod tests {
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id, platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1) Some(1)
); );
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::MUSIC, index: 0 }).asset_id,
Some(201)
);
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
let dummy_click = let dummy_click =
@@ -895,6 +1059,10 @@ mod tests {
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id, platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
None None
); );
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::MUSIC, index: 0 }).asset_id,
None
);
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none()); assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none()); assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
@@ -922,6 +1090,7 @@ mod tests {
); );
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
match &firmware.state { match &firmware.state {
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, dummy_task), FirmwareState::GameRunning(step) => assert_eq!(step.task_id, dummy_task),
@@ -938,7 +1107,9 @@ mod tests {
assert_eq!(dummy_ownership.app_id, 2); assert_eq!(dummy_ownership.app_id, 2);
let front = platform.local_hardware().gfx.front_buffer(); let front = platform.local_hardware().gfx.front_buffer();
let center = 240 + 135 * 480; let center = prometeu_hal::graphics_contract::WIDTH / 2
+ (prometeu_hal::graphics_contract::HEIGHT / 2)
* prometeu_hal::graphics_contract::WIDTH;
assert_eq!(front[center], Color::GREEN.raw()); assert_eq!(front[center], Color::GREEN.raw());
firmware.request_home_from_host(); firmware.request_home_from_host();
@@ -952,6 +1123,7 @@ mod tests {
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() }; InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&stress_click, &mut platform); 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().task_state(dummy_task), Some(TaskState::Closed));
assert_eq!( assert_eq!(
firmware.os.lifecycle().process_state_for_task(dummy_task), firmware.os.lifecycle().process_state_for_task(dummy_task),
@@ -969,6 +1141,10 @@ mod tests {
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id, platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1) Some(1)
); );
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::MUSIC, index: 0 }).asset_id,
Some(201)
);
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some()); assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some());
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some()); assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some());
@@ -1022,7 +1198,10 @@ mod tests {
#[test] #[test]
fn resident_game_termination_closes_session_and_cleans_runtime_state() { 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(); let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(library); firmware.hub.set_game_library(library);
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
@@ -1032,6 +1211,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform); firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state { let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id, FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other), other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -1107,7 +1287,10 @@ mod tests {
#[test] #[test]
fn hub_kill_control_click_terminates_resident_game_and_stays_home() { 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(); let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(library); firmware.hub.set_game_library(library);
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
@@ -1117,6 +1300,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform); firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state { let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id, FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other), other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -1199,7 +1383,10 @@ mod tests {
root.add_game_with_program("zzz-broken", 43, "Zzz Broken", "1.0.0", Some(vec![0, 0, 0, 0])); 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(); 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); firmware.tick(&InputSignals::default(), &mut platform);
let stress_click = let stress_click =
@@ -1265,7 +1452,8 @@ mod tests {
root.add_game("broken", false); root.add_game("broken", false);
let (mut firmware, mut platform) = hub_home_firmware(); 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.is_empty());
assert!(!library.diagnostics().is_empty()); assert!(!library.diagnostics().is_empty());
firmware.hub.set_game_library(library); firmware.hub.set_game_library(library);
@@ -1305,7 +1493,10 @@ mod tests {
let cart = root.add_game("stress", true); let cart = root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware(); 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"); fs::remove_file(cart.join("program.pbx")).expect("program should be removable");
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
@@ -1340,8 +1531,12 @@ mod tests {
#[test] #[test]
fn shell_running_close_click_uses_lifecycle_and_returns_hub_home() { fn shell_running_close_click_uses_lifecycle_and_returns_hub_home() {
let (mut firmware, mut platform, _signals, task_id) = load_shell_running_firmware(); let (mut firmware, mut platform, _signals, task_id) = load_shell_running_firmware();
let close_signals = let close_signals = InputSignals {
InputSignals { f_signal: true, x_pos: 420, y_pos: 24, ..Default::default() }; f_signal: true,
x_pos: prometeu_hal::graphics_contract::WIDTH as i32 - 60,
y_pos: 24,
..Default::default()
};
firmware.tick(&close_signals, &mut platform); firmware.tick(&close_signals, &mut platform);
@@ -1672,4 +1867,458 @@ mod tests {
assert!(matches!(firmware.state, FirmwareState::GameRunning(_))); assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
assert_eq!(firmware.os.vm().current_cartridge_title(), "Valid Cart"); 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_crash_screen::AppCrashesStep;
pub use crate::firmware::firmware_step_game_running::GameRunningStep; pub use crate::firmware::firmware_step_game_running::GameRunningStep;
pub use crate::firmware::firmware_step_hub_home::HubHomeStep; pub use crate::firmware::firmware_step_hub_home::HubHomeStep;
@@ -13,8 +14,11 @@ pub enum FirmwareState {
SplashScreen(SplashScreenStep), SplashScreen(SplashScreenStep),
LaunchHub(LaunchHubStep), LaunchHub(LaunchHubStep),
HubHome(HubHomeStep), HubHome(HubHomeStep),
ConfirmDiscard(ConfirmDiscardStep),
LoadCartridge(LoadCartridgeStep), LoadCartridge(LoadCartridgeStep),
ResumeResidentGame, ResumeResidentGame,
MemoryIoFault,
MemoryCardRemoved(super::firmware_step_confirm_discard::MemoryCardRemovedStep),
GameRunning(GameRunningStep), GameRunning(GameRunningStep),
ShellRunning(ShellRunningStep), ShellRunning(ShellRunningStep),
AppCrashes(AppCrashesStep), 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 // Update peripherals for input on the crash screen
ctx.platform.input_mut().pad_mut().begin_frame(ctx.signals); 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 ctx.platform
.render_submission_sink() .render_submission_sink()
.submit_render_submission(RenderSubmission::shell_ui(FrameId::ZERO, packet)) .submit_render_submission(RenderSubmission::shell_ui(FrameId::ZERO, packet))
@@ -55,6 +69,7 @@ mod tests {
message: "type mismatch".into(), message: "type mismatch".into(),
pc: 0x44, pc: 0x44,
span: None, span: None,
resource: None,
}, },
}, },
}; };
@@ -27,6 +27,15 @@ impl GameRunningStep {
return Some(FirmwareState::AppCrashes(AppCrashesStep { report })); 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 { if task_state != TaskState::Foreground {
// TODO: is it panic? // TODO: is it panic?
let report = CrashReport::VmPanic { let report = CrashReport::VmPanic {
@@ -47,7 +47,12 @@ impl HubHomeStep {
let id = ctx.os.windows().add_window( let id = ctx.os.windows().add_window(
app.title().to_string(), app.title().to_string(),
WindowOwner::Task(task_id), WindowOwner::Task(task_id),
Rect { x: 40, y: 20, w: 400, h: 220 }, Rect {
x: 40,
y: 20,
w: prometeu_hal::graphics_contract::WIDTH as i32 - 80,
h: prometeu_hal::graphics_contract::HEIGHT as i32 - 50,
},
app.color(), app.color(),
); );
ctx.os.windows().set_focus(id); ctx.os.windows().set_focus(id);
@@ -56,6 +61,16 @@ impl HubHomeStep {
Some(SystemProfileAction::LaunchGame { target }) => { Some(SystemProfileAction::LaunchGame { target }) => {
match CartridgeLoader::load(&target.path) { match CartridgeLoader::load(&target.path) {
Ok(cartridge) => { 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 if cartridge.app_mode == AppMode::Game
&& let Some(resident_task_id) = ctx.os.lifecycle().resident_game_task() && let Some(resident_task_id) = ctx.os.lifecycle().resident_game_task()
{ {
@@ -70,6 +85,11 @@ impl HubHomeStep {
return Some(FirmwareState::ResumeResidentGame); 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( if let Err(error) = resident_game_termination::terminate_resident_game(
ctx.os, ctx.os,
ctx.platform, ctx.platform,
@@ -107,6 +127,12 @@ impl HubHomeStep {
} }
} }
Some(SystemProfileAction::KillResidentGame) => { Some(SystemProfileAction::KillResidentGame) => {
if ctx.os.memcard().session.unsaved() {
return Some(FirmwareState::ConfirmDiscard(
super::firmware_state::ConfirmDiscardStep::new(None),
));
}
if let Err(error) = if let Err(error) =
resident_game_termination::terminate_resident_game(ctx.os, ctx.platform, true) resident_game_termination::terminate_resident_game(ctx.os, ctx.platform, true)
{ {
@@ -15,6 +15,10 @@ use prometeu_system::windows::WindowOwner;
pub struct LoadCartridgeStep { pub struct LoadCartridgeStep {
pub cartridge: Cartridge, pub cartridge: Cartridge,
init_error: Option<CrashReport>, 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_task_id: Option<prometeu_system::task::TaskId>,
loaded_app_mode: Option<AppMode>, loaded_app_mode: Option<AppMode>,
failure_recovery: LoadCartridgeFailureRecovery, failure_recovery: LoadCartridgeFailureRecovery,
@@ -31,12 +35,39 @@ impl LoadCartridgeStep {
Self { Self {
cartridge, cartridge,
init_error: None, init_error: None,
awaiting_memcard: false,
preparing_memcard: false,
input_released: false,
memcard_message: String::new(),
loaded_task_id: None, loaded_task_id: None,
loaded_app_mode: None, loaded_app_mode: None,
failure_recovery: LoadCartridgeFailureRecovery::AppCrash, failure_recovery: LoadCartridgeFailureRecovery::AppCrash,
} }
} }
pub fn needs_memcard_choice(&self) -> bool {
self.awaiting_memcard && !self.preparing_memcard
}
/// Typed host and UI admission share this single policy boundary.
pub fn choose_memcard(
&mut self,
os: &mut prometeu_system::SystemOS,
choice: prometeu_system::memcard::admission::Choice,
created_at: u64,
) -> prometeu_system::memcard::image::Result<()> {
if !self.needs_memcard_choice() {
return Err(prometeu_system::memcard::image::Error::InvalidState);
}
os.memcard().choose_for_game(
self.cartridge.app_id,
self.cartridge.memcard_slots.unwrap() as usize,
choice,
created_at,
)?;
self.preparing_memcard = true;
Ok(())
}
pub fn new_game_switch(cartridge: Cartridge) -> Self { pub fn new_game_switch(cartridge: Cartridge) -> Self {
Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) } Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) }
} }
@@ -51,6 +82,15 @@ impl LoadCartridgeStep {
ctx.platform.game2d_frame_composer().unbind_scene(); 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 // Initialize Asset Manager
ctx.platform.assets_mut().initialize_for_cartridge( ctx.platform.assets_mut().initialize_for_cartridge(
self.cartridge.asset_table.clone(), self.cartridge.asset_table.clone(),
@@ -70,6 +110,53 @@ impl LoadCartridgeStep {
} }
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> { 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 self.choose_memcard(ctx.os, choice, created_at) {
Ok(()) => {}
Err(error) => self.memcard_message = Self::preparation_message(error),
}
}
self.draw_memcard(ctx);
return None;
}
}
if let Some(report) = self.init_error.take() { if let Some(report) = self.init_error.take() {
if self.failure_recovery == LoadCartridgeFailureRecovery::ReturnToHub { if self.failure_recovery == LoadCartridgeFailureRecovery::ReturnToHub {
if self.cartridge.app_mode == AppMode::Game if self.cartridge.app_mode == AppMode::Game
@@ -106,6 +193,18 @@ impl LoadCartridgeStep {
return Some(FirmwareState::AppCrashes(AppCrashesStep { report })); 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 Some(task_id) = self.loaded_task_id.take() else {
let report = CrashReport::VmPanic { let report = CrashReport::VmPanic {
message: format!( message: format!(
@@ -131,5 +230,67 @@ impl LoadCartridgeStep {
Some(FirmwareState::GameRunning(GameRunningStep::new(task_id))) 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) {} pub fn on_exit(&mut self, _ctx: &mut PrometeuContext) {}
} }
@@ -9,8 +9,14 @@ pub struct ResetStep;
impl ResetStep { impl ResetStep {
pub fn on_enter(&mut self, ctx: &mut PrometeuContext) { pub fn on_enter(&mut self, ctx: &mut PrometeuContext) {
ctx.os.log(LogLevel::Info, LogSource::Pos, 0, "Firmware Reset".to_string()); ctx.os.log(LogLevel::Info, LogSource::Pos, 0, "Firmware Reset".to_string());
// Reset is a cold-boot boundary. Clearing only the VM session leaves
// the lifecycle registry pointing at the old resident game, which
// rejects the next cartridge as a second resident game.
let _ = ctx.os.lifecycle().terminate_resident_game();
ctx.os.sessions().clear_vm_sessions(); ctx.os.sessions().clear_vm_sessions();
ctx.os.vm().reset_global_runtime_state(); 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> { 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::Firmware;
pub use firmware_state::FirmwareState; pub use firmware_state::FirmwareState;
pub use prometeu_context::PrometeuContext; 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, log_manual_hub_kill: bool,
) -> Result<ResidentGameTerminationOutcome, LifecycleError> { ) -> Result<ResidentGameTerminationOutcome, LifecycleError> {
let Some(task_id) = os.lifecycle().resident_game_task() else { let Some(task_id) = os.lifecycle().resident_game_task() else {
os.memcard().session.end_session();
return Ok(ResidentGameTerminationOutcome::NoResidentGame); return Ok(ResidentGameTerminationOutcome::NoResidentGame);
}; };
@@ -30,6 +31,8 @@ pub(crate) fn terminate_resident_game(
return Ok(ResidentGameTerminationOutcome::NoResidentGame); return Ok(ResidentGameTerminationOutcome::NoResidentGame);
}; };
os.memcard().session.end_session();
platform.audio_mut().set_session(None);
os.vm().transition_render_owner(AppMode::Shell, 0); os.vm().transition_render_owner(AppMode::Shell, 0);
platform.game2d_frame_composer().unbind_scene(); platform.game2d_frame_composer().unbind_scene();
platform.assets_mut().shutdown(); platform.assets_mut().shutdown();
+15 -11
View File
@@ -8,6 +8,7 @@ pub type AssetId = i32;
pub enum BankType { pub enum BankType {
GLYPH, GLYPH,
SOUNDS, SOUNDS,
MUSIC,
SCENE, SCENE,
// TILEMAPS, // TILEMAPS,
// BLOBS, // BLOBS,
@@ -41,9 +42,8 @@ pub struct GlyphBankMetadata {
} }
#[derive(Debug, Clone, Deserialize, Serialize)] #[derive(Debug, Clone, Deserialize, Serialize)]
pub struct SoundBankMetadata { pub struct AudioBankMetadata {
pub sample_rate: u32, pub version: u16,
pub channels: u32,
} }
#[derive(Debug, Clone, Default, Deserialize, Serialize)] #[derive(Debug, Clone, Default, Deserialize, Serialize)]
@@ -73,15 +73,16 @@ impl AssetEntry {
.map_err(|e| format!("Invalid GLYPH metadata for asset {}: {}", self.asset_id, e)) .map_err(|e| format!("Invalid GLYPH metadata for asset {}: {}", self.asset_id, e))
} }
pub fn metadata_as_sound_bank(&self) -> Result<SoundBankMetadata, String> { pub fn metadata_as_audio_bank(&self) -> Result<AudioBankMetadata, String> {
if self.bank_type != BankType::SOUNDS { if !matches!(self.bank_type, BankType::SOUNDS | BankType::MUSIC) {
return Err(format!( return Err("asset is not an audio bank".into());
"Asset {} is not a SOUNDS bank (type: {:?})",
self.asset_id, self.bank_type
));
} }
serde_json::from_value(self.metadata.clone()) let metadata: AudioBankMetadata = serde_json::from_value(self.metadata.clone())
.map_err(|e| format!("Invalid SOUNDS metadata for asset {}: {}", self.asset_id, e)) .map_err(|e| format!("Invalid audio metadata: {e}"))?;
if metadata.version != 1 {
return Err("unsupported audio metadata version".into());
}
Ok(metadata)
} }
pub fn metadata_as_scene_bank(&self) -> Result<SceneBankMetadata, String> { pub fn metadata_as_scene_bank(&self) -> Result<SceneBankMetadata, String> {
@@ -189,6 +190,9 @@ pub struct SlotRef {
} }
impl SlotRef { impl SlotRef {
pub fn music(index: usize) -> Self {
Self { asset_type: BankType::MUSIC, index }
}
pub fn gfx(index: usize) -> Self { pub fn gfx(index: usize) -> Self {
Self { asset_type: BankType::GLYPH, index } Self { asset_type: BankType::GLYPH, index }
} }
@@ -6,12 +6,28 @@ use crate::asset::{
use crate::cartridge::AssetsPayloadSource; use crate::cartridge::AssetsPayloadSource;
pub trait AssetBridge { pub trait AssetBridge {
fn unload_audio(&self, _music: bool, _slot: usize) -> AssetOpStatus {
AssetOpStatus::InvalidState
}
/// 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( fn initialize_for_cartridge(
&self, &self,
assets: Vec<AssetEntry>, assets: Vec<AssetEntry>,
preload: Vec<PreloadEntry>, preload: Vec<PreloadEntry>,
assets_data: AssetsPayloadSource, 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 load(&self, asset_id: AssetId, slot_index: usize) -> Result<HandleId, AssetLoadError>;
fn status(&self, handle: HandleId) -> LoadStatus; fn status(&self, handle: HandleId) -> LoadStatus;
fn commit(&self, handle: HandleId) -> AssetOpStatus; fn commit(&self, handle: HandleId) -> AssetOpStatus;
@@ -17,6 +17,21 @@ pub enum AudioOpStatus {
AssetNotFound = 4, AssetNotFound = 4,
NoEffect = 5, NoEffect = 5,
BankInvalid = 6, BankInvalid = 6,
CommandLimit = 7,
}
/// High-level commands are staged with the ordinary frame/lifecycle batch.
#[derive(Debug, Clone, Copy)]
pub enum AudioControl {
GroupVolume { group: usize, gain: u8 },
MusicStop { group: usize },
MusicPause { group: usize, paused: bool },
MusicVolume { group: usize, gain: u8 },
MusicFade { group: usize, gain: u8, frames: u32, smooth: bool },
Crossfade { source: usize, target: usize, frames: u32, smooth: bool },
BusVolume { bus: usize, gain: u8 },
Effect { group: usize, cutoff_hz: u32, delay_frames: u32, feedback: f32, wet: f32, dry: f32 },
SfxSend { voice: usize, gain: u8 },
} }
pub trait AudioBridge { pub trait AudioBridge {
@@ -43,10 +58,24 @@ pub trait AudioBridge {
priority: u8, priority: u8,
loop_mode: LoopMode, loop_mode: LoopMode,
) -> AudioOpStatus; ) -> AudioOpStatus;
fn stop(&mut self, voice_id: usize); fn music_play(&mut self, group: usize, bank: usize, looping: bool) -> AudioOpStatus;
fn set_volume(&mut self, voice_id: usize, volume: u8); fn control(&mut self, control: AudioControl) -> AudioOpStatus;
fn set_pan(&mut self, voice_id: usize, pan: u8); fn stop(&mut self, voice_id: usize) -> AudioOpStatus;
fn set_pitch(&mut self, voice_id: usize, pitch: f64); fn set_volume(&mut self, voice_id: usize, volume: u8) -> AudioOpStatus;
fn is_playing(&self, voice_id: usize) -> bool; fn set_pan(&mut self, voice_id: usize, pan: u8) -> AudioOpStatus;
fn clear_commands(&mut self); 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 crate::syscalls::CapFlags;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
use std::fs::File; 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::path::PathBuf;
use std::sync::Arc; use std::sync::Arc;
@@ -18,6 +18,7 @@ pub struct Cartridge {
pub app_version: String, pub app_version: String,
pub app_mode: AppMode, pub app_mode: AppMode,
pub capabilities: CapFlags, pub capabilities: CapFlags,
pub memcard_slots: Option<u8>,
pub program: Vec<u8>, pub program: Vec<u8>,
pub assets: AssetsPayloadSource, pub assets: AssetsPayloadSource,
pub asset_table: Vec<AssetEntry>, pub asset_table: Vec<AssetEntry>,
@@ -31,6 +32,7 @@ pub struct CartridgeDTO {
pub app_version: String, pub app_version: String,
pub app_mode: AppMode, pub app_mode: AppMode,
pub capabilities: CapFlags, pub capabilities: CapFlags,
pub memcard_slots: Option<u8>,
pub program: Vec<u8>, pub program: Vec<u8>,
pub assets: AssetsPayloadSource, pub assets: AssetsPayloadSource,
pub asset_table: Vec<AssetEntry>, pub asset_table: Vec<AssetEntry>,
@@ -45,6 +47,7 @@ impl From<CartridgeDTO> for Cartridge {
app_version: dto.app_version, app_version: dto.app_version,
app_mode: dto.app_mode, app_mode: dto.app_mode,
capabilities: dto.capabilities, capabilities: dto.capabilities,
memcard_slots: dto.memcard_slots,
program: dto.program, program: dto.program,
assets: dto.assets, assets: dto.assets,
asset_table: dto.asset_table, asset_table: dto.asset_table,
@@ -125,8 +128,12 @@ impl AssetsPayloadSlice {
pub fn open_reader(&self) -> io::Result<AssetsPayloadReader> { pub fn open_reader(&self) -> io::Result<AssetsPayloadReader> {
match self { match self {
Self::Memory { bytes, start, len } => { Self::Memory { bytes, start, len } => {
let data = Arc::<[u8]>::from(bytes[*start..*start + *len].to_vec()); Ok(AssetsPayloadReader::Memory(MemorySliceReader {
Ok(AssetsPayloadReader::Memory(Cursor::new(data))) bytes: Arc::clone(bytes),
start: *start,
len: *len,
position: 0,
}))
} }
Self::File { source, offset, size } => { Self::File { source, offset, size } => {
let mut file = File::open(&source.path)?; let mut file = File::open(&source.path)?;
@@ -151,7 +158,7 @@ impl AssetsPayloadSlice {
} }
pub enum AssetsPayloadReader { pub enum AssetsPayloadReader {
Memory(Cursor<Arc<[u8]>>), Memory(MemorySliceReader),
File(FileSliceReader), 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 { pub struct FileSliceReader {
file: File, file: File,
start: u64, start: u64,
@@ -278,6 +316,7 @@ pub enum CartridgeError {
MissingProgram, MissingProgram,
MissingAssets, MissingAssets,
IoError, IoError,
ProgramLoadFailed(prometeu_bytecode::load_limits::LoadFailure),
} }
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize, Serialize)] #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize, Serialize)]
@@ -291,6 +330,7 @@ pub enum Capability {
Gfxui, Gfxui,
Audio, Audio,
Fs, Fs,
Memcard,
Log, Log,
Asset, Asset,
Bank, Bank,
@@ -307,4 +347,6 @@ pub struct CartridgeManifest {
pub app_mode: AppMode, pub app_mode: AppMode,
#[serde(default)] #[serde(default)]
pub capabilities: Vec<Capability>, pub capabilities: Vec<Capability>,
#[serde(default)]
pub memcard_slots: Option<u8>,
} }
@@ -5,6 +5,9 @@ use crate::cartridge::{
CartridgeManifest, CartridgeManifest,
}; };
use crate::syscalls::{CapFlags, caps}; use crate::syscalls::{CapFlags, caps};
use prometeu_bytecode::load_limits::{
LoadBudget, LoadFailure, LoadLimits, LoadReason, LoadResource,
};
use std::collections::HashSet; use std::collections::HashSet;
use std::fs; use std::fs;
use std::io::{Read, Seek, SeekFrom}; use std::io::{Read, Seek, SeekFrom};
@@ -52,13 +55,20 @@ impl DirectoryCartridgeLoader {
} }
let capabilities = normalize_capabilities(&manifest.capabilities)?; 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"); let program_path = path.join("program.pbx");
if !program_path.exists() { if !program_path.exists() {
return Err(CartridgeError::MissingProgram); 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_pa_path = path.join("assets.pa");
let (assets, asset_table, preload) = if assets_pa_path.exists() { let (assets, asset_table, preload) = if assets_pa_path.exists() {
@@ -86,6 +96,7 @@ impl DirectoryCartridgeLoader {
app_version: manifest.app_version, app_version: manifest.app_version,
app_mode: manifest.app_mode, app_mode: manifest.app_mode,
capabilities, capabilities,
memcard_slots: manifest.memcard_slots,
program, program,
assets, assets,
asset_table, asset_table,
@@ -98,6 +109,59 @@ impl DirectoryCartridgeLoader {
pub struct PackedCartridgeLoader; 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 { impl PackedCartridgeLoader {
pub fn load(_path: &Path) -> Result<Cartridge, CartridgeError> { pub fn load(_path: &Path) -> Result<Cartridge, CartridgeError> {
Err(CartridgeError::InvalidFormat) Err(CartridgeError::InvalidFormat)
@@ -122,6 +186,7 @@ fn normalize_capabilities(capabilities: &[Capability]) -> Result<CapFlags, Cartr
Capability::Gfxui => caps::GFXUI, Capability::Gfxui => caps::GFXUI,
Capability::Audio => caps::AUDIO, Capability::Audio => caps::AUDIO,
Capability::Fs => caps::FS, Capability::Fs => caps::FS,
Capability::Memcard => caps::MEMCARD,
Capability::Log => caps::LOG, Capability::Log => caps::LOG,
Capability::Asset => caps::ASSET, Capability::Asset => caps::ASSET,
Capability::Bank => caps::BANK, Capability::Bank => caps::BANK,
@@ -204,6 +269,7 @@ mod tests {
use crate::asset::{AssetCodec, AssetEntry, BankType, PreloadEntry}; use crate::asset::{AssetCodec, AssetEntry, BankType, PreloadEntry};
use crate::cartridge::{ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude}; use crate::cartridge::{ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude};
use crate::glyph_bank::GLYPH_BANK_MAX_PALETTE_COUNT_V1; use crate::glyph_bank::GLYPH_BANK_MAX_PALETTE_COUNT_V1;
use prometeu_bytecode::load_limits::LoadCode;
use serde_json::json; use serde_json::json;
use std::path::{Path, PathBuf}; use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering}; use std::sync::atomic::{AtomicU64, Ordering};
@@ -289,6 +355,76 @@ mod tests {
manifest 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] #[test]
fn load_without_capabilities_defaults_to_none() { fn load_without_capabilities_defaults_to_none() {
let dir = TestCartridgeDir::new(manifest_with_capabilities(None)); let dir = TestCartridgeDir::new(manifest_with_capabilities(None));
@@ -318,7 +454,9 @@ mod tests {
#[test] #[test]
fn load_with_all_capability_normalizes_to_all_flags() { 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![], &[]); dir.write_assets_pa(vec![], vec![], &[]);
let cartridge = DirectoryCartridgeLoader::load(dir.path()).expect("cartridge must load"); let cartridge = DirectoryCartridgeLoader::load(dir.path()).expect("cartridge must load");
@@ -1,4 +1,5 @@
use crate::app_mode::AppMode; use crate::app_mode::AppMode;
#[cfg(test)]
use prometeu_bytecode::Value; use prometeu_bytecode::Value;
use serde::{Deserialize, Serialize}; use serde::{Deserialize, Serialize};
@@ -35,7 +36,7 @@ pub enum DebugResponse {
#[serde(rename = "handshake")] #[serde(rename = "handshake")]
Handshake { protocol_version: u32, runtime_version: String, cartridge: HandshakeCartridge }, Handshake { protocol_version: u32, runtime_version: String, cartridge: HandshakeCartridge },
#[serde(rename = "getState")] #[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")] #[serde(rename = "breakpoints")]
Breakpoints { pcs: Vec<usize> }, Breakpoints { pcs: Vec<usize> },
} }
@@ -78,6 +79,9 @@ pub enum DebugEvent {
pc: Option<u32>, pc: Option<u32>,
trap_code: Option<u32>, trap_code: Option<u32>,
opcode: Option<u16>, opcode: Option<u16>,
span: Option<prometeu_bytecode::SourceSpan>,
resource: Option<prometeu_bytecode::ResourceFailure>,
init: Option<serde_json::Value>,
}, },
#[serde(rename = "cert")] #[serde(rename = "cert")]
Cert { rule: String, used: u64, limit: u64, frame_index: u64 }, Cert { rule: String, used: u64, limit: u64, frame_index: u64 },
@@ -115,7 +119,8 @@ mod tests {
fn test_get_state_serialization() { fn test_get_state_serialization() {
let resp = DebugResponse::GetState { let resp = DebugResponse::GetState {
pc: 42, 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, frame_index: 5,
app_id: 1, app_id: 1,
}; };
@@ -136,6 +141,9 @@ mod tests {
pc: Some(12), pc: Some(12),
trap_code: Some(4), trap_code: Some(4),
opcode: Some(0x70), opcode: Some(0x70),
span: None,
resource: None,
init: None,
}; };
let json = serde_json::to_string(&event).unwrap(); let json = serde_json::to_string(&event).unwrap();
@@ -0,0 +1,20 @@
//! Fixed machine graphics contract. Host surfaces never change these dimensions.
pub const WIDTH: usize = 640;
pub const HEIGHT: usize = 360;
pub const REFRESH_HZ: u32 = 60;
/// Canonical RGBA8888, with tightly packed native rows.
pub const BYTES_PER_PIXEL: usize = 4;
pub const PIXELS: usize = WIDTH * HEIGHT;
pub const STRIDE_PIXELS: usize = WIDTH;
pub const STRIDE_BYTES: usize = STRIDE_PIXELS * BYTES_PER_PIXEL;
pub const FRAME_BYTES: usize = STRIDE_BYTES * HEIGHT;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn native_graphics_contract_is_fixed() {
assert_eq!((WIDTH, HEIGHT, REFRESH_HZ), (640, 360, 60));
assert_eq!((PIXELS, STRIDE_BYTES, FRAME_BYTES), (230_400, 2_560, 921_600));
}
}
+271 -10
View File
@@ -1,27 +1,288 @@
use crate::vm_fault::VmFault;
use prometeu_bytecode::{HeapRef, Value}; 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> { pub struct HostReturn<'a> {
stack: &'a mut Vec<Value>, 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> { impl<'a> HostReturn<'a> {
pub fn new(stack: &'a mut Vec<Value>) -> Self { fn size_overflow(&mut self) -> VmFault {
Self { stack } 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) { 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) { 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) { 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) { /// Return a handle issued by the current session's heap.
// Temporary: cast incoming handle/HeapRef index. Real allocator will provide proper handles. pub fn push_gate(&mut self, handle: HeapRef) {
self.stack.push(Value::HeapRef(HeapRef(g as u32))); if self.admit() {
self.stack.push(if handle.is_null() { Value::Null } else { Value::HeapRef(handle) });
}
} }
pub fn push_string(&mut self, s: String) { pub fn push_string(&mut self, text: &str) -> Result<(), VmFault> {
self.stack.push(Value::string(s)); 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());
} }
} }
+8
View File
@@ -2,6 +2,7 @@ pub mod app_mode;
pub mod asset; pub mod asset;
pub mod asset_bridge; pub mod asset_bridge;
pub mod audio_bridge; pub mod audio_bridge;
pub mod background_work;
pub mod button; pub mod button;
pub mod cartridge; pub mod cartridge;
pub mod cartridge_loader; pub mod cartridge_loader;
@@ -11,10 +12,13 @@ pub mod debugger_protocol;
pub mod gfx_bridge; pub mod gfx_bridge;
pub mod glyph; pub mod glyph;
pub mod glyph_bank; pub mod glyph_bank;
pub mod graphics_contract;
pub mod host_context; pub mod host_context;
pub mod host_return; pub mod host_return;
pub mod input_signals; pub mod input_signals;
pub mod log; pub mod log;
pub mod memcard;
pub mod music_bank;
pub mod native_helpers; pub mod native_helpers;
pub mod native_interface; pub mod native_interface;
pub mod owned_frame; pub mod owned_frame;
@@ -36,7 +40,9 @@ pub mod telemetry;
pub mod tile; pub mod tile;
pub mod tilemap; pub mod tilemap;
pub mod touch_bridge; pub mod touch_bridge;
pub mod value_snapshot;
pub mod vm_fault; pub mod vm_fault;
pub mod wall_clock;
pub use asset_bridge::AssetBridge; pub use asset_bridge::AssetBridge;
pub use audio_bridge::{AudioBridge, AudioOpStatus, LoopMode}; pub use audio_bridge::{AudioBridge, AudioOpStatus, LoopMode};
@@ -64,3 +70,5 @@ pub use render_worker::{
RenderWorkerBackend, RenderWorkerError, RenderWorkerFrameSink, RenderWorkerTelemetry, RenderWorkerBackend, RenderWorkerError, RenderWorkerFrameSink, RenderWorkerTelemetry,
}; };
pub use touch_bridge::TouchBridge; pub use touch_bridge::TouchBridge;
pub use value_snapshot::ValueSnapshot;
pub use wall_clock::WallClock;
@@ -57,6 +57,21 @@ impl LogService {
self.events.iter().filter(|e| e.seq > seq).cloned().collect() self.events.iter().filter(|e| e.seq > seq).cloned().collect()
} }
/// Non-destructive page in native sequence order. A null cursor includes zero.
pub fn get_page(&self, after: Option<u64>, limit: usize) -> Vec<LogEvent> {
self.events
.iter()
.filter(|event| after.is_none_or(|seq| event.seq > seq))
.take(limit)
.cloned()
.collect()
}
/// Retained bounds, independent of any reader's progress.
pub fn sequence_bounds(&self) -> (Option<u64>, Option<u64>) {
(self.events.front().map(|event| event.seq), self.last_seq())
}
pub fn last_seq(&self) -> Option<u64> { pub fn last_seq(&self) -> Option<u64> {
self.events.back().map(|e| e.seq) self.events.back().map(|e| e.seq)
} }
@@ -107,4 +122,35 @@ mod tests {
assert_eq!(after[0].msg, "Log 3"); assert_eq!(after[0].msg, "Log 3");
assert_eq!(after[1].msg, "Log 4"); assert_eq!(after[1].msg, "Log 4");
} }
#[test]
fn pages_preserve_zero_requery_and_retained_bounds() {
let mut service = LogService::new(3);
assert_eq!(service.sequence_bounds(), (None, None));
assert!(service.get_page(None, 2).is_empty());
for i in 0..3 {
service.log(i, i, LogLevel::Info, LogSource::Pos, 7, format!("{i}"));
}
assert_eq!(service.sequence_bounds(), (Some(0), Some(2)));
for _ in 0..2 {
let page = service.get_page(None, 2);
assert_eq!(page.iter().map(|event| event.seq).collect::<Vec<_>>(), vec![0, 1]);
}
assert_eq!(service.get_page(Some(1), 2)[0].seq, 2);
assert!(service.get_page(Some(2), 2).is_empty());
service.log(3, 3, LogLevel::Info, LogSource::Pos, 7, "next".into());
assert_eq!(service.sequence_bounds(), (Some(1), Some(3)));
assert_eq!(service.get_page(Some(2), 2)[0].seq, 3);
assert_eq!(service.get_page(None, 10).len(), 3);
}
#[test]
fn page_cursors_preserve_large_unsigned_sequences() {
let mut service = LogService::new(3);
service.next_seq = u64::MAX - 2;
service.log(0, 0, LogLevel::Info, LogSource::Pos, 0, "first".into());
service.log(0, 0, LogLevel::Info, LogSource::Pos, 0, "second".into());
assert_eq!(service.get_page(Some(u64::MAX - 2), 1)[0].seq, u64::MAX - 1);
assert!(service.get_page(Some(u64::MAX), 1).is_empty());
}
} }
@@ -0,0 +1,27 @@
//! 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,
Busy,
AccessDenied,
AlreadyExists,
Indeterminate,
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;
}
@@ -0,0 +1,376 @@
//! Resident, self-contained music data. Construction/compilation is off the audio lane.
use crate::{sample::Sample, sound_bank::AudioBankMetrics};
use std::sync::{
Arc,
atomic::{AtomicBool, Ordering},
};
pub const AUDIO_PPQ: u32 = 960;
pub const AUDIO_RATE: u32 = 48_000;
pub const MAX_MUSIC_TRACKS: usize = 256;
pub const MAX_EVENTS_PER_FRAME: usize = 64;
#[derive(Debug, Clone, Copy)]
pub struct Instrument {
pub id: u16,
pub sample: u16,
pub low: u8,
pub high: u8,
pub root: u8,
pub looping: bool,
pub tuning_cents: i16,
pub pan: u8,
pub gain: u8,
pub attack_us: u32,
pub decay_us: u32,
pub sustain: u16,
pub release_us: u32,
pub vibrato_millihz: u32,
pub vibrato_cents: u16,
pub tremolo_depth: u16,
pub tremolo_millihz: u32,
pub send: u16,
pub curve: u8,
}
impl Default for Instrument {
fn default() -> Self {
Self {
id: 0,
sample: 0,
low: 0,
high: 127,
root: 60,
looping: false,
tuning_cents: 0,
pan: 128,
gain: 255,
attack_us: 0,
decay_us: 0,
sustain: u16::MAX,
release_us: 0,
vibrato_millihz: 0,
vibrato_cents: 0,
tremolo_depth: 0,
tremolo_millihz: 0,
send: 0,
curve: 1,
}
}
}
#[derive(Debug, Clone, Copy, Default)]
pub struct MusicEvent {
pub tick: u32,
pub kind: u8,
pub track: u8,
pub flags: u16,
pub a: u32,
pub b: u32,
pub c: i32,
pub d: i32,
pub duration_frames: u32,
pub curve: u32,
}
#[derive(Debug, Clone, Copy)]
pub struct TimedMusicEvent {
pub time: u128,
pub event: MusicEvent,
pub zone: usize,
}
#[derive(Debug)]
pub struct MusicBank {
pub name: String,
pub samples: Arc<Vec<Arc<Sample>>>,
pub instruments: Arc<Vec<Instrument>>,
pub events: Arc<Vec<TimedMusicEvent>>,
pub denominator: u128,
pub end_time: u128,
pub loop_time: Option<u128>,
pub loop_event: usize,
pub tracks: usize,
pub alive: Arc<AtomicBool>,
pub metrics: AudioBankMetrics,
}
impl MusicBank {
#[allow(clippy::too_many_arguments)]
pub fn compile(
name: String,
samples: Vec<Arc<Sample>>,
instruments: Vec<Instrument>,
events: Vec<MusicEvent>,
ppq: u32,
tempo: u32,
duration: u32,
loop_tick: Option<u32>,
tracks: usize,
) -> Result<Self, String> {
let mut compiler = MusicCompiler::new(
name,
samples,
instruments,
events,
ppq,
tempo,
duration,
loop_tick,
tracks,
)?;
loop {
if let Some(bank) = compiler.step()? {
return Ok(bank);
}
}
}
pub fn invalidate(&self) {
self.alive.store(false, Ordering::Release);
}
pub fn resident_copy(&self) -> Self {
Self {
name: self.name.clone(),
samples: self.samples.clone(),
instruments: self.instruments.clone(),
events: self.events.clone(),
denominator: self.denominator,
end_time: self.end_time,
loop_time: self.loop_time,
loop_event: self.loop_event,
tracks: self.tracks,
alive: Arc::new(AtomicBool::new(true)),
metrics: self.metrics,
}
}
}
/// Cooperative off-lane validation/clock compilation. At most 64 zones/events
/// per step; lookup is logarithmic and the loop-seam check is bounded by 65.
pub struct MusicCompiler {
name: Option<String>,
samples: Vec<Arc<Sample>>,
instruments: Vec<Instrument>,
source: std::vec::IntoIter<MusicEvent>,
compiled: Vec<TimedMusicEvent>,
zones: std::collections::BTreeMap<(u16, u8), usize>,
zone_cursor: usize,
ppq: u32,
tempo: u32,
duration: u32,
loop_tick: Option<u32>,
tracks: usize,
tick: u32,
time: u128,
loop_time: Option<u128>,
selected: [u32; MAX_MUSIC_TRACKS],
}
impl MusicCompiler {
#[allow(clippy::too_many_arguments)]
pub fn new(
name: String,
samples: Vec<Arc<Sample>>,
instruments: Vec<Instrument>,
events: Vec<MusicEvent>,
ppq: u32,
tempo: u32,
duration: u32,
loop_tick: Option<u32>,
tracks: usize,
) -> Result<Self, String> {
if ppq != AUDIO_PPQ
|| tempo == 0
|| duration == 0
|| tracks == 0
|| tracks > MAX_MUSIC_TRACKS
|| loop_tick.is_some_and(|t| t >= duration)
{
return Err("invalid music clock/tracks/loop".into());
}
let mut compiled = Vec::new();
compiled.try_reserve_exact(events.len()).map_err(|_| "music allocation failed")?;
Ok(Self {
name: Some(name),
samples,
instruments,
source: events.into_iter(),
compiled,
zones: std::collections::BTreeMap::new(),
zone_cursor: 0,
ppq,
tempo,
duration,
loop_tick,
tracks,
tick: 0,
time: 0,
loop_time: None,
selected: [u32::MAX; MAX_MUSIC_TRACKS],
})
}
pub fn step(&mut self) -> Result<Option<MusicBank>, String> {
let denominator = self.ppq as u128 * 1_000_000;
for _ in 0..64 {
if self.zone_cursor < self.instruments.len() {
let i = self.zone_cursor;
let inst = self.instruments[i];
if inst.low > inst.high
|| inst.high > 127
|| inst.root > 127
|| inst.curve > 1
|| inst.sample as usize >= self.samples.len()
|| inst.vibrato_millihz > 100_000
|| inst.tremolo_millihz > 100_000
|| inst.vibrato_cents > 2400
{
return Err("invalid instrument zone/modulation".into());
}
if inst.looping && self.samples[inst.sample as usize].loop_start.is_none() {
return Err("instrument requires a sample loop".into());
}
if self
.zones
.range((inst.id, 0)..=(inst.id, inst.high))
.next_back()
.is_some_and(|(_, j)| self.instruments[*j].high >= inst.low)
{
return Err("overlapping instrument zones".into());
}
self.zones.insert((inst.id, inst.low), i);
self.zone_cursor += 1;
continue;
}
let Some(event) = self.source.next() else {
return self.finish(denominator).map(Some);
};
if event.tick < self.tick
|| event.tick > self.duration
|| event.track as usize >= self.tracks
|| event.curve > 1
|| event.flags & !1 != 0
|| !(1..=10).contains(&event.kind)
{
return Err("invalid music event ordering/shape".into());
}
if let Some(t) = self.loop_tick.filter(|&t| t >= self.tick && t <= event.tick)
&& self.loop_time.is_none()
{
self.loop_time = Some(
self.time + (t - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128,
);
}
self.time += (event.tick - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128;
self.tick = event.tick;
let mut zone = 0;
match event.kind {
1 => {
if !(0..=127).contains(&event.c) || !(0..=255).contains(&event.d) {
return Err("invalid note/velocity".into());
}
let id = if event.b == u32::MAX {
self.selected[event.track as usize]
} else {
event.b
};
if id > u16::MAX as u32 {
return Err("note has no bank-local instrument".into());
}
zone = *self
.zones
.range((id as u16, 0)..=(id as u16, event.c as u8))
.next_back()
.map(|(_, i)| i)
.filter(|&&i| self.instruments[i].high as i32 >= event.c)
.ok_or("note has no bank-local instrument zone")?;
}
3 => {
if event.a == 0 {
return Err("zero tempo".into());
}
self.tempo = event.a;
}
4 | 9 => {
if !(0..=65535).contains(&event.c) {
return Err("invalid gain/send".into());
}
}
5 => {
if !(0..=255).contains(&event.c) {
return Err("invalid pan".into());
}
}
6 => {
if !(-9600..=9600).contains(&event.c) {
return Err("invalid pitch bend".into());
}
}
7 | 8 => {
if event.a > 100_000
|| event.c < 0
|| event.c > if event.kind == 7 { 2400 } else { 65535 }
{
return Err("invalid modulation".into());
}
}
10 => {
if event.a > u16::MAX as u32
|| self
.zones
.range((event.a as u16, 0)..=(event.a as u16, 127))
.next()
.is_none()
{
return Err("unknown instrument".into());
}
self.selected[event.track as usize] = event.a;
}
_ => {}
}
if self.compiled.len() >= MAX_EVENTS_PER_FRAME
&& self.time - self.compiled[self.compiled.len() - MAX_EVENTS_PER_FRAME].time
< denominator
{
return Err("music event density exceeds real-time bound".into());
}
self.compiled.push(TimedMusicEvent { time: self.time, event, zone });
}
Ok(None)
}
fn finish(&mut self, denominator: u128) -> Result<MusicBank, String> {
if let Some(t) = self.loop_tick.filter(|&t| t >= self.tick)
&& self.loop_time.is_none()
{
self.loop_time =
Some(self.time + (t - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128);
}
let end_time = self.time
+ (self.duration - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128;
if end_time < denominator || self.loop_time.is_some_and(|t| end_time - t < denominator) {
return Err("music/loop shorter than one output frame".into());
}
let loop_event =
self.loop_time.map_or(0, |t| self.compiled.partition_point(|e| e.time < t));
let length = end_time - self.loop_time.unwrap_or(0);
let slice = &self.compiled[loop_event..];
for i in 0..slice.len().min(MAX_EVENTS_PER_FRAME + 1) {
let tail =
slice.len().saturating_sub(MAX_EVENTS_PER_FRAME - i.min(MAX_EVENTS_PER_FRAME));
if tail < slice.len()
&& slice.len() - tail + i + 1 > MAX_EVENTS_PER_FRAME
&& slice[i].time + length - slice[tail].time < denominator
{
return Err("music loop seam event density".into());
}
}
let pcm_bytes = self.samples.iter().map(|s| s.data.len() * 2).sum();
Ok(MusicBank {
name: self.name.take().ok_or("compiler already complete")?,
samples: Arc::new(std::mem::take(&mut self.samples)),
instruments: Arc::new(std::mem::take(&mut self.instruments)),
events: Arc::new(std::mem::take(&mut self.compiled)),
denominator,
end_time,
loop_time: self.loop_time,
loop_event,
tracks: self.tracks,
alive: Arc::new(AtomicBool::new(true)),
metrics: AudioBankMetrics { pcm_bytes, ..Default::default() },
})
}
}
+4 -1
View File
@@ -6,6 +6,7 @@ use crate::render_submission::{Game2DFramePacket, RenderSubmission};
use crate::sprite::Sprite; use crate::sprite::Sprite;
use crate::telemetry::TelemetryFrame; use crate::telemetry::TelemetryFrame;
use crate::touch_bridge::TouchBridge; use crate::touch_bridge::TouchBridge;
use crate::wall_clock::WallClock;
#[derive(Debug, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RenderSubmitError { pub enum RenderSubmitError {
@@ -60,8 +61,10 @@ pub struct NoopTelemetryPlatform;
impl TelemetryPlatform for NoopTelemetryPlatform {} impl TelemetryPlatform for NoopTelemetryPlatform {}
pub trait RuntimePlatform { pub trait RuntimePlatform {
fn wall_clock(&self) -> &dyn WallClock;
fn display_size(&self) -> (usize, usize) { fn display_size(&self) -> (usize, usize) {
(480, 270) (crate::graphics_contract::WIDTH, crate::graphics_contract::HEIGHT)
} }
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink; fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink;
+24 -2
View File
@@ -1,13 +1,27 @@
#[derive(Debug)]
pub struct Sample { pub struct Sample {
pub sample_rate: u32, pub sample_rate: u32,
pub channels: u8,
pub data: Vec<i16>, pub data: Vec<i16>,
pub loop_start: Option<u32>, pub loop_start: Option<u32>,
pub loop_end: Option<u32>, pub loop_end: Option<u32>,
pub default_volume: u8,
pub default_pan: u8,
pub default_pitch: f64,
} }
impl Sample { impl Sample {
pub fn new(sample_rate: u32, data: Vec<i16>) -> Self { pub fn new(sample_rate: u32, data: Vec<i16>) -> Self {
Self { sample_rate, data, loop_start: None, loop_end: None } Self {
sample_rate,
channels: 1,
data,
loop_start: None,
loop_end: None,
default_volume: 255,
default_pan: 128,
default_pitch: 1.0,
}
} }
pub fn with_loop(mut self, start: u32, end: u32) -> Self { pub fn with_loop(mut self, start: u32, end: u32) -> Self {
@@ -17,6 +31,14 @@ impl Sample {
} }
pub fn frames_len(&self) -> usize { pub fn frames_len(&self) -> usize {
self.data.len() self.data.len() / self.channels.max(1) as usize
}
pub fn with_channels(mut self, channels: u8) -> Result<Self, String> {
if !(1..=2).contains(&channels) || !self.data.len().is_multiple_of(channels as usize) {
return Err("audio sample channels/frame count".into());
}
self.channels = channels;
Ok(self)
} }
} }
@@ -224,6 +224,8 @@ impl SceneViewportResolver {
scene_height_tiles: usize, scene_height_tiles: usize,
) -> TileAnchor { ) -> TileAnchor {
let mut next = current; let mut next = current;
// Mixed layers must not step past the center and immediately step back.
let trigger = self.hysteresis_trigger_px.max(tile_size_px / 2);
loop { loop {
let center_x_px = next.x * tile_size_px + tile_size_px / 2; let center_x_px = next.x * tile_size_px + tile_size_px / 2;
@@ -231,11 +233,11 @@ impl SceneViewportResolver {
if drift_x.abs() <= self.hysteresis_safe_px { if drift_x.abs() <= self.hysteresis_safe_px {
break; break;
} }
if drift_x > self.hysteresis_trigger_px { if drift_x > trigger {
next.x += 1; next.x += 1;
continue; continue;
} }
if drift_x < -self.hysteresis_trigger_px { if drift_x < -trigger {
next.x -= 1; next.x -= 1;
continue; continue;
} }
@@ -248,11 +250,11 @@ impl SceneViewportResolver {
if drift_y.abs() <= self.hysteresis_safe_px { if drift_y.abs() <= self.hysteresis_safe_px {
break; break;
} }
if drift_y > self.hysteresis_trigger_px { if drift_y > trigger {
next.y += 1; next.y += 1;
continue; continue;
} }
if drift_y < -self.hysteresis_trigger_px { if drift_y < -trigger {
next.y -= 1; next.y -= 1;
continue; continue;
} }
@@ -433,20 +435,34 @@ mod tests {
#[test] #[test]
fn first_update_initializes_master_and_layer_anchors() { fn first_update_initializes_master_and_layer_anchors() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let update = resolver.update(&scene, 0, 0); let update = resolver.update(&scene, 0, 0);
assert_eq!(update.master_anchor, TileAnchor { x: 17, y: 10 }); assert_eq!(update.master_anchor, TileAnchor { x: 22, y: 13 });
assert_eq!(update.layer_anchors[0], TileAnchor { x: 17, y: 10 }); assert_eq!(update.layer_anchors[0], TileAnchor { x: 22, y: 13 });
assert_eq!(update.layer_anchors[1], TileAnchor { x: 17, y: 10 }); assert_eq!(update.layer_anchors[1], TileAnchor { x: 22, y: 13 });
assert_eq!(update.refresh_requests.len(), 4); assert_eq!(update.refresh_requests.len(), 4);
} }
#[test] #[test]
fn per_layer_copy_requests_follow_parallax_factor() { fn per_layer_copy_requests_follow_parallax_factor() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let update = resolver.update(&scene, 32, 48); let update = resolver.update(&scene, 32, 48);
@@ -461,24 +477,38 @@ mod tests {
#[test] #[test]
fn hysteresis_prevents_small_back_and_forth_refresh_churn() { fn hysteresis_prevents_small_back_and_forth_refresh_churn() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let _ = resolver.update(&scene, 0, 0); let _ = resolver.update(&scene, 0, 0);
let update = resolver.update(&scene, 8, 0); let update = resolver.update(&scene, 8, 0);
assert!(update.refresh_requests.is_empty()); assert!(update.refresh_requests.is_empty());
assert_eq!(update.master_anchor, TileAnchor { x: 17, y: 10 }); assert_eq!(update.master_anchor, TileAnchor { x: 22, y: 13 });
} }
#[test] #[test]
fn repeated_high_speed_movement_advances_in_tile_steps() { fn repeated_high_speed_movement_advances_in_tile_steps() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let _ = resolver.update(&scene, 0, 0); let _ = resolver.update(&scene, 0, 0);
let update = resolver.update(&scene, 64, 0); let update = resolver.update(&scene, 64, 0);
assert!(update.master_anchor.x > 17); assert!(update.master_anchor.x > 22);
assert!(update.refresh_requests.iter().any(|request| matches!( assert!(update.refresh_requests.iter().any(|request| matches!(
request, request,
CacheRefreshRequest::RefreshColumn { layer_index: 0, .. } CacheRefreshRequest::RefreshColumn { layer_index: 0, .. }
@@ -489,18 +519,32 @@ mod tests {
#[test] #[test]
fn anchors_clamp_near_scene_edges() { fn anchors_clamp_near_scene_edges() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let update = resolver.update(&scene, 10_000, 10_000); let update = resolver.update(&scene, 10_000, 10_000);
assert_eq!(update.master_anchor, TileAnchor { x: 46, y: 53 }); assert_eq!(update.master_anchor, TileAnchor { x: 41, y: 50 });
assert_eq!(update.layer_anchors[0], TileAnchor { x: 46, y: 53 }); assert_eq!(update.layer_anchors[0], TileAnchor { x: 41, y: 50 });
} }
#[test] #[test]
fn corner_trigger_converts_to_non_overlapping_region_requests() { fn corner_trigger_converts_to_non_overlapping_region_requests() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let _ = resolver.update(&scene, 0, 0); let _ = resolver.update(&scene, 0, 0);
let update = resolver.update(&scene, 64, 80); let update = resolver.update(&scene, 64, 80);
@@ -515,15 +559,22 @@ mod tests {
.collect(); .collect();
assert_eq!(regions.len(), 2); assert_eq!(regions.len(), 2);
assert_eq!(regions[0].x + regions[0].width, 35); assert_eq!(regions[0].x + regions[0].width, 45);
assert_eq!(regions[0].height, 21); assert_eq!(regions[0].height, 27);
assert_eq!(regions[1].width, 34); assert_eq!(regions[1].width, 44);
assert_eq!(regions[1].height, 2); assert_eq!(regions[1].height, 2);
} }
#[test] #[test]
fn reset_scene_requests_full_invalidation_for_all_layers() { fn reset_scene_requests_full_invalidation_for_all_layers() {
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let requests = resolver.reset_scene(); let requests = resolver.reset_scene();
+33 -2
View File
@@ -1,16 +1,47 @@
use crate::sample::Sample; use crate::sample::Sample;
use std::sync::Arc; use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
#[derive(Debug, Clone, Copy, Default)]
pub struct AudioBankMetrics {
pub cartridge_bytes: usize,
pub pcm_bytes: usize,
pub canonical_decoded_bytes: usize,
pub materialization_ns: u64,
}
/// A container for audio assets. /// A container for audio assets.
/// ///
/// A SoundBank stores multiple audio samples that can be played by the /// A SoundBank stores multiple audio samples that can be played by the
/// audio subsystem. /// audio subsystem.
#[derive(Debug)]
pub struct SoundBank { pub struct SoundBank {
pub samples: Vec<Arc<Sample>>, pub samples: Arc<Vec<Arc<Sample>>>,
pub name: String,
pub alive: Arc<AtomicBool>,
pub metrics: AudioBankMetrics,
} }
impl SoundBank { impl SoundBank {
pub fn new(samples: Vec<Arc<Sample>>) -> Self { pub fn new(samples: Vec<Arc<Sample>>) -> Self {
Self { samples } let pcm_bytes = samples.iter().map(|s| s.data.len() * 2).sum();
Self {
samples: Arc::new(samples),
name: String::new(),
alive: Arc::new(AtomicBool::new(true)),
metrics: AudioBankMetrics { pcm_bytes, ..Default::default() },
}
}
pub fn invalidate(&self) {
self.alive.store(false, Ordering::Release);
}
pub fn resident_copy(&self) -> Self {
Self {
samples: self.samples.clone(),
name: self.name.clone(),
alive: Arc::new(AtomicBool::new(true)),
metrics: self.metrics,
}
} }
} }
@@ -11,6 +11,12 @@ pub use resolver::{
resolve_declared_program_syscalls, resolve_program_syscalls, resolve_syscall, 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. /// Enumeration of all System Calls (Syscalls) available in the Prometeu environment.
/// ///
/// Syscalls are the primary mechanism for a program running in the Virtual Machine /// Syscalls are the primary mechanism for a program running in the Virtual Machine
@@ -49,6 +55,23 @@ pub enum Syscall {
ComposerEmitSprite = 0x1104, ComposerEmitSprite = 0x1104,
AudioPlaySample = 0x3001, AudioPlaySample = 0x3001,
AudioPlay = 0x3002, AudioPlay = 0x3002,
AudioStop = 0x3003,
AudioSetVolume = 0x3004,
AudioSetPan = 0x3005,
AudioSetPitch = 0x3006,
MusicPlay = 0x3010,
MusicStop = 0x3011,
MusicPause = 0x3012,
MusicResume = 0x3013,
MusicSetVolume = 0x3014,
MusicFadeTo = 0x3015,
MusicCrossfade = 0x3016,
AudioSetBusVolume = 0x3020,
AudioSetEffect = 0x3021,
AudioSetSend = 0x3022,
AudioUnloadBank = 0x3023,
AudioSetGroupVolume = 0x3024,
FsOpen = 0x4001, FsOpen = 0x4001,
FsRead = 0x4002, FsRead = 0x4002,
FsWrite = 0x4003, FsWrite = 0x4003,
@@ -56,12 +79,20 @@ pub enum Syscall {
FsListDir = 0x4005, FsListDir = 0x4005,
FsExists = 0x4006, FsExists = 0x4006,
FsDelete = 0x4007, FsDelete = 0x4007,
MemBootstrap = 0x4200,
MemSlotCount = 0x4201, MemSlotCount = 0x4201,
MemSlotStat = 0x4202, MemSlotStat = 0x4202,
MemSlotRead = 0x4203, MemSlotRead = 0x4203,
MemSlotWrite = 0x4204, MemSlotWrite = 0x4204,
MemSlotCommit = 0x4205, MemSlotCommit = 0x4205,
MemSlotClear = 0x4206, MemSlotClear = 0x4206,
MemQuery = 0x4207,
MemRelease = 0x4208,
MemInfo = 0x4209,
MemMetadata = 0x420A,
MemPresentation = 0x420B,
MemDiagnostic = 0x420C,
MemPublishPresentation = 0x420D,
LogWrite = 0x5001, LogWrite = 0x5001,
LogWriteTag = 0x5002, LogWriteTag = 0x5002,
AssetLoad = 0x6001, AssetLoad = 0x6001,
@@ -10,5 +10,7 @@ pub const ASSET: CapFlags = 1 << 5;
pub const BANK: CapFlags = 1 << 6; pub const BANK: CapFlags = 1 << 6;
pub const GFX2D: CapFlags = 1 << 7; pub const GFX2D: CapFlags = 1 << 7;
pub const GFXUI: CapFlags = 1 << 8; pub const GFXUI: CapFlags = 1 << 8;
pub const MEMCARD: CapFlags = 1 << 9;
pub const GFX: CapFlags = COMPOSER | GFX2D; 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,84 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
.rets(1) .rets(1)
.caps(caps::AUDIO) .caps(caps::AUDIO)
.cost(5), .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),
SyscallRegistryEntry::builder(Syscall::MusicPlay, "music", "play")
.args(3)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicStop, "music", "stop")
.args(1)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicPause, "music", "pause")
.args(1)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicResume, "music", "resume")
.args(1)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicSetVolume, "music", "set_volume")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicFadeTo, "music", "fade_to")
.args(4)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicCrossfade, "music", "crossfade")
.args(4)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetBusVolume, "audio", "set_bus_volume")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetEffect, "audio", "set_effect")
.args(6)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetSend, "audio", "set_send")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioUnloadBank, "audio", "unload_bank")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetGroupVolume, "audio", "set_group_volume")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
]; ];
@@ -32,37 +32,4 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
.caps(caps::FS) .caps(caps::FS)
.non_deterministic() .non_deterministic()
.cost(20), .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(composer::ENTRIES.iter())
.chain(audio::ENTRIES.iter()) .chain(audio::ENTRIES.iter())
.chain(fs::ENTRIES.iter()) .chain(fs::ENTRIES.iter())
.chain(memcard::ENTRIES.iter())
.chain(log::ENTRIES.iter()) .chain(log::ENTRIES.iter())
.chain(asset::ENTRIES.iter()) .chain(asset::ENTRIES.iter())
.chain(bank::ENTRIES.iter()) .chain(bank::ENTRIES.iter())
} }
mod memcard;
@@ -33,6 +33,23 @@ impl Syscall {
0x1104 => Some(Self::ComposerEmitSprite), 0x1104 => Some(Self::ComposerEmitSprite),
0x3001 => Some(Self::AudioPlaySample), 0x3001 => Some(Self::AudioPlaySample),
0x3002 => Some(Self::AudioPlay), 0x3002 => Some(Self::AudioPlay),
0x3003 => Some(Self::AudioStop),
0x3004 => Some(Self::AudioSetVolume),
0x3005 => Some(Self::AudioSetPan),
0x3006 => Some(Self::AudioSetPitch),
0x3010 => Some(Self::MusicPlay),
0x3011 => Some(Self::MusicStop),
0x3012 => Some(Self::MusicPause),
0x3013 => Some(Self::MusicResume),
0x3014 => Some(Self::MusicSetVolume),
0x3015 => Some(Self::MusicFadeTo),
0x3016 => Some(Self::MusicCrossfade),
0x3020 => Some(Self::AudioSetBusVolume),
0x3021 => Some(Self::AudioSetEffect),
0x3022 => Some(Self::AudioSetSend),
0x3023 => Some(Self::AudioUnloadBank),
0x3024 => Some(Self::AudioSetGroupVolume),
0x4001 => Some(Self::FsOpen), 0x4001 => Some(Self::FsOpen),
0x4002 => Some(Self::FsRead), 0x4002 => Some(Self::FsRead),
0x4003 => Some(Self::FsWrite), 0x4003 => Some(Self::FsWrite),
@@ -40,6 +57,14 @@ impl Syscall {
0x4005 => Some(Self::FsListDir), 0x4005 => Some(Self::FsListDir),
0x4006 => Some(Self::FsExists), 0x4006 => Some(Self::FsExists),
0x4007 => Some(Self::FsDelete), 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), 0x4201 => Some(Self::MemSlotCount),
0x4202 => Some(Self::MemSlotStat), 0x4202 => Some(Self::MemSlotStat),
0x4203 => Some(Self::MemSlotRead), 0x4203 => Some(Self::MemSlotRead),
@@ -94,6 +119,23 @@ impl Syscall {
Self::ComposerEmitSprite => "ComposerEmitSprite", Self::ComposerEmitSprite => "ComposerEmitSprite",
Self::AudioPlaySample => "AudioPlaySample", Self::AudioPlaySample => "AudioPlaySample",
Self::AudioPlay => "AudioPlay", Self::AudioPlay => "AudioPlay",
Self::AudioStop => "AudioStop",
Self::AudioSetVolume => "AudioSetVolume",
Self::AudioSetPan => "AudioSetPan",
Self::AudioSetPitch => "AudioSetPitch",
Self::MusicPlay => "MusicPlay",
Self::MusicStop => "MusicStop",
Self::MusicPause => "MusicPause",
Self::MusicResume => "MusicResume",
Self::MusicSetVolume => "MusicSetVolume",
Self::MusicFadeTo => "MusicFadeTo",
Self::MusicCrossfade => "MusicCrossfade",
Self::AudioSetBusVolume => "AudioSetBusVolume",
Self::AudioSetEffect => "AudioSetEffect",
Self::AudioSetSend => "AudioSetSend",
Self::AudioUnloadBank => "AudioUnloadBank",
Self::AudioSetGroupVolume => "AudioSetGroupVolume",
Self::FsOpen => "FsOpen", Self::FsOpen => "FsOpen",
Self::FsRead => "FsRead", Self::FsRead => "FsRead",
Self::FsWrite => "FsWrite", Self::FsWrite => "FsWrite",
@@ -101,6 +143,14 @@ impl Syscall {
Self::FsListDir => "FsListDir", Self::FsListDir => "FsListDir",
Self::FsExists => "FsExists", Self::FsExists => "FsExists",
Self::FsDelete => "FsDelete", 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::MemSlotCount => "MemSlotCount",
Self::MemSlotStat => "MemSlotStat", Self::MemSlotStat => "MemSlotStat",
Self::MemSlotRead => "MemSlotRead", Self::MemSlotRead => "MemSlotRead",
@@ -39,7 +39,8 @@ pub enum LoadError {
} }
/// Load-time error for PBX-declared syscall resolution. /// 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 { pub enum DeclaredLoadError {
UnknownSyscall { UnknownSyscall {
module: String, module: String,
@@ -460,29 +460,59 @@ fn declared_resolver_accepts_mixed_status_first_surface_as_a_single_module() {
#[test] #[test]
fn memcard_syscall_signatures_are_pinned() { fn memcard_syscall_signatures_are_pinned() {
let slot_count = meta_for(Syscall::MemSlotCount); for (call, args, results) in [
assert_eq!(slot_count.module, "mem"); (Syscall::MemBootstrap, 0, 1),
assert_eq!(slot_count.name, "slot_count"); (Syscall::MemSlotCount, 1, 2),
assert_eq!(slot_count.arg_slots, 0); (Syscall::MemSlotStat, 2, 7),
assert_eq!(slot_count.ret_slots, 2); (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); #[test]
assert_eq!(slot_stat.arg_slots, 1); fn audio_control_abi_and_capability_are_stable() {
assert_eq!(slot_stat.ret_slots, 5); for (name, id, args) in [
("stop", 0x3003, 1),
let slot_read = meta_for(Syscall::MemSlotRead); ("set_volume", 0x3004, 2),
assert_eq!(slot_read.arg_slots, 3); ("set_pan", 0x3005, 2),
assert_eq!(slot_read.ret_slots, 3); ("set_pitch", 0x3006, 2),
] {
let slot_write = meta_for(Syscall::MemSlotWrite); let entry = resolve_syscall("audio", name, 1).unwrap();
assert_eq!(slot_write.arg_slots, 3); assert_eq!(entry.id, id);
assert_eq!(slot_write.ret_slots, 2); assert_eq!(entry.meta.arg_slots, args);
assert_eq!(entry.meta.ret_slots, 1);
let slot_commit = meta_for(Syscall::MemSlotCommit); assert_eq!(entry.meta.cost_hint, 5);
assert_eq!(slot_commit.arg_slots, 1); assert_eq!(entry.meta.caps, caps::AUDIO);
assert_eq!(slot_commit.ret_slots, 1); let identities = [SyscallIdentity { module: "audio", name, version: 1 }];
assert!(resolve_program_syscalls(&identities, 0).is_err());
let slot_clear = meta_for(Syscall::MemSlotClear); assert!(resolve_program_syscalls(&identities, caps::AUDIO).is_ok());
assert_eq!(slot_clear.arg_slots, 1); }
assert_eq!(slot_clear.ret_slots, 1);
} }
@@ -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)] #[derive(Debug, PartialEq, Clone)]
pub enum VmFault { pub enum VmFault {
Trap(u32, String), Trap(u32, String),
ResourceLimit(prometeu_bytecode::ResourceFailure),
Panic(String), Panic(String),
Unavailable, 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 license.workspace = true
[dependencies] [dependencies]
serde = { version = "1.0.228", features = ["derive"] }
serde_json = "1.0.149" serde_json = "1.0.149"
prometeu-vm = { path = "../prometeu-vm" } prometeu-vm = { path = "../prometeu-vm" }
prometeu-bytecode = { path = "../prometeu-bytecode" } prometeu-bytecode = { path = "../prometeu-bytecode" }
@@ -12,3 +13,4 @@ prometeu-hal = { path = "../prometeu-hal" }
[dev-dependencies] [dev-dependencies]
prometeu-drivers = { path = "../prometeu-drivers" } prometeu-drivers = { path = "../prometeu-drivers" }
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
@@ -1,6 +1,7 @@
use prometeu_bytecode::TrapInfo; use prometeu_bytecode::TrapInfo;
use prometeu_vm::VmInitError; use prometeu_vm::VmInitError;
use std::fmt; use std::fmt;
mod init_diagnostic;
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
pub enum CrashReport { pub enum CrashReport {
@@ -10,6 +11,20 @@ pub enum CrashReport {
} }
impl 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 { pub fn kind(&self) -> &'static str {
match self { match self {
Self::VmTrap { .. } => "vm_trap", 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, AsyncWorkActiveJob, AsyncWorkCancelToken, AsyncWorkJobContext, AsyncWorkJobId,
AsyncWorkJobKind, AsyncWorkJobOutcome, AsyncWorkLane, AsyncWorkLaneConfig, AsyncWorkJobKind, AsyncWorkJobOutcome, AsyncWorkLane, AsyncWorkLaneConfig,
AsyncWorkLaneController, AsyncWorkLaneError, AsyncWorkLaneTelemetry, AsyncWorkPriority, AsyncWorkLaneController, AsyncWorkLaneError, AsyncWorkLaneTelemetry, AsyncWorkPriority,
AsyncWorkStep,
}; };
pub use services::foreground::{ pub use services::foreground::{
ForegroundOwner, ForegroundStack, ForegroundStackError, ResidentGame, ResidentGameState, ForegroundOwner, ForegroundStack, ForegroundStackError, ResidentGame, ResidentGameState,
@@ -25,7 +26,7 @@ pub use services::fs;
pub use services::game_library::{ pub use services::game_library::{
GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, GameSwitchTarget, discover_games_root, GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, GameSwitchTarget, discover_games_root,
}; };
pub use services::memcard::MemcardAsyncLaneOperation; pub use services::memcard;
pub use services::process; pub use services::process;
pub use services::task; pub use services::task;
pub use services::vm_runtime::{ pub use services::vm_runtime::{
@@ -9,6 +9,7 @@ use crate::services::foreground::{
ForegroundOwner, ForegroundStackError, ResidentGame, ResidentGameState, ForegroundOwner, ForegroundStackError, ResidentGame, ResidentGameState,
}; };
use crate::task::{TaskId, TaskKind, TaskState}; use crate::task::{TaskId, TaskKind, TaskState};
use crate::vm_session::LifecycleTransition;
pub struct LifecycleFacade<'a> { pub struct LifecycleFacade<'a> {
pub(in crate::os) os: &'a mut SystemOS, 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> { 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)?; let process_id = process_id_for_task(self.os, task_id)?;
if task_kind_for_task(self.os, task_id)? != TaskKind::Game { 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.foreground_stack.set_game_foreground(task_id).map_err(map_foreground_error)?;
self.os.task_manager.set_foreground(task_id); self.os.task_manager.set_foreground(task_id);
self.os.process_manager.mark_running(process_id); self.os.process_manager.mark_running(process_id);
@@ -67,6 +104,9 @@ impl<'a> LifecycleFacade<'a> {
&& game_task_id != task_id && game_task_id != task_id
&& self.task_state(game_task_id) != Some(TaskState::Suspended) && 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)?; let game_process_id = process_id_for_task(self.os, game_task_id)?;
self.os.task_manager.mark_suspended(game_task_id); self.os.task_manager.mark_suspended(game_task_id);
self.os.process_manager.mark_suspended(game_process_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> { pub fn request_home_from_game(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let _process_id = process_id_for_task(self.os, task_id)?; 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(); let previous = self.os.foreground_stack.resident_game();
self.os self.os
@@ -113,6 +166,13 @@ impl<'a> LifecycleFacade<'a> {
} }
pub fn advance_game_pause_budget(&mut self, task_id: TaskId) -> Result<bool, LifecycleError> { 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 = let expired =
self.os.foreground_stack.advance_pause_budget(task_id).map_err(map_foreground_error)?; self.os.foreground_stack.advance_pause_budget(task_id).map_err(map_foreground_error)?;
@@ -125,6 +185,34 @@ impl<'a> LifecycleFacade<'a> {
Ok(expired) 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] { pub fn pending_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
&self.os.game_lifecycle_events &self.os.game_lifecycle_events
} }
@@ -141,6 +229,11 @@ impl<'a> LifecycleFacade<'a> {
pub fn suspend_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> { pub fn suspend_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let process_id = process_id_for_task(self.os, task_id)?; 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.task_manager.mark_suspended(task_id);
self.os.process_manager.mark_suspended(process_id); self.os.process_manager.mark_suspended(process_id);
match self.os.foreground_stack.owner() { 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> { 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 = let task =
self.os.task_manager.get(task_id).ok_or(LifecycleError::TaskNotFound(task_id))?; self.os.task_manager.get(task_id).ok_or(LifecycleError::TaskNotFound(task_id))?;
@@ -189,6 +297,16 @@ impl<'a> LifecycleFacade<'a> {
task_id, task_id,
kind: GameLifecycleEventKind::ResumeForeground, 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 self.os
.foreground_stack .foreground_stack
.complete_resume_game(task_id) .complete_resume_game(task_id)
@@ -1,15 +1,15 @@
use crate::CrashReport; use crate::CrashReport;
use crate::os::{GameLifecycleEvent, SystemOS}; use crate::os::{GameLifecycleEvent, SystemOS};
use crate::task::TaskId; use crate::task::TaskId;
use crate::vm_session::VmSession; use crate::vm_session::{LifecycleTransition, VmSession};
use crate::{RenderWorkerConfig, RenderWorkerController}; use crate::{RenderWorkerConfig, RenderWorkerController};
use prometeu_bytecode::Value;
use prometeu_hal::app_mode::AppMode; use prometeu_hal::app_mode::AppMode;
use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame}; use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame};
use prometeu_hal::{ use prometeu_hal::{
FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError, FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError,
RenderWorkerFrameSink, RuntimePlatform, RenderWorkerFrameSink, RuntimePlatform,
}; };
use prometeu_vm::LogicalFrameEndingReason;
use std::sync::atomic::Ordering; use std::sync::atomic::Ordering;
pub struct VmFacade<'a> { pub struct VmFacade<'a> {
@@ -23,6 +23,12 @@ impl<'a> VmFacade<'a> {
signals: &InputSignals, signals: &InputSignals,
platform: &mut dyn RuntimePlatform, platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> { ) -> 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); self.deliver_pending_game_lifecycle_events_to_session(task_id);
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else { 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) { 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 { let Some(session) = self.os.vm_sessions.for_task(task_id) else {
return; return;
@@ -86,6 +198,12 @@ impl<'a> VmFacade<'a> {
pc: None, 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 { let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
return Some(CrashReport::VmPanic { return Some(CrashReport::VmPanic {
message: format!("active debug task {:?} has no VM session", task_id), 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> { pub fn active_pc(&self) -> Option<usize> {
self.active_session().map(|session| session.vm.pc()) 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() self.active_session().map(|session| session.vm.operand_stack_top(n)).unwrap_or_default()
} }
@@ -159,6 +286,15 @@ impl<'a> VmFacade<'a> {
self.os.vm_runtime.debug_step_request = true; self.os.vm_runtime.debug_step_request = true;
} }
pub fn clear_debug_step_request(&mut self) {
if let Some(session) = self.active_session_mut() {
session.runtime.debug_step_request = false;
return;
}
self.os.vm_runtime.debug_step_request = false;
}
pub fn debug_step_requested(&self) -> bool { pub fn debug_step_requested(&self) -> bool {
self.active_session() self.active_session()
.map(|session| session.runtime.debug_step_request) .map(|session| session.runtime.debug_step_request)
@@ -249,6 +385,14 @@ impl<'a> VmFacade<'a> {
self.os.vm_runtime.record_repeated_render_worker_frame(frame_id); self.os.vm_runtime.record_repeated_render_worker_frame(frame_id);
} }
pub fn record_presented_render_worker_frame(
&self,
ownership: RenderOwnership,
frame_id: FrameId,
) {
self.os.vm_runtime.record_presented_render_worker_frame(ownership, frame_id);
}
pub fn active_render_ownership(&self) -> RenderOwnership { pub fn active_render_ownership(&self) -> RenderOwnership {
if let Some(task_id) = self.foreground_session_task_id() if let Some(task_id) = self.foreground_session_task_id()
&& let Some(session) = self.os.vm_sessions.for_task(task_id) && let Some(session) = self.os.vm_sessions.for_task(task_id)
@@ -28,6 +28,8 @@ pub struct SystemOS {
pub(super) memcard: MemcardService, pub(super) memcard: MemcardService,
pub(super) open_files: HashMap<u32, String>, pub(super) open_files: HashMap<u32, String>,
pub(super) next_handle: u32, pub(super) next_handle: u32,
io_controller: Option<crate::AsyncWorkLaneController>,
io_bound: bool,
} }
impl SystemOS { impl SystemOS {
@@ -50,6 +52,8 @@ impl SystemOS {
memcard: MemcardService::new(), memcard: MemcardService::new(),
open_files: HashMap::new(), open_files: HashMap::new(),
next_handle: 1, next_handle: 1,
io_controller: None,
io_bound: false,
}; };
os.log(LogLevel::Info, LogSource::Pos, 0, "PrometeuOS starting...".to_string()); os.log(LogLevel::Info, LogSource::Pos, 0, "PrometeuOS starting...".to_string());
@@ -57,6 +61,63 @@ impl SystemOS {
os os
} }
pub fn memcard(&mut self) -> &mut MemcardService {
&mut self.memcard
}
/// A successful return confirms the shared worker has stopped and joined.
pub fn stop_background_io(&mut self) -> Result<(), crate::AsyncWorkLaneError> {
if let Some(controller) = &mut self.io_controller {
controller.stop()?;
}
self.io_controller = None;
Ok(())
}
/// 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) { 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); self.vm_runtime.log(&mut self.log_service, level, source, tag, msg);
} }
@@ -109,6 +170,16 @@ impl SystemOS {
self.log_service.get_after(seq) self.log_service.get_after(seq)
} }
/// Coherent non-destructive page and retained bounds; does not execute the VM.
pub fn log_snapshot(
&self,
after: Option<u64>,
limit: usize,
) -> (Vec<LogEvent>, Option<u64>, Option<u64>) {
let (oldest, newest) = self.log_service.sequence_bounds();
(self.log_service.get_page(after, limit), oldest, newest)
}
pub fn frame_index(&mut self) -> u64 { pub fn frame_index(&mut self) -> u64 {
self.vm().logical_frame_index() self.vm().logical_frame_index()
} }
@@ -136,7 +207,7 @@ impl SystemOS {
pub(super) fn clear_cartridge_service_state(&mut self) { pub(super) fn clear_cartridge_service_state(&mut self) {
self.open_files.clear(); self.open_files.clear();
self.next_handle = 1; self.next_handle = 1;
self.memcard.clear_all_staging(); self.memcard.session.end_session();
} }
} }
@@ -158,6 +229,7 @@ mod tests {
fn session_test_cartridge(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge { fn session_test_cartridge(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
Cartridge { Cartridge {
memcard_slots: None,
app_id, app_id,
title: title.to_string(), title: title.to_string(),
app_version: "1.0.0".to_string(), app_version: "1.0.0".to_string(),
@@ -10,19 +10,41 @@ use prometeu_hal::{
const SHELL_A_BUTTON: Rect = Rect { x: 112, y: 172, w: 112, h: 32 }; const SHELL_A_BUTTON: Rect = Rect { x: 112, y: 172, w: 112, h: 32 };
const SHELL_B_BUTTON: Rect = Rect { x: 256, y: 172, w: 112, h: 32 }; const SHELL_B_BUTTON: Rect = Rect { x: 256, y: 172, w: 112, h: 32 };
const CLOSE_BUTTON: Rect = Rect { x: 420, y: 24, w: 16, h: 16 }; const CLOSE_BUTTON: Rect =
const VIEWPORT: Rect = Rect { x: 0, y: 0, w: 480, h: 270 }; Rect { x: prometeu_hal::graphics_contract::WIDTH as i32 - 60, y: 24, w: 16, h: 16 };
const HOME_PANEL: Rect = Rect { x: 48, y: 58, w: 384, h: 154 }; const VIEWPORT: Rect = Rect {
const TITLE_PANEL: Rect = Rect { x: 72, y: 34, w: 336, h: 28 }; x: 0,
y: 0,
w: prometeu_hal::graphics_contract::WIDTH as i32,
h: prometeu_hal::graphics_contract::HEIGHT as i32,
};
const HOME_PANEL: Rect = Rect {
x: 48,
y: 58,
w: prometeu_hal::graphics_contract::WIDTH as i32 - 96,
h: prometeu_hal::graphics_contract::HEIGHT as i32 - 116,
};
const TITLE_PANEL: Rect =
Rect { x: 72, y: 34, w: prometeu_hal::graphics_contract::WIDTH as i32 - 144, h: 28 };
const GAME_ROW_X: i32 = 72; const GAME_ROW_X: i32 = 72;
const GAME_ROW_Y: i32 = 90; const GAME_ROW_Y: i32 = 90;
const GAME_ROW_W: i32 = 336; const GAME_ROW_W: i32 = prometeu_hal::graphics_contract::WIDTH as i32 - 144;
const GAME_ROW_H: i32 = 22; const GAME_ROW_H: i32 = 22;
const GAME_ROW_GAP: i32 = 6; const GAME_ROW_GAP: i32 = 6;
const MAX_HOME_GAME_ROWS: usize = 3; const MAX_HOME_GAME_ROWS: usize = 3;
pub const HUB_SUSPENDED_GAME_KILL_CONTROL: Rect = Rect { x: 288, y: 230, w: 168, h: 24 }; pub const HUB_SUSPENDED_GAME_KILL_CONTROL: Rect = Rect {
x: prometeu_hal::graphics_contract::WIDTH as i32 - 192,
y: prometeu_hal::graphics_contract::HEIGHT as i32 - 40,
w: 168,
h: 24,
};
#[cfg(test)] #[cfg(test)]
const SHELL_FRAME: Rect = Rect { x: 40, y: 20, w: 400, h: 220 }; const SHELL_FRAME: Rect = Rect {
x: 40,
y: 20,
w: prometeu_hal::graphics_contract::WIDTH as i32 - 80,
h: prometeu_hal::graphics_contract::HEIGHT as i32 - 50,
};
const COLOR_BG: Color = Color::rgb(12, 14, 22); const COLOR_BG: Color = Color::rgb(12, 14, 22);
const COLOR_PANEL: Color = Color::rgb(25, 31, 48); const COLOR_PANEL: Color = Color::rgb(25, 31, 48);
@@ -607,6 +629,7 @@ mod tests {
fn game_row_click_emits_launch_game_action() { fn game_row_click_emits_launch_game_action() {
let entry = crate::GameLibraryEntry { let entry = crate::GameLibraryEntry {
manifest: prometeu_hal::cartridge::CartridgeManifest { manifest: prometeu_hal::cartridge::CartridgeManifest {
memcard_slots: None,
magic: "PMTU".to_string(), magic: "PMTU".to_string(),
cartridge_version: 1, cartridge_version: 1,
app_id: 42, app_id: 42,
@@ -619,7 +642,7 @@ mod tests {
app_id: 42, app_id: 42,
app_version: "1.0.0".to_string(), app_version: "1.0.0".to_string(),
path: PathBuf::from("test-cartridges/stress-console"), path: PathBuf::from("test-cartridges/stress-console"),
discovered_at: std::time::SystemTime::UNIX_EPOCH, discovered_at: 0,
}; };
let action = action_for_click( 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 { struct PendingAsyncWorkJob {
id: AsyncWorkJobId, id: AsyncWorkJobId,
@@ -180,6 +186,7 @@ struct PendingAsyncWorkJob {
priority: AsyncWorkPriority, priority: AsyncWorkPriority,
cancel_token: AsyncWorkCancelToken, cancel_token: AsyncWorkCancelToken,
work: AsyncWorkFn, work: AsyncWorkFn,
started: bool,
} }
struct RunningAsyncWorkJob { struct RunningAsyncWorkJob {
@@ -188,11 +195,13 @@ struct RunningAsyncWorkJob {
priority: AsyncWorkPriority, priority: AsyncWorkPriority,
cancel_token: AsyncWorkCancelToken, cancel_token: AsyncWorkCancelToken,
work: AsyncWorkFn, work: AsyncWorkFn,
started: bool,
} }
#[derive(Default)] #[derive(Default)]
struct AsyncWorkLaneState { struct AsyncWorkLaneState {
next_job_id: u64, next_job_id: u64,
progress: u64,
pending: VecDeque<PendingAsyncWorkJob>, pending: VecDeque<PendingAsyncWorkJob>,
active: Option<AsyncWorkActiveJob>, active: Option<AsyncWorkActiveJob>,
active_cancel_token: Option<AsyncWorkCancelToken>, active_cancel_token: Option<AsyncWorkCancelToken>,
@@ -204,9 +213,25 @@ struct AsyncWorkLaneState {
pub struct AsyncWorkLane { pub struct AsyncWorkLane {
state: Mutex<AsyncWorkLaneState>, state: Mutex<AsyncWorkLaneState>,
ready: Condvar, ready: Condvar,
progressed: Condvar,
} }
impl AsyncWorkLane { 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( pub fn submit(
&self, &self,
kind: AsyncWorkJobKind, kind: AsyncWorkJobKind,
@@ -220,16 +245,36 @@ impl AsyncWorkLane {
kind: AsyncWorkJobKind, kind: AsyncWorkJobKind,
priority: AsyncWorkPriority, priority: AsyncWorkPriority,
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static, 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> { ) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
let mut state = self.state.lock().map_err(|_| AsyncWorkLaneError::InternalFailure)?; let mut state = self.state.lock().map_err(|_| AsyncWorkLaneError::InternalFailure)?;
if state.shutdown_requested { if state.shutdown_requested {
return Err(AsyncWorkLaneError::Shutdown); 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 id = AsyncWorkJobId::new(state.next_job_id);
let cancel_token = AsyncWorkCancelToken::new(); 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 let insert_at = state
.pending .pending
.iter() .iter()
@@ -340,13 +385,19 @@ impl AsyncWorkLane {
state.active = Some(active); state.active = Some(active);
state.active_cancel_token = Some(pending.cancel_token.clone()); state.active_cancel_token = Some(pending.cancel_token.clone());
let pending_depth = state.pending.len(); 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 { return Some(RunningAsyncWorkJob {
id: pending.id, id: pending.id,
kind: pending.kind, kind: pending.kind,
priority: pending.priority, priority: pending.priority,
cancel_token: pending.cancel_token, cancel_token: pending.cancel_token,
work: pending.work, 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) { fn record_finished(&self, job_id: AsyncWorkJobId, outcome: AsyncWorkJobOutcome) {
let mut state = self.state.lock().unwrap(); let mut state = self.state.lock().unwrap();
if state.active.is_some_and(|active| active.id == job_id) { if state.active.is_some_and(|active| active.id == job_id) {
@@ -362,6 +440,8 @@ impl AsyncWorkLane {
state.active_cancel_token = None; state.active_cancel_token = None;
} }
state.telemetry.record_closed(job_id, outcome); 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>) { 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 { let context = AsyncWorkJobContext {
job_id: job.id, job_id: job.id,
kind: job.kind, kind: job.kind,
priority: job.priority, priority: job.priority,
cancel_token: job.cancel_token, cancel_token: job.cancel_token.clone(),
}; };
let result = catch_unwind(AssertUnwindSafe(|| (job.work)(context))) let result = catch_unwind(AssertUnwindSafe(|| (job.work)(context)))
.unwrap_or(AsyncWorkJobOutcome::Failed); .unwrap_or(AsyncWorkStep::Complete(AsyncWorkJobOutcome::Failed));
lane.record_finished(job.id, result); 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); 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::app_mode::AppMode;
use prometeu_hal::cartridge::CartridgeManifest; use prometeu_hal::cartridge::CartridgeManifest;
use std::fs; use std::fs;
use std::path::{Path, PathBuf}; use std::path::{Path, PathBuf};
use std::time::SystemTime;
#[derive(Debug, Clone)] #[derive(Debug, Clone)]
pub struct GameLibraryEntry { pub struct GameLibraryEntry {
@@ -11,11 +11,12 @@ pub struct GameLibraryEntry {
pub app_id: u32, pub app_id: u32,
pub app_version: String, pub app_version: String,
pub path: PathBuf, 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 { impl GameLibraryEntry {
fn new(path: PathBuf, manifest: CartridgeManifest, discovered_at: SystemTime) -> Self { fn new(path: PathBuf, manifest: CartridgeManifest, discovered_at: u64) -> Self {
Self { Self {
title: manifest.title.clone(), title: manifest.title.clone(),
app_id: manifest.app_id, 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 root = root.as_ref();
let discovered_at = SystemTime::now(); let discovered_at = wall_clock.utc_unix_seconds();
if !root.is_dir() { if !root.is_dir() {
return GameLibrary { return GameLibrary {
@@ -153,7 +154,7 @@ pub fn discover_games_root(root: impl AsRef<Path>) -> GameLibrary {
fn discover_candidate( fn discover_candidate(
path: &Path, path: &Path,
discovered_at: SystemTime, discovered_at: u64,
) -> Result<GameLibraryEntry, GameLibraryDiagnosticReason> { ) -> Result<GameLibraryEntry, GameLibraryDiagnosticReason> {
let manifest_path = path.join("manifest.json"); let manifest_path = path.join("manifest.json");
if !manifest_path.exists() { if !manifest_path.exists() {
@@ -185,8 +186,26 @@ fn discover_candidate(
mod tests { mod tests {
use super::*; use super::*;
use serde_json::json; use serde_json::json;
use std::cell::Cell;
use std::sync::atomic::{AtomicU64, Ordering}; 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); 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]) fs::write(nested_parent.join("nested-game").join("program.pbx"), [0_u8])
.expect("nested program should be written"); .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().len(), 2);
assert_eq!(library.entries()[0].title, "Alpha"); 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].app_version, "1.0.0");
assert_eq!(library.entries()[0].manifest.app_mode, AppMode::Game); assert_eq!(library.entries()[0].manifest.app_mode, AppMode::Game);
assert!(library.entries()[0].path.ends_with("alpha")); 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_eq!(library.entries()[1].title, "Zeta");
assert!(library.diagnostics().iter().any(|diagnostic| { assert!(library.diagnostics().iter().any(|diagnostic| {
@@ -285,6 +304,7 @@ mod tests {
let entry = GameLibraryEntry::new( let entry = GameLibraryEntry::new(
path.clone(), path.clone(),
CartridgeManifest { CartridgeManifest {
memcard_slots: None,
magic: "PMTU".to_string(), magic: "PMTU".to_string(),
cartridge_version: 1, cartridge_version: 1,
app_id: 42, app_id: 42,
@@ -293,7 +313,7 @@ mod tests {
app_mode: AppMode::Game, app_mode: AppMode::Game,
capabilities: vec![], capabilities: vec![],
}, },
UNIX_EPOCH, 0,
); );
let target = entry.switch_target(); let target = entry.switch_target();
@@ -309,7 +329,7 @@ mod tests {
let root = TestRoot::new(); let root = TestRoot::new();
let missing = root.path.join("missing"); 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!(library.is_empty());
assert_eq!(library.diagnostics().len(), 1); assert_eq!(library.diagnostics().len(), 1);
@@ -321,7 +341,7 @@ mod tests {
let games_root = let games_root =
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges"); 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(); let entries = library.entries();
assert!(entries.iter().any(|entry| { 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") 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,22 @@
use crate::fs::{FsError, VirtualFS}; //! Shared image-backed memory cards. Guest operations use RAM snapshots; only the
use crate::services::async_work::{AsyncWorkJobKind, AsyncWorkPriority}; //! shared IO worker owns storage during a publication. Legacy per-slot files are
use std::collections::HashMap; //! intentionally neither read nor migrated by this service.
pub mod admission;
pub const MEMCARD_SLOT_COUNT: usize = 32; pub mod diagnostics;
pub const MEMCARD_SLOT_CAPACITY_BYTES: usize = 32 * 1024; pub mod guest;
pub mod image;
const SLOT_FILE_MAGIC: &[u8; 4] = b"PMMS"; pub mod session;
const SLOT_FILE_VERSION: u8 = 1; pub mod transaction;
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],
}
#[derive(Default)] #[derive(Default)]
pub struct MemcardService { 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 { impl MemcardService {
pub fn new() -> Self { pub fn new() -> Self {
Self::default() 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
);
}
} }

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