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

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

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

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

Validation: tooling make verify passed runtime ci-domains and integration.
2026-11-19 17:32:02 +00:00
bquarkz 2d5735cb13 chore: retire Discussion Framework workflow and retain lessons
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-11-16 16:45:34 +00:00
bquarkz dccf4d0775 fix(ci): declare llvm-tools-preview in pinned toolchain
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-11-16 10:00:49 +00:00
bquarkz c3589be1ad fix(headless): wait for memcard bootstrap IO progress
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
Coordinate bounded native publication progress during frame advance while preserving watchdogs, guest budgets and resource ownership. Add controlled and packaged reopen regressions, clarify the runtime specs, and retain qualification evidence.
2026-11-10 23:26:40 +00:00
bquarkz 49d7fca0b7 chore(toolchain): pin Rust to 1.98.1
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
2026-11-10 22:39:19 +00:00
bquarkz c649e02816 feat(headless): expose negotiated native log observation 2026-11-10 21:57:34 +00:00
bquarkz 09d8778f04 fix(runtime): support older stable Rust atomic updates
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-11-05 09:00:19 +00:00
bquarkz 1aa939eca8 fix(runtime): replace deprecated atomic fetch_update calls
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
2026-11-03 00:01:58 +00:00
bquarkz a4bec5bc45 feat(host): expose memcard controls and qualify process persistence
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
2026-10-30 10:10:07 +00:00
202 changed files with 40782 additions and 1053 deletions
+4 -3
View File
@@ -13,9 +13,10 @@ jobs:
with: with:
submodules: recursive submodules: recursive
- uses: dtolnay/rust-toolchain@stable - name: Install repository Rust toolchain
with: run: |
components: rustfmt, clippy, llvm-tools-preview toolchain=$(python3 -c 'import tomllib; print(tomllib.load(open("rust-toolchain.toml", "rb"))["toolchain"]["channel"])')
rustup toolchain install "$toolchain" --profile minimal
- uses: Swatinem/rust-cache@v2 - uses: Swatinem/rust-cache@v2
-4
View File
@@ -66,7 +66,3 @@ AGENTS.md
.python-version .python-version
.venv .venv
discussion/*
!discussion/lessons/
!discussion/lessons/**
Generated
+4
View File
@@ -1883,6 +1883,7 @@ dependencies = [
"anyhow", "anyhow",
"prometeu-bytecode", "prometeu-bytecode",
"prometeu-hal", "prometeu-hal",
"prometeu-host-headless",
"serde_json", "serde_json",
] ]
@@ -1892,7 +1893,10 @@ version = "0.1.0"
dependencies = [ dependencies = [
"anyhow", "anyhow",
"prometeu-bytecode", "prometeu-bytecode",
"prometeu-drivers",
"prometeu-hal", "prometeu-hal",
"prometeu-host-headless",
"prometeu-vm",
"serde_json", "serde_json",
] ]
+13 -6
View File
@@ -1,4 +1,4 @@
.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 .PHONY: fmt fmt-check clippy test-unit test-local test-integration test-debugger-socket clean coverage coverage-xml coverage-json coverage-report-json coverage-domain-list coverage-domain-evidence coverage-domain-audit coverage-domain-gate test ci ci-domains cobertura
fmt: fmt:
cargo fmt --all cargo fmt --all
@@ -9,8 +9,15 @@ fmt-check:
clippy: clippy:
cargo clippy --workspace --all-targets --all-features -- -D warnings cargo clippy --workspace --all-targets --all-features -- -D warnings
test-local: test-unit:
cargo test --workspace --all-targets --all-features --no-fail-fast cargo test --workspace --lib --bins --all-features --no-fail-fast
# Compatibility entry point: repository-local verification is unit-only.
test-local: test-unit
# Explicit opt-in, orchestrated by ../tooling; test sources stay in this repository.
test-integration:
cargo test --workspace --tests --all-features --no-fail-fast
test-debugger-socket: test-debugger-socket:
cargo test -p prometeu-host-desktop-winit --lib runner::tests -- --ignored cargo test -p prometeu-host-desktop-winit --lib runner::tests -- --ignored
@@ -19,7 +26,7 @@ clean:
cargo llvm-cov clean --workspace cargo llvm-cov clean --workspace
coverage: coverage:
cargo llvm-cov --workspace --all-features --html --output-dir target/llvm-cov cargo llvm-cov --workspace --lib --bins --all-features --html --output-dir target/llvm-cov
coverage-report-json: coverage-report-json:
cargo llvm-cov report --json --output-path target/llvm-cov/report.json cargo llvm-cov report --json --output-path target/llvm-cov/report.json
@@ -46,9 +53,9 @@ coverage-domain-evidence:
coverage-domain-gate: coverage-domain-gate:
./scripts/coverage-domain-evidence.sh --check-all ./scripts/coverage-domain-evidence.sh --check-all
test: fmt-check clippy test-local test-debugger-socket test: fmt-check clippy test-unit
# Local and GitHub entry point; Jenkins exposes the same targets as stages. # 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_DOMAIN_STEPS = clean fmt-check clippy test-unit coverage coverage-report-json coverage-xml coverage-json coverage-domain-audit coverage-domain-gate
ci: ci-domains ci: ci-domains
ci-domains: ci-domains:
+29 -8
View File
@@ -1,14 +1,14 @@
# PROMETEU Runtime # PROMETEU Runtime
PROMETEU is an educational and experimental fantasy handheld / fantasy console. PROMETEU is an educational and experimental fantasy handheld / fantasy console.
This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, firmware/system services, host integration, CLI entrypoints, development utilities, specs, and discussion artifacts. This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, firmware/system services, host integration, CLI entrypoints, development utilities, specs, and engineering lessons.
The VM is only one subsystem of the machine. The canonical docs in this repository intentionally distinguish: The VM is only one subsystem of the machine. The canonical docs in this repository intentionally distinguish:
- machine-level specs; - machine-level specs;
- VM/runtime internal architecture; - VM/runtime internal architecture;
- implementation crates; - implementation crates;
- discussion workflow and lessons learned. - engineering lessons learned.
## What This Repository Contains ## What This Repository Contains
@@ -19,7 +19,7 @@ The VM is only one subsystem of the machine. The canonical docs in this reposito
- `docs/specs/runtime/`: canonical PROMETEU machine specs - `docs/specs/runtime/`: canonical PROMETEU machine specs
- `docs/vm-arch/`: canonical VM/runtime architecture and ISA references - `docs/vm-arch/`: canonical VM/runtime architecture and ISA references
- `devtools/`: debugger protocol material - `devtools/`: debugger protocol material
- `discussion/`: agendas, decisions, plans, and lessons for architectural work - `discussion/lessons/`: published engineering lessons and supporting assets
- `test-cartridges/`: cartridge fixtures used for validation and manual runs - `test-cartridges/`: cartridge fixtures used for validation and manual runs
## Canonical Documentation ## Canonical Documentation
@@ -29,7 +29,11 @@ Use these entrypoints instead of inferring the model from isolated source files:
- [Machine specs](docs/specs/runtime/README.md): authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI - [Machine specs](docs/specs/runtime/README.md): authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI
- [VM architecture](docs/vm-arch/ARCHITECTURE.md): authoritative internal architecture for VM/runtime invariants - [VM architecture](docs/vm-arch/ARCHITECTURE.md): authoritative internal architecture for VM/runtime invariants
- [ISA reference](docs/vm-arch/ISA_CORE.md): bytecode-level instruction set authority - [ISA reference](docs/vm-arch/ISA_CORE.md): bytecode-level instruction set authority
- [Discussion workflow](discussion/index.ndjson): architectural agenda, decision, and execution traceability - [Engineering lessons](discussion/lessons/): published results and rationale
Engineering discussions, decisions, plans and execution evidence are maintained in
the enclosing [Prometeu Engineering workspace](../README.md) using
[AI Engineering](../.ai-engineering/README.md).
## Workspace Layout ## Workspace Layout
@@ -60,11 +64,21 @@ Other ecosystem commands, such as build, pack, and verification tooling, are not
## Requirements ## Requirements
- Rust toolchain from [rust-toolchain.toml](rust-toolchain.toml) - Rust **1.98.1**, pinned in [rust-toolchain.toml](rust-toolchain.toml)
- `rustup` for toolchain installation and management - `rustup` for toolchain installation and management
- `cargo-llvm-cov` for coverage targets such as `make coverage` and `make ci-domains` - `cargo-llvm-cov` for coverage targets such as `make coverage` and `make ci-domains`
- a local graphical environment for desktop runtime commands - a local graphical environment for desktop runtime commands
From the repository root, install and verify the pinned toolchain:
```bash
rustup toolchain install 1.98.1 --profile minimal --component rustfmt,clippy
rustc --version
```
Rustup selects the pinned version automatically for commands run in this repository.
CI installs the toolchain from the same file.
## Quick Start ## Quick Start
Build the workspace: Build the workspace:
@@ -119,7 +133,14 @@ The authoritative target used by both GitHub and Jenkins is:
make ci-domains make ci-domains
``` ```
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). `make test-unit` selects library and binary unit-test harnesses with
`--lib --bins --all-features`; `test-local` remains an alias. Both `make test`
and `make ci-domains` run only this suite. Integration targets under `tests/`,
installed-process qualification and the five ignored debugger socket tests are
excluded from the pipeline. They remain available explicitly through
`make test-integration` and `make test-debugger-socket`, orchestrated by
`../tooling`. Tests and fixtures stay in this repository. Physical audio and manual probes remain opt-in. See
[quality-gate prerequisites and commands](docs/vm-arch/COVERAGE_DOMAINS.md#commands-and-ci).
## Coverage Governance ## Coverage Governance
@@ -156,7 +177,7 @@ make coverage-domain-evidence DOMAIN=host/headless
``` ```
`make ci-domains` runs formatting, strict workspace/all-target/all-feature Clippy, `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 library/binary unit tests, fresh unit-only coverage and every domain
ownership/evidence gate. Both CI providers archive available evidence on failure. 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 A failing run never lowers a configured floor; local and CI checks use the same
repository-owned commands. Reports identify their revision, source/configuration repository-owned commands. Reports identify their revision, source/configuration
@@ -173,7 +194,7 @@ Improving the global percentage alone is not sufficient review evidence when the
The project is still in active architectural and implementation convergence. The project is still in active architectural and implementation convergence.
- the machine contract is being clarified through the specs and discussion workflow; - the machine contract is being clarified through the specs and AI Engineering;
- the workspace already contains concrete runtime and host code; - the workspace already contains concrete runtime and host code;
- the CLI dispatcher currently exposes the runtime paths that are backed by binaries in this workspace. - the CLI dispatcher currently exposes the runtime paths that are backed by binaries in this workspace.
@@ -0,0 +1,256 @@
//! Repeatable CPU/memory observations, not a handheld or physical-device guarantee.
use prometeu_drivers::{
Audio, MemoryBanks, SoundBankPoolInstaller,
bank_format::{decode_audio_bank, encode_ima_wav4},
engine::{AudioMixer, Packet},
};
use prometeu_hal::{
AudioBridge, LoopMode,
audio_bridge::AudioControl,
music_bank::{Instrument, MusicBank, MusicEvent},
sample::Sample,
sound_bank::SoundBank,
};
use serde_json::{Value, json};
use std::{
alloc::{GlobalAlloc, Layout, System},
sync::{
Arc,
atomic::{AtomicUsize, Ordering},
},
time::Instant,
};
struct Counter;
static LIVE: AtomicUsize = AtomicUsize::new(0);
static PEAK: AtomicUsize = AtomicUsize::new(0);
unsafe impl GlobalAlloc for Counter {
unsafe fn alloc(&self, l: Layout) -> *mut u8 {
let p = unsafe { System.alloc(l) };
if !p.is_null() {
let n = LIVE.fetch_add(l.size(), Ordering::Relaxed) + l.size();
PEAK.fetch_max(n, Ordering::Relaxed);
}
p
}
unsafe fn dealloc(&self, p: *mut u8, l: Layout) {
LIVE.fetch_sub(l.size(), Ordering::Relaxed);
unsafe { System.dealloc(p, l) }
}
}
#[global_allocator]
static ALLOCATOR: Counter = Counter;
fn stats(values: &mut [u64]) -> Value {
values.sort_unstable();
let n = values.len();
json!({"p50_ns":values[n/2],"p95_ns":values[n*95/100],"p99_ns":values[n*99/100],"max_ns":values[n-1]})
}
fn music(channels: u8) -> Arc<MusicBank> {
let pcm = (0..4096)
.flat_map(|i| {
std::iter::repeat_n(((i as f64 * 0.05).sin() * 800.0) as i16, channels as usize)
})
.collect();
let sample =
Arc::new(Sample::new(48000, pcm).with_channels(channels).unwrap().with_loop(0, 4096));
let events = (0..12)
.map(|id| MusicEvent { kind: 1, a: id, c: 60 + id as i32, d: 180, ..Default::default() })
.collect();
Arc::new(
MusicBank::compile(
"measure".into(),
vec![sample],
vec![Instrument {
looping: true,
attack_us: 1000,
decay_us: 10_000,
sustain: 50000,
release_us: 10_000,
send: 20000,
vibrato_cents: 10,
vibrato_millihz: 5000,
tremolo_depth: 1000,
tremolo_millihz: 3000,
..Default::default()
}],
events,
960,
500000,
3840,
None,
1,
)
.unwrap(),
)
}
fn scenario(channels: u8, dsp: bool, replacement: bool) -> Value {
let banks = Arc::new(MemoryBanks::new());
let mut audio = Audio::new(banks.clone());
banks.install_music_bank(0, music(channels));
banks.install_music_bank(1, music(channels));
audio.music_play(0, 0, true);
audio.music_play(1, 1, true);
let sample = Arc::new(
Sample::new(48000, vec![500; 4096 * channels as usize])
.with_channels(channels)
.unwrap()
.with_loop(0, 4096),
);
for voice in 0..8 {
audio.play_sample(sample.clone(), voice, 255, 128, 1.0, 0, LoopMode::On);
audio.control(AudioControl::SfxSend { voice, gain: 100 });
}
if dsp {
for group in 0..3 {
audio.control(AudioControl::Effect {
group,
cutoff_hz: 6000,
delay_frames: 4800,
feedback: 0.5,
wet: 0.3,
dry: 0.7,
});
}
}
audio.finish_frame();
let mut mixer = AudioMixer::new();
let mut packet = Packet::new();
mixer.apply_delivery_into(audio.transport().try_take().unwrap(), &mut packet);
packet.recycle(&audio.transport());
let mut pcm = [0.0; 512];
let mut timings = Vec::with_capacity(1000);
let mut overruns = 0;
let mut max_retired = 0;
let baseline = LIVE.load(Ordering::Relaxed);
PEAK.store(baseline, Ordering::Relaxed);
for iteration in 0..1000 {
if replacement && iteration % 10 == 0 {
banks.install_music_bank(0, music(channels));
audio.music_play(0, 0, true);
audio.control(AudioControl::MusicFade {
group: 1,
gain: 180,
frames: 2400,
smooth: true,
});
audio.finish_frame();
}
let start = Instant::now();
mixer.retire_inactive(&mut packet);
if let Some(delivery) = audio.transport().try_take() {
mixer.apply_delivery_into(delivery, &mut packet);
}
mixer.mix(&mut pcm);
mixer.retire_inactive(&mut packet);
let elapsed = start.elapsed().as_nanos() as u64;
if elapsed > 5_333_333 {
overruns += 1;
}
timings.push(elapsed);
max_retired = max_retired.max(packet.retained_pcm_bytes());
packet.recycle(&audio.transport());
std::hint::black_box(&pcm);
}
json!({"channels_per_voice":channels,"dsp":dsp,"replacement_every_10_buffers":replacement,"buffers":1000,"frames_per_buffer":256,"nominal_buffer_ns":5_333_333,"observed_budget_overruns":overruns,"timing":stats(&mut timings),"maximum_active_voices":mixer.diagnostics.maximum_voices,"engine_prepared_bytes":mixer.prepared_bytes(),"maximum_retired_pcm_bytes":max_retired,"baseline_allocated_bytes":baseline,"peak_allocated_bytes":PEAK.load(Ordering::Relaxed)})
}
fn codec_and_memory() -> Value {
let pcm: Vec<i16> = (0..480_000)
.flat_map(|i| {
[((i as f64 * 0.04).sin() * 12000.0) as i16, ((i as f64 * 0.06).cos() * 9000.0) as i16]
})
.collect();
let start = Instant::now();
let compressed = encode_ima_wav4(&pcm, 2, 512).unwrap();
let encode_ns = start.elapsed().as_nanos();
let mut bytes = vec![0u8; 88];
bytes[..4].copy_from_slice(b"SBNK");
bytes[4] = 1;
bytes[48] = 1;
bytes[49] = 2;
bytes[80] = 255;
bytes[81] = 128;
for (at, n) in [
(8, 1u32),
(20, 960),
(24, 500000),
(32, u32::MAX),
(52, 48000),
(56, 480000),
(68, 88),
(72, compressed.len() as u32),
(84, 65536),
] {
bytes[at..at + 4].copy_from_slice(&n.to_le_bytes());
}
bytes[76..78].copy_from_slice(&512u16.to_le_bytes());
bytes[78..80].copy_from_slice(&505u16.to_le_bytes());
bytes.extend(&compressed);
let mut decode = Vec::with_capacity(20);
let baseline = LIVE.load(Ordering::Relaxed);
PEAK.store(baseline, Ordering::Relaxed);
for _ in 0..20 {
let start = Instant::now();
let bank = decode_audio_bank(&bytes, false).unwrap();
decode.push(start.elapsed().as_nanos() as u64);
std::hint::black_box(bank);
}
let decode_peak = PEAK.load(Ordering::Relaxed);
let banks = MemoryBanks::new();
for slot in 0..16 {
banks.install_sound_bank(
slot,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48000, vec![0; 1_048_576]))])),
);
}
let large_music = || {
let sample = Arc::new(Sample::new(48000, vec![0; 1_048_576]).with_loop(0, 1_048_576));
Arc::new(
MusicBank::compile(
"large".into(),
vec![sample],
vec![Instrument { looping: true, ..Default::default() }],
vec![MusicEvent { kind: 1, a: 1, c: 60, d: 255, ..Default::default() }],
960,
500000,
3840,
None,
1,
)
.unwrap(),
)
};
for slot in 0..16 {
banks.install_music_bank(slot, large_music());
}
let snapshot = banks.audio_memory();
let mut mixer = AudioMixer::new();
let mut packet = Packet::new();
use prometeu_drivers::SoundBankPoolAccess;
mixer.apply_delivery_into(
prometeu_drivers::AudioDelivery {
epoch: 0,
paused: false,
frame: Some(vec![prometeu_drivers::AudioCommand::MusicPlay {
group: 0,
bank: banks.music_bank_slot(0).unwrap(),
looping: true,
}]),
lifecycle: None,
},
&mut packet,
);
packet.recycle(&prometeu_drivers::AudioTransport::default());
mixer.mix(&mut [0.0; 2]);
let before = LIVE.load(Ordering::Relaxed);
PEAK.store(before, Ordering::Relaxed);
banks.install_music_bank(0, large_music());
mixer.retire_inactive(&mut packet);
let retired = packet.retained_pcm_bytes();
let replacement_peak = PEAK.load(Ordering::Relaxed);
packet.recycle(&prometeu_drivers::AudioTransport::default());
let after = LIVE.load(Ordering::Relaxed);
json!({"source_frames":480000,"channels":2,"pcm_bytes":pcm.len()*2,"cartridge_sample_bytes":compressed.len(),"compression_ratio":compressed.len()as f64/(pcm.len()*2)as f64,"encode_ns":encode_ns,"decode_timing":stats(&mut decode),"decode_baseline_allocated_bytes":baseline,"decode_peak_allocated_bytes":decode_peak,"large_bank_count":snapshot.banks.len(),"large_banks_unique_pcm_bytes":snapshot.unique_pcm_bytes,"replacement_baseline_allocated_bytes":before,"replacement_peak_allocated_bytes":replacement_peak,"replacement_after_reclamation_bytes":after,"retained_replaced_pcm_bytes":retired,"resident_accounted_metadata_bytes":snapshot.metadata_bytes,"resident_total_accounted_bytes":snapshot.total_accounted_bytes})
}
fn main() {
println!("{}",serde_json::to_string_pretty(&json!({"arch":std::env::consts::ARCH,"os":std::env::consts::OS,"observations":[scenario(1,false,false),scenario(2,false,false),scenario(2,true,false),scenario(2,true,true)],"codecs_and_memory":codec_and_memory()})).unwrap());
}
@@ -0,0 +1,185 @@
//! Controlled graphics measurement. This is not a cartridge stress-suite replacement.
use prometeu_drivers::{Gfx, GlyphBankPoolInstaller, MemoryBanks, hardware::Hardware};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{GlyphBank, TileSize};
use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::scene_viewport_cache::SceneViewportCache;
use prometeu_hal::scene_viewport_resolver::SceneViewportResolver;
use prometeu_hal::sprite::Sprite;
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use prometeu_hal::{FrameId, OwnedRgba8888Frame, RenderOwnership, app_mode::AppMode};
use std::alloc::{GlobalAlloc, Layout, System};
use std::sync::{
Arc,
atomic::{AtomicUsize, Ordering},
};
use std::time::Instant;
struct CountingAllocator;
static LIVE: AtomicUsize = AtomicUsize::new(0);
static PEAK: AtomicUsize = AtomicUsize::new(0);
static ALLOCATIONS: AtomicUsize = AtomicUsize::new(0);
// Only the measurement executable pays the atomic allocation instrumentation cost.
unsafe impl GlobalAlloc for CountingAllocator {
unsafe fn alloc(&self, layout: Layout) -> *mut u8 {
let ptr = unsafe { System.alloc(layout) };
if !ptr.is_null() {
let live = LIVE.fetch_add(layout.size(), Ordering::Relaxed) + layout.size();
PEAK.fetch_max(live, Ordering::Relaxed);
ALLOCATIONS.fetch_add(1, Ordering::Relaxed);
}
ptr
}
unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) {
LIVE.fetch_sub(layout.size(), Ordering::Relaxed);
unsafe { System.dealloc(ptr, layout) };
}
}
#[global_allocator]
static ALLOCATOR: CountingAllocator = CountingAllocator;
fn summary(samples: &mut [u64]) -> serde_json::Value {
samples.sort_unstable();
let n = samples.len();
serde_json::json!({"mean_us": samples.iter().sum::<u64>() as f64 / n as f64 / 1000.0,
"p95_us": samples[(n * 95).div_ceil(100) - 1] as f64 / 1000.0,
"p99_us": samples[(n * 99).div_ceil(100) - 1] as f64 / 1000.0,
"max_us": samples[n-1] as f64 / 1000.0,
"over_60hz_budget": samples.iter().filter(|&&v| v > 1_000_000_000 / 60).count()})
}
fn main() {
let count: usize =
std::env::args().nth(1).map(|v| v.parse().expect("frame count")).unwrap_or(600);
assert!(count > 0);
let (w, h) = (Hardware::W, Hardware::H);
let banks = Arc::new(MemoryBanks::new());
let mixed = std::env::args().nth(2).as_deref() == Some("mixed");
let sizes = if mixed {
[TileSize::Size8, TileSize::Size16, TileSize::Size32, TileSize::Size8]
} else {
[TileSize::Size16; 4]
};
for (i, size) in sizes.iter().enumerate() {
let edge = *size as usize;
let mut bank = GlyphBank::new(*size, edge, edge);
bank.palettes[0][1] = Color::rgba((i * 47 + 30) as u8, 120, 210, 255);
// Transparent holes make all four layers participate in the visible output.
for (p, pixel) in bank.pixel_indices.iter_mut().enumerate() {
*pixel = u8::from(i == 0 || (p + i) % 3 != 0);
}
banks.install_glyph_bank(i, Arc::new(bank));
}
let scene = SceneBank {
layers: std::array::from_fn(|i| SceneLayer {
active: true,
glyph_asset_id: i as i32,
tile_size: sizes[i],
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap {
width: 160,
height: 100,
tiles: vec![
Tile {
active: true,
glyph: Glyph { glyph_id: 0, palette_id: 0 },
flip_x: false,
flip_y: false,
};
160 * 100
],
},
}),
};
let min_tile = if mixed { 8 } else { 16 };
let (cw, ch) = (w.div_ceil(min_tile) + 5, h.div_ceil(min_tile) + 4);
let mut cache = SceneViewportCache::new(&scene, cw, ch);
let mut resolver = SceneViewportResolver::new(
w as i32,
h as i32,
cw,
ch,
min_tile as i32 - 4,
min_tile as i32 + 4,
);
let mut gfx = Gfx::new(w, h, banks);
let sprites: Vec<_> = (0..512)
.map(|i| Sprite {
glyph: Glyph { glyph_id: 0, palette_id: 0 },
x: ((i * 37) % w) as i32,
y: ((i * 53) % h) as i32,
layer: (i % 4) as u8,
bank_id: (i % 4) as u8,
active: true,
flip_x: i % 2 == 0,
flip_y: i % 3 == 0,
priority: (i % 4) as u8,
})
.collect();
gfx.load_frame_sprites(&sprites);
let mut compose = Vec::with_capacity(count);
let mut publish = Vec::with_capacity(count);
let mut upload = Vec::with_capacity(count);
let mut total = Vec::with_capacity(count);
let mut rgba = vec![0u8; w * h * 4];
let ownership = RenderOwnership::new(1, AppMode::Game, 1);
let mut checksum = 0u32;
for frame_id in 0..(count + 120) {
// Resolve/materialize cache outside the raster timing; total includes it.
let start = Instant::now();
let update = resolver.update(&scene, (frame_id % 71) as i32, (frame_id % 43) as i32);
for request in &update.copy_requests {
cache.move_layer_window_to(
request.layer_index,
request.cache_origin_tile_x,
request.cache_origin_tile_y,
);
}
cache.materialize_all_layers(&scene);
let t = Instant::now();
gfx.render_scene_from_cache(&cache, &update, &[0, 1, 2, 3]);
gfx.fill_rect(0, h as i32 - 8, w as i32, 8, Color::WHITE);
let raster = t.elapsed().as_nanos() as u64;
let t = Instant::now();
gfx.present();
let frame = OwnedRgba8888Frame::packed(
FrameId::new(frame_id as u64),
ownership,
w,
h,
gfx.front_buffer().to_vec(),
)
.unwrap();
let publication = t.elapsed().as_nanos() as u64;
let t = Instant::now();
for (pixel, bytes) in frame.pixels.iter().zip(rgba.as_chunks_mut::<4>().0.iter_mut()) {
bytes.copy_from_slice(&pixel.to_be_bytes());
}
std::hint::black_box(&rgba);
let staging = t.elapsed().as_nanos() as u64;
checksum ^= frame.pixels[(frame_id * 173) % (w * h)];
if frame_id >= 120 {
compose.push(raster);
publish.push(publication);
upload.push(staging);
total.push(start.elapsed().as_nanos() as u64);
}
}
let live = LIVE.load(Ordering::Relaxed);
let peak = PEAK.load(Ordering::Relaxed);
let allocations = ALLOCATIONS.load(Ordering::Relaxed);
println!(
"{}",
serde_json::json!({"schema":1,"width":w,"height":h,"frames":count,
"warmup_frames":120,"tiles":sizes.map(|s|s as u32),"sprites_accepted":512,"layers":4,
"framebuffer_bytes":w*h*4,"front_back_bytes":w*h*8,"host_staging_bytes":rgba.len(),
"compose":summary(&mut compose),"publish_owned":summary(&mut publish),
"rgba_staging":summary(&mut upload),"total":summary(&mut total),
"allocated_live_bytes":live,"allocated_peak_bytes":peak,"allocation_count":allocations,
"checksum":checksum,"vm_hz":null,"physical_display_hz":null,
"limitations":"unpaced controlled raster/cache/owned publication/staging; no VM, IPC or GPU present; allocator instrumented; RSS is measured by the process wrapper"})
);
}
+243 -9
View File
@@ -1,6 +1,7 @@
#![allow(clippy::collapsible_if)] #![allow(clippy::collapsible_if)]
mod decode; mod decode;
mod resumable; mod resumable;
use crate::audio::bank_format::{DecodedAudioBank, decode_audio_bank};
use crate::memory_banks::{GlyphBankPoolInstaller, SceneBankPoolInstaller, SoundBankPoolInstaller}; use crate::memory_banks::{GlyphBankPoolInstaller, SceneBankPoolInstaller, SoundBankPoolInstaller};
use prometeu_hal::AssetBridge; use prometeu_hal::AssetBridge;
use prometeu_hal::asset::{ use prometeu_hal::asset::{
@@ -14,7 +15,7 @@ use prometeu_hal::cartridge::AssetsPayloadSource;
use prometeu_hal::color::Color; use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph; use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{GlyphBank, TileSize}; use prometeu_hal::glyph_bank::{GlyphBank, TileSize};
use prometeu_hal::sample::Sample; use prometeu_hal::music_bank::MusicBank;
use prometeu_hal::scene_bank::SceneBank; use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer}; use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::sound_bank::SoundBank; use prometeu_hal::sound_bank::SoundBank;
@@ -61,6 +62,7 @@ pub struct AssetPipelineTelemetry {
pub active_progress: u16, pub active_progress: u16,
pub glyph_latency: AssetLatencyPercentiles, pub glyph_latency: AssetLatencyPercentiles,
pub sound_latency: AssetLatencyPercentiles, pub sound_latency: AssetLatencyPercentiles,
pub music_latency: AssetLatencyPercentiles,
pub scene_latency: AssetLatencyPercentiles, pub scene_latency: AssetLatencyPercentiles,
pub last_asset_id: Option<AssetId>, pub last_asset_id: Option<AssetId>,
pub last_asset_latency: AssetLatencyPercentiles, pub last_asset_latency: AssetLatencyPercentiles,
@@ -130,6 +132,7 @@ impl AssetPipelineTelemetryState {
); );
self.snapshot.glyph_latency = percentile_snapshot(self.bank_samples.get(&BankType::GLYPH)); self.snapshot.glyph_latency = percentile_snapshot(self.bank_samples.get(&BankType::GLYPH));
self.snapshot.sound_latency = percentile_snapshot(self.bank_samples.get(&BankType::SOUNDS)); self.snapshot.sound_latency = percentile_snapshot(self.bank_samples.get(&BankType::SOUNDS));
self.snapshot.music_latency = percentile_snapshot(self.bank_samples.get(&BankType::MUSIC));
self.snapshot.scene_latency = percentile_snapshot(self.bank_samples.get(&BankType::SCENE)); self.snapshot.scene_latency = percentile_snapshot(self.bank_samples.get(&BankType::SCENE));
self.snapshot.last_asset_id = Some(asset_id); self.snapshot.last_asset_id = Some(asset_id);
self.snapshot.last_asset_latency = percentile_snapshot(self.asset_samples.get(&asset_id)); self.snapshot.last_asset_latency = percentile_snapshot(self.asset_samples.get(&asset_id));
@@ -329,12 +332,14 @@ pub struct AssetManager {
gfx_slots: Arc<RwLock<[Option<AssetId>; 16]>>, gfx_slots: Arc<RwLock<[Option<AssetId>; 16]>>,
glyph_slot_index: GlyphAssetSlotIndex, glyph_slot_index: GlyphAssetSlotIndex,
sound_slots: Arc<RwLock<[Option<AssetId>; 16]>>, sound_slots: Arc<RwLock<[Option<AssetId>; 16]>>,
music_slots: Arc<RwLock<[Option<AssetId>; 16]>>,
scene_slots: Arc<RwLock<[Option<AssetId>; 16]>>, scene_slots: Arc<RwLock<[Option<AssetId>; 16]>>,
/// Residency policy for GFX glyph banks. /// Residency policy for GFX glyph banks.
gfx_policy: BankPolicy<GlyphBank>, gfx_policy: BankPolicy<GlyphBank>,
/// Residency policy for sound banks. /// Residency policy for sound banks.
sound_policy: BankPolicy<SoundBank>, sound_policy: BankPolicy<SoundBank>,
music_policy: BankPolicy<MusicBank>,
/// Residency policy for scene banks. /// Residency policy for scene banks.
scene_policy: BankPolicy<SceneBank>, scene_policy: BankPolicy<SceneBank>,
@@ -370,6 +375,7 @@ struct AssetLoadJobResources<'a> {
pipeline_telemetry: &'a Arc<Mutex<AssetPipelineTelemetryState>>, pipeline_telemetry: &'a Arc<Mutex<AssetPipelineTelemetryState>>,
gfx_policy: &'a BankPolicy<GlyphBank>, gfx_policy: &'a BankPolicy<GlyphBank>,
sound_policy: &'a BankPolicy<SoundBank>, sound_policy: &'a BankPolicy<SoundBank>,
music_policy: &'a BankPolicy<MusicBank>,
scene_policy: &'a BankPolicy<SceneBank>, scene_policy: &'a BankPolicy<SceneBank>,
} }
@@ -479,6 +485,7 @@ struct AssetLoadWorker {
} }
impl AssetLoadWorker { impl AssetLoadWorker {
#[allow(clippy::too_many_arguments)]
fn new( fn new(
handles: Arc<RwLock<HandleTable>>, handles: Arc<RwLock<HandleTable>>,
target_generations: Arc<RwLock<TargetGenerationTable>>, target_generations: Arc<RwLock<TargetGenerationTable>>,
@@ -486,6 +493,7 @@ impl AssetLoadWorker {
pipeline_telemetry: Arc<Mutex<AssetPipelineTelemetryState>>, pipeline_telemetry: Arc<Mutex<AssetPipelineTelemetryState>>,
gfx_policy: BankPolicy<GlyphBank>, gfx_policy: BankPolicy<GlyphBank>,
sound_policy: BankPolicy<SoundBank>, sound_policy: BankPolicy<SoundBank>,
music_policy: BankPolicy<MusicBank>,
scene_policy: BankPolicy<SceneBank>, scene_policy: BankPolicy<SceneBank>,
) -> Self { ) -> Self {
let queue = Arc::new(AssetLoadQueue::default()); let queue = Arc::new(AssetLoadQueue::default());
@@ -498,6 +506,7 @@ impl AssetLoadWorker {
pipeline_telemetry: &pipeline_telemetry, pipeline_telemetry: &pipeline_telemetry,
gfx_policy: &gfx_policy, gfx_policy: &gfx_policy,
sound_policy: &sound_policy, sound_policy: &sound_policy,
music_policy: &music_policy,
scene_policy: &scene_policy, scene_policy: &scene_policy,
}; };
while let Some(job) = worker_queue.next_job() { while let Some(job) = worker_queue.next_job() {
@@ -554,6 +563,9 @@ enum AssetOpMode {
} }
impl AssetBridge for AssetManager { impl AssetBridge for AssetManager {
fn unload_audio(&self, music: bool, slot: usize) -> AssetOpStatus {
self.unload_audio(music, slot)
}
fn bind_background_work( fn bind_background_work(
&mut self, &mut self,
lane: Arc<dyn prometeu_hal::background_work::BackgroundWork>, lane: Arc<dyn prometeu_hal::background_work::BackgroundWork>,
@@ -647,7 +659,9 @@ impl AssetManager {
fn op_mode_for(entry: &AssetEntry) -> Result<AssetOpMode, String> { fn op_mode_for(entry: &AssetEntry) -> Result<AssetOpMode, String> {
match (entry.bank_type, entry.codec) { match (entry.bank_type, entry.codec) {
(BankType::GLYPH, AssetCodec::None) => Ok(AssetOpMode::StageInMemory), (BankType::GLYPH, AssetCodec::None) => Ok(AssetOpMode::StageInMemory),
(BankType::SOUNDS, AssetCodec::None) => Ok(AssetOpMode::DirectFromSlice), (BankType::SOUNDS, AssetCodec::None) | (BankType::MUSIC, AssetCodec::None) => {
Ok(AssetOpMode::DirectFromSlice)
}
(BankType::SCENE, AssetCodec::None) => Ok(AssetOpMode::DirectFromSlice), (BankType::SCENE, AssetCodec::None) => Ok(AssetOpMode::DirectFromSlice),
} }
} }
@@ -670,6 +684,7 @@ impl AssetManager {
let pipeline_telemetry = Arc::new(Mutex::new(AssetPipelineTelemetryState::default())); let pipeline_telemetry = Arc::new(Mutex::new(AssetPipelineTelemetryState::default()));
let gfx_policy = BankPolicy::new(); let gfx_policy = BankPolicy::new();
let sound_policy = BankPolicy::new(); let sound_policy = BankPolicy::new();
let music_policy = BankPolicy::new();
let scene_policy = BankPolicy::new(); let scene_policy = BankPolicy::new();
let load_worker = AssetLoadWorker::new( let load_worker = AssetLoadWorker::new(
Arc::clone(&handles), Arc::clone(&handles),
@@ -678,6 +693,7 @@ impl AssetManager {
Arc::clone(&pipeline_telemetry), Arc::clone(&pipeline_telemetry),
gfx_policy.clone(), gfx_policy.clone(),
sound_policy.clone(), sound_policy.clone(),
music_policy.clone(),
scene_policy.clone(), scene_policy.clone(),
); );
@@ -689,9 +705,11 @@ impl AssetManager {
gfx_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), gfx_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
glyph_slot_index: GlyphAssetSlotIndex::new(), glyph_slot_index: GlyphAssetSlotIndex::new(),
sound_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), sound_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
music_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
scene_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))), scene_slots: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
gfx_policy, gfx_policy,
sound_policy, sound_policy,
music_policy,
scene_policy, scene_policy,
handles, handles,
target_handles: Arc::new(RwLock::new(HashMap::new())), target_handles: Arc::new(RwLock::new(HashMap::new())),
@@ -776,6 +794,23 @@ impl AssetManager {
} }
} }
} }
BankType::MUSIC => {
if let Ok(bank) =
Self::perform_load_music_bank(&entry, self.assets_data.clone())
{
let bank_arc = Arc::new(bank);
self.music_policy.put_resident(
entry.asset_id,
Arc::clone(&bank_arc),
entry.decoded_size as usize,
);
self.sound_installer.install_music_bank(slot_index, bank_arc);
let mut slots = self.music_slots.write().unwrap();
if slot_index < slots.len() {
slots[slot_index] = Some(entry.asset_id);
}
}
}
BankType::SCENE => { BankType::SCENE => {
if let Ok(bank) = if let Ok(bank) =
Self::perform_load_scene_bank(&entry, self.assets_data.clone()) Self::perform_load_scene_bank(&entry, self.assets_data.clone())
@@ -840,6 +875,7 @@ impl AssetManager {
fn clear_staging_for_handle(&self, handle_id: HandleId) { fn clear_staging_for_handle(&self, handle_id: HandleId) {
self.gfx_policy.take_staging(handle_id); self.gfx_policy.take_staging(handle_id);
self.sound_policy.take_staging(handle_id); self.sound_policy.take_staging(handle_id);
self.music_policy.take_staging(handle_id);
self.scene_policy.take_staging(handle_id); self.scene_policy.take_staging(handle_id);
} }
@@ -855,6 +891,7 @@ impl AssetManager {
match slot.asset_type { match slot.asset_type {
BankType::GLYPH => self.gfx_slots.read().unwrap().get(slot.index).and_then(|s| *s), BankType::GLYPH => self.gfx_slots.read().unwrap().get(slot.index).and_then(|s| *s),
BankType::SOUNDS => self.sound_slots.read().unwrap().get(slot.index).and_then(|s| *s), BankType::SOUNDS => self.sound_slots.read().unwrap().get(slot.index).and_then(|s| *s),
BankType::MUSIC => self.music_slots.read().unwrap().get(slot.index).and_then(|s| *s),
BankType::SCENE => self.scene_slots.read().unwrap().get(slot.index).and_then(|s| *s), BankType::SCENE => self.scene_slots.read().unwrap().get(slot.index).and_then(|s| *s),
} }
} }
@@ -874,6 +911,7 @@ impl AssetManager {
let slot = match entry.bank_type { let slot = match entry.bank_type {
BankType::GLYPH => SlotRef::gfx(slot_index), BankType::GLYPH => SlotRef::gfx(slot_index),
BankType::SOUNDS => SlotRef::audio(slot_index), BankType::SOUNDS => SlotRef::audio(slot_index),
BankType::MUSIC => SlotRef::music(slot_index),
BankType::SCENE => SlotRef::scene(slot_index), BankType::SCENE => SlotRef::scene(slot_index),
}; };
@@ -899,6 +937,14 @@ impl AssetManager {
false false
} }
} }
BankType::MUSIC => {
if let Some(bank) = self.music_policy.get_resident(asset_id) {
self.music_policy.stage(handle_id, bank, entry.decoded_size as usize);
true
} else {
false
}
}
BankType::SCENE => { BankType::SCENE => {
if let Some(bank) = self.scene_policy.get_resident(asset_id) { if let Some(bank) = self.scene_policy.get_resident(asset_id) {
self.scene_policy.stage(handle_id, bank, entry.decoded_size as usize); self.scene_policy.stage(handle_id, bank, entry.decoded_size as usize);
@@ -1081,6 +1127,57 @@ impl AssetManager {
} }
} }
} }
BankType::MUSIC => {
let result =
Self::perform_load_music_bank(&job.entry, Arc::clone(resources.assets_data));
match result {
Ok(musicbank) => {
if !Self::is_current_target_generation(
resources.target_generations,
job.slot,
job.request_generation,
) {
resources.pipeline_telemetry.lock().unwrap().record_stale_discard();
return;
}
let bank_arc = Arc::new(musicbank);
let resident_arc = resources.music_policy.put_resident(
job.asset_id,
bank_arc,
job.entry.decoded_size as usize,
);
if !Self::is_current_target_generation(
resources.target_generations,
job.slot,
job.request_generation,
) {
resources.pipeline_telemetry.lock().unwrap().record_stale_discard();
return;
}
resources.music_policy.stage(
job.handle_id,
resident_arc,
job.entry.decoded_size as usize,
);
Self::complete_load_job(resources.handles, &job, LoadStatus::READY);
Self::record_load_job_finished(
resources.pipeline_telemetry,
&job,
started_at,
LoadStatus::READY,
);
}
Err(_) => {
Self::complete_load_job(resources.handles, &job, LoadStatus::ERROR);
Self::record_load_job_finished(
resources.pipeline_telemetry,
&job,
started_at,
LoadStatus::ERROR,
);
}
}
}
BankType::SCENE => { BankType::SCENE => {
let result = let result =
Self::perform_load_scene_bank(&job.entry, Arc::clone(resources.assets_data)); Self::perform_load_scene_bank(&job.entry, Arc::clone(resources.assets_data));
@@ -1268,6 +1365,32 @@ impl AssetManager {
} }
} }
fn perform_load_music_bank(
entry: &AssetEntry,
assets_data: Arc<RwLock<AssetsPayloadSource>>,
) -> Result<MusicBank, String> {
let op_mode = Self::op_mode_for(entry)?;
let slice = {
let assets_data = assets_data.read().unwrap();
assets_data
.open_slice(entry.offset, entry.size)
.map_err(|_| "Asset offset/size out of bounds".to_string())?
};
match op_mode {
AssetOpMode::DirectFromSlice => {
let mut reader =
slice.open_reader().map_err(|_| "Asset payload read failed".to_string())?;
Self::decode_music_bank_from_reader(entry, &mut reader)
}
AssetOpMode::StageInMemory => {
let buffer =
slice.read_all().map_err(|_| "Asset payload read failed".to_string())?;
Self::decode_music_bank_from_buffer(entry, &buffer)
}
}
}
fn perform_load_scene_bank( fn perform_load_scene_bank(
entry: &AssetEntry, entry: &AssetEntry,
assets_data: Arc<RwLock<AssetsPayloadSource>>, assets_data: Arc<RwLock<AssetsPayloadSource>>,
@@ -1334,13 +1457,32 @@ impl AssetManager {
entry: &AssetEntry, entry: &AssetEntry,
buffer: &[u8], buffer: &[u8],
) -> Result<SoundBank, String> { ) -> Result<SoundBank, String> {
let sample_rate = decode::sound_rate(entry)?;
decode::payload_size(entry, buffer.len())?; decode::payload_size(entry, buffer.len())?;
let mut data = Vec::with_capacity(buffer.len() / 2); let bank = decode_audio_bank(buffer, false)?;
decode::append_pcm(&mut data, buffer); if bank.decoded_size() as u64 != entry.decoded_size {
return Err("audio decoded_size mismatch".into());
}
if let DecodedAudioBank::Sound(bank) = bank {
Ok(bank)
} else {
Err("audio bank type mismatch".into())
}
}
let sample = Arc::new(Sample::new(sample_rate, data)); fn decode_music_bank_from_buffer(
Ok(SoundBank::new(vec![sample])) entry: &AssetEntry,
buffer: &[u8],
) -> Result<MusicBank, String> {
decode::payload_size(entry, buffer.len())?;
let bank = decode_audio_bank(buffer, true)?;
if bank.decoded_size() as u64 != entry.decoded_size {
return Err("audio decoded_size mismatch".into());
}
if let DecodedAudioBank::Music(bank) = bank {
Ok(bank)
} else {
Err("audio bank type mismatch".into())
}
} }
fn decode_sound_bank_from_reader( fn decode_sound_bank_from_reader(
@@ -1352,6 +1494,15 @@ impl AssetManager {
Self::decode_sound_bank_from_buffer(entry, &raw) Self::decode_sound_bank_from_buffer(entry, &raw)
} }
fn decode_music_bank_from_reader(
entry: &AssetEntry,
reader: &mut impl Read,
) -> Result<MusicBank, String> {
let mut raw = Vec::new();
reader.read_to_end(&mut raw).map_err(|_| "Asset payload read failed".to_string())?;
Self::decode_music_bank_from_buffer(entry, &raw)
}
pub fn status(&self, handle: HandleId) -> LoadStatus { pub fn status(&self, handle: HandleId) -> LoadStatus {
if let Some(status) = self.handles.read().unwrap().get(&handle).map(|h| h.status) { if let Some(status) = self.handles.read().unwrap().get(&handle).map(|h| h.status) {
return status; return status;
@@ -1480,6 +1631,7 @@ impl AssetManager {
let slot_ref = match bank_type { let slot_ref = match bank_type {
BankType::GLYPH => SlotRef::gfx(slot), BankType::GLYPH => SlotRef::gfx(slot),
BankType::SOUNDS => SlotRef::audio(slot), BankType::SOUNDS => SlotRef::audio(slot),
BankType::MUSIC => SlotRef::music(slot),
BankType::SCENE => SlotRef::scene(slot), BankType::SCENE => SlotRef::scene(slot),
}; };
let handle = self.handle_for_slot(slot_ref); let handle = self.handle_for_slot(slot_ref);
@@ -1595,6 +1747,16 @@ impl AssetManager {
h.status = LoadStatus::COMMITTED; h.status = LoadStatus::COMMITTED;
} }
} }
BankType::MUSIC => {
if let Some((bank, _)) = self.music_policy.take_staging(handle_id) {
self.sound_installer.install_music_bank(h.slot.index, bank);
let mut slots = self.music_slots.write().unwrap();
if h.slot.index < slots.len() {
slots[h.slot.index] = Some(h._asset_id);
}
h.status = LoadStatus::COMMITTED;
}
}
BankType::SCENE => { BankType::SCENE => {
if let Some((bank, _)) = self.scene_policy.take_staging(handle_id) { if let Some((bank, _)) = self.scene_policy.take_staging(handle_id) {
self.scene_installer.install_scene_bank(h.slot.index, bank); self.scene_installer.install_scene_bank(h.slot.index, bank);
@@ -1609,12 +1771,57 @@ impl AssetManager {
} }
} }
} }
self.reap_audio_cache();
}
fn reap_audio_cache(&self) {
fn reap<T>(policy: &BankPolicy<T>, slots: &[Option<AssetId>; 16]) {
let mut resident = policy.resident.write().unwrap();
resident.retain(|id, entry| {
let keep = slots.contains(&Some(*id)) || Arc::strong_count(&entry.value) > 1;
if !keep {
policy.used_bytes.fetch_sub(entry.bytes, Ordering::Relaxed);
}
keep
});
}
reap(&self.sound_policy, &self.sound_slots.read().unwrap());
reap(&self.music_policy, &self.music_slots.read().unwrap());
}
pub fn unload_audio(&self, music: bool, slot: usize) -> AssetOpStatus {
if slot >= 16 {
return AssetOpStatus::InvalidState;
}
let target = if music { SlotRef::music(slot) } else { SlotRef::audio(slot) };
self.bump_target_generation(target);
if let Some(handle) = self.target_handles.read().unwrap().get(&target).copied() {
self.clear_staging_for_handle(handle);
if let Some(h) = self.handles.write().unwrap().get_mut(&handle) {
h.status = LoadStatus::CANCELED;
}
}
let slots = if music { &self.music_slots } else { &self.sound_slots };
let mut ids = slots.write().unwrap();
let previous = ids[slot].take();
self.sound_installer.unload_audio_bank(music, slot);
if let Some(id) = previous.filter(|id| !ids.contains(&Some(*id))) {
if music {
if let Some(old) = self.music_policy.resident.write().unwrap().remove(&id) {
self.music_policy.used_bytes.fetch_sub(old.bytes, Ordering::Relaxed);
}
} else if let Some(old) = self.sound_policy.resident.write().unwrap().remove(&id) {
self.sound_policy.used_bytes.fetch_sub(old.bytes, Ordering::Relaxed);
}
}
AssetOpStatus::Ok
} }
pub fn bank_telemetry(&self) -> Vec<BankTelemetry> { pub fn bank_telemetry(&self) -> Vec<BankTelemetry> {
vec![ vec![
self.bank_telemetry_for(BankType::GLYPH), self.bank_telemetry_for(BankType::GLYPH),
self.bank_telemetry_for(BankType::SOUNDS), self.bank_telemetry_for(BankType::SOUNDS),
self.bank_telemetry_for(BankType::MUSIC),
self.bank_telemetry_for(BankType::SCENE), self.bank_telemetry_for(BankType::SCENE),
] ]
} }
@@ -1627,6 +1834,9 @@ impl AssetManager {
BankType::SOUNDS => { BankType::SOUNDS => {
self.sound_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count() self.sound_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count()
} }
BankType::MUSIC => {
self.music_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count()
}
BankType::SCENE => { BankType::SCENE => {
self.scene_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count() self.scene_slots.read().unwrap().iter().filter(|slot| slot.is_some()).count()
} }
@@ -1679,6 +1889,27 @@ impl AssetManager {
SlotStats { asset_id, asset_name, generation: 0, resident_bytes: bytes } SlotStats { asset_id, asset_name, generation: 0, resident_bytes: bytes }
} }
BankType::MUSIC => {
let slots = self.music_slots.read().unwrap();
let asset_id = slots.get(slot.index).and_then(|s| *s);
let (bytes, asset_name) = if let Some(id) = &asset_id {
let bytes = self
.music_policy
.resident
.read()
.unwrap()
.get(id)
.map(|entry| entry.bytes)
.unwrap_or(0);
let name = self.assets.read().unwrap().get(id).map(|e| e.asset_name.clone());
(bytes, name)
} else {
(0, None)
};
SlotStats { asset_id, asset_name, generation: 0, resident_bytes: bytes }
}
BankType::SCENE => { BankType::SCENE => {
let slots = self.scene_slots.read().unwrap(); let slots = self.scene_slots.read().unwrap();
let asset_id = slots.get(slot.index).and_then(|s| *s); let asset_id = slots.get(slot.index).and_then(|s| *s);
@@ -1711,6 +1942,7 @@ impl AssetManager {
} }
self.gfx_policy.clear(); self.gfx_policy.clear();
self.sound_policy.clear(); self.sound_policy.clear();
self.music_policy.clear();
self.scene_policy.clear(); self.scene_policy.clear();
self.handles.write().unwrap().clear(); self.handles.write().unwrap().clear();
self.target_handles.write().unwrap().clear(); self.target_handles.write().unwrap().clear();
@@ -1721,9 +1953,11 @@ impl AssetManager {
self.gfx_slots.write().unwrap().fill(None); self.gfx_slots.write().unwrap().fill(None);
self.glyph_slot_index.clear(); self.glyph_slot_index.clear();
self.sound_slots.write().unwrap().fill(None); self.sound_slots.write().unwrap().fill(None);
self.music_slots.write().unwrap().fill(None);
self.scene_slots.write().unwrap().fill(None); self.scene_slots.write().unwrap().fill(None);
self.gfx_installer.clear_glyph_banks(); self.gfx_installer.clear_glyph_banks();
self.sound_installer.clear_sound_banks(); self.sound_installer.clear_sound_banks();
self.sound_installer.clear_music_banks();
self.scene_installer.clear_scene_banks(); self.scene_installer.clear_scene_banks();
} }
@@ -2512,7 +2746,7 @@ mod tests {
let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>; let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>;
// 100 samples of 16-bit PCM (zeros) // 100 samples of 16-bit PCM (zeros)
let data = vec![0u8; 200]; let data = crate::bank_format::test_pcm_bank(&[0u8; 200], 44100);
let asset_entry = AssetEntry { let asset_entry = AssetEntry {
asset_id: 1, asset_id: 1,
@@ -2558,7 +2792,7 @@ mod tests {
let sound_installer = Arc::clone(&banks) as Arc<dyn SoundBankPoolInstaller>; let sound_installer = Arc::clone(&banks) as Arc<dyn SoundBankPoolInstaller>;
let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>; let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>;
let data = vec![0u8; 200]; let data = crate::bank_format::test_pcm_bank(&[0u8; 200], 44100);
let asset_entry = AssetEntry { let asset_entry = AssetEntry {
asset_id: 2, asset_id: 2,
@@ -69,13 +69,6 @@ pub(super) fn write_palettes(
palettes[at / 16][at % 16] = Color::rgba(rgba[0], rgba[1], rgba[2], rgba[3]); 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> { pub(super) fn payload_size(entry: &AssetEntry, actual: usize) -> Result<(), String> {
if actual as u64 != entry.size { if actual as u64 != entry.size {
return Err("Invalid asset payload size".into()); return Err("Invalid asset payload size".into());
@@ -32,47 +32,33 @@ fn pcm_entry(size: u64) -> AssetEntry {
} }
#[test] #[test]
fn pcm_chunk_edges_and_odd_tails_have_explicit_baseline_outputs() { fn pcm_chunk_edges_validate_all_declared_frames_and_reject_odd_tails() {
for len in [0, 1, 2, 3, 4095, 4096, 4097, 8191, 8192, 8193] { 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 raw: Vec<u8> = (0..len).map(|i| if i % 2 == 0 { 0x34 } else { 0x12 }).collect();
let entry = pcm_entry(len as u64); let bytes = crate::bank_format::test_pcm_bank(&raw, 44100);
let expected = json!([[vec![0x1234_i16; len / 2], 44100, null, null]]); let expected = if len % 2 == 0 {
let buffer = AssetManager::decode_sound_bank_from_buffer(&entry, &bytes).unwrap(); Some(json!([[vec![0x1234_i16; len / 2], 44100, null, null]]))
let reader = AssetManager::decode_sound_bank_from_reader(&entry, &mut &bytes[..]).unwrap(); } else {
let source = Arc::new(RwLock::new(AssetsPayloadSource::from_bytes(bytes))); None
let production = AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap(); };
assert_eq!(sound_snapshot(&buffer), expected, "buffer len={len}"); check_case("pcm-chunk", &pcm_entry(bytes.len() as u64), bytes, expected);
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] #[test]
fn physically_truncated_pcm_file_is_rejected_by_both_modes() { fn physically_truncated_pcm_file_is_rejected_by_all_modes() {
// Two actual bytes, three declared bytes: the missing byte is an odd tail. let bytes = crate::bank_format::test_pcm_bank(&[0x34, 0x12], 44100);
// The approved rule rejects missing declared bytes, including an odd tail. let entry = pcm_entry(bytes.len() as u64);
let fixture = FileFixture::new("truncated-pcm", &[0x34, 0x12]); let fixture = FileFixture::new("truncated-pcm", &bytes[..bytes.len() - 1]);
let entry = pcm_entry(3); let source = fixture.source(bytes.len() as u64);
let source = fixture.source(3);
assert!(AssetManager::perform_load_sound_bank(&entry, source.clone()).is_err()); assert!(AssetManager::perform_load_sound_bank(&entry, source.clone()).is_err());
assert!(resumable::conformance_result(&entry, &source).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, &bytes).unwrap();
std::fs::write(&fixture.0, [0x34, 0x12, 0xff]).unwrap();
let expected = json!([[[0x1234], 44100, null, null]]); let expected = json!([[[0x1234], 44100, null, null]]);
assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected); assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected);
assert_eq!( assert_eq!(
sound_snapshot(&AssetManager::perform_load_sound_bank(&entry, source.clone()).unwrap()), sound_snapshot(&AssetManager::perform_load_sound_bank(&entry, source).unwrap()),
expected 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] #[test]
@@ -129,6 +115,8 @@ fn check_case(name: &str, entry: &AssetEntry, bytes: Vec<u8>, expected: Option<V
AssetManager::perform_load_sound_bank(entry, source.clone()) AssetManager::perform_load_sound_bank(entry, source.clone())
.map(|b| sound_snapshot(&b)) .map(|b| sound_snapshot(&b))
} }
BankType::MUSIC => AssetManager::perform_load_music_bank(entry, source.clone())
.map(|b| music_snapshot(&b)),
BankType::SCENE => AssetManager::perform_load_scene_bank(entry, source.clone()) BankType::SCENE => AssetManager::perform_load_scene_bank(entry, source.clone())
.map(|b| scene_snapshot(&b)), .map(|b| scene_snapshot(&b)),
}; };
@@ -153,6 +141,8 @@ fn check_case(name: &str, entry: &AssetEntry, bytes: Vec<u8>, expected: Option<V
AssetManager::decode_sound_bank_from_reader(entry, &mut reader) AssetManager::decode_sound_bank_from_reader(entry, &mut reader)
.map(|b| sound_snapshot(&b)) .map(|b| sound_snapshot(&b))
} }
(BankType::MUSIC, _) => AssetManager::decode_music_bank_from_buffer(entry, &bytes)
.map(|b| music_snapshot(&b)),
(BankType::SCENE, 0) => AssetManager::decode_scene_bank_from_buffer(entry, &bytes) (BankType::SCENE, 0) => AssetManager::decode_scene_bank_from_buffer(entry, &bytes)
.map(|b| scene_snapshot(&b)), .map(|b| scene_snapshot(&b)),
(BankType::SCENE, _) => { (BankType::SCENE, _) => {
@@ -319,35 +309,29 @@ fn scene_tile_chunk_edges_flags_and_reserved_bytes() {
} }
#[test] #[test]
fn pcm_metadata_and_source_range_corpus() { fn pcm_descriptor_and_source_range_corpus() {
for metadata in [ let bytes = crate::bank_format::test_pcm_bank(&[0x34, 0x12], 44100);
json!(null), let entry = pcm_entry(bytes.len() as u64);
json!({}), // Audio metadata lives in the versioned payload, so it can vary per sample.
json!({"sample_rate":-1,"channels":1}), for (offset, value) in
json!({"sample_rate":44100,"channels":"bad"}), [(48, 99u32), (49, 0), (52, 0), (56, 2), (60, 1), (68, 0), (72, 3), (84, 0)]
] { {
let mut e = pcm_entry(2); let mut invalid = bytes.clone();
e.metadata = metadata; if offset == 48 || offset == 49 {
check_case("pcm-metadata", &e, vec![0x34, 0x12], None); invalid[offset] = value as u8;
} else {
invalid[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
}
check_case("descriptor", &entry, invalid, 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] { for offset in [1, u64::MAX] {
let mut e = pcm_entry(2); let mut invalid = entry.clone();
e.offset = offset; invalid.offset = offset;
check_case("source-range", &e, vec![0x34, 0x12], None); check_case("source-range", &invalid, bytes.clone(), None);
} }
let mut e = pcm_entry(2); let mut invalid = entry;
e.size = u64::MAX; invalid.decoded_size += 1;
check_case("source-size-overflow", &e, vec![0x34, 0x12], None); check_case("decoded-size", &invalid, bytes, None);
} }
pub(in crate::asset) fn glyph_snapshot(bank: &GlyphBank) -> Value { pub(in crate::asset) fn glyph_snapshot(bank: &GlyphBank) -> Value {
@@ -430,3 +414,48 @@ fn physically_truncated_glyph_palette_is_rejected_by_both_modes() {
); );
assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected); assert_eq!(resumable::conformance_result(&entry, &source).unwrap(), expected);
} }
pub(in crate::asset) fn music_snapshot(bank: &prometeu_hal::music_bank::MusicBank) -> Value {
json!({"name": bank.name, "events": bank.events.len(), "pcm": bank.metrics.pcm_bytes})
}
#[test]
fn mixed_audio_fixtures_conform_across_all_asset_decode_modes() {
for (music, bytes) in [
(
false,
&include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-sound.sbnk"
))[..],
),
(
true,
&include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-music.mbnk"
))[..],
),
] {
let decoded = crate::bank_format::decode_audio_bank(bytes, music).unwrap();
let size = decoded.decoded_size();
let expected = match decoded {
DecodedAudioBank::Sound(b) => sound_snapshot(&b),
DecodedAudioBank::Music(b) => music_snapshot(&b),
};
let entry = AssetEntry {
asset_id: 7,
asset_name: "mixed".into(),
bank_type: if music { BankType::MUSIC } else { BankType::SOUNDS },
offset: 0,
size: bytes.len() as u64,
decoded_size: size as u64,
codec: AssetCodec::None,
metadata: json!({"version":1}),
};
check_case("mixed-audio", &entry, bytes.to_vec(), Some(expected));
let mut invalid = bytes.to_vec();
invalid[0] = 0;
check_case("mixed-bad-magic", &entry, invalid, None);
}
}
@@ -11,6 +11,7 @@ pub(super) struct Resources {
telemetry: Arc<Mutex<AssetPipelineTelemetryState>>, telemetry: Arc<Mutex<AssetPipelineTelemetryState>>,
gfx: BankPolicy<GlyphBank>, gfx: BankPolicy<GlyphBank>,
sound: BankPolicy<SoundBank>, sound: BankPolicy<SoundBank>,
music: BankPolicy<MusicBank>,
scene: BankPolicy<SceneBank>, scene: BankPolicy<SceneBank>,
} }
impl Resources { impl Resources {
@@ -22,6 +23,7 @@ impl Resources {
telemetry: m.pipeline_telemetry.clone(), telemetry: m.pipeline_telemetry.clone(),
gfx: m.gfx_policy.clone(), gfx: m.gfx_policy.clone(),
sound: m.sound_policy.clone(), sound: m.sound_policy.clone(),
music: m.music_policy.clone(),
scene: m.scene_policy.clone(), scene: m.scene_policy.clone(),
} }
} }
@@ -142,6 +144,18 @@ pub(super) fn schedule(
job.entry.decoded_size as usize, job.entry.decoded_size as usize,
); );
} }
Decoded::Music(bank) => {
let resident = resources.music.put_resident(
job.asset_id,
Arc::new(bank),
job.entry.decoded_size as usize,
);
resources.music.stage(
job.handle_id,
resident,
job.entry.decoded_size as usize,
);
}
Decoded::Scene(bank) => { Decoded::Scene(bank) => {
let resident = resources.scene.put_resident( let resident = resources.scene.put_resident(
job.asset_id, job.asset_id,
@@ -188,6 +202,7 @@ pub(super) fn schedule(
enum Decoded { enum Decoded {
Glyph(GlyphBank), Glyph(GlyphBank),
Sound(SoundBank), Sound(SoundBank),
Music(MusicBank),
Scene(SceneBank), Scene(SceneBank),
} }
enum State { enum State {
@@ -199,10 +214,11 @@ enum State {
palette_position: usize, palette_position: usize,
}, },
Sound { Sound {
sample_rate: u32, raw: Vec<u8>,
data: Vec<i16>,
remaining: usize, remaining: usize,
music: bool,
}, },
Audio(Box<crate::bank_format::AudioBankMaterializer<'static>>),
Scene { Scene {
layers: [SceneLayer; SCENE_LAYER_COUNT_V1], layers: [SceneLayer; SCENE_LAYER_COUNT_V1],
layer: usize, layer: usize,
@@ -245,12 +261,16 @@ impl Decoder {
palette_position: 0, palette_position: 0,
} }
} }
BankType::SOUNDS => { BankType::SOUNDS | BankType::MUSIC => {
let sample_rate = decode::sound_rate(entry)?; let mut raw = Vec::new();
raw.try_reserve_exact(
usize::try_from(entry.size).map_err(|_| "audio size overflow")?,
)
.map_err(|_| "audio allocation failed")?;
State::Sound { State::Sound {
sample_rate, raw,
data: Vec::with_capacity(entry.size as usize / 2),
remaining: entry.size as usize, remaining: entry.size as usize,
music: entry.bank_type == BankType::MUSIC,
} }
} }
BankType::SCENE => { BankType::SCENE => {
@@ -294,18 +314,34 @@ impl Decoder {
}; };
Ok(Some(Decoded::Glyph(bank))) Ok(Some(Decoded::Glyph(bank)))
} }
State::Sound { sample_rate, data, remaining } => { State::Sound { raw, remaining, music } => {
if *remaining > 0 { if *remaining > 0 {
let n = (*remaining).min(bytes.len()); let n = (*remaining).min(4096);
self.reader.read_exact(&mut bytes[..n]).map_err(|e| e.to_string())?; let mut buffer = [0; 4096];
decode::append_pcm(data, &bytes[..n]); self.reader.read_exact(&mut buffer[..n]).map_err(|e| e.to_string())?;
raw.extend_from_slice(&buffer[..n]);
*remaining -= n; *remaining -= n;
return Ok(None); return Ok(None);
} }
let rate = *sample_rate; let decoder = crate::bank_format::AudioBankMaterializer::new(
let data = std::mem::take(data); std::borrow::Cow::Owned(std::mem::take(raw)),
*music,
)?;
self.state = State::Audio(Box::new(decoder));
Ok(None)
}
State::Audio(decoder) => {
let Some(bank) = decoder.step()? else {
return Ok(None);
};
if bank.decoded_size() as u64 != self.entry.decoded_size {
return Err("audio decoded_size mismatch".into());
}
self.state = State::Done; self.state = State::Done;
Ok(Some(Decoded::Sound(SoundBank::new(vec![Arc::new(Sample::new(rate, data))])))) Ok(Some(match bank {
DecodedAudioBank::Sound(b) => Decoded::Sound(b),
DecodedAudioBank::Music(b) => Decoded::Music(b),
}))
} }
State::Scene { layers, layer, tiles_left, header, decoded } => { State::Scene { layers, layer, tiles_left, header, decoded } => {
if !*header { if !*header {
@@ -372,6 +408,7 @@ pub(super) fn conformance_result(
Decoded::Glyph(bank) => super::decode::tests::glyph_snapshot(&bank), Decoded::Glyph(bank) => super::decode::tests::glyph_snapshot(&bank),
Decoded::Sound(bank) => super::decode::tests::sound_snapshot(&bank), Decoded::Sound(bank) => super::decode::tests::sound_snapshot(&bank),
Decoded::Scene(bank) => super::decode::tests::scene_snapshot(&bank), Decoded::Scene(bank) => super::decode::tests::scene_snapshot(&bank),
Decoded::Music(bank) => super::decode::tests::music_snapshot(&bank),
}); });
} }
} }
@@ -448,9 +485,12 @@ mod tests {
panic!("decoder did not finish") panic!("decoder did not finish")
} }
#[test] #[test]
fn resumable_sound_and_scene_preserve_existing_formats() { fn resumable_audio_bank_and_scene_use_canonical_formats() {
let pcm: Vec<i16> = (0..5000).map(|n| n as i16 - 2500).collect(); 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 bytes = crate::bank_format::test_pcm_bank(
&pcm.iter().flat_map(|n| n.to_le_bytes()).collect::<Vec<_>>(),
44100,
);
let entry = AssetEntry { let entry = AssetEntry {
asset_id: 1, asset_id: 1,
asset_name: "pcm".into(), asset_name: "pcm".into(),
@@ -485,7 +525,7 @@ mod tests {
} }
#[test] #[test]
fn shared_preload_waits_for_worker_and_frame_publication() { fn shared_preload_waits_for_worker_and_frame_publication() {
let bytes = vec![0; 8192]; let bytes = crate::bank_format::test_pcm_bank(&[0; 8192], 44100);
let entry = AssetEntry { let entry = AssetEntry {
asset_id: 1, asset_id: 1,
asset_name: "pcm".into(), asset_name: "pcm".into(),
@@ -521,7 +561,7 @@ mod tests {
#[test] #[test]
fn canceled_and_superseded_partial_decoders_never_publish() { fn canceled_and_superseded_partial_decoders_never_publish() {
use crate::memory_banks::SoundBankPoolAccess; use crate::memory_banks::SoundBankPoolAccess;
let bytes = vec![0x12; 16384]; let bytes = crate::bank_format::test_pcm_bank(&[0x12; 16384], 44100);
let entry = AssetEntry { let entry = AssetEntry {
asset_id: 1, asset_id: 1,
asset_name: "pcm".into(), asset_name: "pcm".into(),
+100 -15
View File
@@ -1,8 +1,14 @@
use prometeu_hal::{AudioBridge, AudioOpStatus}; use prometeu_hal::music_bank::MusicBank;
use prometeu_hal::{AudioBridge, AudioOpStatus, audio_bridge::AudioControl};
use std::sync::Arc; use std::sync::Arc;
use std::sync::atomic::AtomicBool;
pub mod bank_format;
/// Maximum number of simultaneous audio voices supported by the hardware. /// Maximum number of simultaneous audio voices supported by the hardware.
pub const MAX_CHANNELS: usize = 16; pub const MAX_CHANNELS: usize = 32;
pub const SFX_CHANNELS: usize = 8;
pub const SFX_START: usize = 24;
pub mod engine;
/// Standard sample rate for the final audio output. /// Standard sample rate for the final audio output.
pub const OUTPUT_SAMPLE_RATE: u32 = 48000; pub const OUTPUT_SAMPLE_RATE: u32 = 48000;
@@ -19,13 +25,14 @@ pub struct Channel {
pub sample: Option<Arc<Sample>>, pub sample: Option<Arc<Sample>>,
/// Whether this channel is currently active. /// Whether this channel is currently active.
pub active: bool, pub active: bool,
pub alive: Option<Arc<AtomicBool>>,
/// Current playback position within the sample (fractional for pitch shifting). /// Current playback position within the sample (fractional for pitch shifting).
pub pos: f64, pub pos: f64,
/// Playback speed multiplier (1.0 = original speed). /// Playback speed multiplier (1.0 = original speed).
pub pitch: f64, pub pitch: f64,
/// Voice volume (0-255). /// Voice volume (0-255).
pub volume: u8, pub volume: u8,
/// Stereo panning (0=Full Left, 127=Center, 255=Full Right). /// Stereo panning (0=Full Left, 128=Center, 255=Full Right).
pub pan: u8, pub pan: u8,
/// Loop configuration for this voice. /// Loop configuration for this voice.
pub loop_mode: LoopMode, pub loop_mode: LoopMode,
@@ -38,10 +45,11 @@ impl Default for Channel {
Self { Self {
sample: None, sample: None,
active: false, active: false,
alive: None,
pos: 0.0, pos: 0.0,
pitch: 1.0, pitch: 1.0,
volume: 255, volume: 255,
pan: 127, pan: 128,
loop_mode: LoopMode::Off, loop_mode: LoopMode::Off,
priority: 0, priority: 0,
} }
@@ -53,9 +61,16 @@ impl Default for Channel {
/// Because the Core logic runs at 60Hz and Audio is generated at 48kHz, /// Because the Core logic runs at 60Hz and Audio is generated at 48kHz,
/// we use an asynchronous command queue to synchronize them. /// we use an asynchronous command queue to synchronize them.
pub enum AudioCommand { pub enum AudioCommand {
MusicPlay {
group: usize,
bank: Arc<MusicBank>,
looping: bool,
},
Control(AudioControl),
/// Start playing a sample on a specific voice. /// Start playing a sample on a specific voice.
Play { Play {
sample: Arc<Sample>, sample: Arc<Sample>,
alive: Option<Arc<AtomicBool>>,
voice_id: usize, voice_id: usize,
volume: u8, volume: u8,
pan: u8, pan: u8,
@@ -64,13 +79,24 @@ pub enum AudioCommand {
loop_mode: LoopMode, loop_mode: LoopMode,
}, },
/// Stop playback on a voice when this command is applied. /// Stop playback on a voice when this command is applied.
Stop { voice_id: usize }, Stop {
voice_id: usize,
},
/// Update volume of an ongoing playback. /// Update volume of an ongoing playback.
SetVolume { voice_id: usize, volume: u8 }, SetVolume {
voice_id: usize,
volume: u8,
},
/// Update panning of an ongoing playback. /// Update panning of an ongoing playback.
SetPan { voice_id: usize, pan: u8 }, SetPan {
voice_id: usize,
pan: u8,
},
/// Update pitch of an ongoing playback. /// Update pitch of an ongoing playback.
SetPitch { voice_id: usize, pitch: f64 }, SetPitch {
voice_id: usize,
pitch: f64,
},
} }
mod transport; mod transport;
@@ -109,7 +135,7 @@ impl Audio {
} }
fn enqueue(&mut self, voice: usize, command: AudioCommand) -> AudioOpStatus { fn enqueue(&mut self, voice: usize, command: AudioCommand) -> AudioOpStatus {
if voice >= MAX_CHANNELS { if voice >= SFX_CHANNELS {
return AudioOpStatus::VoiceInvalid; return AudioOpStatus::VoiceInvalid;
} }
let admitted = if self.in_lifecycle { let admitted = if self.in_lifecycle {
@@ -142,7 +168,7 @@ impl AudioBridge for Audio {
priority: u8, priority: u8,
loop_mode: LoopMode, loop_mode: LoopMode,
) -> AudioOpStatus { ) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS { if voice_id >= SFX_CHANNELS {
return AudioOpStatus::VoiceInvalid; return AudioOpStatus::VoiceInvalid;
} }
if !pitch.is_finite() || pitch <= 0.0 { if !pitch.is_finite() || pitch <= 0.0 {
@@ -154,7 +180,19 @@ impl AudioBridge for Audio {
let Some(sample) = bank.samples.get(sample_id as usize).cloned() else { let Some(sample) = bank.samples.get(sample_id as usize).cloned() else {
return AudioOpStatus::SampleNotFound; return AudioOpStatus::SampleNotFound;
}; };
self.play_sample(sample, voice_id, volume, pan, pitch, priority, loop_mode) self.enqueue(
voice_id,
AudioCommand::Play {
sample,
alive: Some(bank.alive.clone()),
voice_id,
volume,
pan,
pitch,
priority,
loop_mode,
},
)
} }
fn play_sample( fn play_sample(
@@ -167,7 +205,7 @@ impl AudioBridge for Audio {
priority: u8, priority: u8,
loop_mode: LoopMode, loop_mode: LoopMode,
) -> AudioOpStatus { ) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS { if voice_id >= SFX_CHANNELS {
return AudioOpStatus::VoiceInvalid; return AudioOpStatus::VoiceInvalid;
} }
if !pitch.is_finite() || pitch <= 0.0 { if !pitch.is_finite() || pitch <= 0.0 {
@@ -175,10 +213,57 @@ impl AudioBridge for Audio {
} }
self.enqueue( self.enqueue(
voice_id, voice_id,
AudioCommand::Play { sample, voice_id, volume, pan, pitch, priority, loop_mode }, AudioCommand::Play {
sample,
alive: None,
voice_id,
volume,
pan,
pitch,
priority,
loop_mode,
},
) )
} }
fn music_play(&mut self, group: usize, bank: usize, looping: bool) -> AudioOpStatus {
if group > 1 {
return AudioOpStatus::ArgRangeInvalid;
}
let Some(bank) = self.sound_banks.music_bank_slot(bank) else {
return AudioOpStatus::BankInvalid;
};
self.enqueue(0, AudioCommand::MusicPlay { group, bank, looping })
}
fn control(&mut self, control: AudioControl) -> AudioOpStatus {
let valid = match control {
AudioControl::MusicStop { group }
| AudioControl::MusicPause { group, .. }
| AudioControl::MusicVolume { group, .. }
| AudioControl::MusicFade { group, .. } => group < 2,
AudioControl::Crossfade { source, target, .. } => {
source < 2 && target < 2 && source != target
}
AudioControl::BusVolume { bus, .. } => bus < 3,
AudioControl::GroupVolume { group, .. } => group < 3,
AudioControl::SfxSend { voice, .. } => voice < SFX_CHANNELS,
AudioControl::Effect { group, cutoff_hz, delay_frames, feedback, wet, dry } => {
group < 3
&& cutoff_hz <= OUTPUT_SAMPLE_RATE / 2
&& delay_frames <= 96_000
&& feedback.is_finite()
&& feedback.abs() < 1.0
&& wet.is_finite()
&& dry.is_finite()
&& (0.0..=1.0).contains(&wet)
&& (0.0..=1.0).contains(&dry)
}
};
if !valid {
return AudioOpStatus::ArgRangeInvalid;
}
self.enqueue(0, AudioCommand::Control(control))
}
fn stop(&mut self, voice_id: usize) -> AudioOpStatus { fn stop(&mut self, voice_id: usize) -> AudioOpStatus {
self.enqueue(voice_id, AudioCommand::Stop { voice_id }) self.enqueue(voice_id, AudioCommand::Stop { voice_id })
} }
@@ -189,7 +274,7 @@ impl AudioBridge for Audio {
self.enqueue(voice_id, AudioCommand::SetPan { voice_id, pan }) self.enqueue(voice_id, AudioCommand::SetPan { voice_id, pan })
} }
fn set_pitch(&mut self, voice_id: usize, pitch: f64) -> AudioOpStatus { fn set_pitch(&mut self, voice_id: usize, pitch: f64) -> AudioOpStatus {
if voice_id >= MAX_CHANNELS { if voice_id >= SFX_CHANNELS {
return AudioOpStatus::VoiceInvalid; return AudioOpStatus::VoiceInvalid;
} }
if !pitch.is_finite() || pitch <= 0.0 { if !pitch.is_finite() || pitch <= 0.0 {
@@ -311,7 +396,7 @@ mod control_tests {
for _ in 0..MAX_COMMANDS_PER_FRAME - 1 { for _ in 0..MAX_COMMANDS_PER_FRAME - 1 {
assert_eq!(audio.stop(0), AudioOpStatus::Ok); assert_eq!(audio.stop(0), AudioOpStatus::Ok);
} }
assert_eq!(audio.set_volume(15, 0), AudioOpStatus::Ok); assert_eq!(audio.set_volume(7, 0), AudioOpStatus::Ok);
assert_eq!(audio.set_pan(0, 255), AudioOpStatus::CommandLimit); assert_eq!(audio.set_pan(0, 255), AudioOpStatus::CommandLimit);
assert_eq!(audio.set_pitch(16, f64::NAN), AudioOpStatus::VoiceInvalid); assert_eq!(audio.set_pitch(16, f64::NAN), AudioOpStatus::VoiceInvalid);
assert_eq!(audio.set_pitch(0, f64::NAN), AudioOpStatus::ArgRangeInvalid); assert_eq!(audio.set_pitch(0, f64::NAN), AudioOpStatus::ArgRangeInvalid);
@@ -0,0 +1,592 @@
//! SBNK/MBNK v1. IMA WAVE4 algorithm implemented here from the published Intel
//! format, not copied from a third-party decoder. Project MIT license applies.
use prometeu_hal::{
music_bank::{Instrument, MusicBank, MusicCompiler, MusicEvent},
sample::Sample,
sound_bank::{AudioBankMetrics, SoundBank},
};
use std::sync::Arc;
pub const HEADER_BYTES: usize = 48;
pub const SAMPLE_BYTES: usize = 40;
pub const INSTRUMENT_BYTES: usize = 64;
pub const EVENT_BYTES: usize = 32;
pub enum DecodedAudioBank {
Sound(SoundBank),
Music(MusicBank),
}
impl DecodedAudioBank {
pub fn decoded_size(&self) -> usize {
match self {
Self::Sound(b) => b.metrics.canonical_decoded_bytes,
Self::Music(b) => b.metrics.canonical_decoded_bytes,
}
}
}
fn bytes(data: &[u8], offset: usize, len: usize) -> Result<&[u8], String> {
data.get(offset..offset.checked_add(len).ok_or("audio offset overflow")?)
.ok_or_else(|| "truncated audio bank".into())
}
fn u16le(b: &[u8], o: usize) -> Result<u16, String> {
Ok(u16::from_le_bytes(bytes(b, o, 2)?.try_into().unwrap()))
}
fn u32le(b: &[u8], o: usize) -> Result<u32, String> {
Ok(u32::from_le_bytes(bytes(b, o, 4)?.try_into().unwrap()))
}
fn zero(b: &[u8]) -> Result<(), String> {
if b.iter().any(|&x| x != 0) { Err("nonzero audio reserved bytes".into()) } else { Ok(()) }
}
fn vector<T>(n: usize) -> Result<Vec<T>, String> {
let mut v = Vec::new();
v.try_reserve_exact(n).map_err(|_| "audio allocation failed")?;
Ok(v)
}
/// One bank owns its serialized bytes while materializing. IO and CPU preparation
/// yield separately; no partially decoded bank escapes this object.
pub struct AudioBankMaterializer<'a> {
data: std::borrow::Cow<'a, [u8]>,
music: bool,
ns: usize,
ni: usize,
ne: usize,
ppq: u32,
tempo: u32,
duration: u32,
loop_tick: Option<u32>,
tracks: usize,
name: String,
samples_at: usize,
metadata: usize,
payload_end: usize,
samples: Vec<Arc<Sample>>,
instruments: Vec<Instrument>,
events: Vec<MusicEvent>,
current: Option<SampleMaterializer>,
compiler: Option<MusicCompiler>,
pcm_bytes: usize,
started: std::time::Instant,
}
struct SampleMaterializer {
sample: Sample,
codec: u8,
frames: usize,
offset: usize,
size: usize,
align: usize,
spb: usize,
consumed: usize,
}
impl<'a> AudioBankMaterializer<'a> {
pub fn new(data: std::borrow::Cow<'a, [u8]>, music: bool) -> Result<Self, String> {
let started = std::time::Instant::now();
bytes(&data, 0, HEADER_BYTES)?;
if &data[..4] != if music { b"MBNK" } else { b"SBNK" }
|| u16le(&data, 4)? != 1
|| u16le(&data, 6)? != 0
{
return Err("unsupported audio bank magic/version/flags".into());
}
let ns = u32le(&data, 8)? as usize;
let ni = u32le(&data, 12)? as usize;
let ne = u32le(&data, 16)? as usize;
let ppq = u32le(&data, 20)?;
let tempo = u32le(&data, 24)?;
let duration = u32le(&data, 28)?;
let lp = u32le(&data, 32)?;
let tracks = u32le(&data, 36)? as usize;
let name_len = u32le(&data, 40)? as usize;
zero(bytes(&data, 44, 4)?)?;
if ns > 65536
|| ppq != 960
|| tempo == 0
|| (!music
&& (ns == 0
|| ni != 0
|| ne != 0
|| duration != 0
|| tracks != 0
|| lp != u32::MAX))
{
return Err("invalid audio bank counts/clock".into());
}
if music
&& (duration == 0 || !(1..=256).contains(&tracks) || (lp != u32::MAX && lp >= duration))
{
return Err("invalid music clock/tracks/loop".into());
}
let mut offset = HEADER_BYTES.checked_add(name_len).ok_or("audio name overflow")?;
let samples_at = offset;
for (n, size) in [(ns, SAMPLE_BYTES), (ni, INSTRUMENT_BYTES), (ne, EVENT_BYTES)] {
offset = offset
.checked_add(n.checked_mul(size).ok_or("audio table overflow")?)
.ok_or("audio table overflow")?;
}
bytes(&data, 0, offset)?;
let text = std::str::from_utf8(bytes(&data, HEADER_BYTES, name_len)?)
.map_err(|_| "audio name UTF-8")?;
let mut name = String::new();
name.try_reserve_exact(text.len()).map_err(|_| "audio allocation failed")?;
name.push_str(text);
Ok(Self {
data,
music,
ns,
ni,
ne,
ppq,
tempo,
duration,
loop_tick: (lp != u32::MAX).then_some(lp),
tracks,
name,
samples_at,
metadata: offset,
payload_end: offset,
samples: vector(ns)?,
instruments: vector(ni)?,
events: vector(ne)?,
current: None,
compiler: None,
pcm_bytes: 0,
started,
})
}
fn start_sample(&mut self) -> Result<(), String> {
let d =
bytes(&self.data, self.samples_at + self.samples.len() * SAMPLE_BYTES, SAMPLE_BYTES)?;
let codec = d[0];
let channels = d[1];
let flags = u16le(d, 2)?;
let rate = u32le(d, 4)?;
let frames = u32le(d, 8)? as usize;
let start = u32le(d, 12)?;
let end = u32le(d, 16)?;
let offset = u32le(d, 20)? as usize;
let size = u32le(d, 24)? as usize;
let align = u16le(d, 28)? as usize;
let spb = u16le(d, 30)? as usize;
let pitch = u32le(d, 36)?;
zero(bytes(d, 34, 2)?)?;
if !(1..=2).contains(&channels)
|| rate == 0
|| pitch == 0
|| flags & !1 != 0
|| offset != self.payload_end
|| (flags == 0 && (start != 0 || end != 0))
|| (flags == 1 && (start >= end || end as usize > frames))
{
return Err("invalid audio sample descriptor/loop".into());
}
let scalar = frames.checked_mul(channels as usize).ok_or("PCM frame overflow")?;
let resident = scalar.checked_mul(2).ok_or("PCM byte overflow")?;
bytes(&self.data, offset, size)?;
match codec {
0 => {
if size != resident || align != 0 || spb != 0 {
return Err("PCM payload/frame count mismatch".into());
}
}
1 => {
let c = channels as usize;
if align < 8 * c
|| !align.is_multiple_of(4 * c)
|| spb != 1 + (align - 4 * c) * 2 / c
|| !size.is_multiple_of(align)
|| size / align != frames.div_ceil(spb)
{
return Err("IMA block layout/frame count".into());
}
}
_ => return Err("unsupported sample codec".into()),
}
let mut sample = Sample::new(rate, vector(scalar)?).with_channels(channels)?;
if flags == 1 {
sample = sample.with_loop(start, end);
}
sample.default_volume = d[32];
sample.default_pan = d[33];
sample.default_pitch = pitch as f64 / 65536.0;
self.pcm_bytes =
self.pcm_bytes.checked_add(resident).ok_or("resident audio size overflow")?;
self.current = Some(SampleMaterializer {
sample,
codec,
frames,
offset,
size,
align,
spb,
consumed: 0,
});
Ok(())
}
/// Decode at most 4096 PCM bytes or one independently bounded IMA block;
/// parse at most 64 metadata records; compile at most 64 music records.
pub fn step(&mut self) -> Result<Option<DecodedAudioBank>, String> {
if let Some(compiler) = &mut self.compiler {
return match compiler.step()? {
Some(mut bank) => {
bank.metrics = self.metrics()?;
Ok(Some(DecodedAudioBank::Music(bank)))
}
None => Ok(None),
};
}
if self.samples.len() < self.ns {
if self.current.is_none() {
self.start_sample()?;
}
let current = self.current.as_mut().unwrap();
if current.consumed < current.size {
if current.codec == 0 {
let count = (current.size - current.consumed).min(4096);
let part = bytes(&self.data, current.offset + current.consumed, count)?;
current
.sample
.data
.extend(part.as_chunks::<2>().0.iter().map(|p| i16::from_le_bytes(*p)));
current.consumed += count;
} else {
let frames = (current.frames - current.sample.frames_len()).min(current.spb);
let pcm = decode_ima_wav4(
bytes(&self.data, current.offset + current.consumed, current.align)?,
current.sample.channels,
frames,
current.align,
current.spb,
)?;
current.sample.data.extend(pcm);
current.consumed += current.align;
}
}
if current.consumed == current.size {
self.payload_end = current.offset + current.size;
let current = self.current.take().unwrap();
self.samples.push(Arc::new(current.sample));
}
return Ok(None);
}
if self.payload_end != self.data.len() {
return Err("audio trailing/unreferenced payload".into());
}
if !self.music {
let mut bank = SoundBank::new(std::mem::take(&mut self.samples));
bank.name = std::mem::take(&mut self.name);
bank.metrics = self.metrics()?;
return Ok(Some(DecodedAudioBank::Sound(bank)));
}
let inst_at = self.samples_at + self.ns * SAMPLE_BYTES;
if self.instruments.len() < self.ni {
for _ in 0..64 {
if self.instruments.len() == self.ni {
break;
}
let d = bytes(
&self.data,
inst_at + self.instruments.len() * INSTRUMENT_BYTES,
INSTRUMENT_BYTES,
)?;
if d[7] & !1 != 0 {
return Err("instrument flags".into());
}
zero(bytes(d, 22, 2)?)?;
zero(bytes(d, 43, 21)?)?;
self.instruments.push(Instrument {
id: u16le(d, 0)?,
sample: u16le(d, 2)?,
low: d[4],
high: d[5],
root: d[6],
looping: d[7] & 1 != 0,
tuning_cents: u16le(d, 8)? as i16,
pan: d[10],
gain: d[11],
attack_us: u32le(d, 12)?,
decay_us: u32le(d, 16)?,
sustain: u16le(d, 20)?,
release_us: u32le(d, 24)?,
vibrato_millihz: u32le(d, 28)?,
vibrato_cents: u16le(d, 32)?,
tremolo_depth: u16le(d, 34)?,
tremolo_millihz: u32le(d, 36)?,
send: u16le(d, 40)?,
curve: d[42],
});
}
return Ok(None);
}
if self.events.len() < self.ne {
let at = inst_at + self.ni * INSTRUMENT_BYTES;
for _ in 0..64 {
if self.events.len() == self.ne {
break;
}
let d = bytes(&self.data, at + self.events.len() * EVENT_BYTES, EVENT_BYTES)?;
self.events.push(MusicEvent {
tick: u32le(d, 0)?,
kind: d[4],
track: d[5],
flags: u16le(d, 6)?,
a: u32le(d, 8)?,
b: u32le(d, 12)?,
c: u32le(d, 16)? as i32,
d: u32le(d, 20)? as i32,
duration_frames: u32le(d, 24)?,
curve: u32le(d, 28)?,
});
}
return Ok(None);
}
self.compiler = Some(MusicCompiler::new(
std::mem::take(&mut self.name),
std::mem::take(&mut self.samples),
std::mem::take(&mut self.instruments),
std::mem::take(&mut self.events),
self.ppq,
self.tempo,
self.duration,
self.loop_tick,
self.tracks,
)?);
Ok(None)
}
fn metrics(&self) -> Result<AudioBankMetrics, String> {
Ok(AudioBankMetrics {
cartridge_bytes: self.data.len(),
pcm_bytes: self.pcm_bytes,
canonical_decoded_bytes: self
.metadata
.checked_add(self.pcm_bytes)
.ok_or("decoded audio size overflow")?,
materialization_ns: self.started.elapsed().as_nanos().min(u64::MAX as u128) as u64,
})
}
}
pub fn decode_audio_bank(data: &[u8], music: bool) -> Result<DecodedAudioBank, String> {
let mut decoder = AudioBankMaterializer::new(std::borrow::Cow::Borrowed(data), music)?;
loop {
if let Some(bank) = decoder.step()? {
return Ok(bank);
}
}
}
const STEP: [i32; 89] = [
7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66,
73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190, 209, 230, 253, 279, 307, 337, 371, 408, 449,
494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272,
2499, 2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493,
10442, 11487, 12635, 13899, 15289, 16818, 18500, 20350, 22385, 24623, 27086, 29794, 32767,
];
const INDEX: [i32; 8] = [-1, -1, -1, -1, 2, 4, 6, 8];
fn ima_code(code: u8, predictor: &mut i32, index: &mut usize) -> i16 {
let step = STEP[*index];
let mut diff = step >> 3;
if code & 1 != 0 {
diff += step >> 2;
}
if code & 2 != 0 {
diff += step >> 1;
}
if code & 4 != 0 {
diff += step;
}
*predictor = (*predictor + if code & 8 != 0 { -diff } else { diff }).clamp(-32768, 32767);
*index = (*index as i32 + INDEX[(code & 7) as usize]).clamp(0, 88) as usize;
*predictor as i16
}
pub fn decode_ima_wav4(
data: &[u8],
channels: u8,
frames: usize,
align: usize,
spb: usize,
) -> Result<Vec<i16>, String> {
let c = channels as usize;
if !(1..=2).contains(&channels)
|| align > u16::MAX as usize
|| align < 8 * c
|| !align.is_multiple_of(4 * c)
|| spb != 1 + (align - 4 * c) * 2 / c
|| !data.len().is_multiple_of(align)
|| data.len() / align != frames.div_ceil(spb)
{
return Err("invalid IMA WAVE4 block/frame layout".into());
}
let mut out = vector(frames.checked_mul(c).ok_or("IMA frame overflow")?)?;
for (block_index, block) in data.chunks_exact(align).enumerate() {
let mut pred = [0i32; 2];
let mut index = [0usize; 2];
for ch in 0..c {
pred[ch] = i16::from_le_bytes([block[ch * 4], block[ch * 4 + 1]]) as i32;
index[ch] = block[ch * 4 + 2] as usize;
if index[ch] > 88 || block[ch * 4 + 3] != 0 {
return Err("IMA predictor index/reserved".into());
}
out.push(pred[ch] as i16);
}
let remaining = (frames - block_index * spb).min(spb);
for group in 0..(spb - 1) / 8 {
let mut decoded = [[0i16; 8]; 2];
for ch in 0..c {
for n in 0..8 {
let b = block[4 * c + group * 4 * c + ch * 4 + n / 2];
let code = (b >> ((n % 2) * 4)) & 15;
if 1 + group * 8 + n >= remaining && code != 0 {
return Err("nonzero IMA padding".into());
}
decoded[ch][n] = ima_code(code, &mut pred[ch], &mut index[ch]);
}
}
for n in 0..8 {
if 1 + group * 8 + n < remaining {
for channel in decoded.iter().take(c) {
out.push(channel[n]);
}
}
}
}
}
Ok(out)
}
/// Deterministic storage encoder used by conformance tools/fixtures (never RT).
pub fn encode_ima_wav4(pcm: &[i16], channels: u8, align: usize) -> Result<Vec<u8>, String> {
let c = channels as usize;
if !(1..=2).contains(&channels)
|| !pcm.len().is_multiple_of(c)
|| align > u16::MAX as usize
|| align < 8 * c
|| !align.is_multiple_of(4 * c)
{
return Err("IMA encoder shape".into());
}
let spb = 1 + (align - 4 * c) * 2 / c;
if spb > u16::MAX as usize {
return Err("IMA block exceeds descriptor range".into());
}
let frames = pcm.len() / c;
let nblocks = frames.div_ceil(spb);
let mut out = vector(nblocks.checked_mul(align).ok_or("IMA encoded size overflow")?)?;
for block in 0..nblocks {
let first = block * spb;
let count = (frames - first).min(spb);
let mut pred = [0i32; 2];
let mut index = [0usize; 2];
for ch in 0..c {
pred[ch] = pcm[first * c + ch] as i32;
let n = (count - 1).min(32);
let sum: i32 = (1..=n)
.map(|i| {
(pcm[(first + i) * c + ch] as i32 - pcm[(first + i - 1) * c + ch] as i32).abs()
})
.sum();
let mean = if n == 0 { 0 } else { sum / n as i32 };
index[ch] = STEP.iter().position(|&s| s >= mean).unwrap_or(88);
out.extend_from_slice(&(pred[ch] as i16).to_le_bytes());
out.push(index[ch] as u8);
out.push(0);
}
for group in 0..(spb - 1) / 8 {
for ch in 0..c {
for byte in 0..4 {
let mut packed = 0;
for nibble in 0..2 {
let f = 1 + group * 8 + byte * 2 + nibble;
let code = if f >= count {
0
} else {
let diff = pcm[(first + f) * c + ch] as i32 - pred[ch];
let mut magnitude = diff.abs();
let step = STEP[index[ch]];
let mut code = if diff < 0 { 8 } else { 0 };
if magnitude >= step {
code |= 4;
magnitude -= step;
}
if magnitude >= step >> 1 {
code |= 2;
magnitude -= step >> 1;
}
if magnitude >= step >> 2 {
code |= 1;
}
code
};
ima_code(code, &mut pred[ch], &mut index[ch]);
packed |= code << (nibble * 4);
}
out.push(packed);
}
}
}
}
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn ima_known_nibbles_and_stereo_headers() {
let block = [0, 0, 0, 0, 0x11, 0, 0, 0];
assert_eq!(decode_ima_wav4(&block, 1, 3, 8, 9).unwrap(), [0, 1, 2]);
let mut stereo = vec![0, 0, 0, 0, 100, 0, 0, 0];
stereo.extend([0u8; 8]);
let decoded = decode_ima_wav4(&stereo, 2, 9, 16, 9).unwrap();
assert_eq!(&decoded[..6], [0, 100, 0, 100, 0, 100]);
stereo[2] = 89;
assert!(decode_ima_wav4(&stereo, 2, 9, 16, 9).is_err());
}
#[test]
fn ima_partial_block_padding_round_trip_is_deterministic() {
let pcm: Vec<i16> = (0..1111)
.flat_map(|i| {
[
((i as f64 * 0.03).sin() * 12000.0) as i16,
((i as f64 * 0.02).cos() * 9000.0) as i16,
]
})
.collect();
let encoded = encode_ima_wav4(&pcm, 2, 512).unwrap();
assert_eq!(encoded, encode_ima_wav4(&pcm, 2, 512).unwrap());
let decoded = decode_ima_wav4(&encoded, 2, 1111, 512, 505).unwrap();
assert_eq!(decoded.len(), pcm.len());
assert_eq!(decoded[1010], pcm[1010]);
assert!(decode_ima_wav4(&encoded[..encoded.len() - 1], 2, 1111, 512, 505).is_err());
let error: f64 =
pcm.iter().zip(decoded).map(|(&a, b)| (a as f64 - b as f64).powi(2)).sum::<f64>()
/ pcm.len() as f64;
assert!(error.sqrt() < 400.0, "RMS error {error}");
}
}
#[cfg(test)]
pub(crate) fn test_pcm_bank(raw: &[u8], rate: u32) -> Vec<u8> {
let mut bytes = vec![0u8; 88];
bytes[..4].copy_from_slice(b"SBNK");
bytes[4] = 1;
for (at, value) in [
(8, 1),
(20, 960),
(24, 500000),
(32, u32::MAX),
(52, rate),
(56, (raw.len() / 2) as u32),
(68, 88),
(72, raw.len() as u32),
(84, 65536),
] {
bytes[at..at + 4].copy_from_slice(&value.to_le_bytes());
}
bytes[49] = 1;
bytes[80] = 255;
bytes[81] = 128;
bytes.extend_from_slice(raw);
bytes
}
#[cfg(test)]
#[path = "bank_tests.rs"]
mod bank_tests;
@@ -0,0 +1,182 @@
use super::*;
use crate::{AssetManager, MemoryBanks, SoundBankPoolAccess};
use prometeu_hal::{
asset::{AssetCodec, AssetEntry, AssetOpStatus, BankType, LoadStatus, SlotRef},
cartridge::AssetsPayloadSource,
};
use std::time::{Duration, Instant};
fn fixtures() -> Vec<(&'static [u8], bool)> {
vec![
(
include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/pcm-only.sbnk"
)),
false,
),
(
include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/ima-only.sbnk"
)),
false,
),
(
include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-sound.sbnk"
)),
false,
),
(
include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-music.mbnk"
)),
true,
),
]
}
#[test]
fn packer_binary_fixtures_materialize_mixed_stereo_banks_and_separate_encoded_from_pcm_sizes() {
for (index, (bytes, music)) in fixtures().into_iter().enumerate() {
let decoded = decode_audio_bank(bytes, music).unwrap();
let (samples, metrics) = match &decoded {
DecodedAudioBank::Sound(b) => (&b.samples, b.metrics),
DecodedAudioBank::Music(b) => {
assert_eq!(b.events.len(), 4);
assert_eq!(b.instruments.len(), 2);
assert_eq!(b.tracks, 2);
(&b.samples, b.metrics)
}
};
assert_eq!(metrics.cartridge_bytes, bytes.len());
assert_eq!(metrics.pcm_bytes, if index < 2 { 2000 } else { 6000 });
assert_eq!(samples[0].frames_len(), 1000);
assert_eq!(samples[0].loop_end, Some(1000));
if index >= 2 {
assert_eq!(samples[1].channels, 2);
assert_eq!(samples[1].frames_len(), 1000);
}
if index != 0 {
assert!(decoded.decoded_size() > bytes.len());
}
}
}
#[test]
fn complete_validation_rejects_truncation_unknown_codec_bad_loops_and_reserved_bytes() {
for (bytes, music) in fixtures() {
for cut in [0, 4, 47, 48, bytes.len() - 1] {
assert!(decode_audio_bank(&bytes[..cut], music).is_err());
}
let name = u32le(bytes, 40).unwrap() as usize;
let sample = 48 + name;
for (at, value) in
[(4, 2), (44, 1), (sample, 99), (sample + 1, 3), (sample + 2, 2), (sample + 34, 1)]
{
let mut bad = bytes.to_vec();
bad[at] = value;
assert!(decode_audio_bank(&bad, music).is_err(), "{at}");
}
let mut bad = bytes.to_vec();
bad[sample + 12..sample + 16].copy_from_slice(&1001u32.to_le_bytes());
assert!(decode_audio_bank(&bad, music).is_err());
let mut bad = bytes.to_vec();
bad.push(0);
assert!(decode_audio_bank(&bad, music).is_err());
// Mutating every byte must produce either a validated bank or a clean error.
for i in 0..bytes.len() {
let mut changed = bytes.to_vec();
changed[i] ^= 0xff;
let _ = decode_audio_bank(&changed, music);
}
}
}
fn entry(id: i32, offset: usize, bytes: &[u8], music: bool) -> AssetEntry {
AssetEntry {
asset_id: id,
asset_name: format!("bank{id}"),
bank_type: if music { BankType::MUSIC } else { BankType::SOUNDS },
offset: offset as u64,
size: bytes.len() as u64,
decoded_size: decode_audio_bank(bytes, music).unwrap().decoded_size() as u64,
codec: AssetCodec::None,
metadata: serde_json::json!({"version":1}),
}
}
fn ready(manager: &AssetManager, handle: u32) {
let end = Instant::now() + Duration::from_secs(3);
while matches!(
manager.status(handle),
LoadStatus::QUEUED | LoadStatus::LOADING | LoadStatus::PENDING | LoadStatus::ACTIVE
) {
assert!(Instant::now() < end);
std::thread::yield_now();
}
assert_eq!(manager.status(handle), LoadStatus::READY);
}
#[test]
fn audio_loading_commit_replacement_and_unload_are_atomic_and_type_isolated() {
let fixtures = fixtures();
let sound = fixtures[2].0;
let music = fixtures[3].0;
let mut payload = sound.to_vec();
payload.extend_from_slice(music);
let bad_at = payload.len();
let mut corrupt = sound.to_vec();
corrupt[0] = 0;
payload.extend(&corrupt);
let mut bad = entry(3, bad_at, sound, false);
bad.decoded_size += 1;
let banks = Arc::new(MemoryBanks::new());
let manager = AssetManager::new(
vec![entry(1, 0, sound, false), entry(2, sound.len(), music, true), bad],
AssetsPayloadSource::from_bytes(payload),
banks.clone(),
banks.clone(),
banks.clone(),
);
let s = manager.load(1, 0).unwrap();
ready(&manager, s);
assert!(banks.sound_bank_slot(0).is_none());
assert_eq!(manager.commit(s), AssetOpStatus::Ok);
manager.apply_commits();
let old = banks.sound_bank_slot(0).unwrap();
let m = manager.load(2, 0).unwrap();
ready(&manager, m);
manager.commit(m);
manager.apply_commits();
assert!(old.alive.load(std::sync::atomic::Ordering::Acquire));
assert!(banks.music_bank_slot(0).is_some());
let failing = manager.load(3, 0).unwrap();
let end = Instant::now() + Duration::from_secs(3);
while manager.status(failing) != LoadStatus::ERROR {
assert!(Instant::now() < end);
std::thread::yield_now();
}
manager.apply_commits();
assert!(Arc::ptr_eq(&old, &banks.sound_bank_slot(0).unwrap()));
let replacement = manager.load(1, 0).unwrap();
ready(&manager, replacement);
assert!(old.alive.load(std::sync::atomic::Ordering::Acquire));
manager.commit(replacement);
manager.apply_commits();
assert!(!old.alive.load(std::sync::atomic::Ordering::Acquire));
assert_eq!(manager.unload_audio(true, 0), AssetOpStatus::Ok);
assert!(banks.music_bank_slot(0).is_none());
assert!(banks.sound_bank_slot(0).is_some());
assert_eq!(manager.slot_info(SlotRef::music(0)).asset_id, None);
assert_eq!(manager.unload_audio(false, 0), AssetOpStatus::Ok);
assert!(banks.sound_bank_slot(0).is_none());
assert_eq!(manager.unload_audio(false, 16), AssetOpStatus::InvalidState);
}
#[test]
fn codec_tooling_rejects_overflowing_block_parameters_without_panicking() {
for align in [0, 4, usize::MAX - 3, usize::MAX] {
assert!(encode_ima_wav4(&[1, 2], 1, align).is_err());
assert!(decode_ima_wav4(&[0; 8], 1, 9, align, 9).is_err());
}
assert!(encode_ima_wav4(&[1], 1, 65532).is_err());
assert!(decode_ima_wav4(&[0; 8], 1, usize::MAX, 8, 9).is_err());
assert!(encode_ima_wav4(&[1], 0, 256).is_err());
}
@@ -0,0 +1,924 @@
//! Host-independent bounded PCM engine. Construct resources off the render lane.
use super::{
AudioCommand, AudioDelivery, AudioTransport, Channel, LoopMode, MAX_CHANNELS,
MAX_COMMANDS_PER_FRAME, SFX_CHANNELS, SFX_START,
};
use prometeu_hal::{
audio_bridge::AudioControl,
music_bank::{Instrument, MAX_MUSIC_TRACKS, MusicBank, MusicEvent},
sample::Sample,
};
use std::{
sync::{
Arc,
atomic::{AtomicBool, Ordering},
},
time::{Duration, Instant},
};
pub const RETIRED_CAPACITY: usize = 2 * (3 * MAX_COMMANDS_PER_FRAME + MAX_CHANNELS + 2);
/// Owning resources leave the real-time lane in a preallocated packet.
#[allow(dead_code)]
enum Retired {
Sample(Arc<Sample>),
Bank(Arc<MusicBank>),
Token(Arc<AtomicBool>),
}
pub struct Packet {
retired: Vec<Retired>,
pub batches: [Option<Vec<AudioCommand>>; 2],
}
impl Default for Packet {
fn default() -> Self {
Self::new()
}
}
impl Packet {
pub fn new() -> Self {
Self { retired: Vec::with_capacity(RETIRED_CAPACITY), batches: [None, None] }
}
fn push(&mut self, owner: Retired) {
assert!(self.retired.len() < RETIRED_CAPACITY, "audio retirement bound");
self.retired.push(owner);
}
fn voice(&mut self, voice: &mut Channel) {
if let Some(s) = voice.sample.take() {
self.push(Retired::Sample(s));
}
if let Some(t) = voice.alive.take() {
self.push(Retired::Token(t));
}
voice.active = false;
}
pub fn recycle(&mut self, transport: &AudioTransport) {
self.retired.clear();
for batch in &mut self.batches {
if let Some(batch) = batch.take() {
transport.recycle_commands(batch);
}
}
}
/// Service thread only: count distinct retired PCM payloads, excluding Arc overhead.
pub fn retained_pcm_bytes(&self) -> usize {
let mut seen = std::collections::HashSet::new();
let mut bytes = 0;
let mut add = |sample: &Arc<Sample>| {
if seen.insert(Arc::as_ptr(sample)) {
bytes += sample.data.capacity() * 2;
}
};
for owner in &self.retired {
match owner {
Retired::Sample(sample) => add(sample),
Retired::Bank(bank) => {
for sample in bank.samples.iter() {
add(sample);
}
}
Retired::Token(_) => {}
}
}
for batch in self.batches.iter().flatten() {
for command in batch {
match command {
AudioCommand::Play { sample, .. } => add(sample),
AudioCommand::MusicPlay { bank, .. } => {
for sample in bank.samples.iter() {
add(sample);
}
}
_ => {}
}
}
}
bytes
}
pub fn is_empty(&self) -> bool {
self.retired.is_empty() && self.batches.iter().all(Option::is_none)
}
pub fn capacity(&self) -> usize {
self.retired.capacity()
}
}
#[derive(Clone, Copy)]
struct Ramp {
from: f64,
to: f64,
start: u64,
duration: u32,
smooth: bool,
}
impl Ramp {
fn constant(value: f64) -> Self {
Self { from: value, to: value, start: 0, duration: 0, smooth: false }
}
fn at(self, now: u64) -> f64 {
if self.duration == 0 {
return self.to;
}
let elapsed = now.saturating_sub(self.start);
if elapsed >= self.duration as u64 {
return self.to;
}
let x = elapsed as f64 / self.duration as f64;
let x = if self.smooth { x * x * (3.0 - 2.0 * x) } else { x };
self.from + (self.to - self.from) * x
}
fn set(&mut self, value: f64, now: u64, duration: u32, smooth: bool) {
*self = Self { from: self.at(now), to: value, start: now, duration, smooth };
}
fn done(self, now: u64) -> bool {
now.saturating_sub(self.start) >= self.duration as u64
}
}
#[derive(Clone, Copy)]
struct SendRamp {
base: Ramp,
scale: Ramp,
}
impl Default for SendRamp {
fn default() -> Self {
Self { base: Ramp::constant(0.0), scale: Ramp::constant(1.0) }
}
}
impl SendRamp {
fn at(self, now: u64, instrument_default: f64) -> f64 {
self.base.at(now) + self.scale.at(now) * instrument_default
}
fn set(&mut self, to: f64, now: u64, frames: u32, smooth: bool) {
self.base.set(to, now, frames, smooth);
self.scale.set(0.0, now, frames, smooth);
}
}
#[derive(Clone, Copy)]
struct Track {
gain: Ramp,
pan: Ramp,
pitch: Ramp,
send: SendRamp,
vibrato: Option<(u32, f64)>,
tremolo: Option<(u32, f64)>,
}
impl Default for Track {
fn default() -> Self {
Self {
gain: Ramp::constant(1.0),
pan: Ramp::constant(128.0),
pitch: Ramp::constant(0.0),
send: SendRamp::default(),
vibrato: None,
tremolo: None,
}
}
}
struct MusicGroup {
bank: Option<Arc<MusicBank>>,
active: bool,
paused: bool,
looping: bool,
time: u128,
cursor: usize,
frame: u64,
iteration: u64,
tracks: [Track; MAX_MUSIC_TRACKS],
gain: Ramp,
stop_after_fade: bool,
}
impl Default for MusicGroup {
fn default() -> Self {
Self {
bank: None,
active: false,
paused: false,
looping: false,
time: 0,
cursor: 0,
frame: 0,
iteration: 0,
tracks: [Track::default(); MAX_MUSIC_TRACKS],
gain: Ramp::constant(1.0),
stop_after_fade: false,
}
}
}
#[derive(Clone, Copy)]
struct VoiceState {
inst: Instrument,
track: usize,
note_id: u32,
iteration: u64,
born: u64,
age: u64,
release_age: Option<u64>,
release_level: f64,
release_order: Option<u64>,
level: f64,
cached_cents: f64,
pitch_factor: f64,
glide: Ramp,
send: f64,
zone: usize,
}
impl Default for VoiceState {
fn default() -> Self {
Self {
inst: Instrument::default(),
track: 0,
note_id: 0,
iteration: 0,
born: 0,
age: 0,
release_age: None,
release_level: 0.0,
release_order: None,
level: 1.0,
cached_cents: f64::INFINITY,
pitch_factor: 1.0,
glide: Ramp::constant(0.0),
send: 0.0,
zone: 0,
}
}
}
struct Effect {
delay: Vec<[f32; 2]>,
write: usize,
history: usize,
frames: usize,
feedback: f32,
wet: f32,
dry: f32,
coefficient: f32,
filter: [f32; 2],
}
impl Effect {
fn new() -> Self {
Self {
delay: vec![[0.0; 2]; 96_000],
write: 0,
history: 0,
frames: 0,
feedback: 0.0,
wet: 0.0,
dry: 1.0,
coefficient: 1.0,
filter: [0.0; 2],
}
}
fn reset(&mut self) {
self.write = 0;
self.history = 0;
self.filter = [0.0; 2];
}
fn process(&mut self, input: [f32; 2], send: [f32; 2]) -> [f32; 2] {
if self.frames == 0 && self.coefficient == 1.0 {
self.filter = input;
return [input[0] * self.dry, input[1] * self.dry];
}
let mut out = [0.0; 2];
for c in 0..2 {
self.filter[c] += self.coefficient * (input[c] - self.filter[c]);
// Flush subnormals without denormal-sensitive host settings.
if self.filter[c].abs() < 1e-20 {
self.filter[c] = 0.0;
}
let echo = if self.frames != 0 && self.history >= self.frames {
self.delay[(self.write + 96_000 - self.frames) % 96_000][c]
} else {
0.0
};
out[c] = self.filter[c] * self.dry + echo * self.wet;
self.delay[self.write][c] = send[c] + echo * self.feedback;
if self.delay[self.write][c].abs() < 1e-20 {
self.delay[self.write][c] = 0.0;
}
}
self.write = (self.write + 1) % 96_000;
self.history = (self.history + 1).min(96_000);
out
}
}
#[derive(Debug, Clone, Copy, Default)]
pub struct AudioDiagnostics {
pub frames: u64,
pub active_voices: usize,
pub maximum_voices: usize,
pub last_render_us: u64,
pub maximum_render_us: u64,
}
pub struct AudioMixer {
pub voices: [Channel; MAX_CHANNELS],
states: [VoiceState; MAX_CHANNELS],
groups: [MusicGroup; 2],
effects: [Effect; 3],
bus: [f32; 3],
sfx_gain: f32,
exponential: [f64; 1025],
sine: [f64; 4097],
pub last_processing_time: Duration,
paused: bool,
epoch: u64,
pub diagnostics: AudioDiagnostics,
note_serial: u64,
}
impl Default for AudioMixer {
fn default() -> Self {
Self::new()
}
}
impl AudioMixer {
pub fn new() -> Self {
Self {
voices: std::array::from_fn(|_| Channel::default()),
states: [VoiceState::default(); MAX_CHANNELS],
groups: std::array::from_fn(|_| MusicGroup::default()),
effects: std::array::from_fn(|_| Effect::new()),
bus: [1.0; 3],
sfx_gain: 1.0,
exponential: std::array::from_fn(|i| {
((-6.0 * i as f64 / 1024.0).exp() - (-6.0f64).exp()) / (1.0 - (-6.0f64).exp())
}),
sine: std::array::from_fn(|i| (std::f64::consts::TAU * i as f64 / 4096.0).sin()),
last_processing_time: Duration::ZERO,
paused: false,
epoch: 0,
diagnostics: AudioDiagnostics::default(),
note_serial: 0,
}
}
pub fn prepared_bytes(&self) -> usize {
std::mem::size_of::<Self>()
+ self
.effects
.iter()
.map(|e| e.delay.capacity() * std::mem::size_of::<[f32; 2]>())
.sum::<usize>()
}
fn stop_group(&mut self, group: usize, packet: &mut Packet) {
for v in &mut self.voices[group * 12..group * 12 + 12] {
packet.voice(v);
}
if let Some(bank) = self.groups[group].bank.take() {
packet.push(Retired::Bank(bank));
}
let gain = self.groups[group].gain.at(self.groups[group].frame);
self.groups[group] = MusicGroup::default();
self.groups[group].gain = Ramp::constant(gain);
self.effects[group].reset();
}
pub fn retire_inactive(&mut self, packet: &mut Packet) {
for g in 0..2 {
if self.groups[g].bank.as_ref().is_some_and(|b| !b.alive.load(Ordering::Acquire))
|| (self.groups[g].stop_after_fade && !self.groups[g].active)
{
self.stop_group(g, packet);
}
}
for v in &mut self.voices {
if !v.active || v.alive.as_ref().is_some_and(|a| !a.load(Ordering::Acquire)) {
packet.voice(v);
}
}
}
pub fn apply_delivery_into(&mut self, delivery: AudioDelivery, packet: &mut Packet) {
if delivery.epoch < self.epoch {
packet.batches = [delivery.frame, delivery.lifecycle];
return;
}
if delivery.epoch != self.epoch {
for group in 0..2 {
self.stop_group(group, packet);
}
for voice in &mut self.voices {
packet.voice(voice);
*voice = Channel::default();
}
for group in &mut self.groups {
group.gain = Ramp::constant(1.0);
}
for effect in &mut self.effects {
effect.reset();
effect.frames = 0;
effect.feedback = 0.0;
effect.wet = 0.0;
effect.dry = 1.0;
effect.coefficient = 1.0;
}
self.bus = [1.0; 3];
self.sfx_gain = 1.0;
self.epoch = delivery.epoch;
}
packet.batches = [delivery.frame, delivery.lifecycle];
for index in 0..2 {
if let Some(mut batch) = packet.batches[index].take() {
for command in &mut batch {
let command =
std::mem::replace(command, AudioCommand::Stop { voice_id: SFX_CHANNELS });
self.process_command(command, packet);
}
packet.batches[index] = Some(batch);
}
}
self.paused = delivery.paused;
}
/// Convenience for non-real-time signal tests/offline owners.
pub fn apply_delivery(&mut self, delivery: AudioDelivery) {
self.apply_delivery_into(delivery, &mut Packet::new());
}
pub fn fill_buffer(&mut self, buffer: &mut [f32]) {
self.mix(buffer);
self.retire_inactive(&mut Packet::new());
}
fn process_command(&mut self, command: AudioCommand, packet: &mut Packet) {
match command {
AudioCommand::Play {
sample,
alive,
voice_id,
volume,
pan,
pitch,
priority,
loop_mode,
} => {
if voice_id >= SFX_CHANNELS
|| alive.as_ref().is_some_and(|a| !a.load(Ordering::Acquire))
{
packet.push(Retired::Sample(sample));
if let Some(t) = alive {
packet.push(Retired::Token(t));
}
return;
}
let index = SFX_START + voice_id;
packet.voice(&mut self.voices[index]);
self.voices[index] = Channel {
sample: Some(sample),
alive,
active: true,
pos: 0.0,
pitch,
volume,
pan,
loop_mode,
priority,
};
self.states[index] = VoiceState::default();
}
AudioCommand::Stop { voice_id } => {
if voice_id < SFX_CHANNELS {
packet.voice(&mut self.voices[SFX_START + voice_id]);
}
}
AudioCommand::SetVolume { voice_id, volume } => {
if voice_id < SFX_CHANNELS {
self.voices[SFX_START + voice_id].volume = volume;
}
}
AudioCommand::SetPan { voice_id, pan } => {
if voice_id < SFX_CHANNELS {
self.voices[SFX_START + voice_id].pan = pan;
}
}
AudioCommand::SetPitch { voice_id, pitch } => {
if voice_id < SFX_CHANNELS {
self.voices[SFX_START + voice_id].pitch = pitch;
}
}
AudioCommand::MusicPlay { group, bank, looping } => {
if group >= 2 || !bank.alive.load(Ordering::Acquire) {
packet.push(Retired::Bank(bank));
return;
}
self.stop_group(group, packet);
self.groups[group].bank = Some(bank);
self.groups[group].active = true;
self.groups[group].looping = looping;
}
AudioCommand::Control(control) => match control {
AudioControl::GroupVolume { group, gain } => {
if group == 2 {
self.sfx_gain = gain as f32 / 255.0;
} else {
self.groups[group].gain = Ramp::constant(gain as f64 / 255.0);
self.groups[group].stop_after_fade = false;
}
}
AudioControl::MusicStop { group } => self.stop_group(group, packet),
AudioControl::MusicPause { group, paused } => self.groups[group].paused = paused,
AudioControl::MusicVolume { group, gain } => {
self.groups[group].gain = Ramp::constant(gain as f64 / 255.0);
self.groups[group].stop_after_fade = false;
}
AudioControl::MusicFade { group, gain, frames, smooth } => {
let g = &mut self.groups[group];
g.gain.set(gain as f64 / 255.0, g.frame, frames, smooth);
g.stop_after_fade = false;
}
AudioControl::Crossfade { source, target, frames, smooth } => {
if !self.groups[source].active || !self.groups[target].active {
return;
}
for (g, value) in [(source, 0.0), (target, 1.0)] {
let group = &mut self.groups[g];
group.gain.set(value, group.frame, frames, smooth);
group.stop_after_fade = g == source;
}
}
AudioControl::BusVolume { bus, gain } => self.bus[bus] = gain as f32 / 255.0,
AudioControl::SfxSend { voice, gain } => {
self.states[SFX_START + voice].send = gain as f64 / 255.0
}
AudioControl::Effect { group, cutoff_hz, delay_frames, feedback, wet, dry } => {
let effect = &mut self.effects[group];
effect.coefficient = if cutoff_hz == 0 {
1.0
} else {
(1.0 - (-std::f32::consts::TAU * cutoff_hz as f32 / 48_000.0).exp())
.clamp(0.0, 1.0)
};
if effect.frames != delay_frames as usize {
effect.reset();
}
effect.frames = delay_frames as usize;
effect.feedback = feedback;
effect.wet = wet;
effect.dry = dry;
}
},
}
}
fn release(&mut self, index: usize) {
let state = &mut self.states[index];
if state.release_age.is_none() {
let level = envelope(state, &self.exponential);
state.release_age = Some(state.age);
state.release_order = Some(self.note_serial);
self.note_serial = self.note_serial.wrapping_add(1);
state.release_level = level;
}
}
fn event(&mut self, group: usize, event: MusicEvent, zone: usize) {
let frame = self.groups[group].frame;
let track = event.track as usize;
if event.kind == 1 {
let bank = self.groups[group].bank.as_ref().unwrap();
let inst = bank.instruments[zone];
let cents = (event.c - inst.root as i32) as f64 * 100.0 + inst.tuning_cents as f64;
let range = group * 12..group * 12 + 12;
self.note_serial = self.note_serial.wrapping_add(1);
let legato = if event.flags & 1 != 0 {
range
.clone()
.filter(|&i| {
self.voices[i].active
&& self.states[i].track == track
&& self.states[i].release_age.is_none()
})
.max_by_key(|&i| (self.states[i].born, i))
} else {
None
};
if let Some(index) = legato.filter(|&i| self.states[i].zone == zone) {
let state = &mut self.states[index];
state.glide.set(cents, frame, event.duration_frames, event.curve == 1);
state.note_id = event.a;
state.born = self.note_serial;
state.iteration = self.groups[group].iteration;
self.voices[index].volume = ((inst.gain as u16 * event.d as u16 + 127) / 255) as u8;
return;
}
let index = legato.unwrap_or_else(|| {
range.clone().find(|&i| !self.voices[i].active).unwrap_or_else(|| {
range
.min_by_key(|&i| {
(
self.states[i].release_age.is_none(),
self.states[i].release_order.unwrap_or(self.states[i].born),
i,
)
})
.unwrap()
})
});
// Music samples always have an owner in this group's retained bank.
self.voices[index] = Channel {
sample: Some(bank.samples[inst.sample as usize].clone()),
alive: None,
active: true,
pos: 0.0,
pitch: 1.0,
volume: ((inst.gain as u16 * event.d as u16 + 127) / 255) as u8,
pan: inst.pan,
loop_mode: if inst.looping { LoopMode::On } else { LoopMode::Off },
priority: 0,
};
self.states[index] = VoiceState {
inst,
track,
note_id: event.a,
iteration: self.groups[group].iteration,
born: self.note_serial,
glide: Ramp::constant(cents),
send: inst.send as f64 / 65535.0,
zone,
..VoiceState::default()
};
} else if event.kind == 2 {
for index in group * 12..group * 12 + 12 {
let state = &self.states[index];
if self.voices[index].active
&& state.track == track
&& state.note_id == event.a
&& state.iteration == self.groups[group].iteration
{
self.release(index);
}
}
} else {
let t = &mut self.groups[group].tracks[track];
let smooth = event.curve == 1;
match event.kind {
4 => t.gain.set(event.c as f64 / 65535.0, frame, event.duration_frames, smooth),
5 => t.pan.set(event.c as f64, frame, event.duration_frames, smooth),
6 => t.pitch.set(event.c as f64, frame, event.duration_frames, smooth),
7 => t.vibrato = Some((event.a, event.c as f64)),
8 => t.tremolo = Some((event.a, event.c as f64 / 65535.0)),
9 => t.send.set(event.c as f64 / 65535.0, frame, event.duration_frames, smooth),
_ => {} // Tempo/instrument selection were resolved during compilation.
}
}
}
fn sequence(&mut self, group: usize) {
if !self.groups[group].active || self.groups[group].paused {
return;
}
loop {
let g = &self.groups[group];
let bank = g.bank.as_ref().unwrap();
if let Some(event) = bank.events.get(g.cursor).filter(|e| e.time <= g.time) {
let event = *event;
self.groups[group].cursor += 1;
self.event(group, event.event, event.zone);
continue;
}
if g.time < bank.end_time {
break;
}
let loop_start = bank.loop_time.unwrap_or(0);
let loop_event = if bank.loop_time.is_some() { bank.loop_event } else { 0 };
let loop_length = bank.end_time - loop_start;
for index in group * 12..group * 12 + 12 {
self.release(index);
}
let g = &mut self.groups[group];
if !g.looping {
g.active = false;
break;
}
g.time -= loop_length;
g.cursor = loop_event;
g.iteration = g.iteration.wrapping_add(1);
}
}
pub fn mix(&mut self, buffer: &mut [f32]) {
let start = Instant::now();
buffer.fill(0.0);
if self.paused {
self.last_processing_time = start.elapsed();
return;
}
for frame in buffer.as_chunks_mut::<2>().0 {
// Invalidated resources stay owned until a reclamation packet is available.
for g in 0..2 {
if self.groups[g].bank.as_ref().is_some_and(|b| !b.alive.load(Ordering::Acquire)) {
self.groups[g].active = false;
for v in &mut self.voices[g * 12..g * 12 + 12] {
v.active = false;
}
self.effects[g].reset();
}
self.sequence(g);
}
let mut dry = [[0.0f32; 2]; 3];
let mut send = [[0.0f32; 2]; 3];
let mut active = 0;
for index in 0..MAX_CHANNELS {
let group = if index < 12 {
0
} else if index < 24 {
1
} else {
2
};
if group < 2 && self.groups[group].paused {
continue;
}
let voice = &mut self.voices[index];
if !voice.active {
continue;
}
if voice.alive.as_ref().is_some_and(|a| !a.load(Ordering::Acquire)) {
voice.active = false;
continue;
}
let Some(sample) = &voice.sample else {
continue;
};
let len = sample.frames_len();
if len == 0 {
voice.active = false;
continue;
}
active += 1;
let state = &mut self.states[index];
let mut volume = voice.volume as f64 / 255.0;
let mut pan = voice.pan as f64;
let mut pitch = voice.pitch;
let mut amount = state.send;
if group < 2 {
let g = &self.groups[group];
let track = g.tracks[state.track];
state.level = envelope(state, &self.exponential);
if state.release_age.is_some() && state.level <= 0.0 {
voice.active = false;
continue;
}
let vib = track
.vibrato
.unwrap_or((state.inst.vibrato_millihz, state.inst.vibrato_cents as f64));
let trem = track.tremolo.unwrap_or((
state.inst.tremolo_millihz,
state.inst.tremolo_depth as f64 / 65535.0,
));
let cents = state.glide.at(g.frame)
+ track.pitch.at(g.frame)
+ lfo(&self.sine, state.age, vib.0) * vib.1;
if cents != state.cached_cents {
state.pitch_factor = (cents / 1200.0).exp2();
state.cached_cents = cents;
}
pitch *= state.pitch_factor;
volume *= state.level
* track.gain.at(g.frame)
* (1.0 - trem.1 * (lfo(&self.sine, state.age, trem.0) + 1.0) * 0.5);
pan = (pan + track.pan.at(g.frame) - 128.0).clamp(0.0, 255.0);
amount = track.send.at(g.frame, state.send);
state.age = state.age.wrapping_add(1);
}
let channels = sample.channels as usize;
let (loop_start, end) = match (voice.loop_mode, sample.loop_start, sample.loop_end)
{
(LoopMode::On, Some(a), Some(b)) if a < b && b as usize <= len => {
(a as f64, b as f64)
}
_ => (0.0, len as f64),
};
let pos = voice.pos as usize;
if pos >= len {
voice.active = false;
continue;
}
let next = if voice.loop_mode == LoopMode::On && (pos + 1) as f64 >= end {
loop_start as usize
} else {
pos + 1
};
let frac = (voice.pos - pos as f64) as f32;
let value = |c: usize| {
let a = sample.data[pos * channels + c] as f32 / 32768.0;
let b =
sample.data.get(next * channels + c).copied().unwrap_or(0) as f32 / 32768.0;
a + (b - a) * frac
};
if volume != 0.0 {
let normalized_pan =
if pan <= 128.0 { pan / 256.0 } else { 0.5 + (pan - 128.0) / 254.0 };
let gains = if channels == 1 {
[(1.0 - normalized_pan).sqrt(), normalized_pan.sqrt()]
} else {
[
if pan <= 128.0 { 1.0 } else { (255.0 - pan) / 127.0 },
if pan >= 128.0 { 1.0 } else { pan / 128.0 },
]
};
for c in 0..2 {
let v =
value(if channels == 1 { 0 } else { c }) * (volume * gains[c]) as f32;
dry[group][c] += v;
send[group][c] += v * amount as f32;
}
}
let ratio = sample.sample_rate as f64 / 48_000.0;
if ratio > 0.0 {
if pitch >= (end - voice.pos) / ratio {
if voice.loop_mode == LoopMode::Off {
voice.active = false;
} else {
let length = end - loop_start;
let step = (pitch % (length / ratio)) * ratio;
voice.pos =
loop_start + (voice.pos - loop_start + step).rem_euclid(length);
if voice.pos >= end {
voice.pos = loop_start;
}
}
} else {
voice.pos += pitch * ratio;
}
}
}
self.diagnostics.active_voices = active;
self.diagnostics.maximum_voices = self.diagnostics.maximum_voices.max(active);
for group in 0..3 {
if group < 2 && self.groups[group].paused {
continue;
}
let gain = if group < 2 {
self.groups[group].gain.at(self.groups[group].frame) as f32 * self.bus[0]
} else {
self.bus[1] * self.sfx_gain
};
let values = self.effects[group].process(dry[group], send[group]);
for c in 0..2 {
frame[c] += values[c] * gain;
}
}
for value in frame {
*value = (*value * self.bus[2]).clamp(-1.0, 1.0);
}
for group in &mut self.groups {
if !group.paused
&& let Some(bank) = &group.bank
{
group.frame = group.frame.wrapping_add(1);
if group.active {
group.time += bank.denominator;
}
if group.stop_after_fade && group.gain.done(group.frame) {
group.active = false;
}
}
}
// Crossfade completion silences/relinquishes notes; bank reclamation is deferred.
for g in 0..2 {
if self.groups[g].stop_after_fade && !self.groups[g].active {
for voice in &mut self.voices[g * 12..g * 12 + 12] {
voice.active = false;
}
self.effects[g].reset();
}
}
self.diagnostics.frames += 1;
}
self.last_processing_time = start.elapsed();
self.diagnostics.last_render_us = self.last_processing_time.as_micros() as u64;
self.diagnostics.maximum_render_us =
self.diagnostics.maximum_render_us.max(self.diagnostics.last_render_us);
}
}
fn lfo(table: &[f64; 4097], age: u64, millihz: u32) -> f64 {
let phase = ((age % 48_000_000) * millihz as u64 % 48_000_000) as f64 / 48_000_000.0 * 4096.0;
let index = phase as usize;
table[index] + (table[index + 1] - table[index]) * (phase - index as f64)
}
fn micros_frames(value: u32) -> u64 {
(value as u64 * 48_000).div_ceil(1_000_000)
}
fn envelope(state: &VoiceState, table: &[f64; 1025]) -> f64 {
let curve = |x: f64| {
if state.inst.curve == 0 {
1.0 - x
} else {
let p = x.clamp(0.0, 1.0) * 1024.0;
let i = (p as usize).min(1023);
table[i] + (table[i + 1] - table[i]) * (p - i as f64)
}
};
if let Some(start) = state.release_age {
let duration = micros_frames(state.inst.release_us);
let elapsed = state.age - start;
return if duration == 0 || elapsed >= duration {
0.0
} else {
state.release_level * curve(elapsed as f64 / duration as f64)
};
}
let attack = micros_frames(state.inst.attack_us);
let decay = micros_frames(state.inst.decay_us);
if state.age < attack {
return state.age as f64 / attack as f64;
}
let sustain = state.inst.sustain as f64 / 65535.0;
if state.age - attack < decay {
sustain + (1.0 - sustain) * curve((state.age - attack) as f64 / decay as f64)
} else {
sustain
}
}
#[cfg(test)]
#[path = "engine_tests.rs"]
mod tests;
@@ -0,0 +1,508 @@
use super::*;
use crate::{Audio, MemoryBanks, SoundBankPoolAccess, SoundBankPoolInstaller};
use prometeu_hal::{AudioBridge, AudioOpStatus, music_bank::AUDIO_PPQ, sound_bank::SoundBank};
fn note(tick: u32, id: u32) -> MusicEvent {
MusicEvent { tick, kind: 1, a: id, c: 60, d: 255, ..Default::default() }
}
fn bank(events: Vec<MusicEvent>, inst: Instrument, tempo: u32, duration: u32) -> Arc<MusicBank> {
Arc::new(
MusicBank::compile(
"test".into(),
vec![Arc::new(
Sample::new(48_000, vec![1024, -2048, 1024, -2048])
.with_channels(2)
.unwrap()
.with_loop(0, 2),
)],
vec![inst],
events,
AUDIO_PPQ,
tempo,
duration,
None,
1,
)
.unwrap(),
)
}
fn pair() -> (Arc<MemoryBanks>, Audio, AudioMixer) {
let banks = Arc::new(MemoryBanks::new());
(banks.clone(), Audio::new(banks), AudioMixer::new())
}
fn publish(audio: &mut Audio, mixer: &mut AudioMixer) {
audio.finish_frame();
mixer.apply_delivery(audio.transport().try_take().unwrap());
}
fn install(banks: &MemoryBanks, slot: usize, events: Vec<MusicEvent>) {
banks.install_music_bank(
slot,
bank(events, Instrument { looping: true, ..Default::default() }, 20_000, 100_000),
);
}
#[test]
fn thirty_two_stereo_voices_have_fixed_group_ownership_and_safe_clipping() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, (0..12).map(|n| note(0, n)).collect());
assert_eq!(audio.music_play(0, 0, true), AudioOpStatus::Ok);
assert_eq!(audio.music_play(1, 0, true), AudioOpStatus::Ok);
let sample = Arc::new(Sample::new(48_000, vec![1024, -2048]));
// Stereo uses one cursor/slot; no channel consumes a second voice.
let sample = Arc::new(
Sample::new(48_000, sample.data.clone()).with_channels(2).unwrap().with_loop(0, 1),
);
for i in 0..8 {
assert_eq!(
audio.play_sample(sample.clone(), i, 255, 128, 1.0, 0, LoopMode::On),
AudioOpStatus::Ok
);
}
assert_eq!(audio.stop(8), AudioOpStatus::VoiceInvalid);
publish(&mut audio, &mut mixer);
let mut pcm = [0.0; 2];
mixer.mix(&mut pcm);
assert_eq!(mixer.voices.iter().filter(|v| v.active).count(), 32);
assert_eq!(mixer.diagnostics.maximum_voices, 32);
assert_eq!(pcm, [1.0, -1.0]);
audio.control(AudioControl::MusicStop { group: 0 });
publish(&mut audio, &mut mixer);
assert!(mixer.voices[..12].iter().all(|v| !v.active));
assert!(mixer.voices[12..].iter().all(|v| v.active));
for i in 0..8 {
audio.stop(i);
}
publish(&mut audio, &mut mixer);
assert!(mixer.voices[12..24].iter().all(|v| v.active));
}
#[test]
fn audio_time_does_not_wait_for_frame_sync_and_buffer_partition_is_invariant() {
let (banks, mut audio, mut a) = pair();
install(&banks, 0, vec![note(17, 1)]);
audio.music_play(0, 0, false);
publish(&mut audio, &mut a);
let mut b = AudioMixer::new();
let resident = banks.music_bank_slot(0).unwrap();
b.process_command(
AudioCommand::MusicPlay { group: 0, bank: resident, looping: false },
&mut Packet::new(),
);
let mut whole = vec![0.0; 4000];
a.mix(&mut whole);
let mut pieces = vec![0.0; 4000];
for piece in pieces.chunks_mut(14) {
b.mix(piece);
}
assert_eq!(whole, pieces);
assert!(whole[..34].iter().all(|&v| v == 0.0));
assert_ne!(whole[34], 0.0);
assert_eq!(a.groups[0].frame, 2000);
}
#[test]
fn fractional_tempo_changes_and_loop_remainder_have_no_cumulative_drift() {
let events = vec![MusicEvent { tick: 2, kind: 3, a: 30_001, ..Default::default() }, note(3, 1)];
let music = bank(events, Instrument::default(), 20_001, 5);
assert_eq!(music.events[1].time, 2 * 20_001u128 * 48_000 + 30_001u128 * 48_000);
let mut mixer = AudioMixer::new();
let end = music.end_time;
let den = music.denominator;
mixer.process_command(
AudioCommand::MusicPlay { group: 0, bank: music, looping: true },
&mut Packet::new(),
);
let n = 100_000;
mixer.mix(&mut vec![0.0; n * 2]);
// The first event of a loop is evaluated before the rendered frame.
assert_eq!(mixer.groups[0].iteration, ((n - 1) as u128 * den / end) as u64);
assert_eq!(mixer.groups[0].time, n as u128 * den - mixer.groups[0].iteration as u128 * end);
}
#[test]
fn music_allocator_uses_free_then_release_then_oldest_and_stale_off_does_not_stop_reuse() {
let (banks, mut audio, mut mixer) = pair();
let mut events: Vec<_> = (0..12).map(|n| note(0, n)).collect();
events.push(MusicEvent { tick: 1, kind: 2, a: 3, ..Default::default() });
events.push(note(2, 12));
events.push(MusicEvent { tick: 3, kind: 2, a: 3, ..Default::default() });
events.push(note(4, 13));
banks.install_music_bank(
0,
bank(
events,
Instrument { looping: true, release_us: 1_000_000, ..Default::default() },
20_000,
1000,
),
);
audio.music_play(0, 0, false);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 10]);
assert_eq!(mixer.states[3].note_id, 12);
assert_eq!(mixer.states[0].note_id, 13);
assert!(mixer.states[3].release_age.is_none());
}
#[test]
fn envelopes_have_exact_endpoints_and_note_off_releases() {
let mut state = VoiceState {
inst: Instrument {
attack_us: 1000,
decay_us: 1000,
sustain: 32768,
release_us: 1000,
curve: 0,
..Default::default()
},
..Default::default()
};
let mut mixer = AudioMixer::new();
for (age, value) in [(0, 0.0), (24, 0.5), (48, 1.0), (96, 32768.0 / 65535.0)] {
state.age = age;
assert!((envelope(&state, &mixer.exponential) - value).abs() < 1e-12);
}
state.release_age = Some(96);
state.release_level = 0.5;
for (age, value) in [(96, 0.5), (120, 0.25), (144, 0.0)] {
state.age = age;
assert!((envelope(&state, &mixer.exponential) - value).abs() < 1e-12);
}
for i in 0..10_000 {
let x = i as f64 / 10_000.0;
state.inst.curve = 1;
state.inst.release_us = 1_000_000;
state.release_age = Some(0);
state.release_level = 1.0;
state.age = (x * 48_000.0) as u64;
let x = state.age as f64 / 48_000.0;
let expected = ((-6.0 * x).exp() - (-6.0f64).exp()) / (1.0 - (-6.0f64).exp());
assert!((envelope(&state, &mixer.exponential) - expected).abs() < 1e-4);
}
let music = bank(
vec![note(0, 1), MusicEvent { tick: 2, kind: 2, a: 1, ..Default::default() }],
Instrument { looping: true, release_us: 1000, ..Default::default() },
20_000,
1000,
);
mixer.process_command(
AudioCommand::MusicPlay { group: 0, bank: music, looping: false },
&mut Packet::new(),
);
mixer.mix(&mut [0.0; 8]);
assert!(mixer.voices[0].active);
mixer.mix(&mut [0.0; 100]);
assert!(!mixer.voices[0].active);
}
#[test]
fn legato_retains_cursor_and_envelope_only_for_same_zone() {
let (banks, mut audio, mut mixer) = pair();
let mut legato = note(1, 2);
legato.flags = 1;
legato.c = 72;
legato.duration_frames = 10;
legato.curve = 1;
install(&banks, 0, vec![note(0, 1), legato]);
audio.music_play(0, 0, false);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 8]);
assert_eq!(mixer.voices[..12].iter().filter(|v| v.active).count(), 1);
assert_eq!(mixer.states[0].age, 4);
assert!((mixer.states[0].cached_cents - 124.8).abs() < 1e-10);
assert_eq!(mixer.states[0].note_id, 2);
assert_eq!(mixer.states[0].glide.to, 1200.0);
}
#[test]
fn pause_freezes_sequence_envelopes_fade_and_effect_timeline() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
audio.music_play(0, 0, true);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 6]);
audio.control(AudioControl::MusicPause { group: 0, paused: true });
publish(&mut audio, &mut mixer);
let before = (mixer.groups[0].time, mixer.states[0].age, mixer.effects[0].write);
let mut pcm = [1.0; 200];
mixer.mix(&mut pcm);
assert_eq!(pcm, [0.0; 200]);
assert_eq!(before, (mixer.groups[0].time, mixer.states[0].age, mixer.effects[0].write));
audio.control(AudioControl::MusicPause { group: 0, paused: false });
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 2]);
assert_eq!(mixer.states[0].age, before.1 + 1);
}
#[test]
fn crossfade_stops_outgoing_group_and_target_keeps_its_sequence() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
audio.music_play(0, 0, true);
audio.music_play(1, 0, true);
audio.control(AudioControl::MusicVolume { group: 1, gain: 0 });
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 10]);
audio.control(AudioControl::Crossfade { source: 0, target: 1, frames: 10, smooth: true });
publish(&mut audio, &mut mixer);
mixer.fill_buffer(&mut [0.0; 20]);
assert!(mixer.groups[0].bank.is_none());
assert_eq!(mixer.groups[1].frame, 15);
assert_eq!(mixer.groups[1].gain.at(15), 1.0);
assert!(mixer.voices[12].active);
}
#[test]
fn shared_delay_has_selective_sends_and_sfx_tails_survive_unload() {
let (banks, mut audio, mut mixer) = pair();
banks.install_sound_bank(
0,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![16384]))])),
);
audio.control(AudioControl::Effect {
group: 2,
cutoff_hz: 0,
delay_frames: 2,
feedback: 0.5,
wet: 1.0,
dry: 0.0,
});
audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::Off);
audio.control(AudioControl::SfxSend { voice: 0, gain: 255 });
publish(&mut audio, &mut mixer);
let mut first = [0.0; 2];
mixer.mix(&mut first);
assert_eq!(first, [0.0; 2]);
banks.unload_audio_bank(false, 0);
let mut tail = [0.0; 8];
mixer.fill_buffer(&mut tail);
assert_eq!(tail, [0.0, 0.0, 0.5, 0.0, 0.0, 0.0, 0.25, 0.0]);
}
#[test]
fn replacing_or_unloading_bank_invalidates_queued_play_and_only_its_resident_instance() {
let (banks, mut audio, mut mixer) = pair();
let source = Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![16384; 4]))]));
banks.install_sound_bank(0, source.clone());
banks.install_sound_bank(1, source);
audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::On);
audio.play(1, 0, 1, 255, 0, 1.0, 0, LoopMode::On);
audio.finish_frame();
banks.unload_audio_bank(false, 0);
mixer.apply_delivery(audio.transport().try_take().unwrap());
assert!(!mixer.voices[24].active);
assert!(mixer.voices[25].active);
install(&banks, 0, vec![note(0, 1)]);
audio.music_play(0, 0, true);
audio.music_play(1, 0, true);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 2]);
banks.unload_audio_bank(true, 0);
mixer.fill_buffer(&mut [0.0; 2]);
assert!(mixer.voices[..24].iter().all(|v| !v.active));
assert!(mixer.groups.iter().all(|g| g.bank.is_none()));
assert!(mixer.voices[25].active);
}
#[test]
fn stealing_respects_release_order_and_serialized_onsets_within_one_frame() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, (0..14).map(|n| note(0, n)).collect());
audio.music_play(0, 0, false);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 2]);
assert_eq!(mixer.states[0].note_id, 12);
assert_eq!(mixer.states[1].note_id, 13);
let mut events: Vec<_> = (0..12).map(|n| note(0, n)).collect();
events.push(MusicEvent { tick: 1, kind: 2, a: 4, ..Default::default() });
events.push(MusicEvent { tick: 2, kind: 2, a: 2, ..Default::default() });
events.push(note(3, 20));
banks.install_music_bank(
0,
bank(
events,
Instrument { looping: true, release_us: 1_000_000, ..Default::default() },
20000,
1000,
),
);
audio.music_play(0, 0, false);
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 8]);
assert_eq!(mixer.states[4].note_id, 20);
assert!(mixer.states[2].release_age.is_some());
}
#[test]
fn incompatible_legato_retriggers_the_same_voice_with_no_hidden_polyphony() {
let sample = Arc::new(Sample::new(48000, vec![1000; 8]).with_loop(0, 8));
let mut legato = note(2, 2);
legato.flags = 1;
legato.c = 72;
let music = MusicBank::compile(
"zones".into(),
vec![sample.clone(), sample],
vec![
Instrument { low: 0, high: 63, looping: true, ..Default::default() },
Instrument { low: 64, high: 127, sample: 1, looping: true, ..Default::default() },
],
vec![note(0, 1), legato],
960,
20000,
1000,
None,
1,
)
.unwrap();
let mut mixer = AudioMixer::new();
mixer.process_command(
AudioCommand::MusicPlay { group: 0, bank: Arc::new(music), looping: false },
&mut Packet::new(),
);
mixer.mix(&mut [0.0; 6]);
assert_eq!(mixer.voices[..12].iter().filter(|v| v.active).count(), 1);
assert_eq!(mixer.states[0].age, 1);
assert_eq!(mixer.states[0].zone, 1);
assert_eq!(mixer.states[0].note_id, 2);
}
#[test]
fn parameter_ramps_lfos_and_send_override_use_the_current_audio_value() {
let mut send = SendRamp::default();
assert_eq!(send.at(0, 0.8), 0.8);
send.set(0.0, 0, 100, false);
assert_eq!(send.at(50, 0.8), 0.4);
send.set(1.0, 50, 100, false);
assert_eq!(send.at(50, 0.8), 0.4);
assert!((send.at(100, 0.8) - 0.7).abs() < 1e-12);
assert_eq!(send.at(150, 0.8), 1.0);
let events = vec![
note(0, 1),
MusicEvent { kind: 4, c: 0, duration_frames: 480, ..Default::default() },
MusicEvent { kind: 5, c: 255, duration_frames: 480, ..Default::default() },
MusicEvent { kind: 6, c: 1200, duration_frames: 480, ..Default::default() },
MusicEvent { kind: 7, a: 100000, c: 1200, ..Default::default() },
MusicEvent { kind: 8, a: 100000, c: 65535, ..Default::default() },
];
let mut mixer = AudioMixer::new();
mixer.process_command(
AudioCommand::MusicPlay {
group: 0,
bank: bank(events, Instrument { looping: true, ..Default::default() }, 20000, 1000),
looping: false,
},
&mut Packet::new(),
);
let mut pcm = [0.0; 962];
mixer.mix(&mut pcm);
assert_eq!(&pcm[..2], &[1.0 / 64.0, -1.0 / 32.0]);
assert!(pcm[240].abs() < 1e-8 && pcm[241].abs() < 1e-8);
assert_eq!(&pcm[960..], &[0.0, 0.0]);
assert!(mixer.voices[0].active);
assert_eq!(mixer.groups[0].tracks[0].gain.at(240), 0.5);
assert_eq!(mixer.groups[0].tracks[0].pan.at(240), 191.5);
assert_eq!(mixer.groups[0].tracks[0].pitch.at(240), 600.0);
let mut ramp = Ramp::constant(0.0);
ramp.set(1.0, 0, 100, true);
assert_eq!(ramp.at(0), 0.0);
assert_eq!(ramp.at(50), 0.5);
assert_eq!(ramp.at(100), 1.0);
let endpoint = 1.0 / 65535.0;
ramp.set(endpoint, 100, 100, false);
assert_eq!(ramp.at(200), endpoint);
assert_eq!(ramp.at(1000), endpoint);
}
#[test]
fn music_sfx_and_master_gains_remain_independent_of_group_gain() {
let (_, mut audio, mut mixer) = pair();
audio.play_sample(
Arc::new(Sample::new(48000, vec![16384; 4])),
0,
255,
0,
1.0,
0,
LoopMode::On,
);
audio.control(AudioControl::GroupVolume { group: 2, gain: 128 });
audio.control(AudioControl::BusVolume { bus: 1, gain: 128 });
audio.control(AudioControl::BusVolume { bus: 2, gain: 128 });
publish(&mut audio, &mut mixer);
let mut pcm = [0.0; 2];
mixer.mix(&mut pcm);
assert!((pcm[0] - 0.5 * (128.0f32 / 255.0).powi(3)).abs() < 1e-7);
assert_eq!(pcm[1], 0.0);
}
#[test]
fn invalidating_one_music_slot_clears_only_its_effect_history() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
install(&banks, 1, vec![note(0, 1)]);
audio.music_play(0, 0, true);
audio.music_play(1, 1, true);
for group in 0..2 {
audio.control(AudioControl::Effect {
group,
cutoff_hz: 6000,
delay_frames: 48,
feedback: 0.5,
wet: 0.3,
dry: 0.7,
});
}
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 100]);
banks.unload_audio_bank(true, 0);
mixer.retire_inactive(&mut Packet::new());
assert_eq!(mixer.effects[0].history, 0);
assert_eq!(mixer.effects[1].history, 50);
assert!(mixer.voices[12].active);
}
#[test]
fn crossfade_with_absent_target_does_not_silence_the_active_source() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
audio.music_play(0, 0, true);
audio.control(AudioControl::Crossfade { source: 0, target: 1, frames: 0, smooth: false });
publish(&mut audio, &mut mixer);
mixer.mix(&mut [0.0; 2]);
assert!(mixer.groups[0].active);
assert_eq!(mixer.groups[0].gain.at(1), 1.0);
}
#[test]
fn resident_memory_diagnostics_deduplicate_shared_pcm_across_all_slots() {
let banks = MemoryBanks::new();
let sample = Arc::new(Sample::new(48000, vec![1, 2, 3, 4]));
let source = Arc::new(SoundBank::new(vec![sample]));
for slot in 0..16 {
banks.install_sound_bank(slot, source.clone());
banks.install_music_bank(slot, bank(vec![note(0, 1)], Instrument::default(), 20000, 1000));
}
let snapshot = banks.audio_memory();
assert_eq!(snapshot.banks.len(), 32);
assert_eq!(snapshot.unique_pcm_bytes, 8 + 16 * 8);
assert!(snapshot.metadata_bytes > 0);
assert_eq!(
snapshot.total_accounted_bytes,
snapshot.allocated_pcm_bytes + snapshot.metadata_bytes
);
}
#[test]
fn group_configuration_survives_play_stop_and_replacement_but_not_session_reset() {
let (banks, mut audio, mut mixer) = pair();
install(&banks, 0, vec![note(0, 1)]);
audio.control(AudioControl::MusicVolume { group: 0, gain: 0 });
audio.music_play(0, 0, true);
publish(&mut audio, &mut mixer);
let mut pcm = [1.0; 2];
mixer.mix(&mut pcm);
assert_eq!(pcm, [0.0; 2]);
assert_eq!(mixer.groups[0].gain.at(0), 0.0);
audio.control(AudioControl::Effect {
group: 0,
cutoff_hz: 1000,
delay_frames: 48,
feedback: 0.5,
wet: 0.5,
dry: 0.5,
});
audio.control(AudioControl::MusicStop { group: 0 });
audio.music_play(0, 0, true);
publish(&mut audio, &mut mixer);
assert_eq!(mixer.groups[0].gain.at(0), 0.0);
assert_eq!(mixer.effects[0].frames, 48);
audio.reset();
mixer.apply_delivery(audio.transport().try_take().unwrap());
assert_eq!(mixer.groups[0].gain.at(0), 1.0);
assert_eq!(mixer.effects[0].frames, 0);
assert_eq!(mixer.effects[0].coefficient, 1.0);
assert_eq!(mixer.effects[0].wet, 0.0);
assert_eq!(mixer.effects[0].dry, 1.0);
}
@@ -123,6 +123,7 @@ mod reuse_tests {
let allocation = batch.as_ptr(); let allocation = batch.as_ptr();
batch.push(AudioCommand::Play { batch.push(AudioCommand::Play {
sample, sample,
alive: None,
voice_id: 0, voice_id: 0,
volume: 255, volume: 255,
pan: 0, pan: 0,
@@ -664,7 +664,7 @@ mod tests {
assert!(frame_composer.bind_scene(0)); assert!(frame_composer.bind_scene(0));
let cache = frame_composer.cache().expect("cache should exist for bound scene"); let cache = frame_composer.cache().expect("cache should exist for bound scene");
assert_eq!((cache.width(), cache.height()), (65, 38)); assert_eq!((cache.width(), cache.height()), (85, 49));
} }
#[test] #[test]
@@ -43,6 +43,8 @@ pub struct Gfx {
front: Vec<u32>, front: Vec<u32>,
/// Back buffer: the working buffer where canonical game frames are composed /// Back buffer: the working buffer where canonical game frames are composed
back: Vec<u32>, back: Vec<u32>,
/// Complete local framebuffer publications, including native Hub/Shell output.
publication_count: u64,
/// Shared access to graphical memory banks (tiles and palettes). /// Shared access to graphical memory banks (tiles and palettes).
pub glyph_banks: Arc<dyn GlyphBankPoolAccess>, pub glyph_banks: Arc<dyn GlyphBankPoolAccess>,
@@ -321,6 +323,7 @@ impl Gfx {
h, h,
front: vec![0; len], front: vec![0; len],
back: vec![0; len], back: vec![0; len],
publication_count: 0,
glyph_banks, glyph_banks,
sprites: [EMPTY_SPRITE; 512], sprites: [EMPTY_SPRITE; 512],
sprite_count: 0, sprite_count: 0,
@@ -570,6 +573,11 @@ impl Gfx {
/// Typically called by the Host when it's time to display the finished frame. /// Typically called by the Host when it's time to display the finished frame.
pub fn present(&mut self) { pub fn present(&mut self) {
std::mem::swap(&mut self.front, &mut self.back); std::mem::swap(&mut self.front, &mut self.back);
self.publication_count = self.publication_count.wrapping_add(1);
}
pub fn publication_count(&self) -> u64 {
self.publication_count
} }
pub fn load_frame_sprites(&mut self, sprites: &[Sprite]) { pub fn load_frame_sprites(&mut self, sprites: &[Sprite]) {
@@ -28,7 +28,7 @@ use std::sync::Arc;
/// for easier testing and different host implementations (Desktop, Web, etc.). /// for easier testing and different host implementations (Desktop, Web, etc.).
/// ///
/// ### Console Specifications: /// ### Console Specifications:
/// - **Resolution**: 480x270 (16:9 Aspect Ratio). /// - **Resolution**: 640x360 (16:9 Aspect Ratio).
/// - **Color Format**: RGBA8888. /// - **Color Format**: RGBA8888.
/// - **Audio**: Stereo, Command-based mixing. /// - **Audio**: Stereo, Command-based mixing.
/// - **Input**: 12-button Digital Gamepad + Absolute Touch/Mouse. /// - **Input**: 12-button Digital Gamepad + Absolute Touch/Mouse.
@@ -201,9 +201,9 @@ impl RuntimePlatform for Hardware {
impl Hardware { impl Hardware {
/// Internal hardware width in pixels. /// Internal hardware width in pixels.
pub const W: usize = 480; pub const W: usize = prometeu_hal::graphics_contract::WIDTH;
/// Internal hardware height in pixels. /// Internal hardware height in pixels.
pub const H: usize = 270; pub const H: usize = prometeu_hal::graphics_contract::HEIGHT;
/// Creates a fresh hardware instance with default settings. /// Creates a fresh hardware instance with default settings.
pub fn new(wall_clock: Arc<dyn WallClock>) -> Self { pub fn new(wall_clock: Arc<dyn WallClock>) -> Self {
@@ -5,12 +5,15 @@ mod gfx;
pub mod hardware; pub mod hardware;
mod local_render_backend; mod local_render_backend;
mod memory_banks; mod memory_banks;
#[cfg(test)]
mod native_graphics_tests;
mod pad; mod pad;
mod test_platform; mod test_platform;
mod touch; mod touch;
mod wall_clock; mod wall_clock;
pub use crate::asset::AssetManager; pub use crate::asset::AssetManager;
pub use crate::audio::bank_format;
pub use crate::audio::{ pub use crate::audio::{
Audio, AudioCommand, AudioDelivery, AudioTransport, Channel, MAX_CHANNELS, Audio, AudioCommand, AudioDelivery, AudioTransport, Channel, MAX_CHANNELS,
MAX_COMMANDS_PER_FRAME, OUTPUT_SAMPLE_RATE, MAX_COMMANDS_PER_FRAME, OUTPUT_SAMPLE_RATE,
@@ -27,3 +30,5 @@ pub use crate::test_platform::TestPlatform;
pub use crate::wall_clock::ControlledWallClock; pub use crate::wall_clock::ControlledWallClock;
pub mod memcard; pub mod memcard;
pub use crate::audio::{SFX_CHANNELS, SFX_START, engine};
+14 -3
View File
@@ -13,7 +13,8 @@ fn io_error(e: std::io::Error) -> Error {
use std::io::ErrorKind as K; use std::io::ErrorKind as K;
match e.kind() { match e.kind() {
K::NotFound => Error::Unavailable, K::NotFound => Error::Unavailable,
K::PermissionDenied => Error::ReadOnly, K::PermissionDenied => Error::AccessDenied,
K::AlreadyExists => Error::AlreadyExists,
K::StorageFull => Error::NoSpace, K::StorageFull => Error::NoSpace,
K::InvalidInput | K::UnexpectedEof => Error::InvalidRange, K::InvalidInput | K::UnexpectedEof => Error::InvalidRange,
K::Unsupported => Error::Unsupported, K::Unsupported => Error::Unsupported,
@@ -21,8 +22,15 @@ fn io_error(e: std::io::Error) -> Error {
} }
} }
impl FileMemcard { impl FileMemcard {
fn lock(file: &File) -> Result<(), Error> {
file.try_lock().map_err(|error| match error {
std::fs::TryLockError::WouldBlock => Error::Busy,
std::fs::TryLockError::Error(error) => io_error(error),
})
}
pub fn open(path: &Path, read_only: bool) -> Result<Self, Error> { 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 file = OpenOptions::new().read(true).write(!read_only).open(path).map_err(io_error)?;
Self::lock(&file)?;
let length = file.metadata().map_err(io_error)?.len(); let length = file.metadata().map_err(io_error)?.len();
Ok(Self { file, length, read_only }) Ok(Self { file, length, read_only })
} }
@@ -47,7 +55,9 @@ impl FileMemcard {
.create_new(true) .create_new(true)
.open(&temporary) .open(&temporary)
.map_err(io_error)?; .map_err(io_error)?;
let mut published = false;
let result = (|| { let result = (|| {
Self::lock(&file)?;
let mut card = Self { file, length, read_only: false }; let mut card = Self { file, length, read_only: false };
let zeros = [0u8; 65_536]; let zeros = [0u8; 65_536];
let mut offset = 0; let mut offset = 0;
@@ -64,6 +74,7 @@ impl FileMemcard {
card.sync()?; card.sync()?;
// hard_link publishes without replacing a user file; parent sync makes the name durable. // hard_link publishes without replacing a user file; parent sync makes the name durable.
std::fs::hard_link(&temporary, path).map_err(io_error)?; std::fs::hard_link(&temporary, path).map_err(io_error)?;
published = true;
File::open(parent).and_then(|f| f.sync_all()).map_err(io_error)?; File::open(parent).and_then(|f| f.sync_all()).map_err(io_error)?;
Ok(card) Ok(card)
})(); })();
@@ -71,10 +82,10 @@ impl FileMemcard {
std::fs::remove_file(&temporary).and_then(|()| File::open(parent)?.sync_all()); std::fs::remove_file(&temporary).and_then(|()| File::open(parent)?.sync_all());
match result { match result {
Ok(card) => { Ok(card) => {
cleanup.map_err(io_error)?; cleanup.map_err(|_| Error::Indeterminate)?;
Ok(card) Ok(card)
} }
Err(e) => Err(e), Err(e) => Err(if published { Error::Indeterminate } else { e }),
} }
} }
#[cfg(not(unix))] #[cfg(not(unix))]
@@ -7,6 +7,7 @@
//! the render read surface. //! the render read surface.
use prometeu_hal::glyph_bank::GlyphBank; use prometeu_hal::glyph_bank::GlyphBank;
use prometeu_hal::music_bank::MusicBank;
use prometeu_hal::render_resources::RenderResourceAccess as HalRenderResourceAccess; use prometeu_hal::render_resources::RenderResourceAccess as HalRenderResourceAccess;
use prometeu_hal::scene_bank::SceneBank; use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::sound_bank::SoundBank; use prometeu_hal::sound_bank::SoundBank;
@@ -30,6 +31,7 @@ pub trait GlyphBankPoolInstaller: Send + Sync {
/// Non-generic interface for peripherals to access sound banks. /// Non-generic interface for peripherals to access sound banks.
pub trait SoundBankPoolAccess: Send + Sync { pub trait SoundBankPoolAccess: Send + Sync {
fn music_bank_slot(&self, slot: usize) -> Option<Arc<MusicBank>>;
/// Returns a reference to the resident SoundBank in the specified slot, if any. /// Returns a reference to the resident SoundBank in the specified slot, if any.
fn sound_bank_slot(&self, slot: usize) -> Option<Arc<SoundBank>>; fn sound_bank_slot(&self, slot: usize) -> Option<Arc<SoundBank>>;
/// Returns the total number of slots available in this bank. /// Returns the total number of slots available in this bank.
@@ -38,6 +40,9 @@ pub trait SoundBankPoolAccess: Send + Sync {
/// Non-generic interface for the AssetManager to install sound banks. /// Non-generic interface for the AssetManager to install sound banks.
pub trait SoundBankPoolInstaller: Send + Sync { pub trait SoundBankPoolInstaller: Send + Sync {
fn install_music_bank(&self, slot: usize, bank: Arc<MusicBank>);
fn clear_music_banks(&self);
fn unload_audio_bank(&self, music: bool, slot: usize);
/// Atomically swaps the resident SoundBank in the specified slot. /// Atomically swaps the resident SoundBank in the specified slot.
fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>); fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>);
/// Clears all resident SoundBank slots. /// Clears all resident SoundBank slots.
@@ -68,6 +73,7 @@ pub trait SceneBankPoolInstaller: Send + Sync {
pub struct MemoryBanks { pub struct MemoryBanks {
glyph_bank_pool: Arc<RwLock<[Option<Arc<GlyphBank>>; 16]>>, glyph_bank_pool: Arc<RwLock<[Option<Arc<GlyphBank>>; 16]>>,
sound_bank_pool: Arc<RwLock<[Option<Arc<SoundBank>>; 16]>>, sound_bank_pool: Arc<RwLock<[Option<Arc<SoundBank>>; 16]>>,
music_bank_pool: Arc<RwLock<[Option<Arc<MusicBank>>; 16]>>,
scene_bank_pool: Arc<RwLock<[Option<Arc<SceneBank>>; 16]>>, scene_bank_pool: Arc<RwLock<[Option<Arc<SceneBank>>; 16]>>,
} }
@@ -83,6 +89,7 @@ impl MemoryBanks {
Self { Self {
glyph_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), glyph_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
sound_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), sound_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
music_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
scene_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))), scene_bank_pool: Arc::new(RwLock::new(std::array::from_fn(|_| None))),
} }
} }
@@ -113,6 +120,9 @@ impl GlyphBankPoolInstaller for MemoryBanks {
} }
impl SoundBankPoolAccess for MemoryBanks { impl SoundBankPoolAccess for MemoryBanks {
fn music_bank_slot(&self, slot: usize) -> Option<Arc<MusicBank>> {
self.music_bank_pool.read().unwrap().get(slot).and_then(Clone::clone)
}
fn sound_bank_slot(&self, slot: usize) -> Option<Arc<SoundBank>> { fn sound_bank_slot(&self, slot: usize) -> Option<Arc<SoundBank>> {
let pool = self.sound_bank_pool.read().unwrap(); let pool = self.sound_bank_pool.read().unwrap();
pool.get(slot).and_then(|s| s.as_ref().map(Arc::clone)) pool.get(slot).and_then(|s| s.as_ref().map(Arc::clone))
@@ -124,15 +134,61 @@ impl SoundBankPoolAccess for MemoryBanks {
} }
impl SoundBankPoolInstaller for MemoryBanks { impl SoundBankPoolInstaller for MemoryBanks {
fn install_music_bank(&self, slot: usize, bank: Arc<MusicBank>) {
if slot >= 16 {
return;
}
let prepared = Arc::new(bank.resident_copy());
let mut pool = self.music_bank_pool.write().unwrap();
if let Some(target) = pool.get_mut(slot) {
if let Some(old) = target.take() {
old.invalidate();
}
*target = Some(prepared);
}
}
fn clear_music_banks(&self) {
let mut pool = self.music_bank_pool.write().unwrap();
for bank in pool.iter_mut() {
if let Some(old) = bank.take() {
old.invalidate();
}
}
}
fn unload_audio_bank(&self, music: bool, slot: usize) {
if music {
if let Some(bank) =
self.music_bank_pool.write().unwrap().get_mut(slot).and_then(Option::take)
{
bank.invalidate();
}
} else if let Some(bank) =
self.sound_bank_pool.write().unwrap().get_mut(slot).and_then(Option::take)
{
bank.invalidate();
}
}
fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>) { fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>) {
if slot >= 16 {
return;
}
let prepared = Arc::new(bank.resident_copy());
let mut pool = self.sound_bank_pool.write().unwrap(); let mut pool = self.sound_bank_pool.write().unwrap();
if slot < 16 { if slot < 16 {
pool[slot] = Some(bank); if let Some(old) = pool[slot].take() {
old.invalidate();
}
pool[slot] = Some(prepared);
} }
} }
fn clear_sound_banks(&self) { fn clear_sound_banks(&self) {
self.sound_bank_pool.write().unwrap().fill(None); let mut pool = self.sound_bank_pool.write().unwrap();
for bank in pool.iter_mut() {
if let Some(old) = bank.take() {
old.invalidate();
}
}
} }
} }
@@ -246,3 +302,84 @@ mod tests {
assert_eq!(HalRenderResourceAccess::scene_bank_count(&banks), 16); assert_eq!(HalRenderResourceAccess::scene_bank_count(&banks), 16);
} }
} }
/// Owner-thread diagnostics: canonical bank costs and unique PCM allocation costs
/// are separate, so loading the same asset in two slots does not double-count RAM.
#[derive(Debug, Clone)]
pub struct AudioSlotMemory {
pub music: bool,
pub slot: usize,
pub name: String,
pub metrics: prometeu_hal::sound_bank::AudioBankMetrics,
}
#[derive(Debug, Default)]
pub struct AudioMemorySnapshot {
pub banks: Vec<AudioSlotMemory>,
pub unique_pcm_bytes: usize,
pub allocated_pcm_bytes: usize,
/// Resident Rust structs/vector/string capacities; excludes allocator/Arc headers and host caches.
pub metadata_bytes: usize,
pub total_accounted_bytes: usize,
}
impl MemoryBanks {
pub fn audio_memory(&self) -> AudioMemorySnapshot {
let mut snapshot = AudioMemorySnapshot::default();
let mut seen = std::collections::HashSet::new();
let mut metadata = 0usize;
let mut vectors = std::collections::HashSet::new();
let mut add =
|music, slot, name: String, metrics, samples: &[Arc<prometeu_hal::sample::Sample>]| {
for sample in samples {
if seen.insert(Arc::as_ptr(sample)) {
metadata += std::mem::size_of::<prometeu_hal::sample::Sample>();
snapshot.unique_pcm_bytes += sample.data.len() * 2;
snapshot.allocated_pcm_bytes += sample.data.capacity() * 2;
}
}
snapshot.banks.push(AudioSlotMemory { music, slot, name, metrics });
};
for (slot, bank) in self.sound_bank_pool.read().unwrap().iter().enumerate() {
if let Some(b) = bank {
add(false, slot, b.name.clone(), b.metrics, &b.samples);
snapshot.metadata_bytes += std::mem::size_of::<SoundBank>()
+ b.name.capacity()
+ std::mem::size_of::<std::sync::atomic::AtomicBool>();
if vectors.insert(Arc::as_ptr(&b.samples) as usize) {
snapshot.metadata_bytes += std::mem::size_of::<
Vec<Arc<prometeu_hal::sample::Sample>>,
>() + b.samples.capacity()
* std::mem::size_of::<Arc<prometeu_hal::sample::Sample>>();
}
}
}
for (slot, bank) in self.music_bank_pool.read().unwrap().iter().enumerate() {
if let Some(b) = bank {
add(true, slot, b.name.clone(), b.metrics, &b.samples);
snapshot.metadata_bytes += std::mem::size_of::<MusicBank>()
+ b.name.capacity()
+ std::mem::size_of::<std::sync::atomic::AtomicBool>();
if vectors.insert(Arc::as_ptr(&b.samples) as usize) {
snapshot.metadata_bytes += std::mem::size_of::<
Vec<Arc<prometeu_hal::sample::Sample>>,
>() + b.samples.capacity()
* std::mem::size_of::<Arc<prometeu_hal::sample::Sample>>();
}
if vectors.insert(Arc::as_ptr(&b.instruments) as usize) {
snapshot.metadata_bytes += std::mem::size_of::<
Vec<prometeu_hal::music_bank::Instrument>,
>() + b.instruments.capacity()
* std::mem::size_of::<prometeu_hal::music_bank::Instrument>();
}
if vectors.insert(Arc::as_ptr(&b.events) as usize) {
snapshot.metadata_bytes += std::mem::size_of::<
Vec<prometeu_hal::music_bank::TimedMusicEvent>,
>() + b.events.capacity()
* std::mem::size_of::<prometeu_hal::music_bank::TimedMusicEvent>();
}
}
}
snapshot.metadata_bytes += metadata;
snapshot.total_accounted_bytes = snapshot.allocated_pcm_bytes + snapshot.metadata_bytes;
snapshot
}
}
@@ -0,0 +1,109 @@
use crate::{Gfx, GlyphBankPoolInstaller, MemoryBanks};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::glyph_bank::{GlyphBank, TileSize};
use prometeu_hal::graphics_contract::{FRAME_BYTES, HEIGHT, PIXELS, WIDTH};
use prometeu_hal::scene_bank::SceneBank;
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
use prometeu_hal::scene_viewport_cache::SceneViewportCache;
use prometeu_hal::scene_viewport_resolver::SceneViewportResolver;
use prometeu_hal::tile::Tile;
use prometeu_hal::tilemap::TileMap;
use std::sync::Arc;
#[test]
fn native_allocation_stride_corners_and_external_coordinates() {
let mut gfx = Gfx::new(WIDTH, HEIGHT, Arc::new(MemoryBanks::new()));
assert_eq!(gfx.publication_count(), 0);
gfx.clear(Color::BLACK);
for (x, y) in [(0, 0), (639, 0), (0, 359), (639, 359)] {
gfx.draw_pixel(x, y, Color::RED);
}
for (x, y) in [(-1, 0), (640, 359), (639, 360), (0, -1)] {
gfx.draw_pixel(x, y, Color::GREEN);
}
assert_eq!(gfx.publication_count(), 0, "drawing is not a complete publication");
gfx.present();
assert_eq!(gfx.publication_count(), 1);
let front = gfx.front_buffer();
assert_eq!(gfx.size(), (640, 360));
assert_eq!(front.len(), PIXELS);
assert_eq!(std::mem::size_of_val(front), FRAME_BYTES);
for index in [0, 639, 359 * WIDTH, PIXELS - 1] {
assert_eq!(front[index], Color::RED.raw());
}
assert_eq!(front.iter().filter(|&&p| p == Color::RED.raw()).count(), 4);
gfx.present();
assert_eq!(gfx.publication_count(), 2, "each complete swap is a publication");
}
#[test]
fn native_tile_edges_and_mixed_camera_layers_cover_every_corner() {
for sizes in [
[TileSize::Size8; 4],
[TileSize::Size16; 4],
[TileSize::Size32; 4],
[TileSize::Size8, TileSize::Size16, TileSize::Size32, TileSize::Size8],
] {
let banks = Arc::new(MemoryBanks::new());
let colors = [Color::RED, Color::GREEN, Color::BLUE, Color::WHITE];
for i in 0..4 {
let n = sizes[i] as usize;
let mut bank = GlyphBank::new(sizes[i], n, n);
bank.palettes[0][1] = colors[i];
bank.pixel_indices.fill(1);
banks.install_glyph_bank(i, Arc::new(bank));
}
let scene = SceneBank {
layers: std::array::from_fn(|i| SceneLayer {
active: true,
glyph_asset_id: i as i32,
tile_size: sizes[i],
parallax_factor: ParallaxFactor { x: 1.0, y: 1.0 },
tilemap: TileMap {
width: 160,
height: 120,
tiles: vec![
Tile {
active: true,
glyph: Glyph { glyph_id: 0, palette_id: 0 },
flip_x: true,
flip_y: true,
};
160 * 120
],
},
}),
};
let min = sizes.iter().map(|s| *s as usize).min().unwrap();
let (cw, ch) = (WIDTH.div_ceil(min) + 5, HEIGHT.div_ceil(min) + 4);
let mut cache = SceneViewportCache::new(&scene, cw, ch);
let mut resolver = SceneViewportResolver::new(
WIDTH as i32,
HEIGHT as i32,
cw,
ch,
min as i32 - 4,
min as i32 + 4,
);
let mut gfx = Gfx::new(WIDTH, HEIGHT, banks);
for (x, y) in [(0, 0), (1, 1), (7, 7), (15, 15), (31, 31), (400, 300), (2, 3)] {
let update = resolver.update(&scene, x, y);
for request in &update.copy_requests {
cache.move_layer_window_to(
request.layer_index,
request.cache_origin_tile_x,
request.cache_origin_tile_y,
);
}
cache.materialize_all_layers(&scene);
gfx.render_scene_from_cache(&cache, &update, &[0, 1, 2, 3]);
gfx.present();
// Every pixel, including rows 352..359, must be supplied by the last layer.
assert!(
gfx.front_buffer().iter().all(|&p| p == Color::WHITE.raw()),
"sizes={sizes:?}, camera=({x},{y})"
);
}
}
}
@@ -18,6 +18,8 @@ impl ControlledWallClock {
} }
/// Advance civil time explicitly, saturating at the largest timestamp. /// Advance civil time explicitly, saturating at the largest timestamp.
// `try_update` requires Rust 1.95; keep older stable CI toolchains compatible.
#[allow(deprecated)]
pub fn advance(&self, seconds: u64) { pub fn advance(&self, seconds: u64) {
// Harness control may retry on a concurrent update; reads remain a single load. // Harness control may retry on a concurrent update; reads remain a single load.
let _ = self.seconds.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| { let _ = self.seconds.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |current| {
@@ -609,7 +609,7 @@ mod tests {
} }
fn front_buffer_pixel(platform: &TestPlatform, x: i32, y: i32) -> u32 { fn front_buffer_pixel(platform: &TestPlatform, x: i32, y: i32) -> u32 {
const FRAMEBUFFER_WIDTH: usize = 480; const FRAMEBUFFER_WIDTH: usize = prometeu_hal::graphics_contract::WIDTH;
let index = x as usize + y as usize * FRAMEBUFFER_WIDTH; let index = x as usize + y as usize * FRAMEBUFFER_WIDTH;
platform.local_hardware().gfx.front_buffer()[index] platform.local_hardware().gfx.front_buffer()[index]
} }
@@ -1024,6 +1024,10 @@ mod tests {
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id, platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1) Some(1)
); );
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::MUSIC, index: 0 }).asset_id,
Some(201)
);
firmware.request_home_from_host(); firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
@@ -1038,6 +1042,10 @@ mod tests {
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id, platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1) Some(1)
); );
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::MUSIC, index: 0 }).asset_id,
Some(201)
);
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
let dummy_click = let dummy_click =
@@ -1051,6 +1059,10 @@ mod tests {
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id, platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
None None
); );
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::MUSIC, index: 0 }).asset_id,
None
);
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none()); assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none()); assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
@@ -1078,6 +1090,7 @@ mod tests {
); );
firmware.tick(&InputSignals::default(), &mut platform); firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
match &firmware.state { match &firmware.state {
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, dummy_task), FirmwareState::GameRunning(step) => assert_eq!(step.task_id, dummy_task),
@@ -1094,7 +1107,9 @@ mod tests {
assert_eq!(dummy_ownership.app_id, 2); assert_eq!(dummy_ownership.app_id, 2);
let front = platform.local_hardware().gfx.front_buffer(); let front = platform.local_hardware().gfx.front_buffer();
let center = 240 + 135 * 480; let center = prometeu_hal::graphics_contract::WIDTH / 2
+ (prometeu_hal::graphics_contract::HEIGHT / 2)
* prometeu_hal::graphics_contract::WIDTH;
assert_eq!(front[center], Color::GREEN.raw()); assert_eq!(front[center], Color::GREEN.raw());
firmware.request_home_from_host(); firmware.request_home_from_host();
@@ -1126,6 +1141,10 @@ mod tests {
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id, platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
Some(1) Some(1)
); );
assert_eq!(
platform.assets().slot_info(SlotRef { asset_type: BankType::MUSIC, index: 0 }).asset_id,
Some(201)
);
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some()); assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some());
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some()); assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some());
@@ -1512,8 +1531,12 @@ mod tests {
#[test] #[test]
fn shell_running_close_click_uses_lifecycle_and_returns_hub_home() { fn shell_running_close_click_uses_lifecycle_and_returns_hub_home() {
let (mut firmware, mut platform, _signals, task_id) = load_shell_running_firmware(); let (mut firmware, mut platform, _signals, task_id) = load_shell_running_firmware();
let close_signals = let close_signals = InputSignals {
InputSignals { f_signal: true, x_pos: 420, y_pos: 24, ..Default::default() }; f_signal: true,
x_pos: prometeu_hal::graphics_contract::WIDTH as i32 - 60,
y_pos: 24,
..Default::default()
};
firmware.tick(&close_signals, &mut platform); firmware.tick(&close_signals, &mut platform);
@@ -47,7 +47,12 @@ impl HubHomeStep {
let id = ctx.os.windows().add_window( let id = ctx.os.windows().add_window(
app.title().to_string(), app.title().to_string(),
WindowOwner::Task(task_id), WindowOwner::Task(task_id),
Rect { x: 40, y: 20, w: 400, h: 220 }, Rect {
x: 40,
y: 20,
w: prometeu_hal::graphics_contract::WIDTH as i32 - 80,
h: prometeu_hal::graphics_contract::HEIGHT as i32 - 50,
},
app.color(), app.color(),
); );
ctx.os.windows().set_focus(id); ctx.os.windows().set_focus(id);
@@ -48,6 +48,25 @@ impl LoadCartridgeStep {
pub fn needs_memcard_choice(&self) -> bool { pub fn needs_memcard_choice(&self) -> bool {
self.awaiting_memcard && !self.preparing_memcard self.awaiting_memcard && !self.preparing_memcard
} }
/// Typed host and UI admission share this single policy boundary.
pub fn choose_memcard(
&mut self,
os: &mut prometeu_system::SystemOS,
choice: prometeu_system::memcard::admission::Choice,
created_at: u64,
) -> prometeu_system::memcard::image::Result<()> {
if !self.needs_memcard_choice() {
return Err(prometeu_system::memcard::image::Error::InvalidState);
}
os.memcard().choose_for_game(
self.cartridge.app_id,
self.cartridge.memcard_slots.unwrap() as usize,
choice,
created_at,
)?;
self.preparing_memcard = true;
Ok(())
}
pub fn new_game_switch(cartridge: Cartridge) -> Self { pub fn new_game_switch(cartridge: Cartridge) -> Self {
Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) } Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) }
@@ -128,13 +147,8 @@ impl LoadCartridgeStep {
Choice::MemoryExisting Choice::MemoryExisting
}; };
let created_at = ctx.platform.wall_clock().utc_unix_seconds(); let created_at = ctx.platform.wall_clock().utc_unix_seconds();
match ctx.os.memcard().choose_for_game( match self.choose_memcard(ctx.os, choice, created_at) {
self.cartridge.app_id, Ok(()) => {}
self.cartridge.memcard_slots.unwrap() as usize,
choice,
created_at,
) {
Ok(()) => self.preparing_memcard = true,
Err(error) => self.memcard_message = Self::preparation_message(error), Err(error) => self.memcard_message = Self::preparation_message(error),
} }
} }
+15 -11
View File
@@ -8,6 +8,7 @@ pub type AssetId = i32;
pub enum BankType { pub enum BankType {
GLYPH, GLYPH,
SOUNDS, SOUNDS,
MUSIC,
SCENE, SCENE,
// TILEMAPS, // TILEMAPS,
// BLOBS, // BLOBS,
@@ -41,9 +42,8 @@ pub struct GlyphBankMetadata {
} }
#[derive(Debug, Clone, Deserialize, Serialize)] #[derive(Debug, Clone, Deserialize, Serialize)]
pub struct SoundBankMetadata { pub struct AudioBankMetadata {
pub sample_rate: u32, pub version: u16,
pub channels: u32,
} }
#[derive(Debug, Clone, Default, Deserialize, Serialize)] #[derive(Debug, Clone, Default, Deserialize, Serialize)]
@@ -73,15 +73,16 @@ impl AssetEntry {
.map_err(|e| format!("Invalid GLYPH metadata for asset {}: {}", self.asset_id, e)) .map_err(|e| format!("Invalid GLYPH metadata for asset {}: {}", self.asset_id, e))
} }
pub fn metadata_as_sound_bank(&self) -> Result<SoundBankMetadata, String> { pub fn metadata_as_audio_bank(&self) -> Result<AudioBankMetadata, String> {
if self.bank_type != BankType::SOUNDS { if !matches!(self.bank_type, BankType::SOUNDS | BankType::MUSIC) {
return Err(format!( return Err("asset is not an audio bank".into());
"Asset {} is not a SOUNDS bank (type: {:?})",
self.asset_id, self.bank_type
));
} }
serde_json::from_value(self.metadata.clone()) let metadata: AudioBankMetadata = serde_json::from_value(self.metadata.clone())
.map_err(|e| format!("Invalid SOUNDS metadata for asset {}: {}", self.asset_id, e)) .map_err(|e| format!("Invalid audio metadata: {e}"))?;
if metadata.version != 1 {
return Err("unsupported audio metadata version".into());
}
Ok(metadata)
} }
pub fn metadata_as_scene_bank(&self) -> Result<SceneBankMetadata, String> { pub fn metadata_as_scene_bank(&self) -> Result<SceneBankMetadata, String> {
@@ -189,6 +190,9 @@ pub struct SlotRef {
} }
impl SlotRef { impl SlotRef {
pub fn music(index: usize) -> Self {
Self { asset_type: BankType::MUSIC, index }
}
pub fn gfx(index: usize) -> Self { pub fn gfx(index: usize) -> Self {
Self { asset_type: BankType::GLYPH, index } Self { asset_type: BankType::GLYPH, index }
} }
@@ -6,6 +6,9 @@ use crate::asset::{
use crate::cartridge::AssetsPayloadSource; use crate::cartridge::AssetsPayloadSource;
pub trait AssetBridge { pub trait AssetBridge {
fn unload_audio(&self, _music: bool, _slot: usize) -> AssetOpStatus {
AssetOpStatus::InvalidState
}
/// Bind before cartridge preload/loading. Hosts supporting memcard must use /// Bind before cartridge preload/loading. Hosts supporting memcard must use
/// this same lane for assets; an unsupported bridge refuses the fast profile. /// this same lane for assets; an unsupported bridge refuses the fast profile.
fn bind_background_work( fn bind_background_work(
@@ -20,6 +20,20 @@ pub enum AudioOpStatus {
CommandLimit = 7, CommandLimit = 7,
} }
/// High-level commands are staged with the ordinary frame/lifecycle batch.
#[derive(Debug, Clone, Copy)]
pub enum AudioControl {
GroupVolume { group: usize, gain: u8 },
MusicStop { group: usize },
MusicPause { group: usize, paused: bool },
MusicVolume { group: usize, gain: u8 },
MusicFade { group: usize, gain: u8, frames: u32, smooth: bool },
Crossfade { source: usize, target: usize, frames: u32, smooth: bool },
BusVolume { bus: usize, gain: u8 },
Effect { group: usize, cutoff_hz: u32, delay_frames: u32, feedback: f32, wet: f32, dry: f32 },
SfxSend { voice: usize, gain: u8 },
}
pub trait AudioBridge { pub trait AudioBridge {
#[allow(clippy::too_many_arguments)] #[allow(clippy::too_many_arguments)]
fn play( fn play(
@@ -44,6 +58,8 @@ pub trait AudioBridge {
priority: u8, priority: u8,
loop_mode: LoopMode, loop_mode: LoopMode,
) -> AudioOpStatus; ) -> AudioOpStatus;
fn music_play(&mut self, group: usize, bank: usize, looping: bool) -> AudioOpStatus;
fn control(&mut self, control: AudioControl) -> AudioOpStatus;
fn stop(&mut self, voice_id: usize) -> AudioOpStatus; fn stop(&mut self, voice_id: usize) -> AudioOpStatus;
fn set_volume(&mut self, voice_id: usize, volume: u8) -> 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_pan(&mut self, voice_id: usize, pan: u8) -> AudioOpStatus;
@@ -0,0 +1,20 @@
//! Fixed machine graphics contract. Host surfaces never change these dimensions.
pub const WIDTH: usize = 640;
pub const HEIGHT: usize = 360;
pub const REFRESH_HZ: u32 = 60;
/// Canonical RGBA8888, with tightly packed native rows.
pub const BYTES_PER_PIXEL: usize = 4;
pub const PIXELS: usize = WIDTH * HEIGHT;
pub const STRIDE_PIXELS: usize = WIDTH;
pub const STRIDE_BYTES: usize = STRIDE_PIXELS * BYTES_PER_PIXEL;
pub const FRAME_BYTES: usize = STRIDE_BYTES * HEIGHT;
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn native_graphics_contract_is_fixed() {
assert_eq!((WIDTH, HEIGHT, REFRESH_HZ), (640, 360, 60));
assert_eq!((PIXELS, STRIDE_BYTES, FRAME_BYTES), (230_400, 2_560, 921_600));
}
}
+2
View File
@@ -12,11 +12,13 @@ pub mod debugger_protocol;
pub mod gfx_bridge; pub mod gfx_bridge;
pub mod glyph; pub mod glyph;
pub mod glyph_bank; pub mod glyph_bank;
pub mod graphics_contract;
pub mod host_context; pub mod host_context;
pub mod host_return; pub mod host_return;
pub mod input_signals; pub mod input_signals;
pub mod log; pub mod log;
pub mod memcard; pub mod memcard;
pub mod music_bank;
pub mod native_helpers; pub mod native_helpers;
pub mod native_interface; pub mod native_interface;
pub mod owned_frame; pub mod owned_frame;
@@ -57,6 +57,21 @@ impl LogService {
self.events.iter().filter(|e| e.seq > seq).cloned().collect() self.events.iter().filter(|e| e.seq > seq).cloned().collect()
} }
/// Non-destructive page in native sequence order. A null cursor includes zero.
pub fn get_page(&self, after: Option<u64>, limit: usize) -> Vec<LogEvent> {
self.events
.iter()
.filter(|event| after.is_none_or(|seq| event.seq > seq))
.take(limit)
.cloned()
.collect()
}
/// Retained bounds, independent of any reader's progress.
pub fn sequence_bounds(&self) -> (Option<u64>, Option<u64>) {
(self.events.front().map(|event| event.seq), self.last_seq())
}
pub fn last_seq(&self) -> Option<u64> { pub fn last_seq(&self) -> Option<u64> {
self.events.back().map(|e| e.seq) self.events.back().map(|e| e.seq)
} }
@@ -107,4 +122,35 @@ mod tests {
assert_eq!(after[0].msg, "Log 3"); assert_eq!(after[0].msg, "Log 3");
assert_eq!(after[1].msg, "Log 4"); assert_eq!(after[1].msg, "Log 4");
} }
#[test]
fn pages_preserve_zero_requery_and_retained_bounds() {
let mut service = LogService::new(3);
assert_eq!(service.sequence_bounds(), (None, None));
assert!(service.get_page(None, 2).is_empty());
for i in 0..3 {
service.log(i, i, LogLevel::Info, LogSource::Pos, 7, format!("{i}"));
}
assert_eq!(service.sequence_bounds(), (Some(0), Some(2)));
for _ in 0..2 {
let page = service.get_page(None, 2);
assert_eq!(page.iter().map(|event| event.seq).collect::<Vec<_>>(), vec![0, 1]);
}
assert_eq!(service.get_page(Some(1), 2)[0].seq, 2);
assert!(service.get_page(Some(2), 2).is_empty());
service.log(3, 3, LogLevel::Info, LogSource::Pos, 7, "next".into());
assert_eq!(service.sequence_bounds(), (Some(1), Some(3)));
assert_eq!(service.get_page(Some(2), 2)[0].seq, 3);
assert_eq!(service.get_page(None, 10).len(), 3);
}
#[test]
fn page_cursors_preserve_large_unsigned_sequences() {
let mut service = LogService::new(3);
service.next_seq = u64::MAX - 2;
service.log(0, 0, LogLevel::Info, LogSource::Pos, 0, "first".into());
service.log(0, 0, LogLevel::Info, LogSource::Pos, 0, "second".into());
assert_eq!(service.get_page(Some(u64::MAX - 2), 1)[0].seq, u64::MAX - 1);
assert!(service.get_page(Some(u64::MAX), 1).is_empty());
}
} }
@@ -6,6 +6,10 @@ pub enum MemcardIoError {
InvalidRange, InvalidRange,
NoSpace, NoSpace,
Unsupported, Unsupported,
Busy,
AccessDenied,
AlreadyExists,
Indeterminate,
IoError, IoError,
} }
@@ -0,0 +1,376 @@
//! Resident, self-contained music data. Construction/compilation is off the audio lane.
use crate::{sample::Sample, sound_bank::AudioBankMetrics};
use std::sync::{
Arc,
atomic::{AtomicBool, Ordering},
};
pub const AUDIO_PPQ: u32 = 960;
pub const AUDIO_RATE: u32 = 48_000;
pub const MAX_MUSIC_TRACKS: usize = 256;
pub const MAX_EVENTS_PER_FRAME: usize = 64;
#[derive(Debug, Clone, Copy)]
pub struct Instrument {
pub id: u16,
pub sample: u16,
pub low: u8,
pub high: u8,
pub root: u8,
pub looping: bool,
pub tuning_cents: i16,
pub pan: u8,
pub gain: u8,
pub attack_us: u32,
pub decay_us: u32,
pub sustain: u16,
pub release_us: u32,
pub vibrato_millihz: u32,
pub vibrato_cents: u16,
pub tremolo_depth: u16,
pub tremolo_millihz: u32,
pub send: u16,
pub curve: u8,
}
impl Default for Instrument {
fn default() -> Self {
Self {
id: 0,
sample: 0,
low: 0,
high: 127,
root: 60,
looping: false,
tuning_cents: 0,
pan: 128,
gain: 255,
attack_us: 0,
decay_us: 0,
sustain: u16::MAX,
release_us: 0,
vibrato_millihz: 0,
vibrato_cents: 0,
tremolo_depth: 0,
tremolo_millihz: 0,
send: 0,
curve: 1,
}
}
}
#[derive(Debug, Clone, Copy, Default)]
pub struct MusicEvent {
pub tick: u32,
pub kind: u8,
pub track: u8,
pub flags: u16,
pub a: u32,
pub b: u32,
pub c: i32,
pub d: i32,
pub duration_frames: u32,
pub curve: u32,
}
#[derive(Debug, Clone, Copy)]
pub struct TimedMusicEvent {
pub time: u128,
pub event: MusicEvent,
pub zone: usize,
}
#[derive(Debug)]
pub struct MusicBank {
pub name: String,
pub samples: Arc<Vec<Arc<Sample>>>,
pub instruments: Arc<Vec<Instrument>>,
pub events: Arc<Vec<TimedMusicEvent>>,
pub denominator: u128,
pub end_time: u128,
pub loop_time: Option<u128>,
pub loop_event: usize,
pub tracks: usize,
pub alive: Arc<AtomicBool>,
pub metrics: AudioBankMetrics,
}
impl MusicBank {
#[allow(clippy::too_many_arguments)]
pub fn compile(
name: String,
samples: Vec<Arc<Sample>>,
instruments: Vec<Instrument>,
events: Vec<MusicEvent>,
ppq: u32,
tempo: u32,
duration: u32,
loop_tick: Option<u32>,
tracks: usize,
) -> Result<Self, String> {
let mut compiler = MusicCompiler::new(
name,
samples,
instruments,
events,
ppq,
tempo,
duration,
loop_tick,
tracks,
)?;
loop {
if let Some(bank) = compiler.step()? {
return Ok(bank);
}
}
}
pub fn invalidate(&self) {
self.alive.store(false, Ordering::Release);
}
pub fn resident_copy(&self) -> Self {
Self {
name: self.name.clone(),
samples: self.samples.clone(),
instruments: self.instruments.clone(),
events: self.events.clone(),
denominator: self.denominator,
end_time: self.end_time,
loop_time: self.loop_time,
loop_event: self.loop_event,
tracks: self.tracks,
alive: Arc::new(AtomicBool::new(true)),
metrics: self.metrics,
}
}
}
/// Cooperative off-lane validation/clock compilation. At most 64 zones/events
/// per step; lookup is logarithmic and the loop-seam check is bounded by 65.
pub struct MusicCompiler {
name: Option<String>,
samples: Vec<Arc<Sample>>,
instruments: Vec<Instrument>,
source: std::vec::IntoIter<MusicEvent>,
compiled: Vec<TimedMusicEvent>,
zones: std::collections::BTreeMap<(u16, u8), usize>,
zone_cursor: usize,
ppq: u32,
tempo: u32,
duration: u32,
loop_tick: Option<u32>,
tracks: usize,
tick: u32,
time: u128,
loop_time: Option<u128>,
selected: [u32; MAX_MUSIC_TRACKS],
}
impl MusicCompiler {
#[allow(clippy::too_many_arguments)]
pub fn new(
name: String,
samples: Vec<Arc<Sample>>,
instruments: Vec<Instrument>,
events: Vec<MusicEvent>,
ppq: u32,
tempo: u32,
duration: u32,
loop_tick: Option<u32>,
tracks: usize,
) -> Result<Self, String> {
if ppq != AUDIO_PPQ
|| tempo == 0
|| duration == 0
|| tracks == 0
|| tracks > MAX_MUSIC_TRACKS
|| loop_tick.is_some_and(|t| t >= duration)
{
return Err("invalid music clock/tracks/loop".into());
}
let mut compiled = Vec::new();
compiled.try_reserve_exact(events.len()).map_err(|_| "music allocation failed")?;
Ok(Self {
name: Some(name),
samples,
instruments,
source: events.into_iter(),
compiled,
zones: std::collections::BTreeMap::new(),
zone_cursor: 0,
ppq,
tempo,
duration,
loop_tick,
tracks,
tick: 0,
time: 0,
loop_time: None,
selected: [u32::MAX; MAX_MUSIC_TRACKS],
})
}
pub fn step(&mut self) -> Result<Option<MusicBank>, String> {
let denominator = self.ppq as u128 * 1_000_000;
for _ in 0..64 {
if self.zone_cursor < self.instruments.len() {
let i = self.zone_cursor;
let inst = self.instruments[i];
if inst.low > inst.high
|| inst.high > 127
|| inst.root > 127
|| inst.curve > 1
|| inst.sample as usize >= self.samples.len()
|| inst.vibrato_millihz > 100_000
|| inst.tremolo_millihz > 100_000
|| inst.vibrato_cents > 2400
{
return Err("invalid instrument zone/modulation".into());
}
if inst.looping && self.samples[inst.sample as usize].loop_start.is_none() {
return Err("instrument requires a sample loop".into());
}
if self
.zones
.range((inst.id, 0)..=(inst.id, inst.high))
.next_back()
.is_some_and(|(_, j)| self.instruments[*j].high >= inst.low)
{
return Err("overlapping instrument zones".into());
}
self.zones.insert((inst.id, inst.low), i);
self.zone_cursor += 1;
continue;
}
let Some(event) = self.source.next() else {
return self.finish(denominator).map(Some);
};
if event.tick < self.tick
|| event.tick > self.duration
|| event.track as usize >= self.tracks
|| event.curve > 1
|| event.flags & !1 != 0
|| !(1..=10).contains(&event.kind)
{
return Err("invalid music event ordering/shape".into());
}
if let Some(t) = self.loop_tick.filter(|&t| t >= self.tick && t <= event.tick)
&& self.loop_time.is_none()
{
self.loop_time = Some(
self.time + (t - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128,
);
}
self.time += (event.tick - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128;
self.tick = event.tick;
let mut zone = 0;
match event.kind {
1 => {
if !(0..=127).contains(&event.c) || !(0..=255).contains(&event.d) {
return Err("invalid note/velocity".into());
}
let id = if event.b == u32::MAX {
self.selected[event.track as usize]
} else {
event.b
};
if id > u16::MAX as u32 {
return Err("note has no bank-local instrument".into());
}
zone = *self
.zones
.range((id as u16, 0)..=(id as u16, event.c as u8))
.next_back()
.map(|(_, i)| i)
.filter(|&&i| self.instruments[i].high as i32 >= event.c)
.ok_or("note has no bank-local instrument zone")?;
}
3 => {
if event.a == 0 {
return Err("zero tempo".into());
}
self.tempo = event.a;
}
4 | 9 => {
if !(0..=65535).contains(&event.c) {
return Err("invalid gain/send".into());
}
}
5 => {
if !(0..=255).contains(&event.c) {
return Err("invalid pan".into());
}
}
6 => {
if !(-9600..=9600).contains(&event.c) {
return Err("invalid pitch bend".into());
}
}
7 | 8 => {
if event.a > 100_000
|| event.c < 0
|| event.c > if event.kind == 7 { 2400 } else { 65535 }
{
return Err("invalid modulation".into());
}
}
10 => {
if event.a > u16::MAX as u32
|| self
.zones
.range((event.a as u16, 0)..=(event.a as u16, 127))
.next()
.is_none()
{
return Err("unknown instrument".into());
}
self.selected[event.track as usize] = event.a;
}
_ => {}
}
if self.compiled.len() >= MAX_EVENTS_PER_FRAME
&& self.time - self.compiled[self.compiled.len() - MAX_EVENTS_PER_FRAME].time
< denominator
{
return Err("music event density exceeds real-time bound".into());
}
self.compiled.push(TimedMusicEvent { time: self.time, event, zone });
}
Ok(None)
}
fn finish(&mut self, denominator: u128) -> Result<MusicBank, String> {
if let Some(t) = self.loop_tick.filter(|&t| t >= self.tick)
&& self.loop_time.is_none()
{
self.loop_time =
Some(self.time + (t - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128);
}
let end_time = self.time
+ (self.duration - self.tick) as u128 * self.tempo as u128 * AUDIO_RATE as u128;
if end_time < denominator || self.loop_time.is_some_and(|t| end_time - t < denominator) {
return Err("music/loop shorter than one output frame".into());
}
let loop_event =
self.loop_time.map_or(0, |t| self.compiled.partition_point(|e| e.time < t));
let length = end_time - self.loop_time.unwrap_or(0);
let slice = &self.compiled[loop_event..];
for i in 0..slice.len().min(MAX_EVENTS_PER_FRAME + 1) {
let tail =
slice.len().saturating_sub(MAX_EVENTS_PER_FRAME - i.min(MAX_EVENTS_PER_FRAME));
if tail < slice.len()
&& slice.len() - tail + i + 1 > MAX_EVENTS_PER_FRAME
&& slice[i].time + length - slice[tail].time < denominator
{
return Err("music loop seam event density".into());
}
}
let pcm_bytes = self.samples.iter().map(|s| s.data.len() * 2).sum();
Ok(MusicBank {
name: self.name.take().ok_or("compiler already complete")?,
samples: Arc::new(std::mem::take(&mut self.samples)),
instruments: Arc::new(std::mem::take(&mut self.instruments)),
events: Arc::new(std::mem::take(&mut self.compiled)),
denominator,
end_time,
loop_time: self.loop_time,
loop_event,
tracks: self.tracks,
alive: Arc::new(AtomicBool::new(true)),
metrics: AudioBankMetrics { pcm_bytes, ..Default::default() },
})
}
}
+1 -1
View File
@@ -64,7 +64,7 @@ pub trait RuntimePlatform {
fn wall_clock(&self) -> &dyn WallClock; fn wall_clock(&self) -> &dyn WallClock;
fn display_size(&self) -> (usize, usize) { fn display_size(&self) -> (usize, usize) {
(480, 270) (crate::graphics_contract::WIDTH, crate::graphics_contract::HEIGHT)
} }
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink; fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink;
+24 -2
View File
@@ -1,13 +1,27 @@
#[derive(Debug)]
pub struct Sample { pub struct Sample {
pub sample_rate: u32, pub sample_rate: u32,
pub channels: u8,
pub data: Vec<i16>, pub data: Vec<i16>,
pub loop_start: Option<u32>, pub loop_start: Option<u32>,
pub loop_end: Option<u32>, pub loop_end: Option<u32>,
pub default_volume: u8,
pub default_pan: u8,
pub default_pitch: f64,
} }
impl Sample { impl Sample {
pub fn new(sample_rate: u32, data: Vec<i16>) -> Self { pub fn new(sample_rate: u32, data: Vec<i16>) -> Self {
Self { sample_rate, data, loop_start: None, loop_end: None } Self {
sample_rate,
channels: 1,
data,
loop_start: None,
loop_end: None,
default_volume: 255,
default_pan: 128,
default_pitch: 1.0,
}
} }
pub fn with_loop(mut self, start: u32, end: u32) -> Self { pub fn with_loop(mut self, start: u32, end: u32) -> Self {
@@ -17,6 +31,14 @@ impl Sample {
} }
pub fn frames_len(&self) -> usize { pub fn frames_len(&self) -> usize {
self.data.len() self.data.len() / self.channels.max(1) as usize
}
pub fn with_channels(mut self, channels: u8) -> Result<Self, String> {
if !(1..=2).contains(&channels) || !self.data.len().is_multiple_of(channels as usize) {
return Err("audio sample channels/frame count".into());
}
self.channels = channels;
Ok(self)
} }
} }
@@ -224,6 +224,8 @@ impl SceneViewportResolver {
scene_height_tiles: usize, scene_height_tiles: usize,
) -> TileAnchor { ) -> TileAnchor {
let mut next = current; let mut next = current;
// Mixed layers must not step past the center and immediately step back.
let trigger = self.hysteresis_trigger_px.max(tile_size_px / 2);
loop { loop {
let center_x_px = next.x * tile_size_px + tile_size_px / 2; let center_x_px = next.x * tile_size_px + tile_size_px / 2;
@@ -231,11 +233,11 @@ impl SceneViewportResolver {
if drift_x.abs() <= self.hysteresis_safe_px { if drift_x.abs() <= self.hysteresis_safe_px {
break; break;
} }
if drift_x > self.hysteresis_trigger_px { if drift_x > trigger {
next.x += 1; next.x += 1;
continue; continue;
} }
if drift_x < -self.hysteresis_trigger_px { if drift_x < -trigger {
next.x -= 1; next.x -= 1;
continue; continue;
} }
@@ -248,11 +250,11 @@ impl SceneViewportResolver {
if drift_y.abs() <= self.hysteresis_safe_px { if drift_y.abs() <= self.hysteresis_safe_px {
break; break;
} }
if drift_y > self.hysteresis_trigger_px { if drift_y > trigger {
next.y += 1; next.y += 1;
continue; continue;
} }
if drift_y < -self.hysteresis_trigger_px { if drift_y < -trigger {
next.y -= 1; next.y -= 1;
continue; continue;
} }
@@ -433,20 +435,34 @@ mod tests {
#[test] #[test]
fn first_update_initializes_master_and_layer_anchors() { fn first_update_initializes_master_and_layer_anchors() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let update = resolver.update(&scene, 0, 0); let update = resolver.update(&scene, 0, 0);
assert_eq!(update.master_anchor, TileAnchor { x: 17, y: 10 }); assert_eq!(update.master_anchor, TileAnchor { x: 22, y: 13 });
assert_eq!(update.layer_anchors[0], TileAnchor { x: 17, y: 10 }); assert_eq!(update.layer_anchors[0], TileAnchor { x: 22, y: 13 });
assert_eq!(update.layer_anchors[1], TileAnchor { x: 17, y: 10 }); assert_eq!(update.layer_anchors[1], TileAnchor { x: 22, y: 13 });
assert_eq!(update.refresh_requests.len(), 4); assert_eq!(update.refresh_requests.len(), 4);
} }
#[test] #[test]
fn per_layer_copy_requests_follow_parallax_factor() { fn per_layer_copy_requests_follow_parallax_factor() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let update = resolver.update(&scene, 32, 48); let update = resolver.update(&scene, 32, 48);
@@ -461,24 +477,38 @@ mod tests {
#[test] #[test]
fn hysteresis_prevents_small_back_and_forth_refresh_churn() { fn hysteresis_prevents_small_back_and_forth_refresh_churn() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let _ = resolver.update(&scene, 0, 0); let _ = resolver.update(&scene, 0, 0);
let update = resolver.update(&scene, 8, 0); let update = resolver.update(&scene, 8, 0);
assert!(update.refresh_requests.is_empty()); assert!(update.refresh_requests.is_empty());
assert_eq!(update.master_anchor, TileAnchor { x: 17, y: 10 }); assert_eq!(update.master_anchor, TileAnchor { x: 22, y: 13 });
} }
#[test] #[test]
fn repeated_high_speed_movement_advances_in_tile_steps() { fn repeated_high_speed_movement_advances_in_tile_steps() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let _ = resolver.update(&scene, 0, 0); let _ = resolver.update(&scene, 0, 0);
let update = resolver.update(&scene, 64, 0); let update = resolver.update(&scene, 64, 0);
assert!(update.master_anchor.x > 17); assert!(update.master_anchor.x > 22);
assert!(update.refresh_requests.iter().any(|request| matches!( assert!(update.refresh_requests.iter().any(|request| matches!(
request, request,
CacheRefreshRequest::RefreshColumn { layer_index: 0, .. } CacheRefreshRequest::RefreshColumn { layer_index: 0, .. }
@@ -489,18 +519,32 @@ mod tests {
#[test] #[test]
fn anchors_clamp_near_scene_edges() { fn anchors_clamp_near_scene_edges() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let update = resolver.update(&scene, 10_000, 10_000); let update = resolver.update(&scene, 10_000, 10_000);
assert_eq!(update.master_anchor, TileAnchor { x: 46, y: 53 }); assert_eq!(update.master_anchor, TileAnchor { x: 41, y: 50 });
assert_eq!(update.layer_anchors[0], TileAnchor { x: 46, y: 53 }); assert_eq!(update.layer_anchors[0], TileAnchor { x: 41, y: 50 });
} }
#[test] #[test]
fn corner_trigger_converts_to_non_overlapping_region_requests() { fn corner_trigger_converts_to_non_overlapping_region_requests() {
let scene = make_scene(); let scene = make_scene();
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let _ = resolver.update(&scene, 0, 0); let _ = resolver.update(&scene, 0, 0);
let update = resolver.update(&scene, 64, 80); let update = resolver.update(&scene, 64, 80);
@@ -515,15 +559,22 @@ mod tests {
.collect(); .collect();
assert_eq!(regions.len(), 2); assert_eq!(regions.len(), 2);
assert_eq!(regions[0].x + regions[0].width, 35); assert_eq!(regions[0].x + regions[0].width, 45);
assert_eq!(regions[0].height, 21); assert_eq!(regions[0].height, 27);
assert_eq!(regions[1].width, 34); assert_eq!(regions[1].width, 44);
assert_eq!(regions[1].height, 2); assert_eq!(regions[1].height, 2);
} }
#[test] #[test]
fn reset_scene_requests_full_invalidation_for_all_layers() { fn reset_scene_requests_full_invalidation_for_all_layers() {
let mut resolver = SceneViewportResolver::new(480, 270, 35, 21, 12, 20); let mut resolver = SceneViewportResolver::new(
crate::graphics_contract::WIDTH as i32,
crate::graphics_contract::HEIGHT as i32,
45,
27,
12,
20,
);
let requests = resolver.reset_scene(); let requests = resolver.reset_scene();
+33 -2
View File
@@ -1,16 +1,47 @@
use crate::sample::Sample; use crate::sample::Sample;
use std::sync::Arc; use std::sync::Arc;
use std::sync::atomic::{AtomicBool, Ordering};
#[derive(Debug, Clone, Copy, Default)]
pub struct AudioBankMetrics {
pub cartridge_bytes: usize,
pub pcm_bytes: usize,
pub canonical_decoded_bytes: usize,
pub materialization_ns: u64,
}
/// A container for audio assets. /// A container for audio assets.
/// ///
/// A SoundBank stores multiple audio samples that can be played by the /// A SoundBank stores multiple audio samples that can be played by the
/// audio subsystem. /// audio subsystem.
#[derive(Debug)]
pub struct SoundBank { pub struct SoundBank {
pub samples: Vec<Arc<Sample>>, pub samples: Arc<Vec<Arc<Sample>>>,
pub name: String,
pub alive: Arc<AtomicBool>,
pub metrics: AudioBankMetrics,
} }
impl SoundBank { impl SoundBank {
pub fn new(samples: Vec<Arc<Sample>>) -> Self { pub fn new(samples: Vec<Arc<Sample>>) -> Self {
Self { samples } let pcm_bytes = samples.iter().map(|s| s.data.len() * 2).sum();
Self {
samples: Arc::new(samples),
name: String::new(),
alive: Arc::new(AtomicBool::new(true)),
metrics: AudioBankMetrics { pcm_bytes, ..Default::default() },
}
}
pub fn invalidate(&self) {
self.alive.store(false, Ordering::Release);
}
pub fn resident_copy(&self) -> Self {
Self {
samples: self.samples.clone(),
name: self.name.clone(),
alive: Arc::new(AtomicBool::new(true)),
metrics: self.metrics,
}
} }
} }
@@ -59,6 +59,19 @@ pub enum Syscall {
AudioSetVolume = 0x3004, AudioSetVolume = 0x3004,
AudioSetPan = 0x3005, AudioSetPan = 0x3005,
AudioSetPitch = 0x3006, AudioSetPitch = 0x3006,
MusicPlay = 0x3010,
MusicStop = 0x3011,
MusicPause = 0x3012,
MusicResume = 0x3013,
MusicSetVolume = 0x3014,
MusicFadeTo = 0x3015,
MusicCrossfade = 0x3016,
AudioSetBusVolume = 0x3020,
AudioSetEffect = 0x3021,
AudioSetSend = 0x3022,
AudioUnloadBank = 0x3023,
AudioSetGroupVolume = 0x3024,
FsOpen = 0x4001, FsOpen = 0x4001,
FsRead = 0x4002, FsRead = 0x4002,
FsWrite = 0x4003, FsWrite = 0x4003,
@@ -31,4 +31,64 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
.rets(1) .rets(1)
.caps(caps::AUDIO) .caps(caps::AUDIO)
.cost(5), .cost(5),
SyscallRegistryEntry::builder(Syscall::MusicPlay, "music", "play")
.args(3)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicStop, "music", "stop")
.args(1)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicPause, "music", "pause")
.args(1)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicResume, "music", "resume")
.args(1)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicSetVolume, "music", "set_volume")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicFadeTo, "music", "fade_to")
.args(4)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::MusicCrossfade, "music", "crossfade")
.args(4)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetBusVolume, "audio", "set_bus_volume")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetEffect, "audio", "set_effect")
.args(6)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetSend, "audio", "set_send")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioUnloadBank, "audio", "unload_bank")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
SyscallRegistryEntry::builder(Syscall::AudioSetGroupVolume, "audio", "set_group_volume")
.args(2)
.rets(1)
.caps(caps::AUDIO)
.cost(5),
]; ];
@@ -37,6 +37,19 @@ impl Syscall {
0x3004 => Some(Self::AudioSetVolume), 0x3004 => Some(Self::AudioSetVolume),
0x3005 => Some(Self::AudioSetPan), 0x3005 => Some(Self::AudioSetPan),
0x3006 => Some(Self::AudioSetPitch), 0x3006 => Some(Self::AudioSetPitch),
0x3010 => Some(Self::MusicPlay),
0x3011 => Some(Self::MusicStop),
0x3012 => Some(Self::MusicPause),
0x3013 => Some(Self::MusicResume),
0x3014 => Some(Self::MusicSetVolume),
0x3015 => Some(Self::MusicFadeTo),
0x3016 => Some(Self::MusicCrossfade),
0x3020 => Some(Self::AudioSetBusVolume),
0x3021 => Some(Self::AudioSetEffect),
0x3022 => Some(Self::AudioSetSend),
0x3023 => Some(Self::AudioUnloadBank),
0x3024 => Some(Self::AudioSetGroupVolume),
0x4001 => Some(Self::FsOpen), 0x4001 => Some(Self::FsOpen),
0x4002 => Some(Self::FsRead), 0x4002 => Some(Self::FsRead),
0x4003 => Some(Self::FsWrite), 0x4003 => Some(Self::FsWrite),
@@ -110,6 +123,19 @@ impl Syscall {
Self::AudioSetVolume => "AudioSetVolume", Self::AudioSetVolume => "AudioSetVolume",
Self::AudioSetPan => "AudioSetPan", Self::AudioSetPan => "AudioSetPan",
Self::AudioSetPitch => "AudioSetPitch", Self::AudioSetPitch => "AudioSetPitch",
Self::MusicPlay => "MusicPlay",
Self::MusicStop => "MusicStop",
Self::MusicPause => "MusicPause",
Self::MusicResume => "MusicResume",
Self::MusicSetVolume => "MusicSetVolume",
Self::MusicFadeTo => "MusicFadeTo",
Self::MusicCrossfade => "MusicCrossfade",
Self::AudioSetBusVolume => "AudioSetBusVolume",
Self::AudioSetEffect => "AudioSetEffect",
Self::AudioSetSend => "AudioSetSend",
Self::AudioUnloadBank => "AudioUnloadBank",
Self::AudioSetGroupVolume => "AudioSetGroupVolume",
Self::FsOpen => "FsOpen", Self::FsOpen => "FsOpen",
Self::FsRead => "FsRead", Self::FsRead => "FsRead",
Self::FsWrite => "FsWrite", Self::FsWrite => "FsWrite",
@@ -385,6 +385,14 @@ impl<'a> VmFacade<'a> {
self.os.vm_runtime.record_repeated_render_worker_frame(frame_id); self.os.vm_runtime.record_repeated_render_worker_frame(frame_id);
} }
pub fn record_presented_render_worker_frame(
&self,
ownership: RenderOwnership,
frame_id: FrameId,
) {
self.os.vm_runtime.record_presented_render_worker_frame(ownership, frame_id);
}
pub fn active_render_ownership(&self) -> RenderOwnership { pub fn active_render_ownership(&self) -> RenderOwnership {
if let Some(task_id) = self.foreground_session_task_id() if let Some(task_id) = self.foreground_session_task_id()
&& let Some(session) = self.os.vm_sessions.for_task(task_id) && let Some(session) = self.os.vm_sessions.for_task(task_id)
@@ -64,6 +64,14 @@ impl SystemOS {
pub fn memcard(&mut self) -> &mut MemcardService { pub fn memcard(&mut self) -> &mut MemcardService {
&mut self.memcard &mut self.memcard
} }
/// A successful return confirms the shared worker has stopped and joined.
pub fn stop_background_io(&mut self) -> Result<(), crate::AsyncWorkLaneError> {
if let Some(controller) = &mut self.io_controller {
controller.stop()?;
}
self.io_controller = None;
Ok(())
}
/// Host/player operations are admitted only while gameplay is suspended. /// Host/player operations are admitted only while gameplay is suspended.
pub fn replace_memcard( pub fn replace_memcard(
@@ -162,6 +170,16 @@ impl SystemOS {
self.log_service.get_after(seq) self.log_service.get_after(seq)
} }
/// Coherent non-destructive page and retained bounds; does not execute the VM.
pub fn log_snapshot(
&self,
after: Option<u64>,
limit: usize,
) -> (Vec<LogEvent>, Option<u64>, Option<u64>) {
let (oldest, newest) = self.log_service.sequence_bounds();
(self.log_service.get_page(after, limit), oldest, newest)
}
pub fn frame_index(&mut self) -> u64 { pub fn frame_index(&mut self) -> u64 {
self.vm().logical_frame_index() self.vm().logical_frame_index()
} }
@@ -10,19 +10,41 @@ use prometeu_hal::{
const SHELL_A_BUTTON: Rect = Rect { x: 112, y: 172, w: 112, h: 32 }; const SHELL_A_BUTTON: Rect = Rect { x: 112, y: 172, w: 112, h: 32 };
const SHELL_B_BUTTON: Rect = Rect { x: 256, y: 172, w: 112, h: 32 }; const SHELL_B_BUTTON: Rect = Rect { x: 256, y: 172, w: 112, h: 32 };
const CLOSE_BUTTON: Rect = Rect { x: 420, y: 24, w: 16, h: 16 }; const CLOSE_BUTTON: Rect =
const VIEWPORT: Rect = Rect { x: 0, y: 0, w: 480, h: 270 }; Rect { x: prometeu_hal::graphics_contract::WIDTH as i32 - 60, y: 24, w: 16, h: 16 };
const HOME_PANEL: Rect = Rect { x: 48, y: 58, w: 384, h: 154 }; const VIEWPORT: Rect = Rect {
const TITLE_PANEL: Rect = Rect { x: 72, y: 34, w: 336, h: 28 }; x: 0,
y: 0,
w: prometeu_hal::graphics_contract::WIDTH as i32,
h: prometeu_hal::graphics_contract::HEIGHT as i32,
};
const HOME_PANEL: Rect = Rect {
x: 48,
y: 58,
w: prometeu_hal::graphics_contract::WIDTH as i32 - 96,
h: prometeu_hal::graphics_contract::HEIGHT as i32 - 116,
};
const TITLE_PANEL: Rect =
Rect { x: 72, y: 34, w: prometeu_hal::graphics_contract::WIDTH as i32 - 144, h: 28 };
const GAME_ROW_X: i32 = 72; const GAME_ROW_X: i32 = 72;
const GAME_ROW_Y: i32 = 90; const GAME_ROW_Y: i32 = 90;
const GAME_ROW_W: i32 = 336; const GAME_ROW_W: i32 = prometeu_hal::graphics_contract::WIDTH as i32 - 144;
const GAME_ROW_H: i32 = 22; const GAME_ROW_H: i32 = 22;
const GAME_ROW_GAP: i32 = 6; const GAME_ROW_GAP: i32 = 6;
const MAX_HOME_GAME_ROWS: usize = 3; const MAX_HOME_GAME_ROWS: usize = 3;
pub const HUB_SUSPENDED_GAME_KILL_CONTROL: Rect = Rect { x: 288, y: 230, w: 168, h: 24 }; pub const HUB_SUSPENDED_GAME_KILL_CONTROL: Rect = Rect {
x: prometeu_hal::graphics_contract::WIDTH as i32 - 192,
y: prometeu_hal::graphics_contract::HEIGHT as i32 - 40,
w: 168,
h: 24,
};
#[cfg(test)] #[cfg(test)]
const SHELL_FRAME: Rect = Rect { x: 40, y: 20, w: 400, h: 220 }; const SHELL_FRAME: Rect = Rect {
x: 40,
y: 20,
w: prometeu_hal::graphics_contract::WIDTH as i32 - 80,
h: prometeu_hal::graphics_contract::HEIGHT as i32 - 50,
};
const COLOR_BG: Color = Color::rgb(12, 14, 22); const COLOR_BG: Color = Color::rgb(12, 14, 22);
const COLOR_PANEL: Color = Color::rgb(25, 31, 48); const COLOR_PANEL: Color = Color::rgb(25, 31, 48);
@@ -2,6 +2,7 @@
//! shared IO worker owns storage during a publication. Legacy per-slot files are //! shared IO worker owns storage during a publication. Legacy per-slot files are
//! intentionally neither read nor migrated by this service. //! intentionally neither read nor migrated by this service.
pub mod admission; pub mod admission;
pub mod diagnostics;
pub mod guest; pub mod guest;
pub mod image; pub mod image;
pub mod session; pub mod session;
@@ -37,6 +37,7 @@ pub struct Admission {
pub state: PreparationState, pub state: PreparationState,
pub snapshot_budget: usize, pub snapshot_budget: usize,
faulted: bool, faulted: bool,
replacement_observation: Option<super::diagnostics::SessionDiagnostics>,
} }
impl Default for Admission { impl Default for Admission {
fn default() -> Self { fn default() -> Self {
@@ -48,10 +49,26 @@ impl Default for Admission {
state: PreparationState::Idle, state: PreparationState::Idle,
snapshot_budget: DEFAULT_SNAPSHOT_BUDGET, snapshot_budget: DEFAULT_SNAPSHOT_BUDGET,
faulted: false, faulted: false,
replacement_observation: None,
} }
} }
} }
impl MemcardService { impl MemcardService {
pub fn session_diagnostics(&self) -> super::diagnostics::SessionDiagnostics {
self.admission.replacement_observation.clone().unwrap_or_else(|| self.session.diagnostics())
}
pub fn preparation_active(&self) -> bool {
self.admission.receiver.is_some()
}
pub fn installed_card_id(&self) -> Option<[u8; 16]> {
self.admission.installed.as_ref().map(|c| c.current().card_id)
}
pub fn cancel_pending(&mut self) {
self.session.cancel_pending();
if let Some(control) = &self.admission.control {
control.cancel();
}
}
pub fn host_faulted(&self) -> bool { pub fn host_faulted(&self) -> bool {
self.admission.faulted || self.session.host_faulted() self.admission.faulted || self.session.host_faulted()
} }
@@ -60,7 +77,11 @@ impl MemcardService {
} }
pub fn installed_health(&self) -> Option<(bool, bool, bool)> { pub fn installed_health(&self) -> Option<(bool, bool, bool)> {
self.admission.installed.as_ref().map(|card| { self.admission.installed.as_ref().map(|card| {
(card.recovered, card.degraded, card.write_blocked || card.storage_read_only()) (
card.recovered,
card.degraded,
card.write_blocked || card.storage_read_only() || card.uncertain,
)
}) })
} }
pub fn card_has_game(&self, app_id: u32) -> bool { pub fn card_has_game(&self, app_id: u32) -> bool {
@@ -135,6 +156,9 @@ impl MemcardService {
let owned = let owned =
card.catalog.games.iter().find(|g| g.app_id == app_id).map_or(0, |g| g.slots.len()); card.catalog.games.iter().find(|g| g.app_id == app_id).map_or(0, |g| g.slots.len());
if choice == Choice::Persistent { if choice == Choice::Persistent {
if card.uncertain {
return Err(Error::Indeterminate);
}
if card.storage_read_only() || card.write_blocked { if card.storage_read_only() || card.write_blocked {
return Err(Error::ReadOnly); return Err(Error::ReadOnly);
} }
@@ -171,6 +195,10 @@ impl MemcardService {
} }
Choice::Persistent => { Choice::Persistent => {
let mut card = card.take().unwrap(); let mut card = card.take().unwrap();
if card.uncertain {
session.retain_idle_card(card);
return Err(Error::Indeterminate);
}
if card.storage_read_only() || card.write_blocked { if card.storage_read_only() || card.write_blocked {
session.retain_idle_card(card); session.retain_idle_card(card);
return Err(Error::ReadOnly); return Err(Error::ReadOnly);
@@ -256,9 +284,24 @@ impl MemcardService {
&mut self, &mut self,
storage: Box<dyn MemcardStorage>, storage: Box<dyn MemcardStorage>,
load_existing: bool, load_existing: bool,
) -> Result<()> {
self.replace_card_job(move |session, control| {
session.replace_storage(storage, load_existing, control)
})
}
pub fn reconcile_card_with(
&mut self,
open: impl FnOnce() -> Result<Box<dyn MemcardStorage>> + Send + 'static,
) -> Result<()> {
self.replace_card_job(move |session, control| session.reconcile_storage_with(open, control))
}
fn replace_card_job(
&mut self,
operation: impl FnOnce(&mut Session, &PublicationControl) -> Result<()> + Send + 'static,
) -> Result<()> { ) -> Result<()> {
if self.admission.receiver.is_some() if self.admission.receiver.is_some()
|| self.session.has_in_flight() || self.session.io_active()
|| self.session.has_deferred_write()
|| self.session.is_boot_active() || self.session.is_boot_active()
{ {
return Err(Error::Busy); return Err(Error::Busy);
@@ -266,6 +309,7 @@ impl MemcardService {
if self.admission.faulted { if self.admission.faulted {
return Err(Error::ReadOnly); return Err(Error::ReadOnly);
} }
self.admission.replacement_observation = Some(self.session.diagnostics());
let handoff = Arc::new(Mutex::new(Some(std::mem::take(&mut self.session)))); let handoff = Arc::new(Mutex::new(Some(std::mem::take(&mut self.session))));
let worker = handoff.clone(); let worker = handoff.clone();
let control = Arc::new(PublicationControl::default()); let control = Arc::new(PublicationControl::default());
@@ -275,13 +319,14 @@ impl MemcardService {
.lane .lane
.submit_memcard_commit_write(move |_| { .submit_memcard_commit_write(move |_| {
let mut session = worker.lock().unwrap().take().unwrap(); let mut session = worker.lock().unwrap().take().unwrap();
let result = session.replace_storage(storage, load_existing, &worker_control); let result = operation(&mut session, &worker_control);
let _ = tx.send(Prepared::Replacement(session, result)); let _ = tx.send(Prepared::Replacement(session, result));
crate::AsyncWorkJobOutcome::Completed crate::AsyncWorkJobOutcome::Completed
}) })
.is_err() .is_err()
{ {
self.session = handoff.lock().unwrap().take().unwrap(); self.session = handoff.lock().unwrap().take().unwrap();
self.admission.replacement_observation = None;
return Err(Error::InvalidState); return Err(Error::InvalidState);
} }
self.admission.control = Some(control); self.admission.control = Some(control);
@@ -331,6 +376,7 @@ impl MemcardService {
} }
self.admission.receiver = None; self.admission.receiver = None;
self.admission.control = None; self.admission.control = None;
self.admission.replacement_observation = None;
} }
Err(mpsc::TryRecvError::Disconnected) => { Err(mpsc::TryRecvError::Disconnected) => {
self.admission.state = PreparationState::Failed(Error::InvalidState); self.admission.state = PreparationState::Failed(Error::InvalidState);
@@ -361,3 +407,37 @@ impl MemcardService {
} }
} }
} }
#[cfg(all(test, unix))]
mod tests {
use super::*;
use prometeu_drivers::memcard::FileMemcard;
use prometeu_hal::memcard::MemcardIoError;
#[test]
fn idle_uncertain_media_remains_blocked_before_another_persistent_admission() {
let path = std::env::temp_dir().join(format!(
"memcard-uncertain-idle-{}-{}",
std::process::id(),
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
));
let io = FileMemcard::create(&path, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap();
let mut card = Card::mount(Box::new(io)).unwrap();
card.uncertain = true;
let mut service = MemcardService::new();
// An ended session returns its backend to the same installed-card state.
service.admission.installed = Some(card);
assert_eq!(service.installed_health(), Some((false, false, true)));
assert_eq!(
service.choose_for_game(42, 1, Choice::Persistent, 0),
Err(Error::Indeterminate)
);
assert!(service.card_installed());
assert_eq!(service.lane.pending_depth(), 0);
service.uninstall_card().unwrap();
std::fs::remove_file(path).unwrap();
}
}
@@ -0,0 +1,31 @@
//! Read-only native observations. These do not consume the guest request entry.
use super::{
image::Error,
session::{Mode, RequestResult},
};
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RequestDiagnostics {
pub result: RequestResult,
pub storage_error: Option<Error>,
pub slot: Option<usize>,
pub operation: &'static str,
pub retained: bool,
pub io_active: bool,
pub deferred: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct SessionDiagnostics {
pub app_id: Option<u32>,
pub card_id: Option<[u8; 16]>,
pub epoch: u64,
pub mode: Option<Mode>,
pub health: (bool, bool, bool),
pub dirty_slots: Vec<usize>,
pub request: Option<RequestDiagnostics>,
pub io_active: bool,
pub removal_pending: bool,
pub reconciliation_required: bool,
pub restart_required: bool,
}
@@ -31,12 +31,14 @@ pub fn status(e: Error) -> i64 {
use prometeu_hal::memcard::MemcardIoError as I; use prometeu_hal::memcard::MemcardIoError as I;
match e { match e {
Error::NoSpace | Error::Io(I::NoSpace) => 3, Error::NoSpace | Error::Io(I::NoSpace) => 3,
Error::AccessDenied => 4, Error::AccessDenied
| Error::IdentityMismatch
| Error::Io(I::AccessDenied | I::AlreadyExists) => 4,
Error::Corrupt => 5, Error::Corrupt => 5,
Error::Indeterminate => 6, Error::Indeterminate | Error::Io(I::Indeterminate) => 6,
Error::Io(I::Unavailable) => 7, Error::Io(I::Unavailable) => 7,
Error::InvalidState | Error::Canceled => 8, Error::InvalidState | Error::Canceled => 8,
Error::Busy => 9, Error::Busy | Error::Io(I::Busy) => 9,
Error::ReadOnly | Error::CounterExhausted | Error::Io(I::ReadOnly) => 10, Error::ReadOnly | Error::CounterExhausted | Error::Io(I::ReadOnly) => 10,
Error::InvalidRange | Error::Io(I::InvalidRange) => 11, Error::InvalidRange | Error::Io(I::InvalidRange) => 11,
Error::Unsupported | Error::Io(I::Unsupported) => 12, Error::Unsupported | Error::Io(I::Unsupported) => 12,
@@ -29,6 +29,7 @@ pub enum Error {
OutOfMemory, OutOfMemory,
AccessDenied, AccessDenied,
InvalidState, InvalidState,
IdentityMismatch,
} }
impl From<MemcardIoError> for Error { impl From<MemcardIoError> for Error {
fn from(e: MemcardIoError) -> Self { fn from(e: MemcardIoError) -> Self {
@@ -7,6 +7,8 @@ use std::time::{Duration, Instant};
pub const GUEST_BYTES: usize = 4096; pub const GUEST_BYTES: usize = 4096;
static NEXT_CONTEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1); static NEXT_CONTEXT: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
// `try_update` requires Rust 1.95; keep older stable CI toolchains compatible.
#[allow(deprecated)]
fn next_context() -> Result<u64> { fn next_context() -> Result<u64> {
NEXT_CONTEXT NEXT_CONTEXT
.fetch_update( .fetch_update(
@@ -71,12 +73,14 @@ struct Request {
job: AsyncWorkJobId, job: AsyncWorkJobId,
released: bool, released: bool,
saves_payload: bool, saves_payload: bool,
worker_returned: bool,
} }
/// Main-lane control; the Card moves into the single worker while its source is protected. /// Main-lane control; the Card moves into the single worker while its source is protected.
#[derive(Default)] #[derive(Default)]
pub struct Session { pub struct Session {
card_id: Option<[u8; 16]>, card_id: Option<[u8; 16]>,
uncertain_target: Option<Map>, uncertain_target: Option<Map>,
known_card_exclusions: Option<([u8; 16], [bool; BLOCK_COUNT])>,
health: (bool, bool, bool), health: (bool, bool, bool),
context: u64, context: u64,
epoch: u64, epoch: u64,
@@ -100,6 +104,82 @@ pub struct Session {
deferred: Option<(u64, usize, u64, Instant)>, deferred: Option<(u64, usize, u64, Instant)>,
} }
impl Session { impl Session {
/// IO ownership, independent of a completed result retained for guest release.
pub fn io_active(&self) -> bool {
self.request.as_ref().is_some_and(|r| !r.worker_returned)
}
pub fn has_deferred_write(&self) -> bool {
self.deferred.is_some()
}
pub fn cancel_pending(&mut self) {
if let Some(r) = &self.request {
r.control.cancel();
}
if let Some((id, local, ..)) = self.deferred.take() {
self.slots[local].protected = false;
self.memory_result = Some(RequestResult {
id,
state: RequestState::Failure,
reason: RequestReason::Storage(Error::Canceled),
});
}
}
pub fn diagnostics(&self) -> super::diagnostics::SessionDiagnostics {
use super::diagnostics::{RequestDiagnostics, SessionDiagnostics};
let request = if let Some((id, local, ..)) = self.deferred {
Some(RequestDiagnostics {
result: RequestResult {
id,
state: RequestState::Pending,
reason: RequestReason::None,
},
storage_error: None,
slot: Some(local),
operation: "commit",
retained: true,
io_active: false,
deferred: true,
})
} else if let Some(r) = &self.request {
Some(RequestDiagnostics {
result: r.result,
storage_error: r.worker_error,
slot: r.saves_payload.then_some(r.local),
operation: if r.saves_payload { "commit" } else { "presentation" },
retained: !r.released,
io_active: self.io_active(),
deferred: false,
})
} else {
self.memory_result.map(|result| RequestDiagnostics {
result,
storage_error: None,
slot: None,
operation: "commit",
retained: true,
io_active: false,
deferred: false,
})
};
SessionDiagnostics {
app_id: self.mode.map(|_| self.app_id),
card_id: self.card_id,
epoch: self.epoch,
mode: self.mode,
health: self.health(),
dirty_slots: self
.slots
.iter()
.enumerate()
.filter_map(|(i, s)| s.data.read().ok().filter(|s| s.dirty).map(|_| i))
.collect(),
request,
io_active: self.io_active(),
removal_pending: self.removal_pending,
reconciliation_required: self.reconcile_blocked,
restart_required: self.faulted,
}
}
pub fn context(&self) -> u64 { pub fn context(&self) -> u64 {
self.context self.context
} }
@@ -531,6 +611,7 @@ impl Session {
job, job,
released: !saves_payload, released: !saves_payload,
saves_payload, saves_payload,
worker_returned: false,
}); });
Ok(()) Ok(())
} }
@@ -674,6 +755,7 @@ impl Session {
job, job,
released: false, released: false,
saves_payload: true, saves_payload: true,
worker_returned: false,
}); });
Ok(id) Ok(id)
} }
@@ -692,6 +774,7 @@ impl Session {
let Some(r) = &mut self.request else { return }; let Some(r) = &mut self.request else { return };
match r.receiver.try_recv() { match r.receiver.try_recv() {
Ok(completion) => { Ok(completion) => {
r.worker_returned = true;
r.worker_error = completion.result.error; r.worker_error = completion.result.error;
let current = let current =
self.mode.is_some() && r.session == self.context && r.epoch == self.epoch; self.mode.is_some() && r.session == self.context && r.epoch == self.epoch;
@@ -819,7 +902,7 @@ impl Session {
return Err(Error::Busy); return Err(Error::Busy);
} }
r.released = true; r.released = true;
if self.card.is_some() { if r.worker_returned {
self.request = None; self.request = None;
} }
Ok(()) Ok(())
@@ -833,7 +916,7 @@ impl Session {
r.control.cancel(); r.control.cancel();
r.released = true; r.released = true;
} }
if self.card.is_some() { if !self.io_active() {
self.request = None; self.request = None;
} }
self.removal_pending = false; self.removal_pending = false;
@@ -869,7 +952,23 @@ impl Session {
load_existing: bool, load_existing: bool,
control: &PublicationControl, control: &PublicationControl,
) -> Result<()> { ) -> Result<()> {
if self.has_in_flight() || self.boot_active || self.mode.is_none() { self.replace_storage_with(move || Ok(storage), load_existing, false, control)
}
pub(super) fn reconcile_storage_with(
&mut self,
open: impl FnOnce() -> Result<Box<dyn prometeu_hal::memcard::MemcardStorage>>,
control: &PublicationControl,
) -> Result<()> {
self.replace_storage_with(open, false, true, control)
}
fn replace_storage_with(
&mut self,
open: impl FnOnce() -> Result<Box<dyn prometeu_hal::memcard::MemcardStorage>>,
load_existing: bool,
same_only: bool,
control: &PublicationControl,
) -> Result<()> {
if self.io_active() || self.deferred.is_some() || self.boot_active || self.mode.is_none() {
return Err(Error::Busy); return Err(Error::Busy);
} }
if self.icon.is_empty() if self.icon.is_empty()
@@ -882,11 +981,18 @@ impl Session {
{ {
self.uncertain_target = card.attempted_publication.clone(); self.uncertain_target = card.attempted_publication.clone();
} }
let known = self.card.as_ref().map(|c| (c.current().card_id, c.known_exclusions())); if let Some(card) = &self.card {
self.known_card_exclusions = Some((card.current().card_id, card.known_exclusions()));
}
let known = self.known_card_exclusions;
self.card.take(); // Release the old scratch before mounting another image. self.card.take(); // Release the old scratch before mounting another image.
self.scratch = None; self.scratch = None;
self.reconcile_blocked = true; self.reconcile_blocked = true;
self.card = Some(Card::mount(storage)?); let candidate = Card::mount(open()?)?;
if same_only && self.card_id != Some(candidate.current().card_id) {
return Err(Error::IdentityMismatch);
}
self.card = Some(candidate);
let card = self.card.as_mut().unwrap(); let card = self.card.as_mut().unwrap();
let same = self.card_id == Some(card.current().card_id); let same = self.card_id == Some(card.current().card_id);
if let Some((id, known)) = known if let Some((id, known)) = known
@@ -973,14 +1079,15 @@ impl Session {
Ok(()) Ok(())
} }
pub fn detach(&mut self) -> Result<()> { pub fn detach(&mut self) -> Result<()> {
if self.deferred.is_some() if self.deferred.is_some() || self.io_active() {
|| self
.request
.as_ref()
.is_some_and(|r| r.result.state == RequestState::Pending || self.card.is_none())
{
return Err(Error::Busy); return Err(Error::Busy);
} }
if self.card.is_none() && self.scratch.is_none() {
let mut scratch = Vec::new();
scratch.try_reserve_exact(SLOT_BYTES).map_err(|_| Error::OutOfMemory)?;
scratch.resize(SLOT_BYTES, 0);
self.scratch = Some(scratch);
}
self.mode = Some(Mode::MemoryOnly); self.mode = Some(Mode::MemoryOnly);
self.removal_pending = false; self.removal_pending = false;
self.reconcile_blocked = false; self.reconcile_blocked = false;
@@ -16,6 +16,8 @@ impl PublicationControl {
pub fn publication_attempted(&self) -> bool { pub fn publication_attempted(&self) -> bool {
self.0.load(Ordering::SeqCst) & 1 != 0 self.0.load(Ordering::SeqCst) & 1 != 0
} }
// `try_update` requires Rust 1.95; keep older stable CI toolchains compatible.
#[allow(deprecated)]
fn enter(&self) -> Result<()> { fn enter(&self) -> Result<()> {
self.0 self.0
.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |state| { .fetch_update(Ordering::SeqCst, Ordering::SeqCst, |state| {
@@ -960,7 +960,7 @@ fn persistent_save_preempts_real_multichunk_asset_decoders() {
self.inner.sync() self.inner.sync()
} }
} }
for kind in [BankType::GLYPH, BankType::SOUNDS, BankType::SCENE] { for kind in [BankType::GLYPH, BankType::SOUNDS, BankType::MUSIC, BankType::SCENE] {
let (card, disk) = formatted(); let (card, disk) = formatted();
drop(card); drop(card);
let events: Events = Arc::default(); let events: Events = Arc::default();
@@ -985,8 +985,37 @@ fn persistent_save_preempts_real_multichunk_asset_decoders() {
) )
} }
BankType::SOUNDS => { BankType::SOUNDS => {
(vec![0x12; 16385], 16385, serde_json::json!({"sample_rate":44100,"channels":1})) let mut bytes = vec![0u8; 88];
bytes[..4].copy_from_slice(b"SBNK");
bytes[4] = 1;
bytes[49] = 1;
bytes[80] = 255;
bytes[81] = 128;
for (at, value) in [
(8, 1u32),
(20, 960),
(24, 500000),
(32, u32::MAX),
(52, 44100),
(56, 8192),
(68, 88),
(72, 16384),
(84, 65536),
] {
bytes[at..at + 4].copy_from_slice(&value.to_le_bytes());
} }
bytes.extend([0x12; 16384]);
(bytes, 16472, serde_json::json!({"version":1}))
}
BankType::MUSIC => (
include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-music.mbnk"
))
.to_vec(),
6395,
serde_json::json!({"version":1}),
),
BankType::SCENE => { BankType::SCENE => {
let mut bytes = vec![0; 140]; let mut bytes = vec![0; 140];
bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]); bytes[..8].copy_from_slice(&[b'S', b'C', b'N', b'E', 1, 0, 4, 0]);
@@ -1079,6 +1108,12 @@ fn persistent_save_preempts_real_multichunk_asset_decoders() {
assert_eq!(bank.samples[0].sample_rate, 44100); assert_eq!(bank.samples[0].sample_rate, 44100);
assert_eq!(bank.samples[0].data, vec![0x1212; 8192]); assert_eq!(bank.samples[0].data, vec![0x1212; 8192]);
} }
BankType::MUSIC => {
let bank = banks.music_bank_slot(0).unwrap();
assert_eq!(bank.events.len(), 4);
assert_eq!(bank.samples.len(), 2);
assert_eq!(bank.samples[1].channels, 2);
}
BankType::SCENE => { BankType::SCENE => {
let bank = banks.scene_bank_slot(0).unwrap(); let bank = banks.scene_bank_slot(0).unwrap();
assert_eq!( assert_eq!(
@@ -4,6 +4,7 @@ use crate::services::memcard::MemcardService;
use prometeu_bytecode::{TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_TYPE, Value}; use prometeu_bytecode::{TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_TYPE, Value};
use prometeu_hal::app_mode::AppMode; use prometeu_hal::app_mode::AppMode;
use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType}; use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType};
use prometeu_hal::audio_bridge::AudioControl;
use prometeu_hal::color::Color; use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph; use prometeu_hal::glyph::Glyph;
use prometeu_hal::log::{LogLevel, LogSource}; use prometeu_hal::log::{LogLevel, LogSource};
@@ -465,7 +466,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
let pan_raw = expect_int(args, 3)?; let pan_raw = expect_int(args, 3)?;
let pitch = expect_number(args, 4, "pitch")?; let pitch = expect_number(args, 4, "pitch")?;
if !(0..16).contains(&voice_id_raw) { if !(0..8).contains(&voice_id_raw) {
ret.push_int(AudioOpStatus::VoiceInvalid as i64); ret.push_int(AudioOpStatus::VoiceInvalid as i64);
return Ok(()); return Ok(());
} }
@@ -508,7 +509,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
prometeu_hal::LoopMode::On prometeu_hal::LoopMode::On
}; };
if !(0..16).contains(&voice_id_raw) { if !(0..8).contains(&voice_id_raw) {
ret.push_int(AudioOpStatus::VoiceInvalid as i64); ret.push_int(AudioOpStatus::VoiceInvalid as i64);
return Ok(()); return Ok(());
} }
@@ -558,7 +559,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
} else { } else {
1.0 1.0
}; };
let status = if !(0..16).contains(&voice) { let status = if !(0..8).contains(&voice) {
AudioOpStatus::VoiceInvalid AudioOpStatus::VoiceInvalid
} else if !(0..=255).contains(&value) || !pitch.is_finite() || pitch <= 0.0 { } else if !(0..=255).contains(&value) || !pitch.is_finite() || pitch <= 0.0 {
AudioOpStatus::ArgRangeInvalid AudioOpStatus::ArgRangeInvalid
@@ -575,6 +576,113 @@ impl NativeInterface for VmRuntimeHost<'_> {
ret.push_int(status as i64); ret.push_int(status as i64);
Ok(()) Ok(())
} }
Syscall::MusicPlay
| Syscall::MusicStop
| Syscall::MusicPause
| Syscall::MusicResume
| Syscall::MusicSetVolume
| Syscall::MusicFadeTo
| Syscall::MusicCrossfade
| Syscall::AudioSetBusVolume
| Syscall::AudioSetEffect
| Syscall::AudioSetSend
| Syscall::AudioUnloadBank
| Syscall::AudioSetGroupVolume => {
macro_rules! uint {
($i:expr, $max:expr) => {{
let n = expect_int(args, $i)?;
if !(0..=$max).contains(&n) {
ret.push_int(AudioOpStatus::ArgRangeInvalid as i64);
return Ok(());
}
n as u32
}};
}
let status = match syscall {
Syscall::MusicPlay => {
let group = uint!(0, 1);
let bank = uint!(1, 15);
let looping = uint!(2, 1);
platform.audio_mut().music_play(group as usize, bank as usize, looping != 0)
}
Syscall::AudioUnloadBank => {
let music = uint!(0, 1);
let slot = uint!(1, 15);
let result = platform.assets().unload_audio(music != 0, slot as usize);
ret.push_int(if result == AssetOpStatus::Ok {
AudioOpStatus::Ok
} else {
AudioOpStatus::BankInvalid
} as i64);
return Ok(());
}
_ => {
let control = match syscall {
Syscall::MusicStop => {
AudioControl::MusicStop { group: uint!(0, 1) as usize }
}
Syscall::MusicPause | Syscall::MusicResume => {
AudioControl::MusicPause {
group: uint!(0, 1) as usize,
paused: syscall == Syscall::MusicPause,
}
}
Syscall::MusicSetVolume => AudioControl::MusicVolume {
group: uint!(0, 1) as usize,
gain: uint!(1, 255) as u8,
},
Syscall::MusicFadeTo => {
let group = uint!(0, 1) as usize;
let gain = uint!(1, 255) as u8;
let ms = uint!(2, (u32::MAX / 48) as i64);
let curve = uint!(3, 1);
AudioControl::MusicFade {
group,
gain,
frames: ms * 48,
smooth: curve != 0,
}
}
Syscall::MusicCrossfade => {
let source = uint!(0, 1) as usize;
let target = uint!(1, 1) as usize;
let ms = uint!(2, (u32::MAX / 48) as i64);
let curve = uint!(3, 1);
AudioControl::Crossfade {
source,
target,
frames: ms * 48,
smooth: curve != 0,
}
}
Syscall::AudioSetGroupVolume => AudioControl::GroupVolume {
group: uint!(0, 2) as usize,
gain: uint!(1, 255) as u8,
},
Syscall::AudioSetBusVolume => AudioControl::BusVolume {
bus: uint!(0, 2) as usize,
gain: uint!(1, 255) as u8,
},
Syscall::AudioSetSend => AudioControl::SfxSend {
voice: uint!(0, 7) as usize,
gain: uint!(1, 255) as u8,
},
Syscall::AudioSetEffect => AudioControl::Effect {
group: uint!(0, 2) as usize,
cutoff_hz: uint!(1, 24_000),
delay_frames: uint!(2, 2000) * 48,
feedback: expect_number(args, 3, "feedback")? as f32,
wet: expect_number(args, 4, "wet")? as f32,
dry: expect_number(args, 5, "dry")? as f32,
},
_ => unreachable!(),
};
platform.audio_mut().control(control)
}
};
ret.push_int(status as i64);
Ok(())
}
Syscall::FsOpen => { Syscall::FsOpen => {
let path = expect_string(args, 0, "path")?; let path = expect_string(args, 0, "path")?;
if *self.fs_state != FsState::Mounted { if *self.fs_state != FsState::Mounted {
@@ -749,6 +857,7 @@ impl NativeInterface for VmRuntimeHost<'_> {
0 => BankType::GLYPH, 0 => BankType::GLYPH,
1 => BankType::SOUNDS, 1 => BankType::SOUNDS,
2 => BankType::SCENE, 2 => BankType::SCENE,
3 => BankType::MUSIC,
other => { other => {
return Err(VmFault::Trap( return Err(VmFault::Trap(
TRAP_TYPE, TRAP_TYPE,
@@ -770,6 +879,8 @@ impl NativeInterface for VmRuntimeHost<'_> {
let asset_type = match expect_int(args, 0)? as u32 { let asset_type = match expect_int(args, 0)? as u32 {
0 => BankType::GLYPH, 0 => BankType::GLYPH,
1 => BankType::SOUNDS, 1 => BankType::SOUNDS,
2 => BankType::SCENE,
3 => BankType::MUSIC,
_ => return Err(VmFault::Trap(TRAP_TYPE, "Invalid asset type".to_string())), _ => return Err(VmFault::Trap(TRAP_TYPE, "Invalid asset type".to_string())),
}; };
let telemetry = platform let telemetry = platform
@@ -187,6 +187,16 @@ impl VirtualMachineRuntime {
self.render_worker_ownership.set(self.render_manager.active_ownership()); self.render_worker_ownership.set(self.render_manager.active_ownership());
} }
pub fn record_presented_render_worker_frame(
&self,
ownership: prometeu_hal::RenderOwnership,
frame_id: FrameId,
) {
if let Some(controller) = self.render_worker_controller.as_ref() {
controller.record_presented_frame(ownership, frame_id);
}
}
pub fn record_repeated_render_worker_frame(&self, frame_id: FrameId) { pub fn record_repeated_render_worker_frame(&self, frame_id: FrameId) {
if let Some(controller) = self.render_worker_controller.as_ref() { if let Some(controller) = self.render_worker_controller.as_ref() {
controller.record_repeated_frame(frame_id); controller.record_repeated_frame(frame_id);
@@ -25,6 +25,7 @@ impl Default for RenderWorkerConfig {
struct RenderWorkerState { struct RenderWorkerState {
telemetry: RenderWorkerTelemetry, telemetry: RenderWorkerTelemetry,
last_error: Option<RenderWorkerError>, last_error: Option<RenderWorkerError>,
last_presented: Option<(RenderOwnership, FrameId)>,
} }
#[derive(Clone, Debug, Default)] #[derive(Clone, Debug, Default)]
@@ -40,6 +41,19 @@ impl LatestRenderFrameStore {
pub fn latest_frame(&self) -> Option<OwnedRgba8888Frame> { pub fn latest_frame(&self) -> Option<OwnedRgba8888Frame> {
self.latest.lock().unwrap().clone() self.latest.lock().unwrap().clone()
} }
/// Copy only a different complete publication; paused observers need not copy pixels.
pub fn latest_frame_after(
&self,
previous: Option<(RenderOwnership, FrameId)>,
) -> Option<OwnedRgba8888Frame> {
self.latest
.lock()
.unwrap()
.as_ref()
.filter(|frame| previous != Some((frame.ownership, frame.frame_id)))
.cloned()
}
} }
impl RenderWorkerFrameSink for LatestRenderFrameStore { impl RenderWorkerFrameSink for LatestRenderFrameStore {
@@ -144,6 +158,7 @@ impl RenderWorkerController {
let mut telemetry = self.handoff.telemetry(); let mut telemetry = self.handoff.telemetry();
let state = self.state.lock().unwrap(); let state = self.state.lock().unwrap();
telemetry.published_frames = state.telemetry.published_frames; telemetry.published_frames = state.telemetry.published_frames;
telemetry.presented_frames = state.telemetry.presented_frames;
telemetry.render_failures = state.telemetry.render_failures; telemetry.render_failures = state.telemetry.render_failures;
telemetry.publish_failures = state.telemetry.publish_failures; telemetry.publish_failures = state.telemetry.publish_failures;
telemetry.present_failures = state.telemetry.present_failures; telemetry.present_failures = state.telemetry.present_failures;
@@ -166,6 +181,17 @@ impl RenderWorkerController {
self.ownership.snapshot() self.ownership.snapshot()
} }
/// Record only after a successful host presentation, never on publication.
pub fn record_presented_frame(&self, ownership: RenderOwnership, frame_id: FrameId) {
let mut state = self.state.lock().unwrap();
if state.last_presented == Some((ownership, frame_id)) {
state.telemetry.record_repeated_frame(frame_id.get());
} else {
state.telemetry.record_presented(frame_id.get());
}
state.last_presented = Some((ownership, frame_id));
}
pub fn record_repeated_frame(&self, frame_id: FrameId) { pub fn record_repeated_frame(&self, frame_id: FrameId) {
let mut state = self.state.lock().unwrap(); let mut state = self.state.lock().unwrap();
state.telemetry.record_repeated_frame(frame_id.get()); state.telemetry.record_repeated_frame(frame_id.get());
@@ -190,13 +216,13 @@ fn run_worker_loop<B, S>(
B: RenderWorkerBackend, B: RenderWorkerBackend,
S: RenderWorkerFrameSink, S: RenderWorkerFrameSink,
{ {
loop { let report_path = std::env::var_os("PROMETEU_GRAPHICS_METRICS").map(std::path::PathBuf::from);
let submission = match handoff.wait_take() { let mut measurements = Vec::new();
RenderWorkerHandoffWait::Submission(submission) => submission, let mut measured_frames = 0usize;
RenderWorkerHandoffWait::Shutdown => return, while let RenderWorkerHandoffWait::Submission(submission) = handoff.wait_take() {
};
let frame_id = submission.frame_id; let frame_id = submission.frame_id;
let render_begin = report_path.as_ref().map(|_| std::time::Instant::now());
let render_result = catch_unwind(AssertUnwindSafe(|| backend.render(&submission))) let render_result = catch_unwind(AssertUnwindSafe(|| backend.render(&submission)))
.map_err(|_| RenderWorkerError::WorkerPanic); .map_err(|_| RenderWorkerError::WorkerPanic);
let frame = match render_result { let frame = match render_result {
@@ -212,13 +238,45 @@ fn run_worker_loop<B, S>(
continue; continue;
} }
let render_us = render_begin.map(|start| start.elapsed().as_micros() as u64);
let publish_begin = report_path.as_ref().map(|_| std::time::Instant::now());
let publish_result = catch_unwind(AssertUnwindSafe(|| sink.publish(frame))) let publish_result = catch_unwind(AssertUnwindSafe(|| sink.publish(frame)))
.map_err(|_| RenderWorkerError::WorkerPanic); .map_err(|_| RenderWorkerError::WorkerPanic);
if let (Some(render_us), Some(begin)) = (render_us, publish_begin) {
let sample = (frame_id.get(), render_us, begin.elapsed().as_micros() as u64);
if measurements.len() < 16384 {
measurements.push(sample);
} else {
measurements[measured_frames % 16384] = sample;
}
measured_frames += 1;
}
match publish_result { match publish_result {
Ok(Ok(())) => record_published(&state, frame_id), Ok(Ok(())) => record_published(&state, frame_id),
Ok(Err(error)) | Err(error) => record_error(&state, error, frame_id), Ok(Err(error)) | Err(error) => record_error(&state, error, frame_id),
} }
} }
if let Some(path) = report_path {
use std::io::Write;
let worker = state.lock().unwrap();
let handoff = handoff.telemetry();
let report = serde_json::json!({"schema":1,"source":"async_render_worker",
"produced_submissions":handoff.produced_submissions,"consumed_submissions":handoff.consumed_submissions,
"replaced_before_consume":handoff.replaced_before_consume,
"published_frames":worker.telemetry.published_frames,"first_presentations":worker.telemetry.presented_frames,
"repeated_presentations":worker.telemetry.repeated_frames,
"render_failures":worker.telemetry.render_failures,"publish_failures":worker.telemetry.publish_failures,
"measured_frames":measured_frames,"samples_frame_render_publish_us":measurements,
"physical_display_hz":null,
"limitations":"last 16384 successful-render samples; render includes owned-frame copy; sink publication is not scanout; opt-in clock and storage overhead"});
if let Ok(mut file) = std::fs::OpenOptions::new()
.create(true)
.append(true)
.open(path.with_extension("renderer.jsonl"))
{
let _ = writeln!(file, "{report}");
}
}
} }
fn record_published(state: &Arc<Mutex<RenderWorkerState>>, frame_id: FrameId) { fn record_published(state: &Arc<Mutex<RenderWorkerState>>, frame_id: FrameId) {
@@ -333,6 +391,14 @@ mod tests {
SharedFakeBackend(backend), SharedFakeBackend(backend),
); );
let first_session = RenderOwnership::new(1, AppMode::Game, 7);
controller.record_presented_frame(first_session, FrameId::ZERO);
controller.record_presented_frame(first_session, FrameId::ZERO);
// Frame zero in a new epoch is a new image, not a repeat of the old session.
controller.record_presented_frame(RenderOwnership::new(2, AppMode::Game, 7), FrameId::ZERO);
assert_eq!(controller.telemetry().presented_frames, 2);
assert_eq!(controller.telemetry().repeated_frames, 1);
assert_eq!(controller.stop(), Ok(())); assert_eq!(controller.stop(), Ok(()));
assert_eq!(controller.last_error(), None); assert_eq!(controller.last_error(), None);
} }
@@ -14,13 +14,16 @@ struct Harness {
} }
impl Harness { impl Harness {
fn new(code: &str, name: &str, args: u16) -> Self { fn new(code: &str, name: &str, args: u16) -> Self {
Self::new_domain(code, "audio", name, args)
}
fn new_domain(code: &str, module: &str, name: &str, args: u16) -> Self {
let mut runtime = VirtualMachineRuntime::new(None); let mut runtime = VirtualMachineRuntime::new(None);
let mut vm = VirtualMachine::default(); let mut vm = VirtualMachine::default();
let mut log = LogService::new(4096); let mut log = LogService::new(4096);
let program = serialized_single_function_module( let program = serialized_single_function_module(
assemble(code).unwrap(), assemble(code).unwrap(),
vec![SyscallDecl { vec![SyscallDecl {
module: "audio".into(), module: module.into(),
name: name.into(), name: name.into(),
version: 1, version: 1,
arg_slots: args, arg_slots: args,
@@ -76,7 +79,7 @@ impl Harness {
fn guest_audio_status_matrix_and_type_traps() { fn guest_audio_status_matrix_and_type_traps() {
for (name, args, inputs, expected) in [ for (name, args, inputs, expected) in [
("stop", 1, "PUSH_I32 0", 0), ("stop", 1, "PUSH_I32 0", 0),
("stop", 1, "PUSH_I32 15", 0), ("stop", 1, "PUSH_I32 7", 0),
("stop", 1, "PUSH_I32 -1", 1), ("stop", 1, "PUSH_I32 -1", 1),
("stop", 1, "PUSH_I32 16", 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 0", 0),
@@ -84,7 +87,7 @@ fn guest_audio_status_matrix_and_type_traps() {
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 256", 3), ("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 0\nPUSH_I32 -1", 3),
("set_pan", 2, "PUSH_I32 16\nPUSH_I32 -1", 1), ("set_pan", 2, "PUSH_I32 16\nPUSH_I32 -1", 1),
("set_pan", 2, "PUSH_I32 15\nPUSH_I32 255", 0), ("set_pan", 2, "PUSH_I32 7\nPUSH_I32 255", 0),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 1", 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 0", 3),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 -1", 3), ("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 -1", 3),
@@ -216,3 +219,61 @@ fn normal_entry_return_is_a_successful_implicit_audio_frame() {
} }
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1); assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
} }
#[test]
fn music_and_bus_controls_resolve_with_audio_capability_and_validate_without_partial_commands() {
use prometeu_drivers::SoundBankPoolInstaller;
use prometeu_drivers::bank_format::{DecodedAudioBank, decode_audio_bank};
for (module, name, args, inputs, expected) in [
("music", "play", 3, "PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 1", 0),
("music", "play", 3, "PUSH_I32 0\nPUSH_I32 16\nPUSH_I32 1", 3),
("music", "stop", 1, "PUSH_I32 1", 0),
("music", "pause", 1, "PUSH_I32 0", 0),
("music", "resume", 1, "PUSH_I32 0", 0),
("music", "set_volume", 2, "PUSH_I32 0\nPUSH_I32 255", 0),
("music", "fade_to", 4, "PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 2000\nPUSH_I32 1", 0),
("music", "crossfade", 4, "PUSH_I32 0\nPUSH_I32 1\nPUSH_I32 2000\nPUSH_I32 0", 0),
("music", "crossfade", 4, "PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 2000\nPUSH_I32 0", 3),
("audio", "set_group_volume", 2, "PUSH_I32 2\nPUSH_I32 255", 0),
("audio", "set_bus_volume", 2, "PUSH_I32 2\nPUSH_I32 255", 0),
("audio", "set_send", 2, "PUSH_I32 7\nPUSH_I32 128", 0),
(
"audio",
"set_effect",
6,
"PUSH_I32 2\nPUSH_I32 4000\nPUSH_I32 2000\nPUSH_F64 f64:0x3fe0000000000000\nPUSH_F64 f64:0x3fd3333333333333\nPUSH_F64 f64:0x3fe6666666666666",
0,
),
(
"audio",
"set_effect",
6,
"PUSH_I32 2\nPUSH_I32 4000\nPUSH_I32 2001\nPUSH_F64 f64:0x3fe0000000000000\nPUSH_F64 f64:0x3fd3333333333333\nPUSH_F64 f64:0x3fe6666666666666",
3,
),
("audio", "unload_bank", 2, "PUSH_I32 1\nPUSH_I32 0", 0),
] {
let mut h = Harness::new_domain(
&format!("{inputs}\nHOSTCALL 0\nFRAME_SYNC\nHALT"),
module,
name,
args,
);
let bytes = include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-music.mbnk"
));
let DecodedAudioBank::Music(bank) = decode_audio_bank(bytes, true).unwrap() else {
panic!()
};
h.platform.local_hardware().memory_banks.install_music_bank(0, Arc::new(bank));
assert!(h.tick().is_none(), "{module}.{name}");
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(expected)], "{module}.{name}");
let batch = h.transport().try_take().unwrap().frame;
assert_eq!(
batch.map_or(0, |v| v.len()),
usize::from(expected == 0 && name != "unload_bank"),
"{module}.{name}"
);
}
}
@@ -107,4 +107,5 @@ mod tests {
} }
} }
pub mod memcard_fixture;
pub mod program; pub mod program;
@@ -0,0 +1,146 @@
//! Neutral PBX/ABI fixture. No source-language frontend or compiler is involved.
use crate::program::{TestProgram, scalar_catalog};
use prometeu_bytecode::{
assembler::assemble,
model::{ConstantPoolEntry, SyscallDecl},
registry::*,
};
use std::collections::BTreeMap;
#[derive(Clone, Copy)]
pub enum MemcardFixture {
Write,
Read,
ReadWithPresentation,
Dirty,
}
#[derive(Default)]
struct Code {
bytes: Vec<u8>,
labels: BTreeMap<&'static str, u32>,
fixups: Vec<(usize, &'static str)>,
}
impl Code {
fn emit(&mut self, text: &str) {
self.bytes.extend(assemble(text).expect("fixture assembly"));
}
fn mark(&mut self, name: &'static str) {
self.labels.insert(name, self.bytes.len() as u32);
}
fn jump(&mut self, op: &str, name: &'static str) {
self.fixups.push((self.bytes.len() + 2, name));
self.emit(&format!("{op} 0"));
}
fn check(&mut self, value: i64, int32: bool) {
self.emit(&format!("PUSH_{} {value}\nEQ", if int32 { "I32" } else { "I64" }));
let resume = self.bytes.len() + 8; // conditional jump followed by a terminal trap
self.emit(&format!("JMP_IF_TRUE {resume}\nTRAP"));
}
fn finish(mut self) -> Vec<u8> {
for (offset, label) in self.fixups {
self.bytes[offset..offset + 4].copy_from_slice(&self.labels[label].to_le_bytes());
}
self.bytes
}
}
/// Stack oracle at a completed frame: 100 pending, 101 durable SUCCESS,
/// 104 MEMORY_ONLY, 201 exact existing readback, 301 dirty/uncommitted RAM.
/// Read never writes or submits a commit; a missing/wrong payload traps.
pub fn memcard_program(kind: MemcardFixture) -> Vec<u8> {
let reads = matches!(kind, MemcardFixture::Read | MemcardFixture::ReadWithPresentation);
let mut main = Code::default();
main.emit("HOSTCALL 0");
main.check(0, true);
main.emit("PUSH_I64 4\nARRAY_NEW 9\nSET_GLOBAL 1");
if reads {
let read_import = if matches!(kind, MemcardFixture::Read) { 1 } else { 2 };
main.emit(&format!("GET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 4\nHOSTCALL {read_import}"));
main.check(4, false);
main.check(0, false);
for (i, value) in [0, 127, 128, 255].into_iter().enumerate() {
main.emit(&format!("GET_GLOBAL 1\nPUSH_I64 {i}\nARRAY_GET 9"));
main.check(value, true);
}
main.mark("done");
main.emit("PUSH_I64 201\nFRAME_SYNC\nPOP_N 1");
main.jump("JMP", "done");
} else {
for (i, value) in [0, 127, 128, 255].into_iter().enumerate() {
main.emit(&format!("GET_GLOBAL 1\nPUSH_I64 {i}\nPUSH_I32 {value}\nARRAY_SET 9"));
}
main.emit("GET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 4\nHOSTCALL 2");
main.check(4, false);
main.check(0, false);
if matches!(kind, MemcardFixture::Dirty) {
main.mark("done");
main.emit("PUSH_I64 301\nFRAME_SYNC\nPOP_N 1");
main.jump("JMP", "done");
} else {
main.emit("GET_GLOBAL 0\nPUSH_I32 0\nHOSTCALL 3\nSET_GLOBAL 2");
main.check(0, false);
main.mark("query");
main.emit("GET_GLOBAL 0\nGET_GLOBAL 2\nHOSTCALL 4\nPOP_N 1\nSET_GLOBAL 3");
main.check(0, false);
main.emit("GET_GLOBAL 3\nPUSH_I64 100\nADD\nFRAME_SYNC\nPOP_N 1");
main.jump("JMP", "query");
}
}
main.mark("error");
main.emit("TRAP");
let mut code = main.finish();
let main_len = code.len() as u32;
let hook = if matches!(kind, MemcardFixture::Read) {
assemble("GET_LOCAL 0\nSET_GLOBAL 0\nPUSH_I32 0\nRET").unwrap()
} else {
assemble("GET_LOCAL 0\nSET_GLOBAL 0\nPUSH_I64 560\nARRAY_NEW 9\nSET_GLOBAL 1\nGET_LOCAL 0\nPUSH_CONST 0\nPUSH_I64 1\nPUSH_I32 1\nPUSH_I32 1\nGET_GLOBAL 1\nPUSH_I32 0\nPUSH_I32 560\nHOSTCALL 1\nPOP_N 1\nPUSH_I32 0\nRET").unwrap()
};
let hook_len = hook.len() as u32;
code.extend(hook);
let mut types = scalar_catalog();
types.push(TypeDecl { name: None, kind: TypeKind::Array(TypeId(1)) });
let mut imports = vec![("bootstrap", 0, 1)];
if !matches!(kind, MemcardFixture::Read) {
imports.push(("presentation", 8, 1));
}
match kind {
MemcardFixture::Read | MemcardFixture::ReadWithPresentation => {
imports.push(("slot_read", 6, 2));
}
MemcardFixture::Dirty => imports.push(("slot_write", 6, 2)),
MemcardFixture::Write => {
imports.extend([("slot_write", 6, 2), ("slot_commit", 2, 2), ("query", 2, 3)])
}
}
let syscalls = imports
.into_iter()
.map(|(name, arg_slots, ret_slots)| SyscallDecl {
module: "mem".into(),
name: name.into(),
version: 1,
arg_slots,
ret_slots,
})
.collect();
TestProgram {
const_pool: vec![ConstantPoolEntry::String("Neutral persistence fixture".into())],
code,
functions: vec![
FunctionDecl { code_len: main_len, max_stack_slots: 32, ..Default::default() },
FunctionDecl {
lifecycle_role: LifecycleRole::MemcardBoot,
code_offset: main_len,
code_len: hook_len,
max_stack_slots: 32,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![TypeId(1)],
},
..Default::default()
},
],
syscalls,
..Default::default()
}
.serialize_with_types(types)
}
@@ -63,10 +63,13 @@ impl TestProgram {
} }
} }
pub fn serialize(&self) -> Vec<u8> { pub fn serialize(&self) -> Vec<u8> {
self.serialize_with_types(scalar_catalog())
}
pub fn serialize_with_types(&self, types: Vec<TypeDecl>) -> Vec<u8> {
let mut budget = LoadBudget::new(Default::default()); let mut budget = LoadBudget::new(Default::default());
let registry = Registry::resolve( let registry = Registry::resolve(
RegistryDeclarations { RegistryDeclarations {
types: scalar_catalog(), types,
functions: self.functions.clone(), functions: self.functions.clone(),
implementations: vec![], implementations: vec![],
}, },
@@ -0,0 +1,89 @@
//! Bounded run of the production desktop host, with normal teardown for metrics.
//! No machine timing or rendering loop is replaced by this measurement harness.
use prometeu_host_desktop_winit::{audio, fs_backend, log_sink, stats, utilities, wall_clock};
#[allow(dead_code)]
#[path = "../src/debugger.rs"]
mod debugger;
#[path = "../src/input.rs"]
mod input;
#[path = "../src/presentation_blit.rs"]
mod presentation_blit;
#[allow(dead_code)]
#[path = "../src/studio/mod.rs"]
mod studio;
#[path = "../src/viewport.rs"]
mod viewport;
// Compile the actual host implementation; its non-desktop entry points are unused
// by this executable. Keep measurement access out of the product's public API.
#[allow(dead_code)]
mod runner {
include!("../src/runner.rs");
impl HostRunner {
pub(super) fn measured_state(&mut self) -> serde_json::Value {
serde_json::json!({
"host_vm_ticks": self.firmware.os.vm().tick_index(),
"completed_vm_frames": self.firmware.os.vm().completed_logical_frames(),
"logical_frame_index": self.firmware.os.vm().logical_frame_index(),
"synchronous_publications": self.firmware.os.vm().telemetry_snapshot().presented_frames,
"front_buffer_publications": self.hardware.gfx.publication_count(),
"physical_display_hz": null,
})
}
}
}
use std::time::{Duration, Instant};
use winit::{
application::ApplicationHandler,
event::WindowEvent,
event_loop::{ActiveEventLoop, EventLoop},
window::WindowId,
};
struct Measure {
runner: runner::HostRunner,
started: Option<Instant>,
duration: Duration,
}
impl ApplicationHandler for Measure {
fn resumed(&mut self, events: &ActiveEventLoop) {
self.runner.resumed(events);
self.started = Some(Instant::now());
}
fn window_event(&mut self, events: &ActiveEventLoop, id: WindowId, event: WindowEvent) {
self.runner.window_event(events, id, event);
}
fn about_to_wait(&mut self, events: &ActiveEventLoop) {
if self.started.is_some_and(|start| start.elapsed() >= self.duration) {
events.exit();
} else {
self.runner.about_to_wait(events);
}
}
}
fn main() -> Result<(), Box<dyn std::error::Error>> {
let path = std::env::args().nth(1).expect("cartridge directory");
let seconds: u64 = std::env::args().nth(2).map(|s| s.parse().expect("seconds")).unwrap_or(10);
assert!(seconds > 0);
let mut runner = runner::HostRunner::new(None, None);
runner.set_boot_target(prometeu_firmware::BootTarget::Cartridge {
path,
debug: false,
debug_port: 0,
});
let mut app = Measure { runner, started: None, duration: Duration::from_secs(seconds) };
let mut events = EventLoop::builder();
#[cfg(target_os = "macos")]
{
use winit::platform::macos::EventLoopBuilderExtMacOS;
events.with_activate_ignoring_other_apps(true);
}
events.build()?.run_app(&mut app)?;
println!(
"{}",
serde_json::json!({"schema":1,"source":"production_desktop_host",
"elapsed_seconds":app.started.map(|s|s.elapsed().as_secs_f64()),
"state":app.runner.measured_state(),
"limitation":"includes boot, no discarded warmup; host/API submission is not physical scanout"})
);
Ok(())
}
@@ -0,0 +1,148 @@
//! GPU readback qualification of the actual host blit, not a software geometry mirror.
#[path = "../src/presentation_blit.rs"]
mod presentation_blit;
#[path = "../src/viewport.rs"]
mod viewport;
use pixels::{PixelsBuilder, SurfaceTexture, wgpu};
use winit::{
application::ApplicationHandler,
event_loop::{ActiveEventLoop, EventLoop},
window::Window,
};
#[derive(Default)]
struct Probe;
impl ApplicationHandler for Probe {
fn resumed(&mut self, events: &ActiveEventLoop) {
let window = Box::leak(Box::new(
events
.create_window(
Window::default_attributes()
.with_title("PROMETEU graphics qualification")
.with_inner_size(winit::dpi::PhysicalSize::new(640, 360)),
)
.unwrap(),
));
let size = window.inner_size();
let mut pixels =
PixelsBuilder::new(640, 360, SurfaceTexture::new(size.width, size.height, &*window))
.build()
.unwrap();
for (i, p) in pixels.frame_mut().as_chunks_mut::<4>().0.iter_mut().enumerate() {
let (x, y) = (i % 640, i / 640);
// Single-pixel checkerboard detects smoothing; all channels equal avoid channel-order ambiguity.
let value = if (x + y) % 2 == 0 { 255 } else { 0 };
p.copy_from_slice(&[value, value, value, 255]);
}
// Exercise real surface acquisition/upload/shader validation too.
let blit = presentation_blit::PresentationBlit::new(&pixels);
pixels
.render_with(|e, t, _| {
blit.render(
e,
t,
viewport::Viewport::new((size.width, size.height), (640, 360)).unwrap(),
);
Ok(())
})
.unwrap();
let ctx = pixels.context();
// A newly created macOS surface may be occluded: render_with then returns
// without uploading. Offscreen verification must establish its own input.
ctx.queue.write_texture(
wgpu::TexelCopyTextureInfo {
texture: &ctx.texture,
mip_level: 0,
origin: wgpu::Origin3d::ZERO,
aspect: wgpu::TextureAspect::All,
},
pixels.frame(),
wgpu::TexelCopyBufferLayout {
offset: 0,
bytes_per_row: Some(640 * 4),
rows_per_image: Some(360),
},
ctx.texture_extent,
);
for (w, h) in [(1280u32, 720u32), (1000, 700), (320, 240), (641, 361)] {
let view = viewport::Viewport::new((w, h), (640, 360)).unwrap();
let texture = ctx.device.create_texture(&wgpu::TextureDescriptor {
label: Some("blit-readback"),
size: wgpu::Extent3d { width: w, height: h, depth_or_array_layers: 1 },
mip_level_count: 1,
sample_count: 1,
dimension: wgpu::TextureDimension::D2,
format: pixels.render_texture_format(),
usage: wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::COPY_SRC,
view_formats: &[],
});
let stride = (w * 4).div_ceil(256) * 256;
let buffer = ctx.device.create_buffer(&wgpu::BufferDescriptor {
label: Some("readback"),
size: u64::from(stride) * u64::from(h),
usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
mapped_at_creation: false,
});
let mut encoder = ctx.device.create_command_encoder(&Default::default());
blit.render(&mut encoder, &texture.create_view(&Default::default()), view);
encoder.copy_texture_to_buffer(
wgpu::TexelCopyTextureInfo {
texture: &texture,
mip_level: 0,
origin: wgpu::Origin3d::ZERO,
aspect: wgpu::TextureAspect::All,
},
wgpu::TexelCopyBufferInfo {
buffer: &buffer,
layout: wgpu::TexelCopyBufferLayout {
offset: 0,
bytes_per_row: Some(stride),
rows_per_image: Some(h),
},
},
wgpu::Extent3d { width: w, height: h, depth_or_array_layers: 1 },
);
ctx.queue.submit([encoder.finish()]);
let (tx, rx) = std::sync::mpsc::channel();
buffer.slice(..).map_async(wgpu::MapMode::Read, move |result| tx.send(result).unwrap());
ctx.device.poll(wgpu::PollType::wait_indefinitely()).unwrap();
rx.recv().unwrap().unwrap();
let data = buffer.slice(..).get_mapped_range();
let mut checked = 0;
for y in 0..h {
for x in 0..w {
let offset = (y * stride + x * 4) as usize;
let rgb = &data[offset..offset + 3];
// Every output pixel is black or white: any intermediate value means smoothing.
assert!(
rgb == [0, 0, 0] || rgb == [255, 255, 255],
"filtered pixel at {w}x{h}:({x},{y})={rgb:?}"
);
if let Some((nx, ny)) = view.inverse(x as f64 + 0.5, y as f64 + 0.5) {
let expected = if (nx + ny) % 2 == 0 { 255 } else { 0 };
assert_eq!(
rgb, [expected; 3],
"GPU/input transform mismatch at {w}x{h}:({x},{y})"
);
checked += 1;
} else {
assert_eq!(rgb, [0, 0, 0], "bar");
}
}
}
assert!(checked > 0);
println!("GPU_NEAREST_PASS={w}x{h} checked={checked}");
}
events.exit();
}
fn window_event(
&mut self,
_: &ActiveEventLoop,
_: winit::window::WindowId,
_: winit::event::WindowEvent,
) {
}
}
fn main() {
EventLoop::new().unwrap().run_app(&mut Probe).unwrap();
}
@@ -1,10 +1,14 @@
mod reclamation; mod reclamation;
pub use reclamation::AudioReclaimer; pub use reclamation::AudioReclaimer;
use reclamation::{CallbackLane, Packet}; use reclamation::CallbackLane;
#[cfg(test)]
use reclamation::Packet;
use cpal::traits::{DeviceTrait, HostTrait, StreamTrait}; use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
use prometeu_drivers::{AudioCommand, Channel, MAX_CHANNELS, OUTPUT_SAMPLE_RATE}; use prometeu_drivers::AudioTransport;
use prometeu_drivers::{AudioDelivery, AudioTransport}; use prometeu_drivers::OUTPUT_SAMPLE_RATE;
pub use prometeu_drivers::engine::AudioMixer;
#[cfg(test)]
use prometeu_hal::LoopMode; use prometeu_hal::LoopMode;
use ringbuf::HeapRb; use ringbuf::HeapRb;
use ringbuf::traits::{Consumer, Producer, Split}; use ringbuf::traits::{Consumer, Producer, Split};
@@ -243,6 +247,9 @@ impl AudioCallback {
let (lane, reclaimer) = reclamation::pool(); let (lane, reclaimer) = reclamation::pool();
(Self { mixer: AudioMixer::new(), lane }, reclaimer) (Self { mixer: AudioMixer::new(), lane }, reclaimer)
} }
pub fn diagnostics(&self) -> prometeu_drivers::engine::AudioDiagnostics {
self.mixer.diagnostics
}
pub fn render(&mut self, transport: &AudioTransport, data: &mut [f32]) { pub fn render(&mut self, transport: &AudioTransport, data: &mut [f32]) {
let mut packet = self.lane.take(); let mut packet = self.lane.take();
if let Some(packet) = &mut packet { if let Some(packet) = &mut packet {
@@ -380,201 +387,6 @@ mod tests {
} }
} }
pub struct AudioMixer {
voices: [Channel; MAX_CHANNELS],
pub last_processing_time: Duration,
paused: bool,
epoch: u64,
}
impl Default for AudioMixer {
fn default() -> Self {
Self::new()
}
}
impl AudioMixer {
pub fn new() -> Self {
Self {
voices: Default::default(),
last_processing_time: Duration::ZERO,
paused: false,
epoch: 0,
}
}
fn apply_delivery_into(&mut self, delivery: AudioDelivery, packet: &mut Packet) {
if delivery.epoch < self.epoch {
packet.batches = [delivery.frame, delivery.lifecycle];
return;
}
if delivery.epoch != self.epoch {
for voice in &mut self.voices {
packet.retire(voice.sample.take());
*voice = Channel::default();
}
self.epoch = delivery.epoch;
}
for (slot, batch) in packet.batches.iter_mut().zip([delivery.frame, delivery.lifecycle]) {
*slot = batch;
}
// Move commands out of slots, keeping each vector allocation in its packet.
for index in 0..2 {
if let Some(mut batch) = packet.batches[index].take() {
for command in &mut batch {
let command =
std::mem::replace(command, AudioCommand::Stop { voice_id: MAX_CHANNELS });
self.process_command(command, packet);
}
packet.batches[index] = Some(batch);
}
}
self.paused = delivery.paused;
}
fn retire_inactive(&mut self, packet: &mut Packet) {
for voice in &mut self.voices {
if !voice.active {
packet.retire(voice.sample.take());
}
}
}
// Signal-only tests use synchronous reclamation outside a data callback.
#[cfg(test)]
fn apply_delivery(&mut self, delivery: AudioDelivery) {
self.apply_delivery_into(delivery, &mut Packet::new());
}
#[cfg(test)]
fn fill_buffer(&mut self, buffer: &mut [f32]) {
self.mix(buffer);
self.retire_inactive(&mut Packet::new());
}
fn process_command(&mut self, cmd: AudioCommand, packet: &mut Packet) {
match cmd {
AudioCommand::Play { sample, voice_id, volume, pan, pitch, priority, loop_mode } => {
if voice_id < MAX_CHANNELS {
packet.retire(self.voices[voice_id].sample.take());
self.voices[voice_id] = Channel {
sample: Some(sample),
active: true,
pos: 0.0,
pitch,
volume,
pan,
loop_mode,
priority,
};
} else {
packet.retire(Some(sample));
}
}
AudioCommand::Stop { voice_id } => {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].active = false;
packet.retire(self.voices[voice_id].sample.take());
}
}
AudioCommand::SetVolume { voice_id, volume } => {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].volume = volume;
}
}
AudioCommand::SetPan { voice_id, pan } => {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].pan = pan;
}
}
AudioCommand::SetPitch { voice_id, pitch } => {
if voice_id < MAX_CHANNELS {
self.voices[voice_id].pitch = pitch;
}
}
}
}
fn mix(&mut self, buffer: &mut [f32]) {
let start = std::time::Instant::now();
// Zeroes the buffer (stereo)
for sample in buffer.iter_mut() {
*sample = 0.0;
}
if self.paused {
self.last_processing_time = start.elapsed();
return;
}
for voice in self.voices.iter_mut() {
if !voice.active {
continue;
}
let Some(sample) = voice.sample.as_ref() else {
continue;
};
let len = sample.data.len();
if len == 0 {
voice.active = false;
continue;
}
let (loop_start, end) = match (voice.loop_mode, sample.loop_start, sample.loop_end) {
(LoopMode::On, Some(start), Some(end)) if start < end && end as usize <= len => {
(start as f64, end as f64)
}
_ => (0.0, len as f64),
};
let ratio = sample.sample_rate as f64 / OUTPUT_SAMPLE_RATE as f64;
let volume = voice.volume as f32 / 255.0;
let pan = voice.pan as f32 / 255.0;
let left = volume * (1.0 - pan).sqrt();
let right = volume * pan.sqrt();
for frame in buffer.as_chunks_mut::<2>().0 {
let pos = voice.pos as usize;
if pos >= len {
voice.active = false;
break;
}
let s1 = sample.data[pos] as f32 / 32768.0;
let next = if voice.loop_mode == LoopMode::On && (pos + 1) as f64 >= end {
loop_start as usize
} else {
pos + 1
};
let s2 = sample.data.get(next).copied().unwrap_or(0) as f32 / 32768.0;
let value = s1 + (s2 - s1) * (voice.pos - pos as f64) as f32;
frame[0] += value * left;
frame[1] += value * right;
if ratio == 0.0 {
continue;
}
if voice.pitch >= (end - voice.pos) / ratio {
if voice.loop_mode == LoopMode::Off {
voice.active = false;
break;
}
let length = end - loop_start;
// Reduce before multiplication: every finite positive pitch,
// including f64::MAX, remains finite and wraps multiple loops.
let step = (voice.pitch % (length / ratio)) * ratio;
voice.pos = loop_start + (voice.pos - loop_start + step).rem_euclid(length);
if voice.pos >= end {
voice.pos = loop_start;
}
} else {
voice.pos += voice.pitch * ratio;
}
}
}
// Final clamp to avoid clipping (optional if using f32, but good for fidelity)
for sample in buffer.iter_mut() {
*sample = sample.clamp(-1.0, 1.0);
}
self.last_processing_time = start.elapsed();
}
}
#[cfg(test)] #[cfg(test)]
mod control_tests { mod control_tests {
use super::*; use super::*;
@@ -622,8 +434,8 @@ mod control_tests {
for (frame, value) in pcm.as_chunks::<2>().0.iter().zip(expected) { for (frame, value) in pcm.as_chunks::<2>().0.iter().zip(expected) {
assert_eq!(*frame, [value as f32 / 32768.0, 0.0]); assert_eq!(*frame, [value as f32 / 32768.0, 0.0]);
} }
assert_eq!(mixer.voices[0].active, looping); assert_eq!(mixer.voices[24].active, looping);
assert_eq!(mixer.voices[0].sample.is_some(), looping); assert_eq!(mixer.voices[24].sample.is_some(), looping);
} }
} }
@@ -653,7 +465,7 @@ mod control_tests {
let value = if looping || i < 4 { (i % 4 + 1) as f32 / 8.0 } else { 0.0 }; let value = if looping || i < 4 { (i % 4 + 1) as f32 / 8.0 } else { 0.0 };
assert_eq!(*frame, [value, 0.0], "markers {start:?}/{end:?}, loop {looping}"); assert_eq!(*frame, [value, 0.0], "markers {start:?}/{end:?}, loop {looping}");
} }
assert_eq!(mixer.voices[0].active, looping); assert_eq!(mixer.voices[24].active, looping);
} }
} }
} }
@@ -683,7 +495,7 @@ mod control_tests {
assert!((frame[0] - value).abs() <= 1e-6); assert!((frame[0] - value).abs() <= 1e-6);
assert_eq!(frame[1], 0.0); assert_eq!(frame[1], 0.0);
} }
assert_eq!(mixer.voices[0].active, looping); assert_eq!(mixer.voices[24].active, looping);
} }
} }
} }
@@ -701,8 +513,8 @@ mod control_tests {
let mut pcm = [1.0; 8]; let mut pcm = [1.0; 8];
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.0; 8]); assert_eq!(pcm, [0.0; 8]);
assert!(!mixer.voices[0].active); assert!(!mixer.voices[24].active);
assert!(mixer.voices[0].sample.is_none()); assert!(mixer.voices[24].sample.is_none());
} }
} }
} }
@@ -722,7 +534,7 @@ mod control_tests {
let mut pcm = [0.0; 10]; let mut pcm = [0.0; 10];
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.125, 0.0, 0.25, 0.0, 0.5, 0.0, 0.25, 0.0, 0.5, 0.0]); assert_eq!(pcm, [0.125, 0.0, 0.25, 0.0, 0.5, 0.0, 0.25, 0.0, 0.5, 0.0]);
assert_eq!(mixer.voices[0].pos, 1.0); assert_eq!(mixer.voices[24].pos, 1.0);
} }
} }
@@ -742,12 +554,12 @@ mod control_tests {
let mut pcm = [0.0; 128]; let mut pcm = [0.0; 128];
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert!(pcm.iter().all(|value| value.is_finite())); assert!(pcm.iter().all(|value| value.is_finite()));
assert!(mixer.voices[0].pos.is_finite()); assert!(mixer.voices[24].pos.is_finite());
if rate == 0 { if rate == 0 {
assert_eq!(mixer.voices[0].pos, 0.0); assert_eq!(mixer.voices[24].pos, 0.0);
assert!(pcm.as_chunks::<2>().0.iter().all(|frame| *frame == [0.125, 0.0])); assert!(pcm.as_chunks::<2>().0.iter().all(|frame| *frame == [0.125, 0.0]));
} else if looping { } else if looping {
assert!((1.0..3.0).contains(&mixer.voices[0].pos)); assert!((1.0..3.0).contains(&mixer.voices[24].pos));
assert!( assert!(
pcm.as_chunks::<2>() pcm.as_chunks::<2>()
.0 .0
@@ -759,7 +571,7 @@ mod control_tests {
assert_eq!(&pcm[..2], &[0.125, 0.0]); assert_eq!(&pcm[..2], &[0.125, 0.0]);
assert!(pcm[2..].iter().all(|value| *value == 0.0)); assert!(pcm[2..].iter().all(|value| *value == 0.0));
} }
assert_eq!(mixer.voices[0].active, looping || rate == 0); assert_eq!(mixer.voices[24].active, looping || rate == 0);
} }
} }
} }
@@ -773,29 +585,29 @@ mod control_tests {
let mut pcm = [0.0; 4]; let mut pcm = [0.0; 4];
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.5, 0.0, 0.5, 0.0]); assert_eq!(pcm, [0.5, 0.0, 0.5, 0.0]);
assert_eq!(mixer.voices[0].pos, 2.0); assert_eq!(mixer.voices[24].pos, 2.0);
audio.set_pan(0, 255); audio.set_pan(0, 255);
audio.set_volume(0, 51); audio.set_volume(0, 51);
audio.set_pitch(0, 2.0); audio.set_pitch(0, 2.0);
audio.finish_frame(); audio.finish_frame();
apply(&audio, &mut mixer); apply(&audio, &mut mixer);
assert_eq!(mixer.voices[0].pos, 2.0); assert_eq!(mixer.voices[24].pos, 2.0);
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.0, 0.1, 0.0, 0.1]); assert_eq!(pcm, [0.0, 0.1, 0.0, 0.1]);
assert_eq!(mixer.voices[0].pos, 6.0); assert_eq!(mixer.voices[24].pos, 6.0);
audio.set_volume(0, 0); audio.set_volume(0, 0);
audio.finish_frame(); audio.finish_frame();
apply(&audio, &mut mixer); apply(&audio, &mut mixer);
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.0; 4]); assert_eq!(pcm, [0.0; 4]);
assert_eq!(mixer.voices[0].pos, 10.0); assert_eq!(mixer.voices[24].pos, 10.0);
audio.stop(0); audio.stop(0);
audio.stop(0); audio.stop(0);
audio.finish_frame(); audio.finish_frame();
apply(&audio, &mut mixer); apply(&audio, &mut mixer);
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.0; 4]); assert_eq!(pcm, [0.0; 4]);
assert!(mixer.voices[0].sample.is_none()); assert!(mixer.voices[24].sample.is_none());
} }
#[test] #[test]
@@ -811,7 +623,7 @@ mod control_tests {
let mut pcm = [0.0; 2]; let mut pcm = [0.0; 2];
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.25, 0.0]); assert_eq!(pcm, [0.25, 0.0]);
assert_eq!(mixer.voices[0].pos, 1.0); assert_eq!(mixer.voices[24].pos, 1.0);
} }
#[test] #[test]
@@ -825,7 +637,7 @@ mod control_tests {
let mut pcm = [1.0; 4]; let mut pcm = [1.0; 4];
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.0; 4]); assert_eq!(pcm, [0.0; 4]);
assert_eq!(mixer.voices[0].pos, 0.0); assert_eq!(mixer.voices[24].pos, 0.0);
audio.begin_lifecycle(); audio.begin_lifecycle();
audio.set_pan(0, 255); audio.set_pan(0, 255);
audio.finish_lifecycle(true); audio.finish_lifecycle(true);
@@ -833,7 +645,7 @@ mod control_tests {
apply(&audio, &mut mixer); apply(&audio, &mut mixer);
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.0, 0.5, 0.0, 0.5]); assert_eq!(pcm, [0.0, 0.5, 0.0, 0.5]);
assert_eq!(mixer.voices[0].pos, 2.0); assert_eq!(mixer.voices[24].pos, 2.0);
play(&mut audio, Arc::new(Sample::new(48_000, vec![16384; 16])), 1.0, true); play(&mut audio, Arc::new(Sample::new(48_000, vec![16384; 16])), 1.0, true);
audio.finish_frame(); audio.finish_frame();
let stale = audio.transport().try_take().unwrap(); let stale = audio.transport().try_take().unwrap();
@@ -854,7 +666,7 @@ mod control_tests {
audio.stop(0); audio.stop(0);
audio.finish_lifecycle(true); audio.finish_lifecycle(true);
apply(&audio, &mut mixer); apply(&audio, &mut mixer);
assert!(mixer.voices[0].sample.is_none()); assert!(mixer.voices[24].sample.is_none());
audio.begin_lifecycle(); audio.begin_lifecycle();
audio.finish_lifecycle(true); audio.finish_lifecycle(true);
audio.set_paused(false); audio.set_paused(false);
@@ -866,7 +678,7 @@ mod control_tests {
apply(&audio, &mut mixer); apply(&audio, &mut mixer);
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm, [0.0; 16]); assert_eq!(pcm, [0.0; 16]);
assert!(mixer.voices[0].sample.is_none()); assert!(mixer.voices[24].sample.is_none());
} }
#[test] #[test]
@@ -885,8 +697,8 @@ mod control_tests {
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert!(pcm.iter().all(|v| v.is_finite())); assert!(pcm.iter().all(|v| v.is_finite()));
assert!(pcm.as_chunks::<2>().0.iter().all(|frame| *frame == [0.5, 0.0])); assert!(pcm.as_chunks::<2>().0.iter().all(|frame| *frame == [0.5, 0.0]));
assert!(mixer.voices[0].active); assert!(mixer.voices[24].active);
assert!(mixer.voices[0].pos >= 1.0 && mixer.voices[0].pos < 3.0); assert!(mixer.voices[24].pos >= 1.0 && mixer.voices[24].pos < 3.0);
} }
let (mut audio, mut mixer) = pair(); let (mut audio, mut mixer) = pair();
let sample = Arc::new(Sample::new(48_000, vec![16384])); let sample = Arc::new(Sample::new(48_000, vec![16384]));
@@ -899,7 +711,7 @@ mod control_tests {
} }
#[test] #[test]
fn unloading_bank_keeps_playback_until_stop() { fn unloading_bank_stops_playback_and_rejects_stale_play() {
use prometeu_drivers::SoundBankPoolInstaller; use prometeu_drivers::SoundBankPoolInstaller;
use prometeu_hal::sound_bank::SoundBank; use prometeu_hal::sound_bank::SoundBank;
let banks = Arc::new(MemoryBanks::new()); let banks = Arc::new(MemoryBanks::new());
@@ -914,8 +726,8 @@ mod control_tests {
apply(&audio, &mut mixer); apply(&audio, &mut mixer);
let mut pcm = [0.0; 8]; let mut pcm = [0.0; 8];
mixer.fill_buffer(&mut pcm); mixer.fill_buffer(&mut pcm);
assert_eq!(pcm[0], 0.5); assert_eq!(pcm[0], 0.0);
assert!(weak.upgrade().is_some()); assert!(weak.upgrade().is_none());
assert_eq!(audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::On), AudioOpStatus::BankInvalid); assert_eq!(audio.play(0, 0, 0, 255, 0, 1.0, 0, LoopMode::On), AudioOpStatus::BankInvalid);
audio.stop(0); audio.stop(0);
audio.finish_frame(); audio.finish_frame();
@@ -1,40 +1,16 @@
//! Two packets circulate free -> callback -> returned -> service -> free. //! Two packets circulate free -> callback -> returned -> service -> free.
//! While the callback owns a packet, at most one packet can occupy the return //! While the callback owns a packet, at most one packet can occupy the return
//! lane, so its capacity-two enqueue cannot fail. Neither lane grows. //! lane, so its capacity-two enqueue cannot fail. Neither lane grows.
use prometeu_drivers::{AudioCommand, AudioTransport, MAX_CHANNELS, MAX_COMMANDS_PER_FRAME}; use prometeu_drivers::AudioTransport;
use prometeu_hal::sample::Sample; pub(super) use prometeu_drivers::engine::Packet;
#[cfg(test)]
use prometeu_drivers::engine::RETIRED_CAPACITY;
use ringbuf::{ use ringbuf::{
HeapRb, HeapRb,
traits::{Consumer, Producer, Split}, traits::{Consumer, Producer, Split},
wrap::{CachingCons, CachingProd}, wrap::{CachingCons, CachingProd},
}; };
use std::sync::Arc; use std::sync::Arc;
pub(super) const RETIRED_CAPACITY: usize = 3 * MAX_COMMANDS_PER_FRAME + MAX_CHANNELS;
pub(super) struct Packet {
retired: Vec<Arc<Sample>>,
pub batches: [Option<Vec<AudioCommand>>; 2],
}
impl Packet {
pub(super) fn new() -> Self {
Self { retired: Vec::with_capacity(RETIRED_CAPACITY), batches: [None, None] }
}
pub(super) fn retire(&mut self, sample: Option<Arc<Sample>>) {
if let Some(sample) = sample {
// Every owner comes from at most 3072 Play commands or 16 slots.
assert!(self.retired.len() < RETIRED_CAPACITY, "audio retirement bound");
self.retired.push(sample);
}
}
fn recycle(&mut self, transport: &AudioTransport) {
self.retired.clear();
for batch in &mut self.batches {
if let Some(batch) = batch.take() {
transport.recycle_commands(batch);
}
}
}
}
type Prod = CachingProd<Arc<HeapRb<Packet>>>; type Prod = CachingProd<Arc<HeapRb<Packet>>>;
type Cons = CachingCons<Arc<HeapRb<Packet>>>; type Cons = CachingCons<Arc<HeapRb<Packet>>>;
pub(super) struct CallbackLane { pub(super) struct CallbackLane {
@@ -43,6 +19,7 @@ pub(super) struct CallbackLane {
} }
/// Main-thread endpoint. Service independently of guest progress or pause. /// Main-thread endpoint. Service independently of guest progress or pause.
pub struct AudioReclaimer { pub struct AudioReclaimer {
pub maximum_retired_pcm_bytes: usize,
free: Prod, free: Prod,
returned: Cons, returned: Cons,
} }
@@ -52,7 +29,10 @@ pub(super) fn pool() -> (CallbackLane, AudioReclaimer) {
for _ in 0..2 { for _ in 0..2 {
assert!(free.try_push(Packet::new()).is_ok()); assert!(free.try_push(Packet::new()).is_ok());
} }
(CallbackLane { free: free_cons, returned }, AudioReclaimer { free, returned: returned_cons }) (
CallbackLane { free: free_cons, returned },
AudioReclaimer { free, returned: returned_cons, maximum_retired_pcm_bytes: 0 },
)
} }
impl CallbackLane { impl CallbackLane {
pub(super) fn take(&mut self) -> Option<Packet> { pub(super) fn take(&mut self) -> Option<Packet> {
@@ -66,6 +46,8 @@ impl CallbackLane {
impl AudioReclaimer { impl AudioReclaimer {
pub fn service(&mut self, transport: &AudioTransport) { pub fn service(&mut self, transport: &AudioTransport) {
while let Some(mut packet) = self.returned.try_pop() { while let Some(mut packet) = self.returned.try_pop() {
self.maximum_retired_pcm_bytes =
self.maximum_retired_pcm_bytes.max(packet.retained_pcm_bytes());
packet.recycle(transport); packet.recycle(transport);
assert!(self.free.try_push(packet).is_ok(), "audio packet conservation"); assert!(self.free.try_push(packet).is_ok(), "audio packet conservation");
} }
@@ -89,8 +71,8 @@ mod tests {
service.service(&transport); service.service(&transport);
for _ in 0..2 { for _ in 0..2 {
let packet = callback.take().unwrap(); let packet = callback.take().unwrap();
assert_eq!(packet.retired.capacity(), RETIRED_CAPACITY); assert_eq!(packet.capacity(), RETIRED_CAPACITY);
assert!(packet.retired.is_empty()); assert!(packet.is_empty());
assert!(packet.batches.iter().all(Option::is_none)); assert!(packet.batches.iter().all(Option::is_none));
callback.give_back(packet); callback.give_back(packet);
} }
@@ -3,48 +3,11 @@ use winit::event::{ElementState, MouseButton, WindowEvent};
use winit::keyboard::{KeyCode, PhysicalKey}; use winit::keyboard::{KeyCode, PhysicalKey};
use winit::window::Window; use winit::window::Window;
#[derive(Debug, Clone, Copy)]
struct FbViewport {
pub x: f32,
pub y: f32,
pub w: f32,
pub h: f32,
pub scale: f32,
}
impl FbViewport {
fn framebuffer_viewport(window: &Window, display_size: (usize, usize)) -> Option<FbViewport> {
let size = window.inner_size();
let win_w = size.width as f32;
let win_h = size.height as f32;
if win_w <= 0.0 || win_h <= 0.0 {
return None;
}
let fb_w = display_size.0 as f32;
let fb_h = display_size.1 as f32;
let scale_x = (win_w / fb_w).floor();
let scale_y = (win_h / fb_h).floor();
let scale = scale_x.min(scale_y).max(1.0);
let viewport_w = fb_w * scale;
let viewport_h = fb_h * scale;
let viewport_x = ((win_w - viewport_w) * 0.5).floor();
let viewport_y = ((win_h - viewport_h) * 0.5).floor();
Some(FbViewport { x: viewport_x, y: viewport_y, w: viewport_w, h: viewport_h, scale })
}
}
pub struct HostInputHandler { pub struct HostInputHandler {
pub signals: InputSignals, pub signals: InputSignals,
system_controls: HostSystemControls, system_controls: HostSystemControls,
display_size: (usize, usize), display_size: (usize, usize),
cursor: Option<(f64, f64)>,
} }
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)] #[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
@@ -66,7 +29,7 @@ impl HostSystemControls {
impl Default for HostInputHandler { impl Default for HostInputHandler {
fn default() -> Self { fn default() -> Self {
Self::new((480, 270)) Self::new((prometeu_hal::graphics_contract::WIDTH, prometeu_hal::graphics_contract::HEIGHT))
} }
} }
@@ -76,6 +39,7 @@ impl HostInputHandler {
signals: InputSignals::default(), signals: InputSignals::default(),
system_controls: HostSystemControls::default(), system_controls: HostSystemControls::default(),
display_size, display_size,
cursor: None,
} }
} }
@@ -121,50 +85,34 @@ impl HostInputHandler {
} }
WindowEvent::CursorMoved { position, .. } => { WindowEvent::CursorMoved { position, .. } => {
if let Some((x, y)) = self.cursor = Some((position.x, position.y));
window_to_fb(position.x as f32, position.y as f32, window, self.display_size) let size = window.inner_size();
{ self.update_pointer((size.width, size.height));
self.signals.x_pos = x;
self.signals.y_pos = y;
} }
} WindowEvent::CursorLeft { .. } | WindowEvent::Focused(false) => {
WindowEvent::MouseInput { state, button, .. } if *button == MouseButton::Left => {
match state {
ElementState::Pressed => {
self.signals.f_signal = true;
}
ElementState::Released => {
self.signals.f_signal = false; self.signals.f_signal = false;
self.cursor = None;
} }
} WindowEvent::Resized(size) => self.update_pointer((size.width, size.height)),
WindowEvent::MouseInput { state, button, .. } if *button == MouseButton::Left => {
let size = window.inner_size();
let inside = self.pointer_position((size.width, size.height)).is_some();
self.signals.f_signal = *state == ElementState::Pressed && inside;
} }
_ => {} _ => {}
} }
fn window_to_fb(
wx: f32,
wy: f32,
window: &Window,
display_size: (usize, usize),
) -> Option<(i32, i32)> {
let viewport = FbViewport::framebuffer_viewport(window, display_size)?;
let local_x = wx - viewport.x;
let local_y = wy - viewport.y;
if local_x < 0.0 || local_y < 0.0 || local_x >= viewport.w || local_y >= viewport.h {
return None;
} }
fn pointer_position(&self, surface: (u32, u32)) -> Option<(i32, i32)> {
let fb_x = (local_x / viewport.scale).floor() as i32; let (x, y) = self.cursor?;
let fb_y = (local_y / viewport.scale).floor() as i32; crate::viewport::Viewport::new(surface, self.display_size)?.inverse(x, y)
}
Some(( fn update_pointer(&mut self, surface: (u32, u32)) {
fb_x.clamp(0, display_size.0 as i32 - 1), if let Some((x, y)) = self.pointer_position(surface) {
fb_y.clamp(0, display_size.1 as i32 - 1), self.signals.x_pos = x;
)) self.signals.y_pos = y;
} else {
self.signals.f_signal = false;
} }
} }
} }
@@ -173,6 +121,23 @@ impl HostInputHandler {
mod tests { mod tests {
use super::*; use super::*;
#[test]
fn drag_cancels_outside_and_cannot_recapture_on_reentry() {
let mut input = HostInputHandler {
cursor: Some((200.0, 200.0)),
signals: InputSignals { f_signal: true, ..Default::default() },
..Default::default()
};
input.update_pointer((1000, 700));
assert_eq!((input.signals.x_pos, input.signals.y_pos), (20, 30));
input.cursor = Some((10.0, 200.0)); // left letterbox
input.update_pointer((1000, 700));
assert!(!input.signals.f_signal);
input.cursor = Some((200.0, 200.0));
input.update_pointer((1000, 700));
assert!(!input.signals.f_signal);
}
fn assert_no_pad_signal(signals: InputSignals) { fn assert_no_pad_signal(signals: InputSignals) {
assert!(!signals.up_signal); assert!(!signals.up_signal);
assert!(!signals.down_signal); assert!(!signals.down_signal);
@@ -4,9 +4,12 @@ pub mod debugger;
pub mod fs_backend; pub mod fs_backend;
pub mod input; pub mod input;
pub mod log_sink; pub mod log_sink;
mod presentation_blit;
pub mod runner; pub mod runner;
pub mod stats; pub mod stats;
pub mod studio;
pub mod utilities; pub mod utilities;
mod viewport;
pub mod wall_clock; pub mod wall_clock;
use cap::load_cap_config; use cap::load_cap_config;
@@ -18,6 +21,9 @@ use winit::event_loop::EventLoop;
#[derive(Parser, Debug)] #[derive(Parser, Debug)]
#[command(author, version, about, long_about = None)] #[command(author, version, about, long_about = None)]
struct Cli { struct Cli {
/// Run an interactive Studio session without creating a desktop window.
#[arg(long, requires = "run", conflicts_with = "debug")]
studio: bool,
/// Run a cartridge /// Run a cartridge
#[arg(long, value_name = "PATH", conflicts_with = "debug")] #[arg(long, value_name = "PATH", conflicts_with = "debug")]
run: Option<String>, run: Option<String>,
@@ -54,6 +60,23 @@ struct Cli {
pub fn run() -> Result<(), Box<dyn std::error::Error>> { pub fn run() -> Result<(), Box<dyn std::error::Error>> {
let cli = Cli::parse(); let cli = Cli::parse();
if cli.studio {
let bootstrap = studio::wire::Bootstrap::read(std::io::stdin().lock())?;
let mut runner =
HostRunner::new(cli.fs_root, cli.cap.as_ref().and_then(|path| load_cap_config(path)));
if let Some(path) = cli.memcard {
runner
.install_memcard(path, cli.create_memcard)
.map_err(|e| format!("Cannot install memory card: {e:?}"))?;
}
runner.set_boot_target(BootTarget::Cartridge {
path: cli.run.expect("--studio requires --run"),
debug: false,
debug_port: 0,
});
return studio::run(runner, bootstrap).map_err(Into::into);
}
let fs_root = cli.fs_root; let fs_root = cli.fs_root;
let cap_config = cli.cap.as_ref().and_then(|path| load_cap_config(path)); let cap_config = cli.cap.as_ref().and_then(|path| load_cap_config(path));
@@ -0,0 +1,107 @@
//! Host-only blit: pixels' built-in PixelPerfect path crops below 1x and Fill smooths.
use crate::viewport::Viewport;
use pixels::{Pixels, wgpu};
pub(crate) struct PresentationBlit {
pipeline: wgpu::RenderPipeline,
texture: wgpu::BindGroup,
geometry: wgpu::Buffer,
queue: wgpu::Queue,
}
impl PresentationBlit {
pub fn new(pixels: &Pixels<'_>) -> Self {
let device = pixels.device();
let shader = device.create_shader_module(wgpu::ShaderModuleDescriptor {
label: Some("native-nearest-blit"),
source: wgpu::ShaderSource::Wgsl(
r#"
struct Vertex { @builtin(position) position: vec4f, @location(0) uv: vec2f }
@vertex fn vs(@builtin(vertex_index) i: u32) -> Vertex {
let p = array<vec2f,3>(vec2f(-1,-1),vec2f(3,-1),vec2f(-1,3));
var v: Vertex; v.position=vec4f(p[i],0,1); v.uv=vec2f((p[i].x+1)*0.5,(1-p[i].y)*0.5); return v;
}
@group(0) @binding(0) var image: texture_2d<f32>;
@group(0) @binding(1) var<uniform> geometry: vec4f;
@fragment fn fs(v: Vertex) -> @location(0) vec4f {
let size=vec2i(textureDimensions(image));
let pixel=clamp(vec2i(floor((v.position.xy-geometry.xy)/geometry.z)),vec2i(0),size-vec2i(1));
return textureLoad(image,pixel,0);
}"#
.into(),
),
});
let pipeline = device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
label: Some("native-nearest-blit"),
layout: None,
vertex: wgpu::VertexState {
module: &shader,
entry_point: Some("vs"),
buffers: &[],
compilation_options: Default::default(),
},
fragment: Some(wgpu::FragmentState {
module: &shader,
entry_point: Some("fs"),
compilation_options: Default::default(),
targets: &[Some(wgpu::ColorTargetState {
format: pixels.render_texture_format(),
blend: Some(wgpu::BlendState::ALPHA_BLENDING),
write_mask: wgpu::ColorWrites::ALL,
})],
}),
primitive: Default::default(),
depth_stencil: None,
multisample: Default::default(),
multiview_mask: None,
cache: None,
});
let view = pixels.context().texture.create_view(&Default::default());
let geometry = device.create_buffer(&wgpu::BufferDescriptor {
label: Some("native-viewport"),
size: 16,
usage: wgpu::BufferUsages::UNIFORM | wgpu::BufferUsages::COPY_DST,
mapped_at_creation: false,
});
let texture = device.create_bind_group(&wgpu::BindGroupDescriptor {
label: Some("native-nearest-texture"),
layout: &pipeline.get_bind_group_layout(0),
entries: &[
wgpu::BindGroupEntry {
binding: 0,
resource: wgpu::BindingResource::TextureView(&view),
},
wgpu::BindGroupEntry { binding: 1, resource: geometry.as_entire_binding() },
],
});
Self { pipeline, texture, geometry, queue: pixels.context().queue.clone() }
}
pub fn render(
&self,
encoder: &mut wgpu::CommandEncoder,
target: &wgpu::TextureView,
viewport: Viewport,
) {
let geometry = [viewport.x, viewport.y, viewport.scale, 0.0].map(f32::to_ne_bytes);
self.queue.write_buffer(&self.geometry, 0, geometry.as_flattened());
let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
label: Some("native-nearest-present"),
color_attachments: &[Some(wgpu::RenderPassColorAttachment {
view: target,
resolve_target: None,
ops: wgpu::Operations {
load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
store: wgpu::StoreOp::Store,
},
depth_slice: None,
})],
depth_stencil_attachment: None,
timestamp_writes: None,
occlusion_query_set: None,
multiview_mask: None,
});
pass.set_pipeline(&self.pipeline);
pass.set_bind_group(0, &self.texture, &[]);
pass.set_viewport(viewport.x, viewport.y, viewport.width, viewport.height, 0.0, 1.0);
pass.draw(0..3, 0..1);
}
}
@@ -118,6 +118,7 @@ pub struct HostRunner {
window: Option<&'static Window>, window: Option<&'static Window>,
/// The pixel buffer interface for rendering to the GPU. /// The pixel buffer interface for rendering to the GPU.
pixels: Option<Pixels<'static>>, pixels: Option<Pixels<'static>>,
blit: Option<crate::presentation_blit::PresentationBlit>,
/// The instance of the virtual hardware peripherals. /// The instance of the virtual hardware peripherals.
hardware: Hardware, hardware: Hardware,
@@ -151,6 +152,7 @@ pub struct HostRunner {
render_frame_store: LatestRenderFrameStore, render_frame_store: LatestRenderFrameStore,
/// Tracks whether a new logical frame or host-only surface invalidation requires presentation. /// Tracks whether a new logical frame or host-only surface invalidation requires presentation.
presentation: PresentationState, presentation: PresentationState,
studio_capture: bool,
} }
impl HostRunner { impl HostRunner {
@@ -194,7 +196,7 @@ impl HostRunner {
/// Creates a new desktop runner instance. /// Creates a new desktop runner instance.
pub(crate) fn new(fs_root: Option<String>, cap_config: Option<CertificationConfig>) -> Self { pub(crate) fn new(fs_root: Option<String>, cap_config: Option<CertificationConfig>) -> Self {
let target_fps = 60; let target_fps = prometeu_hal::graphics_contract::REFRESH_HZ;
let mut firmware = Firmware::new(cap_config); let mut firmware = Firmware::new(cap_config);
if let Some(root) = &fs_root { if let Some(root) = &fs_root {
@@ -224,12 +226,13 @@ impl HostRunner {
Self { Self {
window: None, window: None,
pixels: None, pixels: None,
blit: None,
hardware, hardware,
firmware, firmware,
input: HostInputHandler::new(display_size), input: HostInputHandler::new(display_size),
fs_root, fs_root,
log_sink: HostConsoleSink::new(), log_sink: HostConsoleSink::new(),
frame_target_dt: Duration::from_nanos(1_000_000_000 / target_fps), frame_target_dt: Duration::from_nanos(1_000_000_000 / u64::from(target_fps)),
last_frame_time: Instant::now(), last_frame_time: Instant::now(),
accumulator: Duration::ZERO, accumulator: Duration::ZERO,
@@ -238,9 +241,161 @@ impl HostRunner {
audio: HostAudio::new(), audio: HostAudio::new(),
render_frame_store, render_frame_store,
presentation: PresentationState::default(), presentation: PresentationState::default(),
studio_capture: false,
} }
} }
/// One canonical interactive slice, shared by desktop and Studio pacing.
fn tick_machine(&mut self) {
self.audio.service();
if !self.debugger.waiting_for_start {
if self.studio_capture {
let mut platform = crate::studio::platform::StudioPlatform {
hardware: &mut self.hardware,
store: &self.render_frame_store,
};
self.firmware.tick(&self.input.signals, &mut platform);
} else {
self.firmware.tick(&self.input.signals, &mut self.hardware);
}
self.stats.record_host_cpu_time(self.firmware.os.vm().last_frame_cpu_time_us());
}
self.hardware.audio.set_paused(
self.firmware.game_lifecycle_audio_paused()
|| self.firmware.os.vm().paused()
|| self.debugger.waiting_for_start,
);
self.audio.service();
}
pub(crate) fn studio_audio_init(&mut self) {
if let Err(error) = self.audio.init(self.hardware.audio.transport()) {
eprintln!("[HostAudio] Disabled: {error}");
}
}
pub(crate) fn studio_boot_step(&mut self, disposable: bool) -> Result<bool, String> {
self.studio_capture = true;
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
return Ok(true);
}
if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) {
return Err("Cartridge failed during Studio boot".into());
}
self.firmware.os.memcard().poll(Instant::now());
if let FirmwareState::LoadCartridge(step) = &mut self.firmware.state
&& step.needs_memcard_choice()
&& !self.firmware.os.memcard().preparation_active()
{
let choice = if disposable {
prometeu_system::memcard::admission::Choice::MemoryFresh
} else {
prometeu_system::memcard::admission::Choice::Persistent
};
step.choose_memcard(
&mut self.firmware.os,
choice,
self.hardware.wall_clock().utc_unix_seconds(),
)
.map_err(|e| format!("Studio save selection failed: {e:?}"))?;
}
self.tick_machine();
self.studio_logs();
Ok(matches!(self.firmware.state, FirmwareState::GameRunning(_)))
}
pub(crate) fn studio_step(
&mut self,
signals: prometeu_hal::InputSignals,
) -> Result<(), String> {
self.input.signals = signals;
self.tick_machine();
self.studio_logs();
if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) {
return Err("Cartridge faulted during Studio Play".into());
}
Ok(())
}
pub(crate) fn studio_pause(&mut self, paused: bool) {
self.input.clear_guest_signals();
self.firmware.os.vm().set_paused(paused);
self.hardware.audio.set_paused(paused);
self.audio.service();
}
pub(crate) fn studio_dimensions(&self) -> (usize, usize) {
self.hardware.display_size()
}
pub(crate) fn studio_tick_index(&mut self) -> u64 {
self.firmware.os.frame_index()
}
pub(crate) fn studio_frame(
&mut self,
previous: Option<(RenderOwnership, prometeu_hal::FrameId)>,
) -> Option<OwnedRgba8888Frame> {
let active = self.firmware.os.vm().active_render_ownership();
self.render_frame_store
.latest_frame_after(previous)
.filter(|frame| should_present_worker_frame(&self.firmware.state, frame, active))
}
fn studio_logs(&mut self) {
let last = self.log_sink.last_seq();
let events = match last {
Some(seq) => self.firmware.os.logs_after(seq),
None => self.firmware.os.recent_logs(4096),
};
self.log_sink.process_events(events);
}
pub(crate) fn studio_stop(&mut self, disposable: bool) -> Result<(), String> {
self.studio_pause(true);
let deadline = Instant::now() + Duration::from_secs(2);
loop {
let service = self.firmware.os.memcard();
service.poll(Instant::now());
if !service.session.io_active()
&& !service.session.has_deferred_write()
&& !service.preparation_active()
{
break;
}
if Instant::now() >= deadline {
return Err("Save IO has not finished; retry Stop".into());
}
let lane = service.lane.clone();
lane.wait_for_progress(lane.progress_stamp(), Duration::from_millis(5));
}
if self.firmware.os.memcard().session.unsaved() && !disposable {
return Err("Unsaved game data; resume and save before stopping".into());
}
self.firmware
.os
.stop_background_io()
.map_err(|e| format!("Save shutdown failed: {e:?}"))?;
self.firmware.os.memcard().session.end_session();
self.firmware.os.memcard().poll(Instant::now());
self.firmware
.os
.memcard()
.uninstall_card()
.map_err(|e| format!("Save detach failed: {e:?}"))?;
self.firmware
.os
.vm()
.stop_render_worker()
.map_err(|e| format!("Render shutdown failed: {e:?}"))?;
Ok(())
}
pub(crate) fn studio_abort(&mut self) {
self.studio_pause(true);
let _ = self.firmware.os.vm().stop_render_worker();
let _ = self.firmware.os.stop_background_io();
}
fn window(&self) -> &'static Window { fn window(&self) -> &'static Window {
self.window.expect("window not created yet") self.window.expect("window not created yet")
} }
@@ -277,15 +432,32 @@ impl HostRunner {
fn machine_running(&mut self) -> bool { fn machine_running(&mut self) -> bool {
!self.firmware.os.vm().paused() && !self.debugger.waiting_for_start !self.firmware.os.vm().paused() && !self.debugger.waiting_for_start
} }
fn observe_latest_frame(&mut self) {
let active_ownership = self.firmware.os.vm().active_render_ownership();
if let Some(worker_frame) = self.render_frame_store.latest_frame()
&& should_present_worker_frame(&self.firmware.state, &worker_frame, active_ownership)
{
self.presentation
.note_published_frame(worker_frame.ownership, worker_frame.frame_id.get());
} else {
// Observe the actual front-buffer swap, including native Hub/Shell
// publications which do not execute a VM frame.
let publication = self.hardware.gfx.publication_count();
if publication > 0 {
self.presentation.note_published_frame(active_ownership, publication);
}
}
}
} }
impl ApplicationHandler for HostRunner { impl ApplicationHandler for HostRunner {
fn resumed(&mut self, event_loop: &ActiveEventLoop) { fn resumed(&mut self, event_loop: &ActiveEventLoop) {
let attrs = WindowAttributes::default() let attrs = WindowAttributes::default()
.with_title(format!( .with_title(format!(
"PROMETEU | GFX: {:.1} KB | FPS: {:.1} | Load: {:.1}% (C) + {:.1}% (A) | Frame: tick {} logical {} done {}", "PROMETEU | GFX: {:.1} KB | Host ticks/s: {:.1} | Load: {:.1}% (C) + {:.1}% (A) | Frame: tick {} logical {} done {}",
0.0, 0.0, 0.0, 0, 0, 0, 0)) 0.0, 0.0, 0.0, 0, 0, 0, 0))
.with_inner_size(LogicalSize::new(960.0, 540.0)) .with_inner_size(LogicalSize::new((prometeu_hal::graphics_contract::WIDTH * 2) as f64, (prometeu_hal::graphics_contract::HEIGHT * 2) as f64))
.with_min_inner_size(LogicalSize::new(320.0, 180.0)); .with_min_inner_size(LogicalSize::new(320.0, 180.0));
let window = event_loop.create_window(attrs).expect("failed to create window"); let window = event_loop.create_window(attrs).expect("failed to create window");
@@ -307,6 +479,7 @@ impl ApplicationHandler for HostRunner {
pixels.frame_mut().fill(0); pixels.frame_mut().fill(0);
self.blit = Some(crate::presentation_blit::PresentationBlit::new(&pixels));
self.pixels = Some(pixels); self.pixels = Some(pixels);
if let Err(err) = self.audio.init(self.hardware.audio.transport()) { if let Err(err) = self.audio.init(self.hardware.audio.transport()) {
@@ -337,9 +510,16 @@ impl ApplicationHandler for HostRunner {
self.request_redraw_if_needed(); self.request_redraw_if_needed();
} }
WindowEvent::Occluded(false) => {
self.invalidate_host_surface();
self.request_redraw_if_needed();
}
WindowEvent::RedrawRequested => { WindowEvent::RedrawRequested => {
let pixels = self.pixels.as_mut().expect("pixels not initialized"); let pixels = self.pixels.as_mut().expect("pixels not initialized");
let mut presented_worker = None;
let mut presented_frame = None;
{ {
let frame = pixels.frame_mut(); let frame = pixels.frame_mut();
@@ -351,20 +531,47 @@ impl ApplicationHandler for HostRunner {
active_ownership, active_ownership,
) )
{ {
self.firmware presented_worker = Some((worker_frame.ownership, worker_frame.frame_id));
.os presented_frame =
.vm() Some((worker_frame.ownership, worker_frame.frame_id.get()));
.record_repeated_render_worker_frame(worker_frame.frame_id);
draw_owned_rgba8888_frame_to_rgba8(&worker_frame, frame); draw_owned_rgba8888_frame_to_rgba8(&worker_frame, frame);
} else { } else {
let src = self.hardware.gfx.front_buffer(); let src = self.hardware.gfx.front_buffer();
draw_rgba8888_to_rgba8(src, frame); draw_rgba8888_to_rgba8(src, frame);
let publication = self.hardware.gfx.publication_count();
if publication > 0 {
presented_frame = Some((active_ownership, publication));
}
} }
} }
if pixels.render().is_err() { let size = self.window.expect("window").inner_size();
let rendered = std::cell::Cell::new(false);
let viewport = crate::viewport::Viewport::new(
(size.width, size.height),
self.hardware.display_size(),
);
let present_start = Instant::now();
let result = pixels.render_with(|encoder, target, _| {
if let Some(viewport) = viewport {
self.blit.as_ref().expect("blit").render(encoder, target, viewport);
rendered.set(true);
}
Ok(())
});
self.stats.record_present_time(present_start.elapsed());
if result.is_err() {
event_loop.exit(); event_loop.exit();
} else { } else if rendered.get() {
if let Some((ownership, frame_id)) = presented_frame {
self.stats.record_presented(ownership, frame_id);
}
if let Some((ownership, frame_id)) = presented_worker {
self.firmware
.os
.vm()
.record_presented_render_worker_frame(ownership, frame_id);
}
self.presentation.mark_presented(); self.presentation.mark_presented();
} }
} }
@@ -435,34 +642,12 @@ impl ApplicationHandler for HostRunner {
while self.accumulator >= self.frame_target_dt { while self.accumulator >= self.frame_target_dt {
// Reclaim returned audio owners before another guest attempt, even // Reclaim returned audio owners before another guest attempt, even
// when the previous attempt paused or stopped at backpressure. // when the previous attempt paused or stopped at backpressure.
self.audio.service(); self.tick_machine();
// Unless the debugger is waiting for a 'start' command, advance the system.
if !self.debugger.waiting_for_start {
self.firmware.tick(&self.input.signals, &mut self.hardware);
self.stats.record_host_cpu_time(self.firmware.os.vm().last_frame_cpu_time_us());
}
let is_paused = self.firmware.game_lifecycle_audio_paused()
|| self.firmware.os.vm().paused()
|| self.debugger.waiting_for_start;
self.hardware.audio.set_paused(is_paused);
self.audio.service();
self.accumulator -= self.frame_target_dt; self.accumulator -= self.frame_target_dt;
self.stats.record_frame(); self.stats.record_frame();
} }
let active_ownership = self.firmware.os.vm().active_render_ownership();
if let Some(worker_frame) = self.render_frame_store.latest_frame()
&& should_present_worker_frame(&self.firmware.state, &worker_frame, active_ownership)
{
self.presentation
.note_published_frame(worker_frame.ownership, worker_frame.frame_id.get());
} else {
self.presentation
.note_published_frame(active_ownership, self.firmware.os.frame_index());
}
if was_debugger_connected != self.debugger.stream.is_some() if was_debugger_connected != self.debugger.stream.is_some()
|| was_waiting_for_start != self.debugger.waiting_for_start || was_waiting_for_start != self.debugger.waiting_for_start
|| was_paused != self.firmware.os.vm().paused() || was_paused != self.firmware.os.vm().paused()
@@ -471,6 +656,7 @@ impl ApplicationHandler for HostRunner {
} }
// 4. Feedback and Synchronization. // 4. Feedback and Synchronization.
self.observe_latest_frame();
self.audio.update_stats(&mut self.stats); self.audio.update_stats(&mut self.stats);
// Update technical statistics displayed in the window title. // Update technical statistics displayed in the window title.
@@ -500,6 +686,117 @@ impl ApplicationHandler for HostRunner {
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::*; use super::*;
#[test]
fn studio_stress_demoscene_publishes_graphics_and_native_music() {
let cart = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../test-cartridges/stress-console");
let mut host = HostRunner::new(None, None);
host.set_boot_target(BootTarget::Cartridge {
path: cart.to_string_lossy().into_owned(),
debug: false,
debug_port: 0,
});
let deadline = Instant::now() + Duration::from_secs(5);
while !host.studio_boot_step(true).unwrap() {
assert!(Instant::now() < deadline);
std::thread::sleep(Duration::from_millis(1));
}
let (mut callback, mut reclaimer) = crate::audio::AudioCallback::new();
let transport = host.hardware.audio.transport();
let mut pcm = [0.0; 1600];
let mut audible = false;
while host.studio_frame(None).is_none() || !audible {
assert!(Instant::now() < deadline, "demo did not publish graphics/music");
host.studio_step(Default::default()).unwrap();
callback.render(&transport, &mut pcm);
audible |= pcm.iter().any(|x| x.abs() > 0.001);
reclaimer.service(&transport);
std::thread::sleep(Duration::from_millis(2));
}
assert!(callback.diagnostics().maximum_voices > 0);
assert_eq!(host.studio_frame(None).unwrap().ownership.app_id, 1);
let before_pause = callback.diagnostics().frames;
host.studio_pause(true);
callback.render(&transport, &mut pcm);
assert!(pcm.iter().all(|x| *x == 0.0));
assert_eq!(callback.diagnostics().frames, before_pause);
reclaimer.service(&transport);
host.studio_pause(false);
callback.render(&transport, &mut pcm);
assert!(callback.diagnostics().frames > before_pause);
reclaimer.service(&transport);
host.studio_stop(true).unwrap();
callback.render(&transport, &mut pcm);
assert!(pcm.iter().all(|x| *x == 0.0));
}
#[test]
fn studio_can_boot_and_publish_without_a_window() {
let cart = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../test-cartridges/dummy-boy");
let mut host = HostRunner::new(None, None);
host.set_boot_target(BootTarget::Cartridge {
path: cart.to_string_lossy().into_owned(),
debug: false,
debug_port: 0,
});
let deadline = Instant::now() + Duration::from_secs(5);
while !host.studio_boot_step(true).unwrap() {
assert!(Instant::now() < deadline);
std::thread::sleep(Duration::from_millis(1));
}
host.studio_pause(true);
host.studio_pause(false);
for _ in 0..60 {
host.studio_step(Default::default()).unwrap();
std::thread::sleep(Duration::from_millis(2));
}
let frame = host.studio_frame(None);
let published = host.render_frame_store.latest_frame().map(|f| (f.frame_id, f.ownership));
let active = host.firmware.os.vm().active_render_ownership();
assert!(
frame.is_some(),
"store {published:?}, owner {active:?}, state {:?}, frame {}",
host.firmware.state,
host.firmware.os.frame_index()
);
let frame = frame.unwrap();
assert!(host.studio_frame(Some((frame.ownership, frame.frame_id))).is_none());
// Exercise the same audio transport/callback through Studio lifecycle,
// without requiring a physical output device in this contract test.
use prometeu_hal::{AudioBridge, LoopMode, sample::Sample};
let (mut callback, mut reclaimer) = crate::audio::AudioCallback::new();
assert_eq!(
host.hardware.audio.play_sample(
Arc::new(Sample::new(48000, vec![1000; 32])),
0,
255,
0,
1.0,
0,
LoopMode::On,
),
prometeu_hal::AudioOpStatus::Ok
);
host.hardware.audio.finish_frame();
let transport = host.hardware.audio.transport();
let mut pcm = [0.0; 64];
callback.render(&transport, &mut pcm);
assert!(pcm.iter().any(|sample| *sample != 0.0));
reclaimer.service(&transport);
host.studio_pause(true);
callback.render(&transport, &mut pcm);
assert!(pcm.iter().all(|sample| *sample == 0.0));
reclaimer.service(&transport);
host.studio_pause(false);
callback.render(&transport, &mut pcm);
assert!(pcm.iter().any(|sample| *sample != 0.0));
reclaimer.service(&transport);
host.studio_stop(true).unwrap();
callback.render(&transport, &mut pcm);
assert!(pcm.iter().all(|sample| *sample == 0.0));
}
use prometeu_firmware::BootTarget; use prometeu_firmware::BootTarget;
use prometeu_firmware::firmware::firmware_state::{ use prometeu_firmware::firmware::firmware_state::{
GameRunningStep, HubHomeStep, ShellRunningStep, GameRunningStep, HubHomeStep, ShellRunningStep,
@@ -544,6 +841,15 @@ mod tests {
for _ in 0..8 { for _ in 0..8 {
runner.firmware.tick(&signals, &mut runner.hardware); runner.firmware.tick(&signals, &mut runner.hardware);
} }
// Successful session publications must drive redraw even when the
// physical surface has not otherwise been invalidated.
let completed = runner.firmware.os.vm().logical_frame_index();
assert!(completed > 0, "session published a frame in boot {cycle}");
runner.observe_latest_frame();
runner.presentation.mark_presented();
runner.firmware.tick(&signals, &mut runner.hardware);
runner.observe_latest_frame();
assert!(runner.presentation.needs_redraw(), "new session frame must redraw");
runner.firmware.request_home_from_host(); runner.firmware.request_home_from_host();
for _ in 0..32 { for _ in 0..32 {
runner.firmware.tick(&signals, &mut runner.hardware); runner.firmware.tick(&signals, &mut runner.hardware);
@@ -552,6 +858,16 @@ mod tests {
} }
} }
assert!(matches!(runner.firmware.state, FirmwareState::HubHome(_)), "home {cycle}"); assert!(matches!(runner.firmware.state, FirmwareState::HubHome(_)), "home {cycle}");
runner.observe_latest_frame();
runner.presentation.mark_presented();
let vm_frame = runner.firmware.os.vm().logical_frame_index();
runner.firmware.tick(&signals, &mut runner.hardware);
assert_eq!(runner.firmware.os.vm().logical_frame_index(), vm_frame);
runner.observe_latest_frame();
assert!(
runner.presentation.needs_redraw(),
"native Hub publication must redraw without a VM frame"
);
assert!(runner.firmware.resume_resident_game_from_home()); assert!(runner.firmware.resume_resident_game_from_home());
for _ in 0..8 { for _ in 0..8 {
runner.firmware.tick(&signals, &mut runner.hardware); runner.firmware.tick(&signals, &mut runner.hardware);
@@ -4,6 +4,13 @@ use winit::window::Window;
pub struct HostStats { pub struct HostStats {
pub last_stats_update: Instant, pub last_stats_update: Instant,
metrics_path: Option<std::path::PathBuf>,
present_us: Vec<u64>,
present_count: u64,
ticks_total: u64,
first_presentations: u64,
repeated_presentations: u64,
last_presented: Option<(prometeu_hal::RenderOwnership, u64)>,
pub frames_since_last_update: u64, pub frames_since_last_update: u64,
pub current_fps: f64, pub current_fps: f64,
pub audio_load_accum_us: u64, pub audio_load_accum_us: u64,
@@ -23,6 +30,13 @@ impl HostStats {
pub fn new() -> Self { pub fn new() -> Self {
Self { Self {
last_stats_update: Instant::now(), last_stats_update: Instant::now(),
metrics_path: std::env::var_os("PROMETEU_GRAPHICS_METRICS").map(Into::into),
present_us: Vec::new(),
present_count: 0,
ticks_total: 0,
first_presentations: 0,
repeated_presentations: 0,
last_presented: None,
frames_since_last_update: 0, frames_since_last_update: 0,
current_fps: 0.0, current_fps: 0.0,
audio_load_accum_us: 0, audio_load_accum_us: 0,
@@ -33,8 +47,31 @@ impl HostStats {
} }
} }
/// API latency, including texture upload/submit; not a physical scanout timestamp.
pub fn record_present_time(&mut self, duration: Duration) {
self.present_count += 1;
if self.metrics_path.is_some() {
let value = duration.as_micros() as u64;
if self.present_us.len() < 16384 {
self.present_us.push(value);
} else {
self.present_us[(self.present_count as usize - 1) % 16384] = value;
}
}
}
pub fn record_frame(&mut self) { pub fn record_frame(&mut self) {
self.frames_since_last_update += 1; self.frames_since_last_update += 1;
self.ticks_total += 1;
}
pub fn record_presented(&mut self, ownership: prometeu_hal::RenderOwnership, frame_id: u64) {
let marker = (ownership, frame_id);
if self.last_presented == Some(marker) {
self.repeated_presentations += 1;
} else {
self.first_presentations += 1;
}
self.last_presented = Some(marker);
} }
pub fn record_audio_perf(&mut self, us: u64) { pub fn record_audio_perf(&mut self, us: u64) {
@@ -66,7 +103,8 @@ impl HostStats {
if let Some(window) = window { if let Some(window) = window {
// Fixed comparison always against 60Hz, keep even when doing CPU stress tests // Fixed comparison always against 60Hz, keep even when doing CPU stress tests
let frame_budget_us = 16666.0; let frame_budget_us =
1_000_000.0 / prometeu_hal::graphics_contract::REFRESH_HZ as f64;
let cpu_load_core = (self.average_host_cpu_ms() * 1000.0 / frame_budget_us) * 100.0; let cpu_load_core = (self.average_host_cpu_ms() * 1000.0 / frame_budget_us) * 100.0;
let cpu_load_audio = if self.audio_load_samples > 0 { let cpu_load_audio = if self.audio_load_samples > 0 {
@@ -76,7 +114,7 @@ impl HostStats {
}; };
let title = format!( let title = format!(
"PROMETEU | GFX: {:.1} KB | FPS: {:.1} | Load: {:.1}% (C) + {:.1}% (A) | Frame: tick {} logical {} done {}", "PROMETEU | GFX: {:.1} KB | Host ticks/s: {:.1} | Load: {:.1}% (C) + {:.1}% (A) | Frame: tick {} logical {} done {}",
0, 0,
self.current_fps, self.current_fps,
cpu_load_core, cpu_load_core,
@@ -95,3 +133,41 @@ impl HostStats {
} }
} }
} }
impl Drop for HostStats {
fn drop(&mut self) {
if let Some(path) = &self.metrics_path {
self.present_us.sort_unstable();
let n = self.present_us.len();
let percentile =
|p: usize| if n == 0 { 0 } else { self.present_us[(n * p).div_ceil(100) - 1] };
let report = serde_json::json!({"schema":1,"host_ticks":self.ticks_total,
"first_presentations":self.first_presentations,"repeated_presentations":self.repeated_presentations,
"present_api_calls":self.present_count,"samples":n,
"present_api_mean_us":if n==0 {0.0} else {self.present_us.iter().sum::<u64>() as f64/n as f64},
"present_api_p95_us":percentile(95),"present_api_p99_us":percentile(99),
"present_api_max_us":self.present_us.last().copied().unwrap_or(0),
"present_api_over_budget":self.present_us.iter().filter(|&&v|v > 1_000_000 / u64::from(prometeu_hal::graphics_contract::REFRESH_HZ)).count(),
"physical_display_hz":null,"limitation":"bounded last 16384 API samples; API upload/submit/present time is not scanout latency"});
if let Err(error) = std::fs::write(path, report.to_string()) {
eprintln!("graphics metrics: {error}");
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use prometeu_hal::{RenderOwnership, app_mode::AppMode};
#[test]
fn host_counts_actual_submissions_by_identity_and_epoch() {
let mut stats = HostStats::new();
let first = RenderOwnership::new(1, AppMode::Game, 2);
stats.record_presented(first, 0);
stats.record_presented(first, 0);
stats.record_presented(RenderOwnership::new(2, AppMode::Game, 2), 0);
assert_eq!(stats.first_presentations, 2);
assert_eq!(stats.repeated_presentations, 1);
}
}
@@ -0,0 +1,262 @@
//! Interactive Play integration, separate from the automation host.
pub(crate) mod platform;
mod transport;
pub mod wire;
use crate::runner::HostRunner;
use prometeu_hal::InputSignals;
use std::{
io,
time::{Duration, Instant},
};
use transport::Transport;
use wire::*;
fn number64(p: &[u8]) -> u64 {
u64::from_le_bytes(p.try_into().unwrap())
}
fn result(
transport: &Transport,
command: u16,
request: u64,
status: u16,
epoch: u64,
tick: u64,
text: &str,
) -> io::Result<()> {
let mut p = Vec::with_capacity(20 + text.len());
p.extend_from_slice(&command.to_le_bytes());
p.extend_from_slice(&status.to_le_bytes());
p.extend_from_slice(&epoch.to_le_bytes());
p.extend_from_slice(&tick.to_le_bytes());
p.extend_from_slice(text.as_bytes());
transport.send(RESULT, request, p)
}
fn input(p: &[u8], width: usize, height: usize) -> io::Result<(u64, InputSignals)> {
if p.len() != 20 {
return Err(invalid("Invalid Studio input length"));
}
let mask = u16::from_le_bytes(p[8..10].try_into().unwrap());
if mask & !0x1fff != 0 || p[10..12] != [0, 0] {
return Err(invalid("Invalid Studio input bits"));
}
let x = i32::from_le_bytes(p[12..16].try_into().unwrap());
let y = i32::from_le_bytes(p[16..20].try_into().unwrap());
if mask & 0x1000 != 0 && (x < 0 || y < 0 || x as usize >= width || y as usize >= height) {
return Err(invalid("Studio touch outside display"));
}
let bit = |n: u16| mask & (1u16 << n) != 0;
Ok((
number64(&p[..8]),
InputSignals {
up_signal: bit(0),
down_signal: bit(1),
left_signal: bit(2),
right_signal: bit(3),
a_signal: bit(4),
b_signal: bit(5),
x_signal: bit(6),
y_signal: bit(7),
l_signal: bit(8),
r_signal: bit(9),
start_signal: bit(10),
select_signal: bit(11),
f_signal: bit(12),
x_pos: x,
y_pos: y,
},
))
}
pub(crate) fn run(mut runner: HostRunner, boot: Bootstrap) -> io::Result<()> {
let transport = Transport::connect(&boot)?;
runner.studio_audio_init();
let (width, height) = runner.studio_dimensions();
frame_bytes(width as u32, height as u32, width as u32)?;
let mut ready = false;
let mut started = false;
let mut state = 0u32;
let mut epoch = 1u64;
let mut signals = InputSignals::default();
let mut next_tick = Instant::now();
let boot_deadline = Instant::now() + Duration::from_secs(10);
let slice = Duration::from_nanos(
1_000_000_000 / u64::from(prometeu_hal::graphics_contract::REFRESH_HZ),
);
let mut last_request = 0;
let mut last_frame = None;
let outcome = (|| -> io::Result<()> {
loop {
if let Some(error) = transport.failure() {
return Err(invalid(&error));
}
if ready && transport.idle() > Duration::from_secs(5) {
return Err(invalid("Studio control heartbeat expired"));
}
for _ in 0..64 {
let Some(message) = transport.next() else {
break;
};
let h = message.header;
if h.kind == INPUT {
let (received, input) = input(&message.payload, width, height)?;
if received == epoch && state == 1 {
signals = input;
}
continue;
}
if h.kind == PING {
if !message.payload.is_empty() {
return Err(invalid("Invalid PING payload"));
}
let mut p = Vec::with_capacity(20);
p.extend_from_slice(&epoch.to_le_bytes());
p.extend_from_slice(&runner.studio_tick_index().to_le_bytes());
p.extend_from_slice(&state.to_le_bytes());
transport.send(PONG, h.request, p)?;
continue;
}
if !matches!(h.kind, START | PAUSE | RESUME | STOP)
|| !message.payload.is_empty()
|| h.request == 0
{
return Err(invalid("Invalid Studio control command"));
}
if h.request <= last_request {
result(
&transport,
h.kind,
h.request,
1,
epoch,
runner.studio_tick_index(),
"Stale or duplicate request",
)?;
continue;
}
last_request = h.request;
if h.kind == STOP {
signals = InputSignals::default();
state = 2;
epoch = epoch.checked_add(1).ok_or_else(|| invalid("epoch exhausted"))?;
match runner.studio_stop(boot.disposable) {
Ok(()) => {
result(
&transport,
STOP,
h.request,
0,
epoch,
runner.studio_tick_index(),
"",
)?;
transport.finish(h.request)?;
return Ok(());
}
Err(error) => {
result(
&transport,
STOP,
h.request,
2,
epoch,
runner.studio_tick_index(),
&error,
)?;
continue;
}
}
}
if !ready {
result(
&transport,
h.kind,
h.request,
1,
epoch,
runner.studio_tick_index(),
"Cartridge is not ready",
)?;
continue;
}
match h.kind {
START if state == 0 => {
started = true;
state = 1;
runner.studio_pause(false);
next_tick = Instant::now();
}
START if state == 2 && !started => {
started = true;
}
PAUSE if state == 1 || state == 0 => {
state = 2;
epoch += 1;
signals = InputSignals::default();
runner.studio_pause(true);
}
RESUME if state == 2 && started => {
state = 1;
epoch += 1;
signals = InputSignals::default();
runner.studio_pause(false);
next_tick = Instant::now();
}
PAUSE if state == 2 => {}
RESUME if state == 1 => {}
_ => {
result(
&transport,
h.kind,
h.request,
1,
epoch,
runner.studio_tick_index(),
"Invalid execution state",
)?;
continue;
}
}
result(&transport, h.kind, h.request, 0, epoch, runner.studio_tick_index(), "")?;
}
if !ready {
if Instant::now() > boot_deadline {
return Err(invalid("Studio cartridge boot timed out"));
}
ready = runner.studio_boot_step(boot.disposable).map_err(|e| invalid(&e))?;
if ready {
runner.studio_pause(true);
let mut p = Vec::new();
for n in [
width as u32,
height as u32,
prometeu_hal::graphics_contract::REFRESH_HZ,
RGBA8,
] {
p.extend_from_slice(&n.to_le_bytes());
}
p.extend_from_slice(env!("CARGO_PKG_VERSION").as_bytes());
transport.send(READY, 0, p)?;
}
} else if state == 1 && Instant::now() >= next_tick {
runner.studio_step(signals).map_err(|e| invalid(&e))?;
next_tick += slice;
if next_tick + Duration::from_millis(100) < Instant::now() {
next_tick = Instant::now();
}
}
// Completion is asynchronous and can arrive after Pause stopped logical ticks.
if ready && let Some(frame) = runner.studio_frame(last_frame) {
last_frame = Some((frame.ownership, frame.frame_id));
transport.publish(epoch, frame);
}
std::thread::sleep(Duration::from_millis(1));
}
})();
if let Err(error) = &outcome {
eprintln!("[Studio] {error}");
let _ = transport.send(ERROR, 0, error.to_string().into_bytes());
runner.studio_abort();
}
outcome
}
@@ -0,0 +1,69 @@
//! Observe complete synchronous submissions without changing machine/render semantics.
use prometeu_drivers::hardware::Hardware;
use prometeu_hal::*;
use prometeu_system::LatestRenderFrameStore;
pub(crate) struct StudioPlatform<'a> {
pub hardware: &'a mut Hardware,
pub store: &'a LatestRenderFrameStore,
}
impl RenderSubmissionSink for StudioPlatform<'_> {
fn submit_render_submission(
&mut self,
submission: RenderSubmission,
) -> Result<(), RenderSubmitError> {
let marker = (submission.frame_id, submission.ownership);
self.hardware.submit_render_submission(submission)?;
if marker.1.app_mode == app_mode::AppMode::Game {
let (w, h) = self.hardware.display_size();
let frame = OwnedRgba8888Frame::packed(
marker.0,
marker.1,
w,
h,
self.hardware.gfx.front_buffer().to_vec(),
)
.map_err(|_| RenderSubmitError::SubmissionRejected)?;
self.store.publish_frame(frame);
}
Ok(())
}
}
impl RuntimePlatform for StudioPlatform<'_> {
fn wall_clock(&self) -> &dyn WallClock {
self.hardware.wall_clock()
}
fn display_size(&self) -> (usize, usize) {
self.hardware.display_size()
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self
}
fn render_backend(&mut self) -> &mut dyn RenderBackend {
self.hardware
}
fn game2d_frame_composer(&mut self) -> &mut dyn Game2DFrameComposer {
self.hardware
}
fn audio(&self) -> &dyn AudioBridge {
self.hardware.audio()
}
fn audio_mut(&mut self) -> &mut dyn AudioBridge {
self.hardware.audio_mut()
}
fn input(&self) -> &dyn InputPlatform {
self.hardware.input()
}
fn input_mut(&mut self) -> &mut dyn InputPlatform {
self.hardware.input_mut()
}
fn assets(&self) -> &dyn AssetBridge {
self.hardware.assets()
}
fn assets_mut(&mut self) -> &mut dyn AssetBridge {
self.hardware.assets_mut()
}
fn telemetry(&self) -> &dyn TelemetryPlatform {
self.hardware.telemetry()
}
}
@@ -0,0 +1,260 @@
use super::wire::*;
use prometeu_hal::OwnedRgba8888Frame;
use std::io::{self, Read};
use std::net::{Ipv4Addr, Shutdown, SocketAddr, TcpStream};
use std::sync::{
Arc, Condvar, Mutex,
atomic::{AtomicBool, Ordering},
mpsc::{self, Receiver, SyncSender},
};
use std::thread::JoinHandle;
use std::time::{Duration, Instant};
struct Publication {
epoch: u64,
frame: Arc<OwnedRgba8888Frame>,
}
#[derive(Default)]
struct Video {
latest: Option<Publication>,
flight: Option<(u64, u64)>,
}
struct Shared {
video: Mutex<Video>,
wake: Condvar,
closed: AtomicBool,
failure: Mutex<Option<String>>,
activity: Mutex<Instant>,
}
impl Shared {
fn fail(&self, message: impl ToString) {
if self.closed.load(Ordering::Acquire) {
return;
}
let mut failure = self.failure.lock().unwrap();
if failure.is_none() {
*failure = Some(message.to_string());
}
self.wake.notify_all();
}
fn stopped(&self) -> bool {
self.closed.load(Ordering::Acquire) || self.failure.lock().unwrap().is_some()
}
}
struct Outbound {
kind: u16,
request: u64,
payload: Vec<u8>,
flushed: Option<SyncSender<()>>,
}
pub(super) struct Transport {
shared: Arc<Shared>,
outgoing: SyncSender<Outbound>,
incoming: Receiver<Message>,
control: TcpStream,
video: TcpStream,
workers: Vec<JoinHandle<()>>,
}
impl Transport {
pub fn connect(boot: &Bootstrap) -> io::Result<Self> {
fn connect(port: u16) -> io::Result<TcpStream> {
let socket = TcpStream::connect_timeout(
&SocketAddr::from((Ipv4Addr::LOCALHOST, port)),
Duration::from_secs(5),
)?;
socket.set_nodelay(true)?;
socket.set_write_timeout(Some(Duration::from_secs(2)))?;
Ok(socket)
}
let control = connect(boot.control_port)?;
let video = connect(boot.video_port)?;
let mut writer = Writer::new(control.try_clone()?);
writer.send(HELLO, 0, &boot.hello(1))?;
let mut video_writer = Writer::new(video.try_clone()?);
video_writer.send(HELLO, 0, &boot.hello(2))?;
let shared = Arc::new(Shared {
video: Mutex::new(Video::default()),
wake: Condvar::new(),
closed: AtomicBool::new(false),
failure: Mutex::new(None),
activity: Mutex::new(Instant::now()),
});
let (tx, rx) = mpsc::sync_channel::<Outbound>(256);
let (commands, incoming) = mpsc::sync_channel(256);
let mut workers = Vec::new();
let state = shared.clone();
workers.push(std::thread::Builder::new().name("studio-control-write".into()).spawn(
move || {
while !state.stopped() {
let out = match rx.recv_timeout(Duration::from_millis(100)) {
Ok(out) => out,
Err(mpsc::RecvTimeoutError::Timeout) => continue,
Err(_) => break,
};
if let Err(error) = writer.send(out.kind, out.request, &out.payload) {
state.fail(error);
break;
}
if let Some(done) = out.flushed {
let _ = done.send(());
}
}
},
)?);
let state = shared.clone();
let socket = control.try_clone()?;
workers.push(std::thread::Builder::new().name("studio-control-read".into()).spawn(
move || {
let mut reader = Reader::new(socket);
while !state.stopped() {
let message = match reader.receive_control() {
Ok(m) => m,
Err(e) => {
state.fail(format!("Studio control lost: {e}"));
break;
}
};
*state.activity.lock().unwrap() = Instant::now();
if message.header.kind == FRAME_RECEIVED {
if message.payload.len() != 16 || message.header.request != 0 {
state.fail("Invalid frame acknowledgement");
break;
}
let p = &message.payload;
let ack = (
u64::from_le_bytes(p[..8].try_into().unwrap()),
u64::from_le_bytes(p[8..].try_into().unwrap()),
);
let mut frames = state.video.lock().unwrap();
if frames.flight != Some(ack) {
drop(frames);
state.fail("Unexpected frame acknowledgement");
break;
}
frames.flight = None;
state.wake.notify_all();
} else if commands.try_send(message).is_err() {
state.fail("Studio control queue saturated");
break;
}
}
},
)?);
let state = shared.clone();
let session = boot.session;
workers.push(std::thread::Builder::new().name("studio-video-write".into()).spawn(
move || {
let mut previous = None;
let mut payload = Vec::new();
while !state.stopped() {
let (epoch, frame) = {
let mut frames = state.video.lock().unwrap();
loop {
if state.stopped() {
return;
}
if frames.flight.is_none()
&& let Some(p) = &frames.latest
{
let marker = (p.epoch, p.frame.frame_id.get());
if previous != Some(marker) {
let result = (p.epoch, p.frame.clone());
frames.flight = Some(marker);
previous = Some(marker);
break result;
}
}
frames = state
.wake
.wait_timeout(frames, Duration::from_millis(100))
.unwrap()
.0;
}
};
let size = match frame_bytes(
frame.width as u32,
frame.height as u32,
frame.width as u32,
) {
Ok(n) => n,
Err(e) => {
state.fail(e);
break;
}
};
payload.clear();
payload.reserve(FRAME_METADATA_BYTES + size);
payload.extend_from_slice(&session);
payload.extend_from_slice(&epoch.to_le_bytes());
payload.extend_from_slice(&frame.frame_id.get().to_le_bytes());
for n in [frame.width as u32, frame.height as u32, frame.width as u32, RGBA8] {
payload.extend_from_slice(&n.to_le_bytes());
}
for y in 0..frame.height {
for pixel in &frame.pixels
[y * frame.stride_pixels..y * frame.stride_pixels + frame.width]
{
payload.extend_from_slice(&pixel.to_be_bytes());
}
}
if let Err(e) = video_writer.send(FRAME, 0, &payload) {
state.fail(format!("Studio video lost: {e}"));
break;
}
}
},
)?);
let state = shared.clone();
let mut watch = video.try_clone()?;
workers.push(std::thread::Builder::new().name("studio-video-watch".into()).spawn(
move || {
let mut byte = [0];
match watch.read(&mut byte) {
Ok(0) => state.fail("Studio video connection closed"),
Ok(_) => state.fail("Unexpected data on video channel"),
Err(e) => state.fail(format!("Studio video connection failed: {e}")),
}
},
)?);
Ok(Self { shared, outgoing: tx, incoming, control, video, workers })
}
pub fn send(&self, kind: u16, request: u64, payload: Vec<u8>) -> io::Result<()> {
self.outgoing
.try_send(Outbound { kind, request, payload, flushed: None })
.map_err(|_| invalid("Studio output queue unavailable"))
}
pub fn finish(&self, request: u64) -> io::Result<()> {
let (tx, rx) = mpsc::sync_channel(1);
self.outgoing
.try_send(Outbound { kind: STOPPED, request, payload: Vec::new(), flushed: Some(tx) })
.map_err(|_| invalid("Studio output queue unavailable"))?;
rx.recv_timeout(Duration::from_secs(2))
.map_err(|_| invalid("Studio shutdown acknowledgement failed"))
}
pub fn next(&self) -> Option<Message> {
self.incoming.try_recv().ok()
}
pub fn failure(&self) -> Option<String> {
self.shared.failure.lock().unwrap().clone()
}
pub fn idle(&self) -> Duration {
self.shared.activity.lock().unwrap().elapsed()
}
pub fn publish(&self, epoch: u64, frame: OwnedRgba8888Frame) {
self.shared.video.lock().unwrap().latest =
Some(Publication { epoch, frame: Arc::new(frame) });
self.shared.wake.notify_one();
}
}
impl Drop for Transport {
fn drop(&mut self) {
self.shared.closed.store(true, Ordering::SeqCst);
self.shared.wake.notify_all();
let _ = self.control.shutdown(Shutdown::Both);
let _ = self.video.shutdown(Shutdown::Both);
for worker in self.workers.drain(..) {
let _ = worker.join();
}
}
}
@@ -0,0 +1,227 @@
//! Bounded, explicitly little-endian Studio Play messages.
use std::io::{self, Read, Write};
pub const HEADER_BYTES: usize = 32;
pub const CONTROL_LIMIT: usize = 64 * 1024;
pub const FRAME_LIMIT: usize = 16 * 1024 * 1024;
pub const FRAME_METADATA_BYTES: usize = 48;
pub const HELLO: u16 = 1;
pub const READY: u16 = 2;
pub const START: u16 = 3;
pub const PAUSE: u16 = 4;
pub const RESUME: u16 = 5;
pub const STOP: u16 = 6;
pub const RESULT: u16 = 7;
pub const INPUT: u16 = 8;
pub const FRAME: u16 = 9;
pub const FRAME_RECEIVED: u16 = 10;
pub const PING: u16 = 11;
pub const PONG: u16 = 12;
pub const ERROR: u16 = 13;
pub const STOPPED: u16 = 14;
pub const BOOTSTRAP: u16 = 15;
pub const RGBA8: u32 = 1;
pub fn invalid(message: &str) -> io::Error {
io::Error::new(io::ErrorKind::InvalidData, message)
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Header {
pub kind: u16,
pub length: usize,
pub sequence: u64,
pub request: u64,
}
impl Header {
fn validate(self) -> io::Result<()> {
if !(HELLO..=BOOTSTRAP).contains(&self.kind) || self.sequence == 0 {
return Err(invalid("invalid Studio message type/sequence"));
}
if self.length > if self.kind == FRAME { FRAME_LIMIT } else { CONTROL_LIMIT } {
return Err(invalid("Studio payload exceeds limit"));
}
Ok(())
}
pub fn encode(self) -> io::Result<[u8; HEADER_BYTES]> {
self.validate()?;
let mut b = [0; HEADER_BYTES];
b[..4].copy_from_slice(b"PST1");
b[4..6].copy_from_slice(&1u16.to_le_bytes());
b[8..10].copy_from_slice(&self.kind.to_le_bytes());
b[12..16].copy_from_slice(&(self.length as u32).to_le_bytes());
b[16..24].copy_from_slice(&self.sequence.to_le_bytes());
b[24..32].copy_from_slice(&self.request.to_le_bytes());
Ok(b)
}
pub fn decode(b: &[u8; HEADER_BYTES]) -> io::Result<Self> {
if &b[..4] != b"PST1" || b[4..8] != [1, 0, 0, 0] || b[10..12] != [0, 0] {
return Err(invalid("invalid Studio magic/version/flags"));
}
let h = Self {
kind: u16::from_le_bytes(b[8..10].try_into().unwrap()),
length: u32::from_le_bytes(b[12..16].try_into().unwrap()) as usize,
sequence: u64::from_le_bytes(b[16..24].try_into().unwrap()),
request: u64::from_le_bytes(b[24..32].try_into().unwrap()),
};
h.validate()?;
Ok(h)
}
}
#[derive(Debug)]
pub struct Message {
pub header: Header,
pub payload: Vec<u8>,
}
pub struct Reader<R> {
input: R,
sequence: u64,
}
impl<R: Read> Reader<R> {
pub fn new(input: R) -> Self {
Self { input, sequence: 0 }
}
pub fn receive(&mut self) -> io::Result<Message> {
self.receive_bounded(FRAME_LIMIT)
}
pub fn receive_control(&mut self) -> io::Result<Message> {
self.receive_bounded(CONTROL_LIMIT)
}
fn receive_bounded(&mut self, limit: usize) -> io::Result<Message> {
let mut bytes = [0; HEADER_BYTES];
self.input.read_exact(&mut bytes)?;
let header = Header::decode(&bytes)?;
if header.length > limit {
return Err(invalid("payload exceeds channel limit"));
}
if header.sequence <= self.sequence {
return Err(invalid("non-monotonic Studio sequence"));
}
self.sequence = header.sequence;
let mut payload = vec![0; header.length];
self.input.read_exact(&mut payload)?;
Ok(Message { header, payload })
}
}
pub struct Writer<W> {
output: W,
sequence: u64,
}
impl<W: Write> Writer<W> {
pub fn new(output: W) -> Self {
Self { output, sequence: 0 }
}
pub fn send(&mut self, kind: u16, request: u64, payload: &[u8]) -> io::Result<()> {
self.sequence =
self.sequence.checked_add(1).ok_or_else(|| invalid("sequence exhausted"))?;
self.output.write_all(
&Header { kind, request, sequence: self.sequence, length: payload.len() }.encode()?,
)?;
self.output.write_all(payload)?;
self.output.flush()
}
}
#[derive(Debug)]
pub struct Bootstrap {
pub session: [u8; 16],
pub token: [u8; 32],
pub control_port: u16,
pub video_port: u16,
pub disposable: bool,
}
impl Bootstrap {
pub fn read(input: impl Read) -> io::Result<Self> {
let m = Reader::new(input).receive()?;
let p = &m.payload;
if m.header.kind != BOOTSTRAP || m.header.request != 0 || p.len() != 53 || p[52] > 1 {
return Err(invalid("invalid Studio bootstrap"));
}
let b = Self {
session: p[..16].try_into().unwrap(),
token: p[16..48].try_into().unwrap(),
control_port: u16::from_le_bytes(p[48..50].try_into().unwrap()),
video_port: u16::from_le_bytes(p[50..52].try_into().unwrap()),
disposable: p[52] != 0,
};
if b.control_port == 0 || b.video_port == 0 || b.control_port == b.video_port {
return Err(invalid("invalid Studio ports"));
}
Ok(b)
}
pub fn hello(&self, role: u8) -> Vec<u8> {
let mut p = Vec::with_capacity(49);
p.extend_from_slice(&self.session);
p.extend_from_slice(&self.token);
p.push(role);
p
}
}
pub fn frame_bytes(width: u32, height: u32, stride: u32) -> io::Result<usize> {
if width == 0 || height == 0 || stride != width {
return Err(invalid("invalid frame dimensions/stride"));
}
(stride as usize)
.checked_mul(height as usize)
.and_then(|n| n.checked_mul(4))
.filter(|n| *n <= FRAME_LIMIT - FRAME_METADATA_BYTES)
.ok_or_else(|| invalid("frame exceeds limit"))
}
#[cfg(test)]
mod tests {
use super::*;
fn fixture() -> Vec<u8> {
let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../devtools/studio-protocol/fixtures/pause.hex");
std::fs::read_to_string(root)
.unwrap()
.split_whitespace()
.map(|s| u8::from_str_radix(s, 16).unwrap())
.collect()
}
#[test]
fn header_matches_shared_fixture() {
let expected = fixture();
let actual = Header { kind: PAUSE, length: 0, sequence: 1, request: 42 }.encode().unwrap();
assert_eq!(actual.as_slice(), expected);
assert_eq!(Header::decode(&actual).unwrap().request, 42);
}
#[test]
fn truncation_replay_and_invalid_header_fail() {
let bytes = fixture();
assert!(Reader::new(&bytes[..31]).receive().is_err());
let repeated = [bytes.as_slice(), bytes.as_slice()].concat();
let mut r = Reader::new(repeated.as_slice());
assert!(r.receive().is_ok());
assert!(r.receive().is_err());
for offset in [0, 4, 6, 8, 10] {
let mut bad: [u8; 32] = bytes.clone().try_into().unwrap();
bad[offset] = 255;
assert!(Header::decode(&bad).is_err());
}
assert!(
Header { kind: INPUT, length: CONTROL_LIMIT + 1, sequence: 1, request: 0 }
.encode()
.is_err()
);
assert!(frame_bytes(u32::MAX, u32::MAX, u32::MAX).is_err());
assert!(frame_bytes(640, 360, 641).is_err());
assert_eq!(frame_bytes(640, 360, 640).unwrap(), 921600);
}
#[test]
fn fragmented_reads_and_writes_preserve_messages() {
struct Short<'a>(&'a [u8]);
impl Read for Short<'_> {
fn read(&mut self, b: &mut [u8]) -> io::Result<usize> {
let n = b.len().min(3).min(self.0.len());
b[..n].copy_from_slice(&self.0[..n]);
self.0 = &self.0[n..];
Ok(n)
}
}
let mut bytes = Vec::new();
Writer::new(&mut bytes).send(INPUT, 9, &[1, 2, 3]).unwrap();
let m = Reader::new(Short(&bytes)).receive().unwrap();
assert_eq!(m.payload, [1, 2, 3]);
assert_eq!(m.header.request, 9);
assert!(Reader::new(&bytes[..bytes.len() - 1]).receive().is_err());
}
}
@@ -0,0 +1,71 @@
//! Physical surface geometry shared by the nearest blit and pointer normalization.
#[derive(Clone, Copy, Debug)]
pub(crate) struct Viewport {
pub x: f32,
pub y: f32,
pub width: f32,
pub height: f32,
pub scale: f32,
native: (usize, usize),
}
impl Viewport {
pub fn new(surface: (u32, u32), native: (usize, usize)) -> Option<Self> {
if surface.0 == 0 || surface.1 == 0 || native.0 == 0 || native.1 == 0 {
return None;
}
let fit = (surface.0 as f32 / native.0 as f32).min(surface.1 as f32 / native.1 as f32);
let scale = if fit >= 1.0 { fit.floor() } else { fit };
let width = native.0 as f32 * scale;
let height = native.1 as f32 * scale;
Some(Self {
x: ((surface.0 as f32 - width) / 2.0).floor(),
y: ((surface.1 as f32 - height) / 2.0).floor(),
width,
height,
scale,
native,
})
}
pub fn inverse(self, x: f64, y: f64) -> Option<(i32, i32)> {
let (x, y) = (x - self.x as f64, y - self.y as f64);
if !x.is_finite()
|| !y.is_finite()
|| x < 0.0
|| y < 0.0
|| x >= self.width as f64
|| y >= self.height as f64
{
return None;
}
Some((
((x / self.scale as f64).floor() as i32).min(self.native.0 as i32 - 1),
((y / self.scale as f64).floor() as i32).min(self.native.1 as i32 - 1),
))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn physical_scaling_and_inverse_share_bounds() {
for (surface, scale, offset) in [
((1280, 720), 2.0, (0.0, 0.0)),
((1920, 1080), 3.0, (0.0, 0.0)),
((1000, 700), 1.0, (180.0, 170.0)),
((320, 240), 0.5, (0.0, 30.0)),
((2560, 1440), 4.0, (0.0, 0.0)),
] {
let v = Viewport::new(surface, (640, 360)).unwrap();
assert_eq!((v.scale, v.x, v.y), (scale, offset.0, offset.1));
assert_eq!(v.inverse(v.x as f64, v.y as f64), Some((0, 0)));
assert_eq!(
v.inverse((v.x + v.width - 0.01) as f64, (v.y + v.height - 0.01) as f64),
Some((639, 359))
);
assert_eq!(v.inverse((v.x + v.width) as f64, v.y as f64), None);
assert_eq!(v.inverse(v.x as f64, (v.y + v.height) as f64), None);
assert_eq!(v.inverse(v.x as f64 - 0.01, v.y as f64), None);
}
assert!(Viewport::new((0, 0), (640, 360)).is_none());
}
}
@@ -104,7 +104,7 @@ fn callback_owners_do_not_use_allocator() {
fn stalled_service_bounds_retention_and_recovers_pending_delivery() { fn stalled_service_bounds_retention_and_recovers_pending_delivery() {
let mut audio = Audio::new(Arc::new(MemoryBanks::new())); let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
let (mut callback, mut reclaimer) = AudioCallback::new(); let (mut callback, mut reclaimer) = AudioCallback::new();
let owners: Vec<_> = (0..16).map(|voice| play(&mut audio, voice, false)).collect(); let owners: Vec<_> = (0..8).map(|voice| play(&mut audio, voice, false)).collect();
audio.finish_frame(); audio.finish_frame();
// Keep all voices playing until both packets have been returned. // Keep all voices playing until both packets have been returned.
render(&mut callback, &audio, &mut [], "start_16"); render(&mut callback, &audio, &mut [], "start_16");
@@ -135,7 +135,7 @@ fn full_frame_and_combined_lifecycle_fit_one_packet() {
let mut audio = Audio::new(Arc::new(MemoryBanks::new())); let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
let (mut callback, mut reclaimer) = AudioCallback::new(); let (mut callback, mut reclaimer) = AudioCallback::new();
let mut owners = Vec::new(); let mut owners = Vec::new();
for voice in 0..16 { for voice in 0..8 {
owners.push(play(&mut audio, voice, false)); owners.push(play(&mut audio, voice, false));
} }
audio.finish_frame(); audio.finish_frame();
@@ -158,7 +158,7 @@ fn full_frame_and_combined_lifecycle_fit_one_packet() {
let mut pcm = [0.0; 32]; let mut pcm = [0.0; 32];
render(&mut callback, &audio, &mut pcm, "3072_commands_plus_completion"); render(&mut callback, &audio, &mut pcm, "3072_commands_plus_completion");
reclaimer.service(&audio.transport()); reclaimer.service(&audio.transport());
assert!(owners.iter().skip(16).all(|owner| owner.upgrade().is_none())); assert!(owners.iter().skip(8).all(|owner| owner.upgrade().is_none()));
audio.reset(); audio.reset();
render(&mut callback, &audio, &mut pcm, "reset_remaining_voices"); render(&mut callback, &audio, &mut pcm, "reset_remaining_voices");
reclaimer.service(&audio.transport()); reclaimer.service(&audio.transport());
@@ -169,8 +169,8 @@ fn full_frame_and_combined_lifecycle_fit_one_packet() {
/// fixture reads the checked-in asset pack and writes a temporary host save; /// fixture reads the checked-in asset pack and writes a temporary host save;
/// it does not certify asset decoding or guest memcard scheduling. /// it does not certify asset decoding or guest memcard scheduling.
#[test] #[test]
#[ignore = "requires physical audio output; 16 quiet voices and temporary file I/O"] #[ignore = "requires physical audio output; 8 quiet voices and temporary file I/O"]
fn physical_callback_duration_16_voices_with_io_pressure() { fn physical_callback_duration_8_sfx_voices_with_io_pressure() {
use cpal::traits::{DeviceTrait, HostTrait, StreamTrait}; use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
use prometeu_host_desktop_winit::fs_backend::HostDirBackend; use prometeu_host_desktop_winit::fs_backend::HostDirBackend;
use prometeu_system::fs::FsBackend; use prometeu_system::fs::FsBackend;
@@ -185,7 +185,7 @@ fn physical_callback_duration_16_voices_with_io_pressure() {
let mut audio = Audio::new(Arc::new(MemoryBanks::new())); let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
let (mut callback, mut reclaimer) = AudioCallback::new(); let (mut callback, mut reclaimer) = AudioCallback::new();
let mut owners = vec![]; let mut owners = vec![];
for voice in 0..16 { for voice in 0..8 {
let sample = Arc::new(Sample::new(48000, vec![32; 4800])); let sample = Arc::new(Sample::new(48000, vec![32; 4800]));
owners.push(Arc::downgrade(&sample)); owners.push(Arc::downgrade(&sample));
audio.play_sample(sample, voice, 8, 127, 1.0, 0, LoopMode::On); audio.play_sample(sample, voice, 8, 127, 1.0, 0, LoopMode::On);
@@ -264,18 +264,18 @@ fn physical_callback_duration_16_voices_with_io_pressure() {
); );
assert!(!failed.load(Ordering::Relaxed)); assert!(!failed.load(Ordering::Relaxed));
assert_eq!(allocator_calls.load(Ordering::Relaxed), 0); assert_eq!(allocator_calls.load(Ordering::Relaxed), 0);
assert_eq!((live_before, live_after), (16, 0)); assert_eq!((live_before, live_after), (8, 0));
} }
#[test] #[test]
#[ignore = "release timing observation with temporary asset-read/save-write pressure"] #[ignore = "release timing observation with temporary asset-read/save-write pressure"]
fn callback_duration_16_voices_with_io_pressure() { fn callback_duration_8_sfx_voices_with_io_pressure() {
use prometeu_host_desktop_winit::fs_backend::HostDirBackend; use prometeu_host_desktop_winit::fs_backend::HostDirBackend;
use prometeu_system::fs::FsBackend; use prometeu_system::fs::FsBackend;
use std::time::Instant; use std::time::Instant;
let mut audio = Audio::new(Arc::new(MemoryBanks::new())); let mut audio = Audio::new(Arc::new(MemoryBanks::new()));
let (mut callback, mut reclaimer) = AudioCallback::new(); let (mut callback, mut reclaimer) = AudioCallback::new();
let owners: Vec<_> = (0..16).map(|voice| play(&mut audio, voice, true)).collect(); let owners: Vec<_> = (0..8).map(|voice| play(&mut audio, voice, true)).collect();
audio.finish_frame(); audio.finish_frame();
let mut pcm = [0.0; 512]; // 256 stereo frames: nominal 5.333 ms at 48 kHz. let mut pcm = [0.0; 512]; // 256 stereo frames: nominal 5.333 ms at 48 kHz.
callback.render(&audio.transport(), &mut pcm); callback.render(&audio.transport(), &mut pcm);
@@ -311,7 +311,7 @@ fn callback_duration_16_voices_with_io_pressure() {
samples[500], samples[950], samples[990], samples[999] samples[500], samples[950], samples[990], samples[999]
); );
assert_eq!(counts, (0, 0)); assert_eq!(counts, (0, 0));
assert_eq!((before, after), (16, 0)); assert_eq!((before, after), (8, 0));
} }
#[test] #[test]
@@ -341,7 +341,269 @@ fn unloaded_banks_empty_samples_and_controls_reclaim_on_service() {
audio.finish_frame(); audio.finish_frame();
render(&mut callback, &audio, &mut pcm, "controls_stop_empty"); render(&mut callback, &audio, &mut pcm, "controls_stop_empty");
assert!(pcm.iter().all(|&sample| sample == 0.0)); assert!(pcm.iter().all(|&sample| sample == 0.0));
assert!(weak.upgrade().is_some() && weak_empty.upgrade().is_some()); assert!(weak.upgrade().is_none() && weak_empty.upgrade().is_some());
reclaimer.service(&audio.transport()); reclaimer.service(&audio.transport());
assert!(weak.upgrade().is_none() && weak_empty.upgrade().is_none()); assert!(weak.upgrade().is_none() && weak_empty.upgrade().is_none());
} }
fn music_fixture() -> Arc<prometeu_hal::music_bank::MusicBank> {
use prometeu_hal::music_bank::{Instrument, MusicBank, MusicEvent};
let sample =
Arc::new(Sample::new(48000, vec![1000, -1500]).with_channels(2).unwrap().with_loop(0, 1));
let mut events: Vec<_> = (0..12)
.map(|id| MusicEvent { kind: 1, a: id, c: 60, d: 255, ..Default::default() })
.collect();
// Every frame replaces a voice while envelopes and modulation keep running.
for tick in 1..500 {
events.push(MusicEvent {
tick,
kind: 1,
a: 12 + tick,
c: 60 + (tick % 12) as i32,
d: 180,
..Default::default()
});
}
Arc::new(
MusicBank::compile(
"rt".into(),
vec![sample],
vec![Instrument {
looping: true,
attack_us: 100,
release_us: 1000,
vibrato_millihz: 6000,
vibrato_cents: 20,
tremolo_millihz: 4000,
tremolo_depth: 1000,
send: 32768,
..Default::default()
}],
events,
960,
20_000,
1000,
None,
1,
)
.unwrap(),
)
}
#[test]
fn thirty_two_stereo_voices_sequences_dsp_and_bank_retirement_never_call_allocator() {
use prometeu_drivers::SoundBankPoolInstaller;
use prometeu_hal::audio_bridge::AudioControl;
let banks = Arc::new(MemoryBanks::new());
let mut audio = Audio::new(banks.clone());
banks.install_music_bank(0, music_fixture());
audio.music_play(0, 0, true);
audio.music_play(1, 0, true);
for voice in 0..8 {
let sample =
Arc::new(Sample::new(48000, vec![500, -500]).with_channels(2).unwrap().with_loop(0, 1));
audio.play_sample(sample, voice, 255, 128, 1.0, 0, LoopMode::On);
}
for group in 0..3 {
audio.control(AudioControl::Effect {
group,
cutoff_hz: 6000,
delay_frames: 48,
feedback: 0.5,
wet: 0.3,
dry: 0.7,
});
}
audio.finish_frame();
let (mut callback, mut reclaimer) = AudioCallback::new();
let mut pcm = [0.0; 512];
render(&mut callback, &audio, &mut pcm, "32_stereo_sequencers_adsr_modulation_dsp");
assert_eq!(callback.diagnostics().maximum_voices, 32);
reclaimer.service(&audio.transport());
for _ in 0..20 {
banks.install_music_bank(0, music_fixture());
audio.music_play(0, 0, true);
audio.music_play(1, 0, true);
audio.control(AudioControl::Crossfade { source: 0, target: 1, frames: 48, smooth: true });
audio.finish_frame();
render(&mut callback, &audio, &mut pcm, "32_bank_replacement_and_crossfade");
reclaimer.service(&audio.transport());
}
// Exhaust both packets, then invalidate banks and keep processing safely.
render(&mut callback, &audio, &mut pcm, "pool_first");
render(&mut callback, &audio, &mut pcm, "pool_second");
banks.unload_audio_bank(true, 0);
for _ in 0..10 {
render(&mut callback, &audio, &mut pcm, "music_invalidated_without_packet");
}
reclaimer.service(&audio.transport());
render(&mut callback, &audio, &mut pcm, "retire_after_starvation");
reclaimer.service(&audio.transport());
}
#[test]
#[ignore = "physical 48 kHz output; emits a quiet tone for two seconds"]
fn physical_32_stereo_voices_with_dsp_and_bank_replacement() {
use cpal::traits::{DeviceTrait, HostTrait, StreamTrait};
use prometeu_drivers::SoundBankPoolInstaller;
use prometeu_hal::{
audio_bridge::AudioControl,
music_bank::{Instrument, MusicBank, MusicEvent},
};
use ringbuf::{
HeapRb,
traits::{Consumer, Producer, Split},
};
use std::{
sync::atomic::{AtomicUsize, Ordering},
time::{Duration, Instant},
};
let device = cpal::default_host().default_output_device().expect("physical output device");
let name = device.name().unwrap();
let sample = Arc::new(
Sample::new(
48000,
(0..256)
.flat_map(|i| {
let v = ((i as f64 * std::f64::consts::TAU / 256.0).sin() * 512.0) as i16;
[v, v]
})
.collect(),
)
.with_channels(2)
.unwrap()
.with_loop(0, 256),
);
let make_bank = || {
Arc::new(
MusicBank::compile(
"physical".into(),
vec![sample.clone()],
vec![Instrument { looping: true, send: 32768, ..Default::default() }],
(0..12)
.map(|n| MusicEvent {
kind: 1,
a: n,
c: 60 + n as i32,
d: 255,
..Default::default()
})
.collect(),
960,
500000,
3840,
None,
1,
)
.unwrap(),
)
};
let banks = Arc::new(MemoryBanks::new());
banks.install_music_bank(0, make_bank());
banks.install_music_bank(1, make_bank());
let mut audio = Audio::new(banks.clone());
audio.music_play(0, 0, true);
audio.music_play(1, 1, true);
for group in 0..2 {
audio.control(AudioControl::MusicVolume { group, gain: 8 });
}
for voice in 0..8 {
audio.play_sample(sample.clone(), voice, 8, 128, 1.0, 0, LoopMode::On);
audio.control(AudioControl::SfxSend { voice, gain: 100 });
}
for group in 0..3 {
audio.control(AudioControl::Effect {
group,
cutoff_hz: 6000,
delay_frames: 4800,
feedback: 0.5,
wet: 0.3,
dry: 0.7,
});
}
audio.finish_frame();
let (mut callback, mut reclaimer) = AudioCallback::new();
let transport = audio.transport();
let (mut writer, mut reader) = HeapRb::<(u64, usize, usize)>::new(4096).split();
let failures = Arc::new(AtomicUsize::new(0));
let allocator = Arc::new(AtomicUsize::new(0));
let failure = failures.clone();
let allocations = allocator.clone();
let config = cpal::StreamConfig {
channels: 2,
sample_rate: cpal::SampleRate(48000),
buffer_size: cpal::BufferSize::Fixed(256),
};
let stream = device
.build_output_stream(
&config,
move |data: &mut [f32], _: &cpal::OutputCallbackInfo| {
let start = Instant::now();
let (a, d) = measured(|| callback.render(&transport, data));
allocations.fetch_add(a + d, Ordering::Relaxed);
let _ = writer.try_push((
start.elapsed().as_nanos() as u64,
data.len() / 2,
callback.diagnostics().maximum_voices,
));
},
move |_| {
failure.fetch_add(1, Ordering::Relaxed);
},
None,
)
.unwrap();
let temporary =
std::env::temp_dir().join(format!("prometeu-audio-32-pressure-{}", std::process::id()));
let pressure = vec![0x5a; 512 * 1024];
let fixture = include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-music.mbnk"
));
stream.play().unwrap();
let end = Instant::now() + Duration::from_secs(2);
let mut replacements = 0;
while Instant::now() < end {
std::fs::write(&temporary, &pressure).unwrap();
let decoded = prometeu_drivers::bank_format::decode_audio_bank(fixture, true).unwrap();
std::hint::black_box(decoded);
reclaimer.service(&audio.transport());
if audio.ready() {
banks.install_music_bank(0, make_bank());
audio.music_play(0, 0, true);
audio.control(AudioControl::MusicVolume { group: 0, gain: 8 });
audio.finish_frame();
replacements += 1;
}
std::thread::sleep(Duration::from_millis(2));
}
stream.pause().unwrap();
drop(stream);
reclaimer.service(&audio.transport());
std::fs::remove_file(temporary).unwrap();
let mut timings = Vec::new();
let mut overruns = 0;
let mut maximum_voices = 0;
while let Some((n, frames, voices)) = reader.try_pop() {
maximum_voices = maximum_voices.max(voices);
timings.push(n);
if n as u128 > frames as u128 * 1_000_000_000 / 48000 {
overruns += 1;
}
}
timings.sort_unstable();
assert!(!timings.is_empty());
let n = timings.len();
println!(
"physical_32_stereo device={name:?} maximum_voices={maximum_voices} callbacks={n} replacements={replacements} p50_ns={} p95_ns={} p99_ns={} max_ns={} budget_overruns={overruns} device_errors={} allocator_calls={} maximum_retired_pcm_bytes={}",
timings[n / 2],
timings[n * 95 / 100],
timings[n * 99 / 100],
timings[n - 1],
failures.load(Ordering::Relaxed),
allocator.load(Ordering::Relaxed),
reclaimer.maximum_retired_pcm_bytes
);
assert_eq!(maximum_voices, 32);
assert_eq!(failures.load(Ordering::Relaxed), 0);
assert_eq!(allocator.load(Ordering::Relaxed), 0);
}
@@ -0,0 +1,215 @@
//! Real process qualification: no window, slow consumer, pause and broken IPC.
use prometeu_host_desktop_winit::studio::wire::*;
use std::io::{self, BufRead, Write};
use std::net::{Shutdown, TcpListener, TcpStream};
use std::process::{Child, Command, ExitStatus, Stdio};
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
struct Session {
child: Child,
control: Reader<TcpStream>,
writer: Writer<TcpStream>,
video: Reader<TcpStream>,
control_socket: TcpStream,
video_socket: TcpStream,
logs: Arc<Mutex<Vec<String>>>,
}
impl Session {
fn start() -> Self {
let control = TcpListener::bind("127.0.0.1:0").unwrap();
let video = TcpListener::bind("127.0.0.1:0").unwrap();
let cart = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../test-cartridges/dummy-boy");
let child = Command::new(env!("CARGO_BIN_EXE_prometeu-host-desktop-winit"))
.args(["--studio", "--run"])
.arg(cart)
.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::piped())
.spawn()
.unwrap();
let logs = Arc::new(Mutex::new(Vec::new()));
let mut session_child = child;
for stream in [
Box::new(session_child.stdout.take().unwrap()) as Box<dyn io::Read + Send>,
Box::new(session_child.stderr.take().unwrap()) as Box<dyn io::Read + Send>,
] {
let log = logs.clone();
std::thread::spawn(move || {
for line in io::BufReader::new(stream).lines().map_while(Result::ok) {
let mut lines = log.lock().unwrap();
if lines.len() == 200 {
lines.remove(0);
}
lines.push(line);
}
});
}
let mut p = vec![3; 16];
p.extend_from_slice(&[7; 32]);
p.extend_from_slice(&control.local_addr().unwrap().port().to_le_bytes());
p.extend_from_slice(&video.local_addr().unwrap().port().to_le_bytes());
p.push(1);
Writer::new(session_child.stdin.take().unwrap()).send(BOOTSTRAP, 0, &p).unwrap();
fn accept(listener: TcpListener) -> TcpStream {
listener.set_nonblocking(true).unwrap();
let deadline = Instant::now() + Duration::from_secs(10);
loop {
match listener.accept() {
Ok((s, _)) => {
s.set_nonblocking(false).unwrap();
s.set_read_timeout(Some(Duration::from_secs(10))).unwrap();
return s;
}
Err(e) if e.kind() == io::ErrorKind::WouldBlock => {
assert!(Instant::now() < deadline, "child did not connect");
std::thread::sleep(Duration::from_millis(5));
}
Err(e) => panic!("accept: {e}"),
}
}
}
let control = accept(control);
let video = accept(video);
let mut c = Reader::new(control.try_clone().unwrap());
let mut v = Reader::new(video.try_clone().unwrap());
for (message, role) in [(c.receive().unwrap(), 1), (v.receive().unwrap(), 2)] {
assert_eq!(message.header.kind, HELLO);
assert_eq!(&message.payload[..16], &[3; 16]);
assert_eq!(&message.payload[16..48], &[7; 32]);
assert_eq!(message.payload[48], role);
}
let control_socket = control.try_clone().unwrap();
let mut session = Self {
child: session_child,
control: c,
writer: Writer::new(control),
video: v,
control_socket,
video_socket: video,
logs,
};
let ready = session.control.receive().unwrap();
assert_eq!(ready.header.kind, READY, "{:?}", session.logs.lock().unwrap());
assert_eq!(u32::from_le_bytes(ready.payload[..4].try_into().unwrap()), 640);
session
}
fn command(&mut self, kind: u16, request: u64) -> Message {
self.writer.send(kind, request, &[]).unwrap();
let r = self.control.receive().unwrap();
assert_eq!(r.header.kind, RESULT, "{:?}", self.logs.lock().unwrap());
assert_eq!(r.header.request, request);
assert_eq!(u16::from_le_bytes(r.payload[2..4].try_into().unwrap()), 0, "{:?}", r.payload);
r
}
fn ping(&mut self) -> (u64, u64, u32) {
self.writer.send(PING, 0, &[]).unwrap();
let m = self.control.receive().unwrap();
assert_eq!(m.header.kind, PONG);
(
u64::from_le_bytes(m.payload[..8].try_into().unwrap()),
u64::from_le_bytes(m.payload[8..16].try_into().unwrap()),
u32::from_le_bytes(m.payload[16..20].try_into().unwrap()),
)
}
fn frame(&mut self) -> Message {
let m = self
.video
.receive()
.unwrap_or_else(|e| panic!("video: {e}; logs: {:?}", self.logs.lock().unwrap()));
assert_eq!(m.header.kind, FRAME);
assert_eq!(m.payload.len(), 48 + 640 * 360 * 4);
m
}
fn ack(&mut self, frame: &Message) {
self.writer.send(FRAME_RECEIVED, 0, &frame.payload[16..32]).unwrap();
}
fn exit(&mut self) -> ExitStatus {
let deadline = Instant::now() + Duration::from_secs(4);
loop {
if let Some(status) = self.child.try_wait().unwrap() {
return status;
}
assert!(
Instant::now() < deadline,
"runtime did not exit: {:?}",
self.logs.lock().unwrap()
);
std::thread::sleep(Duration::from_millis(10));
}
}
}
impl Drop for Session {
fn drop(&mut self) {
let _ = self.child.kill();
let _ = self.child.wait();
}
}
#[test]
fn slow_video_does_not_stop_ticks_and_pause_resumes_same_process() {
let mut s = Session::start();
let pid = s.child.id();
s.command(START, 1);
let first = s.frame();
let initial = s.ping();
std::thread::sleep(Duration::from_millis(150));
let later = s.ping();
assert!(later.1 > initial.1);
// No credit was returned while the runtime kept publishing. The next frame skips old presentations.
s.ack(&first);
let recent = s.frame();
assert!(
u64::from_le_bytes(recent.payload[24..32].try_into().unwrap())
> u64::from_le_bytes(first.payload[24..32].try_into().unwrap()) + 1
);
s.command(PAUSE, 2);
let paused = s.ping();
assert_eq!(paused.2, 2);
std::thread::sleep(Duration::from_millis(80));
assert_eq!(s.ping().1, paused.1);
s.command(RESUME, 3);
std::thread::sleep(Duration::from_millis(60));
assert!(s.ping().1 > paused.1);
assert_eq!(s.child.id(), pid);
s.command(STOP, 4);
assert_eq!(s.control.receive().unwrap().header.kind, STOPPED);
assert!(s.exit().success());
}
#[test]
fn broken_video_ends_runtime_even_when_paused() {
let mut s = Session::start();
s.command(START, 1);
s.command(PAUSE, 2);
s.video_socket.shutdown(Shutdown::Both).unwrap();
assert!(!s.exit().success());
}
#[test]
fn startup_focus_loss_arms_game_without_advancing_until_manual_resume() {
let mut s = Session::start();
let initial = s.ping().1;
s.command(PAUSE, 1);
s.command(START, 2);
std::thread::sleep(Duration::from_millis(50));
let paused = s.ping();
assert_eq!(paused.1, initial);
assert_eq!(paused.2, 2);
s.command(RESUME, 3);
let _ = s.frame();
assert!(s.ping().1 > initial);
s.command(STOP, 4);
assert_eq!(s.control.receive().unwrap().header.kind, STOPPED);
assert!(s.exit().success());
}
#[test]
fn truncated_control_ends_only_its_owned_runtime() {
let mut s = Session::start();
s.command(START, 1);
s.control_socket.write_all(b"PST").unwrap();
s.control_socket.shutdown(Shutdown::Write).unwrap();
assert!(!s.exit().success());
}
@@ -0,0 +1,38 @@
use prometeu_host_desktop_winit::studio::wire::*;
#[test]
fn rgba_fixture_pins_channel_order_and_metadata() {
let path = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
.join("../../../devtools/studio-protocol/fixtures/rgba.hex");
let bytes: Vec<u8> = std::fs::read_to_string(path)
.unwrap()
.split_whitespace()
.map(|s| u8::from_str_radix(s, 16).unwrap())
.collect();
let m = Reader::new(bytes.as_slice()).receive().unwrap();
assert_eq!(m.header.kind, FRAME);
assert_eq!(m.header.length, 56);
assert_eq!(&m.payload[..16], &(0u8..16).collect::<Vec<_>>());
assert_eq!(
&m.payload[48..],
&[0xff0000ffu32.to_be_bytes(), 0x0000ff80u32.to_be_bytes()].concat()
);
assert_eq!(frame_bytes(2, 1, 2).unwrap() + FRAME_METADATA_BYTES, m.payload.len());
}
#[test]
fn bootstrap_rejects_wrong_roles_lengths_and_ports() {
let mut p = vec![0; 53];
p[48..50].copy_from_slice(&1234u16.to_le_bytes());
p[50..52].copy_from_slice(&1235u16.to_le_bytes());
p[52] = 1;
let mut bytes = Vec::new();
Writer::new(&mut bytes).send(BOOTSTRAP, 0, &p).unwrap();
let boot = Bootstrap::read(bytes.as_slice()).unwrap();
assert!(boot.disposable);
assert_eq!(boot.hello(1).len(), 49);
p[50..52].copy_from_slice(&1234u16.to_le_bytes());
bytes.clear();
Writer::new(&mut bytes).send(BOOTSTRAP, 0, &p).unwrap();
assert!(Bootstrap::read(bytes.as_slice()).is_err());
}
@@ -0,0 +1,56 @@
//! Unpaced logical-frame and capture timing through the real headless host.
use prometeu_host_headless::{AdvanceFrameOutcome, HeadlessHost};
use std::time::Instant;
fn stats(mut times: Vec<u64>) -> serde_json::Value {
times.sort_unstable();
let n = times.len();
serde_json::json!({"mean_us":times.iter().sum::<u64>() as f64/n as f64/1000.0,
"p95_us":times[(n*95).div_ceil(100)-1] as f64/1000.0,
"p99_us":times[(n*99).div_ceil(100)-1] as f64/1000.0,
"max_us":times[n-1] as f64/1000.0,
"over_60hz_budget":times.iter().filter(|&&t|t>1_000_000_000/60).count()})
}
fn main() {
let mut args = std::env::args().skip(1);
let cartridge = args.next().expect("cartridge directory");
let count: usize = args.next().map(|s| s.parse().expect("frame count")).unwrap_or(600);
assert!(count > 0);
let mut host = HeadlessHost::new();
host.boot(cartridge).expect("boot");
let mut advance = Vec::with_capacity(count);
let mut capture = Vec::with_capacity(count);
let mut previous = None;
let mut published = 0;
let mut checksum = 0;
for i in 0..count + 120 {
let start = Instant::now();
assert!(matches!(
host.advance_frame().expect("advance"),
AdvanceFrameOutcome::FrameCompleted { .. }
));
let elapsed = start.elapsed().as_nanos() as u64;
let start = Instant::now();
let frame = host.capture_frame().expect("published frame").frame;
let capture_ns = start.elapsed().as_nanos() as u64;
assert_eq!((frame.width, frame.height, frame.stride_pixels), (640, 360, 640));
assert_ne!(previous, Some((frame.ownership, frame.frame_id)));
previous = Some((frame.ownership, frame.frame_id));
checksum ^= frame.pixels[(i * 173) % frame.pixels.len()];
if i >= 120 {
advance.push(elapsed);
capture.push(capture_ns);
published += 1;
}
}
let state = host.get_state();
println!(
"{}",
serde_json::json!({"schema":1,"width":640,"height":360,"frames":count,"warmup_frames":120,
"completed_logical_frames_total":state.frame_index,"host_ticks_total":state.tick_index,
"published_frames_measured":published,"repeated_publications_measured":0,
"advance_including_vm_render_publish":stats(advance),"owned_capture":stats(capture),"checksum":checksum,
"vm_hz":null,"physical_display_hz":null,
"limitations":"unpaced real VM/headless; capture copies owned pixels; no GPU, realtime cadence or physical display"})
);
}
@@ -2,7 +2,7 @@
mod wire; mod wire;
pub use wire::Limits; pub use wire::Limits;
use crate::{AdvanceFrameOutcome, HeadlessHost}; use crate::{AdvanceFrameOutcome, HeadlessHost, PendingWrites, TeardownPolicy};
use serde_json::{Value, json}; use serde_json::{Value, json};
use std::io::{self, BufRead, Write}; use std::io::{self, BufRead, Write};
use std::sync::{Arc, Mutex, mpsc}; use std::sync::{Arc, Mutex, mpsc};
@@ -16,7 +16,8 @@ struct Control {
} }
enum Job { enum Job {
Work(String, Command), Work(String, Command, bool),
Shutdown(String, TeardownPolicy, bool, mpsc::Sender<bool>),
Stop(Option<String>), Stop(Option<String>),
ReadError(io::Error), ReadError(io::Error),
} }
@@ -104,6 +105,8 @@ fn read_commands<R: BufRead, W: Write>(
limits: &Limits, limits: &Limits,
) -> io::Result<()> { ) -> io::Result<()> {
let mut initialized = false; let mut initialized = false;
let mut memcard = false;
let mut log_read = false;
loop { loop {
let bytes = match read_line(&mut input, limits.max_command_bytes)? { let bytes = match read_line(&mut input, limits.max_command_bytes)? {
Line::Eof => break, Line::Eof => break,
@@ -142,12 +145,37 @@ fn read_commands<R: BufRead, W: Write>(
continue; continue;
} }
}; };
if let Command::Shutdown = command { if matches!(command, Command::GetLogs(_)) && !log_read {
let mut c = control.lock().unwrap(); output.reply(
c.canceled = true; Some(&id),
sender.send(Job::Stop(Some(id))).map_err(|_| io::Error::other("execution stopped"))?; Err(WireError::new(
"unsupported_capability",
"negotiate minor 1.2 and require log_read first",
)),
)?;
continue;
}
if command.needs_memcard() && !memcard {
output.reply(
Some(&id),
Err(WireError::new(
"unsupported_capability",
"negotiate minor 1.1 and require memcard first",
)),
)?;
continue;
}
if let Command::Shutdown(params) = command {
control.lock().unwrap().canceled = true;
let (tx, rx) = mpsc::channel();
sender
.send(Job::Shutdown(id, params.policy(), memcard, tx))
.map_err(|_| io::Error::other("execution stopped"))?;
if rx.recv().map_err(|_| io::Error::other("execution stopped"))? {
return Ok(()); return Ok(());
} }
continue;
}
if let Command::Initialize(params) = command { if let Command::Initialize(params) = command {
let result = if initialized { let result = if initialized {
Err(WireError::new("already_initialized", "session already initialized")) Err(WireError::new("already_initialized", "session already initialized"))
@@ -159,9 +187,23 @@ fn read_commands<R: BufRead, W: Write>(
.any(|c| !CAPABILITIES.contains(&c.as_str())) .any(|c| !CAPABILITIES.contains(&c.as_str()))
{ {
Err(WireError::new("unsupported_capability", "required capability unavailable")) Err(WireError::new("unsupported_capability", "required capability unavailable"))
} else if params.protocol_version.minor == 0
&& params.required_capabilities.iter().any(|c| c == "memcard")
{
Err(WireError::new("incompatible_version", "memcard requires protocol minor >= 1"))
} else if params.protocol_version.minor < 2
&& params.required_capabilities.iter().any(|c| c == "log_read")
{
Err(WireError::new("incompatible_version", "log_read requires protocol minor >= 2"))
} else { } else {
initialized = true; initialized = true;
Ok(json!({"protocolVersion":{"major":1,"minor":0},"capabilities":CAPABILITIES})) memcard = params.protocol_version.minor >= 1
&& params.required_capabilities.iter().any(|c| c == "memcard");
log_read = params.protocol_version.minor >= 2
&& params.required_capabilities.iter().any(|c| c == "log_read");
Ok(
json!({"protocolVersion":{"major":1,"minor":params.protocol_version.minor.min(2)},"capabilities":CAPABILITIES}),
)
}; };
output.reply(Some(&id), result)?; output.reply(Some(&id), result)?;
continue; continue;
@@ -197,7 +239,9 @@ fn read_commands<R: BufRead, W: Write>(
c.active = Some(id.clone()); c.active = Some(id.clone());
c.advancing = matches!(command, Command::Advance(_)); c.advancing = matches!(command, Command::Advance(_));
c.canceled = false; c.canceled = false;
sender.send(Job::Work(id, command)).map_err(|_| io::Error::other("execution stopped"))?; sender
.send(Job::Work(id, command, memcard))
.map_err(|_| io::Error::other("execution stopped"))?;
} }
let mut c = control.lock().unwrap(); let mut c = control.lock().unwrap();
c.canceled = true; c.canceled = true;
@@ -210,14 +254,39 @@ fn execute<W: Write>(
id: &str, id: &str,
output: &Output<W>, output: &Output<W>,
control: &Mutex<Control>, control: &Mutex<Control>,
memcard: bool,
) -> io::Result<Result<Value, WireError>> { ) -> io::Result<Result<Value, WireError>> {
Ok(match command { Ok(match command {
Command::Boot(p) => { Command::Boot(p) => {
host.boot(p.path).map(|()| wire::state(host.get_state())).map_err(wire::host_error) let result = if let Some(choice) = p.memcard_choice {
host.boot_with_memcard_choice(p.path, choice.into())
} else {
host.boot(p.path)
};
result.map(|()| wire::state(host.get_state())).map_err(wire::host_error)
} }
Command::Reset => { Command::Reset(params) => host
host.reset(); .reset_with_policy(params.policy())
Ok(wire::state(host.get_state())) .map(|snapshot| {
let mut state = wire::state(host.get_state());
if memcard {
state["memcard"] = json!(snapshot);
}
state
})
.map_err(wire::host_error),
Command::MemcardMount(p) => {
host.mount_memcard(p).map(|s| json!(s)).map_err(wire::host_error)
}
Command::MemcardUnmount => {
host.unmount_memcard().map(|s| json!(s)).map_err(wire::host_error)
}
Command::GetMemcardState => Ok(json!(host.get_memcard_state())),
Command::MemcardReconcile => {
host.reconcile_memcard().map(|s| json!(s)).map_err(wire::host_error)
}
Command::MemcardContinueInMemory => {
host.continue_memcard_in_memory().map(|s| json!(s)).map_err(wire::host_error)
} }
Command::SetInput(p) => { Command::SetInput(p) => {
host.set_input(p.into()); host.set_input(p.into());
@@ -229,6 +298,7 @@ fn execute<W: Write>(
} }
Command::GetState => Ok(wire::state(host.get_state())), Command::GetState => Ok(wire::state(host.get_state())),
Command::GetFault => Ok(host.get_fault().as_ref().map(wire::fault).unwrap_or(Value::Null)), Command::GetFault => Ok(host.get_fault().as_ref().map(wire::fault).unwrap_or(Value::Null)),
Command::GetLogs(params) => wire::logs(host, params, &output.session),
Command::Capture => host.capture_frame().map_err(wire::host_error).and_then(wire::capture), Command::Capture => host.capture_frame().map_err(wire::host_error).and_then(wire::capture),
Command::Advance(p) => { Command::Advance(p) => {
let mut result = json!({"requested":p.frames,"completed":0,"stop":"completed"}); let mut result = json!({"requested":p.frames,"completed":0,"stop":"completed"});
@@ -254,6 +324,10 @@ fn execute<W: Write>(
result["stop"] = json!("terminated"); result["stop"] = json!("terminated");
break; break;
} }
Ok(AdvanceFrameOutcome::ActionRequired) => {
result["stop"] = json!("action_required");
break;
}
Err(error) => { Err(error) => {
result["stop"] = json!("host_error"); result["stop"] = json!("host_error");
result["error"] = serde_json::to_value(wire::host_error(error))?; result["error"] = serde_json::to_value(wire::host_error(error))?;
@@ -283,7 +357,7 @@ pub fn serve<R: BufRead + Send + 'static, W: Write + Send + 'static>(
let output = let output =
Arc::new(Output { writer: Mutex::new(writer), session, limit: limits.max_response_bytes }); Arc::new(Output { writer: Mutex::new(writer), session, limit: limits.max_response_bytes });
output.send( output.send(
json!({"type":"hello","sessionId":output.session,"protocolVersion":{"major":1,"minor":0}, json!({"type":"hello","sessionId":output.session,"protocolVersion":{"major":1,"minor":2},
"runtimeVersion":runtime_version,"capabilities":CAPABILITIES,"limits":limits}), "runtimeVersion":runtime_version,"capabilities":CAPABILITIES,"limits":limits}),
)?; )?;
let control = Arc::new(Mutex::new(Control::default())); let control = Arc::new(Mutex::new(Control::default()));
@@ -298,18 +372,58 @@ pub fn serve<R: BufRead + Send + 'static, W: Write + Send + 'static>(
} }
}); });
let mut host = HeadlessHost::new(); let mut host = HeadlessHost::new();
while let Ok(job) = receiver.recv() { loop {
host.poll_memcard();
let job = match receiver.recv_timeout(std::time::Duration::from_millis(5)) {
Ok(job) => job,
Err(mpsc::RecvTimeoutError::Timeout) => continue,
Err(mpsc::RecvTimeoutError::Disconnected) => break,
};
match job { match job {
Job::Work(id, command) => { Job::Work(id, command, memcard) => {
let result = execute(&mut host, command, &id, &output, &control)?; let result = match execute(&mut host, command, &id, &output, &control, memcard) {
Ok(result) => result,
Err(error) => {
cleanup_after_loss(&mut host);
return Err(error);
}
};
// Release authority under the same lock as response publication: // Release authority under the same lock as response publication:
// a client reacting to this reply cannot race a stale busy flag. // a client reacting to this reply cannot race a stale busy flag.
let mut c = control.lock().unwrap(); let mut c = control.lock().unwrap();
output.reply(Some(&id), result)?; if let Err(error) = output.reply(Some(&id), result) {
drop(c);
cleanup_after_loss(&mut host);
return Err(error);
}
c.active = None; c.active = None;
c.advancing = false; c.advancing = false;
} }
Job::Shutdown(id, policy, memcard, ack) => match host.shutdown(policy) {
Ok(snapshot) => {
drop(host);
let mut value = json!({"closed":true});
if memcard {
value["memcard"] = json!(snapshot);
}
output.reply(Some(&id), Ok(value))?;
let _ = ack.send(true);
reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
return Ok(());
}
Err(error) => {
if let Err(error) = output.reply(Some(&id), Err(wire::host_error(error))) {
cleanup_after_loss(&mut host);
return Err(error);
}
let _ = ack.send(false);
}
},
Job::Stop(id) => { Job::Stop(id) => {
let _ = host.shutdown(TeardownPolicy {
discard_unsaved: true,
pending_writes: PendingWrites::Cancel,
});
drop(host); drop(host);
if let Some(id) = id { if let Some(id) = id {
output.reply(Some(&id), Ok(json!({"closed":true})))?; output.reply(Some(&id), Ok(json!({"closed":true})))?;
@@ -317,13 +431,24 @@ pub fn serve<R: BufRead + Send + 'static, W: Write + Send + 'static>(
reader.join().map_err(|_| io::Error::other("input reader panicked"))?; reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
return Ok(()); return Ok(());
} }
Job::ReadError(error) => return Err(error), Job::ReadError(error) => {
let _ = host.shutdown(TeardownPolicy {
discard_unsaved: true,
pending_writes: PendingWrites::Cancel,
});
return Err(error);
}
} }
} }
reader.join().map_err(|_| io::Error::other("input reader panicked"))?; reader.join().map_err(|_| io::Error::other("input reader panicked"))?;
Ok(()) Ok(())
} }
fn cleanup_after_loss(host: &mut HeadlessHost) {
let _ = host
.shutdown(TeardownPolicy { discard_unsaved: true, pending_writes: PendingWrites::Cancel });
}
#[cfg(test)] #[cfg(test)]
mod tests { mod tests {
use super::*; use super::*;
@@ -369,7 +494,7 @@ mod tests {
"../../../../../devtools/headless-protocol/requests.json" "../../../../../devtools/headless-protocol/requests.json"
)) ))
.unwrap(); .unwrap();
assert_eq!(requests.len(), 11); assert!(!requests.is_empty());
for request in requests { for request in requests {
wire::parse(serde_json::from_value(request).unwrap()).unwrap(); wire::parse(serde_json::from_value(request).unwrap()).unwrap();
} }
@@ -8,7 +8,10 @@ use std::io;
#[cfg(test)] #[cfg(test)]
mod fault_tests; mod fault_tests;
use crate::{CapturedFrame, HostError, HostExecutionStatus, HostState}; use crate::{
CapturedFrame, HostError, HostExecutionStatus, HostState, MediaAccess, MediaAction,
MemcardChoice, MemcardMount, PendingWrites, TeardownPolicy,
};
pub const CAPABILITIES: &[&str] = &[ pub const CAPABILITIES: &[&str] = &[
"boot", "boot",
@@ -19,8 +22,15 @@ pub const CAPABILITIES: &[&str] = &[
"capture", "capture",
"get_state", "get_state",
"get_fault", "get_fault",
"log_read",
"cancel", "cancel",
"shutdown", "shutdown",
"memcard",
"memcard_mount",
"memcard_unmount",
"get_memcard_state",
"memcard_reconcile",
"memcard_continue_in_memory",
]; ];
#[derive(Clone, Debug, Serialize)] #[derive(Clone, Debug, Serialize)]
@@ -95,6 +105,33 @@ pub(super) struct Initialize {
#[serde(deny_unknown_fields)] #[serde(deny_unknown_fields)]
pub(super) struct Boot { pub(super) struct Boot {
pub path: String, pub path: String,
#[serde(default, rename = "memcardChoice", deserialize_with = "present")]
pub memcard_choice: Option<MemcardChoice>,
}
fn present<'de, D: serde::Deserializer<'de>, T: Deserialize<'de>>(
d: D,
) -> Result<Option<T>, D::Error> {
T::deserialize(d).map(Some)
}
#[derive(Debug, Default, Deserialize)]
#[serde(default, deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Teardown {
#[serde(deserialize_with = "present")]
pub discard_unsaved: Option<bool>,
#[serde(deserialize_with = "present")]
pub pending_writes: Option<PendingWrites>,
}
impl Teardown {
pub fn explicit(&self) -> bool {
self.discard_unsaved.is_some() || self.pending_writes.is_some()
}
pub fn policy(&self) -> TeardownPolicy {
TeardownPolicy {
discard_unsaved: self.discard_unsaved.unwrap_or(false),
pending_writes: self.pending_writes.unwrap_or_default(),
}
}
} }
#[derive(Debug, Deserialize)] #[derive(Debug, Deserialize)]
@@ -103,6 +140,19 @@ pub(super) struct Advance {
pub frames: u64, pub frames: u64,
} }
#[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct GetLogs {
// Explicit deserializer makes the nullable field required, including on first read.
#[serde(deserialize_with = "nullable_cursor")]
pub after_sequence: Option<u64>,
pub limit: u16,
}
fn nullable_cursor<'de, D: serde::Deserializer<'de>>(d: D) -> Result<Option<u64>, D::Error> {
Option::<u64>::deserialize(d)
}
#[derive(Debug, Deserialize)] #[derive(Debug, Deserialize)]
#[serde(deny_unknown_fields, rename_all = "camelCase")] #[serde(deny_unknown_fields, rename_all = "camelCase")]
pub(super) struct Cancel { pub(super) struct Cancel {
@@ -155,15 +205,35 @@ impl From<Input> for InputSignals {
pub(super) enum Command { pub(super) enum Command {
Initialize(Initialize), Initialize(Initialize),
Boot(Boot), Boot(Boot),
Reset, Reset(Teardown),
MemcardMount(MemcardMount),
MemcardUnmount,
GetMemcardState,
MemcardReconcile,
MemcardContinueInMemory,
SetInput(Input), SetInput(Input),
ClearInput, ClearInput,
Advance(Advance), Advance(Advance),
Capture, Capture,
GetState, GetState,
GetFault, GetFault,
GetLogs(GetLogs),
Cancel(Cancel), Cancel(Cancel),
Shutdown, Shutdown(Teardown),
}
impl Command {
pub fn needs_memcard(&self) -> bool {
match self {
Self::MemcardMount(_)
| Self::MemcardUnmount
| Self::GetMemcardState
| Self::MemcardReconcile
| Self::MemcardContinueInMemory => true,
Self::Boot(p) => p.memcard_choice.is_some(),
Self::Reset(p) | Self::Shutdown(p) => p.explicit(),
_ => false,
}
}
} }
fn params<T: serde::de::DeserializeOwned>(value: Value) -> Result<T, WireError> { fn params<T: serde::de::DeserializeOwned>(value: Value) -> Result<T, WireError> {
@@ -192,6 +262,24 @@ pub(super) fn parse(req: Request) -> Result<(String, Command), WireError> {
Command::Boot(p) Command::Boot(p)
} }
"advance" => Command::Advance(params(req.params)?), "advance" => Command::Advance(params(req.params)?),
"get_logs" => {
let p: GetLogs = params(req.params)?;
if !(1..=1024).contains(&p.limit) {
return Err(WireError::new("invalid_params", "limit must be 1..1024"));
}
Command::GetLogs(p)
}
"reset" => Command::Reset(params(req.params)?),
"shutdown" => Command::Shutdown(params(req.params)?),
"memcard_mount" => {
let p: MemcardMount = params(req.params)?;
if p.path.trim().is_empty()
|| matches!((p.action, p.access), (MediaAction::Create, MediaAccess::ReadOnly))
{
return Err(WireError::new("invalid_params", "invalid media path/action/access"));
}
Command::MemcardMount(p)
}
"set_input" => Command::SetInput(params(req.params)?), "set_input" => Command::SetInput(params(req.params)?),
"cancel" => { "cancel" => {
let p: Cancel = params(req.params)?; let p: Cancel = params(req.params)?;
@@ -200,15 +288,25 @@ pub(super) fn parse(req: Request) -> Result<(String, Command), WireError> {
} }
Command::Cancel(p) Command::Cancel(p)
} }
"reset" | "clear_input" | "capture" | "get_state" | "get_fault" | "shutdown" => { "clear_input"
| "capture"
| "get_state"
| "get_fault"
| "memcard_unmount"
| "get_memcard_state"
| "memcard_reconcile"
| "memcard_continue_in_memory" => {
empty(&req.params)?; empty(&req.params)?;
match req.command.as_str() { match req.command.as_str() {
"reset" => Command::Reset, "memcard_unmount" => Command::MemcardUnmount,
"get_memcard_state" => Command::GetMemcardState,
"memcard_reconcile" => Command::MemcardReconcile,
"memcard_continue_in_memory" => Command::MemcardContinueInMemory,
"clear_input" => Command::ClearInput, "clear_input" => Command::ClearInput,
"capture" => Command::Capture, "capture" => Command::Capture,
"get_state" => Command::GetState, "get_state" => Command::GetState,
"get_fault" => Command::GetFault, "get_fault" => Command::GetFault,
_ => Command::Shutdown, _ => unreachable!(),
} }
} }
_ => return Err(WireError::new("unknown_command", "unknown command")), _ => return Err(WireError::new("unknown_command", "unknown command")),
@@ -231,6 +329,9 @@ impl WireError {
pub(super) fn host_error(error: HostError) -> WireError { pub(super) fn host_error(error: HostError) -> WireError {
let (code, details) = match &error { let (code, details) = match &error {
HostError::Memcard(e) => {
("memcard_error", json!({"operation":e.operation,"reason":e.reason,"state":e.state}))
}
HostError::AlreadyBooted => ("already_booted", json!({})), HostError::AlreadyBooted => ("already_booted", json!({})),
HostError::BootFailed { reason, report } => { HostError::BootFailed { reason, report } => {
("boot_failed", json!({"reason":reason,"fault":report.as_deref().map(fault)})) ("boot_failed", json!({"reason":reason,"fault":report.as_deref().map(fault)}))
@@ -278,6 +379,48 @@ pub(super) fn state(s: HostState) -> Value {
"status":status_name(s.status)}) "status":status_name(s.status)})
} }
pub(super) fn logs(
host: &crate::HeadlessHost,
params: GetLogs,
session: &str,
) -> Result<Value, WireError> {
let (events, oldest, newest) =
host.log_snapshot(params.after_sequence, usize::from(params.limit));
if params.after_sequence.is_some_and(|after| newest.is_none_or(|newest| after > newest)) {
return Err(WireError::new("invalid_cursor", "afterSequence exceeds the log stream"));
}
let gap = oldest.is_some_and(|oldest| match params.after_sequence {
None => oldest > 0,
Some(after) => after.checked_add(1).is_some_and(|next| next < oldest),
});
let next = events.last().map(|event| event.seq).or(params.after_sequence);
Ok(
json!({"sessionId":session,"logEpoch":0,"events":events.iter().map(log_event).collect::<Vec<_>>(),
"oldestSequence":oldest,"newestSequence":newest,"nextAfterSequence":next,
"gap":gap,"overflow":oldest.is_some_and(|oldest| oldest > 0)}),
)
}
fn log_event(event: &prometeu_hal::log::LogEvent) -> Value {
use prometeu_hal::log::{LogLevel, LogSource};
let level = match event.level {
LogLevel::Trace => "trace",
LogLevel::Debug => "debug",
LogLevel::Info => "info",
LogLevel::Warn => "warn",
LogLevel::Error => "error",
};
let (source, app_id) = match event.source {
LogSource::Pos => ("pos", None),
LogSource::Hub => ("hub", None),
LogSource::Vm => ("vm", None),
LogSource::Fs => ("fs", None),
LogSource::App { app_id } => ("app", Some(app_id)),
};
json!({"sequence":event.seq,"frame":event.frame,"timestampMs":event.ts_ms,
"level":level,"source":source,"appId":app_id,"tag":event.tag,"message":event.msg})
}
pub(super) fn fault(report: &CrashReport) -> Value { pub(super) fn fault(report: &CrashReport) -> Value {
let mut result = json!({"kind":report.kind(),"pc":report.pc(),"summary":report.summary()}); let mut result = json!({"kind":report.kind(),"pc":report.pc(),"summary":report.summary()});
match report { match report {
@@ -323,3 +466,105 @@ pub(super) fn capture(c: CapturedFrame) -> Result<Value, WireError> {
"width":width,"height":height,"stridePixels":frame.stride_pixels,"pixelFormat":"RGBA8888", "width":width,"height":height,"stridePixels":frame.stride_pixels,"pixelFormat":"RGBA8888",
"logicalFrameIndex":c.logical_frame_index,"frameId":frame.frame_id.get()})) "logicalFrameIndex":c.logical_frame_index,"frameId":frame.frame_id.get()}))
} }
#[cfg(test)]
mod log_tests {
use super::*;
use prometeu_hal::log::{LogEvent, LogLevel, LogSource};
#[test]
fn oversized_native_event_is_an_error_without_partial_result() {
let event = LogEvent {
seq: 0,
frame: 0,
ts_ms: 0,
level: LogLevel::Error,
source: LogSource::Vm,
tag: 0,
msg: "x".repeat(8192),
};
let output = super::super::Output {
writer: std::sync::Mutex::new(Vec::new()),
session: "session".into(),
limit: 4096,
};
output.reply(Some("logs"), Ok(json!({"events":[log_event(&event)]}))).unwrap();
let bytes = output.writer.into_inner().unwrap();
assert!(bytes.len() <= 4097);
let response: Value = serde_json::from_slice(&bytes).unwrap();
assert_eq!(response["error"]["code"], "response_too_large");
assert_eq!(response["requestId"], "logs");
assert!(response.get("result").is_none());
}
#[test]
fn native_records_preserve_unsigned_maxima_and_typed_sources() {
for (source, name, app_id) in [
(LogSource::Pos, "pos", None),
(LogSource::Hub, "hub", None),
(LogSource::Vm, "vm", None),
(LogSource::Fs, "fs", None),
(LogSource::App { app_id: u32::MAX }, "app", Some(u32::MAX)),
] {
for (level, level_name) in [
(LogLevel::Trace, "trace"),
(LogLevel::Debug, "debug"),
(LogLevel::Info, "info"),
(LogLevel::Warn, "warn"),
(LogLevel::Error, "error"),
] {
let event = LogEvent {
seq: u64::MAX,
frame: u64::MAX,
ts_ms: u64::MAX,
level,
source,
tag: u16::MAX,
msg: "complete native message".into(),
};
let encoded = log_event(&event);
let decoded: Value =
serde_json::from_slice(&serde_json::to_vec(&encoded).unwrap()).unwrap();
for key in ["sequence", "frame", "timestampMs"] {
assert_eq!(decoded[key].as_u64(), Some(u64::MAX));
}
assert_eq!(decoded["level"], level_name);
assert_eq!(decoded["source"], name);
assert_eq!(decoded["appId"], json!(app_id));
assert_eq!(decoded["tag"], u16::MAX);
assert_eq!(decoded["message"], event.msg);
}
}
}
#[test]
fn required_nullable_cursor_and_limit_reject_malformed_values() {
for value in [
json!({"limit":1}),
json!({"afterSequence":null}),
json!({"afterSequence":-1,"limit":1}),
json!({"afterSequence":1.5,"limit":1}),
json!({"afterSequence":"0","limit":1}),
json!({"afterSequence":null,"limit":0}),
json!({"afterSequence":null,"limit":1025}),
json!({"afterSequence":null,"limit":1,"filter":"app"}),
] {
assert!(
parse(Request {
request_id: "logs".into(),
command: "get_logs".into(),
params: value
})
.is_err()
);
}
assert!(
parse(Request {
request_id: "logs".into(),
command: "get_logs".into(),
params: json!({"afterSequence":u64::MAX,"limit":1024})
})
.is_ok()
);
}
}
+299 -20
View File
@@ -1,5 +1,6 @@
use std::fmt; use std::fmt;
use std::sync::Arc; use std::sync::Arc;
use std::time::{Duration, Instant};
use prometeu_drivers::hardware::Hardware; use prometeu_drivers::hardware::Hardware;
use prometeu_drivers::{ControlledWallClock, MemoryBanks}; use prometeu_drivers::{ControlledWallClock, MemoryBanks};
@@ -11,9 +12,30 @@ use prometeu_hal::{
RuntimePlatform, TelemetryPlatform, WallClock, RuntimePlatform, TelemetryPlatform, WallClock,
}; };
use prometeu_system::{CrashReport, LatestRenderFrameStore}; use prometeu_system::{CrashReport, LatestRenderFrameStore};
#[path = "memcard.rs"]
mod memcard;
pub use memcard::{
MediaAccess, MediaAction, MemcardChoice, MemcardFailure, MemcardMount, MemcardState,
PendingWrites, TeardownPolicy,
};
const BOOT_TICK_LIMIT: usize = 5000; const BOOT_TICK_LIMIT: usize = 5000;
const HOST_FRAME_ADVANCE_TICK_LIMIT: usize = 100_000; const HOST_FRAME_ADVANCE_TICK_LIMIT: usize = 100_000;
const BOOTSTRAP_IO_WAIT_QUANTUM: Duration = Duration::from_millis(5);
const BOOTSTRAP_IO_WAIT_LIMIT: Duration = Duration::from_secs(2);
/// One deadline for the entire advance, including repeated admission to the gate.
#[derive(Default)]
struct BootstrapIoWait {
deadline: Option<Instant>,
}
impl BootstrapIoWait {
fn next_wait(&mut self, now: Instant) -> Option<Duration> {
let deadline = *self.deadline.get_or_insert(now + BOOTSTRAP_IO_WAIT_LIMIT);
let remaining = deadline.saturating_duration_since(now);
(!remaining.is_zero()).then_some(remaining.min(BOOTSTRAP_IO_WAIT_QUANTUM))
}
}
/// One published logical frame plus the automation counter. /// One published logical frame plus the automation counter.
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
@@ -46,6 +68,7 @@ pub enum AdvanceFrameOutcome {
FrameCompleted { logical_frame_index: u64, frame_id: FrameId }, FrameCompleted { logical_frame_index: u64, frame_id: FrameId },
Faulted(CrashReport), Faulted(CrashReport),
Terminated, Terminated,
ActionRequired,
} }
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
@@ -53,6 +76,7 @@ pub enum AdvanceFramesStop {
Completed, Completed,
Faulted(CrashReport), Faulted(CrashReport),
Terminated, Terminated,
ActionRequired,
} }
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
@@ -64,6 +88,7 @@ pub struct AdvanceFramesOutcome {
#[derive(Debug, Clone, PartialEq, Eq)] #[derive(Debug, Clone, PartialEq, Eq)]
pub enum HostError { pub enum HostError {
Memcard(Box<MemcardFailure>),
AlreadyBooted, AlreadyBooted,
BootFailed { reason: String, report: Option<Box<CrashReport>> }, BootFailed { reason: String, report: Option<Box<CrashReport>> },
InvalidState { operation: &'static str, status: HostExecutionStatus }, InvalidState { operation: &'static str, status: HostExecutionStatus },
@@ -75,6 +100,7 @@ pub enum HostError {
impl fmt::Display for HostError { impl fmt::Display for HostError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self { match self {
Self::Memcard(error) => write!(f, "{}: {}", error.operation, error.reason),
Self::AlreadyBooted => write!(f, "boot requires reset before another attempt"), Self::AlreadyBooted => write!(f, "boot requires reset before another attempt"),
Self::BootFailed { reason, .. } => write!(f, "boot failed: {reason}"), Self::BootFailed { reason, .. } => write!(f, "boot failed: {reason}"),
Self::InvalidState { operation, status } => { Self::InvalidState { operation, status } => {
@@ -98,12 +124,15 @@ impl std::error::Error for HostError {}
/// In-process host. The desktop winit runner is a separate crate and is not linked here. /// In-process host. The desktop winit runner is a separate crate and is not linked here.
pub struct HeadlessHost { pub struct HeadlessHost {
audio: Box<prometeu_drivers::engine::AudioMixer>,
audio_packet: prometeu_drivers::engine::Packet,
firmware: Firmware, firmware: Firmware,
platform: HeadlessPlatform, platform: HeadlessPlatform,
signals: InputSignals, signals: InputSignals,
boot_attempted: bool, boot_attempted: bool,
last_completed_frame: Option<CompletedFrame>, last_completed_frame: Option<CompletedFrame>,
controlled_wall_clock: Option<Arc<ControlledWallClock>>, controlled_wall_clock: Option<Arc<ControlledWallClock>>,
media: memcard::MediaSelection,
} }
#[derive(Debug, Clone, Copy)] #[derive(Debug, Clone, Copy)]
@@ -129,6 +158,25 @@ impl HeadlessHost {
self.firmware.os.memcard().admission.state self.firmware.os.memcard().admission.state
} }
fn apply_audio_commands(&mut self) {
let transport = self.platform.hardware.audio.transport();
self.audio.retire_inactive(&mut self.audio_packet);
if let Some(delivery) = transport.try_take() {
self.audio.apply_delivery_into(delivery, &mut self.audio_packet);
}
self.audio_packet.recycle(&transport);
}
/// Render stereo 48 kHz independently of firmware/graphics progress.
pub fn render_audio(&mut self, output: &mut [f32]) {
self.apply_audio_commands();
self.audio.mix(output);
self.audio.retire_inactive(&mut self.audio_packet);
self.audio_packet.recycle(&self.platform.hardware.audio.transport());
}
pub fn audio_diagnostics(&self) -> prometeu_drivers::engine::AudioDiagnostics {
self.audio.diagnostics
}
pub fn new() -> Self { pub fn new() -> Self {
let clock = Arc::new(ControlledWallClock::default()); let clock = Arc::new(ControlledWallClock::default());
Self::with_clock(clock.clone(), Some(clock)) Self::with_clock(clock.clone(), Some(clock))
@@ -147,12 +195,15 @@ impl HeadlessHost {
let hardware = Hardware::new_with_memory_banks(Arc::clone(&memory_banks), clock); let hardware = Hardware::new_with_memory_banks(Arc::clone(&memory_banks), clock);
let store = LatestRenderFrameStore::default(); let store = LatestRenderFrameStore::default();
Self { Self {
audio: Box::new(prometeu_drivers::engine::AudioMixer::new()),
audio_packet: prometeu_drivers::engine::Packet::new(),
firmware: Firmware::new(None), firmware: Firmware::new(None),
platform: HeadlessPlatform { hardware, store }, platform: HeadlessPlatform { hardware, store },
signals: InputSignals::default(), signals: InputSignals::default(),
boot_attempted: false, boot_attempted: false,
last_completed_frame: None, last_completed_frame: None,
controlled_wall_clock, controlled_wall_clock,
media: Default::default(),
} }
} }
@@ -166,6 +217,15 @@ impl HeadlessHost {
self.controlled_wall_clock.as_deref() self.controlled_wall_clock.as_deref()
} }
/// Observe native log history without advancing, draining or changing lifecycle.
pub fn log_snapshot(
&self,
after: Option<u64>,
limit: usize,
) -> (Vec<prometeu_hal::log::LogEvent>, Option<u64>, Option<u64>) {
self.firmware.os.log_snapshot(after, limit)
}
/// Load `path` and tick until the firmware is in `GameRunning`. /// Load `path` and tick until the firmware is in `GameRunning`.
/// ///
/// The transition into `GameRunning` is the last tick. The first game /// The transition into `GameRunning` is the last tick. The first game
@@ -189,15 +249,20 @@ impl HeadlessHost {
return Err(HostError::AlreadyBooted); return Err(HostError::AlreadyBooted);
} }
self.boot_attempted = true; self.boot_attempted = true;
self.media.choice = choice;
self.media.boot_phase = "loading";
let path = path.into(); let path = path.into();
self.firmware.boot_target = BootTarget::Cartridge { path, debug: false, debug_port: 7777 }; self.firmware.boot_target = BootTarget::Cartridge { path, debug: false, debug_port: 7777 };
let boot_deadline = std::time::Instant::now() + std::time::Duration::from_secs(5); let boot_deadline = std::time::Instant::now() + std::time::Duration::from_secs(5);
let mut choice_submitted = false;
for _ in 0..BOOT_TICK_LIMIT { for _ in 0..BOOT_TICK_LIMIT {
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) { if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
self.media.boot_phase = "running";
return Ok(()); return Ok(());
} }
if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) { if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) {
self.media.boot_phase = "failed";
let report = self.get_fault(); let report = self.get_fault();
let reason = report let reason = report
.as_ref() .as_ref()
@@ -206,33 +271,55 @@ impl HeadlessHost {
return Err(HostError::BootFailed { reason, report: report.map(Box::new) }); return Err(HostError::BootFailed { reason, report: report.map(Box::new) });
} }
if matches!(self.firmware.state, FirmwareState::HubHome(_)) { if matches!(self.firmware.state, FirmwareState::HubHome(_)) {
self.media.boot_phase = "failed";
return Err(HostError::BootFailed { return Err(HostError::BootFailed {
reason: "cartridge did not load".to_string(), reason: "cartridge did not load".to_string(),
report: None, report: None,
}); });
} }
let progress = self.firmware.os.memcard().lane.progress_stamp(); let progress = self.firmware.os.memcard().lane.progress_stamp();
if let FirmwareState::LoadCartridge(step) = &self.firmware.state
&& step.cartridge.memcard_slots.is_none()
&& choice.is_some()
{
self.media.boot_phase = "failed";
return Err(self.memcard_error("boot", "invalid_state"));
}
if choice_submitted
&& let prometeu_system::memcard::admission::PreparationState::Failed(error) =
self.firmware.os.memcard().admission.state
{
self.media.boot_phase = "failed";
return Err(self.memcard_error("boot", memcard::error_name(error)));
}
let waiting = matches!(&self.firmware.state,FirmwareState::LoadCartridge(step) if step.needs_memcard_choice()); let waiting = matches!(&self.firmware.state,FirmwareState::LoadCartridge(step) if step.needs_memcard_choice());
if waiting { if waiting {
let Some(choice) = choice else { let Some(choice) = choice else {
return Err(HostError::BootFailed { self.media.boot_phase = "choice_required";
reason: "Memory-card choice required; use boot_with_memcard_choice".into(), return Err(self.memcard_error("boot", "choice_required"));
report: None,
});
}; };
self.signals = InputSignals::default(); if self.firmware.os.memcard().preparation_active() {
self.tick_once(); self.poll_memcard();
self.signals = match choice { self.firmware
prometeu_system::memcard::admission::Choice::Persistent => { .os
InputSignals { a_signal: true, ..Default::default() } .memcard()
.lane
.wait_for_progress(progress, std::time::Duration::from_millis(5));
continue;
} }
prometeu_system::memcard::admission::Choice::MemoryFresh => { let created_at = self.platform.wall_clock().utc_unix_seconds();
InputSignals { x_signal: true, ..Default::default() } let result = match &mut self.firmware.state {
} FirmwareState::LoadCartridge(step) => {
prometeu_system::memcard::admission::Choice::MemoryExisting => { step.choose_memcard(&mut self.firmware.os, choice, created_at)
InputSignals { y_signal: true, ..Default::default() }
} }
_ => unreachable!(),
}; };
if let Err(error) = result {
self.media.boot_phase = "failed";
return Err(self.memcard_error("boot", memcard::error_name(error)));
}
choice_submitted = true;
self.media.boot_phase = "preparing";
} }
self.tick_once(); self.tick_once();
self.signals = InputSignals::default(); self.signals = InputSignals::default();
@@ -251,6 +338,7 @@ impl HeadlessHost {
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) { if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
Ok(()) Ok(())
} else { } else {
self.media.boot_phase = "failed";
Err(HostError::BootFailed { Err(HostError::BootFailed {
reason: "boot did not reach the game".to_string(), reason: "boot did not reach the game".to_string(),
report: self.get_fault().map(Box::new), report: self.get_fault().map(Box::new),
@@ -258,7 +346,10 @@ impl HeadlessHost {
} }
} }
pub fn reset(&mut self) { pub fn reset(&mut self) -> Result<(), HostError> {
self.reset_with_policy(TeardownPolicy::default()).map(|_| ())
}
fn reset_inner(&mut self) {
self.signals = InputSignals::default(); self.signals = InputSignals::default();
self.firmware.change_state( self.firmware.change_state(
FirmwareState::Reset(ResetStep), FirmwareState::Reset(ResetStep),
@@ -273,12 +364,14 @@ impl HeadlessHost {
pub fn pause(&mut self) -> Result<(), HostError> { pub fn pause(&mut self) -> Result<(), HostError> {
self.require_active("pause")?; self.require_active("pause")?;
self.firmware.os.vm().set_paused(true); self.firmware.os.vm().set_paused(true);
self.platform.hardware.audio.set_paused(true);
Ok(()) Ok(())
} }
pub fn resume(&mut self) -> Result<(), HostError> { pub fn resume(&mut self) -> Result<(), HostError> {
self.require_active("resume")?; self.require_active("resume")?;
self.firmware.os.vm().set_paused(false); self.firmware.os.vm().set_paused(false);
self.platform.hardware.audio.set_paused(false);
Ok(()) Ok(())
} }
@@ -286,8 +379,9 @@ impl HeadlessHost {
pub fn step(&mut self) -> Result<Option<CrashReport>, HostError> { pub fn step(&mut self) -> Result<Option<CrashReport>, HostError> {
self.require_active("step")?; self.require_active("step")?;
self.firmware.os.vm().set_paused(true); self.firmware.os.vm().set_paused(true);
self.platform.hardware.audio.set_paused(true);
let report = self.firmware.os.vm().debug_step_active_session(&mut self.platform); let report = self.firmware.os.vm().debug_step_active_session(&mut self.platform);
self.platform.hardware.audio.transport().consume_silently(); self.apply_audio_commands();
Ok(report) Ok(report)
} }
@@ -296,7 +390,11 @@ impl HeadlessHost {
return Ok(AdvanceFrameOutcome::Faulted(report)); return Ok(AdvanceFrameOutcome::Faulted(report));
} }
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) { if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
return Ok(AdvanceFrameOutcome::Terminated); return Ok(if self.host_action_required() {
AdvanceFrameOutcome::ActionRequired
} else {
AdvanceFrameOutcome::Terminated
});
} }
let start = self.firmware.os.vm().logical_frame_index(); let start = self.firmware.os.vm().logical_frame_index();
@@ -304,7 +402,13 @@ impl HeadlessHost {
self.firmware.os.vm().set_paused(false); self.firmware.os.vm().set_paused(false);
self.firmware.os.vm().request_debug_step(); self.firmware.os.vm().request_debug_step();
let mut io_wait = BootstrapIoWait::default();
for _ in 0..HOST_FRAME_ADVANCE_TICK_LIMIT { for _ in 0..HOST_FRAME_ADVANCE_TICK_LIMIT {
// A controlled lifecycle slice can consume the runtime step marker
// without closing a logical frame. This operation still owns the
// request until its first frame or an explicit stop boundary.
self.firmware.os.vm().set_paused(false);
self.firmware.os.vm().request_debug_step();
self.tick_once(); self.tick_once();
if let Some(report) = self.get_fault() { if let Some(report) = self.get_fault() {
self.finish_frame_advance(); self.finish_frame_advance();
@@ -312,7 +416,11 @@ impl HeadlessHost {
} }
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) { if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
self.finish_frame_advance(); self.finish_frame_advance();
return Ok(AdvanceFrameOutcome::Terminated); return Ok(if self.host_action_required() {
AdvanceFrameOutcome::ActionRequired
} else {
AdvanceFrameOutcome::Terminated
});
} }
let logical_frame_index = self.firmware.os.vm().logical_frame_index(); let logical_frame_index = self.firmware.os.vm().logical_frame_index();
@@ -333,6 +441,24 @@ impl HeadlessHost {
frame_id: frame.frame_id, frame_id: frame.frame_id,
}); });
} }
loop {
// Refresh before every observation/poll: another lane job may
// have progressed without completing this publication.
let progress = self.firmware.os.memcard().lane.progress_stamp();
if !self.bootstrap_io_pending() {
break;
}
// Native polling and waiting do not execute machine ticks.
self.poll_memcard();
if self.host_action_required() {
self.finish_frame_advance();
return Ok(AdvanceFrameOutcome::ActionRequired);
}
if self.bootstrap_io_pending() {
self.wait_for_bootstrap_io(&mut io_wait, progress)?;
}
}
} }
self.finish_frame_advance(); self.finish_frame_advance();
@@ -341,6 +467,32 @@ impl HeadlessHost {
}) })
} }
fn bootstrap_io_pending(&mut self) -> bool {
let FirmwareState::GameRunning(step) = &self.firmware.state else { return false };
let task = step.task_id;
let hook_complete = self
.firmware
.os
.sessions()
.vm_session_for_task(task)
.is_some_and(|session| session.vm.memcard_boot_result() == Some(0));
let service = self.firmware.os.memcard();
hook_complete && service.session.boot_pending() && service.session.io_active()
}
fn wait_for_bootstrap_io(
&mut self,
wait: &mut BootstrapIoWait,
progress: u64,
) -> Result<(), HostError> {
let Some(timeout) = wait.next_wait(Instant::now()) else {
self.finish_frame_advance();
return Err(self.memcard_error("advance", "restart_required"));
};
self.firmware.os.memcard().lane.wait_for_progress(progress, timeout);
Ok(())
}
pub fn advance_frames(&mut self, count: u64) -> Result<AdvanceFramesOutcome, HostError> { pub fn advance_frames(&mut self, count: u64) -> Result<AdvanceFramesOutcome, HostError> {
let mut completed = 0; let mut completed = 0;
for _ in 0..count { for _ in 0..count {
@@ -360,6 +512,13 @@ impl HeadlessHost {
stop: AdvanceFramesStop::Terminated, stop: AdvanceFramesStop::Terminated,
}); });
} }
AdvanceFrameOutcome::ActionRequired => {
return Ok(AdvanceFramesOutcome {
requested: count,
completed,
stop: AdvanceFramesStop::ActionRequired,
});
}
} }
} }
Ok(AdvanceFramesOutcome { requested: count, completed, stop: AdvanceFramesStop::Completed }) Ok(AdvanceFramesOutcome { requested: count, completed, stop: AdvanceFramesStop::Completed })
@@ -410,12 +569,14 @@ impl HeadlessHost {
fn tick_once(&mut self) { fn tick_once(&mut self) {
self.firmware.tick(&self.signals, &mut self.platform); self.firmware.tick(&self.signals, &mut self.platform);
self.platform.hardware.audio.transport().consume_silently(); self.apply_audio_commands();
} }
fn execution_status(&mut self) -> HostExecutionStatus { fn execution_status(&mut self) -> HostExecutionStatus {
if self.fault_is_visible() { if self.fault_is_visible() {
HostExecutionStatus::Faulted HostExecutionStatus::Faulted
} else if self.host_action_required() {
HostExecutionStatus::Paused
} else if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) { } else if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
HostExecutionStatus::Terminated HostExecutionStatus::Terminated
} else if self.firmware.os.vm().paused() { } else if self.firmware.os.vm().paused() {
@@ -432,7 +593,9 @@ impl HeadlessHost {
fn require_active(&mut self, operation: &'static str) -> Result<(), HostError> { fn require_active(&mut self, operation: &'static str) -> Result<(), HostError> {
let status = self.execution_status(); let status = self.execution_status();
if matches!(status, HostExecutionStatus::Running | HostExecutionStatus::Paused) { if matches!(status, HostExecutionStatus::Running | HostExecutionStatus::Paused)
&& !self.host_action_required()
{
Ok(()) Ok(())
} else { } else {
Err(HostError::InvalidState { operation, status }) Err(HostError::InvalidState { operation, status })
@@ -463,6 +626,11 @@ impl RenderSubmissionSink for HeadlessPlatform {
let frame_id = submission.frame_id; let frame_id = submission.frame_id;
let ownership = submission.ownership; let ownership = submission.ownership;
self.hardware.submit_render_submission(submission)?; self.hardware.submit_render_submission(submission)?;
// Host dialogs use their own producer and may reuse FrameId::ZERO.
// Capture/advance observe only canonical game publications.
if ownership.app_mode != prometeu_hal::app_mode::AppMode::Game {
return Ok(());
}
let (width, height) = self.hardware.gfx.size(); let (width, height) = self.hardware.gfx.size();
let pixels = self.hardware.gfx.front_buffer().to_vec(); let pixels = self.hardware.gfx.front_buffer().to_vec();
let frame = OwnedRgba8888Frame::packed(frame_id, ownership, width, height, pixels) let frame = OwnedRgba8888Frame::packed(frame_id, ownership, width, height, pixels)
@@ -590,3 +758,114 @@ mod tests {
directory directory
} }
} }
#[cfg(test)]
mod offline_audio_tests {
use super::*;
use prometeu_drivers::{
SoundBankPoolInstaller,
bank_format::{DecodedAudioBank, decode_audio_bank},
};
#[test]
fn cartridge_preloads_both_bank_types_and_guest_music_sfx_reach_shared_renderer() {
use prometeu_bytecode::{assembler::assemble, model::SyscallDecl};
use prometeu_hal::cartridge::{
ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude,
};
use prometeu_test_support::program::{TestProgram, int64_signature};
let unique =
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos();
let root = std::env::temp_dir()
.join(format!("prometeu-audio-cartridge-{}-{unique}", std::process::id()));
std::fs::create_dir_all(&root).unwrap();
let code=assemble("PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 1\nHOSTCALL 0\nPOP_N 1\nPUSH_I32 1\nPUSH_I32 0\nPUSH_I32 1\nHOSTCALL 0\nPOP_N 1\nPUSH_I32 0\nPUSH_I32 1\nPUSH_I32 0\nPUSH_I32 128\nPUSH_I32 128\nPUSH_I32 1\nPUSH_I32 1\nHOSTCALL 1\nPOP_N 1\nFRAME_SYNC\nRET").unwrap();
let mut program = TestProgram::single(code, int64_signature(0, 0), 0, 7);
program.syscalls = vec![
SyscallDecl {
module: "music".into(),
name: "play".into(),
version: 1,
arg_slots: 3,
ret_slots: 1,
},
SyscallDecl {
module: "audio".into(),
name: "play".into(),
version: 1,
arg_slots: 7,
ret_slots: 1,
},
];
std::fs::write(root.join("program.pbx"), program.serialize()).unwrap();
std::fs::write(root.join("manifest.json"),r#"{"magic":"PMTU","cartridge_version":1,"app_id":87,"title":"Audio pipeline","app_version":"1.0","app_mode":"Game","capabilities":["audio"]}"#).unwrap();
let sound = include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-sound.sbnk"
));
let music = include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-music.mbnk"
));
let header=serde_json::to_vec(&serde_json::json!({"asset_table":[{"asset_id":1,"asset_name":"sfx","bank_type":"SOUNDS","offset":0,"size":sound.len(),"decoded_size":6139,"codec":"NONE","metadata":{"version":1}},{"asset_id":2,"asset_name":"music","bank_type":"MUSIC","offset":sound.len(),"size":music.len(),"decoded_size":6395,"codec":"NONE","metadata":{"version":1}}],"preload":[{"asset_id":1,"slot":0},{"asset_id":2,"slot":0}]})).unwrap();
let mut pack = AssetsPackPrelude {
magic: ASSETS_PA_MAGIC,
schema_version: ASSETS_PA_SCHEMA_VERSION,
header_len: header.len() as u32,
payload_offset: (32 + header.len()) as u64,
flags: 0,
reserved: 0,
header_checksum: 0,
}
.to_bytes()
.to_vec();
pack.extend(header);
pack.extend(sound);
pack.extend(music);
std::fs::write(root.join("assets.pa"), pack).unwrap();
let mut host = HeadlessHost::new();
host.boot(root.to_string_lossy()).unwrap();
assert!(matches!(
host.advance_frame().unwrap(),
AdvanceFrameOutcome::FrameCompleted { .. }
));
host.resume().unwrap();
let before = host.firmware.os.vm().logical_frame_index();
let mut output = vec![0.0; 9600];
host.render_audio(&mut output);
assert!(output.iter().any(|v| *v != 0.0));
assert_eq!(host.audio_diagnostics().maximum_voices, 5);
assert_eq!(host.firmware.os.vm().logical_frame_index(), before);
let audio_before = host.audio_diagnostics().frames;
host.pause().unwrap();
let mut paused = [1.0; 200];
host.render_audio(&mut paused);
assert_eq!(paused, [0.0; 200]);
assert_eq!(host.audio_diagnostics().frames, audio_before);
host.resume().unwrap();
host.render_audio(&mut paused);
assert_eq!(host.audio_diagnostics().frames, audio_before + 100);
drop(host);
std::fs::remove_dir_all(root).unwrap();
}
#[test]
fn explicit_audio_render_advances_shared_sequence_without_any_game_frame() {
let mut host = HeadlessHost::new();
let bytes = include_bytes!(concat!(
env!("CARGO_MANIFEST_DIR"),
"/../../../test-fixtures/audio/mixed-music.mbnk"
));
let DecodedAudioBank::Music(bank) = decode_audio_bank(bytes, true).unwrap() else {
panic!()
};
host.platform.hardware.memory_banks.install_music_bank(0, Arc::new(bank));
host.platform.hardware.audio.music_play(0, 0, true);
host.platform.hardware.audio.finish_frame();
let before = host.firmware.os.vm().logical_frame_index();
let mut pcm = vec![0.0; 4800];
host.render_audio(&mut pcm);
assert_eq!(host.audio_diagnostics().frames, 2400);
assert!(pcm.iter().any(|v| *v != 0.0));
assert_eq!(host.firmware.os.vm().logical_frame_index(), before);
}
}
@@ -11,5 +11,6 @@ mod host;
pub use host::{ pub use host::{
AdvanceFrameOutcome, AdvanceFramesOutcome, AdvanceFramesStop, CapturedFrame, HeadlessHost, AdvanceFrameOutcome, AdvanceFramesOutcome, AdvanceFramesStop, CapturedFrame, HeadlessHost,
HostError, HostExecutionStatus, HostState, HostError, HostExecutionStatus, HostState, MediaAccess, MediaAction, MemcardChoice,
MemcardFailure, MemcardMount, MemcardState, PendingWrites, TeardownPolicy,
}; };
@@ -0,0 +1,480 @@
//! Public native host controls; all image policy stays in the shared system service.
use super::{HeadlessHost, HostError};
use prometeu_drivers::memcard::FileMemcard;
use prometeu_firmware::FirmwareState;
use prometeu_hal::memcard::{MemcardIoError, MemcardStorage};
use prometeu_system::memcard::{
admission::{Choice, PreparationState},
image::{Error, IMAGE_BYTES},
session::{Mode, RequestReason, RequestState},
transaction::Card,
};
use serde::{Deserialize, Serialize};
use std::{
path::PathBuf,
time::{Duration, Instant},
};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum MediaAction {
Open,
Create,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum MediaAccess {
ReadWrite,
ReadOnly,
}
#[derive(Debug, Clone, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct MemcardMount {
pub path: String,
pub action: MediaAction,
pub access: MediaAccess,
}
#[derive(Debug, Clone, Copy, Default, Deserialize, Serialize)]
#[serde(rename_all = "snake_case")]
pub enum PendingWrites {
#[default]
Wait,
Cancel,
}
#[derive(Debug, Clone, Copy, Default, Deserialize)]
#[serde(default, deny_unknown_fields, rename_all = "camelCase")]
pub struct TeardownPolicy {
pub discard_unsaved: bool,
pub pending_writes: PendingWrites,
}
#[derive(Debug, Clone, Copy, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum MemcardChoice {
Persistent,
MemoryFresh,
MemoryExisting,
}
impl From<MemcardChoice> for Choice {
fn from(c: MemcardChoice) -> Self {
match c {
MemcardChoice::Persistent => Self::Persistent,
MemcardChoice::MemoryFresh => Self::MemoryFresh,
MemcardChoice::MemoryExisting => Self::MemoryExisting,
}
}
}
pub(super) fn choice_name(c: Choice) -> &'static str {
match c {
Choice::Persistent => "persistent",
Choice::MemoryFresh => "memory_fresh",
Choice::MemoryExisting => "memory_existing",
}
}
pub(super) fn error_name(e: Error) -> &'static str {
match e {
Error::Io(e) => match e {
MemcardIoError::Unavailable => "unavailable",
MemcardIoError::ReadOnly => "read_only",
MemcardIoError::InvalidRange => "invalid_range",
MemcardIoError::NoSpace => "no_space",
MemcardIoError::Unsupported => "unsupported",
MemcardIoError::Busy => "busy",
MemcardIoError::AccessDenied => "access_denied",
MemcardIoError::AlreadyExists => "already_exists",
MemcardIoError::Indeterminate => "indeterminate",
MemcardIoError::IoError => "io_error",
},
Error::Corrupt => "corrupt",
Error::Unsupported => "unsupported",
Error::NoSpace => "no_space",
Error::InvalidRange => "invalid_range",
Error::CounterExhausted => "counter_exhausted",
Error::ReadOnly => "read_only",
Error::Indeterminate => "indeterminate",
Error::Busy => "busy",
Error::Canceled => "canceled",
Error::OutOfMemory => "out_of_memory",
Error::AccessDenied => "access_denied",
Error::InvalidState => "invalid_state",
Error::IdentityMismatch => "identity_mismatch",
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct MemcardState {
pub media: MediaState,
pub session: SessionState,
pub dirty: bool,
pub dirty_slots: Vec<usize>,
pub request: Option<RequestObservation>,
pub io: IoState,
pub recovery: RecoveryState,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct MediaState {
pub path: Option<PathBuf>,
pub card_id: Option<String>,
pub access: Option<MediaAccess>,
pub mount_epoch: String,
pub preparation: &'static str,
pub error: Option<&'static str>,
pub recovered: bool,
pub degraded: bool,
pub write_blocked: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct SessionState {
pub app_id: Option<u32>,
pub choice: Option<&'static str>,
pub mode: Option<&'static str>,
pub boot_attempted: bool,
pub boot_phase: &'static str,
pub resident: bool,
pub action_required: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RequestObservation {
pub id: String,
pub state: &'static str,
pub reason: &'static str,
pub storage_error: Option<&'static str>,
pub operation: &'static str,
pub slot: Option<usize>,
pub retained: bool,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
pub struct IoState {
pub active: bool,
pub deferred: bool,
pub phase: &'static str,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
#[serde(rename_all = "camelCase")]
pub struct RecoveryState {
pub removal_pending: bool,
pub reconciliation_required: bool,
pub restart_required: bool,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct MemcardFailure {
pub operation: &'static str,
pub reason: &'static str,
pub state: MemcardState,
}
#[derive(Default)]
pub(super) struct MediaSelection {
path: Option<PathBuf>,
access: Option<MediaAccess>,
card_id: Option<[u8; 16]>,
error: Option<&'static str>,
pub choice: Option<Choice>,
pub boot_phase: &'static str,
shutdown_failed: bool,
}
impl HeadlessHost {
/// Poll only native work. This does not tick firmware or execute guest code.
pub fn poll_memcard(&mut self) {
self.firmware.os.poll_background_io(&mut self.platform);
}
pub(super) fn memcard_error(
&mut self,
operation: &'static str,
reason: &'static str,
) -> HostError {
HostError::Memcard(Box::new(MemcardFailure {
operation,
reason,
state: self.get_memcard_state(),
}))
}
pub fn get_memcard_state(&mut self) -> MemcardState {
let resident = self.firmware.os.lifecycle().resident_game_task().is_some();
let service = self.firmware.os.memcard();
let d = service.session_diagnostics();
let preparation = service.preparation_active();
let host_faulted = service.host_faulted() || self.media.shutdown_failed;
let (state, error) = match service.admission.state {
PreparationState::Idle => ("idle", None),
PreparationState::Pending => ("pending", None),
PreparationState::Ready => ("ready", None),
PreparationState::Failed(e) => ("failed", Some(error_name(e))),
};
let id = d.card_id.or(service.installed_card_id()).or(self.media.card_id);
let health = if d.mode.is_some() {
d.health
} else {
service.installed_health().unwrap_or((false, false, false))
};
let phase = if preparation {
"preparing"
} else if d.request.as_ref().is_some_and(|r| r.deferred) {
"deferred"
} else if d.io_active {
if service.lane.telemetry().active_job_id == service.session.pending_job() {
"running"
} else {
"queued"
}
} else if d.request.is_some() {
"returned"
} else {
"idle"
};
MemcardState {
media: MediaState {
path: self.media.path.clone(),
access: self.media.access,
card_id: id.map(|id| id.iter().map(|v| format!("{v:02x}")).collect()),
mount_epoch: d.epoch.to_string(),
preparation: state,
error: error.or(self.media.error),
recovered: health.0,
degraded: health.1,
write_blocked: health.2,
},
session: SessionState {
app_id: d.app_id,
choice: self.media.choice.map(choice_name),
mode: d.mode.map(|m| match m {
Mode::Persistent => "persistent",
Mode::MemoryOnly => "memory_only",
}),
boot_attempted: self.boot_attempted,
boot_phase: if self.media.boot_phase.is_empty() {
"idle"
} else {
self.media.boot_phase
},
resident,
action_required: d.mode.is_some()
&& resident
&& (d.removal_pending
|| host_faulted
|| !matches!(self.firmware.state, FirmwareState::GameRunning(_))),
},
dirty: !d.dirty_slots.is_empty(),
dirty_slots: d.dirty_slots,
request: d.request.map(|r| RequestObservation {
id: r.result.id.to_string(),
state: match r.result.state {
RequestState::Pending => "pending",
RequestState::Success => "success",
RequestState::Failure => "failure",
RequestState::Indeterminate => "indeterminate",
RequestState::MemoryOnly => "memory_only",
},
reason: match r.result.reason {
RequestReason::None => "none",
RequestReason::Timeout => "timeout",
RequestReason::RestartRequired => "restart_required",
RequestReason::Storage(e) => error_name(e),
},
storage_error: r.storage_error.map(error_name),
operation: r.operation,
slot: r.slot,
retained: r.retained,
}),
io: IoState {
active: preparation || d.io_active,
deferred: phase == "deferred",
phase,
},
recovery: RecoveryState {
removal_pending: d.removal_pending,
reconciliation_required: d.reconciliation_required,
restart_required: host_faulted,
},
}
}
pub fn mount_memcard(&mut self, options: MemcardMount) -> Result<MemcardState, HostError> {
self.poll_memcard();
if self.firmware.os.lifecycle().resident_game_task().is_some() {
return Err(self.memcard_error("memcard_mount", "invalid_state"));
}
if options.path.trim().is_empty()
|| matches!(
(options.action, options.access),
(MediaAction::Create, MediaAccess::ReadOnly)
)
{
return Err(self.memcard_error("memcard_mount", "invalid_state"));
}
let path = std::path::absolute(&options.path)
.map_err(|_| self.memcard_error("memcard_mount", "unavailable"))?;
// Do not change selection when admission is refused as busy.
let open_path = path.clone();
let result = self.firmware.os.memcard().mount_card_with(move || {
let io = match options.action {
MediaAction::Open => {
FileMemcard::open(&open_path, options.access == MediaAccess::ReadOnly)?
}
MediaAction::Create => FileMemcard::create(&open_path, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})?,
};
Ok(Box::new(io) as Box<dyn MemcardStorage>)
});
result.map_err(|e| self.memcard_error("memcard_mount", error_name(e)))?;
self.media.path = Some(path);
self.media.access = Some(options.access);
self.media.error = None;
self.media.card_id = None;
if let Err(error) = self.wait_preparation("memcard_mount") {
if let HostError::Memcard(e) = &error {
self.media.error = Some(e.reason);
}
return Err(error);
}
self.media.card_id = self.firmware.os.memcard().installed_card_id();
Ok(self.get_memcard_state())
}
pub fn unmount_memcard(&mut self) -> Result<MemcardState, HostError> {
self.poll_memcard();
if self.firmware.os.lifecycle().resident_game_task().is_some() {
return Err(self.memcard_error("memcard_unmount", "invalid_state"));
}
self.firmware
.os
.memcard()
.uninstall_card()
.map_err(|e| self.memcard_error("memcard_unmount", error_name(e)))?;
self.media = MediaSelection { boot_phase: self.media.boot_phase, ..Default::default() };
Ok(self.get_memcard_state())
}
fn wait_preparation(&mut self, operation: &'static str) -> Result<(), HostError> {
let deadline = Instant::now() + Duration::from_secs(2);
loop {
self.poll_memcard();
match self.firmware.os.memcard().admission.state {
PreparationState::Ready => return Ok(()),
PreparationState::Failed(e) => {
let reason = if self.firmware.os.memcard().host_faulted() {
"restart_required"
} else {
error_name(e)
};
return Err(self.memcard_error(operation, reason));
}
_ => {}
}
if Instant::now() >= deadline {
return Err(self.memcard_error(operation, "restart_required"));
}
let lane = self.firmware.os.memcard().lane.clone();
lane.wait_for_progress(lane.progress_stamp(), Duration::from_millis(5));
}
}
pub fn prepare_teardown(
&mut self,
policy: TeardownPolicy,
operation: &'static str,
) -> Result<MemcardState, HostError> {
self.poll_memcard();
if matches!(policy.pending_writes, PendingWrites::Cancel) {
self.firmware.os.memcard().cancel_pending();
}
let deadline = Instant::now() + Duration::from_secs(2);
loop {
self.poll_memcard();
let state = self.get_memcard_state();
if !state.io.active && !state.io.deferred {
break;
}
if state.recovery.restart_required || Instant::now() >= deadline {
return Err(self.memcard_error(operation, "restart_required"));
}
let lane = self.firmware.os.memcard().lane.clone();
lane.wait_for_progress(lane.progress_stamp(), Duration::from_millis(5));
}
if self.get_memcard_state().dirty && !policy.discard_unsaved {
return Err(self.memcard_error(operation, "unsaved_changes"));
}
Ok(self.get_memcard_state())
}
pub fn reset_with_policy(&mut self, policy: TeardownPolicy) -> Result<MemcardState, HostError> {
self.prepare_teardown(policy, "reset")?;
self.reset_inner();
self.media.choice = None;
self.media.boot_phase = "idle";
self.poll_memcard();
Ok(self.get_memcard_state())
}
pub fn shutdown(&mut self, policy: TeardownPolicy) -> Result<MemcardState, HostError> {
let state = self.prepare_teardown(policy, "shutdown")?;
if self.firmware.os.stop_background_io().is_err() {
self.media.shutdown_failed = true;
return Err(self.memcard_error("shutdown", "restart_required"));
}
self.firmware.os.memcard().session.end_session();
self.firmware.os.memcard().poll(Instant::now());
self.firmware
.os
.memcard()
.uninstall_card()
.map_err(|e| self.memcard_error("shutdown", error_name(e)))?;
Ok(state)
}
pub fn reconcile_memcard(&mut self) -> Result<MemcardState, HostError> {
self.poll_memcard();
if !self.suspended_for_memcard() {
return Err(self.memcard_error("memcard_reconcile", "invalid_state"));
}
let path = self
.media
.path
.clone()
.ok_or_else(|| self.memcard_error("memcard_reconcile", "invalid_state"))?;
let read_only = self.media.access == Some(MediaAccess::ReadOnly);
self.firmware
.os
.memcard()
.reconcile_card_with(move || {
Ok(Box::new(FileMemcard::open(&path, read_only)?) as Box<dyn MemcardStorage>)
})
.map_err(|e| self.memcard_error("memcard_reconcile", error_name(e)))?;
self.wait_preparation("memcard_reconcile")?;
self.media.error = None;
if !self.firmware.resume_resident_game_from_home() {
return Err(self.memcard_error("memcard_reconcile", "invalid_state"));
}
Ok(self.get_memcard_state())
}
pub fn continue_memcard_in_memory(&mut self) -> Result<MemcardState, HostError> {
self.poll_memcard();
if !self.suspended_for_memcard() {
return Err(self.memcard_error("memcard_continue_in_memory", "invalid_state"));
}
self.firmware
.os
.detach_memcard()
.map_err(|e| self.memcard_error("memcard_continue_in_memory", error_name(e)))?;
if !self.firmware.resume_resident_game_from_home() {
return Err(self.memcard_error("memcard_continue_in_memory", "invalid_state"));
}
Ok(self.get_memcard_state())
}
fn suspended_for_memcard(&mut self) -> bool {
let Some(task) = self.firmware.os.lifecycle().resident_game_task() else { return false };
self.firmware.os.lifecycle().task_state(task)
== Some(prometeu_system::task::TaskState::Suspended)
&& (self.firmware.os.memcard().session.removal_pending()
|| self.firmware.os.memcard().session.diagnostics().reconciliation_required
|| self.firmware.os.memcard().session.host_faulted())
}
pub(super) fn host_action_required(&mut self) -> bool {
self.firmware.os.memcard().session.mode().is_some()
&& self.firmware.os.lifecycle().resident_game_task().is_some()
&& (self.firmware.os.memcard().session.removal_pending()
|| self.firmware.os.memcard().host_faulted()
|| !matches!(self.firmware.state, FirmwareState::GameRunning(_)))
}
}
#[cfg(test)]
#[path = "memcard_tests.rs"]
mod tests;
@@ -0,0 +1,487 @@
use super::*;
use crate::{AdvanceFrameOutcome, HostExecutionStatus};
use prometeu_test_support::memcard_fixture::{MemcardFixture, memcard_program};
use std::{fs, sync::mpsc};
/// Holds the first native write after admission; the controller decides its outcome.
struct BootstrapStore {
file: FileMemcard,
entered: mpsc::Sender<()>,
continue_io: mpsc::Receiver<Result<(), MemcardIoError>>,
held: bool,
}
impl MemcardStorage for BootstrapStore {
fn len(&self) -> Result<u64, MemcardIoError> {
self.file.len()
}
fn read_only(&self) -> bool {
false
}
fn read_at(&mut self, offset: u64, bytes: &mut [u8]) -> Result<(), MemcardIoError> {
self.file.read_at(offset, bytes)
}
fn write_at(&mut self, offset: u64, bytes: &[u8]) -> Result<(), MemcardIoError> {
if !self.held {
self.held = true;
let _ = self.entered.send(());
self.continue_io
.recv_timeout(Duration::from_secs(5))
.unwrap_or(Err(MemcardIoError::IoError))?;
}
self.file.write_at(offset, bytes)
}
fn sync(&mut self) -> Result<(), MemcardIoError> {
self.file.sync()
}
}
fn reopen_with_controlled_io(
kind: MemcardFixture,
) -> (Fixture, HeadlessHost, mpsc::Receiver<()>, mpsc::Sender<Result<(), MemcardIoError>>) {
use prometeu_system::memcard::{
image::{Game, Icon, crc32c},
transaction::{DurableResult, PublicationControl},
};
let f = Fixture::new(kind);
let file = FileMemcard::create(&f.image, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap();
let mut card = Card::mount(Box::new(file)).unwrap();
let icon = [0; 560];
card.register(
Game {
app_id: 42,
title: "Existing record".into(),
data_format_version: 1,
created_at: 0,
slots: vec![0],
icon: Icon { offset: 0, frames: 1, duration: 1, crc32c: crc32c(&icon) },
},
&icon,
&PublicationControl::default(),
)
.unwrap();
assert_eq!(
card.commit(0, &[0, 127, 128, 255], 0, &PublicationControl::default()).durable,
DurableResult::Success
);
drop(card);
let (entered_tx, entered) = mpsc::channel();
let (continue_io, release_rx) = mpsc::channel();
let mut host = HeadlessHost::new();
host.media.path = Some(f.image.clone());
host.media.access = Some(MediaAccess::ReadWrite);
host.install_memcard(Box::new(BootstrapStore {
file: FileMemcard::open(&f.image, false).unwrap(),
entered: entered_tx,
continue_io: release_rx,
held: false,
}))
.unwrap();
host.boot_with_memcard_choice(f.cart.to_string_lossy(), Choice::Persistent).unwrap();
assert_eq!(host.get_state().tick_index, 0);
(f, host, entered, continue_io)
}
#[test]
fn first_reopen_frame_waits_for_controlled_presentation_without_replaying() {
let (_f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let (finished_tx, finished) = mpsc::channel();
let controller = std::thread::spawn(move || {
entered.recv_timeout(Duration::from_secs(3)).unwrap();
// Observe the owner while publication is provably held. This is a
// channel deadline, not a sleep used to infer that IO has started.
let premature = finished.recv_timeout(Duration::from_millis(300)).is_ok();
let _ = continue_io.send(Ok(()));
premature
});
let result = host.advance_frame();
let _ = finished_tx.send(());
let premature = controller.join().unwrap();
assert!(!premature, "advance returned while native publication was held: {result:?}");
assert!(matches!(
result,
Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. })
));
let state = host.get_state();
assert_eq!(state.frame_index, 1);
assert_eq!(state.tick_index, 2);
assert_eq!(state.status, HostExecutionStatus::Paused);
assert_eq!(state.stack_top.last(), Some(&prometeu_bytecode::Value::Int64(201)));
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
assert!(!host.get_memcard_state().io.active);
assert_eq!(host.capture_frame().unwrap().logical_frame_index, 1);
host.shutdown(TeardownPolicy::default()).unwrap();
}
#[test]
fn blocked_bootstrap_reaches_native_deadline_and_keeps_worker_lock() {
let (f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let started = Instant::now();
let result = host.advance_frame();
entered.recv_timeout(Duration::from_secs(1)).unwrap();
let state = host.get_memcard_state();
let busy = matches!(FileMemcard::open(&f.image, false), Err(MemcardIoError::Busy));
// Always let the worker return before asserting, including on the old host.
continue_io.send(Ok(())).unwrap();
settle(&mut host);
assert_eq!(result.unwrap(), AdvanceFrameOutcome::ActionRequired);
assert!(started.elapsed() < Duration::from_secs(3));
assert!(state.recovery.restart_required);
assert!(state.io.active && busy);
assert_eq!(host.get_state().frame_index, 0);
assert_eq!(host.get_state().tick_index, 1);
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
}
#[test]
fn ordinary_gameplay_commit_does_not_wait_for_native_io() {
let (_f, mut host, entered, continue_io) = reopen_with_controlled_io(MemcardFixture::Read);
host.advance_frame().unwrap();
let service = host.firmware.os.memcard();
let context = service.session.context();
service.session.write(context, 0, 0, &[0, 127, 128, 255]).unwrap();
service.session.commit(context, 0, 0, Instant::now(), &service.lane).unwrap();
entered.recv_timeout(Duration::from_secs(2)).unwrap();
let result = host.advance_frame();
let pending = host.get_memcard_state();
continue_io.send(Ok(())).unwrap();
settle(&mut host);
assert!(matches!(
result,
Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 2, .. })
));
assert!(pending.io.active);
assert_eq!(pending.request.unwrap().operation, "commit");
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
host.shutdown(TeardownPolicy::default()).unwrap();
}
#[test]
fn bootstrap_wait_deadline_is_shared_across_wakes_and_reentry() {
use super::super::{BOOTSTRAP_IO_WAIT_QUANTUM, BootstrapIoWait};
let start = Instant::now();
let mut wait = BootstrapIoWait::default();
assert_eq!(wait.next_wait(start), Some(BOOTSTRAP_IO_WAIT_QUANTUM));
assert_eq!(
wait.next_wait(start + Duration::from_millis(1000)),
Some(BOOTSTRAP_IO_WAIT_QUANTUM)
);
assert_eq!(wait.next_wait(start + Duration::from_millis(1999)), Some(Duration::from_millis(1)));
assert_eq!(wait.next_wait(start + Duration::from_secs(2)), None);
assert_eq!(wait.next_wait(start + Duration::from_secs(3)), None);
}
#[test]
fn bootstrap_outer_timeout_preserves_native_snapshot_and_machine_state() {
use super::super::BootstrapIoWait;
let (_f, mut host, _entered, _release) = reopen_with_controlled_io(MemcardFixture::Read);
let before = host.get_state();
host.firmware.os.vm().set_paused(false);
host.firmware.os.vm().request_debug_step();
let mut wait = BootstrapIoWait { deadline: Some(Instant::now()) };
let error = host.wait_for_bootstrap_io(&mut wait, 0).unwrap_err();
let snapshot = host.get_memcard_state();
let HostError::Memcard(error) = error else { panic!("expected a native memcard error") };
assert_eq!(error.operation, "advance");
assert_eq!(error.reason, "restart_required");
assert_eq!(error.state, snapshot);
let after = host.get_state();
assert_eq!((after.pc, after.frame_index, after.tick_index), (before.pc, 0, 0));
assert_eq!(after.stack_top.to_vec(), before.stack_top.to_vec());
assert_eq!(after.status, HostExecutionStatus::Paused);
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
host.shutdown(TeardownPolicy::default()).unwrap();
}
#[test]
fn failed_bootstrap_io_returns_native_media_action_without_guest_fault() {
let (_f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let controller = std::thread::spawn(move || {
entered.recv_timeout(Duration::from_secs(2)).unwrap();
continue_io.send(Err(MemcardIoError::Unavailable)).unwrap();
});
let result = host.advance_frame();
controller.join().unwrap();
assert_eq!(result.unwrap(), AdvanceFrameOutcome::ActionRequired);
let state = host.get_memcard_state();
assert!(state.recovery.removal_pending);
assert!(!state.io.active);
assert_eq!(host.get_state().frame_index, 0);
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
assert!(!host.firmware.os.vm().debug_step_requested());
assert!(host.get_fault().is_none());
}
#[test]
fn queued_bootstrap_publication_can_progress_without_moving_guest_during_poll() {
use prometeu_system::AsyncWorkJobOutcome;
let (_f, mut host, entered, continue_io) =
reopen_with_controlled_io(MemcardFixture::ReadWithPresentation);
let (busy_tx, busy) = mpsc::channel();
let (unblock, unblock_rx) = mpsc::channel();
host.firmware
.os
.memcard()
.lane
.submit_memcard_commit_write(move |_| {
busy_tx.send(()).unwrap();
let _ = unblock_rx.recv_timeout(Duration::from_secs(3));
AsyncWorkJobOutcome::Completed
})
.unwrap();
busy.recv_timeout(Duration::from_secs(2)).unwrap();
for _ in 0..10 {
host.firmware.os.vm().set_paused(false);
host.firmware.os.vm().request_debug_step();
host.tick_once();
if host.bootstrap_io_pending() {
break;
}
}
let pending = host.bootstrap_io_pending();
let queued = host.get_memcard_state();
let before = host.get_state();
host.poll_memcard();
let after = host.get_state();
let (finished_tx, finished) = mpsc::channel();
let controller = std::thread::spawn(move || {
let premature = finished.recv_timeout(Duration::from_millis(300)).is_ok();
let _ = unblock.send(());
entered.recv_timeout(Duration::from_secs(2)).unwrap();
let _ = continue_io.send(Ok(()));
premature
});
let result = host.advance_frame();
let _ = finished_tx.send(());
let premature = controller.join().unwrap();
assert!(pending);
assert!(!premature, "advance returned while its publication was queued: {result:?}");
assert_eq!(queued.io.phase, "queued");
assert_eq!(
(before.pc, before.frame_index, before.tick_index),
(after.pc, after.frame_index, after.tick_index)
);
assert_eq!(before.stack_top.to_vec(), after.stack_top.to_vec());
assert!(matches!(
result,
Ok(AdvanceFrameOutcome::FrameCompleted { logical_frame_index: 1, .. })
));
host.shutdown(TeardownPolicy::default()).unwrap();
}
struct Fixture {
root: PathBuf,
image: PathBuf,
cart: PathBuf,
}
impl Fixture {
fn new(kind: MemcardFixture) -> Self {
static COUNTER: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
let root = std::env::temp_dir().join(format!(
"native-memcard-{}-{}-{}",
std::process::id(),
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos(),
COUNTER.fetch_add(1, std::sync::atomic::Ordering::Relaxed)
));
let cart = root.join("cart");
fs::create_dir_all(&cart).unwrap();
fs::write(cart.join("program.pbx"), memcard_program(kind)).unwrap();
fs::write(cart.join("manifest.json"),r#"{"magic":"PMTU","cartridge_version":1,"app_id":42,"title":"Native memcard","app_version":"1","app_mode":"Game","capabilities":["memcard"],"memcard_slots":1}"#).unwrap();
let image = root.join("save.pmc");
Self { root, image, cart }
}
fn mount(&self, host: &mut HeadlessHost) {
host.mount_memcard(MemcardMount {
path: self.image.to_string_lossy().into_owned(),
action: MediaAction::Create,
access: MediaAccess::ReadWrite,
})
.unwrap();
host.boot_with_memcard_choice(self.cart.to_string_lossy(), Choice::Persistent).unwrap();
}
}
impl Drop for Fixture {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.root);
}
}
fn settle(host: &mut HeadlessHost) {
let deadline = Instant::now() + Duration::from_secs(3);
loop {
host.poll_memcard();
if !host.get_memcard_state().io.active {
break;
}
assert!(Instant::now() < deadline, "IO did not cease");
let lane = host.firmware.os.memcard().lane.clone();
lane.wait_for_progress(lane.progress_stamp(), Duration::from_millis(5));
}
}
fn pause_for_media(host: &mut HeadlessHost) {
let task = host.firmware.os.lifecycle().resident_game_task().unwrap();
host.firmware.os.lifecycle().suspend_task(task).unwrap();
assert_eq!(
host.firmware.os.lifecycle().task_state(task),
Some(prometeu_system::task::TaskState::Suspended)
);
}
#[test]
fn same_media_recovery_rejects_replacement_and_preserves_ram_continuation() {
let f = Fixture::new(MemcardFixture::Dirty);
let mut host = HeadlessHost::new();
f.mount(&mut host);
assert!(matches!(host.advance_frame().unwrap(), AdvanceFrameOutcome::FrameCompleted { .. }));
settle(&mut host);
let context = host.firmware.os.memcard().session.context();
host.firmware.os.memcard().session.notify_removal();
pause_for_media(&mut host);
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
assert_eq!(host.advance_frame().unwrap(), AdvanceFrameOutcome::ActionRequired);
let old = f.root.join("old.pmc");
fs::rename(&f.image, &old).unwrap();
let replacement = FileMemcard::create(&f.image, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap();
drop(replacement);
let error = host.reconcile_memcard().unwrap_err();
assert!(matches!(error,HostError::Memcard(e) if e.reason=="identity_mismatch"));
let mut bytes = [0; 4];
host.firmware.os.memcard().session.read(context, 0, 0, &mut bytes).unwrap();
assert_eq!(bytes, [0, 127, 128, 255]);
fs::rename(&f.image, f.root.join("other.pmc")).unwrap();
fs::rename(&old, &f.image).unwrap();
let restored = host.reconcile_memcard().unwrap();
assert!(restored.dirty);
assert!(!restored.recovery.reconciliation_required);
assert_eq!(host.firmware.os.memcard().session.context(), context);
assert!(matches!(host.advance_frame().unwrap(), AdvanceFrameOutcome::FrameCompleted { .. }));
assert_eq!(host.get_state().stack_top.last(), Some(&prometeu_bytecode::Value::Int64(301)));
host.shutdown(TeardownPolicy { discard_unsaved: true, ..Default::default() }).unwrap();
}
#[test]
fn explicit_continue_in_ram_preserves_dirty_snapshot_and_uses_no_new_boot() {
let f = Fixture::new(MemcardFixture::Dirty);
let mut host = HeadlessHost::new();
f.mount(&mut host);
host.advance_frame().unwrap();
settle(&mut host);
let context = host.firmware.os.memcard().session.context();
host.firmware.os.memcard().session.notify_removal();
pause_for_media(&mut host);
let ram = host.continue_memcard_in_memory().unwrap();
assert_eq!(ram.session.mode, Some("memory_only"));
assert!(ram.dirty);
assert_eq!(host.firmware.os.memcard().session.context(), context);
host.advance_frame().unwrap();
host.shutdown(TeardownPolicy { discard_unsaved: true, ..Default::default() }).unwrap();
}
struct GateStore {
file: FileMemcard,
inside_publication: bool,
payload_seen: bool,
fired: bool,
entered: mpsc::Sender<()>,
continue_io: mpsc::Receiver<()>,
}
impl MemcardStorage for GateStore {
fn len(&self) -> Result<u64, MemcardIoError> {
self.file.len()
}
fn read_only(&self) -> bool {
false
}
fn read_at(&mut self, o: u64, b: &mut [u8]) -> Result<(), MemcardIoError> {
self.file.read_at(o, b)
}
fn sync(&mut self) -> Result<(), MemcardIoError> {
self.file.sync()
}
fn write_at(&mut self, o: u64, b: &[u8]) -> Result<(), MemcardIoError> {
let payload = o >= prometeu_system::memcard::image::DATA_OFFSET;
self.payload_seen |= payload;
let publication = self.payload_seen && (o == 8192 || o == 12288);
if !self.fired && if self.inside_publication { publication } else { payload } {
self.fired = true;
if self.inside_publication {
self.file.write_at(o, b)?;
}
self.entered.send(()).unwrap();
self.continue_io.recv_timeout(Duration::from_secs(10)).unwrap();
return Err(MemcardIoError::IoError);
}
self.file.write_at(o, b)
}
}
#[test]
fn unceased_io_retains_lock_and_terminal_result_survives_late_return_and_reconcile() {
for inside_publication in [false, true] {
let f = Fixture::new(MemcardFixture::Write);
let file = FileMemcard::create(&f.image, IMAGE_BYTES, |io, id| {
Card::format(io, id).map_err(|_| MemcardIoError::IoError)
})
.unwrap();
let (entered_tx, entered) = mpsc::channel();
let (continue_io, release_rx) = mpsc::channel();
let mut host = HeadlessHost::new();
host.media.path = Some(f.image.clone());
host.media.access = Some(MediaAccess::ReadWrite);
host.install_memcard(Box::new(GateStore {
file,
inside_publication,
payload_seen: false,
fired: false,
entered: entered_tx,
continue_io: release_rx,
}))
.unwrap();
host.boot_with_memcard_choice(f.cart.to_string_lossy(), Choice::Persistent).unwrap();
host.advance_frame().unwrap();
entered.recv_timeout(Duration::from_secs(3)).unwrap();
host.firmware.os.memcard().poll(Instant::now() + Duration::from_secs(2));
let before = host.get_memcard_state();
assert!(before.io.active);
assert!(before.recovery.restart_required);
assert_eq!(
before.request.as_ref().unwrap().state,
if inside_publication { "indeterminate" } else { "failure" }
);
assert!(
matches!(host.shutdown(TeardownPolicy{discard_unsaved:true,..Default::default()}),Err(HostError::Memcard(e)) if e.reason=="restart_required")
);
assert!(matches!(FileMemcard::open(&f.image, false), Err(MemcardIoError::Busy)));
continue_io.send(()).unwrap();
settle(&mut host);
let returned = host.get_memcard_state().request;
let original = before.request.as_ref().unwrap();
let late = returned.as_ref().unwrap();
assert_eq!(
(&late.id, late.state, late.reason),
(&original.id, original.state, original.reason),
"late completion cannot rewrite the original result"
);
assert_eq!(late.storage_error, Some("io_error"));
pause_for_media(&mut host);
let restored = host.reconcile_memcard().unwrap();
assert_eq!(
restored.request, returned,
"recovery must not consume or rewrite the guest result"
);
assert!(!restored.recovery.restart_required);
host.shutdown(TeardownPolicy { discard_unsaved: true, ..Default::default() }).unwrap();
}
}
@@ -61,7 +61,7 @@ fn thousand_reset_reload_cycles_release_session_owners_and_preserve_controls() {
)); ));
assert_eq!(&*host.get_state().stack_top, &[Value::Int32(73)]); assert_eq!(&*host.get_state().stack_top, &[Value::Int32(73)]);
assert!(host.get_fault().is_none()); assert!(host.get_fault().is_none());
host.reset(); host.reset().expect("reset");
assert_eq!(host.firmware.os.sessions().vm_session_count(), 0); assert_eq!(host.firmware.os.sessions().vm_session_count(), 0);
assert_eq!( assert_eq!(
observer.diagnostic_snapshot().used, observer.diagnostic_snapshot().used,
@@ -37,7 +37,7 @@ fn controlled_civil_time_is_independent_of_frames_pause_and_reset() {
host.controlled_wall_clock().unwrap().set(10); host.controlled_wall_clock().unwrap().set(10);
host.advance_frame().expect("frame after clock adjustment"); host.advance_frame().expect("frame after clock adjustment");
assert_eq!(host.wall_clock().utc_unix_seconds(), 10); assert_eq!(host.wall_clock().utc_unix_seconds(), 10);
host.reset(); host.reset().expect("reset");
assert_eq!(host.wall_clock().utc_unix_seconds(), 10); assert_eq!(host.wall_clock().utc_unix_seconds(), 10);
host.boot(&cartridge).expect("reboot"); host.boot(&cartridge).expect("reboot");
assert_eq!(host.wall_clock().utc_unix_seconds(), 10); assert_eq!(host.wall_clock().utc_unix_seconds(), 10);
@@ -57,7 +57,7 @@ fn injected_civil_clock_remains_the_runtime_source_across_lifecycle() {
assert_eq!(host.wall_clock().utc_unix_seconds(), u64::MAX); assert_eq!(host.wall_clock().utc_unix_seconds(), u64::MAX);
clock.set(42); clock.set(42);
assert_eq!(host.wall_clock().utc_unix_seconds(), 42); assert_eq!(host.wall_clock().utc_unix_seconds(), 42);
host.reset(); host.reset().expect("reset");
clock.advance(3); clock.advance(3);
assert_eq!(host.wall_clock().utc_unix_seconds(), 45); assert_eq!(host.wall_clock().utc_unix_seconds(), 45);
} }
@@ -171,7 +171,7 @@ fn one_frame_returns_and_captures_the_exact_published_frame() {
assert_eq!(captured.frame.ownership.app_mode, AppMode::Game); assert_eq!(captured.frame.ownership.app_mode, AppMode::Game);
assert_eq!(captured.frame.ownership.app_id, 41); assert_eq!(captured.frame.ownership.app_id, 41);
assert_eq!(captured.frame.stride_pixels, captured.frame.width); assert_eq!(captured.frame.stride_pixels, captured.frame.width);
assert_eq!(captured.frame.pixels.len(), 480 * 270); assert_eq!(captured.frame.pixels.len(), 640 * 360);
assert_eq!(host.capture_frame().expect("repeat capture"), captured); assert_eq!(host.capture_frame().expect("repeat capture"), captured);
let mut mutated_clone = captured.clone(); let mut mutated_clone = captured.clone();
@@ -290,7 +290,7 @@ fn two_runs_match_oracle() {
fn reset_matches_fresh_host() { fn reset_matches_fresh_host() {
let mut host = boot_color(); let mut host = boot_color();
let _ = run_on(&mut host); let _ = run_on(&mut host);
host.reset(); host.reset().expect("reset");
assert_eq!(host.get_state().status, HostExecutionStatus::Terminated); assert_eq!(host.get_state().status, HostExecutionStatus::Terminated);
assert_eq!(host.capture_frame(), Err(HostError::NoFrameAvailable)); assert_eq!(host.capture_frame(), Err(HostError::NoFrameAvailable));
host.boot(color_cartridge()).expect("reboot"); host.boot(color_cartridge()).expect("reboot");
@@ -357,7 +357,7 @@ fn batch_stops_early_on_fault_and_reports_partial_progress() {
#[test] #[test]
fn advance_after_reset_reports_termination_without_ticking() { fn advance_after_reset_reports_termination_without_ticking() {
let mut host = boot_color(); let mut host = boot_color();
host.reset(); host.reset().expect("reset");
let before = host.get_state().tick_index; let before = host.get_state().tick_index;
assert_eq!(host.advance_frame().expect("termination outcome"), AdvanceFrameOutcome::Terminated); assert_eq!(host.advance_frame().expect("termination outcome"), AdvanceFrameOutcome::Terminated);
@@ -477,8 +477,8 @@ fn assert_completed(outcome: prometeu_host_headless::AdvanceFramesOutcome, expec
} }
fn assert_color(captured: &CapturedFrame, color: u32) { fn assert_color(captured: &CapturedFrame, color: u32) {
assert_eq!(captured.frame.width, 480); assert_eq!(captured.frame.width, 640);
assert_eq!(captured.frame.height, 270); assert_eq!(captured.frame.height, 360);
assert!(captured.frame.pixels.iter().all(|pixel| *pixel == color)); assert!(captured.frame.pixels.iter().all(|pixel| *pixel == color));
} }
@@ -68,6 +68,7 @@ fn regenerated_cartridges_run_six_complete_frames_on_production_host() {
struct Effects { struct Effects {
scene_binds: usize, scene_binds: usize,
frame_commands: usize, frame_commands: usize,
music_plays: usize,
} }
impl NativeInterface for Effects { impl NativeInterface for Effects {
fn syscall( fn syscall(
@@ -81,6 +82,9 @@ fn regenerated_cartridges_run_six_complete_frames_on_production_host() {
if syscall == Syscall::ComposerBindScene { if syscall == Syscall::ComposerBindScene {
self.scene_binds += 1; self.scene_binds += 1;
} }
if syscall == Syscall::MusicPlay {
self.music_plays += 1;
}
if matches!(syscall, Syscall::GfxClear | Syscall::ComposerSetCamera) { if matches!(syscall, Syscall::GfxClear | Syscall::ComposerSetCamera) {
self.frame_commands += 1; self.frame_commands += 1;
} }
@@ -125,7 +129,7 @@ fn regenerated_cartridges_run_six_complete_frames_on_production_host() {
) )
.unwrap(); .unwrap();
let mut vm = prometeu_vm::VirtualMachine::from_image(image, Default::default()); let mut vm = prometeu_vm::VirtualMachine::from_image(image, Default::default());
let mut effects = Effects { scene_binds: 0, frame_commands: 0 }; let mut effects = Effects { scene_binds: 0, frame_commands: 0, music_plays: 0 };
for _ in 0..6 { for _ in 0..6 {
vm.prepare_boot_call().unwrap(); vm.prepare_boot_call().unwrap();
assert_eq!( assert_eq!(
@@ -135,6 +139,7 @@ fn regenerated_cartridges_run_six_complete_frames_on_production_host() {
} }
assert_eq!(effects.frame_commands, 6); assert_eq!(effects.frame_commands, 6);
assert_eq!(effects.scene_binds, usize::from(name == "stress-console")); assert_eq!(effects.scene_binds, usize::from(name == "stress-console"));
assert_eq!(effects.music_plays, usize::from(name == "stress-console"));
} }
} }
+1
View File
@@ -10,3 +10,4 @@ prometeu-hal = { path = "../../console/prometeu-hal" }
[dev-dependencies] [dev-dependencies]
serde_json = "1" serde_json = "1"
prometeu-host-headless = { path = "../../host/prometeu-host-headless" }
+10 -3
View File
@@ -21,6 +21,11 @@ pub fn generate() -> Result<()> {
fs::create_dir_all(&out_dir)?; fs::create_dir_all(&out_dir)?;
fs::write(out_dir.join("program.pbx"), build_program())?; fs::write(out_dir.join("program.pbx"), build_program())?;
fs::write(out_dir.join("manifest.json"), manifest_json())?; fs::write(out_dir.join("manifest.json"), manifest_json())?;
match fs::remove_file(out_dir.join("assets.pa")) {
Ok(()) => {}
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {}
Err(error) => return Err(error.into()),
}
Ok(()) Ok(())
} }
@@ -50,15 +55,17 @@ pub fn build_program() -> Vec<u8> {
let draw = rom.len() as u32; let draw = rom.len() as u32;
rom.extend(asm(&format!( rom.extend(asm(&format!(
"PUSH_I32 180\n\ "PUSH_I32 {x}\n\
PUSH_I32 75\n\ PUSH_I32 {y}\n\
PUSH_I32 120\n\ PUSH_I32 120\n\
PUSH_I32 120\n\ PUSH_I32 120\n\
PUSH_I64 {}\n\ PUSH_I64 {}\n\
GET_LOCAL 0\n\ GET_LOCAL 0\n\
HOSTCALL 1\n\ HOSTCALL 1\n\
RET", RET",
Color::WHITE.raw() Color::WHITE.raw(),
x = (prometeu_hal::graphics_contract::WIDTH - 120) / 2,
y = (prometeu_hal::graphics_contract::HEIGHT - 120) / 2
))); )));
patch_jump(&mut rom, jump_to_green_case_offset, green_case); patch_jump(&mut rom, jump_to_green_case_offset, green_case);
@@ -0,0 +1,35 @@
use prometeu_host_headless::{AdvanceFrameOutcome, HeadlessHost};
use std::path::PathBuf;
#[test]
fn dummy_boy_is_visual_only_and_silent() {
let root = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../../test-cartridges/dummy-boy");
assert!(!root.join("assets.pa").exists());
assert_eq!(std::fs::read(root.join("program.pbx")).unwrap(), pbxgen_dummy_boy::build_program());
assert_eq!(
std::fs::read(root.join("manifest.json")).unwrap(),
pbxgen_dummy_boy::manifest_json()
);
let manifest: serde_json::Value =
serde_json::from_slice(&pbxgen_dummy_boy::manifest_json()).unwrap();
assert_eq!(manifest["capabilities"], serde_json::json!(["gfx2d"]));
let mut host = HeadlessHost::new();
host.boot(root.to_string_lossy()).unwrap();
let expected = [10098790910174709541_u64, 9216878996269485861, 8328467396362782501];
for index in 0..6 {
assert!(matches!(
host.advance_frame().unwrap(),
AdvanceFrameOutcome::FrameCompleted { .. }
));
let frame = host.capture_frame().unwrap();
let hash = frame.frame.pixels.iter().fold(0xcbf29ce484222325_u64, |hash, byte| {
(hash ^ u64::from(*byte)).wrapping_mul(0x100000001b3)
});
assert_eq!(hash, expected[index % 3]);
host.resume().unwrap();
let mut pcm = [1.0; 1600];
host.render_audio(&mut pcm);
assert_eq!(pcm, [0.0; 1600]);
}
assert_eq!(host.audio_diagnostics().maximum_voices, 0);
}
+6
View File
@@ -6,5 +6,11 @@ edition = "2021"
[dependencies] [dependencies]
prometeu-bytecode = { path = "../../console/prometeu-bytecode" } prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
prometeu-hal = { path = "../../console/prometeu-hal" } prometeu-hal = { path = "../../console/prometeu-hal" }
prometeu-vm = { path = "../../console/prometeu-vm" }
anyhow = "1" anyhow = "1"
serde_json = "1" serde_json = "1"
[dev-dependencies]
prometeu-drivers = { path = "../../console/prometeu-drivers" }
prometeu-host-headless = { path = "../../host/prometeu-host-headless" }
prometeu-vm = { path = "../../console/prometeu-vm", features = ["resource-diagnostics"] }
@@ -0,0 +1,81 @@
# Stress Console local measurement
Executed on 2026-11-20: Apple M2 Pro, macOS/Darwin 27.2.0, aarch64,
`rustc 1.98.1 (48a229cea 2026-09-01)`, Cargo release profile, VM
`resource-diagnostics` enabled. The host was not isolated and its power/thermal
state was not controlled. These are elapsed-time observations from one run.
Reproduce from the runtime root:
```sh
cargo run -p pbxgen-stress --release --example demo_measure -- 120 /tmp/stress-measure
```
Seed: `1347571533`. Particle position-travel multiplier: `1.5`. Each preset loads
independently, executes its first frame,
then measures 120 steady logical frames. All measured frames compose the native
640x360 image and process 800 stereo audio frames (48 kHz). Initialization is
excluded from steady distributions. Percentiles are nearest-rank over the 120
samples; they do not estimate a guaranteed upper bound.
| Preset | VM only mean ms | Headless mean ms | p95 ms | Max ms | Mean virtual cycles | Host ticks/logical frame |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| light | 1.982 | 2.683 | 2.853 | 2.996 | 84701.2 | 1 |
| normal | 4.154 | 4.907 | 5.056 | 5.184 | 178972.8 | 1 |
| heavy | 19.183 | 19.685 | 20.553 | 21.700 | 774621.4 | 4 |
VM-only uses the same PBX on the real VM and SpriteController; other native
calls are counted. Headless uses actual firmware, assets, composition and audio.
Virtual cycles are machine accounting, not CPU cycles or milliseconds. The
heavy preset spans four 250,000-cycle host slices per logical frame; light and
normal use one. `advance_frame` completes all required slices, so these timings
are not physical presentation cadence or a promise of 60 FPS in another host.
| Preset | Host boot ms | First frame ms | GuestBytes used | Live handles/objects | AuxiliaryBytes used | TemporaryBytes peak | Sprites accepted |
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| light | 1.730 | 3.037 | 22640 | 66 | 8680 | 3840 | 192 |
| normal | 3.421 | 5.213 | 44656 | 130 | 16360 | 7680 | 256 |
| heavy | 3.278 | 20.683 | 132720 | 386 | 31720 | 15360 | 512 |
Each preset recorded zero sprite overflows and zero guest composer errors.
Music play was submitted once. The two-second observation reached eight active
voices; the separate 52.4-second audio regression reached ten, with no clipped
samples. Processing 800 audio frames averaged 0.123–0.128 ms in this run.
The guest retains exactly N Particle structs plus one array and one RNG object.
Rebirth reuses those objects. Quota accounting excludes process RSS, framebuffers,
resident banks, renderer caches and allocator overhead. The musical bank has
60,358 PCM bytes and canonical decoded size 112,224 bytes; those are independent
of the workload preset. Boot/first-frame times include their respective host
work and are not isolated codec-decoding measurements.
The current default is heavy: 384 particles, four real simulation passes and
128 tunnel markers. It deliberately selects the largest existing numerical
workload. Normal (128 particles/two passes) and light remain explicit options
for comparison. The current run includes the 1.5 position-travel multiplier and
the larger heavy population. Relative to the previous 256-particle heavy workload, sprite
admission rises from 384 to 512, mean virtual cycles from about 531,444 to
774,621 and host slices from three to four. Its observed mean headless cost
increased from 13.649 to 19.685 ms. These observations do not provide a handheld
frame-rate guarantee.
The example saves report.json, generated cartridges and PPM captures. Diagnostic
state hashes after the initial frame plus 120 measured frames were:
| Preset | Particle-state hash | Native frame hash |
| --- | --- | --- |
| light | `b53cd663d1741a24` | `87f646410e9c3ade` |
| normal | `16b062d046d8efc9` | `c33ceb1e514ff1a8` |
| heavy | `f934f3e61ae1be77` | `6c3302f4a16903bc` |
The tests additionally pin six-frame numeric and visual baselines and execute
them in debug and release. A separate probe checks actual guest displacement
against the updated velocity, establishing the 1.5 multiplier independently of
the replay hashes. The native desktop integration test exercises actual
cartridge music through AudioCallback without a physical output device.
No physical callback deadlines, underruns, GPU presentation, VSync, battery
consumption, thermal throttling or affordable handheld hardware were measured.
The headless harness drives audio explicitly; it cannot observe a device underrun.
Use dedicated subsystem tests for numeric edge cases, GC churn, storage/input,
crossfade, SFX and full 32-voice load.
@@ -0,0 +1,101 @@
//! Reproducible fixture measurement; times include diagnostics and do not qualify a handheld.
#[path = "../tests/support/mod.rs"]
mod support;
use pbxgen_stress::{Preset, DEFAULT_SEED};
use prometeu_host_headless::{AdvanceFrameOutcome, HeadlessHost};
use std::{
io::Write,
path::{Path, PathBuf},
time::Instant,
};
fn distribution(mut ms: Vec<f64>) -> serde_json::Value {
ms.sort_by(f64::total_cmp);
let n = ms.len();
serde_json::json!({"count":n,"mean_ms":ms.iter().sum::<f64>()/n as f64,"p50_ms":ms[(n*50).div_ceil(100)-1],"p95_ms":ms[(n*95).div_ceil(100)-1],"max_ms":ms[n-1]})
}
fn ppm(path: &Path, pixels: &[u32]) {
let mut f = std::io::BufWriter::new(std::fs::File::create(path).unwrap());
write!(f, "P6\n640 360\n255\n").unwrap();
for &p in pixels {
let (r, g, b, _) = prometeu_hal::color::Color::unpack_to_native(p);
f.write_all(&[r, g, b]).unwrap();
}
}
fn main() {
let frames: usize = std::env::args().nth(1).unwrap_or("120".into()).parse().expect("frames");
assert!((1..=10000).contains(&frames));
let output =
PathBuf::from(std::env::args().nth(2).unwrap_or("/tmp/prometeu-demo-measure".into()));
std::fs::create_dir_all(&output).unwrap();
let mut reports = vec![];
for preset in [Preset::Light, Preset::Normal, Preset::Heavy] {
let started = Instant::now();
let mut vm = support::vm(preset, DEFAULT_SEED);
let vm_load_ms = started.elapsed().as_secs_f64() * 1000.0;
let mut native = support::Workload::default();
let started = Instant::now();
let init_cycles = support::frame(&mut vm, &mut native);
let init_vm_ms = started.elapsed().as_secs_f64() * 1000.0;
let mut vm_times = Vec::new();
let mut cycles = 0;
for _ in 0..frames {
let started = Instant::now();
cycles += support::frame(&mut vm, &mut native);
vm_times.push(started.elapsed().as_secs_f64() * 1000.0);
}
let resources = vm.resource_snapshot();
let state_hash = support::hash(&support::particle_bits(&vm));
let cart = output.join(format!("{}-cartridge", preset.name()));
pbxgen_stress::generate_with(preset, DEFAULT_SEED, Some(cart.clone())).unwrap();
let mut host = HeadlessHost::new();
let started = Instant::now();
host.boot(cart.to_string_lossy()).unwrap();
let boot_ms = started.elapsed().as_secs_f64() * 1000.0;
let started = Instant::now();
assert!(matches!(
host.advance_frame().unwrap(),
AdvanceFrameOutcome::FrameCompleted { .. }
));
let host_first_frame_ms = started.elapsed().as_secs_f64() * 1000.0;
host.resume().unwrap();
let mut pcm = [0.0; 1600];
host.render_audio(&mut pcm);
let mut host_times = vec![];
let mut audio_times = vec![];
let mut previous_tick = host.get_state().tick_index;
let mut slices = vec![];
for _ in 0..frames {
let started = Instant::now();
assert!(matches!(
host.advance_frame().unwrap(),
AdvanceFrameOutcome::FrameCompleted { .. }
));
host.resume().unwrap();
let audio_started = Instant::now();
host.render_audio(&mut pcm);
audio_times.push(audio_started.elapsed().as_secs_f64() * 1000.0);
host_times.push(started.elapsed().as_secs_f64() * 1000.0);
let tick = host.get_state().tick_index;
slices.push(tick - previous_tick);
previous_tick = tick;
}
let capture = host.capture_frame().unwrap();
let file = output.join(format!("{}.ppm", preset.name()));
ppm(&file, &capture.frame.pixels);
let audio = host.audio_diagnostics();
reports.push(serde_json::json!({"preset":preset.name(),"particles":preset.particles(),"substeps":preset.substeps(),"steady_frames":frames,"seed":DEFAULT_SEED,
"vm_load_ms":vm_load_ms,"vm_first_frame_ms":init_vm_ms,"host_boot_ms":boot_ms,"host_first_frame_ms":host_first_frame_ms,
"vm_only_with_bounded_native":distribution(vm_times),"headless_graphics_and_800_audio_frames":distribution(host_times),"audio_800_frames_only":distribution(audio_times),
"mean_host_ticks_per_logical_frame":slices.iter().sum::<u64>() as f64 / frames as f64,"max_host_ticks_per_logical_frame":slices.iter().max(),
"first_virtual_cycles":init_cycles,"mean_steady_virtual_cycles":cycles as f64/frames as f64,
"sprites_submitted_per_frame":preset.particles()+128,"sprites_accepted_last_frame":native.sprites.sprite_count(),"sprite_overflow":native.sprites.dropped_sprites(),"guest_composer_errors":native.errors,
"live_guest_objects":resources.live_objects,"vm_budget_used":resources.budget.used,"vm_budget_peaks":resources.budget.peaks,"vm_budget_limits":resources.budget.limits,
"state_hash":format!("{state_hash:016x}"),"music_play_commands":native.plays,"observed_maximum_voices":audio.maximum_voices,"audio_frames":audio.frames,
"capture":file,"frame_hash":format!("{:016x}",support::hash(&capture.frame.pixels.iter().map(|&p|u64::from(p)).collect::<Vec<_>>()))}));
}
let report = serde_json::json!({"profile":if cfg!(debug_assertions){"debug"}else{"release"},"arch":std::env::consts::ARCH,"os":std::env::consts::OS,"resource_diagnostics":true,"particle_travel_scale":pbxgen_stress::PARTICLE_TRAVEL_SCALE,
"notes":["Native-only timing uses real VM and SpriteController, with other host calls counted.","Headless timing includes real software composition and 800 stereo audio frames per logical frame.","No physical callback, VSync, GPU presentation, power or handheld measurement.","VM quota arrays are ordered by RuntimeResource; they are not process RSS."],"presets":reports});
std::fs::write(output.join("report.json"), serde_json::to_vec_pretty(&report).unwrap())
.unwrap();
println!("{}", serde_json::to_string_pretty(&report).unwrap());
}
@@ -0,0 +1,56 @@
# Stress Console music fixture
This fixture uses the Storm Eagle transcription supplied by the owner, sourced
from [Hooktheory](https://www.hooktheory.com/theorytab/view/setsuo-yamamoto/mega-man-x---storm-eagle).
`transcription.json` retains the musical fields: 90 melody notes, 20 chords,
relative degrees/accidentals, inversions and exact 480-PPQ source ticks. The
arranger multiplies ticks by two for native PPQ960, preserving the triplets and
the 72-beat loop. The nearest integer tempo to 168 BPM is 357143 us/quarter.
The eight source WAVs are an unchanged PCM subset extracted from the supplied
`MegaManX-SF-3.0.sf2`, whose INFO author is CliffyJiffy. Original bank fingerprint,
root keys, rates, pitch corrections and raw instrument generators are retained
in `soundfont-source.json`. The complete extracted banks remain at the sibling
port's `games/ports/snes/megaman-x/audio/`; playback and regeneration of this
selected fixture do not depend on that directory.
`tools/arrange_music.py` creates the offline authoring manifest `song.json` and
`instrument-mapping.json`. The latter records source-to-target pitch, loop,
gain, ADSR, pan and modulation decisions, including omitted SF2 hold/modulation
envelopes. Melodic negative SF2 sustain attenuation is clamped conceptually to
full sustain; target gain/articulation are explicit musical mix choices.
Drum Kit root overrides are applied. Source sample rates are preserved; root
and pitch correction are applied by native instruments. No full SF2 conversion,
chorus or SNES DSP emulation is claimed.
To rebuild the MusicBank from the existing WAVs/JSON, from the runtime root:
```sh
python3 crates/tools/pbxgen-stress/tools/regenerate_music.py
cargo run -p pbxgen-stress
```
This requires Python 3, Java 21+ and the sibling Studio checkout. A temporary
Gradle init task resolves the existing packer's runtime classpath. `PackMusic.java`
calls `AudioBankPacker.pack` twice, checks identical output, and writes the bank
and its size metrics. It contains no codec or MusicBank serializer. Studio source
and build scripts are not changed. Use `--studio PATH` for another checkout.
`storm-eagle.mbnk` and the usual `assets.pa` envelope are generated assets.
`bank-metrics.json` distinguishes cartridge payload, PCM bytes and canonical
decoded size; those values do not include all allocator/host overhead.
Run conformance and the optional WAV export with:
```sh
cargo test -p pbxgen-stress
PROMETEU_STRESS_WAV=/tmp/stress-console-storm-eagle.wav \
cargo test -p pbxgen-stress --release --test music_cartridge \
full_sequence_loops_and_frame_controls_preserve_audio -- --nocapture
```
The WAV is rendered by the real cartridge/headless/native mixer path at stereo
48 kHz and contains more than two loops. The test also compares playback with
and without bounded, representative graphics frames across both loops, checks
pause/resume and reports signal metrics and observed voices. It does not measure
sustained frame rate. Listening is still required to judge the mix.
@@ -0,0 +1,6 @@
{
"version" : 1,
"decoded_size" : 112224,
"pcm_bytes" : 60358,
"cartridge_bytes" : 90810
}
File diff suppressed because it is too large Load Diff

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