Dev/runtime improvements for games #42

Merged
bquarkz merged 44 commits from dev/runtime-improvements-for-games into master 2026-10-14 13:58:56 +00:00
285 changed files with 47817 additions and 8513 deletions
+16 -7
View File
@@ -15,15 +15,24 @@ jobs:
- uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt, clippy
components: rustfmt, clippy, llvm-tools-preview
- uses: Swatinem/rust-cache@v2
- name: Format check
run: cargo fmt -- --check
- name: Discard reports from previous runs
run: rm -rf target/llvm-cov
- name: Clippy
run: cargo clippy --workspace --all-features
- name: Provision quality-gate tools and native dependencies
run: bash scripts/provision-quality-gate.sh
- name: Test
run: cargo test --workspace --all-targets --all-features --no-fail-fast
- name: Repository quality gate
run: make ci-domains
- name: Publish gate evidence (including failures)
if: always()
uses: actions/upload-artifact@v4
with:
name: quality-gate-${{ runner.os }}-${{ github.sha }}
path: |
target/llvm-cov/**
if-no-files-found: warn
Generated
+26
View File
@@ -777,6 +777,15 @@ version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "aa9a19cbb55df58761df49b23516a86d432839add4af60fc256da840f66ed35b"
[[package]]
name = "fpmath"
version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f617488244e3bd5aa86da93efaf4072579a301832ca5a9c7e3493563b509a43d"
dependencies = [
"rustc_apfloat",
]
[[package]]
name = "fraction"
version = "0.15.4"
@@ -2054,6 +2063,7 @@ dependencies = [
"prometeu-hal",
"prometeu-host-desktop-winit",
"prometeu-host-headless",
"prometeu-test-support",
"serde_json",
]
@@ -2073,6 +2083,7 @@ dependencies = [
"prometeu-drivers",
"prometeu-hal",
"prometeu-system",
"prometeu-test-support",
"prometeu-vm",
]
@@ -2113,6 +2124,7 @@ dependencies = [
"prometeu-firmware",
"prometeu-hal",
"prometeu-system",
"prometeu-test-support",
"prometeu-vm",
"serde",
"serde_json",
@@ -2139,7 +2151,9 @@ dependencies = [
"prometeu-bytecode",
"prometeu-drivers",
"prometeu-hal",
"prometeu-test-support",
"prometeu-vm",
"serde",
"serde_json",
]
@@ -2147,6 +2161,7 @@ dependencies = [
name = "prometeu-test-support"
version = "0.1.0"
dependencies = [
"prometeu-bytecode",
"rand",
]
@@ -2154,6 +2169,7 @@ dependencies = [
name = "prometeu-vm"
version = "0.1.0"
dependencies = [
"fpmath",
"prometeu-bytecode",
"prometeu-hal",
"prometeu-test-support",
@@ -2356,6 +2372,16 @@ version = "2.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d"
[[package]]
name = "rustc_apfloat"
version = "0.2.3+llvm-462a31f5a5ab"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "486c2179b4796f65bfe2ee33679acf0927ac83ecf583ad6c91c3b4570911b9ad"
dependencies = [
"bitflags 2.10.0",
"smallvec",
]
[[package]]
name = "rustix"
version = "0.38.44"
+16 -7
View File
@@ -1,19 +1,19 @@
.PHONY: fmt fmt-check clippy test-local test-debugger-socket clean coverage coverage-xml coverage-json coverage-report-json coverage-domain-list coverage-domain-evidence coverage-domain-gate test ci ci-domains cobertura
.PHONY: fmt fmt-check clippy test-local test-debugger-socket clean coverage coverage-xml coverage-json coverage-report-json coverage-domain-list coverage-domain-evidence coverage-domain-audit coverage-domain-gate test ci ci-domains cobertura
fmt:
cargo fmt
cargo fmt --all
fmt-check:
cargo fmt -- --check
cargo fmt --all -- --check
clippy:
cargo clippy --workspace --all-features
cargo clippy --workspace --all-targets --all-features -- -D warnings
test-local:
cargo test --workspace --all-targets --all-features --no-fail-fast
test-debugger-socket:
cargo test -p prometeu-host-desktop-winit --lib -- --ignored
cargo test -p prometeu-host-desktop-winit --lib runner::tests -- --ignored
clean:
cargo llvm-cov clean --workspace
@@ -33,6 +33,9 @@ coverage-json:
coverage-domain-list:
./scripts/coverage-domain-evidence.sh --list
coverage-domain-audit:
python3 scripts/audit-coverage-domains.py --report target/llvm-cov/report.json
coverage-domain-evidence:
@if [ -z "$(DOMAIN)" ]; then \
echo "usage: make coverage-domain-evidence DOMAIN=<domain>"; \
@@ -44,6 +47,12 @@ coverage-domain-gate:
./scripts/coverage-domain-evidence.sh --check-all
test: fmt-check clippy test-local test-debugger-socket
ci: clean fmt-check clippy coverage coverage-report-json
ci-domains: clean fmt-check clippy coverage coverage-report-json coverage-xml coverage-json coverage-domain-gate
# Local and GitHub entry point; Jenkins exposes the same targets as stages.
CI_DOMAIN_STEPS = clean fmt-check clippy test-local test-debugger-socket 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
+13 -19
View File
@@ -107,19 +107,19 @@ Format, lint, and test the workspace:
make test
```
Run the CI-oriented non-domain gate:
Run the shared strict CI gate (`make ci` is an alias):
```bash
make ci
```
Run the CI-oriented domain coverage gate:
The authoritative target used by both GitHub and Jenkins is:
```bash
make ci-domains
```
The debugger socket tests bind localhost sockets and are marked ignored in Rust test metadata; `make test` includes them through the dedicated `test-debugger-socket` target.
The five debugger socket tests bind localhost sockets and are marked ignored in Rust test metadata; both `make test` and `make ci-domains` select only `runner::tests` through `test-debugger-socket`. Physical audio and other manual probes remain opt-in. See [quality-gate prerequisites and commands](docs/vm-arch/COVERAGE_DOMAINS.md#commands-and-ci).
## Coverage Governance
@@ -128,20 +128,14 @@ The repository uses a two-layer runtime-edge coverage model:
- a mandatory CI gate based on canonical runtime-edge domains;
- domain-oriented review evidence for the canonical runtime-edge domains.
Current canonical domains:
- `system/runtime`
- `fs`
- `asset/bank`
- `firmware`
- `host-dependent`
- `host/headless`
The fifteen canonical domains and fixed floors are defined in
[the repository configuration](files/config/runtime-edge-coverage-domains.json).
Use `make coverage-domain-list` or the [ownership documentation](docs/vm-arch/COVERAGE_DOMAINS.md)
to inspect the current map.
Global coverage artifacts:
```bash
make ci
make cobertura
make ci-domains
```
@@ -161,12 +155,12 @@ make coverage-domain-evidence DOMAIN=host-dependent
make coverage-domain-evidence DOMAIN=host/headless
```
Per-domain baselines currently start around `60`.
That does not waive test obligations. It means the project is adopting explicit domain evidence immediately while tightening quantitative expectations incrementally over time.
`make ci-domains` is the CI entrypoint used by Jenkins.
It runs the standard coverage pipeline, produces the HTML/XML/JSON artifacts, and fails when any canonical domain falls below its configured `baseline_percent`.
The CI gate currently compares domain `lines` coverage against each domain baseline.
`make ci-domains` runs formatting, strict workspace/all-target/all-feature Clippy,
all-target tests, the five debugger socket tests, fresh coverage and every domain
ownership/evidence gate. Both CI providers archive available evidence on failure.
A failing run never lowers a configured floor; local and CI checks use the same
repository-owned commands. Reports identify their revision, source/configuration
and actual execution platform.
When a PR changes the observable contract of a canonical domain, it is expected to:
@@ -24,6 +24,21 @@ pub const TRAP_BAD_RET_SLOTS: u32 = 0x0000_000C;
/// The intrinsic ID provided is not recognized by the runtime, or its metadata is invalid.
pub const TRAP_INVALID_INTRINSIC: u32 = 0x0000_000D;
/// Valid absence used where an instance is required.
pub const TRAP_NULL_REFERENCE: u32 = 0x0000_000E;
/// Invalid, dead or stale generational heap reference.
pub const TRAP_INVALID_HANDLE: u32 = 0x0000_000F;
/// Quota, checked size overflow or recoverable allocation failure.
pub const TRAP_RESOURCE_LIMIT: u32 = 0x0000_0010;
/// Known input query unavailable on this platform.
pub const TRAP_UNAVAILABLE: u32 = 0x0000_0011;
/// Mathematical domain is invalid for the supplied finite arguments.
pub const TRAP_NUMERIC_DOMAIN: u32 = 0x0000_0012;
/// Finite input produces an unrepresentable result or integer destination.
pub const TRAP_NUMERIC_RANGE: u32 = 0x0000_0013;
/// A NaN or infinite input cannot enter guest numeric computation.
pub const TRAP_NON_FINITE: u32 = 0x0000_0014;
use serde::{Deserialize, Serialize};
/// Detailed information about a source code span.
@@ -47,4 +62,9 @@ pub struct TrapInfo {
pub pc: u32,
/// Optional source span information if debug symbols are available.
pub span: Option<SourceSpan>,
/// Machine-readable quota context; messages are not its serialization.
pub resource: Option<crate::ResourceFailure>,
}
/// All 64 unbiased bounded-random candidates were rejected.
pub const TRAP_RANDOM_REJECTION_LIMIT: u32 = 0x0000_0015;
@@ -58,7 +58,7 @@ fn parse_f64_bits(s: &str) -> Result<u64, AsmError> {
}
fn parse_keyvals(s: &str) -> Result<(&str, &str), AsmError> {
// Parses formats like: "fn=123, captures=2" or "fn=3, argc=1"
// Parses keyed u32 immediates such as "fn=123, type=2" or "type=3, method=1"
let mut parts = s.split(',');
let a = parts.next().ok_or_else(|| AsmError::MissingOperand(s.into()))?.trim();
let b = parts.next().ok_or_else(|| AsmError::MissingOperand(s.into()))?.trim();
@@ -102,6 +102,7 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
"NOP" => {
emit_u16(CoreOpCode::Nop as u16, &mut out);
}
"POP" => emit_u16(CoreOpCode::Pop as u16, &mut out),
"HALT" => {
emit_u16(CoreOpCode::Halt as u16, &mut out);
}
@@ -177,8 +178,8 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
"RET" => {
emit_u16(CoreOpCode::Ret as u16, &mut out);
}
"YIELD" => {
emit_u16(CoreOpCode::Yield as u16, &mut out);
"YIELD" | "SLEEP" | "SPAWN" => {
return Err(AsmError::InvalidOperand("retired coroutine instruction".into()))
}
"FRAME_SYNC" => {
emit_u16(CoreOpCode::FrameSync as u16, &mut out);
@@ -284,60 +285,35 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u16(CoreOpCode::Call as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"CALL_CLOSURE" => {
"CALL_CLOSURE" | "GET_CAPTURE" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (k, v) =
ops.split_once('=').ok_or_else(|| AsmError::InvalidOperand(ops.into()))?;
if k.trim() != "argc" {
return Err(AsmError::InvalidOperand(ops.into()));
}
emit_u16(CoreOpCode::CallClosure as u16, &mut out);
emit_u32(parse_u32_any(v)?, &mut out);
}
"MAKE_CLOSURE" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (a, b) = parse_keyvals(ops)?;
// Accept either order but require exact key names
let (fn_id, captures) = if a.starts_with("fn=") && b.starts_with("captures=") {
parse_pair(a, "fn", b, "captures")?
} else if a.starts_with("captures=") && b.starts_with("fn=") {
let (cap, fid) = parse_pair(a, "captures", b, "fn")?;
(fid, cap)
let opcode = if mn == "CALL_CLOSURE" {
CoreOpCode::CallClosure
} else {
return Err(AsmError::InvalidOperand(ops.into()));
CoreOpCode::GetCapture
};
emit_u16(CoreOpCode::MakeClosure as u16, &mut out);
emit_u32(fn_id, &mut out);
emit_u32(captures, &mut out);
}
"SPAWN" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (a, b) = parse_keyvals(ops)?;
let (fn_id, argc) = if a.starts_with("fn=") && b.starts_with("argc=") {
parse_pair(a, "fn", b, "argc")?
} else if a.starts_with("argc=") && b.starts_with("fn=") {
let (ac, fid) = parse_pair(a, "argc", b, "fn")?;
(fid, ac)
} else {
return Err(AsmError::InvalidOperand(ops.into()));
};
emit_u16(CoreOpCode::Spawn as u16, &mut out);
emit_u32(fn_id, &mut out);
emit_u32(argc, &mut out);
}
"SLEEP" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
emit_u16(CoreOpCode::Sleep as u16, &mut out);
emit_u16(opcode as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"MAKE_CLOSURE" | "CALL_TRAIT" => {
let (a, b) = parse_keyvals(ops)?;
let (key_a, key_b, opcode) = if mn == "MAKE_CLOSURE" {
("fn", "type", CoreOpCode::MakeClosure)
} else {
("type", "method", CoreOpCode::CallTrait)
};
let (first, second) = if a.starts_with(&format!("{}=", key_a)) {
parse_pair(a, key_a, b, key_b)?
} else {
let (second, first) = parse_pair(a, key_b, b, key_a)?;
(first, second)
};
emit_u16(opcode as u16, &mut out);
emit_u32(first, &mut out);
emit_u32(second, &mut out);
}
"HOSTCALL" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
@@ -360,6 +336,57 @@ pub fn assemble(src: &str) -> Result<Vec<u8>, AsmError> {
emit_u32(parse_u32_any(ops)?, &mut out);
}
"STRUCT_GET" | "STRUCT_SET" => {
let (a, b) = parse_keyvals(ops)?;
let (ty, field) = parse_pair(a, "type", b, "field")?;
let op =
if mn == "STRUCT_GET" { CoreOpCode::StructGet } else { CoreOpCode::StructSet };
emit_u16(op as u16, &mut out);
emit_u32(ty, &mut out);
emit_u32(field, &mut out);
}
"STRUCT_NEW" | "ARRAY_NEW" | "ARRAY_LEN" | "ARRAY_GET" | "ARRAY_SET" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let op = match mn {
"STRUCT_NEW" => CoreOpCode::StructNew,
"ARRAY_NEW" => CoreOpCode::ArrayNew,
"ARRAY_LEN" => CoreOpCode::ArrayLen,
"ARRAY_GET" => CoreOpCode::ArrayGet,
_ => CoreOpCode::ArraySet,
};
emit_u16(op as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"DYN_PACK" | "DYN_UNPACK" | "DYN_CAN_UNPACK" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let opcode = match mn {
"DYN_PACK" => CoreOpCode::DynPack,
"DYN_UNPACK" => CoreOpCode::DynUnpack,
_ => CoreOpCode::DynCanUnpack,
};
emit_u16(opcode as u16, &mut out);
emit_u32(parse_u32_any(ops)?, &mut out);
}
"REF_IS_EXACT" | "REF_IMPLEMENTS" | "REF_TO_TRAIT" | "REF_CAST" => {
if ops.is_empty() {
return Err(AsmError::MissingOperand(line.into()));
}
let (a, b) = parse_keyvals(ops)?;
let (source, target) = parse_pair(a, "source", b, "target")?;
let opcode = match mn {
"REF_IS_EXACT" => CoreOpCode::RefIsExact,
"REF_IMPLEMENTS" => CoreOpCode::RefImplements,
"REF_TO_TRAIT" => CoreOpCode::RefToTrait,
_ => CoreOpCode::RefCast,
};
emit_u16(opcode as u16, &mut out);
emit_u32(source, &mut out);
emit_u32(target, &mut out);
}
other => return Err(AsmError::UnknownMnemonic(other.into())),
}
}
@@ -90,7 +90,7 @@ impl<'a> DecodedInstr<'a> {
/// Returns the decoded instruction with canonical `next_pc`.
#[inline]
pub fn decode_next(pc: usize, bytes: &'_ [u8]) -> Result<DecodedInstr<'_>, DecodeError> {
if pc + 2 > bytes.len() {
if pc.checked_add(2).is_none_or(|end| end > bytes.len()) {
return Err(DecodeError::TruncatedOpcode { pc });
}
@@ -100,7 +100,13 @@ pub fn decode_next(pc: usize, bytes: &'_ [u8]) -> Result<DecodedInstr<'_>, Decod
let spec: CoreOpcodeSpec = opcode.spec();
let imm_start = pc + 2;
let imm_end = imm_start + (spec.imm_bytes as usize);
let imm_end =
imm_start.checked_add(spec.imm_bytes as usize).ok_or(DecodeError::TruncatedImmediate {
pc,
opcode,
need: spec.imm_bytes as usize,
have: bytes.len().saturating_sub(imm_start),
})?;
if imm_end > bytes.len() {
return Err(DecodeError::TruncatedImmediate {
@@ -10,9 +10,9 @@
//! - `MNEMONIC <imm>` for 1-operand instructions (decimal unless stated).
//! - Special operand formats:
//! - `PUSH_F64 f64:0xhhhhhhhhhhhhhhhh` — exact IEEE-754 bits in hex (little-endian to_bits()).
//! - `MAKE_CLOSURE fn=<u32>, captures=<u32>`
//! - `SPAWN fn=<u32>, argc=<u32>`
//! - `CALL_CLOSURE argc=<u32>`
//! - `MAKE_CLOSURE fn=<u32>, type=<u32>`
//! - Retired SPAWN/YIELD/SLEEP are identified for diagnostics only.
//! - `CALL_CLOSURE <FnTypeId>`
//! - `HOSTCALL <index>` is printed in decimal because it is a `SYSC` table index.
//! - `SYSCALL` is printed as `SYSCALL 0xhhhh` (numeric id in hex) to avoid cross-crate deps.
//!
@@ -60,18 +60,44 @@ fn format_operand(op: CoreOpCode, imm: &[u8]) -> String {
| CoreOpCode::SetLocal
| CoreOpCode::Call
| CoreOpCode::Sleep
| CoreOpCode::Hostcall => {
| CoreOpCode::GetCapture
| CoreOpCode::CallClosure
| CoreOpCode::Hostcall
| CoreOpCode::DynPack
| CoreOpCode::DynUnpack
| CoreOpCode::DynCanUnpack
| CoreOpCode::StructNew
| CoreOpCode::ArrayNew
| CoreOpCode::ArrayLen
| CoreOpCode::ArrayGet
| CoreOpCode::ArraySet => {
let v = u32::from_le_bytes(imm.try_into().unwrap());
format!("{}", v)
}
CoreOpCode::StructGet | CoreOpCode::StructSet => {
let ty = u32::from_le_bytes(imm[..4].try_into().unwrap());
let field = u32::from_le_bytes(imm[4..].try_into().unwrap());
format!("type={}, field={}", ty, field)
}
CoreOpCode::RefIsExact
| CoreOpCode::RefImplements
| CoreOpCode::RefToTrait
| CoreOpCode::RefCast => {
let source = u32::from_le_bytes(imm[..4].try_into().unwrap());
let target = u32::from_le_bytes(imm[4..].try_into().unwrap());
format!("source={}, target={}", source, target)
}
CoreOpCode::MakeClosure => {
let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap());
let cap = u32::from_le_bytes(imm[4..8].try_into().unwrap());
format!("fn={}, captures={}", fn_id, cap)
format!("fn={}, type={}", fn_id, cap)
}
CoreOpCode::CallClosure => {
let argc = u32::from_le_bytes(imm.try_into().unwrap());
format!("argc={}", argc)
CoreOpCode::CallTrait => {
let (ty, method) = (
u32::from_le_bytes(imm[..4].try_into().unwrap()),
u32::from_le_bytes(imm[4..].try_into().unwrap()),
);
format!("type={}, method={}", ty, method)
}
CoreOpCode::Spawn => {
let fn_id = u32::from_le_bytes(imm[0..4].try_into().unwrap());
@@ -1,8 +1,9 @@
//! Core ISA profile (bytecode-level, stable, canonical).
//!
//! This profile is the canonical opcode surface used by decoder/disasm and
//! mirrors the runtime-visible instruction set implemented today, including
//! closures, coroutines, intrinsics, and hostcall patching semantics.
//! exposes the canonical encoding for closures, coroutines, intrinsics,
//! hostcall patching and Registry instructions. Recognition by tooling alone
//! does not authorize execution without validated program metadata.
// For PR-1.4 we define the core profile as the current `OpCode` set. We re-export
// the opcode type and spec so downstream tools can import from a stable path:
@@ -1,98 +0,0 @@
//! Shared bytecode layout utilities, used by both compiler (emitter/linker)
//! and the VM (verifier/loader). This ensures a single source of truth for
//! how function ranges, instruction boundaries, and pc→function lookups are
//! interpreted post-link.
use crate::model::FunctionMeta;
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct FunctionLayout {
pub start: usize,
pub end: usize, // exclusive
}
/// Precompute canonical [start, end) ranges for all functions.
///
/// Contract:
/// - Ranges are computed by sorting functions by `code_offset` (stable),
/// then using the next function's start as the current end; the last
/// function ends at `code_len_total`.
/// - The returned vector is indexed by the original function indices.
pub fn compute_function_layouts(
functions: &[FunctionMeta],
code_len_total: usize,
) -> Vec<FunctionLayout> {
// Build index array and sort by start offset (stable to preserve relative order).
let mut idxs: Vec<usize> = (0..functions.len()).collect();
idxs.sort_by_key(|&i| functions[i].code_offset as usize);
// Optional guard: offsets should be strictly increasing (duplicates are suspicious).
for w in idxs.windows(2) {
if let [a, b] = *w {
let sa = functions[a].code_offset as usize;
let sb = functions[b].code_offset as usize;
debug_assert!(
sa < sb,
"Function code_offset must be strictly increasing: {} vs {} (indices {} and {})",
sa,
sb,
a,
b
);
}
}
let mut out = vec![FunctionLayout { start: 0, end: 0 }; functions.len()];
for (pos, &i) in idxs.iter().enumerate() {
let start = functions[i].code_offset as usize;
let end = if pos + 1 < idxs.len() {
functions[idxs[pos + 1]].code_offset as usize
} else {
code_len_total
};
out[i] = FunctionLayout { start, end };
}
out
}
#[cfg(test)]
mod tests {
use super::*;
fn build_funcs(offsets: &[usize], lens: Option<&[usize]>) -> Vec<FunctionMeta> {
let mut v = Vec::new();
for (i, off) in offsets.iter().copied().enumerate() {
let len_u32 = lens.and_then(|ls| ls.get(i).copied()).unwrap_or(0) as u32;
v.push(FunctionMeta {
code_offset: off as u32,
code_len: len_u32,
param_slots: 0,
local_slots: 0,
return_slots: 0,
max_stack_slots: 0,
});
}
v
}
#[test]
fn compute_function_layouts_end_is_next_start() {
// Synthetic functions with known offsets: 0, 10, 25; total_len = 40
let funcs = build_funcs(&[0, 10, 25], None);
let layouts = compute_function_layouts(&funcs, 40);
assert_eq!(layouts.len(), 3);
assert_eq!(layouts[0], FunctionLayout { start: 0, end: 10 });
assert_eq!(layouts[1], FunctionLayout { start: 10, end: 25 });
assert_eq!(layouts[2], FunctionLayout { start: 25, end: 40 });
for i in 0..3 {
let l = &layouts[i];
assert_eq!(
l.end - l.start,
(funcs.get(i + 1).map(|n| n.code_offset as usize).unwrap_or(40))
- (funcs[i].code_offset as usize)
);
}
}
}
+16 -6
View File
@@ -3,22 +3,32 @@ pub mod assembler;
mod decoder;
mod disassembler;
pub mod isa; // canonical ISA boundary (core and future profiles)
mod layout;
pub mod model;
mod opcode;
mod opcode_spec;
mod program_image;
mod resource_failure;
mod value;
pub use abi::{
SourceSpan, TrapInfo, TRAP_BAD_RET_SLOTS, TRAP_DIV_ZERO, TRAP_EXPLICIT,
TRAP_ILLEGAL_INSTRUCTION, TRAP_INVALID_FUNC, TRAP_INVALID_INTRINSIC, TRAP_INVALID_LOCAL,
TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_STACK_UNDERFLOW, TRAP_TYPE,
TRAP_ILLEGAL_INSTRUCTION, TRAP_INVALID_FUNC, TRAP_INVALID_HANDLE, TRAP_INVALID_INTRINSIC,
TRAP_INVALID_LOCAL, TRAP_INVALID_SYSCALL, TRAP_NON_FINITE, TRAP_NULL_REFERENCE,
TRAP_NUMERIC_DOMAIN, TRAP_NUMERIC_RANGE, TRAP_OOB, TRAP_RANDOM_REJECTION_LIMIT,
TRAP_RESOURCE_LIMIT, TRAP_STACK_UNDERFLOW, TRAP_TYPE, TRAP_UNAVAILABLE,
};
pub use assembler::{assemble, AsmError};
pub use decoder::{decode_next, DecodeError};
pub use decoder::{decode_next, DecodeError, DecodedInstr};
pub use disassembler::disassemble;
pub use layout::{compute_function_layouts, FunctionLayout};
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl, PBX_MAGIC};
pub use model::{LoadError, SyscallDecl, PBX_MAGIC};
pub use program_image::ExecutionFunction;
pub use program_image::ProgramImage;
pub use resource_failure::{ResourceFailure, ResourceReason, RuntimeResource};
pub use value::{string_materialization_count, HeapRef, Value};
pub mod load_limits;
pub mod registry;
pub mod registry_codec;
mod registry_instruction;
pub use registry_instruction::RegistryStackEffect;
@@ -0,0 +1,402 @@
//! Shared PBX 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,7 +1,5 @@
use crate::abi::SourceSpan;
use crate::opcode::OpCode;
use serde::{Deserialize, Serialize};
use std::collections::HashSet;
/// An entry in the Constant Pool.
///
@@ -42,16 +40,6 @@ pub enum LoadError {
UnexpectedEof,
}
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct FunctionMeta {
pub code_offset: u32,
pub code_len: u32,
pub param_slots: u16,
pub local_slots: u16,
pub return_slots: u16,
pub max_stack_slots: u16,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
pub struct DebugInfo {
pub pc_to_span: Vec<(u32, SourceSpan)>, // Sorted by PC
@@ -73,876 +61,4 @@ pub struct SyscallDecl {
pub ret_slots: u16,
}
const SECTION_KIND_CONST_POOL: u32 = 0;
const SECTION_KIND_FUNCTIONS: u32 = 1;
const SECTION_KIND_CODE: u32 = 2;
const SECTION_KIND_DEBUG: u32 = 3;
const SECTION_KIND_EXPORTS: u32 = 4;
const SECTION_KIND_SYSCALLS: u32 = 5;
pub const PBX_MAGIC: [u8; 4] = *b"PBX\0";
/// Represents the final serialized format of a PBX v0 module.
///
/// This structure is a pure data container for the PBX format. It does NOT
/// contain any linker-like logic (symbol resolution, patching, etc.).
/// All multi-module programs must be flattened and linked by the compiler
/// before being serialized into this format.
#[derive(Debug, Clone, PartialEq)]
pub struct BytecodeModule {
pub version: u16,
pub const_pool: Vec<ConstantPoolEntry>,
pub functions: Vec<FunctionMeta>,
pub code: Vec<u8>,
pub debug_info: Option<DebugInfo>,
pub exports: Vec<Export>,
pub syscalls: Vec<SyscallDecl>,
}
impl BytecodeModule {
pub fn serialize(&self) -> Vec<u8> {
let cp_data = self.serialize_const_pool();
let func_data = self.serialize_functions();
let code_data = self.code.clone();
let debug_data =
self.debug_info.as_ref().map(|di| self.serialize_debug(di)).unwrap_or_default();
let export_data = self.serialize_exports();
let syscall_data = self.serialize_syscalls();
let mut final_sections = Vec::new();
if !cp_data.is_empty() {
final_sections.push((SECTION_KIND_CONST_POOL, cp_data));
}
if !func_data.is_empty() {
final_sections.push((SECTION_KIND_FUNCTIONS, func_data));
}
if !code_data.is_empty() {
final_sections.push((SECTION_KIND_CODE, code_data));
}
if !debug_data.is_empty() {
final_sections.push((SECTION_KIND_DEBUG, debug_data));
}
if !export_data.is_empty() {
final_sections.push((SECTION_KIND_EXPORTS, export_data));
}
final_sections.push((SECTION_KIND_SYSCALLS, syscall_data));
let mut out = Vec::new();
// Magic "PBX\0"
out.extend_from_slice(&PBX_MAGIC);
// Version 0
out.extend_from_slice(&0u16.to_le_bytes());
// Endianness 0 (Little Endian), Reserved
out.extend_from_slice(&[0u8, 0u8]);
// section_count
out.extend_from_slice(&(final_sections.len() as u32).to_le_bytes());
// padding to 32 bytes
out.extend_from_slice(&[0u8; 20]);
let mut current_offset = 32 + (final_sections.len() as u32 * 12);
// Write section table
for (kind, data) in &final_sections {
let k: u32 = *kind;
out.extend_from_slice(&k.to_le_bytes());
out.extend_from_slice(&current_offset.to_le_bytes());
out.extend_from_slice(&(data.len() as u32).to_le_bytes());
current_offset += data.len() as u32;
}
// Write section data
for (_, data) in final_sections {
out.extend_from_slice(&data);
}
out
}
fn serialize_const_pool(&self) -> Vec<u8> {
if self.const_pool.is_empty() {
return Vec::new();
}
let mut data = Vec::new();
data.extend_from_slice(&(self.const_pool.len() as u32).to_le_bytes());
for entry in &self.const_pool {
match entry {
ConstantPoolEntry::Null => data.push(0),
ConstantPoolEntry::Int64(v) => {
data.push(1);
data.extend_from_slice(&v.to_le_bytes());
}
ConstantPoolEntry::Float64(v) => {
data.push(2);
data.extend_from_slice(&v.to_le_bytes());
}
ConstantPoolEntry::Boolean(v) => {
data.push(3);
data.push(if *v { 1 } else { 0 });
}
ConstantPoolEntry::String(v) => {
data.push(4);
let s_bytes = v.as_bytes();
data.extend_from_slice(&(s_bytes.len() as u32).to_le_bytes());
data.extend_from_slice(s_bytes);
}
ConstantPoolEntry::Int32(v) => {
data.push(5);
data.extend_from_slice(&v.to_le_bytes());
}
}
}
data
}
fn serialize_functions(&self) -> Vec<u8> {
if self.functions.is_empty() {
return Vec::new();
}
let mut data = Vec::new();
data.extend_from_slice(&(self.functions.len() as u32).to_le_bytes());
for f in &self.functions {
data.extend_from_slice(&f.code_offset.to_le_bytes());
data.extend_from_slice(&f.code_len.to_le_bytes());
data.extend_from_slice(&f.param_slots.to_le_bytes());
data.extend_from_slice(&f.local_slots.to_le_bytes());
data.extend_from_slice(&f.return_slots.to_le_bytes());
data.extend_from_slice(&f.max_stack_slots.to_le_bytes());
}
data
}
fn serialize_debug(&self, di: &DebugInfo) -> Vec<u8> {
let mut data = Vec::new();
data.extend_from_slice(&(di.pc_to_span.len() as u32).to_le_bytes());
for (pc, span) in &di.pc_to_span {
data.extend_from_slice(&pc.to_le_bytes());
data.extend_from_slice(&span.file_id.to_le_bytes());
data.extend_from_slice(&span.start.to_le_bytes());
data.extend_from_slice(&span.end.to_le_bytes());
}
data.extend_from_slice(&(di.function_names.len() as u32).to_le_bytes());
for (idx, name) in &di.function_names {
data.extend_from_slice(&idx.to_le_bytes());
let n_bytes = name.as_bytes();
data.extend_from_slice(&(n_bytes.len() as u32).to_le_bytes());
data.extend_from_slice(n_bytes);
}
data
}
fn serialize_exports(&self) -> Vec<u8> {
if self.exports.is_empty() {
return Vec::new();
}
let mut data = Vec::new();
data.extend_from_slice(&(self.exports.len() as u32).to_le_bytes());
for exp in &self.exports {
data.extend_from_slice(&exp.func_idx.to_le_bytes());
let s_bytes = exp.symbol.as_bytes();
data.extend_from_slice(&(s_bytes.len() as u32).to_le_bytes());
data.extend_from_slice(s_bytes);
}
data
}
fn serialize_syscalls(&self) -> Vec<u8> {
let mut data = Vec::new();
data.extend_from_slice(&(self.syscalls.len() as u32).to_le_bytes());
for syscall in &self.syscalls {
let module = syscall.module.as_bytes();
let name = syscall.name.as_bytes();
assert!(u16::try_from(module.len()).is_ok(), "SYSC module name exceeds u16 length");
assert!(u16::try_from(name.len()).is_ok(), "SYSC syscall name exceeds u16 length");
data.extend_from_slice(&(module.len() as u16).to_le_bytes());
data.extend_from_slice(module);
data.extend_from_slice(&(name.len() as u16).to_le_bytes());
data.extend_from_slice(name);
data.extend_from_slice(&syscall.version.to_le_bytes());
data.extend_from_slice(&syscall.arg_slots.to_le_bytes());
data.extend_from_slice(&syscall.ret_slots.to_le_bytes());
}
data
}
}
pub struct BytecodeLoader;
impl BytecodeLoader {
pub fn load(bytes: &[u8]) -> Result<BytecodeModule, LoadError> {
if bytes.len() < 32 {
return Err(LoadError::UnexpectedEof);
}
// Magic "PBX\0"
if bytes[0..4] != PBX_MAGIC[..] {
return Err(LoadError::InvalidMagic);
}
let version = u16::from_le_bytes([bytes[4], bytes[5]]);
if version != 0 {
return Err(LoadError::InvalidVersion);
}
let endianness = bytes[6];
if endianness != 0 {
// 0 = Little Endian
return Err(LoadError::InvalidEndianness);
}
let section_count = u32::from_le_bytes([bytes[8], bytes[9], bytes[10], bytes[11]]);
let mut sections = Vec::new();
let mut pos = 32;
for _ in 0..section_count {
if pos + 12 > bytes.len() {
return Err(LoadError::UnexpectedEof);
}
let kind =
u32::from_le_bytes([bytes[pos], bytes[pos + 1], bytes[pos + 2], bytes[pos + 3]]);
let offset = u32::from_le_bytes([
bytes[pos + 4],
bytes[pos + 5],
bytes[pos + 6],
bytes[pos + 7],
]);
let length = u32::from_le_bytes([
bytes[pos + 8],
bytes[pos + 9],
bytes[pos + 10],
bytes[pos + 11],
]);
// Basic bounds check
if (offset as usize) + (length as usize) > bytes.len() {
return Err(LoadError::SectionOutOfBounds);
}
sections.push((kind, offset, length));
pos += 12;
}
// Check for overlapping sections
for i in 0..sections.len() {
for j in i + 1..sections.len() {
let (_, o1, l1) = sections[i];
let (_, o2, l2) = sections[j];
if (o1 < o2 + l2) && (o2 < o1 + l1) {
return Err(LoadError::OverlappingSections);
}
}
}
let mut module = BytecodeModule {
version,
const_pool: Vec::new(),
functions: Vec::new(),
code: Vec::new(),
debug_info: None,
exports: Vec::new(),
syscalls: Vec::new(),
};
let mut has_syscalls = false;
for (kind, offset, length) in sections {
let section_data = &bytes[offset as usize..(offset + length) as usize];
match kind {
SECTION_KIND_CONST_POOL => {
// Const Pool
module.const_pool = parse_const_pool(section_data)?;
}
SECTION_KIND_FUNCTIONS => {
// Functions
module.functions = parse_functions(section_data)?;
}
SECTION_KIND_CODE => {
// Code
module.code = section_data.to_vec();
}
SECTION_KIND_DEBUG => {
// Debug Info
module.debug_info = Some(parse_debug_section(section_data)?);
}
SECTION_KIND_EXPORTS => {
// Exports
module.exports = parse_exports(section_data)?;
}
SECTION_KIND_SYSCALLS => {
module.syscalls = parse_syscalls(section_data)?;
has_syscalls = true;
}
_ => {} // Skip unknown or optional sections
}
}
if !has_syscalls {
return Err(LoadError::MissingSyscallSection);
}
// Additional validations
validate_module(&module)?;
Ok(module)
}
}
fn parse_const_pool(data: &[u8]) -> Result<Vec<ConstantPoolEntry>, LoadError> {
if data.is_empty() {
return Ok(Vec::new());
}
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut cp = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos >= data.len() {
return Err(LoadError::UnexpectedEof);
}
let tag = data[pos];
pos += 1;
match tag {
0 => cp.push(ConstantPoolEntry::Null),
1 => {
// Int64
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let val = i64::from_le_bytes(data[pos..pos + 8].try_into().unwrap());
cp.push(ConstantPoolEntry::Int64(val));
pos += 8;
}
2 => {
// Float64
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let val = f64::from_le_bytes(data[pos..pos + 8].try_into().unwrap());
cp.push(ConstantPoolEntry::Float64(val));
pos += 8;
}
3 => {
// Boolean
if pos >= data.len() {
return Err(LoadError::UnexpectedEof);
}
cp.push(ConstantPoolEntry::Boolean(data[pos] != 0));
pos += 1;
}
4 => {
// String
if pos + 4 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let len = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap()) as usize;
pos += 4;
if pos + len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let s = String::from_utf8_lossy(&data[pos..pos + len]).into_owned();
cp.push(ConstantPoolEntry::String(s));
pos += len;
}
5 => {
// Int32
if pos + 4 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let val = i32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
cp.push(ConstantPoolEntry::Int32(val));
pos += 4;
}
_ => return Err(LoadError::MalformedSection),
}
}
Ok(cp)
}
fn parse_functions(data: &[u8]) -> Result<Vec<FunctionMeta>, LoadError> {
if data.is_empty() {
return Ok(Vec::new());
}
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut functions = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos + 16 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let code_offset = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let code_len = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap());
let param_slots = u16::from_le_bytes(data[pos + 8..pos + 10].try_into().unwrap());
let local_slots = u16::from_le_bytes(data[pos + 10..pos + 12].try_into().unwrap());
let return_slots = u16::from_le_bytes(data[pos + 12..pos + 14].try_into().unwrap());
let max_stack_slots = u16::from_le_bytes(data[pos + 14..pos + 16].try_into().unwrap());
functions.push(FunctionMeta {
code_offset,
code_len,
param_slots,
local_slots,
return_slots,
max_stack_slots,
});
pos += 16;
}
Ok(functions)
}
fn parse_debug_section(data: &[u8]) -> Result<DebugInfo, LoadError> {
if data.is_empty() {
return Ok(DebugInfo::default());
}
if data.len() < 8 {
return Err(LoadError::MalformedSection);
}
let mut pos = 0;
// PC to Span table
let span_count = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap()) as usize;
pos += 4;
let mut pc_to_span = Vec::with_capacity(span_count);
for _ in 0..span_count {
if pos + 16 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let pc = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let file_id = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap());
let start = u32::from_le_bytes(data[pos + 8..pos + 12].try_into().unwrap());
let end = u32::from_le_bytes(data[pos + 12..pos + 16].try_into().unwrap());
pc_to_span.push((pc, SourceSpan { file_id, start, end }));
pos += 16;
}
// Function names table
if pos + 4 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let func_name_count = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap()) as usize;
pos += 4;
let mut function_names = Vec::with_capacity(func_name_count);
for _ in 0..func_name_count {
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let func_idx = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let name_len = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap()) as usize;
pos += 8;
if pos + name_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let name = String::from_utf8_lossy(&data[pos..pos + name_len]).into_owned();
function_names.push((func_idx, name));
pos += name_len;
}
Ok(DebugInfo { pc_to_span, function_names })
}
fn parse_exports(data: &[u8]) -> Result<Vec<Export>, LoadError> {
if data.is_empty() {
return Ok(Vec::new());
}
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut exports = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos + 8 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let func_idx = u32::from_le_bytes(data[pos..pos + 4].try_into().unwrap());
let name_len = u32::from_le_bytes(data[pos + 4..pos + 8].try_into().unwrap()) as usize;
pos += 8;
if pos + name_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let symbol = String::from_utf8_lossy(&data[pos..pos + name_len]).into_owned();
exports.push(Export { symbol, func_idx });
pos += name_len;
}
Ok(exports)
}
fn parse_syscalls(data: &[u8]) -> Result<Vec<SyscallDecl>, LoadError> {
if data.len() < 4 {
return Err(LoadError::MalformedSection);
}
let count = u32::from_le_bytes([data[0], data[1], data[2], data[3]]) as usize;
let mut syscalls = Vec::with_capacity(count);
let mut pos = 4;
for _ in 0..count {
if pos + 2 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let module_len = u16::from_le_bytes(data[pos..pos + 2].try_into().unwrap()) as usize;
pos += 2;
if pos + module_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let module = std::str::from_utf8(&data[pos..pos + module_len])
.map_err(|_| LoadError::InvalidUtf8)?;
pos += module_len;
if pos + 2 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let name_len = u16::from_le_bytes(data[pos..pos + 2].try_into().unwrap()) as usize;
pos += 2;
if pos + name_len > data.len() {
return Err(LoadError::UnexpectedEof);
}
let name =
std::str::from_utf8(&data[pos..pos + name_len]).map_err(|_| LoadError::InvalidUtf8)?;
pos += name_len;
if pos + 6 > data.len() {
return Err(LoadError::UnexpectedEof);
}
let version = u16::from_le_bytes(data[pos..pos + 2].try_into().unwrap());
let arg_slots = u16::from_le_bytes(data[pos + 2..pos + 4].try_into().unwrap());
let ret_slots = u16::from_le_bytes(data[pos + 4..pos + 6].try_into().unwrap());
pos += 6;
syscalls.push(SyscallDecl {
module: module.to_owned(),
name: name.to_owned(),
version,
arg_slots,
ret_slots,
});
}
if pos != data.len() {
return Err(LoadError::MalformedSection);
}
Ok(syscalls)
}
fn validate_module(module: &BytecodeModule) -> Result<(), LoadError> {
let mut syscall_identities = HashSet::with_capacity(module.syscalls.len());
for syscall in &module.syscalls {
if !syscall_identities.insert((
syscall.module.clone(),
syscall.name.clone(),
syscall.version,
)) {
return Err(LoadError::DuplicateSyscallIdentity);
}
}
for func in &module.functions {
// Opcode stream bounds
if (func.code_offset as usize) + (func.code_len as usize) > module.code.len() {
return Err(LoadError::InvalidFunctionIndex);
}
}
// Basic opcode scan for const pool indices
let mut pos = 0;
while pos < module.code.len() {
if pos + 2 > module.code.len() {
break; // Unexpected EOF in middle of opcode, maybe should be error
}
let op_val = u16::from_le_bytes([module.code[pos], module.code[pos + 1]]);
let opcode = OpCode::try_from(op_val).map_err(|_| LoadError::InvalidOpcode)?;
pos += 2;
match opcode {
OpCode::PushConst => {
if pos + 4 > module.code.len() {
return Err(LoadError::UnexpectedEof);
}
let idx =
u32::from_le_bytes(module.code[pos..pos + 4].try_into().unwrap()) as usize;
if idx >= module.const_pool.len() {
return Err(LoadError::InvalidConstIndex);
}
pos += 4;
}
OpCode::PushI32
| OpCode::Jmp
| OpCode::JmpIfFalse
| OpCode::JmpIfTrue
| OpCode::GetGlobal
| OpCode::SetGlobal
| OpCode::GetLocal
| OpCode::SetLocal
| OpCode::PopN
| OpCode::Hostcall
| OpCode::Syscall
| OpCode::Intrinsic => {
pos += 4;
}
OpCode::PushI64 | OpCode::PushF64 => {
pos += 8;
}
OpCode::PushBool => {
pos += 1;
}
OpCode::Call => {
pos += 4;
}
_ => {}
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
fn create_header(section_count: u32) -> Vec<u8> {
let mut h = vec![0u8; 32];
h[0..4].copy_from_slice(&PBX_MAGIC);
h[4..6].copy_from_slice(&0u16.to_le_bytes()); // version
h[6] = 0; // endianness
h[8..12].copy_from_slice(&section_count.to_le_bytes());
h
}
fn minimal_module() -> BytecodeModule {
BytecodeModule {
version: 0,
const_pool: vec![],
functions: vec![],
code: vec![],
debug_info: None,
exports: vec![],
syscalls: vec![],
}
}
fn build_pbx_with_sections(sections: Vec<(u32, Vec<u8>)>) -> Vec<u8> {
let mut data = create_header(sections.len() as u32);
let mut offset = 32 + (sections.len() as u32 * 12);
for (kind, section_data) in &sections {
data.extend_from_slice(&kind.to_le_bytes());
data.extend_from_slice(&offset.to_le_bytes());
data.extend_from_slice(&(section_data.len() as u32).to_le_bytes());
offset += section_data.len() as u32;
}
for (_, section_data) in sections {
data.extend_from_slice(&section_data);
}
data
}
#[test]
fn test_invalid_magic() {
let mut data = create_header(0);
data[0..4].copy_from_slice(b"PBS\0");
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidMagic));
}
#[test]
fn test_invalid_version() {
let mut data = create_header(0);
data[4] = 1;
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidVersion));
}
#[test]
fn test_invalid_endianness() {
let mut data = create_header(0);
data[6] = 1;
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidEndianness));
}
#[test]
fn test_overlapping_sections() {
let mut data = create_header(2);
// Section 1: Kind 0, Offset 64, Length 32
data.extend_from_slice(&0u32.to_le_bytes());
data.extend_from_slice(&64u32.to_le_bytes());
data.extend_from_slice(&32u32.to_le_bytes());
// Section 2: Kind 1, Offset 80, Length 32 (Overlaps with Section 1)
data.extend_from_slice(&1u32.to_le_bytes());
data.extend_from_slice(&80u32.to_le_bytes());
data.extend_from_slice(&32u32.to_le_bytes());
// Ensure data is long enough for the offsets
data.resize(256, 0);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::OverlappingSections));
}
#[test]
fn test_section_out_of_bounds() {
let mut data = create_header(1);
// Section 1: Kind 0, Offset 64, Length 1000
data.extend_from_slice(&0u32.to_le_bytes());
data.extend_from_slice(&64u32.to_le_bytes());
data.extend_from_slice(&1000u32.to_le_bytes());
data.resize(256, 0);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::SectionOutOfBounds));
}
#[test]
fn test_invalid_function_code_offset() {
let mut data = create_header(3);
// Section 1: Functions, Kind 1, Offset 80, Length 20 (Header 4 + 1 entry 16)
data.extend_from_slice(&1u32.to_le_bytes());
data.extend_from_slice(&80u32.to_le_bytes());
data.extend_from_slice(&20u32.to_le_bytes());
// Section 2: Code, Kind 2, Offset 128, Length 10
data.extend_from_slice(&2u32.to_le_bytes());
data.extend_from_slice(&128u32.to_le_bytes());
data.extend_from_slice(&10u32.to_le_bytes());
// Section 3: SYSC, Kind 5, Offset 160, Length 4 (empty)
data.extend_from_slice(&5u32.to_le_bytes());
data.extend_from_slice(&160u32.to_le_bytes());
data.extend_from_slice(&4u32.to_le_bytes());
data.resize(256, 0);
// Setup functions section
let func_data_start = 80;
data[func_data_start..func_data_start + 4].copy_from_slice(&1u32.to_le_bytes()); // 1 function
let entry_start = func_data_start + 4;
data[entry_start..entry_start + 4].copy_from_slice(&5u32.to_le_bytes()); // code_offset = 5
data[entry_start + 4..entry_start + 8].copy_from_slice(&10u32.to_le_bytes()); // code_len = 10
// 5 + 10 = 15 > 10 (code section length)
data[160..164].copy_from_slice(&0u32.to_le_bytes());
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidFunctionIndex));
}
#[test]
fn test_invalid_const_index() {
let mut data = create_header(3);
// Section 1: Const Pool, Kind 0, Offset 80, Length 4 (Empty CP)
data.extend_from_slice(&0u32.to_le_bytes());
data.extend_from_slice(&80u32.to_le_bytes());
data.extend_from_slice(&4u32.to_le_bytes());
// Section 2: Code, Kind 2, Offset 128, Length 6 (PushConst 0)
data.extend_from_slice(&2u32.to_le_bytes());
data.extend_from_slice(&128u32.to_le_bytes());
data.extend_from_slice(&6u32.to_le_bytes());
// Section 3: SYSC, Kind 5, Offset 160, Length 4 (empty)
data.extend_from_slice(&5u32.to_le_bytes());
data.extend_from_slice(&160u32.to_le_bytes());
data.extend_from_slice(&4u32.to_le_bytes());
data.resize(256, 0);
// Setup empty CP
data[80..84].copy_from_slice(&0u32.to_le_bytes());
// Setup code with PushConst 0
data[128..130].copy_from_slice(&(OpCode::PushConst as u16).to_le_bytes());
data[130..134].copy_from_slice(&0u32.to_le_bytes());
data[160..164].copy_from_slice(&0u32.to_le_bytes());
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidConstIndex));
}
#[test]
fn test_missing_sysc_section_is_rejected() {
let data = create_header(0);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MissingSyscallSection));
}
#[test]
fn test_valid_minimal_load_with_empty_sysc() {
let data = minimal_module().serialize();
let module = BytecodeLoader::load(&data).unwrap();
assert_eq!(module.version, 0);
assert!(module.const_pool.is_empty());
assert!(module.functions.is_empty());
assert!(module.code.is_empty());
assert!(module.syscalls.is_empty());
}
#[test]
fn test_valid_sysc_roundtrip() {
let mut module = minimal_module();
module.syscalls = vec![SyscallDecl {
module: "gfx2d".into(),
name: "draw_line".into(),
version: 1,
arg_slots: 4,
ret_slots: 0,
}];
let data = module.serialize();
let loaded = BytecodeLoader::load(&data).unwrap();
assert_eq!(loaded.syscalls, module.syscalls);
}
#[test]
fn test_malformed_sysc_section_is_rejected() {
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, vec![1, 0, 0])]);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MalformedSection));
}
#[test]
fn test_invalid_utf8_in_sysc_section_is_rejected() {
let mut sysc = Vec::new();
sysc.extend_from_slice(&1u32.to_le_bytes());
sysc.extend_from_slice(&1u16.to_le_bytes());
sysc.push(0xFF);
sysc.extend_from_slice(&1u16.to_le_bytes());
sysc.push(b'x');
sysc.extend_from_slice(&1u16.to_le_bytes());
sysc.extend_from_slice(&0u16.to_le_bytes());
sysc.extend_from_slice(&0u16.to_le_bytes());
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, sysc)]);
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidUtf8));
}
#[test]
fn test_duplicate_sysc_identity_is_rejected() {
let mut module = minimal_module();
module.syscalls = vec![
SyscallDecl {
module: "system".into(),
name: "has_cart".into(),
version: 1,
arg_slots: 0,
ret_slots: 1,
},
SyscallDecl {
module: "system".into(),
name: "has_cart".into(),
version: 1,
arg_slots: 0,
ret_slots: 1,
},
];
let data = module.serialize();
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::DuplicateSyscallIdentity));
}
}
+70 -38
View File
@@ -143,46 +143,20 @@ pub enum OpCode {
/// Returns from the current function.
/// Stack: [return_val] -> [return_val]
Ret = 0x51,
/// Creates a closure capturing values from the operand stack (Model B).
/// Operands: fn_id (u32), capture_count (u32)
/// Stack before: [..., captured_N, ..., captured_1]
/// Pops capture_count values (top-first), preserves order as [captured_1..captured_N]
/// and stores them inside the closure environment. Pushes a HeapRef to the closure.
/// Create a typed instance: FunctionId, FnTypeId. Captures come from metadata.
MakeClosure = 0x52,
/// Calls a closure value with hidden arg0 semantics (Model B).
/// Operand: arg_count (u32) — number of user-supplied args (excludes hidden arg0)
/// Stack before: [..., argN, ..., arg1, closure_ref]
/// Behavior:
/// - Pops `closure_ref` and validates it is a Closure.
/// - Pops `arg_count` user args.
/// - Fetches `fn_id` from the closure and creates a new call frame.
/// - Injects hidden arg0 = closure_ref, followed by user args as arg1..argN.
/// Invoke with expected FnTypeId; environment belongs to CallFrame, not arg0.
CallClosure = 0x53,
// --- 7.x Concurrency / Coroutines ---
/// Spawns a new coroutine to run a function with arguments.
/// Operands: fn_id (u32), arg_count (u32)
/// Semantics:
/// - Pops `arg_count` arguments from the current operand stack (top-first),
/// preserving user order as arg1..argN for the callee.
/// - Allocates a new Coroutine object with its own stack and a single entry frame
/// pointing at `fn_id`.
/// - Enqueues the coroutine into the scheduler ready queue.
/// - Does NOT switch execution immediately; current coroutine continues.
/// Retired opcode, recognized only for load rejection and diagnostics.
Spawn = 0x54,
/// Cooperatively yields the current coroutine. Execution continues
/// until the next VM safepoint (FRAME_SYNC), where the scheduler
/// may switch to another ready coroutine.
/// Retired opcode, recognized only for load rejection and diagnostics.
Yield = 0x55,
/// Suspends the current coroutine for a number of logical ticks.
/// Operand: duration_ticks (u32)
/// Semantics:
/// - Set the coroutine wake tick to `current_tick + duration_ticks`.
/// - End the current logical frame (as if reaching FRAME_SYNC).
/// - The coroutine will resume execution on or after the wake tick.
/// Retired opcode, recognized only for load rejection and diagnostics.
Sleep = 0x56,
/// Copy complete current-frame capture group by declaration index.
GetCapture = 0x57,
/// Dispatch through an immutable implementation: TraitTypeId, method index.
CallTrait = 0x58,
// --- 6.8 Peripherals and System ---
/// Pre-load host binding call by `SYSC` table index.
@@ -202,6 +176,31 @@ pub enum OpCode {
/// Synchronizes the VM with the hardware frame (usually 60Hz).
/// Execution pauses until the next VSync.
FrameSync = 0x80,
// Registry-dependent typed operations (DEC-0045).
/// DYN_PACK: TypeId:u32; requires validated Registry metadata.
DynPack = 0x90,
/// DYN_UNPACK: TypeId:u32; requires validated Registry metadata.
DynUnpack = 0x91,
/// DYN_CAN_UNPACK: TypeId:u32; requires validated Registry metadata.
DynCanUnpack = 0x92,
/// REF_IS_EXACT: source:TypeId, target:TypeId; requires validated Registry metadata.
RefIsExact = 0x93,
/// REF_IMPLEMENTS: source:TypeId, target:TypeId; requires validated Registry metadata.
RefImplements = 0x94,
/// REF_TO_TRAIT: source:TypeId, target:TypeId; requires validated Registry metadata.
RefToTrait = 0x95,
/// REF_CAST: source:TypeId, target:TypeId; requires validated Registry metadata.
RefCast = 0x96,
// Registry-backed collection operations. cycles() is their base component.
StructNew = 0xA0,
StructGet = 0xA1,
StructSet = 0xA2,
ArrayNew = 0xA3,
ArrayLen = 0xA4,
ArrayGet = 0xA5,
ArraySet = 0xA6,
}
impl TryFrom<u16> for OpCode {
@@ -255,18 +254,36 @@ impl TryFrom<u16> for OpCode {
0x54 => Ok(OpCode::Spawn),
0x55 => Ok(OpCode::Yield),
0x56 => Ok(OpCode::Sleep),
0x57 => Ok(OpCode::GetCapture),
0x58 => Ok(OpCode::CallTrait),
0x70 => Ok(OpCode::Syscall),
0x71 => Ok(OpCode::Hostcall),
0x72 => Ok(OpCode::Intrinsic),
0x80 => Ok(OpCode::FrameSync),
0x90 => Ok(OpCode::DynPack),
0x91 => Ok(OpCode::DynUnpack),
0x92 => Ok(OpCode::DynCanUnpack),
0x93 => Ok(OpCode::RefIsExact),
0x94 => Ok(OpCode::RefImplements),
0x95 => Ok(OpCode::RefToTrait),
0x96 => Ok(OpCode::RefCast),
0xA0 => Ok(OpCode::StructNew),
0xA1 => Ok(OpCode::StructGet),
0xA2 => Ok(OpCode::StructSet),
0xA3 => Ok(OpCode::ArrayNew),
0xA4 => Ok(OpCode::ArrayLen),
0xA5 => Ok(OpCode::ArrayGet),
0xA6 => Ok(OpCode::ArraySet),
_ => Err(format!("Invalid OpCode: 0x{:04X}", value)),
}
}
}
impl OpCode {
/// Returns the cost of the instruction in VM cycles.
/// This is used for performance monitoring and resource limiting (Certification).
/// Returns fixed VM cycles, or the base component for collection operations.
/// Collection execution adds Registry widths and valid construction length;
/// callers must not use this base alone as the complete attempt cost.
pub fn cycles(&self) -> u64 {
match self {
OpCode::Nop => 1,
@@ -311,7 +328,8 @@ impl OpCode {
OpCode::Call => 5,
OpCode::Ret => 4,
OpCode::MakeClosure => 8,
OpCode::CallClosure => 6,
OpCode::CallClosure | OpCode::CallTrait => 6,
OpCode::GetCapture => 2,
OpCode::Spawn => 6,
OpCode::Yield => 1,
OpCode::Sleep => 1,
@@ -319,6 +337,20 @@ impl OpCode {
OpCode::Hostcall => 1,
OpCode::Intrinsic => 1,
OpCode::FrameSync => 1,
OpCode::DynPack => 8,
OpCode::DynUnpack => 4,
OpCode::DynCanUnpack => 3,
OpCode::RefIsExact => 4,
OpCode::RefImplements => 4,
OpCode::RefToTrait => 5,
OpCode::RefCast => 4,
OpCode::StructNew => 8,
OpCode::StructGet => 3,
OpCode::StructSet => 4,
OpCode::ArrayNew => 8,
OpCode::ArrayLen => 3,
OpCode::ArrayGet => 3,
OpCode::ArraySet => 4,
}
}
}
@@ -5,18 +5,24 @@ use crate::opcode::OpCode;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OpcodeSpec {
pub name: &'static str,
pub imm_bytes: u8, // immediate payload size (decode)
pub pops: u16, // slots popped
pub pushes: u16, // slots pushed
pub is_branch: bool, // has a control-flow target
pub imm_bytes: u8, // immediate payload size (decode)
/// None requires Registry resolution; it never means zero slots.
pub pops: Option<u16>, // slots popped
/// None requires Registry resolution; it never means zero slots.
pub pushes: Option<u16>, // slots pushed
pub is_branch: bool, // has a control-flow target
pub is_terminator: bool, // ends basic block: JMP/RET/TRAP/HALT
pub may_trap: bool, // runtime trap possible
/// Marks this opcode as a VM safepoint. Used by GC/scheduler policies.
pub may_trap: bool, // runtime trap possible
/// Marks this opcode as a VM safepoint. Used by GC policies. Last-root RET is also a contextual GC opportunity.
pub is_safepoint: bool,
}
pub trait OpCodeSpecExt {
fn spec(&self) -> OpcodeSpec;
/// These instructions cannot be verified from slot-only ExecutionFunction.
fn requires_registry(&self) -> bool {
self.spec().pops.is_none() || self.spec().pushes.is_none()
}
}
impl OpCodeSpecExt for OpCode {
@@ -25,8 +31,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Nop => OpcodeSpec {
name: "NOP",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -35,8 +41,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Halt => OpcodeSpec {
name: "HALT",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: true,
may_trap: false,
@@ -45,8 +51,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Jmp => OpcodeSpec {
name: "JMP",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: true,
is_terminator: true,
may_trap: false,
@@ -55,8 +61,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::JmpIfFalse => OpcodeSpec {
name: "JMP_IF_FALSE",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: true,
is_terminator: false,
may_trap: true,
@@ -65,8 +71,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::JmpIfTrue => OpcodeSpec {
name: "JMP_IF_TRUE",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: true,
is_terminator: false,
may_trap: true,
@@ -75,8 +81,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Trap => OpcodeSpec {
name: "TRAP",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: true,
may_trap: true,
@@ -85,8 +91,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushConst => OpcodeSpec {
name: "PUSH_CONST",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -95,8 +101,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Pop => OpcodeSpec {
name: "POP",
imm_bytes: 0,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -105,8 +111,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PopN => OpcodeSpec {
name: "POP_N",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -115,8 +121,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Dup => OpcodeSpec {
name: "DUP",
imm_bytes: 0,
pops: 1,
pushes: 2,
pops: Some(1),
pushes: Some(2),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -125,8 +131,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Swap => OpcodeSpec {
name: "SWAP",
imm_bytes: 0,
pops: 2,
pushes: 2,
pops: Some(2),
pushes: Some(2),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -135,8 +141,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushI64 => OpcodeSpec {
name: "PUSH_I64",
imm_bytes: 8,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -145,8 +151,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushF64 => OpcodeSpec {
name: "PUSH_F64",
imm_bytes: 8,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -155,8 +161,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushBool => OpcodeSpec {
name: "PUSH_BOOL",
imm_bytes: 1,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -165,8 +171,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::PushI32 => OpcodeSpec {
name: "PUSH_I32",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -175,8 +181,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Add => OpcodeSpec {
name: "ADD",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -185,8 +191,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Sub => OpcodeSpec {
name: "SUB",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -195,8 +201,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Mul => OpcodeSpec {
name: "MUL",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -205,8 +211,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Div => OpcodeSpec {
name: "DIV",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -215,8 +221,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Mod => OpcodeSpec {
name: "MOD",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -225,8 +231,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Eq => OpcodeSpec {
name: "EQ",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -235,8 +241,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Neq => OpcodeSpec {
name: "NEQ",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -245,8 +251,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Lt => OpcodeSpec {
name: "LT",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -255,8 +261,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Gt => OpcodeSpec {
name: "GT",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -265,8 +271,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::And => OpcodeSpec {
name: "AND",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -275,8 +281,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Or => OpcodeSpec {
name: "OR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -285,8 +291,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Not => OpcodeSpec {
name: "NOT",
imm_bytes: 0,
pops: 1,
pushes: 1,
pops: Some(1),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -295,8 +301,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitAnd => OpcodeSpec {
name: "BIT_AND",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -305,8 +311,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitOr => OpcodeSpec {
name: "BIT_OR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -315,8 +321,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::BitXor => OpcodeSpec {
name: "BIT_XOR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -325,8 +331,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Shl => OpcodeSpec {
name: "SHL",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -335,8 +341,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Shr => OpcodeSpec {
name: "SHR",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -345,8 +351,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Lte => OpcodeSpec {
name: "LTE",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -355,8 +361,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Gte => OpcodeSpec {
name: "GTE",
imm_bytes: 0,
pops: 2,
pushes: 1,
pops: Some(2),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -365,8 +371,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Neg => OpcodeSpec {
name: "NEG",
imm_bytes: 0,
pops: 1,
pushes: 1,
pops: Some(1),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -375,8 +381,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::GetGlobal => OpcodeSpec {
name: "GET_GLOBAL",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -385,8 +391,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::SetGlobal => OpcodeSpec {
name: "SET_GLOBAL",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -395,8 +401,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::GetLocal => OpcodeSpec {
name: "GET_LOCAL",
imm_bytes: 4,
pops: 0,
pushes: 1,
pops: Some(0),
pushes: Some(1),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -405,8 +411,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::SetLocal => OpcodeSpec {
name: "SET_LOCAL",
imm_bytes: 4,
pops: 1,
pushes: 0,
pops: Some(1),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -415,8 +421,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Call => OpcodeSpec {
name: "CALL",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -425,44 +431,41 @@ impl OpCodeSpecExt for OpCode {
OpCode::Ret => OpcodeSpec {
name: "RET",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: true,
may_trap: false,
is_safepoint: false,
},
OpCode::MakeClosure => OpcodeSpec {
name: "MAKE_CLOSURE",
// Two u32 immediates: fn_id and capture_count
imm_bytes: 8,
// Dynamic, depends on capture_count; keep 0 here for verifier-free spec
pops: 0,
pushes: 1,
is_branch: false,
is_terminator: false,
may_trap: false,
is_safepoint: false,
},
OpCode::CallClosure => OpcodeSpec {
name: "CALL_CLOSURE",
// One u32 immediate: arg_count (user args, excludes hidden arg0)
imm_bytes: 4,
// Dynamic: pops closure_ref + arg_count; keep 0 in spec layer
pops: 0,
pushes: 0,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::MakeClosure | OpCode::CallClosure | OpCode::GetCapture | OpCode::CallTrait => {
OpcodeSpec {
name: match self {
OpCode::MakeClosure => "MAKE_CLOSURE",
OpCode::CallClosure => "CALL_CLOSURE",
OpCode::GetCapture => "GET_CAPTURE",
_ => "CALL_TRAIT",
},
imm_bytes: if matches!(self, OpCode::MakeClosure | OpCode::CallTrait) {
8
} else {
4
},
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
}
}
OpCode::Spawn => OpcodeSpec {
name: "SPAWN",
// Two u32 immediates: fn_id and arg_count
imm_bytes: 8,
// Dynamic pops depends on arg_count; keep 0 here in spec layer
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -471,33 +474,33 @@ impl OpCodeSpecExt for OpCode {
OpCode::Yield => OpcodeSpec {
name: "YIELD",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
// Not a block terminator; effect realized at safepoint
// Retired encoding: retained for diagnostic decoding only.
is_terminator: false,
may_trap: false,
// Treated as a safepoint marker for cooperative scheduling
is_safepoint: true,
// Loading rejects this opcode, including unreachable occurrences.
is_safepoint: false,
},
OpCode::Sleep => OpcodeSpec {
name: "SLEEP",
// One u32 immediate: duration_ticks
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
// Ends execution at safepoint after instruction completes
// Retired encoding: retained for diagnostic decoding only.
is_terminator: false,
may_trap: false,
// Considered a safepoint since it forces a frame boundary
is_safepoint: true,
// Loading rejects this opcode, including unreachable occurrences.
is_safepoint: false,
},
OpCode::Hostcall => OpcodeSpec {
name: "HOSTCALL",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -506,8 +509,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::Syscall => OpcodeSpec {
name: "SYSCALL",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -516,8 +519,148 @@ impl OpCodeSpecExt for OpCode {
OpCode::Intrinsic => OpcodeSpec {
name: "INTRINSIC",
imm_bytes: 4,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::DynPack => OpcodeSpec {
name: "DYN_PACK",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::DynUnpack => OpcodeSpec {
name: "DYN_UNPACK",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::DynCanUnpack => OpcodeSpec {
name: "DYN_CAN_UNPACK",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefIsExact => OpcodeSpec {
name: "REF_IS_EXACT",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefImplements => OpcodeSpec {
name: "REF_IMPLEMENTS",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefToTrait => OpcodeSpec {
name: "REF_TO_TRAIT",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::RefCast => OpcodeSpec {
name: "REF_CAST",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::StructNew => OpcodeSpec {
name: "STRUCT_NEW",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::StructGet => OpcodeSpec {
name: "STRUCT_GET",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::StructSet => OpcodeSpec {
name: "STRUCT_SET",
imm_bytes: 8,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayNew => OpcodeSpec {
name: "ARRAY_NEW",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayLen => OpcodeSpec {
name: "ARRAY_LEN",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArrayGet => OpcodeSpec {
name: "ARRAY_GET",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
is_safepoint: false,
},
OpCode::ArraySet => OpcodeSpec {
name: "ARRAY_SET",
imm_bytes: 4,
pops: None,
pushes: None,
is_branch: false,
is_terminator: false,
may_trap: true,
@@ -526,8 +669,8 @@ impl OpCodeSpecExt for OpCode {
OpCode::FrameSync => OpcodeSpec {
name: "FRAME_SYNC",
imm_bytes: 0,
pops: 0,
pushes: 0,
pops: Some(0),
pushes: Some(0),
is_branch: false,
is_terminator: false,
may_trap: false,
@@ -1,43 +1,35 @@
/// Resolved execution widths derived from sealed Registry metadata.
/// This cache is never serialized as a PBX function signature.
#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
pub struct ExecutionFunction {
pub code_offset: u32,
pub code_len: u32,
pub param_slots: u16,
pub local_slots: u16,
pub return_slots: u16,
pub max_stack_slots: u16,
}
use crate::abi::TrapInfo;
use crate::model::{BytecodeModule, ConstantPoolEntry, DebugInfo, Export, FunctionMeta};
use crate::model::DebugInfo;
use crate::value::Value;
use serde::{Deserialize, Serialize};
use std::collections::HashMap;
use std::sync::Arc;
/// Represents a fully linked, executable PBX program image.
///
/// Under the Prometeu architecture, the ProgramImage is a "closed-world" artifact
/// produced by the compiler. All linking, relocation, and symbol resolution
/// MUST be performed by the compiler before this image is created.
///
/// The runtime (VM) assumes this image is authoritative and performs no
/// additional linking or fixups.
/// Immutable execution payload/cache, produced during sealed image publication.
/// This container does not authorize execution. VM sessions require the private
/// ValidatedProgramImage factory, including bounded Registry/ISA/native checks.
#[derive(Debug, Clone, Default)]
pub struct ProgramImage {
pub rom: Arc<[u8]>,
pub constant_pool: Arc<[Value]>,
pub functions: Arc<[FunctionMeta]>,
pub debug_info: Option<DebugInfo>,
pub functions: Arc<[ExecutionFunction]>,
pub debug_info: Option<Arc<DebugInfo>>,
pub exports: Arc<HashMap<String, u32>>,
}
impl ProgramImage {
pub fn new(
rom: Vec<u8>,
constant_pool: Vec<Value>,
functions: Vec<FunctionMeta>,
debug_info: Option<DebugInfo>,
exports: HashMap<String, u32>,
) -> Self {
Self {
rom: Arc::from(rom),
constant_pool: Arc::from(constant_pool),
functions: Arc::from(functions),
debug_info,
exports: Arc::new(exports),
}
}
pub fn create_trap(&self, code: u32, opcode: u16, mut message: String, pc: u32) -> TrapInfo {
let span = self
.debug_info
@@ -50,7 +42,7 @@ impl ProgramImage {
}
}
TrapInfo { code, opcode, message, pc, span }
TrapInfo { code, opcode, message, pc, span, resource: None }
}
pub fn find_function_index(&self, pc: u32) -> Option<usize> {
@@ -64,61 +56,3 @@ impl ProgramImage {
.map(|(_, name)| name.as_str())
}
}
impl From<BytecodeModule> for ProgramImage {
fn from(module: BytecodeModule) -> Self {
let constant_pool: Vec<Value> = module
.const_pool
.iter()
.map(|entry| match entry {
ConstantPoolEntry::Null => Value::Null,
ConstantPoolEntry::Int64(v) => Value::Int64(*v),
ConstantPoolEntry::Float64(v) => Value::Float(*v),
ConstantPoolEntry::Boolean(v) => Value::Boolean(*v),
ConstantPoolEntry::String(v) => Value::string(v.clone()),
ConstantPoolEntry::Int32(v) => Value::Int32(*v),
})
.collect();
let mut exports = HashMap::new();
for export in module.exports {
exports.insert(export.symbol, export.func_idx);
}
ProgramImage::new(module.code, constant_pool, module.functions, module.debug_info, exports)
}
}
impl From<ProgramImage> for BytecodeModule {
fn from(program: ProgramImage) -> Self {
let const_pool = program
.constant_pool
.iter()
.map(|v| match v {
Value::Null => ConstantPoolEntry::Null,
Value::Int64(v) => ConstantPoolEntry::Int64(*v),
Value::Float(v) => ConstantPoolEntry::Float64(*v),
Value::Boolean(v) => ConstantPoolEntry::Boolean(*v),
Value::String(v) => ConstantPoolEntry::String(v.to_string()),
Value::Int32(v) => ConstantPoolEntry::Int32(*v),
Value::HeapRef(_) => ConstantPoolEntry::Null,
})
.collect();
let exports = program
.exports
.iter()
.map(|(symbol, &func_idx)| Export { symbol: symbol.clone(), func_idx })
.collect();
BytecodeModule {
version: 0,
const_pool,
functions: program.functions.as_ref().to_vec(),
code: program.rom.as_ref().to_vec(),
debug_info: program.debug_info.clone(),
exports,
syscalls: Vec::new(),
}
}
}
@@ -0,0 +1,833 @@
//! Typed PBX declarations and bounded immutable Registry resolution.
//! These declarations do not authorize execution: code and bindings still require verification.
use crate::load_limits::IdDomain;
use crate::load_limits::{
LoadBudget, LoadCode as C, LoadFailure as E, LoadReason as R, LoadResource as Q,
};
use crate::Value;
use std::sync::Arc;
macro_rules! id {
($name:ident) => {
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct $name(pub u32);
};
}
id!(TypeId);
id!(FunctionId);
id!(ImplementationId);
id!(BuiltinId);
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct NamedType {
pub type_id: TypeId,
pub name: Option<String>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Signature {
pub parameters: Vec<NamedType>,
pub results: Vec<TypeId>,
}
impl Signature {
pub fn same_types(&self, other: &Self) -> bool {
self.parameters.len() == other.parameters.len()
&& self
.parameters
.iter()
.map(|p| p.type_id)
.eq(other.parameters.iter().map(|p| p.type_id))
&& self.results == other.results
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MethodDecl {
pub name: Option<String>,
pub signature: Signature,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum TypeKind {
Builtin(BuiltinId),
Struct(Vec<NamedType>),
Array(TypeId),
Trait(Vec<MethodDecl>),
Fn(Signature),
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct TypeDecl {
pub name: Option<String>,
pub kind: TypeKind,
}
/// Runtime-owned roles; frontend names and FunctionIds are independent.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[repr(u8)]
pub enum LifecycleRole {
#[default]
None = 0,
BeforePause = 1,
BeforeResume = 2,
MemcardBoot = 3,
}
impl TryFrom<u8> for LifecycleRole {
type Error = E;
fn try_from(value: u8) -> Result<Self, E> {
match value {
0 => Ok(Self::None),
1 => Ok(Self::BeforePause),
2 => Ok(Self::BeforeResume),
3 => Ok(Self::MemcardBoot),
_ => Err(E::new(C::InvalidRegistry, R::LifecycleRole)),
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FunctionDecl {
pub lifecycle_role: LifecycleRole,
pub name: Option<String>,
pub signature: Signature,
pub code_offset: u32,
pub code_len: u32,
pub local_slots: u32,
pub max_stack_slots: u32,
/// Ordered logical capture groups, encoded in the separate PBX section 8.
pub captures: Vec<TypeId>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImplementationDecl {
pub owner: TypeId,
pub trait_id: TypeId,
pub methods: Vec<FunctionId>,
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct RegistryDeclarations {
pub types: Vec<TypeDecl>,
pub functions: Vec<FunctionDecl>,
pub implementations: Vec<ImplementationDecl>,
}
pub type StringSlot = Option<Arc<str>>;
#[derive(Debug, Clone)]
pub struct DynamicSlot {
pub type_id: Option<TypeId>,
pub payload: Value,
}
impl Default for DynamicSlot {
fn default() -> Self {
Self { type_id: None, payload: Value::Null }
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DefaultKind {
Int32,
Int64,
Float,
Bool,
Null,
Vec2,
Pixel,
Trait,
Dynamic,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Ownership {
Plain,
GuestReference,
NativeString,
TraitReceiver,
Dynamic,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StorageLayout {
pub size: usize,
pub alignment: usize,
pub slots: u32,
pub ownership: Ownership,
pub default: DefaultKind,
}
impl StorageLayout {
fn new(
size: usize,
alignment: usize,
slots: u32,
ownership: Ownership,
default: DefaultKind,
) -> Self {
Self { size, alignment, slots, ownership, default }
}
pub fn nullable(self) -> bool {
!matches!(self.ownership, Ownership::Plain)
}
/// Canonical stack-side defaults, with no allocation or source constructor.
/// Native typed storage still requires its own initialized-slot construction.
pub fn default_values(self) -> &'static [Value] {
match self.default {
DefaultKind::Int32 => &[Value::Int32(0)],
DefaultKind::Int64 => &[Value::Int64(0)],
DefaultKind::Float => &[Value::Float(0.0)],
DefaultKind::Bool => &[Value::Boolean(false)],
DefaultKind::Null => &[Value::Null],
DefaultKind::Vec2 => &[Value::Float(0.0), Value::Float(0.0)],
DefaultKind::Pixel => &[Value::Int64(0), Value::Int64(0), Value::Int64(0)],
DefaultKind::Trait | DefaultKind::Dynamic => &[Value::Null, Value::Null],
}
}
}
impl BuiltinId {
pub const COLOR: Self = Self(1);
pub const VEC2: Self = Self(2);
pub const PIXEL: Self = Self(3);
pub const INT32: Self = Self(0x10);
pub const INT64: Self = Self(0x11);
pub const FLOAT: Self = Self(0x12);
pub const BOOL: Self = Self(0x13);
pub const STRING: Self = Self(0x14);
pub const DYNAMIC: Self = Self(0x15);
pub const RANDOM: Self = Self(0x16);
pub fn layout(self) -> Result<StorageLayout, E> {
use DefaultKind as D;
use Ownership as O;
let (size, alignment, slots, ownership, default) = match self {
Self::COLOR => (4, 4, 1, O::Plain, D::Int64),
Self::VEC2 => (16, 8, 2, O::Plain, D::Vec2),
Self::PIXEL => (24, 8, 3, O::Plain, D::Pixel),
Self::INT32 => (4, 4, 1, O::Plain, D::Int32),
Self::INT64 => (8, 8, 1, O::Plain, D::Int64),
Self::FLOAT => (8, 8, 1, O::Plain, D::Float),
Self::BOOL => (1, 1, 1, O::Plain, D::Bool),
Self::RANDOM => (8, 8, 1, O::GuestReference, D::Null),
Self::STRING => {
(size_of::<StringSlot>(), align_of::<StringSlot>(), 1, O::NativeString, D::Null)
}
Self::DYNAMIC => {
(size_of::<DynamicSlot>(), align_of::<DynamicSlot>(), 2, O::Dynamic, D::Dynamic)
}
_ => return Err(E::new(C::UnsupportedFormat, R::Builtin)),
};
Ok(StorageLayout::new(size, alignment, slots, ownership, default))
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct FieldLayout {
pub type_id: TypeId,
pub offset: usize,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct OwnedField {
pub offset: usize,
pub ownership: Ownership,
}
#[derive(Debug, PartialEq, Eq)]
pub struct StructLayout {
/// Sum of execution-slot widths, resolved once for deterministic NEW charging.
pub initialization_slots: u64,
pub size: usize,
pub alignment: usize,
pub fields: Vec<FieldLayout>,
/// Sorted offsets for fields requiring guest tracing or native ownership handling.
pub owned_fields: Vec<OwnedField>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ArrayLayout {
pub element_type_id: TypeId,
pub stride: usize,
pub element_alignment: usize,
}
#[derive(Debug, PartialEq, Eq)]
pub struct TypeLayout {
pub storage: StorageLayout,
pub instance: Option<StructLayout>,
pub array: Option<ArrayLayout>,
pub callable: Option<FunctionLayout>,
pub methods: Vec<FunctionLayout>,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CaptureLayout {
pub type_id: TypeId,
pub slot_offset: u32,
pub slots: u32,
}
#[derive(Debug, PartialEq, Eq)]
pub struct FunctionLayout {
pub parameter_slots: u32,
pub result_slots: u32,
pub capture_slots: u32,
pub captures: Vec<CaptureLayout>,
}
#[derive(Debug)]
pub struct Registry {
lifecycle_hooks: [Option<FunctionId>; 3],
declarations: RegistryDeclarations,
layouts: Vec<TypeLayout>,
functions: Vec<FunctionLayout>,
// Sorted by owner/trait; original implementation IDs are never remapped.
implementations: Vec<(TypeId, TypeId, ImplementationId)>,
}
impl Registry {
pub fn lifecycle_hook(&self, role: LifecycleRole) -> Option<FunctionId> {
match role {
LifecycleRole::None => None,
LifecycleRole::BeforePause => self.lifecycle_hooks[0],
LifecycleRole::BeforeResume => self.lifecycle_hooks[1],
LifecycleRole::MemcardBoot => self.lifecycle_hooks[2],
}
}
pub fn declarations(&self) -> &RegistryDeclarations {
&self.declarations
}
pub fn type_layout(&self, id: TypeId) -> Option<&TypeLayout> {
self.layouts.get(id.0 as usize)
}
pub fn function_layout(&self, id: FunctionId) -> Option<&FunctionLayout> {
self.functions.get(id.0 as usize)
}
pub fn implementation(&self, owner: TypeId, trait_id: TypeId) -> Option<ImplementationId> {
self.implementations
.binary_search_by_key(&(owner, trait_id), |&(a, b, _)| (a, b))
.ok()
.map(|i| self.implementations[i].2)
}
/// Resolves declarations, not code/bindings. The caller must still verify before publication.
/// Declaration allocations are retained and charged here, even for non-PBX producers.
pub fn resolve(
declarations: RegistryDeclarations,
code_len: usize,
budget: &mut LoadBudget,
) -> Result<Self, E> {
budget.transaction(|budget| Self::resolve_inner(declarations, code_len, budget))
}
fn resolve_inner(
d: RegistryDeclarations,
code_len: usize,
b: &mut LoadBudget,
) -> Result<Self, E> {
b.check(Q::Types, d.types.len() as u64)?;
b.check(Q::Functions, d.functions.len() as u64)?;
b.check(Q::Implementations, d.implementations.len() as u64)?;
b.check(Q::CodeBytes, code_len as u64)?;
charge_declarations(&d, b)?;
validate_declarations(&d, b)?;
let mut layouts = b.vector(d.types.len(), Q::RegistryBytes)?;
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
let storage = match t.kind {
TypeKind::Builtin(id) => id.layout().map_err(|e| e.record(i as u32))?,
TypeKind::Trait(_) => {
StorageLayout::new(16, 8, 2, Ownership::TraitReceiver, DefaultKind::Trait)
}
_ => StorageLayout::new(8, 8, 1, Ownership::GuestReference, DefaultKind::Null),
};
layouts.push(TypeLayout {
storage,
instance: None,
array: None,
callable: None,
methods: Vec::new(),
});
}
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
if let TypeKind::Fn(s) = &t.kind {
layouts[i].callable = Some(resolve_signature(s, &layouts, b)?);
}
if let TypeKind::Trait(methods) = &t.kind {
let mut resolved = b.vector(methods.len(), Q::RegistryBytes)?;
for method in methods {
b.work(1)?;
resolved.push(resolve_signature(&method.signature, &layouts, b)?);
}
layouts[i].methods = resolved;
}
if let TypeKind::Array(element_type_id) = t.kind {
let element = layouts[element_type_id.0 as usize].storage;
layouts[i].array = Some(ArrayLayout {
element_type_id,
stride: align(element.size, element.alignment)?,
element_alignment: element.alignment,
});
}
if let TypeKind::Struct(fields) = &t.kind {
let mut offsets = b.vector(fields.len(), Q::RegistryBytes)?;
b.work(fields.len())?;
let owned_count = fields
.iter()
.filter(|f| layouts[f.type_id.0 as usize].storage.ownership != Ownership::Plain)
.count();
let mut owned = b.vector(owned_count, Q::RegistryBytes)?;
let (mut size, mut alignment) = (0, 1);
let mut initialization_slots = 0u64;
for field in fields {
b.work(1)?;
let layout = layouts[field.type_id.0 as usize].storage;
initialization_slots = initialization_slots
.checked_add(u64::from(layout.slots))
.ok_or_else(overflow)?;
size = align(size, layout.alignment)?;
offsets.push(FieldLayout { type_id: field.type_id, offset: size });
if layout.ownership != Ownership::Plain {
owned.push(OwnedField { offset: size, ownership: layout.ownership });
}
size = size.checked_add(layout.size).ok_or_else(overflow)?;
alignment = alignment.max(layout.alignment);
}
layouts[i].instance = Some(StructLayout {
initialization_slots,
size: align(size, alignment)?,
alignment,
fields: offsets,
owned_fields: owned,
});
}
}
let mut lifecycle_hooks = [None; 3];
let mut functions = b.vector(d.functions.len(), Q::RegistryBytes)?;
let mut ranges = b.vector(d.functions.len(), Q::TemporaryBytes)?;
for (i, f) in d.functions.iter().enumerate() {
b.work(1)?;
if f.lifecycle_role != LifecycleRole::None {
let signature_valid = if f.lifecycle_role == LifecycleRole::MemcardBoot {
f.signature.parameters.len() == 1
&& f.signature.results.len() == 1
&& d.types
.get(f.signature.parameters[0].type_id.0 as usize)
.is_some_and(|t| t.kind == TypeKind::Builtin(BuiltinId::INT64))
&& d.types
.get(f.signature.results[0].0 as usize)
.is_some_and(|t| t.kind == TypeKind::Builtin(BuiltinId::INT32))
} else {
f.signature.parameters.is_empty() && f.signature.results.is_empty()
};
let invalid = i == 0 || !signature_valid || !f.captures.is_empty();
if invalid {
return Err(E::new(C::InvalidEntrypoint, R::LifecycleSignature)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
let slot = &mut lifecycle_hooks[f.lifecycle_role as usize - 1];
if slot.replace(FunctionId(i as u32)).is_some() {
return Err(E::new(C::InvalidRegistry, R::DuplicateLifecycleRole)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
}
let params = width(f.signature.parameters.iter().map(|p| p.type_id), &layouts, b)?;
let results = width(f.signature.results.iter().copied(), &layouts, b)?;
let frame = u64::from(params) + u64::from(f.local_slots) + u64::from(f.max_stack_slots);
if frame > b.frame_limit() {
return Err(E::new(C::InvalidCode, R::FrameSlots)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
if u64::from(results) > b.result_limit() {
return Err(E::new(C::InvalidCode, R::ReturnSlots)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
let end = f.code_offset.checked_add(f.code_len).ok_or_else(|| {
E::new(C::InvalidCode, R::CodeRange)
.in_section(1)
.record(i as u32)
.in_function(i as u32, Some(f.code_offset))
})?;
if end as usize > code_len || f.code_len == 0 {
return Err(E::new(C::InvalidCode, R::CodeRange)
.in_section(1)
.record(i as u32)
.in_function(i as u32, Some(f.code_offset)));
}
ranges.push((f.code_offset, end, i as u32));
let mut captures = b.vector(f.captures.len(), Q::RegistryBytes)?;
let mut capture_slots = 0u32;
for &type_id in &f.captures {
b.work(1)?;
let slots = layouts[type_id.0 as usize].storage.slots;
captures.push(CaptureLayout { type_id, slot_offset: capture_slots, slots });
capture_slots = capture_slots.checked_add(slots).ok_or_else(overflow)?;
}
functions.push(FunctionLayout {
parameter_slots: params,
result_slots: results,
capture_slots,
captures,
});
}
sort_work(ranges.len(), b)?;
ranges.sort_unstable();
for pair in ranges.windows(2) {
b.work(1)?;
if pair[0].1 > pair[1].0 {
return Err(E::new(C::InvalidCode, R::CodeRange).record(pair[1].2));
}
}
b.refund(Q::TemporaryBytes, (ranges.capacity() * size_of::<(u32, u32, u32)>()) as u64);
drop(ranges);
let mut implementations = b.vector(d.implementations.len(), Q::RegistryBytes)?;
for (i, imp) in d.implementations.iter().enumerate() {
b.work(1)?;
if !matches!(d.types[imp.owner.0 as usize].kind, TypeKind::Struct(_)) {
return Err(E::new(C::InvalidReference, R::OwnerCategory)
.in_section(7)
.record(i as u32)
.reference(IdDomain::Type, imp.owner.0));
}
let TypeKind::Trait(methods) = &d.types[imp.trait_id.0 as usize].kind else {
return Err(E::new(C::InvalidReference, R::TraitCategory)
.in_section(7)
.record(i as u32)
.reference(IdDomain::Type, imp.trait_id.0));
};
if methods.len() != imp.methods.len() {
return Err(E::new(C::InvalidRegistry, R::MethodCount)
.in_section(7)
.record(i as u32));
}
for (j, (method, id)) in methods.iter().zip(&imp.methods).enumerate() {
let signature = &d.functions[id.0 as usize].signature;
if !d.functions[id.0 as usize].captures.is_empty() {
return Err(E::new(C::InvalidRegistry, R::CapturedDirectCall)
.in_section(7)
.record(i as u32)
.member(j as u32));
}
b.work(signature.parameters.len() + signature.results.len() + 1)?;
if signature.parameters.first().map(|p| p.type_id) != Some(imp.owner)
|| signature.parameters.len() != method.signature.parameters.len() + 1
|| !signature.parameters.iter().skip(1).map(|p| p.type_id).eq(method
.signature
.parameters
.iter()
.map(|p| p.type_id))
|| signature.results != method.signature.results
{
return Err(E::new(C::InvalidRegistry, R::Signature)
.in_section(7)
.record(i as u32)
.member(j as u32));
}
}
implementations.push((imp.owner, imp.trait_id, ImplementationId(i as u32)));
}
sort_work(implementations.len(), b)?;
implementations.sort_unstable();
for pair in implementations.windows(2) {
b.work(1)?;
if (pair[0].0, pair[0].1) == (pair[1].0, pair[1].1) {
return Err(E::new(C::InvalidRegistry, R::DuplicateImplementation)
.in_section(7)
.record(pair[1].2 .0));
}
}
Ok(Self { lifecycle_hooks, declarations: d, layouts, functions, implementations })
}
}
fn overflow() -> E {
E::new(C::ResourceLimit, R::Overflow)
}
fn resolve_signature(
s: &Signature,
layouts: &[TypeLayout],
b: &mut LoadBudget,
) -> Result<FunctionLayout, E> {
let parameter_slots = width(s.parameters.iter().map(|p| p.type_id), layouts, b)?;
let result_slots = width(s.results.iter().copied(), layouts, b)?;
if u64::from(parameter_slots) > b.frame_limit() {
return Err(E::new(C::InvalidRegistry, R::FrameSlots));
}
if u64::from(result_slots) > b.result_limit() {
return Err(E::new(C::InvalidRegistry, R::ReturnSlots));
}
Ok(FunctionLayout { parameter_slots, result_slots, capture_slots: 0, captures: Vec::new() })
}
fn align(n: usize, a: usize) -> Result<usize, E> {
n.checked_add(a - 1).map(|v| v & !(a - 1)).ok_or_else(overflow)
}
fn width(
ids: impl Iterator<Item = TypeId>,
layouts: &[TypeLayout],
b: &mut LoadBudget,
) -> Result<u32, E> {
let mut sum = 0u32;
for id in ids {
b.work(1)?;
sum = sum.checked_add(layouts[id.0 as usize].storage.slots).ok_or_else(overflow)?;
}
Ok(sum)
}
fn sort_work(n: usize, b: &mut LoadBudget) -> Result<(), E> {
let bits = usize::BITS - n.leading_zeros();
b.work(n.checked_mul(bits as usize + 1).ok_or_else(overflow)?)
}
fn type_ref(id: TypeId, d: &RegistryDeclarations) -> Result<(), E> {
if (id.0 as usize) < d.types.len() {
Ok(())
} else {
Err(E::new(C::InvalidReference, R::TypeId).reference(IdDomain::Type, id.0))
}
}
fn name(name: &Option<String>, b: &mut LoadBudget) -> Result<(), E> {
if let Some(name) = name {
if name.len() as u64 > b.individual_name_limit() {
return Err(E::resource(Q::NameBytes, name.len() as u64, b.individual_name_limit()));
}
b.charge(Q::NameBytes, name.len() as u64)?;
b.work(name.len())?;
}
Ok(())
}
fn named(items: &[NamedType], d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::NestedRecords, items.len() as u64)?;
for (i, item) in items.iter().enumerate() {
b.work(1)?;
type_ref(item.type_id, d).map_err(|e| e.member(i as u32))?;
name(&item.name, b)?;
}
Ok(())
}
fn signature(s: &Signature, d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
named(&s.parameters, d, b)?;
b.charge(Q::NestedRecords, s.results.len() as u64)?;
for (i, id) in s.results.iter().enumerate() {
b.work(1)?;
type_ref(*id, d).map_err(|e| e.member(i as u32))?;
}
Ok(())
}
fn signature_order(
a: &Signature,
b: &Signature,
budget: &mut LoadBudget,
) -> Result<std::cmp::Ordering, E> {
use std::cmp::Ordering;
for (a, b) in a.parameters.iter().zip(&b.parameters) {
budget.work(1)?;
let order = a.type_id.cmp(&b.type_id);
if order != Ordering::Equal {
return Ok(order);
}
}
budget.work(1)?;
let order = a.parameters.len().cmp(&b.parameters.len());
if order != Ordering::Equal {
return Ok(order);
}
for (a, b) in a.results.iter().zip(&b.results) {
budget.work(1)?;
let order = a.cmp(b);
if order != Ordering::Equal {
return Ok(order);
}
}
budget.work(1)?;
Ok(a.results.len().cmp(&b.results.len()))
}
/// Validate all edges before indexed layout resolution; IDs remain table positions.
pub(crate) fn validate_declarations(d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::Types, d.types.len() as u64)?;
b.charge(Q::Functions, d.functions.len() as u64)?;
b.charge(Q::Implementations, d.implementations.len() as u64)?;
let mut constructors = b.vector(d.types.len(), Q::TemporaryBytes)?;
for (i, t) in d.types.iter().enumerate() {
b.work(1)?;
name(&t.name, b).map_err(|e| e.in_section(6).record(i as u32))?;
let result = (|| match &t.kind {
TypeKind::Builtin(id) => {
id.layout()?;
constructors.push((0, id.0, i as u32));
Ok(())
}
TypeKind::Array(id) => {
type_ref(*id, d)?;
constructors.push((1, id.0, i as u32));
Ok(())
}
TypeKind::Struct(fields) => named(fields, d, b),
TypeKind::Fn(s) => signature(s, d, b),
TypeKind::Trait(methods) => {
b.charge(Q::NestedRecords, methods.len() as u64)?;
for m in methods {
b.work(1)?;
name(&m.name, b)?;
signature(&m.signature, d, b)?;
}
Ok(())
}
})();
result.map_err(|e| e.in_section(6).record(i as u32))?;
}
sort_work(constructors.len(), b)?;
constructors.sort_unstable();
for pair in constructors.windows(2) {
b.work(1)?;
if (pair[0].0, pair[0].1) == (pair[1].0, pair[1].1) {
return Err(E::new(
C::InvalidRegistry,
if pair[1].0 == 0 { R::DuplicateBuiltin } else { R::DuplicateArray },
)
.record(pair[1].2));
}
}
b.refund(Q::TemporaryBytes, (constructors.capacity() * size_of::<(i32, u32, u32)>()) as u64);
drop(constructors);
// Sorted Fn indices use fallible, metered comparisons; names are never keys.
let mut fns = b.vector::<usize>(d.types.len(), Q::TemporaryBytes)?;
for (id, t) in d.types.iter().enumerate() {
b.work(1)?;
let TypeKind::Fn(key) = &t.kind else { continue };
let (mut lo, mut hi) = (0, fns.len());
while lo < hi {
let mid = lo + (hi - lo) / 2;
let TypeKind::Fn(other) = &d.types[fns[mid]].kind else { unreachable!() };
match signature_order(key, other, b)? {
std::cmp::Ordering::Equal => {
return Err(E::new(C::InvalidRegistry, R::DuplicateFn)
.in_section(6)
.record(id as u32))
}
std::cmp::Ordering::Less => hi = mid,
std::cmp::Ordering::Greater => lo = mid + 1,
}
}
b.work(fns.len() - lo + 1)?;
fns.insert(lo, id);
}
b.refund(Q::TemporaryBytes, (fns.capacity() * size_of::<usize>()) as u64);
drop(fns);
// Iterative DFS processes each structural edge once; nominal nodes are leaves.
let mut colors = b.vector::<u8>(d.types.len(), Q::TemporaryBytes)?;
b.work(d.types.len())?;
colors.resize(d.types.len(), 0);
let mut walk = b.vector::<(usize, usize)>(d.types.len(), Q::TemporaryBytes)?;
for start in 0..d.types.len() {
b.work(1)?;
if colors[start] != 0 {
continue;
}
colors[start] = 1;
walk.push((start, 0));
while let Some((node, edge)) = walk.last_mut() {
b.work(1)?;
let next = match &d.types[*node].kind {
TypeKind::Array(id) if *edge == 0 => Some(*id),
TypeKind::Fn(s) => s.parameters.get(*edge).map(|p| p.type_id).or_else(|| {
edge.checked_sub(s.parameters.len()).and_then(|e| s.results.get(e)).copied()
}),
_ => None,
};
*edge += 1;
if let Some(id) = next {
let id = id.0 as usize;
if colors[id] == 1 {
b.work(walk.len())?;
let reason =
if walk.iter().any(|(n, _)| matches!(d.types[*n].kind, TypeKind::Fn(_))) {
R::StructuralTypeCycle
} else {
R::ArrayCycle
};
return Err(E::new(C::InvalidRegistry, reason).in_section(6).record(id as u32));
}
if colors[id] == 0 {
colors[id] = 1;
walk.push((id, 0));
}
} else {
colors[*node] = 2;
walk.pop();
}
}
}
b.refund(Q::TemporaryBytes, colors.capacity() as u64);
b.refund(Q::TemporaryBytes, (walk.capacity() * size_of::<(usize, usize)>()) as u64);
drop(colors);
drop(walk);
for (i, f) in d.functions.iter().enumerate() {
b.work(1)?;
name(&f.name, b).map_err(|e| e.in_section(1).record(i as u32))?;
signature(&f.signature, d, b).map_err(|e| e.in_section(1).record(i as u32))?;
b.charge(Q::NestedRecords, f.captures.len() as u64)?;
for (j, &id) in f.captures.iter().enumerate() {
b.work(1)?;
type_ref(id, d).map_err(|e| e.in_section(8).record(i as u32).member(j as u32))?;
}
}
for (i, imp) in d.implementations.iter().enumerate() {
b.work(1)?;
type_ref(imp.owner, d).map_err(|e| e.in_section(7).record(i as u32))?;
type_ref(imp.trait_id, d).map_err(|e| e.in_section(7).record(i as u32))?;
b.charge(Q::NestedRecords, imp.methods.len() as u64)?;
for (j, id) in imp.methods.iter().enumerate() {
b.work(1)?;
if id.0 as usize >= d.functions.len() {
return Err(E::new(C::InvalidReference, R::FunctionId)
.in_section(7)
.reference(IdDomain::Function, id.0)
.record(i as u32)
.member(j as u32));
}
}
}
Ok(())
}
fn charge_vec<T>(v: &Vec<T>, b: &mut LoadBudget) -> Result<(), E> {
b.charge(
Q::RegistryBytes,
(v.capacity() as u64).checked_mul(size_of::<T>() as u64).ok_or_else(overflow)?,
)
}
fn charge_name(n: &Option<String>, b: &mut LoadBudget) -> Result<(), E> {
if let Some(n) = n {
b.charge(Q::RegistryBytes, n.capacity() as u64)?;
}
Ok(())
}
fn charge_named(v: &Vec<NamedType>, b: &mut LoadBudget) -> Result<(), E> {
charge_vec(v, b)?;
for p in v {
b.work(1)?;
charge_name(&p.name, b)?;
}
Ok(())
}
fn charge_signature(s: &Signature, b: &mut LoadBudget) -> Result<(), E> {
charge_named(&s.parameters, b)?;
charge_vec(&s.results, b)
}
fn charge_declarations(d: &RegistryDeclarations, b: &mut LoadBudget) -> Result<(), E> {
b.charge(Q::RegistryBytes, size_of::<Registry>() as u64)?;
charge_vec(&d.types, b)?;
charge_vec(&d.functions, b)?;
charge_vec(&d.implementations, b)?;
for t in &d.types {
b.work(1)?;
charge_name(&t.name, b)?;
match &t.kind {
TypeKind::Struct(fields) => charge_named(fields, b)?,
TypeKind::Fn(s) => charge_signature(s, b)?,
TypeKind::Trait(methods) => {
charge_vec(methods, b)?;
for m in methods {
b.work(1)?;
charge_name(&m.name, b)?;
charge_signature(&m.signature, b)?;
}
}
_ => {}
}
}
for f in &d.functions {
b.work(1)?;
charge_name(&f.name, b)?;
charge_signature(&f.signature, b)?;
charge_vec(&f.captures, b)?;
}
for imp in &d.implementations {
b.work(1)?;
charge_vec(&imp.methods, b)?;
}
Ok(())
}
@@ -0,0 +1,515 @@
//! Strict PBX 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,180 @@
//! Registry-aware immediate validation and slot effects for typed instructions.
use crate::decoder::DecodedInstr;
use crate::isa::core::{CoreOpCode as Op, CoreOpCodeSpecExt};
use crate::load_limits::{IdDomain, LoadCode, LoadFailure, LoadReason};
use crate::registry::{FunctionId, Registry, TypeId, TypeKind};
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct RegistryStackEffect {
pub pops: u32,
pub pushes: u32,
}
impl DecodedInstr<'_> {
/// Capture effects require the enclosing function's resolved environment.
pub fn registry_stack_effect_in(
&self,
registry: &Registry,
function: FunctionId,
) -> Result<Option<RegistryStackEffect>, LoadFailure> {
if self.opcode == Op::GetCapture {
let index = self
.imm_u32()
.map_err(|_| LoadFailure::new(LoadCode::InvalidCode, LoadReason::Truncated))?;
let capture = registry
.function_layout(function)
.and_then(|f| f.captures.get(index as usize))
.ok_or_else(|| {
LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex)
.member(index)
})?;
return Ok(Some(RegistryStackEffect { pops: 0, pushes: capture.slots }));
}
self.registry_stack_effect(registry)
}
/// Resolve an instruction's exact group widths and check immediate domains.
/// None means this is not a Registry instruction, not a zero stack effect.
/// This does not prove that the values on the stack satisfy the signature.
pub fn registry_stack_effect(
&self,
registry: &Registry,
) -> Result<Option<RegistryStackEffect>, LoadFailure> {
if !self.opcode.requires_registry() {
return Ok(None);
}
let malformed = || {
let mut e = LoadFailure::new(LoadCode::InvalidCode, LoadReason::Truncated);
e.pc = u32::try_from(self.pc).ok();
e
};
let type_info = |id: u32| {
let decl = registry.declarations().types.get(id as usize);
let layout = registry.type_layout(TypeId(id));
decl.zip(layout).ok_or_else(|| {
let mut e = LoadFailure::new(LoadCode::InvalidReference, LoadReason::TypeId)
.reference(IdDomain::Type, id);
e.pc = u32::try_from(self.pc).ok();
e
})
};
let bad_category = |id: u32| {
let mut e = LoadFailure::new(LoadCode::InvalidReference, LoadReason::Category)
.reference(IdDomain::Type, id);
e.pc = u32::try_from(self.pc).ok();
e
};
let (pops, pushes) = match self.opcode {
Op::MakeClosure => {
let (function, ty) = self.imm_u32x2().map_err(|_| malformed())?;
let (_, layout) = type_info(ty)?;
if layout.callable.is_none() {
return Err(bad_category(ty));
}
let target = registry.function_layout(FunctionId(function)).ok_or_else(|| {
LoadFailure::new(LoadCode::InvalidReference, LoadReason::FunctionId)
.reference(IdDomain::Function, function)
})?;
(target.capture_slots, 1)
}
Op::CallClosure => {
let ty = self.imm_u32().map_err(|_| malformed())?;
let (_, layout) = type_info(ty)?;
let signature = layout.callable.as_ref().ok_or_else(|| bad_category(ty))?;
(
signature.parameter_slots.checked_add(1).ok_or_else(malformed)?,
signature.result_slots,
)
}
Op::GetCapture => {
return Err(LoadFailure::new(LoadCode::InvalidReference, LoadReason::CaptureIndex))
}
Op::CallTrait => {
let (ty, method) = self.imm_u32x2().map_err(|_| malformed())?;
let (_, layout) = type_info(ty)?;
let signature = layout
.methods
.get(method as usize)
.ok_or_else(|| bad_category(ty).member(method))?;
(
signature.parameter_slots.checked_add(2).ok_or_else(malformed)?,
signature.result_slots,
)
}
Op::DynPack | Op::DynUnpack | Op::DynCanUnpack => {
let id = self.imm_u32().map_err(|_| malformed())?;
let (_, layout) = type_info(id)?;
match self.opcode {
Op::DynPack => (layout.storage.slots, 2),
Op::DynUnpack => (2, layout.storage.slots),
_ => (2, 1),
}
}
Op::RefIsExact | Op::RefImplements | Op::RefToTrait | Op::RefCast => {
let (source, target) = self.imm_u32x2().map_err(|_| malformed())?;
let (source_decl, source_layout) = type_info(source)?;
let (target_decl, target_layout) = type_info(target)?;
if !matches!(
source_decl.kind,
TypeKind::Struct(_) | TypeKind::Array(_) | TypeKind::Trait(_)
) {
return Err(bad_category(source));
}
let trait_target = matches!(self.opcode, Op::RefImplements | Op::RefToTrait);
if (trait_target && !matches!(target_decl.kind, TypeKind::Trait(_)))
|| (!trait_target
&& !matches!(target_decl.kind, TypeKind::Struct(_) | TypeKind::Array(_)))
{
return Err(bad_category(target));
}
let pushes = if matches!(self.opcode, Op::RefIsExact | Op::RefImplements) {
1
} else {
target_layout.storage.slots
};
(source_layout.storage.slots, pushes)
}
Op::StructNew
| Op::StructGet
| Op::StructSet
| Op::ArrayNew
| Op::ArrayLen
| Op::ArrayGet
| Op::ArraySet => {
let (id, field) = if matches!(self.opcode, Op::StructGet | Op::StructSet) {
self.imm_u32x2().map_err(|_| malformed())?
} else {
(self.imm_u32().map_err(|_| malformed())?, 0)
};
let (_, layout) = type_info(id)?;
if matches!(self.opcode, Op::StructNew | Op::StructGet | Op::StructSet) {
let instance = layout.instance.as_ref().ok_or_else(|| bad_category(id))?;
match self.opcode {
Op::StructNew => (0, 1),
op => {
let f = instance
.fields
.get(field as usize)
.ok_or_else(|| bad_category(id).member(field))?;
let w = registry.type_layout(f.type_id).unwrap().storage.slots;
if op == Op::StructGet {
(1, w)
} else {
(1 + w, 0)
}
}
}
} else {
let array = layout.array.as_ref().ok_or_else(|| bad_category(id))?;
let w = registry.type_layout(array.element_type_id).unwrap().storage.slots;
match self.opcode {
Op::ArrayNew | Op::ArrayLen => (1, 1),
Op::ArrayGet => (2, w),
_ => (2 + w, 0),
}
}
}
_ => unreachable!("requires_registry is defined by the typed opcode catalogue"),
};
Ok(Some(RegistryStackEffect { pops, pushes }))
}
}
@@ -0,0 +1,40 @@
//! Resource fault context shared by the VM, native boundary and host tooling.
//! Accounting and product ceilings remain owned by the runtime budget.
use serde::{Deserialize, Serialize};
use std::fmt;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[repr(usize)]
pub enum RuntimeResource {
GuestBytes,
HandleSlots,
AuxiliaryBytes,
TemporaryBytes,
StringBytes,
StringAllocations,
IndividualStringBytes,
CallDepth,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum ResourceReason {
Limit,
SizeOverflow,
AllocationFailed,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct ResourceFailure {
pub resource: RuntimeResource,
pub reason: ResourceReason,
pub requested: u64,
pub limit: u64,
}
impl fmt::Display for ResourceFailure {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(
f,
"{:?}: {:?}, requested {}, limit {}",
self.resource, self.reason, self.requested, self.limit
)
}
}
impl std::error::Error for ResourceFailure {}
+32 -26
View File
@@ -1,7 +1,6 @@
use serde::{Deserialize, Serialize};
use std::cell::Cell;
use std::cmp::Ordering;
use std::fmt::Write;
use std::sync::Arc;
thread_local! {
@@ -10,17 +9,28 @@ thread_local! {
/// Opaque handle that references an object stored in the VM heap.
///
/// This is an index-based handle. It does not imply ownership and carries
/// no lifetime information. GC/allocator integration will come in later PRs.
/// Handles belong to the heap/session that issued them. Native boundaries must
/// preserve that provenance. Generation zero is reserved; compact null is (0, 0).
#[repr(C, align(8))]
#[derive(Debug, Copy, Clone, Eq, PartialEq, Hash, Serialize, Deserialize)]
pub struct HeapRef(pub u32);
pub struct HeapRef {
pub index: u32,
pub generation: u32,
}
impl HeapRef {
pub const NULL: Self = Self { index: 0, generation: 0 };
pub const fn is_null(self) -> bool {
self.index == 0 && self.generation == 0
}
}
/// Represents any piece of data that can be stored on the VM stack or in globals.
///
/// The PVM is "dynamically typed" at the bytecode level, meaning a single
/// `Value` enum can hold different primitive types. The VM performs
/// automatic type promotion (e.g., adding an Int32 to a Float64 results
/// in a Float64) to ensure mathematical correctness.
/// This enum is a physical carrier, not a semantic type declaration. Registry
/// boundaries validate exact types and complete multi-slot groups. Arithmetic
/// instructions may have their own numeric promotion rules; those rules do not
/// authorize implicit conversions at typed storage or call boundaries.
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(untagged)]
pub enum Value {
@@ -108,24 +118,20 @@ impl Value {
}
pub fn append_to_string(&self, out: &mut String) {
self.write_text(out).expect("writing into String is infallible");
}
/// Writes existing Value text without allocating a String, so bounded
/// callers can measure and reserve with their own fmt::Write sink.
pub fn write_text(&self, out: &mut impl std::fmt::Write) -> std::fmt::Result {
match self {
Value::Int32(i) => {
let _ = write!(out, "{}", i);
}
Value::Int64(i) => {
let _ = write!(out, "{}", i);
}
Value::Float(f) => {
let _ = write!(out, "{}", f);
}
Value::Boolean(b) => {
let _ = write!(out, "{}", b);
}
Value::String(s) => out.push_str(s),
Value::HeapRef(r) => {
let _ = write!(out, "[HeapRef {}]", r.0);
}
Value::Null => out.push_str("null"),
Value::Int32(i) => write!(out, "{}", i),
Value::Int64(i) => write!(out, "{}", i),
Value::Float(f) => write!(out, "{}", f),
Value::Boolean(b) => write!(out, "{}", b),
Value::String(s) => out.write_str(s),
Value::HeapRef(r) => write!(out, "[HeapRef {}:{}]", r.index, r.generation),
Value::Null => out.write_str("null"),
}
}
@@ -138,7 +144,7 @@ impl Value {
Value::Int32(i) => i.to_string().len(),
Value::Int64(i) => i.to_string().len(),
Value::Float(f) => f.to_string().len(),
Value::HeapRef(r) => 11 + r.0.to_string().len(),
Value::HeapRef(r) => 11 + r.index.to_string().len() + r.generation.to_string().len(),
}
}
@@ -9,7 +9,7 @@ fn emit(op: CoreOpCode, imm: Option<&[u8]>, out: &mut Vec<u8>) {
}
#[test]
fn roundtrip_disasm_assemble_byte_equal_with_closures_and_coroutines() {
fn roundtrip_disasm_assemble_byte_equal_with_typed_callables() {
// Program: PUSH_I32 7; MAKE_CLOSURE fn=1,captures=0; CALL_CLOSURE argc=1;
// SPAWN fn=2,argc=1; YIELD; SLEEP 3; HOSTCALL 2; SYSCALL 0x1003; FRAME_SYNC; HALT
let mut prog = Vec::new();
@@ -22,15 +22,9 @@ fn roundtrip_disasm_assemble_byte_equal_with_closures_and_coroutines() {
emit(CoreOpCode::MakeClosure, Some(&mc), &mut prog);
// CALL_CLOSURE argc=1
emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog);
// SPAWN (fn=2, argc=1)
let mut sp = [0u8; 8];
sp[0..4].copy_from_slice(&2u32.to_le_bytes());
sp[4..8].copy_from_slice(&1u32.to_le_bytes());
emit(CoreOpCode::Spawn, Some(&sp), &mut prog);
// YIELD
emit(CoreOpCode::Yield, None, &mut prog);
// SLEEP 3
emit(CoreOpCode::Sleep, Some(&3u32.to_le_bytes()), &mut prog);
emit(CoreOpCode::GetCapture, Some(&0u32.to_le_bytes()), &mut prog);
let trait_call = [7u32.to_le_bytes(), 0u32.to_le_bytes()].concat();
emit(CoreOpCode::CallTrait, Some(&trait_call), &mut prog);
// HOSTCALL sysc[2]
emit(CoreOpCode::Hostcall, Some(&2u32.to_le_bytes()), &mut prog);
// SYSCALL gfx2d.draw_line (0x1003)
@@ -17,7 +17,7 @@ fn snapshot_representative_program_is_stable() {
mc[0..4].copy_from_slice(&1u32.to_le_bytes());
mc[4..8].copy_from_slice(&0u32.to_le_bytes());
emit(CoreOpCode::MakeClosure, Some(&mc), &mut prog);
// CALL_CLOSURE argc=1
// CALL_CLOSURE 1
emit(CoreOpCode::CallClosure, Some(&1u32.to_le_bytes()), &mut prog);
// SPAWN (fn=2, argc=1)
let mut sp = [0u8; 8];
@@ -38,6 +38,6 @@ fn snapshot_representative_program_is_stable() {
emit(CoreOpCode::Halt, None, &mut prog);
let text = disassemble(&prog).expect("disasm ok");
let expected = "PUSH_I32 7\nMAKE_CLOSURE fn=1, captures=0\nCALL_CLOSURE argc=1\nSPAWN fn=2, argc=1\nYIELD\nSLEEP 3\nHOSTCALL 2\nSYSCALL 0x1003\nFRAME_SYNC\nHALT";
let expected = "PUSH_I32 7\nMAKE_CLOSURE fn=1, type=0\nCALL_CLOSURE 1\nSPAWN fn=2, argc=1\nYIELD\nSLEEP 3\nHOSTCALL 2\nSYSCALL 0x1003\nFRAME_SYNC\nHALT";
assert_eq!(text, expected);
}
@@ -0,0 +1,206 @@
use prometeu_bytecode::isa::core::{CoreOpCode as Op, CoreOpCodeSpecExt};
use prometeu_bytecode::load_limits::{LoadBudget, LoadCode, LoadLimits, LoadReason};
use prometeu_bytecode::registry::*;
use prometeu_bytecode::{assemble, decode_next, disassemble, DecodeError, RegistryStackEffect};
fn registry() -> Registry {
let types = vec![
TypeKind::Builtin(BuiltinId::INT32),
TypeKind::Builtin(BuiltinId::VEC2),
TypeKind::Builtin(BuiltinId::PIXEL),
TypeKind::Builtin(BuiltinId::DYNAMIC),
TypeKind::Struct(vec![]),
TypeKind::Array(TypeId(0)),
TypeKind::Trait(vec![]),
]
.into_iter()
.map(|kind| TypeDecl { name: None, kind })
.collect();
Registry::resolve(
RegistryDeclarations { types, ..Default::default() },
0,
&mut LoadBudget::new(LoadLimits::default()),
)
.unwrap()
}
#[test]
fn all_typed_instructions_match_independent_bytes_and_costs() {
let cases: &[(&str, &[u8], u64)] = &[
("DYN_PACK 16909060", &[0x90, 0, 4, 3, 2, 1], 8),
("DYN_UNPACK 16909060", &[0x91, 0, 4, 3, 2, 1], 4),
("DYN_CAN_UNPACK 16909060", &[0x92, 0, 4, 3, 2, 1], 3),
("REF_IS_EXACT source=16909060, target=84281096", &[0x93, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
("REF_IMPLEMENTS source=16909060, target=84281096", &[0x94, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
("REF_TO_TRAIT source=16909060, target=84281096", &[0x95, 0, 4, 3, 2, 1, 8, 7, 6, 5], 5),
("REF_CAST source=16909060, target=84281096", &[0x96, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
];
for &(text, bytes, cycles) in cases {
assert_eq!(assemble(text).unwrap(), bytes);
assert_eq!(disassemble(bytes).unwrap(), text);
let decoded = decode_next(0, bytes).unwrap();
assert_eq!(decoded.next_pc, bytes.len());
assert_eq!(decoded.opcode.cycles(), cycles);
assert_eq!(decoded.opcode.spec().pops, None);
assert_eq!(decoded.opcode.spec().pushes, None);
assert!(decoded.opcode.requires_registry());
for n in 0..bytes.len() {
assert!(decode_next(0, &bytes[..n]).is_err(), "{text}, prefix {n}");
}
}
assert!(matches!(
decode_next(0, &[0x97, 0]),
Err(DecodeError::UnknownOpcode { opcode: 0x97, .. })
));
}
#[test]
fn slot_effects_resolve_semantic_widths_and_reference_categories() {
let registry = registry();
for (text, pops, pushes) in [
("DYN_PACK 0", 1, 2),
("DYN_PACK 1", 2, 2),
("DYN_PACK 2", 3, 2),
("DYN_PACK 3", 2, 2),
("DYN_UNPACK 2", 2, 3),
("DYN_CAN_UNPACK 2", 2, 1),
("REF_IS_EXACT source=6, target=4", 2, 1),
("REF_IMPLEMENTS source=5, target=6", 1, 1),
("REF_TO_TRAIT source=4, target=6", 1, 2),
("REF_TO_TRAIT source=6, target=6", 2, 2),
("REF_CAST source=6, target=4", 2, 1),
] {
let bytes = assemble(text).unwrap();
assert_eq!(
decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap(),
Some(RegistryStackEffect { pops, pushes }),
"{text}"
);
}
assert_eq!(decode_next(0, &[0, 0]).unwrap().registry_stack_effect(&registry).unwrap(), None);
}
#[test]
fn invalid_type_immediates_are_contextual_load_errors() {
let registry = registry();
for text in ["DYN_PACK 7", "DYN_UNPACK 4294967295", "REF_CAST source=7, target=4"] {
let bytes = assemble(text).unwrap();
let e = decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap_err();
assert_eq!(
(e.code, e.reason, e.pc),
(LoadCode::InvalidReference, LoadReason::TypeId, Some(0))
);
}
for text in [
"REF_CAST source=3, target=4",
"REF_IS_EXACT source=4, target=6",
"REF_TO_TRAIT source=4, target=0",
"REF_IMPLEMENTS source=0, target=6",
] {
let bytes = assemble(text).unwrap();
let e = decode_next(0, &bytes).unwrap().registry_stack_effect(&registry).unwrap_err();
assert_eq!(
(e.code, e.reason),
(LoadCode::InvalidReference, LoadReason::Category),
"{text}"
);
}
}
#[test]
fn assembler_rejects_missing_overflowing_or_ambiguous_type_ids() {
for text in [
"DYN_PACK",
"DYN_PACK -1",
"DYN_PACK 4294967296",
"DYN_PACK 1 2",
"REF_CAST source=4",
"REF_CAST source=4, target=5, target=6",
"REF_CAST source=4, trait=6",
] {
assert!(assemble(text).is_err(), "{text}");
}
}
#[test]
fn decoder_extreme_pc_does_not_overflow() {
assert!(matches!(
decode_next(usize::MAX, &[]),
Err(DecodeError::TruncatedOpcode { pc: usize::MAX })
));
assert_eq!(Op::DynPack as u16, 0x0090);
}
#[test]
fn collection_literal_encodings_roundtrip_and_reject_every_truncation() {
for (text, bytes, base) in [
("STRUCT_NEW 16909060", vec![0xa0, 0, 4, 3, 2, 1], 8),
("STRUCT_GET type=16909060, field=84281096", vec![0xa1, 0, 4, 3, 2, 1, 8, 7, 6, 5], 3),
("STRUCT_SET type=16909060, field=84281096", vec![0xa2, 0, 4, 3, 2, 1, 8, 7, 6, 5], 4),
("ARRAY_NEW 16909060", vec![0xa3, 0, 4, 3, 2, 1], 8),
("ARRAY_LEN 16909060", vec![0xa4, 0, 4, 3, 2, 1], 3),
("ARRAY_GET 16909060", vec![0xa5, 0, 4, 3, 2, 1], 3),
("ARRAY_SET 16909060", vec![0xa6, 0, 4, 3, 2, 1], 4),
] {
assert_eq!(assemble(text).unwrap(), bytes);
assert_eq!(disassemble(&bytes).unwrap(), text);
let op = decode_next(0, &bytes).unwrap().opcode;
assert_eq!(op.cycles(), base);
assert!(op.requires_registry() && op.spec().may_trap);
assert!(!op.spec().is_safepoint && !op.spec().is_branch && !op.spec().is_terminator);
for n in 0..bytes.len() {
assert!(decode_next(0, &bytes[..n]).is_err());
}
}
for bad in [
"STRUCT_NEW",
"ARRAY_NEW -1",
"ARRAY_GET 4294967296",
"ARRAY_LEN 1 2",
"STRUCT_GET type=1",
"STRUCT_SET type=1, field=2, field=3",
"STRUCT_GET type=1, field=-1",
] {
assert!(assemble(bad).is_err(), "{bad}");
}
}
#[test]
fn collection_effects_and_cached_initialization_width_are_exact() {
let d = RegistryDeclarations {
types: vec![
TypeDecl { name: None, kind: TypeKind::Builtin(BuiltinId::PIXEL) },
TypeDecl {
name: None,
kind: TypeKind::Struct(vec![
NamedType { type_id: TypeId(0), name: None },
NamedType { type_id: TypeId(1), name: None },
]),
},
TypeDecl { name: None, kind: TypeKind::Array(TypeId(0)) },
],
..Default::default()
};
let r = Registry::resolve(d, 0, &mut LoadBudget::new(Default::default())).unwrap();
assert_eq!(
r.type_layout(TypeId(1)).unwrap().instance.as_ref().unwrap().initialization_slots,
4
);
for (s, pops, pushes) in [
("STRUCT_NEW 1", 0, 1),
("STRUCT_GET type=1, field=0", 1, 3),
("STRUCT_SET type=1, field=0", 4, 0),
("ARRAY_NEW 2", 1, 1),
("ARRAY_LEN 2", 1, 1),
("ARRAY_GET 2", 2, 3),
("ARRAY_SET 2", 5, 0),
] {
let code = assemble(s).unwrap();
assert_eq!(
decode_next(0, &code).unwrap().registry_stack_effect(&r).unwrap(),
Some(RegistryStackEffect { pops, pushes })
);
}
for s in ["STRUCT_NEW 0", "ARRAY_NEW 1", "STRUCT_GET type=1, field=2", "ARRAY_GET 99"] {
let code = assemble(s).unwrap();
assert_eq!(
decode_next(0, &code).unwrap().registry_stack_effect(&r).unwrap_err().code,
LoadCode::InvalidReference
);
}
}
File diff suppressed because it is too large Load Diff
+101 -235
View File
@@ -1,4 +1,6 @@
#![allow(clippy::collapsible_if)]
mod decode;
mod resumable;
use crate::memory_banks::{GlyphBankPoolInstaller, SceneBankPoolInstaller, SoundBankPoolInstaller};
use prometeu_hal::AssetBridge;
use prometeu_hal::asset::{
@@ -340,6 +342,8 @@ pub struct AssetManager {
// Commits that are ready to be applied at the next frame boundary.
pending_commits: Mutex<Vec<(HandleId, u64)>>,
preload_handles: Mutex<Vec<HandleId>>,
preload_failed: std::sync::atomic::AtomicBool,
}
struct LoadHandleInfo {
@@ -374,6 +378,7 @@ struct AssetLoadQueueState {
pending: VecDeque<AssetLoadJob>,
active: Option<AssetLoadJob>,
shutdown: bool,
scheduled: bool,
}
#[derive(Default)]
@@ -470,6 +475,7 @@ impl AssetLoadQueue {
struct AssetLoadWorker {
queue: Arc<AssetLoadQueue>,
join_handle: Option<thread::JoinHandle<()>>,
shared: Option<(Arc<dyn prometeu_hal::background_work::BackgroundWork>, resumable::Resources)>,
}
impl AssetLoadWorker {
@@ -500,11 +506,15 @@ impl AssetLoadWorker {
}
});
Self { queue, join_handle: Some(join_handle) }
Self { queue, join_handle: Some(join_handle), shared: None }
}
fn submit_counting_superseded(&self, job: AssetLoadJob) -> usize {
self.queue.submit(job)
let removed = self.queue.submit(job);
if let Some((lane, resources)) = &self.shared {
resumable::schedule(self.queue.clone(), lane.clone(), resources.clone());
}
removed
}
fn clear_pending(&self) {
@@ -544,6 +554,25 @@ enum AssetOpMode {
}
impl AssetBridge for AssetManager {
fn bind_background_work(
&mut self,
lane: Arc<dyn prometeu_hal::background_work::BackgroundWork>,
) -> bool {
if self.load_worker.shared.as_ref().is_some_and(|(bound, _)| Arc::ptr_eq(bound, &lane)) {
return true;
}
// Bind only before loading: replacing an active worker could block the main lane.
if self.load_worker.pending_count() != 0 || self.load_worker.active_job().is_some() {
return false;
}
let resources = resumable::Resources::new(self);
self.load_worker = AssetLoadWorker {
queue: Arc::new(AssetLoadQueue::default()),
join_handle: None,
shared: Some((lane, resources)),
};
true
}
fn initialize_for_cartridge(
&self,
assets: Vec<AssetEntry>,
@@ -552,6 +581,12 @@ impl AssetBridge for AssetManager {
) {
self.initialize_for_cartridge(assets, preload, assets_data)
}
fn preloads_ready(&self) -> Result<bool, AssetLoadError> {
if self.preload_failed.load(std::sync::atomic::Ordering::Acquire) {
return Err(AssetLoadError::BackendError);
}
Ok(self.preload_handles.lock().unwrap().is_empty())
}
fn load(&self, asset_id: AssetId, slot_index: usize) -> Result<HandleId, AssetLoadError> {
self.load(asset_id, slot_index)
}
@@ -600,62 +635,13 @@ impl AssetManager {
fn decode_glyph_bank_layout(
entry: &AssetEntry,
) -> Result<(TileSize, usize, usize, usize, usize, usize), String> {
let meta = entry.metadata_as_glyph_bank()?;
let tile_size = match meta.tile_size {
8 => TileSize::Size8,
16 => TileSize::Size16,
32 => TileSize::Size32,
_ => return Err(format!("Invalid tile_size: {}", meta.tile_size)),
};
let palette_count = meta.palette_count as usize;
if !(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count) {
return Err(format!("Invalid palette_count: {}", meta.palette_count));
}
let width = meta.width as usize;
let height = meta.height as usize;
let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?;
let serialized_pixel_bytes = logical_pixels.div_ceil(2);
let palette_bytes = palette_count
.checked_mul(GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
.ok_or("GlyphBank palette size overflow")?;
let serialized_size = serialized_pixel_bytes
.checked_add(palette_bytes)
.ok_or("GlyphBank serialized size overflow")?;
let decoded_size =
logical_pixels.checked_add(palette_bytes).ok_or("GlyphBank decoded size overflow")?;
if entry.size != serialized_size as u64 {
return Err(format!(
"Invalid GLYPHBANK serialized size: expected {}, got {}",
serialized_size, entry.size
));
}
if entry.decoded_size != decoded_size as u64 {
return Err(format!(
"Invalid GLYPHBANK decoded_size: expected {}, got {}",
decoded_size, entry.decoded_size
));
}
Ok((tile_size, width, height, serialized_pixel_bytes, palette_count, palette_bytes))
decode::glyph_layout(entry)
}
fn unpack_glyph_bank_pixels(packed_pixels: &[u8], logical_pixels: usize) -> Vec<u8> {
let mut pixel_indices = Vec::with_capacity(logical_pixels);
for &packed in packed_pixels {
if pixel_indices.len() < logical_pixels {
pixel_indices.push(packed >> 4);
}
if pixel_indices.len() < logical_pixels {
pixel_indices.push(packed & 0x0f);
}
}
pixel_indices
let mut pixels = Vec::with_capacity(logical_pixels);
decode::append_pixels(&mut pixels, packed_pixels, logical_pixels);
pixels
}
fn op_mode_for(entry: &AssetEntry) -> Result<AssetOpMode, String> {
@@ -715,6 +701,8 @@ impl AssetManager {
pipeline_telemetry,
load_worker,
pending_commits: Mutex::new(Vec::new()),
preload_handles: Mutex::new(Vec::new()),
preload_failed: std::sync::atomic::AtomicBool::new(false),
}
}
@@ -734,7 +722,16 @@ impl AssetManager {
}
*self.assets_data.write().unwrap() = assets_data;
// Perform Preload for assets in the preload list
if self.load_worker.shared.is_some() {
for item in preload {
match self.load(item.asset_id, item.slot) {
Ok(handle) => self.preload_handles.lock().unwrap().push(handle),
Err(_) => self.preload_failed.store(true, std::sync::atomic::Ordering::SeqCst),
}
}
return;
}
// Standalone bridges retain their synchronous preload compatibility path.
for item in preload {
let entry_opt = {
let assets = self.assets.read().unwrap();
@@ -1215,17 +1212,7 @@ impl AssetManager {
let palette_data = &buffer[packed_pixel_bytes..packed_pixel_bytes + palette_bytes];
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
for (p, pal) in palettes.iter_mut().enumerate() {
for (c, slot) in pal.iter_mut().enumerate() {
let offset = (p * 16 + c) * 4;
*slot = Color::rgba(
palette_data[offset],
palette_data[offset + 1],
palette_data[offset + 2],
palette_data[offset + 3],
);
}
}
decode::write_palettes(&mut palettes, 0, palette_data);
Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes })
}
@@ -1250,17 +1237,7 @@ impl AssetManager {
.map_err(|_| "Buffer too small for GLYPHBANK".to_string())?;
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
for (p, pal) in palettes.iter_mut().enumerate() {
for (c, slot) in pal.iter_mut().enumerate() {
let offset = (p * 16 + c) * 4;
*slot = Color::rgba(
palette_data[offset],
palette_data[offset + 1],
palette_data[offset + 2],
palette_data[offset + 3],
);
}
}
decode::write_palettes(&mut palettes, 0, &palette_data);
Ok(GlyphBank { tile_size, width, height, pixel_indices, palettes })
}
@@ -1295,7 +1272,7 @@ impl AssetManager {
entry: &AssetEntry,
assets_data: Arc<RwLock<AssetsPayloadSource>>,
) -> Result<SceneBank, String> {
let _ = entry.metadata_as_scene_bank()?;
decode::scene_metadata(entry)?;
let op_mode = Self::op_mode_for(entry)?;
let slice = {
let assets_data = assets_data.read().unwrap();
@@ -1322,152 +1299,25 @@ impl AssetManager {
entry: &AssetEntry,
buffer: &[u8],
) -> Result<SceneBank, String> {
let _ = entry.metadata_as_scene_bank()?;
if buffer.len() < SCENE_HEADER_BYTES_V1 {
return Err("Buffer too small for SCENE".to_string());
}
if buffer[0..4] != SCENE_PAYLOAD_MAGIC_V1 {
return Err("Invalid SCENE magic".to_string());
}
let version = u16::from_le_bytes([buffer[4], buffer[5]]);
if version != SCENE_PAYLOAD_VERSION_V1 {
return Err(format!("Unsupported SCENE version: {}", version));
}
let layer_count = u16::from_le_bytes([buffer[6], buffer[7]]) as usize;
if layer_count != SCENE_LAYER_COUNT_V1 {
return Err(format!("Invalid SCENE layer count: {}", layer_count));
}
decode::scene_metadata(entry)?;
decode::payload_size(entry, buffer.len())?;
decode::scene_header(buffer)?;
let mut offset = SCENE_HEADER_BYTES_V1;
let mut decoded_size = 0_usize;
let layers = std::array::from_fn(|_| SceneLayer {
active: false,
glyph_asset_id: 0,
tile_size: TileSize::Size8,
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap { width: 0, height: 0, tiles: Vec::new() },
});
let mut layers = layers;
let mut decoded = 0;
let mut layers = decode::empty_layers();
for layer in &mut layers {
let header_end = offset
let end = offset
.checked_add(SCENE_LAYER_HEADER_BYTES_V1)
.ok_or("SCENE layer header offset overflow")?;
if header_end > buffer.len() {
return Err("Buffer too small for SCENE layer header".to_string());
}
let flags = buffer[offset];
let glyph_asset_id = i32::from_le_bytes([
buffer[offset + 1],
buffer[offset + 2],
buffer[offset + 3],
buffer[offset + 4],
]);
let tile_size_raw = buffer[offset + 5];
let tile_size = match tile_size_raw {
8 => TileSize::Size8,
16 => TileSize::Size16,
32 => TileSize::Size32,
other => return Err(format!("Invalid SCENE tile size: {}", other)),
};
let parallax_factor_x = f32::from_le_bytes([
buffer[offset + 8],
buffer[offset + 9],
buffer[offset + 10],
buffer[offset + 11],
]);
let parallax_factor_y = f32::from_le_bytes([
buffer[offset + 12],
buffer[offset + 13],
buffer[offset + 14],
buffer[offset + 15],
]);
if !parallax_factor_x.is_finite() || !parallax_factor_y.is_finite() {
return Err("Invalid SCENE parallax_factor".to_string());
}
let width = u32::from_le_bytes([
buffer[offset + 16],
buffer[offset + 17],
buffer[offset + 18],
buffer[offset + 19],
]) as usize;
let height = u32::from_le_bytes([
buffer[offset + 20],
buffer[offset + 21],
buffer[offset + 22],
buffer[offset + 23],
]) as usize;
let tile_count = u32::from_le_bytes([
buffer[offset + 24],
buffer[offset + 25],
buffer[offset + 26],
buffer[offset + 27],
]) as usize;
let expected_tile_count =
width.checked_mul(height).ok_or("SCENE tile count overflow")?;
if tile_count != expected_tile_count {
return Err(format!(
"Invalid SCENE tile count for layer: expected {}, got {}",
expected_tile_count, tile_count
));
}
offset = header_end;
let tile_bytes = tile_count
.checked_mul(SCENE_TILE_RECORD_BYTES_V1)
.ok_or("SCENE tile payload overflow")?;
let tiles_end = offset.checked_add(tile_bytes).ok_or("SCENE payload overflow")?;
if tiles_end > buffer.len() {
return Err("Buffer too small for SCENE tile data".to_string());
}
let mut tiles = Vec::with_capacity(tile_count);
for _ in 0..tile_count {
let tile_flags = buffer[offset];
let palette_id = buffer[offset + 1];
let glyph_id = u16::from_le_bytes([buffer[offset + 2], buffer[offset + 3]]);
tiles.push(Tile {
active: (tile_flags & 0b0000_0001) != 0,
glyph: Glyph { glyph_id, palette_id },
flip_x: (tile_flags & 0b0000_0010) != 0,
flip_y: (tile_flags & 0b0000_0100) != 0,
});
offset += SCENE_TILE_RECORD_BYTES_V1;
}
decoded_size = decoded_size
.checked_add(SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1)
.and_then(|size| size.checked_add(tile_count * size_of::<Tile>()))
.ok_or("SCENE decoded_size overflow")?;
*layer = SceneLayer {
active: (flags & 0b0000_0001) != 0,
glyph_asset_id,
tile_size,
parallax_factor: ParallaxFactor { x: parallax_factor_x, y: parallax_factor_y },
tilemap: TileMap { width, height, tiles },
};
.ok_or("SCENE header offset overflow")?;
let header =
buffer.get(offset..end).ok_or("Buffer too small for SCENE layer header")?;
*layer = decode::scene_layer(header, end, entry.size, &mut decoded)?;
let tile_bytes =
layer.tilemap.width * layer.tilemap.height * SCENE_TILE_RECORD_BYTES_V1;
offset = end + tile_bytes; // checked by scene_layer before allocation
decode::append_tiles(&mut layer.tilemap.tiles, &buffer[end..offset]);
}
if offset != buffer.len() {
return Err("Trailing bytes in SCENE payload".to_string());
}
if entry.decoded_size != decoded_size as u64 {
return Err(format!(
"Invalid SCENE decoded_size: expected {}, got {}",
decoded_size, entry.decoded_size
));
}
decode::scene_finish(entry, offset, decoded)?;
Ok(SceneBank { layers })
}
@@ -1484,15 +1334,10 @@ impl AssetManager {
entry: &AssetEntry,
buffer: &[u8],
) -> Result<SoundBank, String> {
let meta = entry.metadata_as_sound_bank()?;
let sample_rate = meta.sample_rate;
let sample_rate = decode::sound_rate(entry)?;
decode::payload_size(entry, buffer.len())?;
let mut data = Vec::with_capacity(buffer.len() / 2);
for i in (0..buffer.len()).step_by(2) {
if i + 1 < buffer.len() {
data.push(i16::from_le_bytes([buffer[i], buffer[i + 1]]));
}
}
decode::append_pcm(&mut data, buffer);
let sample = Arc::new(Sample::new(sample_rate, data));
Ok(SoundBank::new(vec![sample]))
@@ -1709,6 +1554,19 @@ impl AssetManager {
}
pub fn apply_commits(&self) {
self.preload_handles.lock().unwrap().retain(|&handle| match self.status(handle) {
LoadStatus::READY => {
self.commit(handle);
false
}
LoadStatus::QUEUED | LoadStatus::LOADING | LoadStatus::PENDING | LoadStatus::ACTIVE => {
true
}
_ => {
self.preload_failed.store(true, std::sync::atomic::Ordering::SeqCst);
false
}
});
let mut pending = self.pending_commits.lock().unwrap();
let mut handles = self.handles.write().unwrap();
@@ -1846,16 +1704,20 @@ impl AssetManager {
}
pub fn shutdown(&self) {
// Exclude worker publication while invalidating and clearing the cartridge.
let mut generations = self.target_generations.write().unwrap();
for generation in generations.values_mut() {
*generation += 1;
}
self.gfx_policy.clear();
self.sound_policy.clear();
self.scene_policy.clear();
self.handles.write().unwrap().clear();
self.target_handles.write().unwrap().clear();
for generation in self.target_generations.write().unwrap().values_mut() {
*generation += 1;
}
self.load_worker.clear_pending();
self.pending_commits.lock().unwrap().clear();
self.preload_handles.lock().unwrap().clear();
self.preload_failed.store(false, std::sync::atomic::Ordering::SeqCst);
self.gfx_slots.write().unwrap().fill(None);
self.glyph_slot_index.clear();
self.sound_slots.write().unwrap().fill(None);
@@ -1936,7 +1798,7 @@ mod tests {
}
}
fn test_scene() -> SceneBank {
pub(super) fn test_scene() -> SceneBank {
let make_layer = |glyph_asset_id: AssetId,
active: bool,
parallax_x: f32,
@@ -1999,7 +1861,7 @@ mod tests {
.sum()
}
fn encode_scene_payload(scene: &SceneBank) -> Vec<u8> {
pub(super) fn encode_scene_payload(scene: &SceneBank) -> Vec<u8> {
let mut data = Vec::new();
data.extend_from_slice(&SCENE_PAYLOAD_MAGIC_V1);
data.extend_from_slice(&SCENE_PAYLOAD_VERSION_V1.to_le_bytes());
@@ -2039,7 +1901,11 @@ mod tests {
data
}
fn test_scene_asset_entry(asset_name: &str, data: &[u8], scene: &SceneBank) -> AssetEntry {
pub(super) fn test_scene_asset_entry(
asset_name: &str,
data: &[u8],
scene: &SceneBank,
) -> AssetEntry {
AssetEntry {
asset_id: 2,
asset_name: asset_name.to_string(),
@@ -0,0 +1,187 @@
//! Format authority shared by complete-buffer and bounded resumable decoding.
use super::*;
pub(super) fn glyph_layout(
entry: &AssetEntry,
) -> Result<(TileSize, usize, usize, usize, usize, usize), String> {
let meta = entry.metadata_as_glyph_bank()?;
let tile_size = match meta.tile_size {
8 => TileSize::Size8,
16 => TileSize::Size16,
32 => TileSize::Size32,
_ => return Err(format!("Invalid tile_size: {}", meta.tile_size)),
};
let palette_count = meta.palette_count as usize;
if !(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count) {
return Err(format!("Invalid palette_count: {}", meta.palette_count));
}
let width = meta.width as usize;
let height = meta.height as usize;
let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?;
let serialized_pixel_bytes = logical_pixels.div_ceil(2);
let palette_bytes = palette_count
.checked_mul(GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
.ok_or("GlyphBank palette size overflow")?;
let serialized_size = serialized_pixel_bytes
.checked_add(palette_bytes)
.ok_or("GlyphBank serialized size overflow")?;
let decoded_size =
logical_pixels.checked_add(palette_bytes).ok_or("GlyphBank decoded size overflow")?;
if entry.size != serialized_size as u64 {
return Err(format!(
"Invalid GLYPHBANK serialized size: expected {}, got {}",
serialized_size, entry.size
));
}
if entry.decoded_size != decoded_size as u64 {
return Err(format!(
"Invalid GLYPHBANK decoded_size: expected {}, got {}",
decoded_size, entry.decoded_size
));
}
Ok((tile_size, width, height, serialized_pixel_bytes, palette_count, palette_bytes))
}
pub(super) fn append_pixels(pixels: &mut Vec<u8>, bytes: &[u8], logical: usize) {
for &packed in bytes {
if pixels.len() < logical {
pixels.push(packed >> 4);
}
if pixels.len() < logical {
pixels.push(packed & 15);
}
}
}
pub(super) fn write_palettes(
palettes: &mut [[Color; GLYPH_BANK_COLORS_PER_PALETTE]],
position: usize,
bytes: &[u8],
) {
for (i, rgba) in bytes.as_chunks::<4>().0.iter().enumerate() {
let at = position / 4 + i;
palettes[at / 16][at % 16] = Color::rgba(rgba[0], rgba[1], rgba[2], rgba[3]);
}
}
pub(super) fn sound_rate(entry: &AssetEntry) -> Result<u32, String> {
Ok(entry.metadata_as_sound_bank()?.sample_rate)
}
// Callers split on even chunk boundaries. Only the final odd byte is ignored.
pub(super) fn append_pcm(data: &mut Vec<i16>, bytes: &[u8]) {
data.extend(bytes.as_chunks::<2>().0.iter().map(|p| i16::from_le_bytes(*p)));
}
pub(super) fn payload_size(entry: &AssetEntry, actual: usize) -> Result<(), String> {
if actual as u64 != entry.size {
return Err("Invalid asset payload size".into());
}
Ok(())
}
pub(super) fn scene_metadata(entry: &AssetEntry) -> Result<(), String> {
entry.metadata_as_scene_bank().map(|_| ())
}
pub(super) fn empty_layers() -> [SceneLayer; SCENE_LAYER_COUNT_V1] {
std::array::from_fn(|_| SceneLayer {
active: false,
glyph_asset_id: 0,
tile_size: TileSize::Size8,
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap { width: 0, height: 0, tiles: Vec::new() },
})
}
pub(super) fn scene_header(bytes: &[u8]) -> Result<(), String> {
if bytes.len() < SCENE_HEADER_BYTES_V1 {
return Err("Buffer too small for SCENE".into());
}
if bytes[..4] != SCENE_PAYLOAD_MAGIC_V1 {
return Err("Invalid SCENE magic".into());
}
let version = u16::from_le_bytes([bytes[4], bytes[5]]);
if version != SCENE_PAYLOAD_VERSION_V1 {
return Err(format!("Unsupported SCENE version: {version}"));
}
let count = u16::from_le_bytes([bytes[6], bytes[7]]) as usize;
if count != SCENE_LAYER_COUNT_V1 {
return Err(format!("Invalid SCENE layer count: {count}"));
}
Ok(())
}
pub(super) fn scene_layer(
bytes: &[u8],
position: usize,
payload_len: u64,
decoded: &mut usize,
) -> Result<SceneLayer, String> {
if bytes.len() < SCENE_LAYER_HEADER_BYTES_V1 {
return Err("Buffer too small for SCENE layer header".into());
}
let u32at = |at| u32::from_le_bytes(bytes[at..at + 4].try_into().unwrap());
let tile_size = match bytes[5] {
8 => TileSize::Size8,
16 => TileSize::Size16,
32 => TileSize::Size32,
other => return Err(format!("Invalid SCENE tile size: {other}")),
};
let x = f32::from_le_bytes(bytes[8..12].try_into().unwrap());
let y = f32::from_le_bytes(bytes[12..16].try_into().unwrap());
if !x.is_finite() || !y.is_finite() {
return Err("Invalid SCENE parallax_factor".into());
}
let width = u32at(16) as usize;
let height = u32at(20) as usize;
let count = u32at(24) as usize;
let expected = width.checked_mul(height).ok_or("SCENE tile count overflow")?;
if count != expected {
return Err(format!(
"Invalid SCENE tile count for layer: expected {expected}, got {count}"
));
}
let end = count
.checked_mul(SCENE_TILE_RECORD_BYTES_V1)
.and_then(|n| position.checked_add(n))
.ok_or("SCENE payload overflow")?;
if end as u64 > payload_len {
return Err("Buffer too small for SCENE tile data".into());
}
*decoded = decoded
.checked_add(SCENE_DECODED_LAYER_OVERHEAD_BYTES_V1)
.and_then(|n| count.checked_mul(size_of::<Tile>()).and_then(|b| n.checked_add(b)))
.ok_or("SCENE decoded_size overflow")?;
Ok(SceneLayer {
active: bytes[0] & 1 != 0,
glyph_asset_id: i32::from_le_bytes(bytes[1..5].try_into().unwrap()),
tile_size,
parallax_factor: ParallaxFactor { x, y },
tilemap: TileMap { width, height, tiles: Vec::with_capacity(count) },
})
}
pub(super) fn append_tiles(tiles: &mut Vec<Tile>, bytes: &[u8]) {
tiles.extend(bytes.as_chunks::<SCENE_TILE_RECORD_BYTES_V1>().0.iter().map(|b| Tile {
active: b[0] & 1 != 0,
glyph: Glyph { glyph_id: u16::from_le_bytes([b[2], b[3]]), palette_id: b[1] },
flip_x: b[0] & 2 != 0,
flip_y: b[0] & 4 != 0,
}));
}
pub(super) fn scene_finish(
entry: &AssetEntry,
position: usize,
decoded: usize,
) -> Result<(), String> {
payload_size(entry, position)?;
if decoded as u64 != entry.decoded_size {
return Err(format!(
"Invalid SCENE decoded_size: expected {decoded}, got {}",
entry.decoded_size
));
}
Ok(())
}
#[cfg(test)]
pub(super) mod tests;
@@ -0,0 +1,432 @@
use super::*;
use serde_json::{Value, json};
struct FileFixture(std::path::PathBuf);
impl FileFixture {
fn new(name: &str, bytes: &[u8]) -> Self {
let path = std::env::temp_dir()
.join(format!("prometeu-conformance-{}-{name}", std::process::id()));
std::fs::write(&path, bytes).unwrap();
Self(path)
}
fn source(&self, declared_len: u64) -> Arc<RwLock<AssetsPayloadSource>> {
Arc::new(RwLock::new(AssetsPayloadSource::from_file(self.0.clone(), 0, declared_len)))
}
}
impl Drop for FileFixture {
fn drop(&mut self) {
std::fs::remove_file(&self.0).unwrap();
}
}
fn pcm_entry(size: u64) -> AssetEntry {
AssetEntry {
asset_id: 1,
asset_name: "pcm".into(),
bank_type: BankType::SOUNDS,
offset: 0,
size,
decoded_size: size,
codec: AssetCodec::None,
metadata: json!({"sample_rate": 44100, "channels": 1}),
}
}
#[test]
fn pcm_chunk_edges_and_odd_tails_have_explicit_baseline_outputs() {
for len in [0, 1, 2, 3, 4095, 4096, 4097, 8191, 8192, 8193] {
let bytes: Vec<u8> = (0..len).map(|i| if i % 2 == 0 { 0x34 } else { 0x12 }).collect();
let entry = pcm_entry(len as u64);
let expected = json!([[vec![0x1234_i16; len / 2], 44100, null, null]]);
let buffer = AssetManager::decode_sound_bank_from_buffer(&entry, &bytes).unwrap();
let reader = AssetManager::decode_sound_bank_from_reader(&entry, &mut &bytes[..]).unwrap();
let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes)));
let production = AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap();
assert_eq!(sound_snapshot(&buffer), expected, "buffer len={len}");
assert_eq!(sound_snapshot(&reader), expected, "reader len={len}");
assert_eq!(sound_snapshot(&production), expected, "legacy load len={len}");
assert_eq!(
resumable::conformance_result(&entry, &source).unwrap(),
expected,
"resumable len={len}"
);
}
}
#[test]
fn physically_truncated_pcm_file_is_rejected_by_both_modes() {
// Two actual bytes, three declared bytes: the missing byte is an odd tail.
// The approved rule rejects missing declared bytes, including an odd tail.
let fixture = FileFixture::new("truncated-pcm", &[0x34, 0x12]);
let entry = pcm_entry(3);
let source = fixture.source(3);
assert!(AssetManager::perform_load_sound_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).is_err());
// With the declared byte physically present, both accept and ignore it.
std::fs::write(&fixture.0, [0x34, 0x12, 0xff]).unwrap();
let expected = json!([[[0x1234], 44100, null, null]]);
assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected);
assert_eq!(
sound_snapshot(&AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap()),
expected
);
// Memory carriers reject the range before either decoder can accept it.
let memory = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(vec![0x34, 0x12])));
assert!(AssetManager::perform_load_sound_bank(&entry, memory.clone()).is_err());
assert!(resumable::conformance_result(&entry, &memory).is_err());
}
#[test]
fn physically_short_scene_file_is_rejected_by_both_modes() {
// Minimal scene: four empty layers, 12-byte header + 4 * 32-byte headers.
let mut bytes = vec![0_u8; 140];
bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]);
for start in [12, 44, 76, 108] {
bytes[start + 5] = 8;
}
let fixture = FileFixture::new("short-scene", &bytes);
let mut entry = AssetEntry {
asset_id: 2,
asset_name: "scene".into(),
bank_type: BankType::SCENE,
offset: 0,
size: 141,
decoded_size: 64,
codec: AssetCodec::None,
metadata: json!({}),
};
let expected = json!(vec![json!([false, 0, 8, 0.0, 0.0, 0, 0, []]); 4]);
let source = fixture.source(141);
assert!(AssetManager::perform_load_scene_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).is_err());
// Exact physical/declared size is accepted by both.
entry.size = 140;
assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected);
assert_eq!(
scene_snapshot(&AssetManager::perform_load_scene_bank(&entry, source.clone()).unwrap()),
expected
);
// An actual trailing byte is rejected by both.
entry.size = 141;
bytes.push(0);
std::fs::write(&fixture.0, bytes).unwrap();
assert!(AssetManager::perform_load_scene_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).is_err());
}
// Every mode sees the same declared slice, just as it does in production.
fn check_case(name: &str, entry: &AssetEntry, bytes: Vec<u8>, expected: Option<Value>) {
let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes)));
for mode in 0..4 {
let result = (|| -> Result<Value, String> {
if mode == 3 {
return resumable::conformance_result(entry, &source);
}
if mode == 2 {
return match entry.bank_type {
BankType::GLYPH => AssetManager::perform_load_glyph_bank(entry, source.clone())
.map(|b| glyph_snapshot(&b)),
BankType::SOUNDS => {
AssetManager::perform_load_sound_bank(entry, source.clone())
.map(|b| sound_snapshot(&b))
}
BankType::SCENE => AssetManager::perform_load_scene_bank(entry, source.clone())
.map(|b| scene_snapshot(&b)),
};
}
let slice = source
.read()
.unwrap()
.open_slice(entry.offset, entry.size)
.map_err(|e| e.to_string())?;
let bytes = slice.read_all().map_err(|e| e.to_string())?;
let mut reader = &bytes[..];
match (entry.bank_type, mode) {
(BankType::GLYPH, 0) => AssetManager::decode_glyph_bank_from_buffer(entry, &bytes)
.map(|b| glyph_snapshot(&b)),
(BankType::GLYPH, _) => {
AssetManager::decode_glyph_bank_from_reader(entry, &mut reader)
.map(|b| glyph_snapshot(&b))
}
(BankType::SOUNDS, 0) => AssetManager::decode_sound_bank_from_buffer(entry, &bytes)
.map(|b| sound_snapshot(&b)),
(BankType::SOUNDS, _) => {
AssetManager::decode_sound_bank_from_reader(entry, &mut reader)
.map(|b| sound_snapshot(&b))
}
(BankType::SCENE, 0) => AssetManager::decode_scene_bank_from_buffer(entry, &bytes)
.map(|b| scene_snapshot(&b)),
(BankType::SCENE, _) => {
AssetManager::decode_scene_bank_from_reader(entry, &mut reader)
.map(|b| scene_snapshot(&b))
}
}
})();
assert_eq!(result.ok(), expected, "{name}, mode={mode}");
}
}
#[test]
fn glyph_layout_palette_nibbles_and_chunk_boundaries() {
for pixels in [0_usize, 1, 2, 8191, 8192, 8193, 16385] {
for palettes in [1, 3, 64] {
let mut bytes = vec![0x12; pixels.div_ceil(2)];
bytes.extend(std::iter::repeat_n([0x12, 0x34, 0x56, 0x78], palettes * 16).flatten());
let entry = AssetEntry {
asset_id: 1,
asset_name: "glyph".into(),
bank_type: BankType::GLYPH,
offset: 0,
size: bytes.len() as u64,
decoded_size: (pixels + palettes * 64) as u64,
codec: AssetCodec::None,
metadata: json!({"tile_size":16,"width":pixels,"height":1,"palette_count":palettes,"palette_authored":palettes}),
};
let expected = json!([
16,
pixels,
1,
(0..pixels).map(|i| 1 + i % 2).collect::<Vec<_>>(),
vec![vec![0x12345678_u32; 16]; palettes]
]);
check_case("glyph-valid", &entry, bytes.clone(), Some(expected));
for (key, value) in [
("tile_size", json!(7)),
("palette_count", json!(0)),
("palette_count", json!(65)),
("width", json!(-1)),
("height", json!("bad")),
] {
let mut invalid = entry.clone();
invalid.metadata[key] = value;
check_case(key, &invalid, bytes.clone(), None);
}
let mut invalid = entry.clone();
invalid.decoded_size += 1;
check_case("glyph-decoded-size", &invalid, bytes.clone(), None);
let mut invalid = entry.clone();
invalid.size += 1;
let mut extra = bytes.clone();
extra.push(0);
check_case("glyph-trailing", &invalid, extra, None);
bytes.pop();
check_case("glyph-truncated", &entry, bytes, None);
}
}
}
fn empty_scene() -> (AssetEntry, Vec<u8>, Value) {
let mut bytes = vec![0_u8; 140];
bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]);
for start in [12, 44, 76, 108] {
bytes[start + 5] = 8;
}
let entry = AssetEntry {
asset_id: 2,
asset_name: "scene".into(),
bank_type: BankType::SCENE,
offset: 0,
size: 140,
decoded_size: 64,
codec: AssetCodec::None,
metadata: json!({}),
};
(entry, bytes, json!(vec![json!([false, 0, 8, 0.0, 0.0, 0, 0, []]); 4]))
}
#[test]
fn scene_header_ranges_nonfinite_and_truncation_corpus() {
let (entry, bytes, expected) = empty_scene();
check_case("empty-scene", &entry, bytes.clone(), Some(expected));
for end in 0..bytes.len() {
let mut e = entry.clone();
e.size = end as u64;
check_case("scene-every-truncation", &e, bytes[..end].to_vec(), None);
}
for (offset, value) in [(0, 0xff), (4, 2), (6, 3), (17, 7), (36, 1)] {
let mut invalid = bytes.clone();
invalid[offset] = value;
check_case("scene-invalid-header-field", &entry, invalid, None);
}
for offset in [20, 24] {
for value in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY] {
let mut invalid = bytes.clone();
invalid[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
check_case("scene-nonfinite", &entry, invalid, None);
}
}
let mut invalid = bytes.clone();
for offset in [28, 32, 36] {
invalid[offset..offset + 4].copy_from_slice(&u32::MAX.to_le_bytes());
}
check_case("scene-dimensions-overflow-or-count-mismatch", &entry, invalid, None);
let mut invalid = bytes.clone();
for offset in [28, 32, 36] {
invalid[offset..offset + 4].copy_from_slice(&1_u32.to_le_bytes());
}
// Four layer headers no longer fit after the declared tile consumes bytes.
check_case("scene-tile-range", &entry, invalid, None);
let mut sequence_metadata = entry.clone();
sequence_metadata.metadata = json!([]);
check_case(
"scene-empty-sequence-metadata",
&sequence_metadata,
bytes.clone(),
Some(empty_scene().2),
);
let mut e = entry.clone();
e.decoded_size += 1;
check_case("scene-decoded-size", &e, bytes.clone(), None);
e = entry.clone();
e.size += 1;
let mut trailing = bytes.clone();
trailing.push(0);
check_case("scene-trailing", &e, trailing, None);
for metadata in [json!(null), json!("bad")] {
e = entry.clone();
e.metadata = metadata;
check_case("scene-metadata", &e, bytes.clone(), None);
}
}
#[test]
fn scene_tile_chunk_edges_flags_and_reserved_bytes() {
for count in [1_usize, 1023, 1024, 1025, 2049] {
let (mut entry, mut bytes, mut expected) = empty_scene();
bytes[12] = 0xff; // Only the active flag is meaningful.
bytes[13..17].copy_from_slice(&(-7_i32).to_le_bytes());
bytes[17] = 32;
bytes[18..20].copy_from_slice(&[0xff; 2]); // Reserved fields are ignored.
bytes[20..24].copy_from_slice(&(-0.5_f32).to_le_bytes());
bytes[24..28].copy_from_slice(&2.0_f32.to_le_bytes());
bytes[28..32].copy_from_slice(&(count as u32).to_le_bytes());
bytes[32..36].copy_from_slice(&1_u32.to_le_bytes());
bytes[36..40].copy_from_slice(&(count as u32).to_le_bytes());
bytes.splice(44..44, std::iter::repeat_n([0xff, 255, 0x34, 0x12], count).flatten());
entry.size = bytes.len() as u64;
entry.decoded_size += (count * size_of::<Tile>()) as u64;
expected[0] = json!([
true,
-7,
32,
-0.5,
2.0,
count,
1,
vec![(true, 0x1234, 255, true, true); count]
]);
check_case("scene-chunks", &entry, bytes, Some(expected));
}
}
#[test]
fn pcm_metadata_and_source_range_corpus() {
for metadata in [
json!(null),
json!({}),
json!({"sample_rate":-1,"channels":1}),
json!({"sample_rate":44100,"channels":"bad"}),
] {
let mut e = pcm_entry(2);
e.metadata = metadata;
check_case("pcm-metadata", &e, vec![0x34, 0x12], None);
}
// These fields are currently descriptive, not extra PCM layout constraints.
let mut e = pcm_entry(2);
e.metadata = json!({"sample_rate":0,"channels":0});
e.decoded_size = 999;
check_case(
"pcm-permissive-metadata",
&e,
vec![0x34, 0x12],
Some(json!([[[0x1234], 0, null, null]])),
);
for offset in [1, u64::MAX] {
let mut e = pcm_entry(2);
e.offset = offset;
check_case("source-range", &e, vec![0x34, 0x12], None);
}
let mut e = pcm_entry(2);
e.size = u64::MAX;
check_case("source-size-overflow", &e, vec![0x34, 0x12], None);
}
pub(in crate::asset) fn glyph_snapshot(bank: &GlyphBank) -> Value {
json!([
bank.tile_size as u8,
bank.width,
bank.height,
bank.pixel_indices,
bank.palettes
.iter()
.map(|p| p.iter().map(|c| c.raw()).collect::<Vec<_>>())
.collect::<Vec<_>>()
])
}
pub(in crate::asset) fn sound_snapshot(bank: &SoundBank) -> Value {
json!(
bank.samples
.iter()
.map(|s| (&s.data, s.sample_rate, s.loop_start, s.loop_end))
.collect::<Vec<_>>()
)
}
pub(in crate::asset) fn scene_snapshot(bank: &SceneBank) -> Value {
json!(
bank.layers
.iter()
.map(|l| json!([
l.active,
l.glyph_asset_id,
l.tile_size as u8,
l.parallax_factor.x,
l.parallax_factor.y,
l.tilemap.width,
l.tilemap.height,
l.tilemap
.tiles
.iter()
.map(|t| (t.active, t.glyph.glyph_id, t.glyph.palette_id, t.flip_x, t.flip_y))
.collect::<Vec<_>>()
]))
.collect::<Vec<_>>()
)
}
#[test]
fn shared_scene_arithmetic_rejects_overflow_before_allocating() {
let (_, bytes, _) = empty_scene();
let mut header = bytes[12..44].to_vec();
header[16..20].copy_from_slice(&1_u32.to_le_bytes());
header[20..24].copy_from_slice(&1_u32.to_le_bytes());
header[24..28].copy_from_slice(&1_u32.to_le_bytes());
assert!(scene_layer(&header, usize::MAX, u64::MAX, &mut 0).is_err());
let mut decoded = usize::MAX;
assert!(scene_layer(&header, 44, 48, &mut decoded).is_err());
assert!(scene_layer(&header, 44, 47, &mut 0).is_err());
assert!(scene_layer(&header[..31], 44, 48, &mut 0).is_err());
}
#[test]
fn physically_truncated_glyph_palette_is_rejected_by_both_modes() {
let fixture = FileFixture::new("truncated-glyph", &[0; 63]);
let entry = AssetEntry {
asset_id: 3,
asset_name: "empty-glyph".into(),
bank_type: BankType::GLYPH,
offset: 0,
size: 64,
decoded_size: 64,
codec: AssetCodec::None,
metadata: json!({"tile_size":8,"width":0,"height":0,"palette_count":1,"palette_authored":1}),
};
let source = fixture.source(64);
assert!(AssetManager::perform_load_glyph_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).is_err());
std::fs::write(&fixture.0, [0; 64]).unwrap();
let expected = json!([8, 0, 0, [], vec![vec![0; 16]]]);
assert_eq!(
glyph_snapshot(&AssetManager::perform_load_glyph_bank(&entry, source.clone()).unwrap()),
expected
);
assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected);
}
@@ -0,0 +1,572 @@
//! Bounded decoding steps retain progress while the shared lane services saves.
use super::*;
use prometeu_hal::background_work::{BackgroundWork, WorkStep};
use prometeu_hal::cartridge::AssetsPayloadReader;
#[derive(Clone)]
pub(super) struct Resources {
handles: Arc<RwLock<HandleTable>>,
generations: Arc<RwLock<TargetGenerationTable>>,
source: Arc<RwLock<AssetsPayloadSource>>,
telemetry: Arc<Mutex<AssetPipelineTelemetryState>>,
gfx: BankPolicy<GlyphBank>,
sound: BankPolicy<SoundBank>,
scene: BankPolicy<SceneBank>,
}
impl Resources {
pub(super) fn new(m: &AssetManager) -> Self {
Self {
handles: m.handles.clone(),
generations: m.target_generations.clone(),
source: m.assets_data.clone(),
telemetry: m.pipeline_telemetry.clone(),
gfx: m.gfx_policy.clone(),
sound: m.sound_policy.clone(),
scene: m.scene_policy.clone(),
}
}
fn current(&self, job: &AssetLoadJob) -> bool {
AssetManager::is_current_target_generation(
&self.generations,
job.slot,
job.request_generation,
)
}
}
pub(super) fn schedule(
queue: Arc<AssetLoadQueue>,
lane: Arc<dyn BackgroundWork>,
resources: Resources,
) {
{
let mut state = queue.state.lock().unwrap();
if state.scheduled || state.shutdown {
return;
}
state.scheduled = true;
}
let owner = queue.clone();
let failure_queue = queue.clone();
let failures = resources.clone();
let mut active: Option<(AssetLoadJob, Decoder, Instant)> = None;
if lane
.submit_asset(Box::new(move |canceled| {
if canceled || owner.state.lock().unwrap().shutdown {
let mut state = owner.state.lock().unwrap();
state.scheduled = false;
state.active = None;
return WorkStep::Failed;
}
if active.is_none() {
let job = {
let mut state = owner.state.lock().unwrap();
match state.pending.pop_front() {
Some(job) => {
state.active = Some(job.clone());
job
}
None => {
state.scheduled = false;
return WorkStep::Complete;
}
}
};
if !resources.current(&job) {
resources.telemetry.lock().unwrap().record_stale_discard();
owner.complete_active(job.handle_id, job.request_generation);
return WorkStep::Yield;
}
if let Some(handle) = resources.handles.write().unwrap().get_mut(&job.handle_id) {
handle.status = LoadStatus::LOADING;
handle.progress = ASSET_PROGRESS_LOADING;
}
let start = Instant::now();
resources.telemetry.lock().unwrap().record_started(0);
match Decoder::new(&job.entry, &resources.source) {
Ok(decoder) => active = Some((job, decoder, start)),
Err(_) => {
AssetManager::complete_load_job(
&resources.handles,
&job,
LoadStatus::ERROR,
);
AssetManager::record_load_job_finished(
&resources.telemetry,
&job,
start,
LoadStatus::ERROR,
);
owner.complete_active(job.handle_id, job.request_generation);
return WorkStep::Yield;
}
}
return WorkStep::Yield;
}
let (job, decoder, start) = active.as_mut().unwrap();
if !resources.current(job) {
resources.telemetry.lock().unwrap().record_stale_discard();
owner.complete_active(job.handle_id, job.request_generation);
active = None;
return WorkStep::Yield;
}
match decoder.step() {
Ok(None) => WorkStep::Yield,
outcome => {
let generations = resources.generations.read().unwrap();
let status = if let Ok(Some(bank)) = outcome {
if generations.get(&job.slot).copied().unwrap_or(0)
== job.request_generation
{
match bank {
Decoded::Glyph(bank) => {
let resident = resources.gfx.put_resident(
job.asset_id,
Arc::new(bank),
job.entry.decoded_size as usize,
);
resources.gfx.stage(
job.handle_id,
resident,
job.entry.decoded_size as usize,
);
}
Decoded::Sound(bank) => {
let resident = resources.sound.put_resident(
job.asset_id,
Arc::new(bank),
job.entry.decoded_size as usize,
);
resources.sound.stage(
job.handle_id,
resident,
job.entry.decoded_size as usize,
);
}
Decoded::Scene(bank) => {
let resident = resources.scene.put_resident(
job.asset_id,
Arc::new(bank),
job.entry.decoded_size as usize,
);
resources.scene.stage(
job.handle_id,
resident,
job.entry.decoded_size as usize,
);
}
}
LoadStatus::READY
} else {
LoadStatus::ERROR
}
} else {
LoadStatus::ERROR
};
drop(generations);
AssetManager::complete_load_job(&resources.handles, job, status);
AssetManager::record_load_job_finished(
&resources.telemetry,
job,
*start,
status,
);
owner.complete_active(job.handle_id, job.request_generation);
active = None;
WorkStep::Yield
}
}
}))
.is_err()
{
let mut state = failure_queue.state.lock().unwrap();
state.scheduled = false;
for job in state.pending.drain(..) {
AssetManager::complete_load_job(&failures.handles, &job, LoadStatus::ERROR);
}
}
}
enum Decoded {
Glyph(GlyphBank),
Sound(SoundBank),
Scene(SceneBank),
}
enum State {
Glyph {
bank: GlyphBank,
packed: usize,
position: usize,
palette_bytes: usize,
palette_position: usize,
},
Sound {
sample_rate: u32,
data: Vec<i16>,
remaining: usize,
},
Scene {
layers: [SceneLayer; SCENE_LAYER_COUNT_V1],
layer: usize,
tiles_left: usize,
header: bool,
decoded: usize,
},
Done,
}
struct Decoder {
reader: AssetsPayloadReader,
entry: AssetEntry,
state: State,
position: usize,
}
impl Decoder {
fn new(entry: &AssetEntry, source: &Arc<RwLock<AssetsPayloadSource>>) -> Result<Self, String> {
let reader = source
.read()
.unwrap()
.open_slice(entry.offset, entry.size)
.map_err(|e| e.to_string())?
.open_reader()
.map_err(|e| e.to_string())?;
let state = match entry.bank_type {
BankType::GLYPH => {
let (tile_size, width, height, packed, palette_count, palette_bytes) =
AssetManager::decode_glyph_bank_layout(entry)?;
State::Glyph {
bank: GlyphBank {
tile_size,
width,
height,
pixel_indices: Vec::with_capacity(width * height),
palettes: vec![[Color::BLACK; 16]; palette_count],
},
packed,
position: 0,
palette_bytes,
palette_position: 0,
}
}
BankType::SOUNDS => {
let sample_rate = decode::sound_rate(entry)?;
State::Sound {
sample_rate,
data: Vec::with_capacity(entry.size as usize / 2),
remaining: entry.size as usize,
}
}
BankType::SCENE => {
decode::scene_metadata(entry)?;
State::Scene {
layers: decode::empty_layers(),
layer: 0,
tiles_left: 0,
header: false,
decoded: 0,
}
}
};
Ok(Self { reader, entry: entry.clone(), state, position: 0 })
}
fn step(&mut self) -> Result<Option<Decoded>, String> {
let mut bytes = [0; 4096];
match &mut self.state {
State::Glyph { bank, packed, position, palette_bytes, palette_position } => {
if *position < *packed {
let n = (*packed - *position).min(bytes.len());
self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?;
decode::append_pixels(
&mut bank.pixel_indices,
&bytes[..n],
bank.width * bank.height,
);
*position += n;
return Ok(None);
}
if *palette_position < *palette_bytes {
let n = (*palette_bytes - *palette_position).min(bytes.len());
self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?;
decode::write_palettes(&mut bank.palettes, *palette_position, &bytes[..n]);
*palette_position += n;
return Ok(None);
}
let State::Glyph { bank, .. } = std::mem::replace(&mut self.state, State::Done)
else {
unreachable!()
};
Ok(Some(Decoded::Glyph(bank)))
}
State::Sound { sample_rate, data, remaining } => {
if *remaining > 0 {
let n = (*remaining).min(bytes.len());
self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?;
decode::append_pcm(data, &bytes[..n]);
*remaining -= n;
return Ok(None);
}
let rate = *sample_rate;
let data = std::mem::take(data);
self.state = State::Done;
Ok(Some(Decoded::Sound(SoundBank::new(vec![Arc::new(Sample::new(rate, data))]))))
}
State::Scene { layers, layer, tiles_left, header, decoded } => {
if !*header {
self.reader
.read_exact(&mut bytes[..SCENE_HEADER_BYTES_V1])
.map_err(|e| e.to_string())?;
decode::scene_header(&bytes[..SCENE_HEADER_BYTES_V1])?;
self.position += SCENE_HEADER_BYTES_V1;
*header = true;
return Ok(None);
}
if *tiles_left > 0 {
let n = (*tiles_left).min(bytes.len() / SCENE_TILE_RECORD_BYTES_V1);
let count = n * SCENE_TILE_RECORD_BYTES_V1;
self.reader.read_exact(&mut bytes[..count]).map_err(|e| e.to_string())?;
decode::append_tiles(&mut layers[*layer - 1].tilemap.tiles, &bytes[..count]);
*tiles_left -= n;
self.position += count;
return Ok(None);
}
if *layer < layers.len() {
self.reader
.read_exact(&mut bytes[..SCENE_LAYER_HEADER_BYTES_V1])
.map_err(|e| e.to_string())?;
self.position += SCENE_LAYER_HEADER_BYTES_V1;
layers[*layer] = decode::scene_layer(
&bytes[..SCENE_LAYER_HEADER_BYTES_V1],
self.position,
self.entry.size,
decoded,
)?;
let count = layers[*layer].tilemap.width * layers[*layer].tilemap.height;
*layer += 1;
*tiles_left = count;
return Ok(None);
}
decode::scene_finish(&self.entry, self.position, *decoded)?;
let State::Scene { layers, .. } = std::mem::replace(&mut self.state, State::Done)
else {
unreachable!()
};
Ok(Some(Decoded::Scene(SceneBank { layers })))
}
State::Done => Err("Decoder already complete".into()),
}
}
}
// Test-only access to the production state machine; no alternate decode rules.
#[cfg(test)]
pub(super) fn conformance_result(
entry: &AssetEntry,
source: &Arc<RwLock<AssetsPayloadSource>>,
) -> Result<serde_json::Value, String> {
use std::io::Seek;
let mut decoder = Decoder::new(entry, source)?;
for _ in 0..100 {
let before = decoder.reader.stream_position().unwrap();
let result = decoder.step();
let after = decoder.reader.stream_position().unwrap();
assert!(after >= before && after - before <= 4096, "unbounded or rewound decode step");
if let Some(bank) = result? {
return Ok(match bank {
Decoded::Glyph(bank) => super::decode::tests::glyph_snapshot(&bank),
Decoded::Sound(bank) => super::decode::tests::sound_snapshot(&bank),
Decoded::Scene(bank) => super::decode::tests::scene_snapshot(&bank),
});
}
}
panic!("conformance fixture exceeded its step budget")
}
#[cfg(test)]
mod tests {
use super::*;
use prometeu_hal::background_work::{AssetWork, WorkUnavailable};
#[derive(Default)]
struct ManualLane(Mutex<VecDeque<AssetWork>>);
impl BackgroundWork for ManualLane {
fn submit_asset(&self, work: AssetWork) -> Result<(), WorkUnavailable> {
self.0.lock().unwrap().push_back(work);
Ok(())
}
}
impl ManualLane {
fn step(&self) -> bool {
let Some(mut work) = self.0.lock().unwrap().pop_front() else { return false };
if work(false) == WorkStep::Yield {
self.0.lock().unwrap().push_back(work);
}
true
}
}
#[test]
fn shared_decoder_yields_and_matches_existing_glyph_format() {
let mut data = vec![0x12; 32];
data.extend([255; 64]);
let entry = AssetEntry {
asset_id: 7,
asset_name: "glyph".into(),
bank_type: BankType::GLYPH,
codec: AssetCodec::None,
offset: 0,
size: data.len() as u64,
decoded_size: 128,
metadata: serde_json::json!({"tile_size":8,"width":8,"height":8,"palette_count":1,"palette_authored":1}),
};
let expected = AssetManager::decode_glyph_bank_from_buffer(&entry, &data).unwrap();
let banks = Arc::new(crate::memory_banks::MemoryBanks::new());
let mut manager = AssetManager::new(
vec![entry],
AssetsPayloadSource::from_bytes(data),
banks.clone(),
banks.clone(),
banks,
);
let lane = Arc::new(ManualLane::default());
assert!(manager.bind_background_work(lane.clone()));
let handle = manager.load(7, 0).unwrap();
let mut steps = 0;
while lane.step() {
steps += 1;
assert!(steps < 20);
}
assert!(steps >= 4);
assert_eq!(manager.status(handle), LoadStatus::READY);
let staging = manager.gfx_policy.staging.read().unwrap();
let (actual, _) = staging.get(&handle).unwrap();
assert_eq!(actual.pixel_indices, expected.pixel_indices);
assert_eq!(actual.palettes, expected.palettes);
}
fn decode_in_steps(entry: &AssetEntry, bytes: Vec<u8>) -> Decoded {
let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes)));
let mut decoder = Decoder::new(entry, &source).unwrap();
for _ in 0..100 {
if let Some(result) = decoder.step().unwrap() {
return result;
}
}
panic!("decoder did not finish")
}
#[test]
fn resumable_sound_and_scene_preserve_existing_formats() {
let pcm: Vec<i16> = (0..5000).map(|n| n as i16 - 2500).collect();
let bytes: Vec<u8> = pcm.iter().flat_map(|n| n.to_le_bytes()).collect();
let entry = AssetEntry {
asset_id: 1,
asset_name: "pcm".into(),
bank_type: BankType::SOUNDS,
offset: 0,
size: bytes.len() as u64,
decoded_size: bytes.len() as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({"sample_rate":44100,"channels":1}),
};
let Decoded::Sound(bank) = decode_in_steps(&entry, bytes) else { panic!() };
assert_eq!(bank.samples[0].data, pcm);
let scene = crate::asset::tests::test_scene();
let bytes = crate::asset::tests::encode_scene_payload(&scene);
let entry = crate::asset::tests::test_scene_asset_entry("scene", &bytes, &scene);
let Decoded::Scene(actual) = decode_in_steps(&entry, bytes) else { panic!() };
for (a, b) in actual.layers.iter().zip(scene.layers.iter()) {
assert_eq!(a.active, b.active);
assert_eq!(a.glyph_asset_id, b.glyph_asset_id);
assert_eq!(a.tile_size, b.tile_size);
assert_eq!(a.parallax_factor.x, b.parallax_factor.x);
assert_eq!(a.tilemap.width, b.tilemap.width);
assert_eq!(a.tilemap.height, b.tilemap.height);
assert_eq!(a.tilemap.tiles.len(), b.tilemap.tiles.len());
for (x, y) in a.tilemap.tiles.iter().zip(&b.tilemap.tiles) {
assert_eq!(
(x.active, x.glyph.glyph_id, x.glyph.palette_id, x.flip_x, x.flip_y),
(y.active, y.glyph.glyph_id, y.glyph.palette_id, y.flip_x, y.flip_y)
);
}
}
}
#[test]
fn shared_preload_waits_for_worker_and_frame_publication() {
let bytes = vec![0; 8192];
let entry = AssetEntry {
asset_id: 1,
asset_name: "pcm".into(),
bank_type: BankType::SOUNDS,
offset: 0,
size: bytes.len() as u64,
decoded_size: bytes.len() as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({"sample_rate":44100,"channels":1}),
};
let banks = Arc::new(crate::memory_banks::MemoryBanks::new());
let mut manager = AssetManager::new(
vec![],
AssetsPayloadSource::empty(),
banks.clone(),
banks.clone(),
banks,
);
let lane = Arc::new(ManualLane::default());
assert!(manager.bind_background_work(lane.clone()));
manager.initialize_for_cartridge(
vec![entry],
vec![PreloadEntry { asset_id: 1, slot: 0 }],
AssetsPayloadSource::from_bytes(bytes),
);
assert_eq!(manager.preloads_ready(), Ok(false));
while lane.step() {}
assert_eq!(manager.preloads_ready(), Ok(false));
manager.apply_commits();
assert_eq!(manager.preloads_ready(), Ok(true));
assert_eq!(manager.slot_info(SlotRef::audio(0)).asset_id, Some(1));
}
#[test]
fn canceled_and_superseded_partial_decoders_never_publish() {
use crate::memory_banks::SoundBankPoolAccess;
let bytes = vec![0x12; 16384];
let entry = AssetEntry {
asset_id: 1,
asset_name: "pcm".into(),
bank_type: BankType::SOUNDS,
offset: 0,
size: bytes.len() as u64,
decoded_size: bytes.len() as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({"sample_rate":44100,"channels":1}),
};
let mut newer = entry.clone();
newer.asset_id = 2;
let banks = Arc::new(crate::memory_banks::MemoryBanks::new());
let mut manager = AssetManager::new(
vec![entry, newer],
AssetsPayloadSource::from_bytes(bytes),
banks.clone(),
banks.clone(),
banks.clone(),
);
let lane = Arc::new(ManualLane::default());
assert!(manager.bind_background_work(lane.clone()));
let handle = manager.load(1, 0).unwrap();
assert!(lane.step());
assert!(lane.step());
assert_eq!(manager.status(handle), LoadStatus::LOADING);
assert_eq!(manager.cancel(handle), AssetOpStatus::Ok);
while lane.step() {}
assert_eq!(manager.status(handle), LoadStatus::CANCELED);
assert!(manager.sound_policy.staging.read().unwrap().is_empty());
manager.apply_commits();
assert!(banks.sound_bank_slot(0).is_none());
let old = manager.load(1, 0).unwrap();
assert!(lane.step());
assert!(lane.step());
let new = manager.load(2, 0).unwrap();
assert_eq!(old, new); // Stable slot handle, different request generation.
assert!(lane.step()); // Discard the in-flight old decoder.
assert!(manager.sound_policy.staging.read().unwrap().is_empty());
while lane.step() {}
assert_eq!(manager.status(new), LoadStatus::READY);
assert!(banks.sound_bank_slot(0).is_none());
assert_eq!(manager.commit(new), AssetOpStatus::Ok);
manager.apply_commits();
assert_eq!(manager.slot_info(SlotRef::audio(0)).asset_id, Some(2));
assert_eq!(banks.sound_bank_slot(0).unwrap().samples[0].data, vec![0x1212; 8192]);
}
}
+281 -168
View File
@@ -13,8 +13,7 @@ use prometeu_hal::sample::Sample;
/// State of a single playback voice (channel).
///
/// The Core maintains this state to provide information to the App (e.g., is_playing),
/// but the actual real-time mixing is performed by the Host using commands.
/// This state belongs exclusively to the mixer, which observes natural completion.
pub struct Channel {
/// The actual sample data being played.
pub sample: Option<Arc<Sample>>,
@@ -30,7 +29,7 @@ pub struct Channel {
pub pan: u8,
/// Loop configuration for this voice.
pub loop_mode: LoopMode,
/// Playback priority (used for voice stealing policies).
/// Internal priority metadata; the guest explicitly selects its voice.
pub priority: u8,
}
@@ -64,7 +63,7 @@ pub enum AudioCommand {
priority: u8,
loop_mode: LoopMode,
},
/// Immediately stop playback on a voice.
/// Stop playback on a voice when this command is applied.
Stop { voice_id: usize },
/// Update volume of an ongoing playback.
SetVolume { voice_id: usize, volume: u8 },
@@ -72,36 +71,65 @@ pub enum AudioCommand {
SetPan { voice_id: usize, pan: u8 },
/// Update pitch of an ongoing playback.
SetPitch { voice_id: usize, pitch: f64 },
/// Pause all audio processing.
MasterPause,
/// Resume audio processing.
MasterResume,
}
/// PROMETEU Audio Subsystem.
///
/// Models a multi-channel PCM sampler (SPU).
/// The audio system in Prometeu is **command-based**. This means the Core
/// doesn't generate raw audio samples; instead, it sends high-level commands
/// (like `Play`, `Stop`, `SetVolume`) to a queue. The physical host backend
/// (e.g., CPAL on desktop) then consumes these commands and performs the
/// actual mixing at the native hardware sample rate.
///
/// ### Key Features:
/// - **16 Simultaneous Voices**: Independent volume, pan, and pitch.
/// - **Sample-based Synthesis**: Plays PCM data stored in SoundBanks.
/// - **Stereo Output**: 48kHz output target.
mod transport;
pub use transport::{AudioDelivery, AudioTransport};
pub const MAX_COMMANDS_PER_FRAME: usize = 1024;
/// Bounded producer staging. Samples belong to staged/published commands and the
/// mixer, never to a second playback mirror that cannot observe completion.
pub struct Audio {
/// Local state of the hardware voices. This state is used for logic
/// (e.g., checking if a sound is still playing) and is synchronized with the Host.
pub voices: [Channel; MAX_CHANNELS],
/// Queue of pending commands to be processed by the Host mixer.
/// This queue is typically flushed and sent to the Host once per frame.
pub commands: Vec<AudioCommand>,
/// Interface to access sound memory banks (ARAM).
commands: Vec<AudioCommand>,
/// Admission survives an early lifecycle flush of the interrupted frame.
frame_commands_admitted: usize,
lifecycle_commands: Vec<AudioCommand>,
in_lifecycle: bool,
session: Option<u32>,
transport: AudioTransport,
pub sound_banks: Arc<dyn SoundBankPoolAccess>,
}
impl Audio {
pub fn new(sound_banks: Arc<dyn SoundBankPoolAccess>) -> Self {
Self {
commands: Vec::new(),
frame_commands_admitted: 0,
lifecycle_commands: Vec::new(),
in_lifecycle: false,
session: None,
transport: AudioTransport::default(),
sound_banks,
}
}
pub fn transport(&self) -> AudioTransport {
self.transport.clone()
}
fn enqueue(&mut self, voice: usize, command: AudioCommand) -> AudioOpStatus {
if voice >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
let admitted = if self.in_lifecycle {
self.lifecycle_commands.len()
} else {
self.frame_commands_admitted
};
if admitted >= MAX_COMMANDS_PER_FRAME {
return AudioOpStatus::CommandLimit;
}
if self.in_lifecycle {
self.lifecycle_commands.push(command);
} else {
self.commands.push(command);
self.frame_commands_admitted += 1;
}
AudioOpStatus::Ok
}
}
impl AudioBridge for Audio {
fn play(
&mut self,
@@ -112,14 +140,23 @@ impl AudioBridge for Audio {
pan: u8,
pitch: f64,
priority: u8,
loop_mode: prometeu_hal::LoopMode,
loop_mode: LoopMode,
) -> AudioOpStatus {
let lm = match loop_mode {
prometeu_hal::LoopMode::Off => LoopMode::Off,
prometeu_hal::LoopMode::On => LoopMode::On,
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
}
let Some(bank) = self.sound_banks.sound_bank_slot(bank_id as usize) else {
return AudioOpStatus::BankInvalid;
};
self.play(bank_id, sample_id, voice_id, volume, pan, pitch, priority, lm)
let Some(sample) = bank.samples.get(sample_id as usize).cloned() else {
return AudioOpStatus::SampleNotFound;
};
self.play_sample(sample, voice_id, volume, pan, pitch, priority, loop_mode)
}
fn play_sample(
&mut self,
sample: Arc<Sample>,
@@ -128,156 +165,85 @@ impl AudioBridge for Audio {
pan: u8,
pitch: f64,
priority: u8,
loop_mode: prometeu_hal::LoopMode,
) -> AudioOpStatus {
let lm = match loop_mode {
prometeu_hal::LoopMode::Off => LoopMode::Off,
prometeu_hal::LoopMode::On => LoopMode::On,
};
self.play_sample(sample, voice_id, volume, pan, pitch, priority, lm)
}
fn stop(&mut self, voice_id: usize) {
self.stop(voice_id)
}
fn set_volume(&mut self, voice_id: usize, volume: u8) {
self.set_volume(voice_id, volume)
}
fn set_pan(&mut self, voice_id: usize, pan: u8) {
self.set_pan(voice_id, pan)
}
fn set_pitch(&mut self, voice_id: usize, pitch: f64) {
self.set_pitch(voice_id, pitch)
}
fn is_playing(&self, voice_id: usize) -> bool {
self.is_playing(voice_id)
}
fn clear_commands(&mut self) {
self.clear_commands()
}
}
impl Audio {
/// Initializes the audio system with empty voices and sound bank access.
pub fn new(sound_banks: Arc<dyn SoundBankPoolAccess>) -> Self {
Self {
voices: std::array::from_fn(|_| Channel::default()),
commands: Vec::new(),
sound_banks,
}
}
#[allow(clippy::too_many_arguments)]
pub fn play(
&mut self,
bank_id: u8,
sample_id: u16,
voice_id: usize,
volume: u8,
pan: u8,
pitch: f64,
priority: u8,
loop_mode: LoopMode,
) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
// Resolve the sample from the hardware pools
let bank_slot = self.sound_banks.sound_bank_slot(bank_id as usize);
if bank_slot.is_none() {
return AudioOpStatus::BankInvalid;
if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
}
let sample =
bank_slot.and_then(|bank| bank.samples.get(sample_id as usize).map(Arc::clone));
if let Some(s) = sample {
// println!(
// "[Audio] Resolved sample from bank {} sample {}. Playing on voice {}.",
// bank_id, sample_id, voice_id
// );
self.play_sample(s, voice_id, volume, pan, pitch, priority, loop_mode)
} else {
AudioOpStatus::SampleNotFound
}
}
#[allow(clippy::too_many_arguments)]
pub fn play_sample(
&mut self,
sample: Arc<Sample>,
voice_id: usize,
volume: u8,
pan: u8,
pitch: f64,
priority: u8,
loop_mode: LoopMode,
) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
// Update local state
self.voices[voice_id] = Channel {
sample: Some(Arc::clone(&sample)),
active: true,
pos: 0.0,
pitch,
volume,
pan,
loop_mode,
priority,
};
// Push command to the host
self.commands.push(AudioCommand::Play {
sample,
self.enqueue(
voice_id,
volume,
pan,
pitch,
priority,
loop_mode,
});
AudioOpStatus::Ok
AudioCommand::Play { sample, voice_id, volume, pan, pitch, priority, loop_mode },
)
}
pub fn stop(&mut self, voice_id: usize) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].active = false;
self.voices[voice_id].sample = None;
self.commands.push(AudioCommand::Stop { voice_id });
fn stop(&mut self, voice_id: usize) -> AudioOpStatus {
self.enqueue(voice_id, AudioCommand::Stop { voice_id })
}
fn set_volume(&mut self, voice_id: usize, volume: u8) -> AudioOpStatus {
self.enqueue(voice_id, AudioCommand::SetVolume { voice_id, volume })
}
fn set_pan(&mut self, voice_id: usize, pan: u8) -> AudioOpStatus {
self.enqueue(voice_id, AudioCommand::SetPan { voice_id, pan })
}
fn set_pitch(&mut self, voice_id: usize, pitch: f64) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS {
return AudioOpStatus::VoiceInvalid;
}
}
pub fn set_volume(&mut self, voice_id: usize, volume: u8) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].volume = volume;
self.commands.push(AudioCommand::SetVolume { voice_id, volume });
if !pitch.is_finite() || pitch <= 0.0 {
return AudioOpStatus::ArgRangeInvalid;
}
self.enqueue(voice_id, AudioCommand::SetPitch { voice_id, pitch })
}
pub fn set_pan(&mut self, voice_id: usize, pan: u8) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].pan = pan;
self.commands.push(AudioCommand::SetPan { voice_id, pan });
}
fn ready(&self) -> bool {
self.transport.ready()
}
pub fn set_pitch(&mut self, voice_id: usize, pitch: f64) {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].pitch = pitch;
self.commands.push(AudioCommand::SetPitch { voice_id, pitch });
}
fn begin_frame(&mut self) { /* Staging may already contain debugger steps. */
}
pub fn is_playing(&self, voice_id: usize) -> bool {
if voice_id < MAX_CHANNELS { self.voices[voice_id].active } else { false }
fn finish_frame(&mut self) {
let commands = std::mem::replace(&mut self.commands, self.transport.take_buffer());
self.transport.publish(commands, false);
self.frame_commands_admitted = 0;
}
/// Clears the command queue. The Host should consume this every frame.
pub fn clear_commands(&mut self) {
fn abort_frame(&mut self) {
self.commands.clear();
self.frame_commands_admitted = 0;
}
fn lifecycle_ready(&self) -> bool {
self.transport.lifecycle_ready()
}
fn begin_lifecycle(&mut self) {
self.in_lifecycle = true;
}
fn finish_lifecycle(&mut self, success: bool) {
self.in_lifecycle = false;
if success {
// Publish the earlier frame prefix first so a callback stop cannot
// be undone by an old play on resume. Do not replenish frame quota.
let mut commands = std::mem::replace(&mut self.commands, self.transport.take_buffer());
commands.append(&mut self.lifecycle_commands);
self.transport.publish(commands, true);
} else {
self.lifecycle_commands.clear();
self.abort_frame();
}
}
fn set_session(&mut self, session: Option<u32>) {
if self.session != session {
self.reset();
self.session = session;
}
}
fn reset(&mut self) {
self.abort_frame();
self.lifecycle_commands.clear();
self.in_lifecycle = false;
self.transport.reset();
}
fn set_paused(&mut self, paused: bool) {
self.transport.set_paused(paused);
}
}
@@ -326,7 +292,154 @@ mod tests {
let status = audio.play_sample(sample(), MAX_CHANNELS, 255, 128, 1.0, 0, LoopMode::Off);
assert_eq!(status, AudioOpStatus::VoiceInvalid);
assert!(!audio.voices.iter().any(|voice| voice.active));
assert!(audio.commands.is_empty());
}
}
#[cfg(test)]
mod control_tests {
use super::*;
use crate::MemoryBanks;
fn audio() -> Audio {
Audio::new(Arc::new(MemoryBanks::new()))
}
#[test]
fn quota_is_shared_and_rejections_never_publish_partial_effects() {
let mut audio = audio();
for _ in 0..MAX_COMMANDS_PER_FRAME - 1 {
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
assert_eq!(audio.set_volume(15, 0), AudioOpStatus::Ok);
assert_eq!(audio.set_pan(0, 255), AudioOpStatus::CommandLimit);
assert_eq!(audio.set_pitch(16, f64::NAN), AudioOpStatus::VoiceInvalid);
assert_eq!(audio.set_pitch(0, f64::NAN), AudioOpStatus::ArgRangeInvalid);
let sample = Arc::new(Sample::new(48_000, vec![1]));
assert_eq!(
audio.play_sample(sample.clone(), 0, 255, 0, 1.0, 0, LoopMode::Off),
AudioOpStatus::CommandLimit
);
assert_eq!(Arc::strong_count(&sample), 1);
assert!(audio.transport.try_take().unwrap().frame.is_none());
audio.finish_frame();
assert!(!audio.ready());
assert_eq!(
audio.transport.try_take().unwrap().frame.unwrap().len(),
MAX_COMMANDS_PER_FRAME
);
assert!(audio.ready());
audio.begin_frame();
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
#[test]
fn lifecycle_and_reset_bypass_full_guest_batch_and_release_samples() {
let mut audio = audio();
audio.set_session(Some(1));
let sample = Arc::new(Sample::new(48_000, vec![1]));
let weak = Arc::downgrade(&sample);
assert_eq!(audio.play_sample(sample, 0, 255, 0, 1.0, 0, LoopMode::On), AudioOpStatus::Ok);
for _ in 1..MAX_COMMANDS_PER_FRAME {
audio.stop(1);
}
audio.finish_frame();
assert!(!audio.ready());
assert!(audio.lifecycle_ready());
audio.begin_lifecycle();
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
audio.finish_lifecycle(true);
audio.set_paused(true);
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.paused);
assert_eq!(delivery.frame.as_ref().unwrap().len(), MAX_COMMANDS_PER_FRAME);
assert!(matches!(
delivery.lifecycle.as_ref().unwrap()[0],
AudioCommand::Stop { voice_id: 0 }
));
let old_epoch = delivery.epoch;
drop(delivery);
assert!(weak.upgrade().is_none(), "driver must not retain a playback mirror");
audio.stop(0);
audio.finish_frame();
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(true);
audio.set_session(Some(2));
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.epoch > old_epoch);
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
assert!(audio.ready());
}
#[test]
fn lifecycle_publishes_prefix_first_and_aborted_batches_are_cancelled() {
let mut audio = audio();
audio.set_pan(0, 17);
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(true);
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.frame.is_none());
let lifecycle = delivery.lifecycle.unwrap();
assert!(matches!(lifecycle[0], AudioCommand::SetPan { pan: 17, .. }));
assert!(matches!(lifecycle[1], AudioCommand::Stop { voice_id: 1 }));
audio.set_volume(0, 23);
audio.finish_frame();
let commands = audio.transport.try_take().unwrap().frame.unwrap();
assert_eq!(commands.len(), 1);
assert!(matches!(commands[0], AudioCommand::SetVolume { volume: 23, .. }));
audio.stop(0);
audio.abort_frame();
audio.finish_frame();
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(false);
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
}
#[test]
fn prefix_flush_preserves_quota_and_combined_delivery_is_bounded() {
let mut audio = audio();
for _ in 0..MAX_COMMANDS_PER_FRAME {
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
audio.begin_lifecycle();
for _ in 0..MAX_COMMANDS_PER_FRAME {
assert_eq!(audio.stop(1), AudioOpStatus::Ok);
}
assert_eq!(audio.stop(1), AudioOpStatus::CommandLimit);
audio.finish_lifecycle(true);
let delivery = audio.transport.try_take().unwrap().lifecycle.unwrap();
assert_eq!(delivery.len(), 2 * MAX_COMMANDS_PER_FRAME);
assert!(matches!(delivery[0], AudioCommand::Stop { voice_id: 0 }));
assert!(matches!(delivery[MAX_COMMANDS_PER_FRAME], AudioCommand::Stop { voice_id: 1 }));
assert_eq!(audio.stop(0), AudioOpStatus::CommandLimit);
// Resume and another pause must not replenish the interrupted frame quota.
for _ in 0..2 {
audio.begin_lifecycle();
audio.stop(1);
audio.finish_lifecycle(true);
audio.transport.consume_silently();
assert_eq!(audio.stop(0), AudioOpStatus::CommandLimit);
}
audio.finish_frame();
assert!(audio.transport.try_take().unwrap().frame.is_none());
assert_eq!(audio.stop(0), AudioOpStatus::Ok);
}
#[test]
fn failed_callback_cancels_unpublished_prefix_and_its_sample_reference() {
let mut audio = audio();
let sample = Arc::new(Sample::new(48_000, vec![1]));
let weak = Arc::downgrade(&sample);
audio.play_sample(sample, 0, 255, 0, 1.0, 0, LoopMode::On);
audio.begin_lifecycle();
audio.stop(0);
audio.finish_lifecycle(false);
audio.finish_frame();
let delivery = audio.transport.try_take().unwrap();
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
assert!(weak.upgrade().is_none());
}
}
@@ -0,0 +1,144 @@
use super::AudioCommand;
use std::sync::{Arc, Mutex};
/// One pending frame plus an independent lifecycle lane. Control state never
/// competes with guest commands for capacity. The lifecycle batch can include
/// an interrupted frame prefix (at most 1024 + 1024 commands). Only one consumer
/// may drain it.
#[derive(Clone, Default)]
pub struct AudioTransport(Arc<Mutex<Mailbox>>);
#[derive(Default)]
struct Mailbox {
epoch: u64,
paused: bool,
frame: Option<Vec<AudioCommand>>,
lifecycle: Option<Vec<AudioCommand>>,
recycled: [Option<Vec<AudioCommand>>; 4],
}
pub struct AudioDelivery {
pub epoch: u64,
pub paused: bool,
pub frame: Option<Vec<AudioCommand>>,
pub lifecycle: Option<Vec<AudioCommand>>,
}
impl AudioTransport {
/// The real-time consumer never waits for the producer's short critical section.
pub fn try_take(&self) -> Option<AudioDelivery> {
let mut state = self.0.try_lock().ok()?;
Some(AudioDelivery {
epoch: state.epoch,
paused: state.paused,
frame: state.frame.take(),
lifecycle: state.lifecycle.take(),
})
}
pub fn consume_silently(&self) {
if let Some(delivery) = self.try_take() {
for batch in [delivery.frame, delivery.lifecycle].into_iter().flatten() {
self.recycle_commands(batch);
}
}
}
/// Main/service lane only: drop command owners and retain bounded empty storage.
pub fn recycle_commands(&self, mut commands: Vec<AudioCommand>) {
commands.clear();
let mut state = self.0.lock().expect("audio mailbox");
if let Some(slot) = state.recycled.iter_mut().find(|slot| slot.is_none()) {
*slot = Some(commands);
}
// Excess empty buffers are destroyed here, never in the data callback.
}
pub(super) fn take_buffer(&self) -> Vec<AudioCommand> {
self.0
.lock()
.expect("audio mailbox")
.recycled
.iter_mut()
.find_map(Option::take)
.unwrap_or_default()
}
pub fn ready(&self) -> bool {
let state = self.0.lock().expect("audio mailbox");
state.frame.is_none() && state.lifecycle.is_none()
}
pub fn lifecycle_ready(&self) -> bool {
self.0.lock().expect("audio mailbox").lifecycle.is_none()
}
pub(super) fn publish(&self, commands: Vec<AudioCommand>, lifecycle: bool) {
if commands.is_empty() {
return;
}
let mut state = self.0.lock().expect("audio mailbox");
let target = if lifecycle { &mut state.lifecycle } else { &mut state.frame };
assert!(target.is_none(), "audio producer must respect backpressure");
*target = Some(commands);
}
pub(super) fn reset(&self) {
let mut state = self.0.lock().expect("audio mailbox");
state.epoch = state.epoch.checked_add(1).expect("audio epoch exhausted");
state.frame = None;
state.lifecycle = None;
state.paused = false;
}
pub(super) fn set_paused(&self, paused: bool) {
self.0.lock().expect("audio mailbox").paused = paused;
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn realtime_consumer_does_not_wait_for_publication_lock() {
let transport = AudioTransport::default();
let guard = transport.0.lock().unwrap();
assert!(transport.try_take().is_none());
drop(guard);
assert!(transport.try_take().is_some());
}
}
#[cfg(test)]
mod reuse_tests {
use super::*;
#[test]
fn service_recycles_storage_and_releases_sample_owners() {
use prometeu_hal::{LoopMode, sample::Sample};
let transport = AudioTransport::default();
let sample = Arc::new(Sample::new(48000, vec![1]));
let weak = Arc::downgrade(&sample);
let mut batch = Vec::with_capacity(1024);
let allocation = batch.as_ptr();
batch.push(AudioCommand::Play {
sample,
voice_id: 0,
volume: 255,
pan: 0,
pitch: 1.0,
priority: 0,
loop_mode: LoopMode::Off,
});
transport.recycle_commands(batch);
assert!(weak.upgrade().is_none());
let reused = transport.take_buffer();
assert_eq!(reused.as_ptr(), allocation);
assert_eq!(reused.capacity(), 1024);
assert!(reused.is_empty());
for _ in 0..8 {
transport.recycle_commands(Vec::with_capacity(16));
}
assert_eq!(transport.0.lock().unwrap().recycled.iter().flatten().count(), 4);
}
}
@@ -560,9 +560,7 @@ mod tests {
let mut bank =
GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
bank.palette_mut(palette_id).unwrap()[1] = color;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
bank.pixel_indices.fill(1);
bank
}
+28 -20
View File
@@ -12,7 +12,7 @@ use prometeu_hal::cartridge::AssetsPayloadSource;
use prometeu_hal::sprite::Sprite;
use prometeu_hal::{
AssetBridge, AudioBridge, InputPlatform, NoopTelemetryPlatform, PadBridge, RenderBackend,
RuntimePlatform, TelemetryPlatform, TouchBridge,
RuntimePlatform, TelemetryPlatform, TouchBridge, WallClock,
};
use prometeu_hal::{
Game2DFrameComposer, Game2DFramePacket, RenderSubmission, RenderSubmissionPacket,
@@ -33,6 +33,7 @@ use std::sync::Arc;
/// - **Audio**: Stereo, Command-based mixing.
/// - **Input**: 12-button Digital Gamepad + Absolute Touch/Mouse.
pub struct Hardware {
wall_clock: Arc<dyn WallClock>,
/// Shared physical memory bank ownership used by peripherals and worker backends.
pub memory_banks: Arc<MemoryBanks>,
/// The Graphics Processing Unit (GPU). Handles drawing primitives, sprites, and tilemaps.
@@ -49,12 +50,6 @@ pub struct Hardware {
pub assets: AssetManager,
}
impl Default for Hardware {
fn default() -> Self {
Self::new()
}
}
impl Hardware {
fn consume_render_submission(&mut self, submission: &RenderSubmission) {
match &submission.packet {
@@ -159,6 +154,10 @@ impl InputPlatform for Hardware {
static NOOP_TELEMETRY: NoopTelemetryPlatform = NoopTelemetryPlatform;
impl RuntimePlatform for Hardware {
fn wall_clock(&self) -> &dyn WallClock {
self.wall_clock.as_ref()
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self
}
@@ -207,12 +206,15 @@ impl Hardware {
pub const H: usize = 270;
/// Creates a fresh hardware instance with default settings.
pub fn new() -> Self {
Self::new_with_memory_banks(Arc::new(MemoryBanks::new()))
pub fn new(wall_clock: Arc<dyn WallClock>) -> Self {
Self::new_with_memory_banks(Arc::new(MemoryBanks::new()), wall_clock)
}
/// Creates hardware with explicit shared bank ownership.
pub fn new_with_memory_banks(memory_banks: Arc<MemoryBanks>) -> Self {
pub fn new_with_memory_banks(
memory_banks: Arc<MemoryBanks>,
wall_clock: Arc<dyn WallClock>,
) -> Self {
let assets = AssetManager::new(
vec![],
AssetsPayloadSource::empty(),
@@ -222,6 +224,7 @@ impl Hardware {
);
let glyph_slot_index = assets.glyph_asset_slot_index();
Self {
wall_clock,
memory_banks: Arc::clone(&memory_banks),
gfx: Gfx::new(
Self::W,
@@ -266,9 +269,7 @@ mod tests {
fn make_glyph_bank() -> GlyphBank {
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
bank.palette_mut(0).unwrap()[1] = Color::RED;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
bank.pixel_indices.fill(1);
bank
}
@@ -306,7 +307,10 @@ mod tests {
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
banks.install_scene_bank(0, Arc::new(make_scene_with_glyph_asset_id(0)));
let mut hardware = Hardware::new_with_memory_banks(Arc::clone(&banks));
let mut hardware = Hardware::new_with_memory_banks(
Arc::clone(&banks),
Arc::new(crate::ControlledWallClock::default()),
);
let scene = banks.scene_bank_slot(0).expect("scene bank slot 0 should be resident");
let mut cache = SceneViewportCache::new(&scene, 4, 4);
cache.materialize_all_layers(&scene);
@@ -325,7 +329,8 @@ mod tests {
let banks = Arc::new(MemoryBanks::new());
banks.install_scene_bank(2, Arc::new(make_scene()));
let hardware = Hardware::new_with_memory_banks(banks);
let hardware =
Hardware::new_with_memory_banks(banks, Arc::new(crate::ControlledWallClock::default()));
let scene = hardware
.frame_composer
.scene_bank_slot(2)
@@ -342,7 +347,8 @@ mod tests {
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
banks.install_scene_bank(0, Arc::new(make_scene_with_glyph_asset_id(0)));
let mut hardware = Hardware::new_with_memory_banks(banks);
let mut hardware =
Hardware::new_with_memory_banks(banks, Arc::new(crate::ControlledWallClock::default()));
let mut glyph_slots = [None; 16];
glyph_slots[0] = Some(0);
hardware.assets.glyph_asset_slot_index().rebuild_from_slots(&glyph_slots);
@@ -372,7 +378,8 @@ mod tests {
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
banks.install_scene_bank(0, Arc::new(make_scene_with_glyph_asset_id(0)));
let mut hardware = Hardware::new_with_memory_banks(banks);
let mut hardware =
Hardware::new_with_memory_banks(banks, Arc::new(crate::ControlledWallClock::default()));
let mut glyph_slots = [None; 16];
glyph_slots[0] = Some(0);
hardware.assets.glyph_asset_slot_index().rebuild_from_slots(&glyph_slots);
@@ -413,7 +420,7 @@ mod tests {
#[test]
fn render_submission_sink_accepts_owned_game2d_submission() {
let mut hardware = Hardware::new();
let mut hardware = Hardware::new(Arc::new(crate::ControlledWallClock::default()));
let packet = Game2DFramePacket::new(
ComposerFramePacket::default(),
vec![Gfx2dCommand::Clear { color: Color::BLUE }],
@@ -428,7 +435,7 @@ mod tests {
#[test]
fn render_submission_sink_accepts_owned_shell_ui_submission() {
let mut hardware = Hardware::new();
let mut hardware = Hardware::new(Arc::new(crate::ControlledWallClock::default()));
let packet = ShellUiFramePacket::new(vec![GfxUiCommand::Clear { color: Color::RED }]);
let submission = RenderSubmission::shell_ui(FrameId::ZERO, packet);
@@ -442,7 +449,8 @@ mod tests {
fn emit_sprite_rejects_palette_id_outside_loaded_glyph_bank() {
let banks = Arc::new(MemoryBanks::new());
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
let mut hardware = Hardware::new_with_memory_banks(banks);
let mut hardware =
Hardware::new_with_memory_banks(banks, Arc::new(crate::ControlledWallClock::default()));
let status = Game2DFrameComposer::emit_sprite(
&mut hardware,
+8 -1
View File
@@ -8,9 +8,13 @@ mod memory_banks;
mod pad;
mod test_platform;
mod touch;
mod wall_clock;
pub use crate::asset::AssetManager;
pub use crate::audio::{Audio, AudioCommand, Channel, MAX_CHANNELS, OUTPUT_SAMPLE_RATE};
pub use crate::audio::{
Audio, AudioCommand, AudioDelivery, AudioTransport, Channel, MAX_CHANNELS,
MAX_COMMANDS_PER_FRAME, OUTPUT_SAMPLE_RATE,
};
pub use crate::frame_composer::{ComposerBuffer, FrameComposer, SceneStatus, SpriteController};
pub use crate::gfx::Gfx;
pub use crate::local_render_backend::LocalFramebufferRenderBackend;
@@ -20,3 +24,6 @@ pub use crate::memory_banks::{
};
pub use crate::pad::Pad;
pub use crate::test_platform::TestPlatform;
pub use crate::wall_clock::ControlledWallClock;
pub mod memcard;
@@ -0,0 +1,119 @@
//! File-host implementation. IO runs only on the shared worker, never the guest lane.
use prometeu_hal::memcard::{MemcardIoError as Error, MemcardStorage};
use std::fs::{File, OpenOptions};
use std::io::{Read, Seek, SeekFrom, Write};
use std::path::Path;
pub struct FileMemcard {
file: File,
length: u64,
read_only: bool,
}
fn io_error(e: std::io::Error) -> Error {
use std::io::ErrorKind as K;
match e.kind() {
K::NotFound => Error::Unavailable,
K::PermissionDenied => Error::ReadOnly,
K::StorageFull => Error::NoSpace,
K::InvalidInput | K::UnexpectedEof => Error::InvalidRange,
K::Unsupported => Error::Unsupported,
_ => Error::IoError,
}
}
impl FileMemcard {
pub fn open(path: &Path, read_only: bool) -> Result<Self, Error> {
let file = OpenOptions::new().read(true).write(!read_only).open(path).map_err(io_error)?;
let length = file.metadata().map_err(io_error)?.len();
Ok(Self { file, length, read_only })
}
/// Write every byte and verify allocated blocks before formatting/publication.
/// The initializer supplies the runtime-owned format. Existing files are never replaced.
#[cfg(unix)]
pub fn create(
path: &Path,
length: u64,
initialize: impl FnOnce(&mut dyn MemcardStorage, [u8; 16]) -> Result<(), Error>,
) -> Result<Self, Error> {
use std::os::unix::fs::MetadataExt;
let mut id = [0; 16];
File::open("/dev/urandom").and_then(|mut f| f.read_exact(&mut id)).map_err(io_error)?;
let parent =
path.parent().filter(|p| !p.as_os_str().is_empty()).unwrap_or_else(|| Path::new("."));
let suffix: String = id.iter().map(|b| format!("{b:02x}")).collect();
let temporary = parent.join(format!(".memcard-{suffix}.tmp"));
let file = OpenOptions::new()
.read(true)
.write(true)
.create_new(true)
.open(&temporary)
.map_err(io_error)?;
let result = (|| {
let mut card = Self { file, length, read_only: false };
let zeros = [0u8; 65_536];
let mut offset = 0;
while offset < length {
let n = (length - offset).min(zeros.len() as u64) as usize;
card.file.write_all(&zeros[..n]).map_err(io_error)?;
offset += n as u64;
}
card.sync()?;
if card.file.metadata().map_err(io_error)?.blocks().saturating_mul(512) < length {
return Err(Error::Unsupported);
}
initialize(&mut card, id)?;
card.sync()?;
// hard_link publishes without replacing a user file; parent sync makes the name durable.
std::fs::hard_link(&temporary, path).map_err(io_error)?;
File::open(parent).and_then(|f| f.sync_all()).map_err(io_error)?;
Ok(card)
})();
let cleanup =
std::fs::remove_file(&temporary).and_then(|()| File::open(parent)?.sync_all());
match result {
Ok(card) => {
cleanup.map_err(io_error)?;
Ok(card)
}
Err(e) => Err(e),
}
}
#[cfg(not(unix))]
pub fn create(
_path: &Path,
_length: u64,
_initialize: impl FnOnce(&mut dyn MemcardStorage, [u8; 16]) -> Result<(), Error>,
) -> Result<Self, Error> {
Err(Error::Unsupported)
}
fn check(&self, offset: u64, length: usize) -> Result<(), Error> {
if length > 65_536 || offset.checked_add(length as u64).is_none_or(|end| end > self.length)
{
return Err(Error::InvalidRange);
}
Ok(())
}
}
impl MemcardStorage for FileMemcard {
fn len(&self) -> Result<u64, Error> {
Ok(self.length)
}
fn read_only(&self) -> bool {
self.read_only
}
fn read_at(&mut self, offset: u64, target: &mut [u8]) -> Result<(), Error> {
self.check(offset, target.len())?;
self.file.seek(SeekFrom::Start(offset)).map_err(io_error)?;
self.file.read_exact(target).map_err(io_error)
}
fn write_at(&mut self, offset: u64, source: &[u8]) -> Result<(), Error> {
if self.read_only {
return Err(Error::ReadOnly);
}
self.check(offset, source.len())?;
self.file.seek(SeekFrom::Start(offset)).map_err(io_error)?;
self.file.write_all(source).map_err(io_error)
}
fn sync(&mut self) -> Result<(), Error> {
self.file.sync_all().map_err(io_error)
}
}
@@ -1,13 +1,15 @@
use crate::ControlledWallClock;
use crate::hardware::Hardware;
use crate::memory_banks::MemoryBanks;
use prometeu_hal::{
AssetBridge, AudioBridge, Game2DFrameComposer, InputPlatform, RenderBackend,
RenderSubmissionSink, RuntimePlatform, TelemetryPlatform,
RenderSubmissionSink, RuntimePlatform, TelemetryPlatform, WallClock,
};
use std::sync::Arc;
pub struct TestPlatform {
hardware: Hardware,
controlled_wall_clock: Option<Arc<ControlledWallClock>>,
}
impl Default for TestPlatform {
@@ -18,11 +20,24 @@ impl Default for TestPlatform {
impl TestPlatform {
pub fn new() -> Self {
Self { hardware: Hardware::new() }
Self::new_with_memory_banks(Arc::new(MemoryBanks::new()))
}
pub fn new_with_memory_banks(memory_banks: Arc<MemoryBanks>) -> Self {
Self { hardware: Hardware::new_with_memory_banks(memory_banks) }
let clock = Arc::new(ControlledWallClock::default());
Self {
hardware: Hardware::new_with_memory_banks(memory_banks, clock.clone()),
controlled_wall_clock: Some(clock),
}
}
pub fn new_with_wall_clock(clock: Arc<dyn WallClock>) -> Self {
Self { hardware: Hardware::new(clock), controlled_wall_clock: None }
}
/// Native controls for the default clock. Injected providers are controlled by their owner.
pub fn controlled_wall_clock(&self) -> Option<&ControlledWallClock> {
self.controlled_wall_clock.as_deref()
}
pub fn local_hardware(&self) -> &Hardware {
@@ -35,6 +50,10 @@ impl TestPlatform {
}
impl RuntimePlatform for TestPlatform {
fn wall_clock(&self) -> &dyn WallClock {
self.hardware.wall_clock()
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self.hardware.render_submission_sink()
}
@@ -93,8 +112,26 @@ mod tests {
Game2DFramePacket::default(),
))
.expect("test platform render sink should accept local submission");
assert!(!platform.audio().is_playing(0));
assert!(platform.audio().ready());
assert!(!platform.input().pad().any());
assert!(platform.telemetry().telemetry_snapshot().is_none());
}
#[test]
fn selected_clock_is_shared_with_hardware_and_can_be_injected() {
let platform = TestPlatform::new();
assert_eq!(platform.wall_clock().utc_unix_seconds(), 0);
let clock = platform.controlled_wall_clock().expect("default controls");
clock.set(42);
assert_eq!(platform.local_hardware().wall_clock().utc_unix_seconds(), 42);
clock.advance(3);
assert_eq!(platform.wall_clock().utc_unix_seconds(), 45);
let custom = Arc::new(ControlledWallClock::new(900));
let platform = TestPlatform::new_with_wall_clock(custom.clone());
assert!(platform.controlled_wall_clock().is_none());
assert_eq!(platform.wall_clock().utc_unix_seconds(), 900);
custom.set(7);
assert_eq!(platform.local_hardware().wall_clock().utc_unix_seconds(), 7);
}
}
@@ -0,0 +1,57 @@
use prometeu_hal::WallClock;
use std::sync::atomic::{AtomicU64, Ordering};
/// A native harness-controlled civil clock. Reads and runtime ticks never advance it.
#[derive(Debug, Default)]
pub struct ControlledWallClock {
seconds: AtomicU64,
}
impl ControlledWallClock {
pub fn new(seconds: u64) -> Self {
Self { seconds: AtomicU64::new(seconds) }
}
/// Set civil time explicitly, including backwards adjustments.
pub fn set(&self, seconds: u64) {
self.seconds.store(seconds, Ordering::Relaxed);
}
/// Advance civil time explicitly, saturating at the largest timestamp.
pub fn advance(&self, seconds: u64) {
// Harness control may retry on a concurrent update; reads remain a single load.
let _ = self.seconds.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
Some(current.saturating_add(seconds))
});
}
}
impl WallClock for ControlledWallClock {
fn utc_unix_seconds(&self) -> u64 {
self.seconds.load(Ordering::Relaxed)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn explicit_changes_allow_regression_and_saturate_without_advancing_on_read() {
let clock = ControlledWallClock::default();
assert_eq!(clock.utc_unix_seconds(), 0);
clock.set(100);
for _ in 0..10 {
assert_eq!(clock.utc_unix_seconds(), 100);
}
clock.advance(9);
assert_eq!(clock.utc_unix_seconds(), 109);
clock.set(3);
assert_eq!(clock.utc_unix_seconds(), 3);
clock.advance(u64::MAX);
clock.advance(1);
assert_eq!(clock.utc_unix_seconds(), u64::MAX);
clock.set(0);
assert_eq!(clock.utc_unix_seconds(), 0);
}
}
@@ -12,3 +12,4 @@ prometeu-hal = { path = "../prometeu-hal" }
[dev-dependencies]
prometeu-drivers = { path = "../prometeu-drivers" }
prometeu-bytecode = { path = "../prometeu-bytecode" }
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
@@ -3,12 +3,16 @@ use crate::firmware::firmware_state::{
FirmwareState, GameRunningStep, LoadCartridgeStep, ResetStep,
};
use crate::firmware::prometeu_context::PrometeuContext;
#[cfg(test)]
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::Cartridge;
use prometeu_hal::log::LogSource;
use prometeu_hal::telemetry::CertificationConfig;
use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_system::{PrometeuHub, ResidentGameState, SystemOS};
#[cfg(test)]
use prometeu_test_support::program::{TestProgram, int64_signature};
/// PROMETEU Firmware.
///
@@ -57,6 +61,56 @@ impl Firmware {
/// This method is called exactly once per Host frame (60Hz).
/// It updates peripheral signals and delegates the logic to the current state.
pub fn tick(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
self.sync_audio(platform);
self.tick_inner(signals, platform);
self.sync_audio(platform);
}
fn sync_audio(&mut self, platform: &mut dyn RuntimePlatform) {
let task = self.os.lifecycle().resident_game_task().map(|task| task.0);
let suspended = matches!(
self.os.lifecycle().resident_game().map(|game| game.state),
Some(ResidentGameState::PausedSuspended)
);
let paused = self.game_lifecycle_audio_paused() || self.os.vm().paused();
platform.audio_mut().set_session(task);
platform.audio_mut().set_paused(paused);
// Without a pause hook the OS can suspend synchronously, bypassing the
// callback runner. Complete the same audio boundary before resuming.
// A real hook already published its prefix; repeating an empty flush is inert.
if suspended && platform.audio().lifecycle_ready() {
platform.audio_mut().begin_lifecycle();
platform.audio_mut().finish_lifecycle(true);
}
}
fn tick_inner(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
self.os.poll_background_io(platform);
if self.os.memcard().host_faulted() {
// Keep the resident VM, snapshots, and worker-owned buffers alive. A
// stuck host operation cannot be repaired by launching another worker.
self.state = FirmwareState::MemoryIoFault;
self.state_initialized = true;
self.on_update(signals, platform);
return;
}
if self.os.memcard().session.removal_pending()
&& let Some(task) = self.os.lifecycle().resident_game_task()
{
if self.os.lifecycle().task_state(task)
== Some(prometeu_system::task::TaskState::Suspended)
{
if !matches!(
self.state,
FirmwareState::MemoryCardRemoved(_) | FirmwareState::ConfirmDiscard(_)
) {
self.state = FirmwareState::MemoryCardRemoved(Default::default());
self.state_initialized = true;
}
} else {
self.request_home_from_host();
}
}
let barriered_signals = InputSignals::default();
let effective_signals = if self.game_input_barrier_frames > 0 {
self.game_input_barrier_frames -= 1;
@@ -79,6 +133,40 @@ impl Firmware {
self.state_initialized = true;
}
// Hooks run after leaving gameplay and before completing OS suspension/resume.
if let Some((task_id, result)) = self.os.vm().poll_pending_lifecycle(platform) {
if let Err(report) = result {
let _ = self.os.lifecycle().crash_task(task_id, Some(&report));
self.change_state(
FirmwareState::AppCrashes(crate::firmware::firmware_state::AppCrashesStep {
report,
}),
effective_signals,
platform,
);
} else if matches!(self.state, FirmwareState::GameRunning(_))
&& matches!(
self.os.lifecycle().task_state(task_id),
Some(
prometeu_system::task::TaskState::Suspended
| prometeu_system::task::TaskState::Closed
)
)
{
self.os.vm().transition_render_owner(AppMode::Shell, 0);
let state = match self.os.lifecycle().foreground_owner() {
prometeu_system::ForegroundOwner::Shell(task_id) => {
FirmwareState::ShellRunning(
crate::firmware::firmware_state::ShellRunningStep::new(task_id),
)
}
_ => FirmwareState::HubHome(crate::firmware::firmware_state::HubHomeStep),
};
self.change_state(state, effective_signals, platform);
}
return;
}
// 3. Update the current state and check for transitions.
if let Some(next_state) = self.on_update(effective_signals, platform) {
self.change_state(next_state, effective_signals, platform);
@@ -129,8 +217,10 @@ impl Firmware {
FirmwareState::SplashScreen(s) => s.on_enter(&mut req),
FirmwareState::LaunchHub(s) => s.on_enter(&mut req),
FirmwareState::HubHome(s) => s.on_enter(&mut req),
FirmwareState::ConfirmDiscard(s) => s.on_enter(&mut req),
FirmwareState::MemoryCardRemoved(s) => s.on_enter(&mut req),
FirmwareState::LoadCartridge(s) => s.on_enter(&mut req),
FirmwareState::ResumeResidentGame => {}
FirmwareState::ResumeResidentGame | FirmwareState::MemoryIoFault => {}
FirmwareState::GameRunning(s) => s.on_enter(&mut req),
FirmwareState::ShellRunning(s) => s.on_enter(&mut req),
FirmwareState::AppCrashes(s) => s.on_enter(&mut req),
@@ -156,8 +246,32 @@ impl Firmware {
FirmwareState::SplashScreen(s) => s.on_update(&mut req),
FirmwareState::LaunchHub(s) => s.on_update(&mut req),
FirmwareState::HubHome(s) => s.on_update(&mut req),
FirmwareState::ConfirmDiscard(s) => s.on_update(&mut req),
FirmwareState::MemoryCardRemoved(s) => s.on_update(&mut req),
FirmwareState::LoadCartridge(s) => s.on_update(&mut req),
FirmwareState::ResumeResidentGame => None,
FirmwareState::MemoryIoFault => {
use prometeu_hal::color::Color;
use prometeu_hal::{FrameId, GfxUiCommand, RenderSubmission, ShellUiFramePacket};
let lines = [
"Memory-card IO did not stop in time.",
"Save outcome may be unknown.",
"Restart the host before using storage again.",
];
let mut commands = vec![GfxUiCommand::Clear { color: Color::BLACK }];
commands.extend(lines.into_iter().enumerate().map(|(i, text)| {
GfxUiCommand::DrawText {
x: 8,
y: 8 + i as i32 * 20,
text: text.into(),
color: Color::WHITE,
}
}));
let _ = req.platform.render_submission_sink().submit_render_submission(
RenderSubmission::shell_ui(FrameId::ZERO, ShellUiFramePacket::new(commands)),
);
None
}
FirmwareState::GameRunning(s) => s.on_update(&mut req),
FirmwareState::ShellRunning(s) => s.on_update(&mut req),
FirmwareState::AppCrashes(s) => s.on_update(&mut req),
@@ -178,8 +292,10 @@ impl Firmware {
FirmwareState::SplashScreen(s) => s.on_exit(&mut req),
FirmwareState::LaunchHub(s) => s.on_exit(&mut req),
FirmwareState::HubHome(s) => s.on_exit(&mut req),
FirmwareState::ConfirmDiscard(s) => s.on_exit(&mut req),
FirmwareState::MemoryCardRemoved(s) => s.on_exit(&mut req),
FirmwareState::LoadCartridge(s) => s.on_exit(&mut req),
FirmwareState::ResumeResidentGame => {}
FirmwareState::ResumeResidentGame | FirmwareState::MemoryIoFault => {}
FirmwareState::GameRunning(s) => s.on_exit(&mut req),
FirmwareState::ShellRunning(s) => s.on_exit(&mut req),
FirmwareState::AppCrashes(s) => s.on_exit(&mut req),
@@ -252,7 +368,7 @@ mod tests {
use crate::firmware::firmware_state::HubHomeStep;
use crate::firmware::resident_game_termination::{self, ResidentGameTerminationOutcome};
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, FunctionMeta, SyscallDecl};
use prometeu_bytecode::model::SyscallDecl;
use prometeu_drivers::{GlyphBankPoolAccess, SceneBankPoolAccess, TestPlatform};
use prometeu_hal::RuntimePlatform;
use prometeu_hal::app_mode::AppMode;
@@ -345,13 +461,18 @@ mod tests {
fn halting_program() -> Vec<u8> {
let code = assemble("HALT").expect("assemble");
BytecodeModule {
version: 0,
TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
..Default::default()
signature: int64_signature(0, 0),
captures: vec![],
name: None,
local_slots: 0,
max_stack_slots: 256,
}],
code,
debug_info: None,
@@ -367,6 +488,7 @@ mod tests {
fn invalid_game_cartridge() -> Cartridge {
Cartridge {
memcard_slots: None,
app_id: 7,
title: "Broken Cart".into(),
app_version: "1.0.0".into(),
@@ -381,13 +503,18 @@ mod tests {
fn trapping_game_cartridge() -> Cartridge {
let code = assemble("PUSH_BOOL 1\nHOSTCALL 0\nHALT").expect("assemble");
let program = BytecodeModule {
version: 0,
let program = TestProgram {
const_pool: vec![],
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
..Default::default()
signature: int64_signature(0, 0),
captures: vec![],
name: None,
local_slots: 0,
max_stack_slots: 256,
}],
code,
debug_info: None,
@@ -403,6 +530,7 @@ mod tests {
.serialize();
Cartridge {
memcard_slots: None,
app_id: 8,
title: "Trap Cart".into(),
app_version: "1.0.0".into(),
@@ -421,6 +549,7 @@ mod tests {
fn valid_cartridge_with(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
Cartridge {
memcard_slots: None,
app_id,
title: title.into(),
app_version: "1.0.0".into(),
@@ -485,6 +614,15 @@ mod tests {
platform.local_hardware().gfx.front_buffer()[index]
}
fn wait_for_cartridge_preload(firmware: &mut Firmware, platform: &mut TestPlatform) {
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(2);
while matches!(firmware.state, FirmwareState::LoadCartridge(_)) {
assert!(std::time::Instant::now() < deadline, "cartridge admission did not complete");
firmware.tick(&InputSignals::default(), platform);
std::thread::yield_now();
}
}
#[test]
fn load_cartridge_transitions_to_app_crashes_when_vm_init_fails() {
let mut firmware = Firmware::new(None);
@@ -497,7 +635,7 @@ mod tests {
match &firmware.state {
FirmwareState::AppCrashes(step) => match &step.report {
CrashReport::VmInit { error } => {
assert!(matches!(error, prometeu_vm::VmInitError::InvalidFormat));
assert!(matches!(error, prometeu_vm::VmInitError::RegistryLoadFailed(_)));
}
other => panic!("expected VmInit crash report, got {:?}", other),
},
@@ -681,7 +819,10 @@ mod tests {
root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let signals = InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
@@ -702,7 +843,10 @@ mod tests {
root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let signals = InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
@@ -720,7 +864,10 @@ mod tests {
root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let launch_click =
@@ -775,7 +922,10 @@ mod tests {
root.add_game_with_identity("zzz-dummy", 43, "Zzz Dummy", "1.0.0", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
@@ -836,7 +986,10 @@ mod tests {
#[test]
fn repository_stress_to_dummy_boy_switch_is_end_to_end() {
let library = discover_games_root(repository_test_cartridges_root());
let library = discover_games_root(
repository_test_cartridges_root(),
&prometeu_drivers::ControlledWallClock::default(),
);
assert!(
library
.entries()
@@ -856,6 +1009,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -954,6 +1108,7 @@ mod tests {
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&stress_click, &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
assert_eq!(firmware.os.lifecycle().task_state(dummy_task), Some(TaskState::Closed));
assert_eq!(
firmware.os.lifecycle().process_state_for_task(dummy_task),
@@ -1024,7 +1179,10 @@ mod tests {
#[test]
fn resident_game_termination_closes_session_and_cleans_runtime_state() {
let library = discover_games_root(repository_test_cartridges_root());
let library = discover_games_root(
repository_test_cartridges_root(),
&prometeu_drivers::ControlledWallClock::default(),
);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(library);
firmware.tick(&InputSignals::default(), &mut platform);
@@ -1034,6 +1192,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -1109,7 +1268,10 @@ mod tests {
#[test]
fn hub_kill_control_click_terminates_resident_game_and_stays_home() {
let library = discover_games_root(repository_test_cartridges_root());
let library = discover_games_root(
repository_test_cartridges_root(),
&prometeu_drivers::ControlledWallClock::default(),
);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(library);
firmware.tick(&InputSignals::default(), &mut platform);
@@ -1119,6 +1281,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -1201,7 +1364,10 @@ mod tests {
root.add_game_with_program("zzz-broken", 43, "Zzz Broken", "1.0.0", Some(vec![0, 0, 0, 0]));
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
firmware.tick(&InputSignals::default(), &mut platform);
let stress_click =
@@ -1267,7 +1433,8 @@ mod tests {
root.add_game("broken", false);
let (mut firmware, mut platform) = hub_home_firmware();
let library = discover_games_root(&root.path);
let library =
discover_games_root(&root.path, &prometeu_drivers::ControlledWallClock::default());
assert!(library.is_empty());
assert!(!library.diagnostics().is_empty());
firmware.hub.set_game_library(library);
@@ -1307,7 +1474,10 @@ mod tests {
let cart = root.add_game("stress", true);
let (mut firmware, mut platform) = hub_home_firmware();
firmware.hub.set_game_library(discover_games_root(&root.path));
firmware.hub.set_game_library(discover_games_root(
&root.path,
&prometeu_drivers::ControlledWallClock::default(),
));
fs::remove_file(cart.join("program.pbx")).expect("program should be removable");
firmware.tick(&InputSignals::default(), &mut platform);
@@ -1674,4 +1844,458 @@ mod tests {
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
assert_eq!(firmware.os.vm().current_cartridge_title(), "Valid Cart");
}
fn lifecycle_cartridge(pause: &str, resume: &str) -> Cartridge {
use prometeu_bytecode::registry::LifecycleRole;
let mut program = TestProgram::single(
assemble("FRAME_SYNC\nJMP 0").unwrap(),
int64_signature(0, 0),
0,
8,
);
for (role, source) in
[(LifecycleRole::BeforePause, pause), (LifecycleRole::BeforeResume, resume)]
{
if source.is_empty() {
continue;
}
let code = assemble(source).unwrap();
program.functions.push(FunctionDecl {
lifecycle_role: role,
code_offset: program.code.len() as u32,
code_len: code.len() as u32,
max_stack_slots: 8,
..Default::default()
});
program.code.extend(code);
}
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.program = program.serialize();
cartridge
}
fn load_lifecycle(pause: &str, resume: &str) -> (Firmware, TestPlatform, TaskId) {
let mut firmware = Firmware::new(None);
let mut platform = TestPlatform::new();
firmware.load_cartridge(lifecycle_cartridge(pause, resume));
firmware.tick(&InputSignals::default(), &mut platform);
let task = firmware.os.lifecycle().resident_game_task().unwrap();
(firmware, platform, task)
}
fn check_audio_lifecycle(partial: bool, hooks: bool) {
use prometeu_bytecode::registry::LifecycleRole;
use prometeu_drivers::AudioCommand;
let mut program = TestProgram::single(
assemble("PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\nFRAME_SYNC\nJMP 0").unwrap(),
int64_signature(0, 0),
0,
8,
);
program.syscalls.push(SyscallDecl {
module: "audio".into(),
name: "stop".into(),
version: 1,
arg_slots: 1,
ret_slots: 1,
});
for (role, voice) in [(LifecycleRole::BeforePause, 1), (LifecycleRole::BeforeResume, 2)] {
if !hooks {
continue;
}
let code = assemble(&format!("PUSH_I32 {voice}\nHOSTCALL 0\nPOP_N 1\nRET")).unwrap();
program.functions.push(FunctionDecl {
lifecycle_role: role,
code_offset: program.code.len() as u32,
code_len: code.len() as u32,
max_stack_slots: 8,
..Default::default()
});
program.code.extend(code);
}
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.capabilities = caps::AUDIO;
cartridge.program = program.serialize();
let mut fw = Firmware::new(None);
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
fw.load_cartridge(cartridge);
fw.tick(&signals, &mut platform);
if partial {
for _ in 0..2 {
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
}
} else {
fw.tick(&signals, &mut platform);
}
let task = fw.os.lifecycle().resident_game_task().unwrap();
let transport = platform.local_hardware().audio.transport();
assert_eq!(platform.audio().ready(), partial);
fw.os.lifecycle().suspend_task(task).unwrap();
fw.tick(&signals, &mut platform);
let delivery = transport.try_take().unwrap();
assert!(delivery.paused);
if partial {
assert!(delivery.frame.is_none());
} else {
assert!(matches!(delivery.frame.unwrap()[0], AudioCommand::Stop { voice_id: 0 }));
}
let lifecycle = delivery.lifecycle.unwrap_or_default();
assert_eq!(lifecycle.len(), usize::from(partial) + usize::from(hooks));
if partial {
assert!(matches!(lifecycle[0], AudioCommand::Stop { voice_id: 0 }));
}
if hooks {
assert!(matches!(lifecycle[usize::from(partial)], AudioCommand::Stop { voice_id: 1 }));
}
assert!(fw.resume_resident_game_from_home());
fw.tick(&signals, &mut platform);
let delivery = transport.try_take().unwrap();
assert!(!delivery.paused);
if hooks {
assert!(matches!(delivery.lifecycle.unwrap()[0], AudioCommand::Stop { voice_id: 2 }));
} else {
assert!(delivery.lifecycle.is_none());
assert!(delivery.frame.is_none(), "hookless resume completed the prefix-free frame");
}
let epoch = delivery.epoch;
fw.tick(&signals, &mut platform);
if partial && hooks {
assert!(
platform.audio().ready(),
"prefix must not be published again at frame completion"
);
fw.tick(&signals, &mut platform);
}
assert!(!platform.audio().ready());
fw.change_state(FirmwareState::Reset(ResetStep), &signals, &mut platform);
let delivery = transport.try_take().unwrap();
assert!(delivery.epoch > epoch);
assert!(delivery.frame.is_none() && delivery.lifecycle.is_none());
assert!(platform.audio().ready());
}
#[test]
fn audio_lifecycle_publishes_with_pending_frame_and_reset_invalidates_session() {
check_audio_lifecycle(false, true);
}
#[test]
fn audio_lifecycle_publishes_interrupted_frame_prefix_before_hook() {
check_audio_lifecycle(true, true);
}
#[test]
fn audio_lifecycle_flushes_prefix_when_optional_hooks_are_absent() {
check_audio_lifecycle(true, false);
}
#[test]
fn lifecycle_home_resume_callbacks_are_outside_frames_and_preserve_pc() {
let (mut fw, mut platform, task) = load_lifecycle("RET", "RET");
let signals = InputSignals::default();
assert!(!fw.os.lifecycle().advance_game_pause_budget(task).unwrap());
assert!(fw.os.vm().poll_pending_lifecycle(&mut platform).is_none());
fw.request_home_from_host();
fw.tick(&signals, &mut platform); // existing handoff tick
let pc = fw.os.vm().active_pc();
let ticks = vm_session_tick_index(&mut fw, task);
let frames = fw.os.vm().completed_logical_frames();
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground));
fw.tick(&signals, &mut platform); // BeforePause only
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
assert_eq!(fw.os.vm().active_pc(), pc);
assert_eq!(vm_session_tick_index(&mut fw, task), ticks);
assert!(fw.resume_resident_game_from_home());
fw.tick(&signals, &mut platform); // BeforeResume only
assert_eq!(fw.os.vm().active_pc(), pc);
assert_eq!(vm_session_tick_index(&mut fw, task), ticks);
assert_eq!(fw.os.vm().completed_logical_frames(), frames);
assert_eq!(fw.os.lifecycle().resident_game().unwrap().state, ResidentGameState::Foreground);
fw.tick(&signals, &mut platform);
assert_eq!(vm_session_tick_index(&mut fw, task), ticks + 1);
}
#[test]
fn lifecycle_direct_suspend_and_shell_handoff_wait_for_callback() {
let (mut fw, mut platform, task) = load_lifecycle("RET", "RET");
fw.os.lifecycle().suspend_task(task).unwrap();
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground));
fw.tick(&InputSignals::default(), &mut platform);
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
assert!(fw.resume_resident_game_from_home());
fw.tick(&InputSignals::default(), &mut platform);
let shell = fw.os.sessions().try_create_native_shell_task(99, "Tools").unwrap();
assert_eq!(fw.os.lifecycle().foreground_owner(), ForegroundOwner::Game(task));
fw.tick(&InputSignals::default(), &mut platform);
assert_eq!(fw.os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
}
#[test]
fn lifecycle_debugger_retains_budget_and_steps_without_game_frames() {
let (mut fw, mut platform, task) = load_lifecycle("PUSH_I32 7\nSET_GLOBAL 0\nRET", "RET");
fw.os.lifecycle().suspend_task(task).unwrap();
let offset = assemble("FRAME_SYNC\nJMP 0").unwrap().len();
fw.os.vm().insert_active_breakpoint(offset);
fw.tick(&InputSignals::default(), &mut platform);
assert!(fw.os.vm().paused());
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground));
let remaining =
fw.os.sessions().vm_session_for_task(task).unwrap().vm.lifecycle_remaining_cycles();
fw.tick(&InputSignals::default(), &mut platform);
assert_eq!(
fw.os.sessions().vm_session_for_task(task).unwrap().vm.lifecycle_remaining_cycles(),
remaining
);
for _ in 0..3 {
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
}
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
}
#[test]
fn lifecycle_faults_exhaustion_and_halt_never_resume_gameplay() {
for body in ["FRAME_SYNC\nRET", "JMP 0", "HALT"] {
let (mut fw, mut platform, task) = load_lifecycle(body, "RET");
fw.os.lifecycle().suspend_task(task).unwrap();
for _ in 0..8 {
fw.tick(&InputSignals::default(), &mut platform);
if fw.os.lifecycle().task_state(task) != Some(TaskState::Foreground) {
break;
}
}
if body == "HALT" {
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Closed));
assert!(matches!(fw.state, FirmwareState::HubHome(_)));
} else {
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Crashed));
let FirmwareState::AppCrashes(step) = &fw.state else { panic!("expected crash") };
assert!(step.report.to_string().contains("BeforePause"));
}
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
}
}
#[test]
fn lifecycle_debugger_hostcalls_use_real_session_handles() {
use prometeu_bytecode::registry::LifecycleRole;
let main = assemble("FRAME_SYNC\nJMP 0").unwrap();
let mut program = TestProgram::single(main, int64_signature(0, 0), 0, 8);
let hook =
assemble("PUSH_CONST 0\nHOSTCALL 0\nPOP_N 1\nPUSH_I32 42\nHOSTCALL 1\nRET").unwrap();
program
.const_pool
.push(prometeu_bytecode::model::ConstantPoolEntry::String("/missing".into()));
program.syscalls.push(SyscallDecl {
module: "fs".into(),
name: "open".into(),
version: 1,
arg_slots: 1,
ret_slots: 1,
});
program.functions.push(FunctionDecl {
lifecycle_role: LifecycleRole::BeforePause,
code_offset: program.code.len() as u32,
code_len: hook.len() as u32,
max_stack_slots: 8,
..Default::default()
});
program.code.extend(hook);
program.syscalls.push(SyscallDecl {
module: "fs".into(),
name: "close".into(),
version: 1,
arg_slots: 1,
ret_slots: 0,
});
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.capabilities = caps::FS;
cartridge.program = program.serialize();
let mut fw = Firmware::new(None);
let mut platform = TestPlatform::new();
fw.load_cartridge(cartridge);
fw.tick(&InputSignals::default(), &mut platform);
let task = fw.os.lifecycle().resident_game_task().unwrap();
fw.os
.sessions()
.vm_session_for_task_mut(task)
.unwrap()
.open_files
.insert(42, "/save".into());
fw.os.lifecycle().suspend_task(task).unwrap();
fw.os.vm().set_paused(true);
assert_eq!(
fw.os.sessions().vm_session_for_task(task).unwrap().fs_state,
prometeu_system::fs::FsState::Unmounted
);
// fs.open returns an ordinary error value on this unmounted session.
for _ in 0..6 {
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
}
assert!(fw.os.sessions().vm_session_for_task(task).unwrap().open_files.is_empty());
let pc = fw.os.vm().active_pc();
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
assert_eq!(fw.os.vm().active_pc(), pc);
assert!(fw.os.vm().tick_session(task, &InputSignals::default(), &mut platform).is_none());
assert_eq!(fw.os.vm().active_pc(), pc);
fw.tick(&InputSignals::default(), &mut platform);
assert!(matches!(fw.state, FirmwareState::HubHome(_)));
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
}
#[test]
fn lifecycle_resume_failure_blocks_gameplay_and_conflicting_pause_request() {
let (mut fw, mut platform, task) = load_lifecycle("RET", "FRAME_SYNC\nRET");
fw.os.lifecycle().suspend_task(task).unwrap();
fw.tick(&InputSignals::default(), &mut platform);
assert!(fw.resume_resident_game_from_home());
assert!(fw.os.lifecycle().request_home_from_game(task).is_err());
assert!(fw.os.lifecycle().suspend_task(task).is_err());
fw.tick(&InputSignals::default(), &mut platform);
let FirmwareState::AppCrashes(step) = &fw.state else { panic!("expected failure") };
assert!(step.report.to_string().contains("BeforeResume"));
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
}
#[test]
fn lifecycle_roles_are_independently_optional() {
for (pause, resume) in [("", "RET"), ("RET", "")] {
let (mut fw, mut platform, task) = load_lifecycle(pause, resume);
fw.request_home_from_host();
for _ in 0..2 {
fw.tick(&InputSignals::default(), &mut platform);
}
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
assert!(fw.resume_resident_game_from_home());
fw.tick(&InputSignals::default(), &mut platform);
assert_eq!(
fw.os.lifecycle().resident_game().unwrap().state,
ResidentGameState::Foreground
);
}
}
#[test]
fn memory_only_admission_runs_typed_guest_boot_and_warns_before_discard() {
for debug in [false, true] {
use prometeu_bytecode::{
load_limits::LoadBudget,
model::{ConstantPoolEntry, SyscallDecl},
registry::{
LifecycleRole, NamedType, Registry, RegistryDeclarations, Signature, TypeDecl,
TypeId, TypeKind,
},
registry_codec::PbxModule,
};
let boot = assemble("HOSTCALL 0\nPOP_N 1\nFRAME_SYNC\nJMP 12").unwrap();
let hook=assemble("PUSH_I64 560\nARRAY_NEW 9\nSET_GLOBAL 0\nGET_LOCAL 0\nPUSH_CONST 0\nPUSH_I32 1\nPUSH_I32 1\nPUSH_I32 1\nGET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 560\nHOSTCALL 1\nPOP_N 1\nGET_LOCAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 560\nHOSTCALL 2\nPOP_N 2\nGET_LOCAL 0\nPUSH_I32 0\nHOSTCALL 3\nPOP_N 2\nPUSH_I32 0\nRET").unwrap();
let mut code = boot.clone();
code.extend(&hook);
let mut types = prometeu_test_support::program::scalar_catalog();
types.push(TypeDecl { name: None, kind: TypeKind::Array(TypeId(1)) });
let registry = Registry::resolve(
RegistryDeclarations {
types,
functions: vec![
FunctionDecl {
code_len: boot.len() as u32,
max_stack_slots: 16,
..Default::default()
},
FunctionDecl {
lifecycle_role: LifecycleRole::MemcardBoot,
code_offset: boot.len() as u32,
code_len: hook.len() as u32,
max_stack_slots: 16,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![TypeId(1)],
},
..Default::default()
},
],
implementations: vec![],
},
code.len(),
&mut LoadBudget::new(Default::default()),
)
.unwrap();
let syscalls = [
("bootstrap", 0, 1),
("presentation", 8, 1),
("slot_write", 6, 2),
("slot_commit", 2, 2),
]
.map(|(name, arg_slots, ret_slots)| SyscallDecl {
module: "mem".into(),
name: name.into(),
version: 1,
arg_slots,
ret_slots,
});
let constants = [ConstantPoolEntry::String("Guest save".into())];
let program = PbxModule {
registry: &registry,
code: &code,
constants: &constants,
debug: None,
exports: &[],
syscalls: &syscalls,
}
.serialize(&mut LoadBudget::new(Default::default()))
.unwrap();
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.program = program;
cartridge.memcard_slots = Some(1);
cartridge.capabilities = prometeu_hal::syscalls::caps::MEMCARD;
let mut firmware = Firmware::new(None);
let mut platform = TestPlatform::new();
firmware.load_cartridge(cartridge);
firmware.tick(&InputSignals::default(), &mut platform);
assert!(matches!(firmware.state, FirmwareState::LoadCartridge(_)));
firmware.tick(&InputSignals { x_signal: true, ..Default::default() }, &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
if debug {
firmware.os.vm().set_paused(true);
for _ in 0..80 {
assert!(firmware.os.vm().debug_step_active_session(&mut platform).is_none());
if !firmware.os.memcard().session.is_boot_active() {
break;
}
}
assert!(!firmware.os.memcard().session.is_boot_active());
firmware.os.vm().set_paused(false);
}
for _ in 0..4 {
firmware.tick(&InputSignals::default(), &mut platform);
}
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
let session = &mut firmware.os.memcard().session;
let context = session.context();
assert_eq!(session.mode(), Some(prometeu_system::memcard::session::Mode::MemoryOnly));
assert_eq!(session.presentation(context).unwrap().unwrap().title, "Guest save");
assert_eq!(session.descriptor(context, 0).unwrap().1, 560);
assert!(session.unsaved());
firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform);
firmware.change_state(
FirmwareState::ConfirmDiscard(
super::super::firmware_state::ConfirmDiscardStep::new(None),
),
&InputSignals::default(),
&mut platform,
);
firmware.tick(&InputSignals::default(), &mut platform);
firmware.tick(&InputSignals { b_signal: true, ..Default::default() }, &mut platform);
assert!(firmware.os.memcard().session.unsaved());
firmware.change_state(
FirmwareState::ConfirmDiscard(
super::super::firmware_state::ConfirmDiscardStep::new(None),
),
&InputSignals::default(),
&mut platform,
);
firmware.tick(&InputSignals::default(), &mut platform);
firmware.tick(&InputSignals { a_signal: true, ..Default::default() }, &mut platform);
assert_eq!(firmware.os.memcard().session.mode(), None);
}
}
}
@@ -1,3 +1,4 @@
pub use crate::firmware::firmware_step_confirm_discard::ConfirmDiscardStep;
pub use crate::firmware::firmware_step_crash_screen::AppCrashesStep;
pub use crate::firmware::firmware_step_game_running::GameRunningStep;
pub use crate::firmware::firmware_step_hub_home::HubHomeStep;
@@ -13,8 +14,11 @@ pub enum FirmwareState {
SplashScreen(SplashScreenStep),
LaunchHub(LaunchHubStep),
HubHome(HubHomeStep),
ConfirmDiscard(ConfirmDiscardStep),
LoadCartridge(LoadCartridgeStep),
ResumeResidentGame,
MemoryIoFault,
MemoryCardRemoved(super::firmware_step_confirm_discard::MemoryCardRemovedStep),
GameRunning(GameRunningStep),
ShellRunning(ShellRunningStep),
AppCrashes(AppCrashesStep),
@@ -0,0 +1,101 @@
use super::{
firmware_state::{FirmwareState, HubHomeStep, LoadCartridgeStep},
prometeu_context::PrometeuContext,
resident_game_termination,
};
use prometeu_hal::{
FrameId, GfxUiCommand, RenderSubmission, ShellUiFramePacket, cartridge::Cartridge, color::Color,
};
/// Player-owned exit decision. It never starts a save implicitly.
#[derive(Debug, Clone)]
pub struct ConfirmDiscardStep {
next: Option<Cartridge>,
released: bool,
}
impl ConfirmDiscardStep {
pub fn new(next: Option<Cartridge>) -> Self {
Self { next, released: false }
}
pub fn on_enter(&mut self, _ctx: &mut PrometeuContext) {}
pub fn on_exit(&mut self, _ctx: &mut PrometeuContext) {}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
let lines = [
"Unsaved progress",
"Leaving this game will discard RAM saves.",
"A: Discard and leave",
"B: Return to Home without leaving the game",
];
let mut commands = vec![GfxUiCommand::Clear { color: Color::BLACK }];
commands.extend(lines.into_iter().enumerate().map(|(i, text)| GfxUiCommand::DrawText {
x: 8,
y: 8 + i as i32 * 20,
text: text.into(),
color: Color::WHITE,
}));
let _ = ctx.platform.render_submission_sink().submit_render_submission(
RenderSubmission::shell_ui(FrameId::ZERO, ShellUiFramePacket::new(commands)),
);
if !ctx.signals.a_signal && !ctx.signals.b_signal {
self.released = true;
}
if self.released && ctx.signals.b_signal {
return Some(FirmwareState::HubHome(HubHomeStep));
}
if self.released && ctx.signals.a_signal {
if resident_game_termination::terminate_resident_game(ctx.os, ctx.platform, true)
.is_err()
{
return None;
}
return Some(match self.next.take() {
Some(card) => {
FirmwareState::LoadCartridge(LoadCartridgeStep::new_game_switch(card))
}
None => FirmwareState::HubHome(HubHomeStep),
});
}
None
}
}
#[derive(Debug, Clone, Default)]
pub struct MemoryCardRemovedStep {
released: bool,
}
impl MemoryCardRemovedStep {
pub fn on_enter(&mut self, _ctx: &mut PrometeuContext) {}
pub fn on_exit(&mut self, _ctx: &mut PrometeuContext) {}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
if !ctx.os.memcard().session.removal_pending() {
return Some(FirmwareState::HubHome(HubHomeStep));
}
let lines = [
"Memory card is unavailable.",
"Progress remains in memory.",
"Reinsert a card through the host, or choose:",
"A: Continue without saving to disk",
"B: Leave the game",
];
let mut commands = vec![GfxUiCommand::Clear { color: Color::BLACK }];
commands.extend(lines.into_iter().enumerate().map(|(i, text)| GfxUiCommand::DrawText {
x: 8,
y: 8 + i as i32 * 20,
text: text.into(),
color: Color::WHITE,
}));
let _ = ctx.platform.render_submission_sink().submit_render_submission(
RenderSubmission::shell_ui(FrameId::ZERO, ShellUiFramePacket::new(commands)),
);
if !ctx.signals.a_signal && !ctx.signals.b_signal {
self.released = true;
}
if self.released && ctx.signals.a_signal && ctx.os.detach_memcard().is_ok() {
return Some(FirmwareState::ResumeResidentGame);
}
if self.released && ctx.signals.b_signal {
return Some(FirmwareState::ConfirmDiscard(ConfirmDiscardStep::new(None)));
}
None
}
}
@@ -23,7 +23,21 @@ impl AppCrashesStep {
// Update peripherals for input on the crash screen
ctx.platform.input_mut().pad_mut().begin_frame(ctx.signals);
let packet = ShellUiFramePacket::new(vec![GfxUiCommand::Clear { color: Color::RED }]);
let mut commands = vec![GfxUiCommand::Clear { color: Color::RED }];
if let CrashReport::VmPanic { message, .. } = &self.report
&& message.starts_with("Memcard")
{
let text: Vec<char> = message.chars().take(240).collect();
commands.extend(text.chunks(48).enumerate().map(|(line, chars)| {
GfxUiCommand::DrawText {
x: 8,
y: 8 + line as i32 * 20,
text: chars.iter().collect(),
color: Color::WHITE,
}
}));
}
let packet = ShellUiFramePacket::new(commands);
ctx.platform
.render_submission_sink()
.submit_render_submission(RenderSubmission::shell_ui(FrameId::ZERO, packet))
@@ -55,6 +69,7 @@ mod tests {
message: "type mismatch".into(),
pc: 0x44,
span: None,
resource: None,
},
},
};
@@ -27,6 +27,15 @@ impl GameRunningStep {
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
};
if matches!(task_state, TaskState::Suspended | TaskState::Closed) {
ctx.os.vm().transition_render_owner(AppMode::Shell, 0);
return Some(match ctx.os.lifecycle().foreground_owner() {
prometeu_system::ForegroundOwner::Shell(task_id) => FirmwareState::ShellRunning(
crate::firmware::firmware_state::ShellRunningStep::new(task_id),
),
_ => FirmwareState::HubHome(HubHomeStep),
});
}
if task_state != TaskState::Foreground {
// TODO: is it panic?
let report = CrashReport::VmPanic {
@@ -56,6 +56,16 @@ impl HubHomeStep {
Some(SystemProfileAction::LaunchGame { target }) => {
match CartridgeLoader::load(&target.path) {
Ok(cartridge) => {
if ctx.os.lifecycle().resident_game_task().is_none()
&& ctx.os.memcard().session.mode().is_some()
{
if ctx.os.memcard().session.unsaved() {
return Some(FirmwareState::ConfirmDiscard(
super::firmware_state::ConfirmDiscardStep::new(Some(cartridge)),
));
}
ctx.os.memcard().session.end_session();
}
if cartridge.app_mode == AppMode::Game
&& let Some(resident_task_id) = ctx.os.lifecycle().resident_game_task()
{
@@ -70,6 +80,11 @@ impl HubHomeStep {
return Some(FirmwareState::ResumeResidentGame);
}
if ctx.os.memcard().session.unsaved() {
return Some(FirmwareState::ConfirmDiscard(
super::firmware_state::ConfirmDiscardStep::new(Some(cartridge)),
));
}
if let Err(error) = resident_game_termination::terminate_resident_game(
ctx.os,
ctx.platform,
@@ -107,6 +122,12 @@ impl HubHomeStep {
}
}
Some(SystemProfileAction::KillResidentGame) => {
if ctx.os.memcard().session.unsaved() {
return Some(FirmwareState::ConfirmDiscard(
super::firmware_state::ConfirmDiscardStep::new(None),
));
}
if let Err(error) =
resident_game_termination::terminate_resident_game(ctx.os, ctx.platform, true)
{
@@ -15,6 +15,10 @@ use prometeu_system::windows::WindowOwner;
pub struct LoadCartridgeStep {
pub cartridge: Cartridge,
init_error: Option<CrashReport>,
awaiting_memcard: bool,
preparing_memcard: bool,
input_released: bool,
memcard_message: String,
loaded_task_id: Option<prometeu_system::task::TaskId>,
loaded_app_mode: Option<AppMode>,
failure_recovery: LoadCartridgeFailureRecovery,
@@ -31,12 +35,20 @@ impl LoadCartridgeStep {
Self {
cartridge,
init_error: None,
awaiting_memcard: false,
preparing_memcard: false,
input_released: false,
memcard_message: String::new(),
loaded_task_id: None,
loaded_app_mode: None,
failure_recovery: LoadCartridgeFailureRecovery::AppCrash,
}
}
pub fn needs_memcard_choice(&self) -> bool {
self.awaiting_memcard && !self.preparing_memcard
}
pub fn new_game_switch(cartridge: Cartridge) -> Self {
Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) }
}
@@ -51,6 +63,15 @@ impl LoadCartridgeStep {
ctx.platform.game2d_frame_composer().unbind_scene();
if self.cartridge.app_mode == AppMode::Game && self.cartridge.memcard_slots.is_some() {
self.awaiting_memcard = true;
ctx.os.vm().transition_render_owner(AppMode::Shell, 0);
return;
}
self.load(ctx);
}
fn load(&mut self, ctx: &mut PrometeuContext) {
// Initialize Asset Manager
ctx.platform.assets_mut().initialize_for_cartridge(
self.cartridge.asset_table.clone(),
@@ -70,6 +91,58 @@ impl LoadCartridgeStep {
}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
if self.awaiting_memcard {
use prometeu_system::memcard::admission::{Choice, PreparationState};
if self.preparing_memcard {
match ctx.os.memcard().admission.state {
PreparationState::Ready => {
self.awaiting_memcard = false;
self.preparing_memcard = false;
self.load(ctx);
}
PreparationState::Failed(error) => {
self.memcard_message = Self::preparation_message(error);
self.preparing_memcard = false;
}
_ => {}
}
}
if self.awaiting_memcard {
let pressed = ctx.signals.a_signal
|| ctx.signals.b_signal
|| ctx.signals.x_signal
|| ctx.signals.y_signal;
if !pressed {
self.input_released = true;
}
if self.input_released && pressed && !self.preparing_memcard {
self.input_released = false;
if ctx.signals.b_signal {
return Some(FirmwareState::HubHome(HubHomeStep));
}
let choice = if ctx.signals.a_signal {
Choice::Persistent
} else if ctx.signals.x_signal {
Choice::MemoryFresh
} else {
Choice::MemoryExisting
};
let created_at = ctx.platform.wall_clock().utc_unix_seconds();
match ctx.os.memcard().choose_for_game(
self.cartridge.app_id,
self.cartridge.memcard_slots.unwrap() as usize,
choice,
created_at,
) {
Ok(()) => self.preparing_memcard = true,
Err(error) => self.memcard_message = Self::preparation_message(error),
}
}
self.draw_memcard(ctx);
return None;
}
}
if let Some(report) = self.init_error.take() {
if self.failure_recovery == LoadCartridgeFailureRecovery::ReturnToHub {
if self.cartridge.app_mode == AppMode::Game
@@ -106,6 +179,18 @@ impl LoadCartridgeStep {
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
}
match ctx.platform.assets().preloads_ready() {
Ok(false) => return None,
Err(error) => {
return Some(FirmwareState::AppCrashes(AppCrashesStep {
report: CrashReport::VmPanic {
message: format!("Cartridge preload failed: {error:?}"),
pc: None,
},
}));
}
Ok(true) => {}
}
let Some(task_id) = self.loaded_task_id.take() else {
let report = CrashReport::VmPanic {
message: format!(
@@ -131,5 +216,67 @@ impl LoadCartridgeStep {
Some(FirmwareState::GameRunning(GameRunningStep::new(task_id)))
}
fn preparation_message(error: prometeu_system::memcard::image::Error) -> String {
use prometeu_system::memcard::image::Error;
match error {
Error::NoSpace => "This memory card has no room for this game.".into(),
Error::Corrupt => "The memory card failed its integrity checks.".into(),
Error::ReadOnly => "This memory card cannot accept saves.".into(),
Error::OutOfMemory => "There is not enough memory to start this game.".into(),
Error::Busy => "The memory card is still busy. Please wait.".into(),
Error::InvalidState => "No usable memory card or existing save is available.".into(),
_ => format!("Memory card unavailable: {error:?}"),
}
}
fn draw_memcard(&self, ctx: &mut PrometeuContext) {
use prometeu_hal::{FrameId, GfxUiCommand, RenderSubmission, ShellUiFramePacket};
let installed = ctx.os.memcard().card_installed();
let existing = ctx.os.memcard().card_has_game(self.cartridge.app_id);
let mut lines = vec!["Save memory".to_string(), self.cartridge.title.clone()];
if let Some((recovered, degraded, blocked)) = ctx.os.memcard().installed_health() {
if recovered {
lines.push("Recovered an older save after an integrity failure.".into());
}
if degraded {
lines.push("Memory card degraded: some blocks are excluded.".into());
}
if blocked {
lines.push("Disk saving is unavailable on this card.".into());
}
}
if let prometeu_system::memcard::admission::PreparationState::Failed(error) =
ctx.os.memcard().admission.state
{
lines.push(Self::preparation_message(error));
}
if self.preparing_memcard {
lines.push("Preparing save memory...".into());
} else {
lines.push(
if installed { "A: Use installed memory card" } else { "No memory card installed" }
.into(),
);
lines.push("X: Start fresh without saving to disk".into());
if existing {
lines.push("Y: Load saves, then play without disk saving".into());
}
lines.push("B: Return to Home".into());
}
if !self.memcard_message.is_empty() {
lines.push(self.memcard_message.clone());
}
let mut commands = vec![GfxUiCommand::Clear { color: Color::BLACK }];
commands.extend(lines.into_iter().enumerate().map(|(i, text)| GfxUiCommand::DrawText {
x: 8,
y: 8 + i as i32 * 20,
text,
color: Color::WHITE,
}));
let _ = ctx.platform.render_submission_sink().submit_render_submission(
RenderSubmission::shell_ui(FrameId::ZERO, ShellUiFramePacket::new(commands)),
);
}
pub fn on_exit(&mut self, _ctx: &mut PrometeuContext) {}
}
@@ -15,6 +15,8 @@ impl ResetStep {
let _ = ctx.os.lifecycle().terminate_resident_game();
ctx.os.sessions().clear_vm_sessions();
ctx.os.vm().reset_global_runtime_state();
ctx.platform.audio_mut().reset();
ctx.platform.audio_mut().set_session(None);
}
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
@@ -18,3 +18,5 @@ pub use boot_target::BootTarget;
pub use firmware::Firmware;
pub use firmware_state::FirmwareState;
pub use prometeu_context::PrometeuContext;
pub(crate) mod firmware_step_confirm_discard;
@@ -16,6 +16,7 @@ pub(crate) fn terminate_resident_game(
log_manual_hub_kill: bool,
) -> Result<ResidentGameTerminationOutcome, LifecycleError> {
let Some(task_id) = os.lifecycle().resident_game_task() else {
os.memcard().session.end_session();
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
};
@@ -30,6 +31,8 @@ pub(crate) fn terminate_resident_game(
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
};
os.memcard().session.end_session();
platform.audio_mut().set_session(None);
os.vm().transition_render_owner(AppMode::Shell, 0);
platform.game2d_frame_composer().unbind_scene();
platform.assets_mut().shutdown();
@@ -6,12 +6,25 @@ use crate::asset::{
use crate::cartridge::AssetsPayloadSource;
pub trait AssetBridge {
/// Bind before cartridge preload/loading. Hosts supporting memcard must use
/// this same lane for assets; an unsupported bridge refuses the fast profile.
fn bind_background_work(
&mut self,
_lane: std::sync::Arc<dyn crate::background_work::BackgroundWork>,
) -> bool {
false
}
fn initialize_for_cartridge(
&self,
assets: Vec<AssetEntry>,
preload: Vec<PreloadEntry>,
assets_data: AssetsPayloadSource,
);
/// Admission waits until all preloads are installed. Failure blocks guest boot.
fn preloads_ready(&self) -> Result<bool, AssetLoadError> {
Ok(true)
}
fn load(&self, asset_id: AssetId, slot_index: usize) -> Result<HandleId, AssetLoadError>;
fn status(&self, handle: HandleId) -> LoadStatus;
fn commit(&self, handle: HandleId) -> AssetOpStatus;
@@ -17,6 +17,7 @@ pub enum AudioOpStatus {
AssetNotFound = 4,
NoEffect = 5,
BankInvalid = 6,
CommandLimit = 7,
}
pub trait AudioBridge {
@@ -43,10 +44,22 @@ pub trait AudioBridge {
priority: u8,
loop_mode: LoopMode,
) -> AudioOpStatus;
fn stop(&mut self, voice_id: usize);
fn set_volume(&mut self, voice_id: usize, volume: u8);
fn set_pan(&mut self, voice_id: usize, pan: u8);
fn set_pitch(&mut self, voice_id: usize, pitch: f64);
fn is_playing(&self, voice_id: usize) -> bool;
fn clear_commands(&mut self);
fn stop(&mut self, voice_id: usize) -> AudioOpStatus;
fn set_volume(&mut self, voice_id: usize, volume: u8) -> AudioOpStatus;
fn set_pan(&mut self, voice_id: usize, pan: u8) -> AudioOpStatus;
fn set_pitch(&mut self, voice_id: usize, pitch: f64) -> AudioOpStatus;
/// Pending publication must be consumed before starting another guest frame.
fn ready(&self) -> bool;
fn begin_frame(&mut self);
fn finish_frame(&mut self);
fn abort_frame(&mut self);
/// Lifecycle has independent bounded staging/publication, even with a pending frame.
fn lifecycle_ready(&self) -> bool;
fn begin_lifecycle(&mut self);
/// Success publishes the interrupted frame prefix before callback commands,
/// without replenishing frame quota. Failure cancels both unpublished parts.
fn finish_lifecycle(&mut self, success: bool);
fn set_session(&mut self, session: Option<u32>);
fn reset(&mut self);
fn set_paused(&mut self, paused: bool);
}
@@ -0,0 +1,13 @@
//! Portable submission seam for host-owned cooperative IO execution.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WorkStep {
Yield,
Complete,
Failed,
}
pub type AssetWork = Box<dyn FnMut(bool) -> WorkStep + Send + 'static>;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct WorkUnavailable;
pub trait BackgroundWork: Send + Sync {
fn submit_asset(&self, work: AssetWork) -> Result<(), WorkUnavailable>;
}
+46 -4
View File
@@ -3,7 +3,7 @@ use crate::asset::{AssetEntry, PreloadEntry};
use crate::syscalls::CapFlags;
use serde::{Deserialize, Serialize};
use std::fs::File;
use std::io::{self, Cursor, Read, Seek, SeekFrom};
use std::io::{self, Read, Seek, SeekFrom};
use std::path::PathBuf;
use std::sync::Arc;
@@ -18,6 +18,7 @@ pub struct Cartridge {
pub app_version: String,
pub app_mode: AppMode,
pub capabilities: CapFlags,
pub memcard_slots: Option<u8>,
pub program: Vec<u8>,
pub assets: AssetsPayloadSource,
pub asset_table: Vec<AssetEntry>,
@@ -31,6 +32,7 @@ pub struct CartridgeDTO {
pub app_version: String,
pub app_mode: AppMode,
pub capabilities: CapFlags,
pub memcard_slots: Option<u8>,
pub program: Vec<u8>,
pub assets: AssetsPayloadSource,
pub asset_table: Vec<AssetEntry>,
@@ -45,6 +47,7 @@ impl From<CartridgeDTO> for Cartridge {
app_version: dto.app_version,
app_mode: dto.app_mode,
capabilities: dto.capabilities,
memcard_slots: dto.memcard_slots,
program: dto.program,
assets: dto.assets,
asset_table: dto.asset_table,
@@ -125,8 +128,12 @@ impl AssetsPayloadSlice {
pub fn open_reader(&self) -> io::Result<AssetsPayloadReader> {
match self {
Self::Memory { bytes, start, len } => {
let data = Arc::<[u8]>::from(bytes[*start..*start + *len].to_vec());
Ok(AssetsPayloadReader::Memory(Cursor::new(data)))
Ok(AssetsPayloadReader::Memory(MemorySliceReader {
bytes: Arc::clone(bytes),
start: *start,
len: *len,
position: 0,
}))
}
Self::File { source, offset, size } => {
let mut file = File::open(&source.path)?;
@@ -151,7 +158,7 @@ impl AssetsPayloadSlice {
}
pub enum AssetsPayloadReader {
Memory(Cursor<Arc<[u8]>>),
Memory(MemorySliceReader),
File(FileSliceReader),
}
@@ -173,6 +180,37 @@ impl Seek for AssetsPayloadReader {
}
}
pub struct MemorySliceReader {
bytes: Arc<[u8]>,
start: usize,
len: usize,
position: usize,
}
impl Read for MemorySliceReader {
fn read(&mut self, target: &mut [u8]) -> io::Result<usize> {
let n = target.len().min(self.len.saturating_sub(self.position));
target[..n].copy_from_slice(
&self.bytes[self.start + self.position..self.start + self.position + n],
);
self.position += n;
Ok(n)
}
}
impl Seek for MemorySliceReader {
fn seek(&mut self, pos: SeekFrom) -> io::Result<u64> {
let next = match pos {
SeekFrom::Start(n) => n as i128,
SeekFrom::Current(n) => self.position as i128 + n as i128,
SeekFrom::End(n) => self.len as i128 + n as i128,
};
if next < 0 || next > self.len as i128 {
return Err(invalid_input("slice seek out of bounds"));
}
self.position = next as usize;
Ok(self.position as u64)
}
}
pub struct FileSliceReader {
file: File,
start: u64,
@@ -278,6 +316,7 @@ pub enum CartridgeError {
MissingProgram,
MissingAssets,
IoError,
ProgramLoadFailed(prometeu_bytecode::load_limits::LoadFailure),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize, Serialize)]
@@ -291,6 +330,7 @@ pub enum Capability {
Gfxui,
Audio,
Fs,
Memcard,
Log,
Asset,
Bank,
@@ -307,4 +347,6 @@ pub struct CartridgeManifest {
pub app_mode: AppMode,
#[serde(default)]
pub capabilities: Vec<Capability>,
#[serde(default)]
pub memcard_slots: Option<u8>,
}
@@ -5,6 +5,9 @@ use crate::cartridge::{
CartridgeManifest,
};
use crate::syscalls::{CapFlags, caps};
use prometeu_bytecode::load_limits::{
LoadBudget, LoadFailure, LoadLimits, LoadReason, LoadResource,
};
use std::collections::HashSet;
use std::fs;
use std::io::{Read, Seek, SeekFrom};
@@ -52,13 +55,20 @@ impl DirectoryCartridgeLoader {
}
let capabilities = normalize_capabilities(&manifest.capabilities)?;
if ((capabilities & caps::MEMCARD) != 0) != manifest.memcard_slots.is_some()
|| manifest.memcard_slots.is_some_and(|n| !(1..=64).contains(&n))
{
return Err(CartridgeError::InvalidManifest);
}
let program_path = path.join("program.pbx");
if !program_path.exists() {
return Err(CartridgeError::MissingProgram);
}
let program = fs::read(program_path).map_err(|_| CartridgeError::IoError)?;
let mut program_file = fs::File::open(program_path).map_err(|_| CartridgeError::IoError)?;
let program_len = program_file.metadata().map_err(|_| CartridgeError::IoError)?.len();
let program = read_program(&mut program_file, program_len, LoadLimits::default())?;
let assets_pa_path = path.join("assets.pa");
let (assets, asset_table, preload) = if assets_pa_path.exists() {
@@ -86,6 +96,7 @@ impl DirectoryCartridgeLoader {
app_version: manifest.app_version,
app_mode: manifest.app_mode,
capabilities,
memcard_slots: manifest.memcard_slots,
program,
assets,
asset_table,
@@ -98,6 +109,59 @@ impl DirectoryCartridgeLoader {
pub struct PackedCartridgeLoader;
/// Admit the PBX input separately from parsing scratch. Metadata rejects an
/// oversized file before reservation; bounded reads also cover file growth.
fn read_program(
reader: &mut impl Read,
size_hint: u64,
limits: LoadLimits,
) -> Result<Vec<u8>, CartridgeError> {
let budget = LoadBudget::new(limits);
let limit = budget.limit(LoadResource::PbxBytes);
budget.check(LoadResource::PbxBytes, size_hint).map_err(CartridgeError::ProgramLoadFailed)?;
let resource_error = |reason, requested| {
let mut error = LoadFailure::resource(LoadResource::PbxBytes, requested, limit);
error.reason = reason;
CartridgeError::ProgramLoadFailed(error)
};
let mut out = Vec::<u8>::new();
let initial =
usize::try_from(size_hint).map_err(|_| resource_error(LoadReason::Overflow, size_hint))?;
out.try_reserve_exact(initial)
.map_err(|_| resource_error(LoadReason::Allocation, size_hint))?;
budget
.check(LoadResource::PbxBytes, out.capacity() as u64)
.map_err(CartridgeError::ProgramLoadFailed)?;
let mut chunk = [0u8; 8192];
loop {
// At the ceiling inspect one extra byte without growing the input.
let remaining = limit - out.len() as u64;
let read_len = remaining.min(chunk.len() as u64).max(1) as usize;
let count = match reader.read(&mut chunk[..read_len]) {
Ok(count) => count,
Err(e) if e.kind() == std::io::ErrorKind::Interrupted => continue,
Err(_) => return Err(CartridgeError::IoError),
};
if count == 0 {
return Ok(out);
}
let requested = (out.len() as u64)
.checked_add(count as u64)
.ok_or_else(|| resource_error(LoadReason::Overflow, u64::MAX))?;
budget
.check(LoadResource::PbxBytes, requested)
.map_err(CartridgeError::ProgramLoadFailed)?;
// Reserve exact growth rather than allowing Vec's geometric growth to
// exceed admission. Existing spare capacity is reused without billing twice.
out.try_reserve_exact(count)
.map_err(|_| resource_error(LoadReason::Allocation, requested))?;
budget
.check(LoadResource::PbxBytes, out.capacity() as u64)
.map_err(CartridgeError::ProgramLoadFailed)?;
out.extend_from_slice(&chunk[..count]);
}
}
impl PackedCartridgeLoader {
pub fn load(_path: &Path) -> Result<Cartridge, CartridgeError> {
Err(CartridgeError::InvalidFormat)
@@ -122,6 +186,7 @@ fn normalize_capabilities(capabilities: &[Capability]) -> Result<CapFlags, Cartr
Capability::Gfxui => caps::GFXUI,
Capability::Audio => caps::AUDIO,
Capability::Fs => caps::FS,
Capability::Memcard => caps::MEMCARD,
Capability::Log => caps::LOG,
Capability::Asset => caps::ASSET,
Capability::Bank => caps::BANK,
@@ -204,6 +269,7 @@ mod tests {
use crate::asset::{AssetCodec, AssetEntry, BankType, PreloadEntry};
use crate::cartridge::{ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude};
use crate::glyph_bank::GLYPH_BANK_MAX_PALETTE_COUNT_V1;
use prometeu_bytecode::load_limits::LoadCode;
use serde_json::json;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
@@ -289,6 +355,76 @@ mod tests {
manifest
}
#[test]
fn program_admission_accepts_exact_limit_and_rejects_growth_after_metadata() {
let limits = LoadLimits { pbx_bytes: 3, ..Default::default() };
for hint in [0, 1, 3] {
assert_eq!(read_program(&mut &b"abc"[..], hint, limits).unwrap(), b"abc");
let error = read_program(&mut &b"abcd"[..], hint, limits).unwrap_err();
let CartridgeError::ProgramLoadFailed(error) = error else {
panic!("typed PBX admission failure expected")
};
assert_eq!((error.code, error.reason), (LoadCode::ResourceLimit, LoadReason::Limit));
assert_eq!(
(error.resource, error.requested, error.limit),
(Some(LoadResource::PbxBytes), Some(4), Some(3))
);
}
}
#[test]
fn program_admission_rejects_oversized_metadata_before_reading() {
struct MustNotRead;
impl Read for MustNotRead {
fn read(&mut self, _: &mut [u8]) -> std::io::Result<usize> {
panic!("must reject before reading")
}
}
let limits = LoadLimits { pbx_bytes: 3, ..Default::default() };
assert!(matches!(
read_program(&mut MustNotRead, 4, limits),
Err(CartridgeError::ProgramLoadFailed(_))
));
}
#[test]
fn program_admission_handles_empty_short_and_interrupted_reads() {
assert!(read_program(&mut &[][..], 0, LoadLimits::default()).unwrap().is_empty());
struct ShortReads {
interrupted: bool,
remaining: &'static [u8],
}
impl Read for ShortReads {
fn read(&mut self, bytes: &mut [u8]) -> std::io::Result<usize> {
if !self.interrupted {
self.interrupted = true;
return Err(std::io::ErrorKind::Interrupted.into());
}
if self.remaining.is_empty() {
return Ok(0);
}
bytes[0] = self.remaining[0];
self.remaining = &self.remaining[1..];
Ok(1)
}
}
let mut reader = ShortReads { interrupted: false, remaining: b"abc" };
assert_eq!(read_program(&mut reader, 2, LoadLimits::default()).unwrap(), b"abc");
}
#[test]
fn directory_loader_rejects_oversized_pbx_with_default_limit() {
let dir = TestCartridgeDir::new(manifest_with_capabilities(None));
let file = fs::OpenOptions::new().write(true).open(dir.path().join("program.pbx")).unwrap();
let limit = LoadLimits::default().pbx_bytes;
file.set_len(limit + 1).unwrap(); // Sparse file; no giant content allocation.
let error = DirectoryCartridgeLoader::load(dir.path()).unwrap_err();
let CartridgeError::ProgramLoadFailed(error) = error else {
panic!("typed PBX admission failure expected")
};
assert_eq!((error.requested, error.limit), (Some(limit + 1), Some(64 * 1_048_576)));
}
#[test]
fn load_without_capabilities_defaults_to_none() {
let dir = TestCartridgeDir::new(manifest_with_capabilities(None));
@@ -318,7 +454,9 @@ mod tests {
#[test]
fn load_with_all_capability_normalizes_to_all_flags() {
let dir = TestCartridgeDir::new(manifest_with_capabilities(Some(vec!["all"])));
let mut manifest = manifest_with_capabilities(Some(vec!["all"]));
manifest["memcard_slots"] = serde_json::json!(1);
let dir = TestCartridgeDir::new(manifest);
dir.write_assets_pa(vec![], vec![], &[]);
let cartridge = DirectoryCartridgeLoader::load(dir.path()).expect("cartridge must load");
@@ -1,4 +1,5 @@
use crate::app_mode::AppMode;
#[cfg(test)]
use prometeu_bytecode::Value;
use serde::{Deserialize, Serialize};
@@ -35,7 +36,7 @@ pub enum DebugResponse {
#[serde(rename = "handshake")]
Handshake { protocol_version: u32, runtime_version: String, cartridge: HandshakeCartridge },
#[serde(rename = "getState")]
GetState { pc: usize, stack_top: Vec<Value>, frame_index: u64, app_id: u32 },
GetState { pc: usize, stack_top: crate::ValueSnapshot, frame_index: u64, app_id: u32 },
#[serde(rename = "breakpoints")]
Breakpoints { pcs: Vec<usize> },
}
@@ -78,6 +79,9 @@ pub enum DebugEvent {
pc: Option<u32>,
trap_code: Option<u32>,
opcode: Option<u16>,
span: Option<prometeu_bytecode::SourceSpan>,
resource: Option<prometeu_bytecode::ResourceFailure>,
init: Option<serde_json::Value>,
},
#[serde(rename = "cert")]
Cert { rule: String, used: u64, limit: u64, frame_index: u64 },
@@ -115,7 +119,8 @@ mod tests {
fn test_get_state_serialization() {
let resp = DebugResponse::GetState {
pc: 42,
stack_top: vec![Value::Int64(10), Value::String("test".into()), Value::Boolean(true)],
stack_top: vec![Value::Int64(10), Value::String("test".into()), Value::Boolean(true)]
.into(),
frame_index: 5,
app_id: 1,
};
@@ -136,6 +141,9 @@ mod tests {
pc: Some(12),
trap_code: Some(4),
opcode: Some(0x70),
span: None,
resource: None,
init: None,
};
let json = serde_json::to_string(&event).unwrap();
+271 -10
View File
@@ -1,27 +1,288 @@
use crate::vm_fault::VmFault;
use prometeu_bytecode::{HeapRef, Value};
use std::sync::Arc;
/// Native producers describe their output before materializing guest content.
/// The VM provides the session allocator; HAL does not own guest quotas.
pub trait GuestStringAllocator {
fn byte_limit(&self) -> u64;
fn build(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault>;
}
/// A bounded, call-scoped Array<Int32> byte carrier. Implementations validate
/// concrete array type, every value and all bounds before exposing mutations.
pub trait GuestByteArrays {
fn validate(&mut self, handle: HeapRef, offset: usize, count: usize) -> Result<(), VmFault>;
fn read(&mut self, handle: HeapRef, offset: usize, target: &mut [u8]) -> Result<(), VmFault>;
fn write(&mut self, handle: HeapRef, offset: usize, bytes: &[u8]) -> Result<(), VmFault>;
}
/// Writes only into result slots reserved by the VM. A native handler cannot
/// grow the operand buffer or exceed its declared result count.
pub struct HostReturn<'a> {
stack: &'a mut Vec<Value>,
remaining: usize,
overflowed: bool,
strings: &'a mut dyn GuestStringAllocator,
failure: Option<VmFault>,
arrays: Option<&'a mut dyn GuestByteArrays>,
}
impl<'a> HostReturn<'a> {
pub fn new(stack: &'a mut Vec<Value>) -> Self {
Self { stack }
fn size_overflow(&mut self) -> VmFault {
let error = VmFault::ResourceLimit(prometeu_bytecode::ResourceFailure {
resource: prometeu_bytecode::RuntimeResource::StringBytes,
reason: prometeu_bytecode::ResourceReason::SizeOverflow,
requested: u64::MAX,
limit: self.strings.byte_limit(),
});
self.failure = Some(error.clone());
error
}
pub fn new(
stack: &'a mut Vec<Value>,
result_slots: usize,
strings: &'a mut dyn GuestStringAllocator,
) -> Self {
Self {
stack,
remaining: result_slots,
overflowed: false,
strings,
failure: None,
arrays: None,
}
}
pub fn with_arrays(mut self, arrays: &'a mut dyn GuestByteArrays) -> Self {
self.arrays = Some(arrays);
self
}
pub fn byte_arrays(&mut self) -> Result<&mut (dyn GuestByteArrays + 'a), VmFault> {
self.arrays.as_deref_mut().ok_or(VmFault::Unavailable)
}
pub fn failure(&self) -> Option<&VmFault> {
self.failure.as_ref()
}
pub fn overflowed(&self) -> bool {
self.overflowed
}
fn admit(&mut self) -> bool {
if self.failure.is_some() {
return false;
}
if self.remaining == 0 || self.stack.len() == self.stack.capacity() {
self.overflowed = true;
false
} else {
self.remaining -= 1;
true
}
}
pub fn push_bool(&mut self, v: bool) {
self.stack.push(Value::Boolean(v));
if self.admit() {
self.stack.push(Value::Boolean(v));
}
}
pub fn push_int(&mut self, v: i64) {
self.stack.push(Value::Int64(v));
if self.admit() {
self.stack.push(Value::Int64(v));
}
}
pub fn push_null(&mut self) {
self.stack.push(Value::Null);
if self.admit() {
self.stack.push(Value::Null);
}
}
pub fn push_gate(&mut self, g: usize) {
// Temporary: cast incoming handle/HeapRef index. Real allocator will provide proper handles.
self.stack.push(Value::HeapRef(HeapRef(g as u32)));
/// Return a handle issued by the current session's heap.
pub fn push_gate(&mut self, handle: HeapRef) {
if self.admit() {
self.stack.push(if handle.is_null() { Value::Null } else { Value::HeapRef(handle) });
}
}
pub fn push_string(&mut self, s: String) {
self.stack.push(Value::string(s));
pub fn push_string(&mut self, text: &str) -> Result<(), VmFault> {
self.push_string_with_len(text.len(), &mut |writer| writer.write_str(text))
}
pub fn push_string_with_len(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<(), VmFault> {
if !self.admit() {
return self.failure.clone().map_or(Ok(()), Err);
}
match self.strings.build(length, writer) {
Ok(content) => {
self.stack.push(Value::String(content));
Ok(())
}
Err(error) => {
self.failure = Some(error.clone());
Err(error)
}
}
}
pub fn push_utf8_lossy(&mut self, bytes: &[u8]) -> Result<(), VmFault> {
let mut length = 0usize;
lossy_chunks(bytes, &mut |part| {
length = length.checked_add(part.len()).ok_or(std::fmt::Error)?;
Ok(())
})
.map_err(|_| self.size_overflow())?;
self.push_string_with_len(length, &mut |writer| {
lossy_chunks(bytes, &mut |part| writer.write_str(part))
})
}
pub fn push_hex(&mut self, bytes: &[u8]) -> Result<(), VmFault> {
const HEX: &[u8; 16] = b"0123456789abcdef";
let length = bytes.len().checked_mul(2).ok_or_else(|| self.size_overflow())?;
self.push_string_with_len(length, &mut |writer| {
for &byte in bytes {
let pair = [HEX[(byte >> 4) as usize], HEX[(byte & 15) as usize]];
writer.write_str(std::str::from_utf8(&pair).expect("ASCII hex"))?;
}
Ok(())
})
}
pub fn push_joined<'s, I: Iterator<Item = &'s str> + Clone>(
&mut self,
parts: I,
separator: &str,
) -> Result<(), VmFault> {
let mut length = 0usize;
for (index, part) in parts.clone().enumerate() {
if index > 0 {
length = length.checked_add(separator.len()).ok_or_else(|| self.size_overflow())?;
}
length = length.checked_add(part.len()).ok_or_else(|| self.size_overflow())?;
}
self.push_string_with_len(length, &mut |writer| {
for (index, part) in parts.clone().enumerate() {
if index > 0 {
writer.write_str(separator)?;
}
writer.write_str(part)?;
}
Ok(())
})
}
}
fn lossy_chunks(
mut bytes: &[u8],
emit: &mut dyn FnMut(&str) -> std::fmt::Result,
) -> std::fmt::Result {
while !bytes.is_empty() {
match std::str::from_utf8(bytes) {
Ok(valid) => {
emit(valid)?;
break;
}
Err(error) => {
let valid = error.valid_up_to();
emit(std::str::from_utf8(&bytes[..valid]).expect("validated prefix"))?;
emit("\u{fffd}")?;
match error.error_len() {
Some(invalid) => bytes = &bytes[valid + invalid..],
None => break,
}
}
}
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
struct RejectStrings;
impl GuestStringAllocator for RejectStrings {
fn byte_limit(&self) -> u64 {
0
}
fn build(
&mut self,
_length: usize,
_writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault> {
panic!("unexpected string allocation")
}
}
#[test]
fn native_results_cannot_grow_the_reserved_buffer_or_exceed_the_signature() {
let mut stack = Vec::with_capacity(8);
let capacity = stack.capacity();
let mut strings = RejectStrings;
let mut ret = HostReturn::new(&mut stack, 1, &mut strings);
ret.push_int(7);
ret.push_int(8);
assert!(ret.overflowed());
assert_eq!(stack, vec![Value::Int64(7)]);
assert_eq!(stack.capacity(), capacity);
let mut empty = Vec::new();
let mut ret = HostReturn::new(&mut empty, 1, &mut strings);
ret.push_null();
assert!(ret.overflowed());
assert!(empty.is_empty());
assert_eq!(empty.capacity(), 0);
}
struct Collect;
impl GuestStringAllocator for Collect {
fn byte_limit(&self) -> u64 {
u64::MAX
}
fn build(
&mut self,
length: usize,
writer: &mut dyn FnMut(&mut dyn std::fmt::Write) -> std::fmt::Result,
) -> Result<Arc<str>, VmFault> {
let mut text = String::new();
writer(&mut text).unwrap();
assert_eq!(text.len(), length);
Ok(Arc::from(text))
}
}
#[test]
fn measured_native_encoding_matches_utf8_lossy_hex_and_join_semantics() {
for bytes in [
b"plain".as_slice(),
"é猫".as_bytes(),
&[0xff, 0xe2, 0x82],
&[0xf0, 0x80, 0x80, 0x80, 0x61, 0xc2, 0xa9],
&[],
] {
let mut stack = Vec::with_capacity(1);
let mut allocator = Collect;
let mut ret = HostReturn::new(&mut stack, 1, &mut allocator);
ret.push_utf8_lossy(bytes).unwrap();
assert_eq!(stack, vec![Value::string(String::from_utf8_lossy(bytes).as_ref())]);
}
for byte in 0..=255u8 {
let bytes = [b'a', byte, b'b', byte];
let mut stack = Vec::with_capacity(1);
let mut allocator = Collect;
HostReturn::new(&mut stack, 1, &mut allocator).push_utf8_lossy(&bytes).unwrap();
assert_eq!(stack, vec![Value::string(String::from_utf8_lossy(&bytes).as_ref())]);
}
let mut stack = Vec::with_capacity(2);
let mut allocator = Collect;
let mut ret = HostReturn::new(&mut stack, 2, &mut allocator);
ret.push_hex(&[0, 0x12, 0xab, 0xff]).unwrap();
ret.push_joined(["", "é", "猫"].into_iter(), ";").unwrap();
assert_eq!(stack, vec![Value::string("0012abff"), Value::string(";é;猫")]);
}
#[test]
fn full_native_result_buffer_does_not_invoke_string_allocator() {
let mut stack = Vec::with_capacity(1);
let mut allocator = RejectStrings;
let mut ret = HostReturn::new(&mut stack, 0, &mut allocator);
ret.push_string("ignored").unwrap();
assert!(ret.overflowed());
assert!(stack.is_empty());
}
}
+6
View File
@@ -2,6 +2,7 @@ pub mod app_mode;
pub mod asset;
pub mod asset_bridge;
pub mod audio_bridge;
pub mod background_work;
pub mod button;
pub mod cartridge;
pub mod cartridge_loader;
@@ -15,6 +16,7 @@ pub mod host_context;
pub mod host_return;
pub mod input_signals;
pub mod log;
pub mod memcard;
pub mod native_helpers;
pub mod native_interface;
pub mod owned_frame;
@@ -36,7 +38,9 @@ pub mod telemetry;
pub mod tile;
pub mod tilemap;
pub mod touch_bridge;
pub mod value_snapshot;
pub mod vm_fault;
pub mod wall_clock;
pub use asset_bridge::AssetBridge;
pub use audio_bridge::{AudioBridge, AudioOpStatus, LoopMode};
@@ -64,3 +68,5 @@ pub use render_worker::{
RenderWorkerBackend, RenderWorkerError, RenderWorkerFrameSink, RenderWorkerTelemetry,
};
pub use touch_bridge::TouchBridge;
pub use value_snapshot::ValueSnapshot;
pub use wall_clock::WallClock;
@@ -0,0 +1,23 @@
//! Host region IO. Logical mapping, checksums and publication belong to the runtime.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemcardIoError {
Unavailable,
ReadOnly,
InvalidRange,
NoSpace,
Unsupported,
IoError,
}
/// Implementations return success only for a complete transfer. Errors may have
/// partial effects. Instances stay owned by their worker until all IO has ceased.
pub trait MemcardStorage: Send {
fn len(&self) -> Result<u64, MemcardIoError>;
fn is_empty(&self) -> Result<bool, MemcardIoError> {
self.len().map(|length| length == 0)
}
fn read_at(&mut self, offset: u64, target: &mut [u8]) -> Result<(), MemcardIoError>;
fn write_at(&mut self, offset: u64, source: &[u8]) -> Result<(), MemcardIoError>;
fn sync(&mut self) -> Result<(), MemcardIoError>;
fn read_only(&self) -> bool;
}
@@ -6,6 +6,7 @@ use crate::render_submission::{Game2DFramePacket, RenderSubmission};
use crate::sprite::Sprite;
use crate::telemetry::TelemetryFrame;
use crate::touch_bridge::TouchBridge;
use crate::wall_clock::WallClock;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RenderSubmitError {
@@ -60,6 +61,8 @@ pub struct NoopTelemetryPlatform;
impl TelemetryPlatform for NoopTelemetryPlatform {}
pub trait RuntimePlatform {
fn wall_clock(&self) -> &dyn WallClock;
fn display_size(&self) -> (usize, usize) {
(480, 270)
}
@@ -11,6 +11,12 @@ pub use resolver::{
resolve_declared_program_syscalls, resolve_program_syscalls, resolve_syscall,
};
/// Native metadata iteration for bounded image binding. This is not guest
/// reflection; callers account comparisons before examining catalogue entries.
pub fn catalogue() -> impl Iterator<Item = &'static SyscallRegistryEntry> {
domains::all_entries()
}
/// Enumeration of all System Calls (Syscalls) available in the Prometeu environment.
///
/// Syscalls are the primary mechanism for a program running in the Virtual Machine
@@ -49,6 +55,10 @@ pub enum Syscall {
ComposerEmitSprite = 0x1104,
AudioPlaySample = 0x3001,
AudioPlay = 0x3002,
AudioStop = 0x3003,
AudioSetVolume = 0x3004,
AudioSetPan = 0x3005,
AudioSetPitch = 0x3006,
FsOpen = 0x4001,
FsRead = 0x4002,
FsWrite = 0x4003,
@@ -56,12 +66,20 @@ pub enum Syscall {
FsListDir = 0x4005,
FsExists = 0x4006,
FsDelete = 0x4007,
MemBootstrap = 0x4200,
MemSlotCount = 0x4201,
MemSlotStat = 0x4202,
MemSlotRead = 0x4203,
MemSlotWrite = 0x4204,
MemSlotCommit = 0x4205,
MemSlotClear = 0x4206,
MemQuery = 0x4207,
MemRelease = 0x4208,
MemInfo = 0x4209,
MemMetadata = 0x420A,
MemPresentation = 0x420B,
MemDiagnostic = 0x420C,
MemPublishPresentation = 0x420D,
LogWrite = 0x5001,
LogWriteTag = 0x5002,
AssetLoad = 0x6001,
@@ -10,5 +10,7 @@ pub const ASSET: CapFlags = 1 << 5;
pub const BANK: CapFlags = 1 << 6;
pub const GFX2D: CapFlags = 1 << 7;
pub const GFXUI: CapFlags = 1 << 8;
pub const MEMCARD: CapFlags = 1 << 9;
pub const GFX: CapFlags = COMPOSER | GFX2D;
pub const ALL: CapFlags = SYSTEM | COMPOSER | AUDIO | FS | LOG | ASSET | BANK | GFX2D | GFXUI;
pub const ALL: CapFlags =
SYSTEM | COMPOSER | AUDIO | FS | LOG | ASSET | BANK | GFX2D | GFXUI | MEMCARD;
@@ -11,4 +11,24 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioStop, "audio", "stop")
.args(1)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetVolume, "audio", "set_volume")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetPan, "audio", "set_pan")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetPitch, "audio", "set_pitch")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
];
@@ -32,37 +32,4 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
.caps(caps::FS)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotCount, "mem", "slot_count")
.rets(2)
.caps(caps::FS),
SyscallRegistryEntry::builder(Syscall::MemSlotStat, "mem", "slot_stat")
.args(1)
.rets(5)
.caps(caps::FS)
.non_deterministic()
.cost(5),
SyscallRegistryEntry::builder(Syscall::MemSlotRead, "mem", "slot_read")
.args(3)
.rets(3)
.caps(caps::FS)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotWrite, "mem", "slot_write")
.args(3)
.rets(2)
.caps(caps::FS)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotCommit, "mem", "slot_commit")
.args(1)
.rets(1)
.caps(caps::FS)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotClear, "mem", "slot_clear")
.args(1)
.rets(1)
.caps(caps::FS)
.non_deterministic()
.cost(20),
];
@@ -0,0 +1,87 @@
use crate::syscalls::{Syscall, SyscallRegistryEntry, caps};
pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
SyscallRegistryEntry::builder(Syscall::MemBootstrap, "mem", "bootstrap")
.args(0)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotCount, "mem", "slot_count")
.args(1)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotStat, "mem", "slot_stat")
.args(2)
.rets(7)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotRead, "mem", "slot_read")
.args(6)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotWrite, "mem", "slot_write")
.args(6)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotCommit, "mem", "slot_commit")
.args(2)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemSlotClear, "mem", "slot_clear")
.args(2)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemQuery, "mem", "query")
.args(2)
.rets(3)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemRelease, "mem", "release")
.args(2)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemInfo, "mem", "info")
.args(1)
.rets(6)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemMetadata, "mem", "metadata")
.args(1)
.rets(4)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemPresentation, "mem", "presentation")
.args(8)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemDiagnostic, "mem", "diagnostic")
.args(2)
.rets(1)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
SyscallRegistryEntry::builder(Syscall::MemPublishPresentation, "mem", "publish_presentation")
.args(1)
.rets(2)
.caps(caps::MEMCARD)
.non_deterministic()
.cost(20),
];
@@ -18,7 +18,10 @@ pub(crate) fn all_entries() -> impl Iterator<Item = &'static SyscallRegistryEntr
.chain(composer::ENTRIES.iter())
.chain(audio::ENTRIES.iter())
.chain(fs::ENTRIES.iter())
.chain(memcard::ENTRIES.iter())
.chain(log::ENTRIES.iter())
.chain(asset::ENTRIES.iter())
.chain(bank::ENTRIES.iter())
}
mod memcard;
@@ -33,6 +33,10 @@ impl Syscall {
0x1104 => Some(Self::ComposerEmitSprite),
0x3001 => Some(Self::AudioPlaySample),
0x3002 => Some(Self::AudioPlay),
0x3003 => Some(Self::AudioStop),
0x3004 => Some(Self::AudioSetVolume),
0x3005 => Some(Self::AudioSetPan),
0x3006 => Some(Self::AudioSetPitch),
0x4001 => Some(Self::FsOpen),
0x4002 => Some(Self::FsRead),
0x4003 => Some(Self::FsWrite),
@@ -40,6 +44,14 @@ impl Syscall {
0x4005 => Some(Self::FsListDir),
0x4006 => Some(Self::FsExists),
0x4007 => Some(Self::FsDelete),
0x4200 => Some(Self::MemBootstrap),
0x4207 => Some(Self::MemQuery),
0x4208 => Some(Self::MemRelease),
0x4209 => Some(Self::MemInfo),
0x420A => Some(Self::MemMetadata),
0x420B => Some(Self::MemPresentation),
0x420C => Some(Self::MemDiagnostic),
0x420D => Some(Self::MemPublishPresentation),
0x4201 => Some(Self::MemSlotCount),
0x4202 => Some(Self::MemSlotStat),
0x4203 => Some(Self::MemSlotRead),
@@ -94,6 +106,10 @@ impl Syscall {
Self::ComposerEmitSprite => "ComposerEmitSprite",
Self::AudioPlaySample => "AudioPlaySample",
Self::AudioPlay => "AudioPlay",
Self::AudioStop => "AudioStop",
Self::AudioSetVolume => "AudioSetVolume",
Self::AudioSetPan => "AudioSetPan",
Self::AudioSetPitch => "AudioSetPitch",
Self::FsOpen => "FsOpen",
Self::FsRead => "FsRead",
Self::FsWrite => "FsWrite",
@@ -101,6 +117,14 @@ impl Syscall {
Self::FsListDir => "FsListDir",
Self::FsExists => "FsExists",
Self::FsDelete => "FsDelete",
Self::MemBootstrap => "MemBootstrap",
Self::MemQuery => "MemQuery",
Self::MemRelease => "MemRelease",
Self::MemInfo => "MemInfo",
Self::MemMetadata => "MemMetadata",
Self::MemPresentation => "MemPresentation",
Self::MemDiagnostic => "MemDiagnostic",
Self::MemPublishPresentation => "MemPublishPresentation",
Self::MemSlotCount => "MemSlotCount",
Self::MemSlotStat => "MemSlotStat",
Self::MemSlotRead => "MemSlotRead",
@@ -39,7 +39,8 @@ pub enum LoadError {
}
/// Load-time error for PBX-declared syscall resolution.
#[derive(Debug, Clone, PartialEq, Eq)]
#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
#[serde(tag = "reason", rename_all = "snake_case")]
pub enum DeclaredLoadError {
UnknownSyscall {
module: String,
@@ -460,29 +460,59 @@ fn declared_resolver_accepts_mixed_status_first_surface_as_a_single_module() {
#[test]
fn memcard_syscall_signatures_are_pinned() {
let slot_count = meta_for(Syscall::MemSlotCount);
assert_eq!(slot_count.module, "mem");
assert_eq!(slot_count.name, "slot_count");
assert_eq!(slot_count.arg_slots, 0);
assert_eq!(slot_count.ret_slots, 2);
for (call, args, results) in [
(Syscall::MemBootstrap, 0, 1),
(Syscall::MemSlotCount, 1, 2),
(Syscall::MemSlotStat, 2, 7),
(Syscall::MemSlotRead, 6, 2),
(Syscall::MemSlotWrite, 6, 2),
(Syscall::MemSlotCommit, 2, 2),
(Syscall::MemSlotClear, 2, 1),
(Syscall::MemQuery, 2, 3),
(Syscall::MemRelease, 2, 1),
(Syscall::MemInfo, 1, 6),
(Syscall::MemMetadata, 1, 4),
(Syscall::MemPresentation, 8, 1),
(Syscall::MemDiagnostic, 2, 1),
(Syscall::MemPublishPresentation, 1, 2),
] {
let meta = meta_for(call);
assert_eq!(meta.module, "mem");
assert_eq!(meta.arg_slots, args);
assert_eq!(meta.ret_slots, results);
assert!(
resolve_program_syscalls(
&[SyscallIdentity { module: "mem", name: meta.name, version: 1 }],
caps::FS
)
.is_err()
);
assert!(
resolve_program_syscalls(
&[SyscallIdentity { module: "mem", name: meta.name, version: 1 }],
caps::MEMCARD
)
.is_ok()
);
}
}
let slot_stat = meta_for(Syscall::MemSlotStat);
assert_eq!(slot_stat.arg_slots, 1);
assert_eq!(slot_stat.ret_slots, 5);
let slot_read = meta_for(Syscall::MemSlotRead);
assert_eq!(slot_read.arg_slots, 3);
assert_eq!(slot_read.ret_slots, 3);
let slot_write = meta_for(Syscall::MemSlotWrite);
assert_eq!(slot_write.arg_slots, 3);
assert_eq!(slot_write.ret_slots, 2);
let slot_commit = meta_for(Syscall::MemSlotCommit);
assert_eq!(slot_commit.arg_slots, 1);
assert_eq!(slot_commit.ret_slots, 1);
let slot_clear = meta_for(Syscall::MemSlotClear);
assert_eq!(slot_clear.arg_slots, 1);
assert_eq!(slot_clear.ret_slots, 1);
#[test]
fn audio_control_abi_and_capability_are_stable() {
for (name, id, args) in [
("stop", 0x3003, 1),
("set_volume", 0x3004, 2),
("set_pan", 0x3005, 2),
("set_pitch", 0x3006, 2),
] {
let entry = resolve_syscall("audio", name, 1).unwrap();
assert_eq!(entry.id, id);
assert_eq!(entry.meta.arg_slots, args);
assert_eq!(entry.meta.ret_slots, 1);
assert_eq!(entry.meta.cost_hint, 5);
assert_eq!(entry.meta.caps, caps::AUDIO);
let identities = [SyscallIdentity { module: "audio", name, version: 1 }];
assert!(resolve_program_syscalls(&identities, 0).is_err());
assert!(resolve_program_syscalls(&identities, caps::AUDIO).is_ok());
}
}
@@ -0,0 +1,62 @@
use prometeu_bytecode::Value;
use serde::{Deserialize, Serialize};
use std::sync::Arc;
/// Native/debug ownership only. Wire data is the ordinary list of values;
/// opaque accounting domains stay alive for every retained string allocation.
#[derive(Clone, Default, Serialize, Deserialize)]
#[serde(transparent)]
pub struct ValueSnapshot {
values: Vec<Value>,
#[serde(skip)]
owners: [Option<Arc<dyn Send + Sync>>; 2],
}
impl ValueSnapshot {
pub fn with_owners(values: Vec<Value>, owners: [Option<Arc<dyn Send + Sync>>; 2]) -> Self {
Self { values, owners }
}
pub fn retained_domains(&self) -> usize {
self.owners.iter().filter(|owner| owner.is_some()).count()
}
}
impl std::ops::Deref for ValueSnapshot {
type Target = [Value];
fn deref(&self) -> &[Value] {
&self.values
}
}
impl std::fmt::Debug for ValueSnapshot {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
self.values.fmt(f)
}
}
impl PartialEq<Vec<Value>> for ValueSnapshot {
fn eq(&self, other: &Vec<Value>) -> bool {
self.values == *other
}
}
impl From<Vec<Value>> for ValueSnapshot {
/// External/native values have no provenance and are copied on guest import.
fn from(values: Vec<Value>) -> Self {
Self::with_owners(values, [None, None])
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn serialization_contains_values_and_never_exports_native_domain_metadata() {
let owner: Arc<dyn Send + Sync> = Arc::new(17u32);
let snapshot = ValueSnapshot::with_owners(
vec![Value::string("shared"), Value::Null],
[Some(owner), None],
);
assert_eq!(snapshot.retained_domains(), 1);
let bytes = serde_json::to_string(&snapshot).unwrap();
assert_eq!(bytes, "[\"shared\",null]");
let imported: ValueSnapshot = serde_json::from_str(&bytes).unwrap();
assert_eq!(imported.retained_domains(), 0);
assert_eq!(&*imported, &*snapshot);
}
}
@@ -1,6 +1,7 @@
#[derive(Debug, PartialEq, Clone)]
pub enum VmFault {
Trap(u32, String),
ResourceLimit(prometeu_bytecode::ResourceFailure),
Panic(String),
Unavailable,
}
@@ -0,0 +1,11 @@
/// Host civil time for administrative timestamps, independent of gameplay and deadlines.
///
/// Reads must be local and bounded, without waiting for IO or clock synchronization.
/// The host always supplies a value, even when its civil clock is incorrect.
pub trait WallClock {
/// Whole UTC seconds since the Unix epoch, with fractions discarded.
///
/// Values outside the unsigned range saturate to zero or `u64::MAX`.
/// Successive reads may go backwards when the host adjusts its clock.
fn utc_unix_seconds(&self) -> u64;
}
@@ -5,6 +5,7 @@ edition = "2024"
license.workspace = true
[dependencies]
serde = { version = "1.0.228", features = ["derive"] }
serde_json = "1.0.149"
prometeu-vm = { path = "../prometeu-vm" }
prometeu-bytecode = { path = "../prometeu-bytecode" }
@@ -12,3 +13,4 @@ prometeu-hal = { path = "../prometeu-hal" }
[dev-dependencies]
prometeu-drivers = { path = "../prometeu-drivers" }
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
@@ -1,6 +1,7 @@
use prometeu_bytecode::TrapInfo;
use prometeu_vm::VmInitError;
use std::fmt;
mod init_diagnostic;
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CrashReport {
@@ -10,6 +11,20 @@ pub enum CrashReport {
}
impl CrashReport {
/// The same machine fields serve headless and desktop transports.
pub fn init_diagnostic(&self) -> Option<serde_json::Value> {
match self {
Self::VmInit { error } => Some(init_diagnostic::serialize(error)),
_ => None,
}
}
pub fn resource_failure(&self) -> Option<prometeu_bytecode::ResourceFailure> {
match self {
Self::VmTrap { trap } => trap.resource,
Self::VmInit { error: VmInitError::RuntimeResourceLimit(resource) } => Some(*resource),
_ => None,
}
}
pub fn kind(&self) -> &'static str {
match self {
Self::VmTrap { .. } => "vm_trap",
@@ -0,0 +1,132 @@
use prometeu_vm::VmInitError;
use serde_json::{Value, json};
pub(super) fn serialize(error: &VmInitError) -> Value {
let code = match error {
VmInitError::RegistryLoadFailed(_) => "registry_load_failed",
VmInitError::RuntimeResourceLimit(_) => "runtime_resource_limit",
VmInitError::InvalidFormat => "invalid_format",
VmInitError::UnsupportedFormat => "unsupported_format",
VmInitError::ImageLoadFailed(_) => "image_load_failed",
VmInitError::LoaderPatchFailed(_) => "loader_patch_failed",
VmInitError::EntrypointNotFound => "entrypoint_not_found",
VmInitError::EntrypointArgumentsInvalid { .. } => "entrypoint_arguments_invalid",
VmInitError::VerificationFailed(_) => "verification_failed",
};
let mut result = json!({"code":code,"message":format!("{error:?}")});
match error {
VmInitError::RegistryLoadFailed(load) => {
result["load"] = json!(load);
result["load"]["code"] = json!(load.code.tag());
}
VmInitError::RuntimeResourceLimit(resource) => result["resource"] = json!(resource),
VmInitError::EntrypointArgumentsInvalid { function, slot, trap_code } => {
result["entry"] = json!({"function":function,"slot":slot,"trapCode":trap_code});
}
VmInitError::LoaderPatchFailed(patch) => {
use prometeu_vm::LoaderPatchError as P;
result["binding"] = match patch {
P::ResolveFailed(native) => json!(native),
P::HostcallIndexOutOfBounds { pc, sysc_index, syscalls_len } => {
json!({"reason":"hostcall_index_out_of_bounds","pc":pc,"syscallIndex":sysc_index,"syscallsLength":syscalls_len})
}
P::RawSyscallInPreloadArtifact { pc, syscall_id } => {
json!({"reason":"raw_syscall","pc":pc,"syscallId":syscall_id})
}
P::UnusedSyscallDecl { sysc_index, module, name, version } => {
json!({"reason":"unused_syscall","syscallIndex":sysc_index,"module":module,"name":name,"version":version})
}
P::HostcallRemaining { pc, sysc_index } => {
json!({"reason":"hostcall_remaining","pc":pc,"syscallIndex":sysc_index})
}
P::DecodeFailed(_) => json!({"reason":"decode_failed"}),
};
}
_ => {}
}
result
}
#[cfg(test)]
mod tests {
use super::*;
use crate::CrashReport;
use prometeu_bytecode::{
ResourceFailure, ResourceReason, RuntimeResource,
load_limits::{IdDomain, LoadCode, LoadFailure, LoadReason},
};
#[test]
fn load_tag_and_reference_context_survive_without_fabricating_runtime_pc() {
let error = LoadFailure::new(LoadCode::InvalidReference, LoadReason::TypeId)
.at(6, 159)
.record(4)
.member(2)
.reference(IdDomain::Type, 77)
.in_function(3, Some(18));
let report = CrashReport::VmInit { error: VmInitError::RegistryLoadFailed(error) };
assert_eq!(report.pc(), None);
let wire = report.init_diagnostic().unwrap();
assert_eq!(wire["code"], "registry_load_failed");
assert_eq!(wire["load"]["code"], "LOAD_INVALID_REFERENCE");
for (field, value) in [
("section", 6),
("offset", 159),
("record", 4),
("member", 2),
("referenced_id", 77),
("function", 3),
("pc", 18),
] {
assert_eq!(wire["load"][field], value);
}
assert_eq!(wire["load"]["id_domain"], "Type");
assert_eq!(wire["load"]["reason"], "TypeId");
}
#[test]
fn native_abi_and_resource_context_are_machine_fields() {
let native = prometeu_hal::syscalls::DeclaredLoadError::AbiMismatch {
module: "system".into(),
name: "has_cart".into(),
version: 1,
declared_arg_slots: 0,
declared_ret_slots: 2,
expected_arg_slots: 0,
expected_ret_slots: 1,
};
let wire = serialize(&VmInitError::LoaderPatchFailed(
prometeu_vm::LoaderPatchError::ResolveFailed(native),
));
assert_eq!(wire["binding"]["reason"], "abi_mismatch");
assert_eq!(wire["binding"]["module"], "system");
assert_eq!(wire["binding"]["declared_ret_slots"], 2);
assert_eq!(wire["binding"]["expected_ret_slots"], 1);
let resource = ResourceFailure {
resource: RuntimeResource::CallDepth,
reason: ResourceReason::Limit,
requested: 3,
limit: 2,
};
let report = CrashReport::VmInit { error: VmInitError::RuntimeResourceLimit(resource) };
assert_eq!(report.resource_failure(), Some(resource));
let wire = report.init_diagnostic().unwrap();
assert_eq!(wire["resource"]["resource"], "CallDepth");
assert_eq!(wire["resource"]["reason"], "Limit");
assert_eq!(wire["resource"]["requested"], 3);
assert_eq!(wire["resource"]["limit"], 2);
}
#[test]
fn all_load_codes_serialize_to_the_normative_tags() {
for code in [
LoadCode::InvalidFormat,
LoadCode::UnsupportedFormat,
LoadCode::InvalidReference,
LoadCode::InvalidRegistry,
LoadCode::InvalidCode,
LoadCode::ResourceLimit,
LoadCode::InvalidEntrypoint,
] {
assert_eq!(json!(code), code.tag());
assert_eq!(serde_json::from_value::<LoadCode>(json!(code)).unwrap(), code);
}
}
}
+2 -1
View File
@@ -17,6 +17,7 @@ pub use services::async_work::{
AsyncWorkActiveJob, AsyncWorkCancelToken, AsyncWorkJobContext, AsyncWorkJobId,
AsyncWorkJobKind, AsyncWorkJobOutcome, AsyncWorkLane, AsyncWorkLaneConfig,
AsyncWorkLaneController, AsyncWorkLaneError, AsyncWorkLaneTelemetry, AsyncWorkPriority,
AsyncWorkStep,
};
pub use services::foreground::{
ForegroundOwner, ForegroundStack, ForegroundStackError, ResidentGame, ResidentGameState,
@@ -25,7 +26,7 @@ pub use services::fs;
pub use services::game_library::{
GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, GameSwitchTarget, discover_games_root,
};
pub use services::memcard::MemcardAsyncLaneOperation;
pub use services::memcard;
pub use services::process;
pub use services::task;
pub use services::vm_runtime::{
@@ -9,6 +9,7 @@ use crate::services::foreground::{
ForegroundOwner, ForegroundStackError, ResidentGame, ResidentGameState,
};
use crate::task::{TaskId, TaskKind, TaskState};
use crate::vm_session::LifecycleTransition;
pub struct LifecycleFacade<'a> {
pub(in crate::os) os: &'a mut SystemOS,
@@ -35,6 +36,21 @@ impl<'a> LifecycleFacade<'a> {
}
pub fn set_game_foreground_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
if self.os.memcard.host_faulted()
|| self.os.memcard.session.removal_pending()
|| matches!(
self.os.memcard.admission.state,
crate::memcard::admission::PreparationState::Pending
| crate::memcard::admission::PreparationState::Failed(_)
)
{
return Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::SetForeground,
});
}
let process_id = process_id_for_task(self.os, task_id)?;
if task_kind_for_task(self.os, task_id)? != TaskKind::Game {
@@ -45,6 +61,27 @@ impl<'a> LifecycleFacade<'a> {
});
}
if self
.os
.vm_sessions
.for_task(task_id)
.is_some_and(|session| session.lifecycle_transition.is_some())
{
return Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::SetForeground,
});
}
if self.task_state(task_id) == Some(TaskState::Suspended)
&& self.os.vm_sessions.for_task(task_id).is_some_and(|session| {
session
.vm
.has_lifecycle_hook(prometeu_bytecode::registry::LifecycleRole::BeforeResume)
})
{
return self.resume_task(task_id);
}
self.os.foreground_stack.set_game_foreground(task_id).map_err(map_foreground_error)?;
self.os.task_manager.set_foreground(task_id);
self.os.process_manager.mark_running(process_id);
@@ -67,6 +104,9 @@ impl<'a> LifecycleFacade<'a> {
&& game_task_id != task_id
&& self.task_state(game_task_id) != Some(TaskState::Suspended)
{
if self.defer_pause(game_task_id, LifecycleTransition::PauseToShell(task_id))? {
return Ok(());
}
let game_process_id = process_id_for_task(self.os, game_task_id)?;
self.os.task_manager.mark_suspended(game_task_id);
self.os.process_manager.mark_suspended(game_process_id);
@@ -93,6 +133,19 @@ impl<'a> LifecycleFacade<'a> {
pub fn request_home_from_game(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let _process_id = process_id_for_task(self.os, task_id)?;
if let Some(pending) =
self.os.vm_sessions.for_task(task_id).and_then(|s| s.lifecycle_transition)
{
return if pending == LifecycleTransition::PauseToHub {
Ok(())
} else {
Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::Suspend,
})
};
}
let previous = self.os.foreground_stack.resident_game();
self.os
@@ -113,6 +166,13 @@ impl<'a> LifecycleFacade<'a> {
}
pub fn advance_game_pause_budget(&mut self, task_id: TaskId) -> Result<bool, LifecycleError> {
if self.os.foreground_stack.resident_game().is_some_and(|game| {
game.task_id == task_id
&& game.state == ResidentGameState::PauseRequested { remaining_ticks: 1 }
}) && self.defer_pause(task_id, LifecycleTransition::PauseToHub)?
{
return Ok(false);
}
let expired =
self.os.foreground_stack.advance_pause_budget(task_id).map_err(map_foreground_error)?;
@@ -125,6 +185,34 @@ impl<'a> LifecycleFacade<'a> {
Ok(expired)
}
fn defer_pause(
&mut self,
task_id: TaskId,
transition: LifecycleTransition,
) -> Result<bool, LifecycleError> {
let state = self.task_state(task_id).unwrap_or(TaskState::Closed);
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
return Ok(false);
};
if let Some(pending) = session.lifecycle_transition {
return if pending == transition {
Ok(true)
} else {
Err(LifecycleError::InvalidTransition {
task_id,
from: state,
operation: LifecycleOperation::Suspend,
})
};
}
if session.pause_hook_complete || !session.vm.has_lifecycle_hook(transition.role()) {
return Ok(false);
}
session.lifecycle_transition = Some(transition);
session.lifecycle_started = false;
Ok(true)
}
pub fn pending_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
&self.os.game_lifecycle_events
}
@@ -141,6 +229,11 @@ impl<'a> LifecycleFacade<'a> {
pub fn suspend_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let process_id = process_id_for_task(self.os, task_id)?;
if task_kind_for_task(self.os, task_id)? == TaskKind::Game
&& self.defer_pause(task_id, LifecycleTransition::PauseToHub)?
{
return Ok(());
}
self.os.task_manager.mark_suspended(task_id);
self.os.process_manager.mark_suspended(process_id);
match self.os.foreground_stack.owner() {
@@ -164,6 +257,21 @@ impl<'a> LifecycleFacade<'a> {
}
pub fn resume_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
if self.os.memcard.host_faulted()
|| self.os.memcard.session.removal_pending()
|| matches!(
self.os.memcard.admission.state,
crate::memcard::admission::PreparationState::Pending
| crate::memcard::admission::PreparationState::Failed(_)
)
{
return Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::Resume,
});
}
let task =
self.os.task_manager.get(task_id).ok_or(LifecycleError::TaskNotFound(task_id))?;
@@ -189,6 +297,16 @@ impl<'a> LifecycleFacade<'a> {
task_id,
kind: GameLifecycleEventKind::ResumeForeground,
});
if let Some(session) = self.os.vm_sessions.for_task_mut(task_id) {
session.pause_hook_complete = false;
if session.vm.has_lifecycle_hook(
prometeu_bytecode::registry::LifecycleRole::BeforeResume,
) {
session.lifecycle_transition = Some(LifecycleTransition::Resume);
session.lifecycle_started = false;
return Ok(());
}
}
self.os
.foreground_stack
.complete_resume_game(task_id)
@@ -1,15 +1,15 @@
use crate::CrashReport;
use crate::os::{GameLifecycleEvent, SystemOS};
use crate::task::TaskId;
use crate::vm_session::VmSession;
use crate::vm_session::{LifecycleTransition, VmSession};
use crate::{RenderWorkerConfig, RenderWorkerController};
use prometeu_bytecode::Value;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame};
use prometeu_hal::{
FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError,
RenderWorkerFrameSink, RuntimePlatform,
};
use prometeu_vm::LogicalFrameEndingReason;
use std::sync::atomic::Ordering;
pub struct VmFacade<'a> {
@@ -23,6 +23,12 @@ impl<'a> VmFacade<'a> {
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if self.os.lifecycle().task_state(task_id) != Some(crate::task::TaskState::Foreground) {
return None;
}
if self.os.vm_sessions.for_task(task_id).is_some_and(|s| s.lifecycle_transition.is_some()) {
return self.drive_lifecycle(task_id, platform, false).err();
}
self.deliver_pending_game_lifecycle_events_to_session(task_id);
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
@@ -45,6 +51,112 @@ impl<'a> VmFacade<'a> {
)
}
/// Firmware polls this before dispatching ordinary Game/Shell updates.
pub fn poll_pending_lifecycle(
&mut self,
platform: &mut dyn RuntimePlatform,
) -> Option<(TaskId, Result<(), CrashReport>)> {
let task_id = self.os.foreground_stack.resident_game_task()?;
self.os.vm_sessions.for_task(task_id)?.lifecycle_transition?;
Some((task_id, self.drive_lifecycle(task_id, platform, false)))
}
fn drive_lifecycle(
&mut self,
task_id: TaskId,
platform: &mut dyn RuntimePlatform,
single_step: bool,
) -> Result<(), CrashReport> {
self.deliver_pending_game_lifecycle_events_to_session(task_id);
let session = self.os.vm_sessions.for_task_mut(task_id).expect("pending lifecycle session");
let transition = session.lifecycle_transition.expect("pending lifecycle transition");
let role = transition.role();
// A fatal hook remains failed even if a caller tries to tick the same session again.
if let Some(report) = &session.runtime.last_crash_report {
return Err(report.clone());
}
if !platform.audio().lifecycle_ready() {
return Ok(());
}
let reason = if !session.lifecycle_started {
session.lifecycle_started = true;
match session.vm.begin_lifecycle(role) {
Ok(true) => None,
Ok(false) => {
// Optional hooks still form a successful lifecycle boundary.
platform.audio_mut().begin_lifecycle();
platform.audio_mut().finish_lifecycle(true);
Some(LogicalFrameEndingReason::LifecycleComplete)
}
Err(error) => Some(LogicalFrameEndingReason::Panic(format!("{error:?}"))),
}
} else {
None
};
let reason = reason.unwrap_or_else(|| {
session.runtime.tick_lifecycle(
&mut self.os.log_service,
&mut self.os.fs,
&mut session.fs_state,
&mut self.os.memcard,
&mut session.open_files,
&mut session.next_handle,
&mut session.vm,
platform,
single_step,
)
});
match reason {
LogicalFrameEndingReason::BudgetExhausted | LogicalFrameEndingReason::Breakpoint => {
Ok(())
}
LogicalFrameEndingReason::LifecycleComplete => {
session.lifecycle_transition = None;
session.lifecycle_started = false;
match transition {
LifecycleTransition::PauseToHub => {
session.pause_hook_complete = true;
self.os.lifecycle().suspend_task(task_id).expect("validated suspension");
}
LifecycleTransition::PauseToShell(shell) => {
session.pause_hook_complete = true;
self.os
.lifecycle()
.set_shell_foreground_task(shell)
.expect("validated Shell transition");
}
LifecycleTransition::Resume => {
self.os
.foreground_stack
.complete_resume_game(task_id)
.expect("validated resume");
}
}
Ok(())
}
LogicalFrameEndingReason::Halted => {
// HALT ends the session; it must never restore or resume gameplay.
session.lifecycle_transition = None;
self.os.lifecycle().close_task(task_id).expect("validated task");
Ok(())
}
failure => {
let report = match failure {
LogicalFrameEndingReason::Trap(mut trap) => {
trap.message = format!("{role:?}: {}", trap.message);
CrashReport::VmTrap { trap }
}
other => CrashReport::VmPanic {
message: format!("{role:?} lifecycle failed: {other:?}"),
pc: Some(session.vm.pc() as u32),
},
};
session.runtime.last_crash_report = Some(report.clone());
Err(report)
}
}
}
fn deliver_pending_game_lifecycle_events_to_session(&mut self, task_id: TaskId) {
let Some(session) = self.os.vm_sessions.for_task(task_id) else {
return;
@@ -86,6 +198,12 @@ impl<'a> VmFacade<'a> {
pc: None,
});
};
if self.os.lifecycle().task_state(task_id) != Some(crate::task::TaskState::Foreground) {
return None;
}
if self.os.vm_sessions.for_task(task_id).is_some_and(|s| s.lifecycle_transition.is_some()) {
return self.drive_lifecycle(task_id, platform, true).err();
}
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
return Some(CrashReport::VmPanic {
message: format!("active debug task {:?} has no VM session", task_id),
@@ -93,14 +211,23 @@ impl<'a> VmFacade<'a> {
});
};
session.runtime.debug_step_instruction(&mut self.os.log_service, &mut session.vm, platform)
session.runtime.debug_step_instruction(
&mut self.os.log_service,
&mut self.os.fs,
&mut session.fs_state,
&mut self.os.memcard,
&mut session.open_files,
&mut session.next_handle,
&mut session.vm,
platform,
)
}
pub fn active_pc(&self) -> Option<usize> {
self.active_session().map(|session| session.vm.pc())
}
pub fn active_operand_stack_top(&self, n: usize) -> Vec<Value> {
pub fn active_operand_stack_top(&self, n: usize) -> prometeu_hal::ValueSnapshot {
self.active_session().map(|session| session.vm.operand_stack_top(n)).unwrap_or_default()
}
@@ -28,6 +28,8 @@ pub struct SystemOS {
pub(super) memcard: MemcardService,
pub(super) open_files: HashMap<u32, String>,
pub(super) next_handle: u32,
io_controller: Option<crate::AsyncWorkLaneController>,
io_bound: bool,
}
impl SystemOS {
@@ -50,6 +52,8 @@ impl SystemOS {
memcard: MemcardService::new(),
open_files: HashMap::new(),
next_handle: 1,
io_controller: None,
io_bound: false,
};
os.log(LogLevel::Info, LogSource::Pos, 0, "PrometeuOS starting...".to_string());
@@ -57,6 +61,55 @@ impl SystemOS {
os
}
pub fn memcard(&mut self) -> &mut MemcardService {
&mut self.memcard
}
/// Host/player operations are admitted only while gameplay is suspended.
pub fn replace_memcard(
&mut self,
storage: Box<dyn prometeu_hal::memcard::MemcardStorage>,
load_existing: bool,
) -> crate::memcard::image::Result<()> {
if let Some(task) = self.foreground_stack.resident_game_task()
&& self
.task_manager
.get(task)
.is_none_or(|t| t.state != crate::task::TaskState::Suspended)
{
return Err(crate::memcard::image::Error::AccessDenied);
}
self.memcard.replace_card(storage, load_existing)
}
pub fn detach_memcard(&mut self) -> crate::memcard::image::Result<()> {
if let Some(task) = self.foreground_stack.resident_game_task()
&& self
.task_manager
.get(task)
.is_none_or(|t| t.state != crate::task::TaskState::Suspended)
{
return Err(crate::memcard::image::Error::AccessDenied);
}
if self.memcard.host_faulted() {
return Err(crate::memcard::image::Error::ReadOnly);
}
self.memcard.session.detach()?;
self.memcard.admission.state = crate::memcard::admission::PreparationState::Ready;
Ok(())
}
/// Called outside guest/frame execution, including while a game is suspended.
pub fn poll_background_io(&mut self, platform: &mut dyn prometeu_hal::RuntimePlatform) {
if !self.io_bound && platform.assets_mut().bind_background_work(self.memcard.lane.clone()) {
self.io_controller = Some(crate::AsyncWorkLaneController::start(
crate::AsyncWorkLaneConfig::default(),
self.memcard.lane.clone(),
));
self.io_bound = true;
}
self.memcard.poll(std::time::Instant::now());
}
pub fn log(&mut self, level: LogLevel, source: LogSource, tag: u16, msg: String) {
self.vm_runtime.log(&mut self.log_service, level, source, tag, msg);
}
@@ -136,7 +189,7 @@ impl SystemOS {
pub(super) fn clear_cartridge_service_state(&mut self) {
self.open_files.clear();
self.next_handle = 1;
self.memcard.clear_all_staging();
self.memcard.session.end_session();
}
}
@@ -158,6 +211,7 @@ mod tests {
fn session_test_cartridge(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
Cartridge {
memcard_slots: None,
app_id,
title: title.to_string(),
app_version: "1.0.0".to_string(),
@@ -607,6 +607,7 @@ mod tests {
fn game_row_click_emits_launch_game_action() {
let entry = crate::GameLibraryEntry {
manifest: prometeu_hal::cartridge::CartridgeManifest {
memcard_slots: None,
magic: "PMTU".to_string(),
cartridge_version: 1,
app_id: 42,
@@ -619,7 +620,7 @@ mod tests {
app_id: 42,
app_version: "1.0.0".to_string(),
path: PathBuf::from("test-cartridges/stress-console"),
discovered_at: std::time::SystemTime::UNIX_EPOCH,
discovered_at: 0,
};
let action = action_for_click(
@@ -172,7 +172,13 @@ impl AsyncWorkJobContext {
}
}
type AsyncWorkFn = Box<dyn FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static>;
/// A step must release the executor when yielding; it retains its own bounded progress.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AsyncWorkStep {
Yield,
Complete(AsyncWorkJobOutcome),
}
type AsyncWorkFn = Box<dyn FnMut(AsyncWorkJobContext) -> AsyncWorkStep + Send + 'static>;
struct PendingAsyncWorkJob {
id: AsyncWorkJobId,
@@ -180,6 +186,7 @@ struct PendingAsyncWorkJob {
priority: AsyncWorkPriority,
cancel_token: AsyncWorkCancelToken,
work: AsyncWorkFn,
started: bool,
}
struct RunningAsyncWorkJob {
@@ -188,11 +195,13 @@ struct RunningAsyncWorkJob {
priority: AsyncWorkPriority,
cancel_token: AsyncWorkCancelToken,
work: AsyncWorkFn,
started: bool,
}
#[derive(Default)]
struct AsyncWorkLaneState {
next_job_id: u64,
progress: u64,
pending: VecDeque<PendingAsyncWorkJob>,
active: Option<AsyncWorkActiveJob>,
active_cancel_token: Option<AsyncWorkCancelToken>,
@@ -204,9 +213,25 @@ struct AsyncWorkLaneState {
pub struct AsyncWorkLane {
state: Mutex<AsyncWorkLaneState>,
ready: Condvar,
progressed: Condvar,
}
impl AsyncWorkLane {
pub fn progress_stamp(&self) -> u64 {
self.state.lock().unwrap().progress
}
/// Used by synchronous headless boot admission, never by a guest/frame tick.
/// Wakes on actual IO progress; timeout lets the caller run its watchdog.
pub fn wait_for_progress(&self, stamp: u64, timeout: Duration) {
let state = self.state.lock().unwrap();
let _guard = self
.progressed
.wait_timeout_while(state, timeout, |s| {
s.progress == stamp && (!s.pending.is_empty() || s.active.is_some())
})
.unwrap();
}
pub fn submit(
&self,
kind: AsyncWorkJobKind,
@@ -220,16 +245,36 @@ impl AsyncWorkLane {
kind: AsyncWorkJobKind,
priority: AsyncWorkPriority,
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
let mut once = Some(work);
self.submit_steps(kind, priority, move |context| {
AsyncWorkStep::Complete(once.take().expect("one-shot job executed once")(context))
})
}
pub fn submit_steps(
&self,
kind: AsyncWorkJobKind,
priority: AsyncWorkPriority,
work: impl FnMut(AsyncWorkJobContext) -> AsyncWorkStep + Send + 'static,
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
let mut state = self.state.lock().map_err(|_| AsyncWorkLaneError::InternalFailure)?;
if state.shutdown_requested {
return Err(AsyncWorkLaneError::Shutdown);
}
state.next_job_id += 1;
state.next_job_id =
state.next_job_id.checked_add(1).ok_or(AsyncWorkLaneError::InternalFailure)?;
let id = AsyncWorkJobId::new(state.next_job_id);
let cancel_token = AsyncWorkCancelToken::new();
let job = PendingAsyncWorkJob { id, kind, priority, cancel_token, work: Box::new(work) };
let job = PendingAsyncWorkJob {
id,
kind,
priority,
cancel_token,
work: Box::new(work),
started: false,
};
let insert_at = state
.pending
.iter()
@@ -340,13 +385,19 @@ impl AsyncWorkLane {
state.active = Some(active);
state.active_cancel_token = Some(pending.cancel_token.clone());
let pending_depth = state.pending.len();
state.telemetry.record_started(pending.id, pending_depth);
if !pending.started {
state.telemetry.record_started(pending.id, pending_depth);
} else {
state.telemetry.active_job_id = Some(pending.id);
state.telemetry.pending_depth = pending_depth;
}
return Some(RunningAsyncWorkJob {
id: pending.id,
kind: pending.kind,
priority: pending.priority,
cancel_token: pending.cancel_token,
work: pending.work,
started: true,
});
}
@@ -355,6 +406,33 @@ impl AsyncWorkLane {
}
}
fn yield_job(&self, job: RunningAsyncWorkJob) {
let mut state = self.state.lock().unwrap();
state.active = None;
state.active_cancel_token = None;
state.telemetry.active_job_id = None;
let at = state
.pending
.iter()
.position(|p| job.priority.rank() < p.priority.rank())
.unwrap_or(state.pending.len());
state.pending.insert(
at,
PendingAsyncWorkJob {
id: job.id,
kind: job.kind,
priority: job.priority,
cancel_token: job.cancel_token,
work: job.work,
started: job.started,
},
);
state.telemetry.pending_depth = state.pending.len();
state.progress = state.progress.saturating_add(1);
self.progressed.notify_all();
self.ready.notify_one();
}
fn record_finished(&self, job_id: AsyncWorkJobId, outcome: AsyncWorkJobOutcome) {
let mut state = self.state.lock().unwrap();
if state.active.is_some_and(|active| active.id == job_id) {
@@ -362,6 +440,8 @@ impl AsyncWorkLane {
state.active_cancel_token = None;
}
state.telemetry.record_closed(job_id, outcome);
state.progress = state.progress.saturating_add(1);
self.progressed.notify_all();
}
}
@@ -415,16 +495,19 @@ impl Drop for AsyncWorkLaneController {
}
fn run_async_work_loop(lane: Arc<AsyncWorkLane>) {
while let Some(job) = lane.wait_take() {
while let Some(mut job) = lane.wait_take() {
let context = AsyncWorkJobContext {
job_id: job.id,
kind: job.kind,
priority: job.priority,
cancel_token: job.cancel_token,
cancel_token: job.cancel_token.clone(),
};
let result = catch_unwind(AssertUnwindSafe(|| (job.work)(context)))
.unwrap_or(AsyncWorkJobOutcome::Failed);
lane.record_finished(job.id, result);
.unwrap_or(AsyncWorkStep::Complete(AsyncWorkJobOutcome::Failed));
match result {
AsyncWorkStep::Yield => lane.yield_job(job),
AsyncWorkStep::Complete(outcome) => lane.record_finished(job.id, outcome),
}
}
}
@@ -599,3 +682,63 @@ mod tests {
assert_eq!(lane.telemetry().shutdown_discards, 1);
}
}
#[cfg(test)]
mod step_tests {
use super::*;
#[test]
fn yielded_asset_resumes_same_job_after_priority_save() {
let lane = Arc::new(AsyncWorkLane::default());
let events = Arc::new(Mutex::new(Vec::new()));
let nested = lane.clone();
let log = events.clone();
let mut step = 0;
let mut identity = None;
lane.submit_steps(AsyncWorkJobKind::Asset, AsyncWorkPriority::AssetLoad, move |context| {
assert_eq!(*identity.get_or_insert(context.job_id), context.job_id);
if step == 0 {
log.lock().unwrap().push("asset first");
let log = log.clone();
nested
.submit_memcard_commit_write(move |_| {
log.lock().unwrap().push("save");
AsyncWorkJobOutcome::Completed
})
.unwrap();
step += 1;
AsyncWorkStep::Yield
} else {
log.lock().unwrap().push("asset resumes");
AsyncWorkStep::Complete(AsyncWorkJobOutcome::Completed)
}
})
.unwrap();
let mut controller =
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), lane.clone());
let deadline = std::time::Instant::now() + Duration::from_secs(1);
while lane.telemetry().completed_jobs < 2 {
assert!(std::time::Instant::now() < deadline);
std::thread::yield_now();
}
controller.stop().unwrap();
assert_eq!(*events.lock().unwrap(), vec!["asset first", "save", "asset resumes"]);
}
}
impl prometeu_hal::background_work::BackgroundWork for AsyncWorkLane {
fn submit_asset(
&self,
mut work: prometeu_hal::background_work::AssetWork,
) -> Result<(), prometeu_hal::background_work::WorkUnavailable> {
use prometeu_hal::background_work::{WorkStep, WorkUnavailable};
self.submit_steps(AsyncWorkJobKind::Asset, AsyncWorkPriority::AssetLoad, move |context| {
match work(context.is_canceled()) {
WorkStep::Yield => AsyncWorkStep::Yield,
WorkStep::Complete => AsyncWorkStep::Complete(AsyncWorkJobOutcome::Completed),
WorkStep::Failed => AsyncWorkStep::Complete(AsyncWorkJobOutcome::Failed),
}
})
.map(|_| ())
.map_err(|_| WorkUnavailable)
}
}
@@ -1,8 +1,8 @@
use prometeu_hal::WallClock;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::CartridgeManifest;
use std::fs;
use std::path::{Path, PathBuf};
use std::time::SystemTime;
#[derive(Debug, Clone)]
pub struct GameLibraryEntry {
@@ -11,11 +11,12 @@ pub struct GameLibraryEntry {
pub app_id: u32,
pub app_version: String,
pub path: PathBuf,
pub discovered_at: SystemTime,
/// UTC seconds sampled once for the discovery scan, from the selected host clock.
pub discovered_at: u64,
}
impl GameLibraryEntry {
fn new(path: PathBuf, manifest: CartridgeManifest, discovered_at: SystemTime) -> Self {
fn new(path: PathBuf, manifest: CartridgeManifest, discovered_at: u64) -> Self {
Self {
title: manifest.title.clone(),
app_id: manifest.app_id,
@@ -91,9 +92,9 @@ impl GameLibrary {
}
}
pub fn discover_games_root(root: impl AsRef<Path>) -> GameLibrary {
pub fn discover_games_root(root: impl AsRef<Path>, wall_clock: &dyn WallClock) -> GameLibrary {
let root = root.as_ref();
let discovered_at = SystemTime::now();
let discovered_at = wall_clock.utc_unix_seconds();
if !root.is_dir() {
return GameLibrary {
@@ -153,7 +154,7 @@ pub fn discover_games_root(root: impl AsRef<Path>) -> GameLibrary {
fn discover_candidate(
path: &Path,
discovered_at: SystemTime,
discovered_at: u64,
) -> Result<GameLibraryEntry, GameLibraryDiagnosticReason> {
let manifest_path = path.join("manifest.json");
if !manifest_path.exists() {
@@ -185,8 +186,26 @@ fn discover_candidate(
mod tests {
use super::*;
use serde_json::json;
use std::cell::Cell;
use std::sync::atomic::{AtomicU64, Ordering};
use std::time::UNIX_EPOCH;
struct CountingClock {
seconds: Cell<u64>,
calls: Cell<usize>,
}
impl CountingClock {
fn new(seconds: u64) -> Self {
Self { seconds: Cell::new(seconds), calls: Cell::new(0) }
}
}
impl WallClock for CountingClock {
fn utc_unix_seconds(&self) -> u64 {
self.calls.set(self.calls.get() + 1);
self.seconds.get()
}
}
static TEST_DIR_COUNTER: AtomicU64 = AtomicU64::new(0);
@@ -254,7 +273,7 @@ mod tests {
fs::write(nested_parent.join("nested-game").join("program.pbx"), [0_u8])
.expect("nested program should be written");
let library = discover_games_root(&root.path);
let library = discover_games_root(&root.path, &CountingClock::new(123));
assert_eq!(library.entries().len(), 2);
assert_eq!(library.entries()[0].title, "Alpha");
@@ -262,7 +281,7 @@ mod tests {
assert_eq!(library.entries()[0].app_version, "1.0.0");
assert_eq!(library.entries()[0].manifest.app_mode, AppMode::Game);
assert!(library.entries()[0].path.ends_with("alpha"));
assert!(library.entries()[0].discovered_at >= UNIX_EPOCH);
assert_eq!(library.entries()[0].discovered_at, 123);
assert_eq!(library.entries()[1].title, "Zeta");
assert!(library.diagnostics().iter().any(|diagnostic| {
@@ -285,6 +304,7 @@ mod tests {
let entry = GameLibraryEntry::new(
path.clone(),
CartridgeManifest {
memcard_slots: None,
magic: "PMTU".to_string(),
cartridge_version: 1,
app_id: 42,
@@ -293,7 +313,7 @@ mod tests {
app_mode: AppMode::Game,
capabilities: vec![],
},
UNIX_EPOCH,
0,
);
let target = entry.switch_target();
@@ -309,7 +329,7 @@ mod tests {
let root = TestRoot::new();
let missing = root.path.join("missing");
let library = discover_games_root(&missing);
let library = discover_games_root(&missing, &CountingClock::new(0));
assert!(library.is_empty());
assert_eq!(library.diagnostics().len(), 1);
@@ -321,7 +341,7 @@ mod tests {
let games_root =
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges");
let library = discover_games_root(games_root);
let library = discover_games_root(games_root, &CountingClock::new(0));
let entries = library.entries();
assert!(entries.iter().any(|entry| {
@@ -333,4 +353,24 @@ mod tests {
entry.app_id == 2 && entry.title == "Dummy Boy" && entry.path.ends_with("dummy-boy")
}));
}
#[test]
fn discovery_samples_once_per_scan_and_preserves_adjustments_and_full_range() {
let root = TestRoot::new();
root.add_candidate("zeta", manifest("Zeta", 2, "Game"), true);
root.add_candidate("alpha", manifest("Alpha", 1, "Game"), true);
let clock = CountingClock::new(u64::MAX);
let first = discover_games_root(&root.path, &clock);
assert_eq!(clock.calls.get(), 1);
assert_eq!(first.entries().len(), 2);
assert!(first.entries().iter().all(|entry| entry.discovered_at == u64::MAX));
clock.seconds.set(7);
let second = discover_games_root(&root.path, &clock);
assert_eq!(clock.calls.get(), 2);
assert!(second.entries().iter().all(|entry| entry.discovered_at == 7));
assert_eq!(second.entries()[0].app_id, 1);
assert_eq!(second.entries()[1].app_id, 2);
assert!(first.entries().iter().all(|entry| entry.discovered_at == u64::MAX));
}
}
@@ -1,481 +1,21 @@
use crate::fs::{FsError, VirtualFS};
use crate::services::async_work::{AsyncWorkJobKind, AsyncWorkPriority};
use std::collections::HashMap;
pub const MEMCARD_SLOT_COUNT: usize = 32;
pub const MEMCARD_SLOT_CAPACITY_BYTES: usize = 32 * 1024;
const SLOT_FILE_MAGIC: &[u8; 4] = b"PMMS";
const SLOT_FILE_VERSION: u8 = 1;
const SLOT_HEADER_SIZE: usize = 4 + 1 + 16 + 8 + 4 + 4;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
pub enum MemcardStatus {
Ok = 0,
Empty = 1,
NotFound = 2,
NoSpace = 3,
AccessDenied = 4,
Corrupt = 5,
Conflict = 6,
Unavailable = 7,
InvalidState = 8,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(i32)]
pub enum MemcardSlotState {
Empty = 0,
Staged = 1,
Committed = 2,
Corrupt = 3,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct MemcardSlotStat {
pub state: MemcardSlotState,
pub used_bytes: u32,
pub generation: u64,
pub checksum: u32,
}
pub struct MemcardReadResult {
pub status: MemcardStatus,
pub bytes: Vec<u8>,
pub bytes_read: u32,
}
pub struct MemcardWriteResult {
pub status: MemcardStatus,
pub bytes_written: u32,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum MemcardAsyncLaneOperation {
SlotWrite,
SlotCommit,
SlotClear,
SlotRead,
SlotStat,
}
impl MemcardAsyncLaneOperation {
pub const fn job_kind(self) -> AsyncWorkJobKind {
AsyncWorkJobKind::Memcard
}
pub const fn priority(self) -> AsyncWorkPriority {
match self {
Self::SlotWrite | Self::SlotCommit | Self::SlotClear => {
AsyncWorkPriority::MemcardCommitWrite
}
Self::SlotRead | Self::SlotStat => AsyncWorkPriority::NonCriticalReadList,
}
}
}
#[derive(Debug, Clone)]
struct SlotImage {
payload: Vec<u8>,
generation: u64,
checksum: u32,
save_uuid: [u8; 16],
}
//! Shared image-backed memory cards. Guest operations use RAM snapshots; only the
//! shared IO worker owns storage during a publication. Legacy per-slot files are
//! intentionally neither read nor migrated by this service.
pub mod admission;
pub mod guest;
pub mod image;
pub mod session;
pub mod transaction;
#[derive(Default)]
pub struct MemcardService {
staged: HashMap<(u32, u8), Vec<u8>>,
pub session: session::Session,
pub lane: std::sync::Arc<crate::AsyncWorkLane>,
pub admission: admission::Admission,
pub diagnostic: String,
}
impl MemcardService {
pub fn new() -> Self {
Self::default()
}
pub fn clear_all_staging(&mut self) {
self.staged.clear();
}
pub fn slot_count(&self) -> usize {
MEMCARD_SLOT_COUNT
}
pub fn slot_stat(&self, fs: &VirtualFS, app_id: u32, slot: u8) -> MemcardSlotStat {
if let Some(staged_payload) = self.staged.get(&(app_id, slot)) {
let generation = match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => committed.generation.saturating_add(1),
_ => 1,
};
return MemcardSlotStat {
state: MemcardSlotState::Staged,
used_bytes: staged_payload.len() as u32,
generation,
checksum: checksum32(staged_payload),
};
}
match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => MemcardSlotStat {
state: MemcardSlotState::Committed,
used_bytes: committed.payload.len() as u32,
generation: committed.generation,
checksum: committed.checksum,
},
Ok(None) => MemcardSlotStat {
state: MemcardSlotState::Empty,
used_bytes: 0,
generation: 0,
checksum: 0,
},
Err(MemcardStatus::Corrupt) => MemcardSlotStat {
state: MemcardSlotState::Corrupt,
used_bytes: 0,
generation: 0,
checksum: 0,
},
Err(_) => MemcardSlotStat {
state: MemcardSlotState::Empty,
used_bytes: 0,
generation: 0,
checksum: 0,
},
}
}
pub fn slot_read(
&self,
fs: &VirtualFS,
app_id: u32,
slot: u8,
offset: usize,
max_bytes: usize,
) -> MemcardReadResult {
if let Some(staged_payload) = self.staged.get(&(app_id, slot)) {
return Self::slice_payload(staged_payload, offset, max_bytes);
}
match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => Self::slice_payload(&committed.payload, offset, max_bytes),
Ok(None) => {
MemcardReadResult { status: MemcardStatus::Empty, bytes: Vec::new(), bytes_read: 0 }
}
Err(status) => MemcardReadResult { status, bytes: Vec::new(), bytes_read: 0 },
}
}
pub fn slot_write(
&mut self,
fs: &VirtualFS,
app_id: u32,
slot: u8,
offset: usize,
data: &[u8],
) -> MemcardWriteResult {
let end = match offset.checked_add(data.len()) {
Some(v) => v,
None => {
return MemcardWriteResult { status: MemcardStatus::NoSpace, bytes_written: 0 };
}
};
if end > MEMCARD_SLOT_CAPACITY_BYTES {
return MemcardWriteResult { status: MemcardStatus::NoSpace, bytes_written: 0 };
}
let mut payload = if let Some(staged_payload) = self.staged.get(&(app_id, slot)) {
staged_payload.clone()
} else {
match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => committed.payload,
Ok(None) => Vec::new(),
Err(status) => {
return MemcardWriteResult { status, bytes_written: 0 };
}
}
};
if offset > payload.len() {
payload.resize(offset, 0);
}
if end > payload.len() {
payload.resize(end, 0);
}
payload[offset..end].copy_from_slice(data);
self.staged.insert((app_id, slot), payload);
MemcardWriteResult { status: MemcardStatus::Ok, bytes_written: data.len() as u32 }
}
pub fn slot_commit(&mut self, fs: &mut VirtualFS, app_id: u32, slot: u8) -> MemcardStatus {
let Some(staged_payload) = self.staged.get(&(app_id, slot)).cloned() else {
return MemcardStatus::InvalidState;
};
let (save_uuid, generation) = match self.load_committed(fs, app_id, slot) {
Ok(Some(committed)) => (committed.save_uuid, committed.generation.saturating_add(1)),
Ok(None) => (make_save_uuid(app_id, slot), 1),
Err(status) => return status,
};
let checksum = checksum32(&staged_payload);
let encoded = encode_slot_file(SlotImage {
payload: staged_payload,
generation,
checksum,
save_uuid,
});
let path = slot_path(app_id, slot);
match fs.write_file(&path, &encoded) {
Ok(()) => {
self.staged.remove(&(app_id, slot));
MemcardStatus::Ok
}
Err(err) => map_fs_error(err),
}
}
pub fn slot_clear(&mut self, fs: &mut VirtualFS, app_id: u32, slot: u8) -> MemcardStatus {
self.staged.remove(&(app_id, slot));
let path = slot_path(app_id, slot);
match fs.delete(&path) {
Ok(()) => MemcardStatus::Ok,
Err(FsError::NotFound) => MemcardStatus::Empty,
Err(err) => map_fs_error(err),
}
}
fn slice_payload(payload: &[u8], offset: usize, max_bytes: usize) -> MemcardReadResult {
if offset >= payload.len() || max_bytes == 0 {
return MemcardReadResult {
status: MemcardStatus::Ok,
bytes: Vec::new(),
bytes_read: 0,
};
}
let end = payload.len().min(offset.saturating_add(max_bytes));
let bytes = payload[offset..end].to_vec();
MemcardReadResult { status: MemcardStatus::Ok, bytes_read: bytes.len() as u32, bytes }
}
fn load_committed(
&self,
fs: &VirtualFS,
app_id: u32,
slot: u8,
) -> Result<Option<SlotImage>, MemcardStatus> {
let path = slot_path(app_id, slot);
match fs.read_file(&path) {
Ok(bytes) => decode_slot_file(&bytes).map(Some),
Err(FsError::NotFound) => Ok(None),
Err(err) => Err(map_fs_error(err)),
}
}
}
fn slot_path(app_id: u32, slot: u8) -> String {
format!("/user/games/{}/memcard/slot_{:02}.pmem", app_id, slot)
}
fn map_fs_error(err: FsError) -> MemcardStatus {
match err {
FsError::NotFound => MemcardStatus::NotFound,
FsError::AlreadyExists => MemcardStatus::Conflict,
FsError::PermissionDenied => MemcardStatus::AccessDenied,
FsError::NotMounted | FsError::IOError(_) | FsError::Other(_) | FsError::InvalidPath(_) => {
MemcardStatus::Unavailable
}
}
}
fn checksum32(data: &[u8]) -> u32 {
let mut a: u32 = 1;
let mut b: u32 = 0;
const MOD: u32 = 65521;
for &byte in data {
a = (a + byte as u32) % MOD;
b = (b + a) % MOD;
}
(b << 16) | a
}
fn make_save_uuid(app_id: u32, slot: u8) -> [u8; 16] {
let mut out = [0u8; 16];
out[0..4].copy_from_slice(&app_id.to_le_bytes());
out[4] = slot;
out[5..13].copy_from_slice(
&(std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.map(|d| d.as_nanos() as u64)
.unwrap_or(0))
.to_le_bytes(),
);
out[13] = 0x50;
out[14] = 0x4D;
out[15] = 0x31;
out
}
fn encode_slot_file(slot: SlotImage) -> Vec<u8> {
let mut out = Vec::with_capacity(SLOT_HEADER_SIZE + slot.payload.len());
out.extend_from_slice(SLOT_FILE_MAGIC);
out.push(SLOT_FILE_VERSION);
out.extend_from_slice(&slot.save_uuid);
out.extend_from_slice(&slot.generation.to_le_bytes());
out.extend_from_slice(&slot.checksum.to_le_bytes());
out.extend_from_slice(&(slot.payload.len() as u32).to_le_bytes());
out.extend_from_slice(&slot.payload);
out
}
fn decode_slot_file(bytes: &[u8]) -> Result<SlotImage, MemcardStatus> {
if bytes.len() < SLOT_HEADER_SIZE {
return Err(MemcardStatus::Corrupt);
}
if &bytes[0..4] != SLOT_FILE_MAGIC {
return Err(MemcardStatus::Corrupt);
}
if bytes[4] != SLOT_FILE_VERSION {
return Err(MemcardStatus::Corrupt);
}
let mut save_uuid = [0u8; 16];
save_uuid.copy_from_slice(&bytes[5..21]);
let generation =
u64::from_le_bytes(bytes[21..29].try_into().map_err(|_| MemcardStatus::Corrupt)?);
let checksum =
u32::from_le_bytes(bytes[29..33].try_into().map_err(|_| MemcardStatus::Corrupt)?);
let payload_size =
u32::from_le_bytes(bytes[33..37].try_into().map_err(|_| MemcardStatus::Corrupt)?) as usize;
if payload_size > MEMCARD_SLOT_CAPACITY_BYTES {
return Err(MemcardStatus::Corrupt);
}
if bytes.len() != SLOT_HEADER_SIZE + payload_size {
return Err(MemcardStatus::Corrupt);
}
let payload = bytes[SLOT_HEADER_SIZE..].to_vec();
if checksum32(&payload) != checksum {
return Err(MemcardStatus::Corrupt);
}
Ok(SlotImage { payload, generation, checksum, save_uuid })
}
#[cfg(test)]
mod tests {
use super::*;
use crate::fs::{FsBackend, FsEntry};
use std::collections::HashMap;
struct MockBackend {
files: HashMap<String, Vec<u8>>,
}
impl MockBackend {
fn new() -> Self {
Self { files: HashMap::new() }
}
}
impl FsBackend for MockBackend {
fn mount(&mut self) -> Result<(), FsError> {
Ok(())
}
fn unmount(&mut self) {}
fn list_dir(&self, _path: &str) -> Result<Vec<FsEntry>, FsError> {
Ok(Vec::new())
}
fn read_file(&self, path: &str) -> Result<Vec<u8>, FsError> {
self.files.get(path).cloned().ok_or(FsError::NotFound)
}
fn write_file(&mut self, path: &str, data: &[u8]) -> Result<(), FsError> {
self.files.insert(path.to_string(), data.to_vec());
Ok(())
}
fn delete(&mut self, path: &str) -> Result<(), FsError> {
self.files.remove(path).map(|_| ()).ok_or(FsError::NotFound)
}
fn exists(&self, path: &str) -> bool {
self.files.contains_key(path)
}
fn is_healthy(&self) -> bool {
true
}
}
#[test]
fn slot_roundtrip_commit_and_generation() {
let mut fs = VirtualFS::new();
fs.mount(Box::new(MockBackend::new())).expect("mount");
let mut mem = MemcardService::new();
let write = mem.slot_write(&fs, 10, 0, 0, b"hello");
assert_eq!(write.status, MemcardStatus::Ok);
assert_eq!(write.bytes_written, 5);
let staged = mem.slot_stat(&fs, 10, 0);
assert_eq!(staged.state, MemcardSlotState::Staged);
assert_eq!(staged.generation, 1);
assert_eq!(mem.slot_commit(&mut fs, 10, 0), MemcardStatus::Ok);
let committed = mem.slot_stat(&fs, 10, 0);
assert_eq!(committed.state, MemcardSlotState::Committed);
assert_eq!(committed.generation, 1);
let write2 = mem.slot_write(&fs, 10, 0, 5, b"!");
assert_eq!(write2.status, MemcardStatus::Ok);
assert_eq!(mem.slot_commit(&mut fs, 10, 0), MemcardStatus::Ok);
let committed2 = mem.slot_stat(&fs, 10, 0);
assert_eq!(committed2.generation, 2);
let read = mem.slot_read(&fs, 10, 0, 0, 10);
assert_eq!(read.status, MemcardStatus::Ok);
assert_eq!(read.bytes, b"hello!");
assert_eq!(read.bytes_read, 6);
}
#[test]
fn slot_clear_missing_is_empty() {
let mut fs = VirtualFS::new();
fs.mount(Box::new(MockBackend::new())).expect("mount");
let mut mem = MemcardService::new();
assert_eq!(mem.slot_clear(&mut fs, 1, 1), MemcardStatus::Empty);
}
#[test]
fn slot_stat_reports_corruption() {
let mut fs = VirtualFS::new();
let mut backend = MockBackend::new();
backend.files.insert(slot_path(7, 2), vec![0, 1, 2, 3, 4]);
fs.mount(Box::new(backend)).expect("mount");
let mem = MemcardService::new();
let stat = mem.slot_stat(&fs, 7, 2);
assert_eq!(stat.state, MemcardSlotState::Corrupt);
}
#[test]
fn memcard_async_lane_operations_classify_priority_without_changing_public_api() {
assert_eq!(MemcardAsyncLaneOperation::SlotWrite.job_kind(), AsyncWorkJobKind::Memcard);
assert_eq!(
MemcardAsyncLaneOperation::SlotWrite.priority(),
AsyncWorkPriority::MemcardCommitWrite
);
assert_eq!(
MemcardAsyncLaneOperation::SlotCommit.priority(),
AsyncWorkPriority::MemcardCommitWrite
);
assert_eq!(
MemcardAsyncLaneOperation::SlotClear.priority(),
AsyncWorkPriority::MemcardCommitWrite
);
assert_eq!(
MemcardAsyncLaneOperation::SlotRead.priority(),
AsyncWorkPriority::NonCriticalReadList
);
assert_eq!(
MemcardAsyncLaneOperation::SlotStat.priority(),
AsyncWorkPriority::NonCriticalReadList
);
}
}
@@ -0,0 +1,363 @@
//! External SO/Hub choices prepare the snapshot before any game boot execution.
use super::{
MemcardService,
image::*,
session::Session,
transaction::{Card, PublicationControl},
};
use prometeu_hal::memcard::MemcardStorage;
use std::sync::{Arc, Mutex, mpsc};
use std::time::{Duration, Instant};
pub const DEFAULT_SNAPSHOT_BUDGET: usize = 5 * 1024 * 1024;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Choice {
Persistent,
MemoryFresh,
MemoryExisting,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum PreparationState {
Idle,
Pending,
Ready,
Failed(Error),
}
enum Prepared {
Card(Result<Card>),
Session(Session, Result<()>),
Replacement(Session, Result<()>),
Maintenance(Card, Result<()>),
}
pub struct Admission {
installed: Option<Card>,
receiver: Option<mpsc::Receiver<Prepared>>,
admitted: Option<Instant>,
control: Option<Arc<PublicationControl>>,
pub state: PreparationState,
pub snapshot_budget: usize,
faulted: bool,
}
impl Default for Admission {
fn default() -> Self {
Self {
installed: None,
receiver: None,
admitted: None,
control: None,
state: PreparationState::Idle,
snapshot_budget: DEFAULT_SNAPSHOT_BUDGET,
faulted: false,
}
}
}
impl MemcardService {
pub fn host_faulted(&self) -> bool {
self.admission.faulted || self.session.host_faulted()
}
pub fn card_installed(&self) -> bool {
self.admission.installed.is_some()
}
pub fn installed_health(&self) -> Option<(bool, bool, bool)> {
self.admission.installed.as_ref().map(|card| {
(card.recovered, card.degraded, card.write_blocked || card.storage_read_only())
})
}
pub fn card_has_game(&self, app_id: u32) -> bool {
self.admission
.installed
.as_ref()
.is_some_and(|c| c.catalog.games.iter().any(|g| g.app_id == app_id))
}
pub fn uninstall_card(&mut self) -> Result<()> {
if self.session.mode().is_some()
|| self.session.has_in_flight()
|| self.admission.receiver.is_some()
{
return Err(Error::Busy);
}
self.admission.installed = None;
self.admission.state = PreparationState::Idle;
Ok(())
}
pub fn mount_card(&mut self, storage: Box<dyn MemcardStorage>) -> Result<()> {
self.mount_card_with(move || Ok(storage))
}
pub fn mount_card_with(
&mut self,
open: impl FnOnce() -> Result<Box<dyn MemcardStorage>> + Send + 'static,
) -> Result<()> {
if self.admission.installed.is_some()
|| self.admission.receiver.is_some()
|| self.session.mode().is_some()
|| self.session.has_in_flight()
{
return Err(Error::Busy);
}
if self.admission.faulted {
return Err(Error::ReadOnly);
}
let (tx, rx) = mpsc::channel();
self.lane
.submit_memcard_commit_write(move |_| {
let _ = tx.send(Prepared::Card(open().and_then(Card::mount)));
crate::AsyncWorkJobOutcome::Completed
})
.map_err(|_| Error::InvalidState)?;
self.admission.receiver = Some(rx);
self.admission.admitted = Some(Instant::now());
self.admission.state = PreparationState::Pending;
Ok(())
}
pub fn choose_for_game(
&mut self,
app_id: u32,
count: usize,
choice: Choice,
created_at: u64,
) -> Result<()> {
if self.admission.receiver.is_some()
|| self.session.mode().is_some()
|| self.session.has_in_flight()
{
return Err(Error::Busy);
}
if self.admission.faulted {
return Err(Error::ReadOnly);
}
if choice != Choice::MemoryFresh && self.admission.installed.is_none() {
return Err(Error::InvalidState);
}
if Session::required_bytes(count)? > self.admission.snapshot_budget {
return Err(Error::OutOfMemory);
}
if let Some(card) = &self.admission.installed {
let owned =
card.catalog.games.iter().find(|g| g.app_id == app_id).map_or(0, |g| g.slots.len());
if choice == Choice::Persistent {
if card.storage_read_only() || card.write_blocked {
return Err(Error::ReadOnly);
}
if count.saturating_sub(owned)
> card.current().slots.iter().filter(|s| !s.assigned).count()
{
return Err(Error::NoSpace);
}
}
if choice == Choice::MemoryExisting && owned == 0 {
return Err(Error::InvalidState);
}
}
let handoff = Arc::new(Mutex::new(self.admission.installed.take()));
let worker_handoff = handoff.clone();
let control = Arc::new(PublicationControl::default());
let worker_control = control.clone();
let budget = self.admission.snapshot_budget;
let (tx, rx) = mpsc::channel();
let submitted = self.lane.submit_memcard_commit_write(move |_| {
let mut card = worker_handoff.lock().unwrap().take();
let mut session = Session::default();
let result = (|| {
if worker_control.canceled() {
session.retain_idle_card_opt(card.take());
return Err(Error::Canceled);
}
match choice {
Choice::MemoryFresh => {
session.start_memory_with_card(app_id, count, budget, card.take())?;
}
Choice::MemoryExisting => {
session.load_card_memory(card.take().unwrap(), app_id, count, budget)?;
}
Choice::Persistent => {
let mut card = card.take().unwrap();
if card.storage_read_only() || card.write_blocked {
session.retain_idle_card(card);
return Err(Error::ReadOnly);
}
if card.catalog.games.iter().any(|g| g.app_id == app_id) {
if let Err(e) = card.grow(app_id, count, &worker_control) {
session.retain_idle_card(card);
return Err(e);
}
session.load_card(card, app_id, count, budget)?;
} else {
session.prepare_new_card(card, app_id, count, created_at, budget)?;
}
}
}
session.begin_boot();
Ok(())
})();
let _ = tx.send(Prepared::Session(session, result));
crate::AsyncWorkJobOutcome::Completed
});
if submitted.is_err() {
self.admission.installed = handoff.lock().unwrap().take();
return Err(Error::InvalidState);
}
self.admission.control = Some(control);
self.admission.receiver = Some(rx);
self.admission.admitted = Some(Instant::now());
self.admission.state = PreparationState::Pending;
Ok(())
}
/// Whole-game removal is only available outside a resident game session.
pub fn remove_game(&mut self, app_id: u32) -> Result<()> {
self.maintain_card(move |card, control| card.remove_game(app_id, control))
}
pub fn revalidate_card(&mut self) -> Result<()> {
self.maintain_card(|card, control| card.revalidate(control))
}
pub fn reintegrate_block(&mut self, block: u8) -> Result<()> {
self.maintain_card(move |card, control| card.reintegrate(block, control))
}
fn maintain_card(
&mut self,
operation: impl FnOnce(&mut Card, &PublicationControl) -> Result<()> + Send + 'static,
) -> Result<()> {
if self.admission.receiver.is_some()
|| self.session.mode().is_some()
|| self.session.has_in_flight()
{
return Err(Error::Busy);
}
if self.admission.faulted {
return Err(Error::ReadOnly);
}
let card = self.admission.installed.take().ok_or(Error::InvalidState)?;
let handoff = Arc::new(Mutex::new(Some(card)));
let worker = handoff.clone();
let control = Arc::new(PublicationControl::default());
let worker_control = control.clone();
let (tx, rx) = mpsc::channel();
if self
.lane
.submit_memcard_commit_write(move |_| {
let mut card = worker.lock().unwrap().take().unwrap();
let result = operation(&mut card, &worker_control);
let _ = tx.send(Prepared::Maintenance(card, result));
crate::AsyncWorkJobOutcome::Completed
})
.is_err()
{
self.admission.installed = handoff.lock().unwrap().take();
return Err(Error::InvalidState);
}
self.admission.control = Some(control);
self.admission.receiver = Some(rx);
self.admission.admitted = Some(Instant::now());
self.admission.state = PreparationState::Pending;
Ok(())
}
/// Caller must suspend gameplay and obtain the player's keep-RAM/load-existing choice.
/// Once admitted, the resident continuation must wait for `PreparationState::Ready`.
pub fn replace_card(
&mut self,
storage: Box<dyn MemcardStorage>,
load_existing: bool,
) -> Result<()> {
if self.admission.receiver.is_some()
|| self.session.has_in_flight()
|| self.session.is_boot_active()
{
return Err(Error::Busy);
}
if self.admission.faulted {
return Err(Error::ReadOnly);
}
let handoff = Arc::new(Mutex::new(Some(std::mem::take(&mut self.session))));
let worker = handoff.clone();
let control = Arc::new(PublicationControl::default());
let worker_control = control.clone();
let (tx, rx) = mpsc::channel();
if self
.lane
.submit_memcard_commit_write(move |_| {
let mut session = worker.lock().unwrap().take().unwrap();
let result = session.replace_storage(storage, load_existing, &worker_control);
let _ = tx.send(Prepared::Replacement(session, result));
crate::AsyncWorkJobOutcome::Completed
})
.is_err()
{
self.session = handoff.lock().unwrap().take().unwrap();
return Err(Error::InvalidState);
}
self.admission.control = Some(control);
self.admission.receiver = Some(rx);
self.admission.admitted = Some(Instant::now());
self.admission.state = PreparationState::Pending;
Ok(())
}
pub fn poll(&mut self, now: Instant) {
self.session.poll(now);
if let Some(rx) = &self.admission.receiver {
match rx.try_recv() {
Ok(prepared) => {
if !self.admission.faulted {
self.admission.state = match prepared {
Prepared::Card(Ok(card)) => {
self.admission.installed = Some(card);
PreparationState::Ready
}
Prepared::Maintenance(card, result) => {
self.admission.installed = Some(card);
match result {
Ok(()) => PreparationState::Ready,
Err(e) => PreparationState::Failed(e),
}
}
Prepared::Replacement(session, result) => {
self.session = session;
match result {
Ok(()) => PreparationState::Ready,
Err(e) => PreparationState::Failed(e),
}
}
Prepared::Session(session, Ok(())) => {
self.session = session;
PreparationState::Ready
}
Prepared::Card(Err(e)) => PreparationState::Failed(e),
Prepared::Session(mut session, Err(e)) => {
session.end_session();
self.admission.installed = session.take_idle_card().ok().flatten();
PreparationState::Failed(e)
}
};
} else if let Prepared::Replacement(session, _) = prepared {
self.session = session;
}
self.admission.receiver = None;
self.admission.control = None;
}
Err(mpsc::TryRecvError::Disconnected) => {
self.admission.state = PreparationState::Failed(Error::InvalidState);
self.admission.receiver = None;
}
Err(mpsc::TryRecvError::Empty) => {
if self.admission.admitted.is_some_and(|at| {
now.saturating_duration_since(at) >= Duration::from_millis(500)
}) && let Some(control) = &self.admission.control
{
control.cancel();
}
if self.admission.admitted.is_some_and(|at| {
now.saturating_duration_since(at) >= Duration::from_secs(1)
}) {
self.admission.faulted = true;
self.admission.state = PreparationState::Failed(Error::Indeterminate);
}
}
}
}
if self.session.mode().is_none()
&& !self.session.has_in_flight()
&& self.admission.installed.is_none()
&& let Ok(card) = self.session.take_idle_card()
{
self.admission.installed = card;
}
}
}
@@ -0,0 +1,256 @@
//! Guest mem ABI. Only bounded copies cross the VM/native ownership boundary.
use super::{
MemcardService,
image::Error,
session::{Mode, RequestReason, RequestState},
};
use prometeu_bytecode::{HeapRef, TRAP_OOB, TRAP_TYPE, Value};
use prometeu_hal::{HostReturn, expect_int, syscalls::Syscall, vm_fault::VmFault};
use std::time::Instant;
fn index(args: &[Value], n: usize) -> Result<usize, VmFault> {
usize::try_from(expect_int(args, n)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Negative memcard range".into()))
}
fn opaque(args: &[Value], n: usize) -> Result<u64, VmFault> {
u64::try_from(expect_int(args, n)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Negative memcard identity".into()))
}
fn handle(args: &[Value], n: usize) -> Result<HeapRef, VmFault> {
match args.get(n) {
Some(Value::HeapRef(h)) => Ok(*h),
_ => Err(VmFault::Trap(TRAP_TYPE, "Expected Array<Int32>".into())),
}
}
fn text(args: &[Value], n: usize) -> Result<&str, VmFault> {
match args.get(n) {
Some(Value::String(s)) => Ok(s),
_ => Err(VmFault::Trap(TRAP_TYPE, "Expected String".into())),
}
}
pub fn status(e: Error) -> i64 {
use prometeu_hal::memcard::MemcardIoError as I;
match e {
Error::NoSpace | Error::Io(I::NoSpace) => 3,
Error::AccessDenied => 4,
Error::Corrupt => 5,
Error::Indeterminate => 6,
Error::Io(I::Unavailable) => 7,
Error::InvalidState | Error::Canceled => 8,
Error::Busy => 9,
Error::ReadOnly | Error::CounterExhausted | Error::Io(I::ReadOnly) => 10,
Error::InvalidRange | Error::Io(I::InvalidRange) => 11,
Error::Unsupported | Error::Io(I::Unsupported) => 12,
Error::Io(I::IoError) => 13,
Error::OutOfMemory => 16,
}
}
fn error(ret: &mut HostReturn, syscall: Syscall, e: Error) {
ret.push_int(status(e));
for _ in 1..syscall.results_count() {
ret.push_null();
}
}
impl MemcardService {
pub fn guest(
&mut self,
syscall: Syscall,
args: &[Value],
ret: &mut HostReturn,
app_id: u32,
timestamp: u64,
game_profile: bool,
) -> Result<(), VmFault> {
let authorized = game_profile && self.session.app_id() == Some(app_id);
if syscall == Syscall::MemBootstrap {
if !authorized || !self.session.is_boot_active() {
return Err(VmFault::Trap(
TRAP_TYPE,
"Memcard snapshot is not admitted for bootstrap".into(),
));
}
ret.push_int(self.session.context() as i64);
return Ok(());
}
let context = opaque(args, 0)?;
if !authorized || context != self.session.context() {
error(ret, syscall, Error::AccessDenied);
return Ok(());
}
match syscall {
Syscall::MemSlotCount => {
ret.push_int(0);
ret.push_int(self.session.count() as i64);
}
Syscall::MemSlotStat => match self.session.descriptor(context, index(args, 1)?) {
Ok((d, used, dirty)) => {
ret.push_int(0);
ret.push_int(i64::from(used > 0));
ret.push_int(used as i64);
ret.push_int(d.generation as i64);
ret.push_int(d.update_at as i64);
ret.push_int(d.crc as i64);
ret.push_bool(dirty);
}
Err(e) => error(ret, syscall, e),
},
Syscall::MemSlotRead | Syscall::MemSlotWrite => {
let local = index(args, 1)?;
let offset = index(args, 2)?;
let array = handle(args, 3)?;
let array_offset = index(args, 4)?;
let count = index(args, 5)?;
if count > 4096 {
return Err(VmFault::Trap(
TRAP_OOB,
"Memcard transfer exceeds 4096 bytes".into(),
));
}
if let Err(e) = self.session.descriptor(context, local) {
error(ret, syscall, e);
return Ok(());
}
if offset.checked_add(count).is_none_or(|end| end > 65536) {
error(ret, syscall, Error::InvalidRange);
return Ok(());
}
ret.byte_arrays()?.validate(array, array_offset, count)?;
let mut bytes = [0; 4096];
if syscall == Syscall::MemSlotRead {
match self.session.read(context, local, offset, &mut bytes[..count]) {
Ok(n) => {
ret.byte_arrays()?.write(array, array_offset, &bytes[..n])?;
ret.push_int(0);
ret.push_int(n as i64)
}
Err(e) => error(ret, syscall, e),
}
} else {
ret.byte_arrays()?.read(array, array_offset, &mut bytes[..count])?;
match self.session.write(context, local, offset, &bytes[..count]) {
Ok(()) => {
ret.push_int(0);
ret.push_int(count as i64)
}
Err(e) => error(ret, syscall, e),
}
}
}
Syscall::MemSlotCommit => {
match self.session.commit(
context,
index(args, 1)?,
timestamp,
Instant::now(),
&self.lane,
) {
Ok(id) => {
ret.push_int(0);
ret.push_int(id as i64)
}
Err(e) => error(ret, syscall, e),
}
}
Syscall::MemSlotClear => match self.session.clear(context, index(args, 1)?) {
Ok(()) => ret.push_int(0),
Err(e) => error(ret, syscall, e),
},
Syscall::MemQuery => match self.session.query(context, opaque(args, 1)?) {
Ok(r) => {
ret.push_int(0);
ret.push_int(match r.state {
RequestState::Pending => 0,
RequestState::Success => 1,
RequestState::Failure => 2,
RequestState::Indeterminate => 3,
RequestState::MemoryOnly => 4,
});
ret.push_int(match r.reason {
RequestReason::None => 0,
RequestReason::Storage(e) => status(e),
RequestReason::Timeout | RequestReason::RestartRequired => 15,
});
}
Err(e) => error(ret, syscall, e),
},
Syscall::MemRelease => match self.session.release_request(context, opaque(args, 1)?) {
Ok(()) => ret.push_int(0),
Err(e) => error(ret, syscall, e),
},
Syscall::MemInfo => {
ret.push_int(0);
ret.push_int(i64::from(self.session.mode() == Some(Mode::MemoryOnly)));
ret.push_bool(self.session.is_new());
let (recovered, degraded, blocked) = self.session.health();
ret.push_bool(recovered);
ret.push_bool(degraded);
ret.push_bool(blocked);
}
Syscall::MemMetadata => match self.session.presentation(context) {
Ok(Some(g)) => {
ret.push_int(0);
ret.push_string(&g.title)?;
ret.push_int(g.data_format_version as i64);
ret.push_int(g.created_at as i64)
}
Ok(None) => {
ret.push_int(0);
ret.push_string("")?;
ret.push_int(0);
ret.push_int(timestamp as i64)
}
Err(e) => error(ret, syscall, e),
},
Syscall::MemPresentation => {
let title = text(args, 1)?;
let version = u32::try_from(index(args, 2)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Invalid dataFormatVersion".into()))?;
let frames = u8::try_from(index(args, 3)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Invalid icon frames".into()))?;
let duration = u16::try_from(index(args, 4)?)
.map_err(|_| VmFault::Trap(TRAP_OOB, "Invalid icon duration".into()))?;
let array = handle(args, 5)?;
let offset = index(args, 6)?;
let count = index(args, 7)?;
if count > 2096 || title.len() > 128 {
error(ret, syscall, Error::InvalidRange);
return Ok(());
}
let mut bytes = [0; 2096];
ret.byte_arrays()?.read(array, offset, &mut bytes[..count])?;
match self.session.set_presentation(
context,
title,
version,
frames,
duration,
&bytes[..count],
timestamp,
) {
Ok(()) => ret.push_int(0),
Err(e) => error(ret, syscall, e),
}
}
Syscall::MemDiagnostic => {
let message = text(args, 1)?;
if message.len() > 1024 {
error(ret, syscall, Error::InvalidRange)
} else {
self.diagnostic.clear();
self.diagnostic.push_str(message);
ret.push_int(0)
}
}
Syscall::MemPublishPresentation => {
match self.session.publish_presentation(context, &self.lane, Instant::now()) {
Ok(id) => {
ret.push_int(0);
ret.push_int(id as i64)
}
Err(e) => error(ret, syscall, e),
}
}
_ => return Err(VmFault::Trap(TRAP_TYPE, "Invalid memcard operation".into())),
}
Ok(())
}
}
@@ -0,0 +1,452 @@
//! Fixed shared-card codec. All offsets and CRC coverage are defined in the save spec.
use prometeu_hal::memcard::{MemcardIoError, MemcardStorage};
use serde::{Deserialize, Serialize};
pub const SLOT_COUNT: usize = 64;
pub const BLOCK_COUNT: usize = 68;
pub const SLOT_BYTES: usize = 65_536;
pub const PAGE_BYTES: usize = 4096;
pub const CATALOG_BYTES: usize = 131_072;
pub const ICON_BYTES: usize = 262_144;
pub const CATALOG_OFFSETS: [u64; 2] = [16_384, 409_600];
pub const ICON_OFFSETS: [u64; 2] = [147_456, 540_672];
pub const MAP_OFFSETS: [u64; 2] = [8192, 12_288];
pub const DATA_OFFSET: u64 = 802_816;
pub const IMAGE_BYTES: u64 = DATA_OFFSET + (BLOCK_COUNT * SLOT_BYTES) as u64;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Error {
Io(MemcardIoError),
Corrupt,
Unsupported,
NoSpace,
InvalidRange,
CounterExhausted,
ReadOnly,
Indeterminate,
Busy,
Canceled,
OutOfMemory,
AccessDenied,
InvalidState,
}
impl From<MemcardIoError> for Error {
fn from(e: MemcardIoError) -> Self {
Self::Io(e)
}
}
pub type Result<T> = std::result::Result<T, Error>;
pub fn crc32c(bytes: &[u8]) -> u32 {
crc_extend(!0, bytes) ^ !0
}
pub fn crc_extend(mut crc: u32, bytes: &[u8]) -> u32 {
for &byte in bytes {
crc ^= byte as u32;
for _ in 0..8 {
crc = (crc >> 1) ^ (0x82f6_3b78 & 0u32.wrapping_sub(crc & 1));
}
}
crc
}
fn u32_at(b: &[u8], p: usize) -> u32 {
u32::from_le_bytes(b[p..p + 4].try_into().unwrap())
}
fn u64_at(b: &[u8], p: usize) -> u64 {
u64::from_le_bytes(b[p..p + 8].try_into().unwrap())
}
fn put32(b: &mut [u8], p: usize, n: u32) {
b[p..p + 4].copy_from_slice(&n.to_le_bytes());
}
fn put64(b: &mut [u8], p: usize, n: u64) {
b[p..p + 8].copy_from_slice(&n.to_le_bytes());
}
fn zero(b: &[u8]) -> Result<()> {
if b.iter().any(|&v| v != 0) { Err(Error::Corrupt) } else { Ok(()) }
}
fn page_crc(b: &[u8; PAGE_BYTES]) -> Result<()> {
if crc32c(&b[..4092]) != u32_at(b, 4092) {
return Err(Error::Corrupt);
}
Ok(())
}
fn seal(b: &mut [u8; PAGE_BYTES]) {
let crc = crc32c(&b[..4092]);
put32(b, 4092, crc);
}
pub fn identity_page(id: [u8; 16]) -> [u8; PAGE_BYTES] {
let mut b = [0; PAGE_BYTES];
b[..8].copy_from_slice(b"PMCARD1\0");
put32(&mut b, 8, 1);
put32(&mut b, 12, IMAGE_BYTES as u32);
b[16..32].copy_from_slice(&id);
seal(&mut b);
b
}
pub fn decode_identity(b: &[u8; PAGE_BYTES]) -> Result<[u8; 16]> {
if &b[..8] != b"PMCARD1\0" || u32_at(b, 8) != 1 {
return Err(Error::Unsupported);
}
page_crc(b)?;
if u32_at(b, 12) != IMAGE_BYTES as u32 {
return Err(Error::Corrupt);
}
zero(&b[32..4092])?;
Ok(b[16..32].try_into().unwrap())
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Icon {
pub offset: u32,
pub frames: u8,
pub duration: u16,
pub crc32c: u32,
}
impl Icon {
pub fn length(&self) -> Result<usize> {
if !(1..=4).contains(&self.frames)
|| self.duration == 0
|| (self.frames == 1 && self.duration != 1)
{
return Err(Error::Corrupt);
}
Ok(48 + 512 * self.frames as usize)
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Game {
pub app_id: u32,
pub title: String,
#[serde(rename = "dataFormatVersion")]
pub data_format_version: u32,
pub created_at: u64,
pub slots: Vec<u8>,
pub icon: Icon,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Catalog {
#[serde(rename = "metadataVersion")]
pub metadata_version: u32,
pub games: Vec<Game>,
}
impl Default for Catalog {
fn default() -> Self {
Self { metadata_version: 1, games: Vec::new() }
}
}
impl Catalog {
pub fn validate(&self, icons_used: usize) -> Result<[bool; SLOT_COUNT]> {
if self.metadata_version != 1 || self.games.len() > 64 || icons_used > ICON_BYTES {
return Err(Error::Corrupt);
}
let mut assigned = [false; SLOT_COUNT];
let mut spans = Vec::with_capacity(64);
for (index, g) in self.games.iter().enumerate() {
if g.title.trim().is_empty()
|| g.title.len() > 128
|| g.slots.is_empty()
|| g.slots.len() > 64
|| self.games[..index].iter().any(|prior| prior.app_id == g.app_id)
{
return Err(Error::Corrupt);
}
for &slot in &g.slots {
let used = assigned.get_mut(slot as usize).ok_or(Error::Corrupt)?;
if *used {
return Err(Error::Corrupt);
}
*used = true;
}
let start = g.icon.offset as usize;
let end = start.checked_add(g.icon.length()?).ok_or(Error::Corrupt)?;
if end > icons_used || spans.iter().any(|&(a, b)| start < b && a < end) {
return Err(Error::Corrupt);
}
spans.push((start, end));
}
Ok(assigned)
}
pub fn encode(&self, icons_used: usize) -> Result<Vec<u8>> {
self.validate(icons_used)?;
let b = serde_json::to_vec(self).map_err(|_| Error::Corrupt)?;
if b.len() > CATALOG_BYTES {
return Err(Error::NoSpace);
}
Ok(b)
}
pub fn decode(b: &[u8], icons_used: usize) -> Result<Self> {
if b.len() > CATALOG_BYTES {
return Err(Error::Corrupt);
}
// Bound nesting before serde; strings (including escaped quotes) do not count.
let (mut depth, mut quoted, mut escaped) = (0u8, false, false);
for &v in b {
if quoted {
if escaped {
escaped = false;
} else if v == b'\\' {
escaped = true;
} else if v == b'"' {
quoted = false;
}
} else {
match v {
b'"' => quoted = true,
b'[' | b'{' => {
depth = depth.checked_add(1).ok_or(Error::Corrupt)?;
if depth > 8 {
return Err(Error::Corrupt);
}
}
b']' | b'}' => depth = depth.checked_sub(1).ok_or(Error::Corrupt)?,
_ => {}
}
}
}
let catalog: Self = serde_json::from_slice(b).map_err(|_| Error::Corrupt)?;
catalog.validate(icons_used)?;
Ok(catalog)
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct Slot {
pub assigned: bool,
pub block: Option<u8>,
pub used: u32,
pub generation: u64,
pub update_at: u64,
pub crc: u32,
}
impl Slot {
fn validate(&self) -> Result<()> {
if !self.assigned && *self != Self::default() {
return Err(Error::Corrupt);
}
if self.generation == 0 && (self.update_at != 0 || self.block.is_some()) {
return Err(Error::Corrupt);
}
match self.block {
Some(id)
if id as usize >= BLOCK_COUNT
|| self.used == 0
|| self.used as usize > SLOT_BYTES =>
{
Err(Error::Corrupt)
}
None if self.used != 0 || self.crc != 0 => Err(Error::Corrupt),
_ => Ok(()),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Map {
pub card_id: [u8; 16],
pub sequence: u64,
pub public_copy: usize,
pub catalog_len: u32,
pub catalog_crc: u32,
pub icons_len: u32,
pub icons_crc: u32,
pub order: [u8; BLOCK_COUNT],
pub quarantine: [bool; BLOCK_COUNT],
pub slots: [Slot; SLOT_COUNT],
}
impl Map {
pub fn new(card_id: [u8; 16]) -> Self {
Self {
card_id,
sequence: 1,
public_copy: 0,
catalog_len: 0,
catalog_crc: 0,
icons_len: 0,
icons_crc: 0,
order: std::array::from_fn(|i| i as u8),
quarantine: [false; BLOCK_COUNT],
slots: [Slot::default(); SLOT_COUNT],
}
}
pub fn encode(&self) -> Result<[u8; PAGE_BYTES]> {
if self.sequence == 0
|| self.public_copy > 1
|| self.catalog_len as usize > CATALOG_BYTES
|| self.icons_len as usize > ICON_BYTES
{
return Err(Error::Corrupt);
}
let mut seen = [false; BLOCK_COUNT];
for &id in &self.order {
let v = seen.get_mut(id as usize).ok_or(Error::Corrupt)?;
if *v {
return Err(Error::Corrupt);
}
*v = true;
}
let mut owned = [false; BLOCK_COUNT];
let mut b = [0; PAGE_BYTES];
b[..8].copy_from_slice(b"PMMAP1\0\0");
put64(&mut b, 8, self.sequence);
put32(&mut b, 16, self.public_copy as u32);
put32(&mut b, 20, self.catalog_len);
put32(&mut b, 24, self.catalog_crc);
put32(&mut b, 28, self.icons_len);
put32(&mut b, 32, self.icons_crc);
b[36..52].copy_from_slice(&self.card_id);
b[64..132].copy_from_slice(&self.order);
for i in 0..BLOCK_COUNT {
b[132 + i] = self.quarantine[i] as u8;
}
for (i, s) in self.slots.iter().enumerate() {
s.validate()?;
if let Some(id) = s.block {
if owned[id as usize] || self.quarantine[id as usize] {
return Err(Error::Corrupt);
}
owned[id as usize] = true;
}
let p = 256 + i * 40;
b[p] = if !s.assigned {
0
} else if s.block.is_none() {
1
} else {
2
};
b[p + 1] = s.block.unwrap_or(255);
put32(&mut b, p + 4, s.used);
put64(&mut b, p + 8, s.generation);
put64(&mut b, p + 16, s.update_at);
put32(&mut b, p + 24, s.crc);
}
seal(&mut b);
Ok(b)
}
pub fn decode(b: &[u8; PAGE_BYTES], card_id: [u8; 16]) -> Result<Self> {
page_crc(b)?;
if &b[..8] != b"PMMAP1\0\0" || b[36..52] != card_id {
return Err(Error::Corrupt);
}
zero(&b[52..64])?;
zero(&b[200..256])?;
zero(&b[2816..4092])?;
let mut m = Self::new(card_id);
m.sequence = u64_at(b, 8);
m.public_copy = u32_at(b, 16) as usize;
m.catalog_len = u32_at(b, 20);
m.catalog_crc = u32_at(b, 24);
m.icons_len = u32_at(b, 28);
m.icons_crc = u32_at(b, 32);
m.order.copy_from_slice(&b[64..132]);
for i in 0..BLOCK_COUNT {
if b[132 + i] > 1 {
return Err(Error::Corrupt);
}
m.quarantine[i] = b[132 + i] != 0;
}
for i in 0..SLOT_COUNT {
let p = 256 + i * 40;
zero(&b[p + 2..p + 4])?;
zero(&b[p + 28..p + 40])?;
if b[p] > 2 || (b[p] != 2 && b[p + 1] != 255) || (b[p] == 2 && b[p + 1] == 255) {
return Err(Error::Corrupt);
}
m.slots[i] = Slot {
assigned: b[p] != 0,
block: if b[p] == 2 { Some(b[p + 1]) } else { None },
used: u32_at(b, p + 4),
generation: u64_at(b, p + 8),
update_at: u64_at(b, p + 16),
crc: u32_at(b, p + 24),
};
}
if m.encode()? != *b {
return Err(Error::Corrupt);
}
Ok(m)
}
pub fn game_update_at(&self, game: &Game) -> Option<u64> {
game.slots
.iter()
.filter_map(|&i| self.slots.get(i as usize))
.filter(|s| s.generation > 0)
.map(|s| s.update_at)
.max()
}
}
pub fn read_region(io: &mut dyn MemcardStorage, offset: u64, out: &mut [u8]) -> Result<()> {
for (i, b) in out.chunks_mut(SLOT_BYTES).enumerate() {
io.read_at(offset + (i * SLOT_BYTES) as u64, b)?;
}
Ok(())
}
pub fn write_region(io: &mut dyn MemcardStorage, offset: u64, bytes: &[u8]) -> Result<()> {
for (i, b) in bytes.chunks(SLOT_BYTES).enumerate() {
io.write_at(offset + (i * SLOT_BYTES) as u64, b)?;
}
Ok(())
}
pub fn block_offset(id: u8) -> Result<u64> {
if id as usize >= BLOCK_COUNT {
return Err(Error::InvalidRange);
}
Ok(DATA_OFFSET + id as u64 * SLOT_BYTES as u64)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn crc_vectors_and_identity_golden() {
assert_eq!(crc32c(b""), 0);
assert_eq!(crc32c(b"123456789"), 0xe3069283);
let p = identity_page([7; 16]);
assert_eq!(&p[..16], b"PMCARD1\0\x01\0\0\0\0\x40\x50\0");
assert_eq!(decode_identity(&p), Ok([7; 16]));
}
#[test]
fn descriptor_roundtrip_rejects_reserved_and_alias() {
let mut m = Map::new([1; 16]);
m.slots[2] =
Slot { assigned: true, block: Some(3), used: 7, generation: 1, update_at: 0, crc: 12 };
assert_eq!(Map::decode(&m.encode().unwrap(), [1; 16]), Ok(m.clone()));
m.slots[4] = m.slots[2];
assert_eq!(m.encode(), Err(Error::Corrupt));
let mut b = Map::new([1; 16]).encode().unwrap();
b[3000] = 1;
seal(&mut b);
assert_eq!(Map::decode(&b, [1; 16]), Err(Error::Corrupt));
}
#[test]
fn closed_catalog_rejects_duplicates_and_deep_input() {
for s in [
r#"{"metadataVersion":1,"metadataVersion":1,"games":[]}"#,
r#"{"metadataVersion":1,"games":[],"extra":0}"#,
r#"[[[[[[[[[]]]]]]]]]"#,
] {
assert_eq!(Catalog::decode(s.as_bytes(), 0), Err(Error::Corrupt));
}
}
#[test]
fn maximum_catalog_and_icons_fit_and_preserve_uint64() {
let mut c = Catalog::default();
for i in 0..64 {
c.games.push(Game {
app_id: u32::MAX - i,
title: "\u{1}".repeat(127) + "a",
data_format_version: u32::MAX,
created_at: u64::MAX,
slots: vec![i as u8],
icon: Icon { offset: i * 2096, frames: 4, duration: u16::MAX, crc32c: u32::MAX },
});
}
let b = c.encode(64 * 2096).unwrap();
assert!(b.len() < CATALOG_BYTES);
assert_eq!(Catalog::decode(&b, 64 * 2096), Ok(c));
}
}
File diff suppressed because it is too large Load Diff
@@ -0,0 +1,610 @@
//! Worker-owned transaction engine. Main-lane callers exchange owned requests/results.
use super::image::*;
use prometeu_hal::memcard::MemcardStorage;
use std::sync::atomic::{AtomicU8, Ordering};
/// Publication entry and pre-publication cancellation share a single linearization point.
#[derive(Default)]
pub struct PublicationControl(AtomicU8);
impl PublicationControl {
pub fn cancel(&self) {
self.0.fetch_or(2, Ordering::SeqCst);
}
pub fn canceled(&self) -> bool {
self.0.load(Ordering::SeqCst) & 2 != 0
}
pub fn publication_attempted(&self) -> bool {
self.0.load(Ordering::SeqCst) & 1 != 0
}
fn enter(&self) -> Result<()> {
self.0
.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |state| {
if state & 2 == 0 { Some(state | 1) } else { None }
})
.map(|_| ())
.map_err(|_| Error::Canceled)
}
fn check(&self) -> Result<()> {
if self.canceled() { Err(Error::Canceled) } else { Ok(()) }
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DurableResult {
Success,
Failure,
Indeterminate,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CommitResult {
pub durable: DurableResult,
pub error: Option<Error>,
pub sequence: u64,
}
pub struct Card {
io: Box<dyn MemcardStorage>,
pub maps: [Option<Map>; 2],
pub active: usize,
pub catalog: Catalog,
scratch: Box<[u8; SLOT_BYTES]>,
pub recovered: bool,
pub degraded: bool,
pub uncertain: bool,
pub(super) attempted_publication: Option<Map>,
pub write_blocked: bool,
known_quarantine: [bool; BLOCK_COUNT],
}
impl Card {
pub fn format(io: &mut dyn MemcardStorage, id: [u8; 16]) -> Result<()> {
if io.len()? != IMAGE_BYTES {
return Err(Error::InvalidRange);
}
let identity = identity_page(id);
io.write_at(0, &identity)?;
io.write_at(PAGE_BYTES as u64, &identity)?;
let catalog = Catalog::default().encode(0)?;
write_region(io, CATALOG_OFFSETS[0], &catalog)?;
let mut map = Map::new(id);
map.catalog_len = catalog.len() as u32;
map.catalog_crc = crc32c(&catalog);
let encoded = map.encode()?;
io.write_at(MAP_OFFSETS[0], &encoded)?;
io.write_at(MAP_OFFSETS[1], &encoded)?;
io.sync()?;
Ok(())
}
pub fn mount(mut io: Box<dyn MemcardStorage>) -> Result<Self> {
if io.len()? != IMAGE_BYTES {
return Err(Error::Unsupported);
}
let mut page = [0; PAGE_BYTES];
let mut identities = [None; 2];
let mut recognized = false;
for (i, item) in identities.iter_mut().enumerate() {
io.read_at((i * PAGE_BYTES) as u64, &mut page)?;
recognized |= &page[..8] == b"PMCARD1\0"
&& u32::from_le_bytes(page[8..12].try_into().unwrap()) == 1;
*item = decode_identity(&page).ok();
}
let id = identities[0].or(identities[1]).ok_or(if recognized {
Error::Corrupt
} else {
Error::Unsupported
})?;
if identities.iter().flatten().any(|other| *other != id) {
return Err(Error::Corrupt);
}
let mut maps: [Option<Map>; 2] = [None, None];
let mut unknown_metadata = false;
for i in 0..2 {
io.read_at(MAP_OFFSETS[i], &mut page)?;
maps[i] = Map::decode(&page, id).ok();
// A zero page is a verified retirement. An undecodable nonzero page
// may have lost quarantine information; do not silently reuse its pool.
unknown_metadata |= maps[i].is_none() && page.iter().any(|&byte| byte != 0);
}
if let (Some(a), Some(b)) = (&maps[0], &maps[1])
&& a.sequence == b.sequence
&& a != b
{
return Err(Error::Corrupt);
}
let highest = maps.iter().flatten().map(|m| m.sequence).max().unwrap_or(0);
let mut known = [false; BLOCK_COUNT];
for m in maps.iter().flatten() {
for (i, &bad) in m.quarantine.iter().enumerate() {
known[i] |= bad;
}
}
let mut scratch = Box::new([0; SLOT_BYTES]);
let mut catalogs: [Option<Catalog>; 2] = [None, None];
let mut lost_map = false;
for i in 0..2 {
if let Some(m) = &maps[i] {
match Self::validate_map(io.as_mut(), m, scratch.as_mut()) {
Ok(c) => catalogs[i] = Some(c),
Err(Error::Corrupt) => {
maps[i] = None;
lost_map = true
}
Err(e) => return Err(e),
}
}
}
let active = match (&maps[0], &maps[1]) {
(Some(a), Some(b)) => usize::from(b.sequence > a.sequence),
(Some(_), None) => 0,
(None, Some(_)) => 1,
_ => return Err(Error::Corrupt),
};
let m = maps[active].as_ref().unwrap();
let recovered = m.sequence < highest || lost_map || unknown_metadata;
let write_blocked =
unknown_metadata || known.iter().zip(m.quarantine.iter()).any(|(&a, &b)| a && !b);
let degraded = identities.iter().any(Option::is_none)
|| maps.iter().any(Option::is_none)
|| known.iter().any(|v| *v);
Ok(Self {
io,
maps,
active,
catalog: catalogs[active].take().unwrap(),
scratch,
recovered,
degraded,
uncertain: false,
attempted_publication: None,
write_blocked,
known_quarantine: known,
})
}
fn validate_map(
io: &mut dyn MemcardStorage,
m: &Map,
scratch: &mut [u8; SLOT_BYTES],
) -> Result<Catalog> {
let mut raw = vec![0; m.catalog_len as usize];
read_region(io, CATALOG_OFFSETS[m.public_copy], &mut raw)?;
if crc32c(&raw) != m.catalog_crc {
return Err(Error::Corrupt);
}
let catalog = Catalog::decode(&raw, m.icons_len as usize)?;
let assigned = catalog.validate(m.icons_len as usize)?;
for (s, &expected) in m.slots.iter().zip(&assigned) {
if s.assigned != expected {
return Err(Error::Corrupt);
}
if let Some(id) = s.block {
io.read_at(block_offset(id)?, &mut scratch[..s.used as usize])?;
if crc32c(&scratch[..s.used as usize]) != s.crc {
return Err(Error::Corrupt);
}
}
}
let mut crc = !0;
let mut at = 0usize;
while at < m.icons_len as usize {
let n = (m.icons_len as usize - at).min(SLOT_BYTES);
io.read_at(ICON_OFFSETS[m.public_copy] + at as u64, &mut scratch[..n])?;
crc = crc_extend(crc, &scratch[..n]);
at += n;
}
if crc ^ !0 != m.icons_crc {
return Err(Error::Corrupt);
}
for game in &catalog.games {
let n = game.icon.length()?;
io.read_at(ICON_OFFSETS[m.public_copy] + game.icon.offset as u64, &mut scratch[..n])?;
if crc32c(&scratch[..n]) != game.icon.crc32c {
return Err(Error::Corrupt);
}
}
Ok(catalog)
}
pub fn current(&self) -> &Map {
self.maps[self.active].as_ref().unwrap()
}
pub(super) fn known_exclusions(&self) -> [bool; BLOCK_COUNT] {
self.known_quarantine
}
pub(super) fn remember_exclusions(&mut self, known: [bool; BLOCK_COUNT]) {
for (i, bad) in known.into_iter().enumerate() {
self.known_quarantine[i] |= bad;
self.write_blocked |= bad && !self.current().quarantine[i];
}
self.degraded |= self.known_quarantine.iter().any(|&bad| bad);
}
pub fn storage_read_only(&self) -> bool {
self.io.read_only()
}
pub fn into_storage(self) -> Box<dyn MemcardStorage> {
self.io
}
pub fn read_slot(&mut self, slot: usize, target: &mut [u8]) -> Result<usize> {
let s = *self.current().slots.get(slot).ok_or(Error::InvalidRange)?;
if !s.assigned || target.len() < s.used as usize {
return Err(Error::InvalidRange);
}
if let Some(id) = s.block {
self.io.read_at(block_offset(id)?, &mut target[..s.used as usize])?;
if crc32c(&target[..s.used as usize]) != s.crc {
return Err(Error::Corrupt);
}
}
Ok(s.used as usize)
}
fn writable(&self) -> Result<()> {
if self.uncertain {
return Err(Error::Indeterminate);
}
if self.write_blocked || self.io.read_only() {
return Err(Error::ReadOnly);
}
if self.current().sequence == u64::MAX {
return Err(Error::CounterExhausted);
}
Ok(())
}
fn retire_inactive(&mut self, control: &PublicationControl) -> Result<()> {
control.check()?;
let inactive = 1 - self.active;
// Also invalidate torn/unknown pages before a previously referenced region is reused.
self.io.write_at(MAP_OFFSETS[inactive], &[0; PAGE_BYTES])?;
self.io.sync()?;
self.io.read_at(MAP_OFFSETS[inactive], &mut self.scratch[..PAGE_BYTES])?;
if self.scratch[..PAGE_BYTES].iter().any(|&v| v != 0) {
self.write_blocked = true;
return Err(Error::Corrupt);
}
self.maps[inactive] = None;
control.check()
}
fn publish(&mut self, next: Map, control: &PublicationControl) -> Result<()> {
let b = next.encode()?;
control.enter()?;
self.uncertain = true;
self.attempted_publication = Some(next.clone());
let inactive = 1 - self.active;
self.io.write_at(MAP_OFFSETS[inactive], &b)?;
self.io.sync()?;
self.io.read_at(MAP_OFFSETS[inactive], &mut self.scratch[..PAGE_BYTES])?;
if self.scratch[..PAGE_BYTES] != b {
return Err(Error::Corrupt);
}
self.maps[inactive] = Some(next);
self.active = inactive;
self.uncertain = false;
Ok(())
}
pub fn commit(
&mut self,
slot: usize,
payload: &[u8],
timestamp: u64,
control: &PublicationControl,
) -> CommitResult {
let outcome = self.commit_inner(slot, payload, timestamp, control);
CommitResult {
durable: if outcome.is_ok() {
DurableResult::Success
} else if self.uncertain {
DurableResult::Indeterminate
} else {
DurableResult::Failure
},
error: outcome.err(),
sequence: self.current().sequence,
}
}
fn commit_inner(
&mut self,
slot: usize,
payload: &[u8],
timestamp: u64,
control: &PublicationControl,
) -> Result<()> {
self.writable()?;
self.attempted_publication = None;
control.check()?;
let old =
*self.current().slots.get(slot).filter(|s| s.assigned).ok_or(Error::InvalidRange)?;
if payload.len() > SLOT_BYTES {
return Err(Error::InvalidRange);
}
let generation = old.generation.checked_add(1).ok_or(Error::CounterExhausted)?;
self.retire_inactive(control)?;
let mut next = self.current().clone();
next.sequence += 1;
let block = if payload.is_empty() {
None
} else {
let mut protected = self.known_quarantine;
for m in self.maps.iter().flatten() {
for s in &m.slots {
if let Some(b) = s.block {
protected[b as usize] = true;
}
}
}
let id =
*next.order.iter().find(|&&id| !protected[id as usize]).ok_or(Error::NoSpace)?;
control.check()?;
self.io.write_at(block_offset(id)?, payload)?;
self.io.sync()?;
control.check()?;
self.io.read_at(block_offset(id)?, &mut self.scratch[..payload.len()])?;
if self.scratch[..payload.len()] != *payload {
return Err(Error::Corrupt);
}
Some(id)
};
if let Some(id) = block {
move_last(&mut next.order, id)
}
if let Some(id) = old.block {
move_last(&mut next.order, id)
}
next.slots[slot] = Slot {
assigned: true,
block,
used: payload.len() as u32,
generation,
update_at: timestamp,
crc: crc32c(payload),
};
self.publish(next, control)
}
/// Runtime-authorized catalog mutation; userland cannot provide global ownership.
/// Existing icon data streams between copies through the single scratch buffer.
pub fn publish_catalog(
&mut self,
mut catalog: Catalog,
slots: [Slot; SLOT_COUNT],
new_icon: Option<(u32, &[u8])>,
control: &PublicationControl,
) -> Result<()> {
self.writable()?;
self.attempted_publication = None;
control.check()?;
let mut next = self.current().clone();
next.sequence += 1;
next.public_copy = 1 - next.public_copy;
next.slots = slots;
let mut offset = 0usize;
for game in &mut catalog.games {
let len = game.icon.length()?;
game.icon.offset = offset as u32;
offset = offset.checked_add(len).ok_or(Error::NoSpace)?;
}
catalog.validate(offset)?;
let raw = catalog.encode(offset)?;
let assigned = catalog.validate(offset)?;
if slots.iter().zip(assigned).any(|(s, a)| s.assigned != a) {
return Err(Error::Corrupt);
}
next.catalog_len = raw.len() as u32;
next.catalog_crc = crc32c(&raw);
next.icons_len = offset as u32;
// Reject invalid descriptors before any administrative IO.
next.encode()?;
self.retire_inactive(control)?;
let mut crc = !0;
for game in &catalog.games {
control.check()?;
let len = game.icon.length()?;
if let Some((id, bytes)) = new_icon.filter(|(id, _)| *id == game.app_id) {
let _ = id;
if bytes.len() != len || crc32c(bytes) != game.icon.crc32c {
return Err(Error::Corrupt);
}
self.scratch[..len].copy_from_slice(bytes);
} else {
let old = self
.catalog
.games
.iter()
.find(|g| g.app_id == game.app_id)
.ok_or(Error::InvalidRange)?;
if old.icon.length()? != len || old.icon.crc32c != game.icon.crc32c {
return Err(Error::Corrupt);
}
self.io.read_at(
ICON_OFFSETS[self.current().public_copy] + old.icon.offset as u64,
&mut self.scratch[..len],
)?;
if crc32c(&self.scratch[..len]) != old.icon.crc32c {
return Err(Error::Corrupt);
}
}
crc = crc_extend(crc, &self.scratch[..len]);
self.io.write_at(
ICON_OFFSETS[next.public_copy] + game.icon.offset as u64,
&self.scratch[..len],
)?;
}
next.icons_crc = crc ^ !0;
write_region(self.io.as_mut(), CATALOG_OFFSETS[next.public_copy], &raw)?;
self.io.sync()?;
Self::validate_map(self.io.as_mut(), &next, self.scratch.as_mut())?;
self.publish(next, control)?;
self.catalog = catalog;
Ok(())
}
pub fn register(
&mut self,
mut game: Game,
icon: &[u8],
control: &PublicationControl,
) -> Result<()> {
if self.catalog.games.iter().any(|g| g.app_id == game.app_id) {
return Err(Error::InvalidRange);
}
let n = game.slots.len();
if !(1..=64).contains(&n) {
return Err(Error::InvalidRange);
}
let mut slots = self.current().slots;
let free: Vec<u8> = slots
.iter()
.enumerate()
.filter(|(_, s)| !s.assigned)
.map(|(i, _)| i as u8)
.take(n)
.collect();
if free.len() != n {
return Err(Error::NoSpace);
}
game.slots = free;
for &id in &game.slots {
slots[id as usize] = Slot { assigned: true, ..Slot::default() };
}
let app_id = game.app_id;
let mut c = self.catalog.clone();
c.games.push(game);
self.publish_catalog(c, slots, Some((app_id, icon)), control)
}
pub fn remove_game(&mut self, app_id: u32, control: &PublicationControl) -> Result<()> {
let game =
self.catalog.games.iter().find(|g| g.app_id == app_id).ok_or(Error::InvalidRange)?;
let mut slots = self.current().slots;
for &id in &game.slots {
slots[id as usize] = Slot::default();
}
let mut c = self.catalog.clone();
c.games.retain(|g| g.app_id != app_id);
self.publish_catalog(c, slots, None, control)
}
pub fn grow(&mut self, app_id: u32, count: usize, control: &PublicationControl) -> Result<()> {
if !(1..=64).contains(&count) {
return Err(Error::InvalidRange);
}
let mut c = self.catalog.clone();
let g = c.games.iter_mut().find(|g| g.app_id == app_id).ok_or(Error::InvalidRange)?;
if count <= g.slots.len() {
return Ok(());
}
let need = count - g.slots.len();
let mut slots = self.current().slots;
let free: Vec<u8> = slots
.iter()
.enumerate()
.filter(|(_, s)| !s.assigned)
.map(|(i, _)| i as u8)
.take(need)
.collect();
if free.len() != need {
return Err(Error::NoSpace);
}
for &id in &free {
slots[id as usize] = Slot { assigned: true, ..Slot::default() };
}
g.slots.extend(free);
self.publish_catalog(c, slots, None, control)
}
/// Explicit host maintenance after coherent mount. Unknown exclusion history
/// can only be cleared after every reusable, non-quarantined block is tested.
pub fn revalidate(&mut self, control: &PublicationControl) -> Result<()> {
if self.uncertain {
return Err(Error::Indeterminate);
}
if self.io.read_only() {
return Err(Error::ReadOnly);
}
if self.current().sequence == u64::MAX {
return Err(Error::CounterExhausted);
}
self.write_blocked = true;
self.retire_inactive(control)?;
for block in 0..BLOCK_COUNT {
if !self.known_quarantine[block]
&& !self.current().slots.iter().any(|s| s.block == Some(block as u8))
{
self.test_free_block(block as u8, control)?;
}
}
let mut next = self.current().clone();
next.sequence += 1;
next.quarantine = self.known_quarantine;
self.publish(next, control)?;
self.write_blocked = false;
self.degraded = self.known_quarantine.iter().any(|&bad| bad);
Ok(())
}
fn test_free_block(&mut self, block: u8, control: &PublicationControl) -> Result<()> {
for pattern in [0x55, 0xaa] {
control.check()?;
self.scratch.fill(pattern);
self.io.write_at(block_offset(block)?, self.scratch.as_ref())?;
self.io.sync()?;
control.check()?;
self.io.read_at(block_offset(block)?, self.scratch.as_mut())?;
if self.scratch.iter().any(|&byte| byte != pattern) {
return Err(Error::Corrupt);
}
}
Ok(())
}
/// Reintegrating a known excluded block is a separate, explicit operation.
pub fn reintegrate(&mut self, block: u8, control: &PublicationControl) -> Result<()> {
self.writable()?;
if block as usize >= BLOCK_COUNT
|| self.current().slots.iter().any(|s| s.block == Some(block))
{
return Err(Error::InvalidRange);
}
self.retire_inactive(control)?;
self.test_free_block(block, control)?;
let mut next = self.current().clone();
next.sequence += 1;
next.quarantine[block as usize] = false;
self.publish(next, control)?;
self.known_quarantine[block as usize] = false;
self.degraded = self.known_quarantine.iter().any(|&bad| bad);
Ok(())
}
pub fn read_icon(&mut self, app_id: u32) -> Result<Vec<u8>> {
let icon = &self
.catalog
.games
.iter()
.find(|g| g.app_id == app_id)
.ok_or(Error::InvalidRange)?
.icon;
let mut bytes = vec![0; icon.length()?];
self.io
.read_at(ICON_OFFSETS[self.current().public_copy] + icon.offset as u64, &mut bytes)?;
if crc32c(&bytes) != icon.crc32c {
return Err(Error::Corrupt);
}
Ok(bytes)
}
pub fn quarantine(&mut self, block: u8, control: &PublicationControl) -> Result<()> {
if block as usize >= BLOCK_COUNT {
return Err(Error::InvalidRange);
}
self.known_quarantine[block as usize] = true;
self.degraded = true;
let result = (|| {
self.writable()?;
if self.current().slots.iter().any(|s| s.block == Some(block)) {
return Err(Error::Corrupt);
}
self.retire_inactive(control)?;
let mut next = self.current().clone();
next.sequence += 1;
next.quarantine = self.known_quarantine;
self.publish(next, control)
})();
if result.is_err() {
self.write_blocked = true;
}
result
}
}
fn move_last(order: &mut [u8; BLOCK_COUNT], id: u8) {
let pos = order.iter().position(|&b| b == id).unwrap();
order[pos..].rotate_left(1);
}
#[cfg(test)]
mod tests;
File diff suppressed because it is too large Load Diff
@@ -1,9 +1,9 @@
use super::*;
use crate::fs::{FsState, VirtualFS};
use crate::services::memcard::{MemcardService, MemcardSlotState, MemcardStatus};
use crate::services::memcard::MemcardService;
use prometeu_bytecode::{TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_TYPE, Value};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType, SlotRef};
use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::log::{LogLevel, LogSource};
@@ -495,15 +495,17 @@ impl NativeInterface for VmRuntimeHost<'_> {
Ok(())
}
Syscall::AudioPlay => {
let bank_id = expect_int(args, 0)? as u8;
let bank_id_raw = expect_int(args, 0)?;
let sample_id_raw = expect_int(args, 1)?;
let voice_id_raw = expect_int(args, 2)?;
let volume_raw = expect_int(args, 3)?;
let pan_raw = expect_int(args, 4)?;
let pitch = expect_number(args, 5, "pitch")?;
let loop_mode = match expect_int(args, 6)? {
0 => prometeu_hal::LoopMode::Off,
_ => prometeu_hal::LoopMode::On,
let loop_raw = expect_int(args, 6)?;
let loop_mode = if loop_raw == 0 {
prometeu_hal::LoopMode::Off
} else {
prometeu_hal::LoopMode::On
};
if !(0..16).contains(&voice_id_raw) {
@@ -511,18 +513,18 @@ impl NativeInterface for VmRuntimeHost<'_> {
return Ok(());
}
if platform.assets().slot_info(SlotRef::audio(bank_id as usize)).asset_id.is_none()
{
if !(0..16).contains(&bank_id_raw) {
ret.push_int(AudioOpStatus::BankInvalid as i64);
return Ok(());
}
let bank_id = bank_id_raw as u8;
if sample_id_raw < 0
|| sample_id_raw > u16::MAX as i64
|| !(0..=255).contains(&volume_raw)
|| !(0..=255).contains(&pan_raw)
|| !pitch.is_finite()
|| pitch <= 0.0
|| !(0..=1).contains(&loop_raw)
{
ret.push_int(AudioOpStatus::ArgRangeInvalid as i64);
return Ok(());
@@ -541,6 +543,38 @@ impl NativeInterface for VmRuntimeHost<'_> {
ret.push_int(status as i64);
Ok(())
}
Syscall::AudioStop
| Syscall::AudioSetVolume
| Syscall::AudioSetPan
| Syscall::AudioSetPitch => {
let voice = expect_int(args, 0)?;
// Decode all types before reporting operational validation failures.
let value = match syscall {
Syscall::AudioSetVolume | Syscall::AudioSetPan => expect_int(args, 1)?,
_ => 0,
};
let pitch = if syscall == Syscall::AudioSetPitch {
expect_number(args, 1, "pitch")?
} else {
1.0
};
let status = if !(0..16).contains(&voice) {
AudioOpStatus::VoiceInvalid
} else if !(0..=255).contains(&value) || !pitch.is_finite() || pitch <= 0.0 {
AudioOpStatus::ArgRangeInvalid
} else {
let audio = platform.audio_mut();
match syscall {
Syscall::AudioStop => audio.stop(voice as usize),
Syscall::AudioSetVolume => audio.set_volume(voice as usize, value as u8),
Syscall::AudioSetPan => audio.set_pan(voice as usize, value as u8),
Syscall::AudioSetPitch => audio.set_pitch(voice as usize, pitch),
_ => unreachable!(),
}
};
ret.push_int(status as i64);
Ok(())
}
Syscall::FsOpen => {
let path = expect_string(args, 0, "path")?;
if *self.fs_state != FsState::Mounted {
@@ -561,7 +595,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
.ok_or_else(|| VmFault::Panic("Invalid handle".into()))?
.clone();
match self.fs.read_file(&path) {
Ok(data) => ret.push_string(String::from_utf8_lossy(&data).into_owned()),
Ok(data) => ret.push_utf8_lossy(&data)?,
Err(_) => ret.push_null(),
}
Ok(())
@@ -588,8 +622,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
let path = expect_string(args, 0, "path")?;
match self.fs.list_dir(&path) {
Ok(entries) => {
let names: Vec<String> = entries.into_iter().map(|e| e.name).collect();
ret.push_string(names.join(";"));
ret.push_joined(entries.iter().map(|entry| entry.name.as_str()), ";")?;
}
Err(_) => ret.push_null(),
}
@@ -606,101 +639,24 @@ impl NativeInterface for VmRuntimeHost<'_> {
}
Ok(())
}
Syscall::MemSlotCount => {
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_int(0);
return Ok(());
}
ret.push_int(MemcardStatus::Ok as i64);
ret.push_int(self.memcard.slot_count() as i64);
Ok(())
}
Syscall::MemSlotStat => {
let slot = expect_slot_index(args, 0)?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_int(MemcardSlotState::Empty as i64);
ret.push_int(0);
ret.push_int(0);
ret.push_int(0);
return Ok(());
}
let stat = self.memcard.slot_stat(self.fs, self.current_app_id, slot);
let status = if stat.state == MemcardSlotState::Corrupt {
MemcardStatus::Corrupt
} else {
MemcardStatus::Ok
};
ret.push_int(status as i64);
ret.push_int(stat.state as i64);
ret.push_int(stat.used_bytes as i64);
ret.push_int(stat.generation as i64);
ret.push_int(stat.checksum as i64);
Ok(())
}
Syscall::MemSlotRead => {
let slot = expect_slot_index(args, 0)?;
let offset = expect_non_negative_usize(args, 1, "offset")?;
let max_bytes = expect_non_negative_usize(args, 2, "max_bytes")?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_string(String::new());
ret.push_int(0);
return Ok(());
}
let read =
self.memcard.slot_read(self.fs, self.current_app_id, slot, offset, max_bytes);
ret.push_int(read.status as i64);
ret.push_string(hex_encode(&read.bytes));
ret.push_int(read.bytes_read as i64);
Ok(())
}
Syscall::MemSlotWrite => {
let slot = expect_slot_index(args, 0)?;
let offset = expect_non_negative_usize(args, 1, "offset")?;
let payload_hex = expect_string(args, 2, "payload_hex")?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_int(0);
return Ok(());
}
let payload = hex_decode(&payload_hex)?;
Syscall::MemBootstrap
| Syscall::MemSlotCount
| Syscall::MemSlotStat
| Syscall::MemSlotRead
| Syscall::MemSlotWrite
| Syscall::MemSlotCommit
| Syscall::MemSlotClear
| Syscall::MemQuery
| Syscall::MemRelease
| Syscall::MemInfo
| Syscall::MemMetadata
| Syscall::MemPresentation
| Syscall::MemDiagnostic
| Syscall::MemPublishPresentation => {
let timestamp = platform.wall_clock().utc_unix_seconds();
let app_id = self.current_app_id;
let write = self.memcard.slot_write(self.fs, app_id, slot, offset, &payload);
ret.push_int(write.status as i64);
ret.push_int(write.bytes_written as i64);
Ok(())
}
Syscall::MemSlotCommit => {
let slot = expect_slot_index(args, 0)?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
return Ok(());
}
let status = {
let app_id = self.current_app_id;
let memcard = &mut self.memcard;
let fs = &mut self.fs;
memcard.slot_commit(fs, app_id, slot)
};
ret.push_int(status as i64);
Ok(())
}
Syscall::MemSlotClear => {
let slot = expect_slot_index(args, 0)?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
return Ok(());
}
let status = {
let app_id = self.current_app_id;
let memcard = &mut self.memcard;
let fs = &mut self.fs;
memcard.slot_clear(fs, app_id, slot)
};
ret.push_int(status as i64);
Ok(())
let game_profile = self.current_cartridge_app_mode == AppMode::Game;
self.memcard.guest(syscall, args, ret, app_id, timestamp, game_profile)
}
Syscall::LogWrite => {
self.syscall_log_write(
@@ -850,14 +806,6 @@ fn expect_number(args: &[Value], index: usize, field: &str) -> Result<f64, VmFau
}
}
fn expect_slot_index(args: &[Value], index: usize) -> Result<u8, VmFault> {
let slot = expect_int(args, index)?;
if !(0..32).contains(&slot) {
return Err(VmFault::Trap(TRAP_OOB, format!("slot index out of bounds: {}", slot)));
}
Ok(slot as u8)
}
fn expect_non_negative_usize(args: &[Value], index: usize, field: &str) -> Result<usize, VmFault> {
let val = expect_int(args, index)?;
if val < 0 {
@@ -865,42 +813,3 @@ fn expect_non_negative_usize(args: &[Value], index: usize, field: &str) -> Resul
}
Ok(val as usize)
}
fn hex_encode(bytes: &[u8]) -> String {
const HEX: &[u8; 16] = b"0123456789abcdef";
let mut out = String::with_capacity(bytes.len() * 2);
for &b in bytes {
out.push(HEX[(b >> 4) as usize] as char);
out.push(HEX[(b & 0x0f) as usize] as char);
}
out
}
fn hex_decode(s: &str) -> Result<Vec<u8>, VmFault> {
fn nibble(c: u8) -> Option<u8> {
match c {
b'0'..=b'9' => Some(c - b'0'),
b'a'..=b'f' => Some(10 + c - b'a'),
b'A'..=b'F' => Some(10 + c - b'A'),
_ => None,
}
}
let bytes = s.as_bytes();
if !bytes.len().is_multiple_of(2) {
return Err(VmFault::Trap(TRAP_TYPE, "payload_hex must have even length".to_string()));
}
let mut out = Vec::with_capacity(bytes.len() / 2);
let mut i = 0usize;
while i < bytes.len() {
let hi = nibble(bytes[i]).ok_or_else(|| {
VmFault::Trap(TRAP_TYPE, "payload_hex contains invalid hex".to_string())
})?;
let lo = nibble(bytes[i + 1]).ok_or_else(|| {
VmFault::Trap(TRAP_TYPE, "payload_hex contains invalid hex".to_string())
})?;
out.push((hi << 4) | lo);
i += 2;
}
Ok(out)
}
@@ -219,6 +219,22 @@ impl VirtualMachineRuntime {
match vm.initialize(cartridge.program.clone()) {
Ok(_) => {
if let Some(count) = cartridge.memcard_slots {
if !(1..=64).contains(&count)
|| cartridge.capabilities & prometeu_hal::syscalls::caps::MEMCARD == 0
{
return Err(CrashReport::VmPanic {
message: "Invalid memcard capability/count".into(),
pc: None,
});
}
vm.require_memcard_boot().map_err(|error| CrashReport::VmInit { error })?;
} else if cartridge.capabilities & prometeu_hal::syscalls::caps::MEMCARD != 0 {
return Err(CrashReport::VmPanic {
message: "Memcard capability requires a slot count".into(),
pc: None,
});
}
self.current_app_id = cartridge.app_id;
self.current_cartridge_title = cartridge.title.clone();
self.current_cartridge_app_version = cartridge.app_version.clone();
@@ -1,10 +1,11 @@
use super::*;
use crate::fs::{FsBackend, FsEntry, FsError, FsState, VirtualFS};
use crate::fs::{FsState, VirtualFS};
use crate::services::memcard::MemcardService;
use prometeu_bytecode::TRAP_TYPE;
use prometeu_bytecode::Value;
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, ConstantPoolEntry, FunctionMeta, SyscallDecl};
use prometeu_bytecode::model::{ConstantPoolEntry, SyscallDecl};
use prometeu_bytecode::registry::FunctionDecl;
use prometeu_drivers::TestPlatform;
use prometeu_drivers::{GlyphBankPoolInstaller, MemoryBanks, SceneBankPoolInstaller};
use prometeu_hal::AudioOpStatus;
@@ -22,55 +23,19 @@ use prometeu_hal::syscalls::caps;
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_test_support::program::{TestProgram, int64_signature};
use prometeu_vm::VmInitError;
use std::collections::HashMap;
use std::sync::Arc;
use std::sync::atomic::Ordering;
#[derive(Default)]
struct MemFsBackend {
files: HashMap<String, Vec<u8>>,
}
impl FsBackend for MemFsBackend {
fn mount(&mut self) -> Result<(), FsError> {
Ok(())
}
fn unmount(&mut self) {}
fn list_dir(&self, _path: &str) -> Result<Vec<FsEntry>, FsError> {
Ok(Vec::new())
}
fn read_file(&self, path: &str) -> Result<Vec<u8>, FsError> {
self.files.get(path).cloned().ok_or(FsError::NotFound)
}
fn write_file(&mut self, path: &str, data: &[u8]) -> Result<(), FsError> {
self.files.insert(path.to_string(), data.to_vec());
Ok(())
}
fn delete(&mut self, path: &str) -> Result<(), FsError> {
self.files.remove(path).map(|_| ()).ok_or(FsError::NotFound)
}
fn exists(&self, path: &str) -> bool {
self.files.contains_key(path)
}
fn is_healthy(&self) -> bool {
true
}
}
fn cartridge_with_program_and_mode(
program: Vec<u8>,
capabilities: u64,
app_mode: AppMode,
) -> Cartridge {
Cartridge {
memcard_slots: None,
app_id: 42,
title: "Test Cart".into(),
app_version: "1.0.0".into(),
@@ -96,13 +61,18 @@ fn serialized_single_function_module_with_consts(
const_pool: Vec<ConstantPoolEntry>,
syscalls: Vec<SyscallDecl>,
) -> Vec<u8> {
BytecodeModule {
version: 0,
TestProgram {
const_pool,
functions: vec![FunctionMeta {
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
..Default::default()
signature: int64_signature(0, 0),
captures: vec![],
name: None,
local_slots: 0,
max_stack_slots: 256,
}],
code,
debug_info: None,
@@ -151,9 +121,7 @@ fn runtime_test_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) ->
let size = tile_size as usize;
let mut bank = GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
bank.palette_mut(palette_id).unwrap()[1] = color;
for pixel in &mut bank.pixel_indices {
*pixel = 1;
}
bank.pixel_indices.fill(1);
bank
}
@@ -235,6 +203,8 @@ fn initialize_vm_succeeds_when_cartridge_capabilities_cover_hostcalls() {
assert!(res.is_ok());
assert_eq!(runtime.current_app_id, 42);
assert!(vm.is_halted());
vm.prepare_boot_call().unwrap();
assert!(!vm.is_halted());
}
@@ -681,40 +651,11 @@ fn tick_system_profile_can_use_shared_log_transport() {
}
#[test]
fn tick_returns_panic_report_distinct_from_trap() {
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
let mut vm = VirtualMachine::new(assemble("HOSTCALL 0\nHALT").expect("assemble"), vec![]);
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
let report = runtime
.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
)
.expect("panic must surface as runtime error");
match report {
CrashReport::VmPanic { message, pc } => {
assert!(message.contains("HOSTCALL 0 reached execution without loader patching"));
assert!(pc.is_some());
}
other => panic!("expected VmPanic crash report, got {:?}", other),
}
assert!(matches!(runtime.last_crash_report, Some(CrashReport::VmPanic { .. })));
fn unpatched_hostcall_is_rejected_before_tick() {
let bytes = serialized_single_function_module(assemble("HOSTCALL 0\nHALT").unwrap(), vec![]);
let mut vm = VirtualMachine::default();
assert!(vm.initialize(bytes).is_err());
assert!(vm.is_halted());
}
#[test]
@@ -1661,3 +1602,6 @@ fn tick_composer_emit_sprite_type_mismatch_surfaces_trap_not_panic() {
}
assert!(matches!(runtime.last_crash_report, Some(CrashReport::VmTrap { .. })));
}
#[path = "tests_audio.rs"]
mod audio_controls;
@@ -0,0 +1,218 @@
use super::*;
use prometeu_drivers::{AudioCommand, AudioTransport};
struct Harness {
runtime: VirtualMachineRuntime,
vm: VirtualMachine,
platform: TestPlatform,
log: LogService,
fs: VirtualFS,
fs_state: FsState,
memcard: MemcardService,
files: HashMap<u32, String>,
next: u32,
}
impl Harness {
fn new(code: &str, name: &str, args: u16) -> Self {
let mut runtime = VirtualMachineRuntime::new(None);
let mut vm = VirtualMachine::default();
let mut log = LogService::new(4096);
let program = serialized_single_function_module(
assemble(code).unwrap(),
vec![SyscallDecl {
module: "audio".into(),
name: name.into(),
version: 1,
arg_slots: args,
ret_slots: 1,
}],
);
runtime
.initialize_vm(&mut log, &mut vm, &cartridge_with_program(program, caps::AUDIO))
.unwrap();
Self {
runtime,
vm,
log,
platform: TestPlatform::new(),
fs: VirtualFS::new(),
fs_state: FsState::Unmounted,
memcard: MemcardService::new(),
files: HashMap::new(),
next: 1,
}
}
fn tick(&mut self) -> Option<CrashReport> {
self.runtime.tick(
&mut self.log,
&mut self.fs,
&mut self.fs_state,
&mut self.memcard,
&mut self.files,
&mut self.next,
&mut self.vm,
&InputSignals::default(),
&mut self.platform,
)
}
fn transport(&self) -> AudioTransport {
self.platform.local_hardware().audio.transport()
}
fn step(&mut self) -> Option<CrashReport> {
self.runtime.debug_step_instruction(
&mut self.log,
&mut self.fs,
&mut self.fs_state,
&mut self.memcard,
&mut self.files,
&mut self.next,
&mut self.vm,
&mut self.platform,
)
}
}
#[test]
fn guest_audio_status_matrix_and_type_traps() {
for (name, args, inputs, expected) in [
("stop", 1, "PUSH_I32 0", 0),
("stop", 1, "PUSH_I32 15", 0),
("stop", 1, "PUSH_I32 -1", 1),
("stop", 1, "PUSH_I32 16", 1),
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 0", 0),
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 255", 0),
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 256", 3),
("set_pan", 2, "PUSH_I32 0\nPUSH_I32 -1", 3),
("set_pan", 2, "PUSH_I32 16\nPUSH_I32 -1", 1),
("set_pan", 2, "PUSH_I32 15\nPUSH_I32 255", 0),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 1", 0),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 0", 3),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 -1", 3),
(
"play",
7,
"PUSH_I32 256\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 255\nPUSH_I32 0\nPUSH_I32 1\nPUSH_I32 0",
6,
),
] {
let mut h = Harness::new(&format!("{inputs}\nHOSTCALL 0\nFRAME_SYNC\nHALT"), name, args);
assert!(h.tick().is_none(), "{name}: {inputs}");
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(expected)], "{name}: {inputs}");
let batch = h.transport().try_take().unwrap().frame;
assert_eq!(batch.map_or(0, |v| v.len()), usize::from(expected == 0));
}
for name in ["set_volume", "set_pan", "set_pitch"] {
let mut h = Harness::new("PUSH_I32 -1\nPUSH_BOOL 1\nHOSTCALL 0\nFRAME_SYNC\nHALT", name, 2);
assert!(matches!(h.tick(), Some(CrashReport::VmTrap { .. })));
assert!(h.transport().try_take().unwrap().frame.is_none());
}
}
#[test]
fn frame_publication_backpressure_abort_and_debug_steps() {
let mut h = Harness::new(
"PUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nPUSH_I32 1\nHOSTCALL 0\nFRAME_SYNC\nHALT",
"stop",
1,
);
assert!(h.tick().is_none());
let pc = h.vm.pc();
assert!(h.tick().is_none());
assert_eq!(h.vm.pc(), pc, "pending batch stalls guest");
let batch = h.transport().try_take().unwrap().frame.unwrap();
assert!(matches!(batch[0], AudioCommand::Stop { voice_id: 0 }));
assert!(h.tick().is_none());
assert!(matches!(
h.transport().try_take().unwrap().frame.unwrap()[0],
AudioCommand::Stop { voice_id: 1 }
));
for end in ["HALT", "PUSH_BOOL 1\nHOSTCALL 0\nHALT"] {
let mut h = Harness::new(&format!("PUSH_I32 0\nHOSTCALL 0\n{end}"), "stop", 1);
let _ = h.tick();
h.platform.audio_mut().finish_frame();
assert!(h.transport().try_take().unwrap().frame.is_none(), "abort cancels admitted stop");
}
let mut h = Harness::new("PUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nHALT", "stop", 1);
assert!(h.step().is_none());
assert!(h.step().is_none());
assert!(h.transport().try_take().unwrap().frame.is_none());
// Switching from stepping to running must preserve previously staged commands.
assert!(h.tick().is_none());
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
#[test]
fn guest_quota_is_deterministic_and_resets_on_next_frame() {
let repeated = "PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\n".repeat(1024);
let mut h = Harness::new(
&format!(
"{repeated}PUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nPUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nHALT"
),
"stop",
1,
);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(7)]);
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1024);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(0)]);
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
#[test]
fn guest_play_validates_raw_bank_loop_and_preserves_both_play_forms() {
use prometeu_drivers::SoundBankPoolInstaller;
use prometeu_hal::{sample::Sample, sound_bank::SoundBank};
for (bank, loop_mode, expected) in
[(0, 0, 0), (0, 1, 0), (0, -1, 3), (0, 2, 3), (256, 0, 6), (-256, 0, 6), (16, 0, 6)]
{
let mut h = Harness::new(
&format!(
"PUSH_I32 {bank}\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 255\nPUSH_I32 127\nPUSH_I32 1\nPUSH_I32 {loop_mode}\nHOSTCALL 0\nFRAME_SYNC\nHALT"
),
"play",
7,
);
let banks = Arc::new(MemoryBanks::new());
banks.install_sound_bank(
0,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![1, 2, 3]))])),
);
h.platform = TestPlatform::new_with_memory_banks(banks);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(expected)]);
let batch = h.transport().try_take().unwrap().frame;
assert_eq!(batch.map_or(0, |v| v.len()), usize::from(expected == 0));
}
let mut h = Harness::new(
"PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 255\nPUSH_I32 127\nPUSH_I32 1\nHOSTCALL 0\nFRAME_SYNC\nHALT",
"play_sample",
5,
);
let banks = Arc::new(MemoryBanks::new());
banks.install_sound_bank(
0,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![1]))])),
);
h.platform = TestPlatform::new_with_memory_banks(banks);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(0)]);
assert!(matches!(
h.transport().try_take().unwrap().frame.unwrap()[0],
AudioCommand::Play { loop_mode: prometeu_hal::LoopMode::Off, .. }
));
}
#[test]
fn normal_entry_return_is_a_successful_implicit_audio_frame() {
let mut h = Harness::new("PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\nRET", "stop", 1);
for _ in 0..2 {
assert!(h.tick().is_none());
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
let mut h = Harness::new("PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\nRET", "stop", 1);
for _ in 0..4 {
assert!(h.step().is_none());
}
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
@@ -1,129 +1,155 @@
use super::*;
use prometeu_bytecode::registry::{LifecycleRole, NamedType, Signature, TypeId};
#[test]
fn tick_memcard_slot_roundtrip_for_game_profile() {
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
runtime.mount_fs(&mut log_service, &mut fs, &mut fs_state, Box::new(MemFsBackend::default()));
let mut vm = VirtualMachine::default();
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
let code = assemble(
"PUSH_I32 0\nPUSH_I32 0\nPUSH_CONST 0\nHOSTCALL 0\nPOP_N 2\nPUSH_I32 0\nHOSTCALL 1\nPOP_N 1\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 10\nHOSTCALL 2\nHALT",
)
.expect("assemble");
let program = serialized_single_function_module_with_consts(
fn memcard_cartridge(app_mode: AppMode, hook: &str) -> Cartridge {
let boot =
assemble("HOSTCALL 0\nPOP_N 1\nGET_GLOBAL 0\nGET_GLOBAL 1\nFRAME_SYNC\nHALT").unwrap();
let callback = assemble(hook).unwrap();
let mut code = boot.clone();
code.extend(&callback);
let program = TestProgram {
code,
vec![ConstantPoolEntry::String("6869".into())],
vec![
functions: vec![
FunctionDecl { code_len: boot.len() as u32, max_stack_slots: 16, ..Default::default() },
FunctionDecl {
lifecycle_role: LifecycleRole::MemcardBoot,
code_offset: boot.len() as u32,
code_len: callback.len() as u32,
max_stack_slots: 16,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![TypeId(1)],
},
..Default::default()
},
],
syscalls: vec![
SyscallDecl {
module: "mem".into(),
name: "slot_write".into(),
name: "bootstrap".into(),
version: 1,
arg_slots: 3,
arg_slots: 0,
ret_slots: 1,
},
SyscallDecl {
module: "mem".into(),
name: "slot_count".into(),
version: 1,
arg_slots: 1,
ret_slots: 2,
},
SyscallDecl {
module: "mem".into(),
name: "slot_commit".into(),
version: 1,
arg_slots: 1,
ret_slots: 1,
},
SyscallDecl {
module: "mem".into(),
name: "slot_read".into(),
version: 1,
arg_slots: 3,
ret_slots: 3,
arg_slots: 2,
ret_slots: 2,
},
],
);
let cartridge = Cartridge {
..Default::default()
};
Cartridge {
memcard_slots: Some(2),
app_id: 42,
title: "Memcard Game".into(),
app_version: "1.0.0".into(),
app_mode: AppMode::Game,
capabilities: caps::FS,
program,
title: "Memcard test".into(),
app_version: "1".into(),
app_mode,
capabilities: caps::MEMCARD,
program: program.serialize(),
assets: AssetsPayloadSource::empty(),
asset_table: vec![],
preload: vec![],
};
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
let report = runtime.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
);
assert!(report.is_none(), "memcard roundtrip must not crash");
assert!(vm.is_halted());
assert_eq!(
vm.operand_stack_top(3),
vec![Value::Int64(2), Value::String("6869".into()), Value::Int64(0)]
);
}
}
#[test]
fn tick_memcard_access_is_denied_for_non_game_profile() {
fn tick_memcard_boot_receives_admitted_context_and_precedes_first_frame() {
let cartridge = memcard_cartridge(
AppMode::Game,
"GET_LOCAL 0\nHOSTCALL 1\nSET_GLOBAL 0\nPOP_N 1\nGET_LOCAL 0\nPUSH_I32 0\nHOSTCALL 2\nSET_GLOBAL 1\nPOP_N 1\nPUSH_I32 0\nRET",
);
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
let mut log = LogService::new(4096);
let mut vm = VirtualMachine::default();
runtime.initialize_vm(&mut log, &mut vm, &cartridge).unwrap();
let mut memcard = MemcardService::new();
let context = memcard.session.start_memory(42, 2, 1024 * 1024).unwrap();
memcard.session.begin_boot();
memcard.session.set_presentation(context, "Test", 1, 1, 1, &[0; 560], 0).unwrap();
let mut fs = VirtualFS::new();
let mut state = FsState::Unmounted;
let mut files = HashMap::new();
let mut next = 1;
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
let code = assemble("HOSTCALL 0\nHALT").expect("assemble");
let program = serialized_single_function_module(
code,
vec![SyscallDecl {
module: "mem".into(),
name: "slot_count".into(),
version: 1,
arg_slots: 0,
ret_slots: 2,
}],
for expected in [None, Some(0)] {
assert!(
runtime
.tick(
&mut log,
&mut fs,
&mut state,
&mut memcard,
&mut files,
&mut next,
&mut vm,
&signals,
&mut platform
)
.is_none()
);
assert_eq!(vm.memcard_boot_result(), expected);
assert_eq!(runtime.logical_frame_index, 0);
}
let request = 1;
assert_eq!(
memcard.session.query(context, request).unwrap().state,
crate::memcard::session::RequestState::MemoryOnly
);
let cartridge = Cartridge {
app_id: 101,
title: "System App".into(),
app_version: "1.0.0".into(),
app_mode: AppMode::Shell,
capabilities: caps::FS,
program,
assets: AssetsPayloadSource::empty(),
asset_table: vec![],
preload: vec![],
};
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
let report = runtime.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
assert!(
runtime
.tick(
&mut log,
&mut fs,
&mut state,
&mut memcard,
&mut files,
&mut next,
&mut vm,
&signals,
&mut platform
)
.is_none()
);
assert!(report.is_none(), "non-game memcard call must return status");
assert!(vm.is_halted());
assert_eq!(vm.operand_stack_top(2), vec![Value::Int64(0), Value::Int64(4)]);
assert_eq!(runtime.logical_frame_index, 1);
assert_eq!(vm.operand_stack_top(2), vec![Value::Int64(1), Value::Int64(2)]);
assert!(vm.begin_memcard_boot(context as i64).is_err());
}
#[test]
fn tick_memcard_boot_is_denied_for_non_game_profile() {
let cartridge = memcard_cartridge(
AppMode::Shell,
"GET_LOCAL 0\nHOSTCALL 1\nPOP_N 2\nGET_LOCAL 0\nPUSH_I32 0\nHOSTCALL 2\nPOP_N 2\nPUSH_I32 0\nRET",
);
let mut runtime = VirtualMachineRuntime::new(None);
let mut log = LogService::new(4096);
let mut vm = VirtualMachine::default();
runtime.initialize_vm(&mut log, &mut vm, &cartridge).unwrap();
let mut memcard = MemcardService::new();
memcard.session.start_memory(42, 2, 1024 * 1024).unwrap();
memcard.session.begin_boot();
let report = runtime.tick(
&mut log,
&mut VirtualFS::new(),
&mut FsState::Unmounted,
&mut memcard,
&mut HashMap::new(),
&mut 1,
&mut vm,
&InputSignals::default(),
&mut TestPlatform::new(),
);
assert!(matches!(report, Some(CrashReport::VmTrap { .. })));
assert_eq!(vm.memcard_boot_result(), None);
}
@@ -70,38 +70,103 @@ impl VirtualMachineRuntime {
(glyph, sounds, scenes)
}
#[allow(clippy::too_many_arguments)]
pub fn debug_step_instruction(
&mut self,
log_service: &mut LogService,
fs: &mut VirtualFS,
fs_state: &mut FsState,
memcard: &mut MemcardService,
open_files: &mut HashMap<u32, String>,
next_handle: &mut u32,
vm: &mut VirtualMachine,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if vm.call_stack_is_empty() {
vm.prepare_boot_call();
if !platform.audio().ready() {
return None;
}
if vm.memcard_boot_result() == Some(0) && memcard.session.boot_pending() {
return None;
}
let was_memcard_boot = vm.memcard_boot_active();
if was_memcard_boot {
platform.audio_mut().begin_lifecycle();
}
if vm.call_stack_is_empty()
&& let Err(error) = vm.prepare_boot_call()
{
let report = CrashReport::VmInit { error };
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
let step_result = {
let mut ctx = HostContext::new_platform(Some(platform));
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files = HashMap::new();
let mut next_handle = 1;
let mut host = VmRuntimeHost {
runtime: self,
log_service,
fs: &mut fs,
fs_state: &mut fs_state,
memcard: &mut memcard,
open_files: &mut open_files,
next_handle: &mut next_handle,
fs,
fs_state,
memcard,
open_files,
next_handle,
};
vm.step(&mut host, &mut ctx)
};
// run_budget derives these terminal reasons after executing an instruction;
// single stepping must observe the same publication/cancellation boundary.
let step_result = if step_result.is_ok() && vm.is_halted() {
Err(LogicalFrameEndingReason::Halted)
} else if step_result.is_ok() && !was_memcard_boot && vm.call_stack_is_empty() {
Err(LogicalFrameEndingReason::EndOfRom)
} else {
step_result
};
if was_memcard_boot
&& step_result == Err(LogicalFrameEndingReason::LifecycleComplete)
&& let Err(error) = memcard.session.finish_boot(
vm.memcard_boot_result() == Some(0),
&memcard.lane,
Instant::now(),
)
{
let report = CrashReport::VmPanic {
message: format!("Memcard bootstrap failed: {error:?}: {}", memcard.diagnostic),
pc: Some(vm.pc() as u32),
};
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
if was_memcard_boot {
match &step_result {
Err(LogicalFrameEndingReason::LifecycleComplete) => {
platform.audio_mut().finish_lifecycle(true)
}
Err(
LogicalFrameEndingReason::Trap(_)
| LogicalFrameEndingReason::Panic(_)
| LogicalFrameEndingReason::Halted,
) => platform.audio_mut().finish_lifecycle(false),
_ => {}
}
}
match &step_result {
Err(LogicalFrameEndingReason::FrameSync | LogicalFrameEndingReason::EndOfRom) => {
platform.audio_mut().finish_frame()
}
Err(LogicalFrameEndingReason::Halted) => platform.audio_mut().reset(),
Err(LogicalFrameEndingReason::Trap(_) | LogicalFrameEndingReason::Panic(_)) => {
platform.audio_mut().abort_frame()
}
_ => {}
}
match step_result {
Ok(())
| Err(
LogicalFrameEndingReason::FrameSync
LogicalFrameEndingReason::LifecycleComplete
| LogicalFrameEndingReason::FrameSync
| LogicalFrameEndingReason::BudgetExhausted
| LogicalFrameEndingReason::Halted
| LogicalFrameEndingReason::EndOfRom
@@ -116,6 +181,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
format!("PVM Fault during Step: {}", report),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
Some(report)
}
@@ -128,12 +194,76 @@ impl VirtualMachineRuntime {
report.log_tag(),
format!("PVM Fault during Step: {}", report),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
Some(report)
}
}
}
/// Uses the session's real services, outside logical-frame accounting.
#[allow(clippy::too_many_arguments)]
pub(crate) fn tick_lifecycle(
&mut self,
log_service: &mut LogService,
fs: &mut VirtualFS,
fs_state: &mut FsState,
memcard: &mut MemcardService,
open_files: &mut HashMap<u32, String>,
next_handle: &mut u32,
vm: &mut VirtualMachine,
platform: &mut dyn RuntimePlatform,
single_step: bool,
) -> LogicalFrameEndingReason {
if self.paused && !single_step && !self.debug_step_request {
return LogicalFrameEndingReason::Breakpoint;
}
if !platform.audio().lifecycle_ready() {
return LogicalFrameEndingReason::BudgetExhausted;
}
platform.audio_mut().begin_lifecycle();
let result = catch_unwind(AssertUnwindSafe(|| {
let mut ctx = HostContext::new_platform(Some(platform));
let mut host = VmRuntimeHost {
runtime: self,
log_service,
fs,
fs_state,
memcard,
open_files,
next_handle,
};
if single_step {
vm.step(&mut host, &mut ctx)
.err()
.unwrap_or(LogicalFrameEndingReason::BudgetExhausted)
} else {
vm.run_budget(VirtualMachine::LIFECYCLE_SLICE, &mut host, &mut ctx)
.map(|report| report.reason)
.unwrap_or_else(LogicalFrameEndingReason::Panic)
}
}));
let reason = result.unwrap_or_else(|payload| {
LogicalFrameEndingReason::Panic(Self::host_panic_payload_to_string(payload))
});
match &reason {
LogicalFrameEndingReason::LifecycleComplete => {
platform.audio_mut().finish_lifecycle(true)
}
LogicalFrameEndingReason::BudgetExhausted | LogicalFrameEndingReason::Breakpoint => {}
_ => {
platform.audio_mut().finish_lifecycle(false);
platform.audio_mut().abort_frame();
}
}
if reason == LogicalFrameEndingReason::Breakpoint || single_step || self.debug_step_request
{
self.paused = true;
self.debug_step_request = false;
}
reason
}
#[allow(clippy::too_many_arguments)]
pub fn tick(
&mut self,
@@ -147,6 +277,56 @@ impl VirtualMachineRuntime {
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if vm.memcard_boot_active() {
let reason = self.tick_lifecycle(
log_service,
fs,
fs_state,
mem_card,
open_files,
next_handle,
vm,
platform,
false,
);
let failure = match reason {
LogicalFrameEndingReason::LifecycleComplete => {
let ready = vm.memcard_boot_result() == Some(0);
mem_card.session.finish_boot(ready, &mem_card.lane, Instant::now()).err().map(
|error| CrashReport::VmPanic {
message: format!(
"Memcard bootstrap failed: {error:?}: {}",
mem_card.diagnostic
),
pc: Some(vm.pc() as u32),
},
)
}
LogicalFrameEndingReason::BudgetExhausted
| LogicalFrameEndingReason::Breakpoint => None,
LogicalFrameEndingReason::Trap(trap) => Some(CrashReport::VmTrap { trap }),
other => Some(CrashReport::VmPanic {
message: format!("Memcard bootstrap stopped: {other:?}"),
pc: Some(vm.pc() as u32),
}),
};
if let Some(report) = &failure {
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
}
return failure;
}
if vm.memcard_boot_result() == Some(0) {
if let Some(error) = mem_card.session.boot_error() {
return Some(CrashReport::VmPanic {
message: format!("Memcard registration failed: {error:?}"),
pc: Some(vm.pc() as u32),
});
}
if mem_card.session.boot_pending() {
return None;
}
}
let start = Instant::now();
self.tick_index += 1;
@@ -154,6 +334,9 @@ impl VirtualMachineRuntime {
return None;
}
if !platform.audio().ready() {
return None;
}
self.update_fs(log_service, fs, fs_state);
if !self.logical_frame_active {
if RenderManager::policy_for_app_mode(self.current_cartridge_app_mode)
@@ -168,7 +351,12 @@ impl VirtualMachineRuntime {
self.begin_logical_frame(signals, platform);
if self.needs_prepare_entry_call || vm.call_stack_is_empty() {
vm.prepare_boot_call();
if let Err(error) = vm.prepare_boot_call() {
let report = CrashReport::VmInit { error };
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
self.needs_prepare_entry_call = false;
}
@@ -214,6 +402,9 @@ impl VirtualMachineRuntime {
self.atomic_telemetry.cycles_used.fetch_add(run.cycles_used, Ordering::Relaxed);
self.atomic_telemetry.vm_steps.fetch_add(run.steps_executed, Ordering::Relaxed);
if run.reason == LogicalFrameEndingReason::Halted {
platform.audio_mut().reset();
}
if run.reason == LogicalFrameEndingReason::Breakpoint {
self.paused = true;
self.debug_step_request = false;
@@ -236,6 +427,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
report.summary(),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -249,6 +441,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
report.summary(),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -373,6 +566,8 @@ impl VirtualMachineRuntime {
log_service.reset_count();
// Entry return is the runtime's successful implicit frame end.
platform.audio_mut().finish_frame();
self.logical_frame_index += 1;
self.logical_frame_active = false;
self.logical_frame_remaining_cycles = 0;
@@ -382,9 +577,8 @@ impl VirtualMachineRuntime {
self.frame_scheduler.complete_game_frame();
}
if run.reason == LogicalFrameEndingReason::FrameSync {
self.needs_prepare_entry_call = true;
}
self.needs_prepare_entry_call =
run.reason == LogicalFrameEndingReason::EndOfRom;
if self.debug_step_request {
self.paused = true;
@@ -406,6 +600,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
report.summary(),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -456,7 +651,7 @@ impl VirtualMachineRuntime {
platform: &mut dyn RuntimePlatform,
) {
platform.game2d_frame_composer().begin_frame();
platform.audio_mut().clear_commands();
platform.audio_mut().begin_frame();
self.logs_written_this_frame.clear();
}
}
@@ -20,7 +20,27 @@ pub enum VmSessionError {
ProcessIsNotVmBacked(ProcessId),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum LifecycleTransition {
PauseToHub,
PauseToShell(TaskId),
Resume,
}
impl LifecycleTransition {
pub(crate) fn role(self) -> prometeu_bytecode::registry::LifecycleRole {
use prometeu_bytecode::registry::LifecycleRole;
match self {
Self::Resume => LifecycleRole::BeforeResume,
_ => LifecycleRole::BeforePause,
}
}
}
pub struct VmSession {
pub(crate) lifecycle_transition: Option<LifecycleTransition>,
pub(crate) lifecycle_started: bool,
pub(crate) pause_hook_complete: bool,
pub id: VmSessionId,
pub task_id: TaskId,
pub process_id: ProcessId,
@@ -45,6 +65,9 @@ impl VmSession {
logs_count: Arc<AtomicU32>,
) -> Self {
Self {
lifecycle_transition: None,
lifecycle_started: false,
pause_hook_complete: false,
id: VmSessionId(task.id),
task_id: task.id,
process_id: process.id,
+12
View File
@@ -4,9 +4,21 @@ version = "0.1.0"
edition = "2024"
license.workspace = true
[features]
resource-diagnostics = []
[[example]]
name = "resource_qualification"
required-features = ["resource-diagnostics"]
[dependencies]
prometeu-bytecode = { path = "../prometeu-bytecode" }
prometeu-hal = { path = "../prometeu-hal" }
fpmath = { version = "=0.1.1", features = ["soft-float"] }
[dev-dependencies]
prometeu-test-support = { path = "../../dev/prometeu-test-support" }
[[example]]
name = "string_provenance_benchmark"
required-features = ["resource-diagnostics"]
@@ -0,0 +1,7 @@
fn main() {
if std::env::args().nth(1).as_deref() == Some("constants") {
print!("{}", prometeu_vm::builtin_constant_catalog_csv());
} else {
print!("{}", prometeu_vm::intrinsic_catalog_csv());
}
}
@@ -0,0 +1,49 @@
//! Local host timing only; these measurements never define guest cycles.
use prometeu_bytecode::Value;
use prometeu_vm::{HostContext, lookup_intrinsic_by_id};
use std::hint::black_box;
use std::time::Instant;
fn main() {
let iterations: u32 =
std::env::args().nth(1).unwrap_or_else(|| "20000".into()).parse().unwrap();
for (id, args) in [
(0x3010, vec![Value::Float(2.)]),
(0x3011, vec![Value::Float(f64::from_bits(0x6974e718d7d7625a))]),
(0x3012, vec![Value::Float(f64::from_bits(0x7fefffffffffffff))]),
(0x3013, vec![Value::Float(1.), Value::Float(3.)]),
(0x1000, vec![Value::Float(1.), Value::Float(2.), Value::Float(3.), Value::Float(4.)]),
(0x1001, vec![Value::Float(1e200), Value::Float(1e200)]),
] {
let m = lookup_intrinsic_by_id(id).unwrap();
let mut ctx = HostContext::new(None);
for _ in 0..100 {
black_box(
(m.implementation.host_callback().expect("host intrinsic"))(
black_box(&args),
&mut ctx,
)
.unwrap(),
);
}
let start = Instant::now();
for _ in 0..iterations {
black_box(
(m.implementation.host_callback().expect("host intrinsic"))(
black_box(&args),
&mut ctx,
)
.unwrap(),
);
}
let elapsed = start.elapsed().as_nanos();
println!(
"{}.{} iterations={} total_ns={} ns_per_call={:.2} virtual_cycles={}",
m.owner,
m.name,
iterations,
elapsed,
elapsed as f64 / f64::from(iterations),
m.cost_cycles
);
}
}
@@ -0,0 +1,94 @@
//! Reproducible bit-level probe for independent tooling; not a cartridge dependency.
//! stdin: intrinsic hex ID followed by f:bits / i:decimal / l:decimal.
//! Arithmetic opcode names ADD/SUB/MUL/DIV execute a validated PBX program.
use prometeu_bytecode::{Value, assemble};
use prometeu_hal::vm_fault::VmFault;
use prometeu_vm::{
HostContext, HostReturn, LogicalFrameEndingReason, NativeInterface, VirtualMachine,
lookup_intrinsic_by_id,
};
use std::io::{self, BufRead};
struct NoNative;
impl NativeInterface for NoNative {
fn syscall(
&mut self,
_: u32,
_: &[Value],
_: &mut HostReturn,
_: &mut HostContext,
) -> Result<(), VmFault> {
panic!("no native call in numeric probe")
}
}
fn text(value: &Value) -> String {
match value {
Value::Float(x) => format!("f:{:016x}", x.to_bits()),
Value::Int32(x) => format!("i:{x}"),
Value::Int64(x) => format!("l:{x}"),
_ => panic!("numeric output"),
}
}
fn main() {
for line in io::stdin().lock().lines() {
let line = line.unwrap();
let mut words = line.split_whitespace();
let op = words.next().unwrap();
let args: Vec<_> = words
.map(|s| {
let (kind, v) = s.split_once(':').unwrap();
match kind {
"f" => Value::Float(f64::from_bits(u64::from_str_radix(v, 16).unwrap())),
"i" => Value::Int32(v.parse().unwrap()),
"l" => Value::Int64(v.parse().unwrap()),
_ => panic!("carrier"),
}
})
.collect();
if !matches!(op, "ADD" | "SUB" | "MUL" | "DIV") {
let id = u32::from_str_radix(op, 16).unwrap();
let m = lookup_intrinsic_by_id(id).unwrap();
match (m.implementation.host_callback().expect("host intrinsic"))(
&args,
&mut HostContext::new(None),
) {
Ok(v) => println!("{} {}", text(&v[0]), m.cost_cycles),
Err(prometeu_vm::IntrinsicExecutionError::Numeric(e)) => {
println!("trap:{:x} {}", e.code, m.cost_cycles)
}
Err(e) => panic!("{e:?}"),
}
} else {
let mut source = String::new();
for v in args {
source.push_str(&match v {
Value::Float(x) => format!("PUSH_F64 f64:0x{:016x}\n", x.to_bits()),
Value::Int32(x) => format!("PUSH_I32 {x}\n"),
Value::Int64(x) => format!("PUSH_I64 {x}\n"),
_ => unreachable!(),
});
}
source.push_str(op);
source.push_str("\nHALT");
let bytes = prometeu_test_support::program::TestProgram::single(
assemble(&source).unwrap(),
Default::default(),
0,
8,
)
.serialize();
let mut vm = VirtualMachine::default();
vm.initialize(bytes).unwrap();
vm.prepare_call("0").unwrap();
let r = vm.run_budget(100, &mut NoNative, &mut HostContext::new(None)).unwrap();
match r.reason {
LogicalFrameEndingReason::Halted => {
println!("{} {}", text(&vm.operand_stack_top(1)[0]), r.cycles_used)
}
LogicalFrameEndingReason::Trap(e) => {
println!("trap:{:x} {}", e.code, r.cycles_used)
}
e => panic!("{e:?}"),
}
}
}
}

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