feat(runtime): support Studio Play and separate integration gates
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
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.
This commit is contained in:
@@ -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:
|
||||
cargo fmt --all
|
||||
@@ -9,8 +9,15 @@ fmt-check:
|
||||
clippy:
|
||||
cargo clippy --workspace --all-targets --all-features -- -D warnings
|
||||
|
||||
test-local:
|
||||
cargo test --workspace --all-targets --all-features --no-fail-fast
|
||||
test-unit:
|
||||
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:
|
||||
cargo test -p prometeu-host-desktop-winit --lib runner::tests -- --ignored
|
||||
@@ -19,7 +26,7 @@ clean:
|
||||
cargo llvm-cov clean --workspace
|
||||
|
||||
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:
|
||||
cargo llvm-cov report --json --output-path target/llvm-cov/report.json
|
||||
@@ -46,9 +53,9 @@ coverage-domain-evidence:
|
||||
coverage-domain-gate:
|
||||
./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.
|
||||
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-domains:
|
||||
|
||||
@@ -133,7 +133,14 @@ The authoritative target used by both GitHub and Jenkins is:
|
||||
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
|
||||
|
||||
@@ -170,7 +177,7 @@ make coverage-domain-evidence DOMAIN=host/headless
|
||||
```
|
||||
|
||||
`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.
|
||||
A failing run never lowers a configured floor; local and CI checks use the same
|
||||
repository-owned commands. Reports identify their revision, source/configuration
|
||||
|
||||
@@ -40,6 +40,19 @@ impl LatestRenderFrameStore {
|
||||
pub fn latest_frame(&self) -> Option<OwnedRgba8888Frame> {
|
||||
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 {
|
||||
|
||||
@@ -6,6 +6,7 @@ pub mod input;
|
||||
pub mod log_sink;
|
||||
pub mod runner;
|
||||
pub mod stats;
|
||||
pub mod studio;
|
||||
pub mod utilities;
|
||||
pub mod wall_clock;
|
||||
|
||||
@@ -18,6 +19,9 @@ use winit::event_loop::EventLoop;
|
||||
#[derive(Parser, Debug)]
|
||||
#[command(author, version, about, long_about = None)]
|
||||
struct Cli {
|
||||
/// Run an interactive Studio session without creating a desktop window.
|
||||
#[arg(long, requires = "run", conflicts_with = "debug")]
|
||||
studio: bool,
|
||||
/// Run a cartridge
|
||||
#[arg(long, value_name = "PATH", conflicts_with = "debug")]
|
||||
run: Option<String>,
|
||||
@@ -54,6 +58,23 @@ struct Cli {
|
||||
pub fn run() -> Result<(), Box<dyn std::error::Error>> {
|
||||
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 cap_config = cli.cap.as_ref().and_then(|path| load_cap_config(path));
|
||||
|
||||
|
||||
@@ -151,6 +151,7 @@ pub struct HostRunner {
|
||||
render_frame_store: LatestRenderFrameStore,
|
||||
/// Tracks whether a new logical frame or host-only surface invalidation requires presentation.
|
||||
presentation: PresentationState,
|
||||
studio_capture: bool,
|
||||
}
|
||||
|
||||
impl HostRunner {
|
||||
@@ -238,9 +239,161 @@ impl HostRunner {
|
||||
audio: HostAudio::new(),
|
||||
render_frame_store,
|
||||
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 {
|
||||
self.window.expect("window not created yet")
|
||||
}
|
||||
@@ -435,18 +588,7 @@ impl ApplicationHandler for HostRunner {
|
||||
while self.accumulator >= self.frame_target_dt {
|
||||
// Reclaim returned audio owners before another guest attempt, even
|
||||
// when the previous attempt paused or stopped at backpressure.
|
||||
self.audio.service();
|
||||
// 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.tick_machine();
|
||||
|
||||
self.accumulator -= self.frame_target_dt;
|
||||
self.stats.record_frame();
|
||||
@@ -500,6 +642,73 @@ impl ApplicationHandler for HostRunner {
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[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::firmware::firmware_state::{
|
||||
GameRunningStep, HubHomeStep, ShellRunningStep,
|
||||
|
||||
@@ -0,0 +1,255 @@
|
||||
//! 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 / 60);
|
||||
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, 60, 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(480, 270, 481).is_err());
|
||||
assert_eq!(frame_bytes(480, 270, 480).unwrap(), 518400);
|
||||
}
|
||||
#[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,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()), 480);
|
||||
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 + 480 * 270 * 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,2 @@
|
||||
50 53 54 31 01 00 00 00 04 00 00 00 00 00 00 00
|
||||
01 00 00 00 00 00 00 00 2a 00 00 00 00 00 00 00
|
||||
@@ -0,0 +1,6 @@
|
||||
50 53 54 31 01 00 00 00 09 00 00 00 38 00 00 00
|
||||
01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
|
||||
00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f
|
||||
01 00 00 00 00 00 00 00 07 00 00 00 00 00 00 00
|
||||
02 00 00 00 01 00 00 00 02 00 00 00 01 00 00 00
|
||||
ff 00 00 ff 00 00 ff 80
|
||||
@@ -279,6 +279,13 @@ PROMETEU promises:
|
||||
|
||||
## 13 Deterministic Headless Control
|
||||
|
||||
The interactive desktop host also supports Studio-owned realtime execution without
|
||||
a native game window, specified by [Studio Play Protocol v1](11b-studio-play-protocol.md).
|
||||
This mode retains interactive pacing, native audio and the existing firmware/VM;
|
||||
it is not the deterministic automation host. Its frame transport workers must not
|
||||
block machine advancement on UI/video consumption. This addition does not change
|
||||
the headless controls below, guest capabilities or canonical frame ownership.
|
||||
|
||||
The external tooling boundary is specified separately in
|
||||
[Headless Automation Protocol v1](11a-headless-automation-protocol.md). It preserves
|
||||
the in-process semantics in this section and does not extend the guest ABI.
|
||||
|
||||
@@ -0,0 +1,81 @@
|
||||
# Studio Play Protocol v1
|
||||
|
||||
This protocol belongs to the interactive desktop host. It does not extend or replace
|
||||
the deterministic headless automation protocol. The mode and Java adapter are
|
||||
implemented and exercised on macOS ARM64 with a relocated installation of current
|
||||
debug binaries. Protocol fixtures do not qualify other platforms or release builds.
|
||||
|
||||
The Studio starts `prometeu-runtime --studio --run <directory>` directly. No native
|
||||
window/event loop is created in this mode. The parent listens on two ephemeral IPv4
|
||||
loopback ports: control/input and video. Both connect/authenticate before readiness.
|
||||
The parent sends a BOOTSTRAP message through private child stdin and closes stdin.
|
||||
Bootstrap payload: session ID (16 bytes), random token (32 bytes), control/video ports
|
||||
(u16 each), disposable-save selection (u8: 0 persistent, 1 explicitly disposable).
|
||||
Token material must not appear in arguments or logs. No reconnect or automatic restart.
|
||||
|
||||
All integer fields use little-endian encoding. Messages have this 32-byte header:
|
||||
|
||||
| Offset | Type | Meaning |
|
||||
| --- | --- | --- |
|
||||
| 0 | 4 bytes | ASCII PST1 |
|
||||
| 4 / 6 | u16 / u16 | major 1 / minor 0 |
|
||||
| 8 / 10 | u16 / u16 | type / flags (zero) |
|
||||
| 12 | u32 | payload bytes, validated before allocation |
|
||||
| 16 | u64 | strictly increasing nonzero sequence per direction/channel |
|
||||
| 24 | u64 | request correlation, zero for unsolicited messages |
|
||||
|
||||
Types: HELLO=1, READY=2, START=3, PAUSE=4, RESUME=5, STOP=6, RESULT=7,
|
||||
INPUT=8, FRAME=9, FRAME_RECEIVED=10, PING=11, PONG=12, ERROR=13,
|
||||
STOPPED=14, BOOTSTRAP=15. Unknown types/flags/versions, invalid sizes, replay,
|
||||
invalid UTF-8 and truncated messages fail the connection. Control payload limit is
|
||||
64 KiB; FRAME limit is 16 MiB including metadata. Overflow is rejected.
|
||||
|
||||
| Message | Payload |
|
||||
| --- | --- |
|
||||
| HELLO | session[16], token[32], role u8 (control=1, video=2) |
|
||||
| READY | width/height/fps/format u32; UTF-8 runtime version in remaining bytes |
|
||||
| START / PAUSE / RESUME / STOP / PING | empty; nonzero request ID for commands |
|
||||
| RESULT | command u16, status u16 (0 success, 1 invalid state, 2 save blocked), input epoch u64, tick u64, UTF-8 diagnostic remainder |
|
||||
| INPUT | input epoch u64, buttons u16, reserved u16=0, touch x/y i32 |
|
||||
| FRAME | session[16], input epoch u64, frame ID u64, width/height/stride/format u32, pixels |
|
||||
| FRAME_RECEIVED | input epoch u64, frame ID u64 |
|
||||
| PONG | input epoch u64, tick u64, state u32 (0 ready, 1 running, 2 paused) |
|
||||
| ERROR | UTF-8 diagnostic |
|
||||
| STOPPED | empty; correlated with successful STOP |
|
||||
|
||||
Pixel format 1 is compact RGBA8: R,G,B,A bytes, stride equal to width. Never memcpy
|
||||
native u32 `0xRRGGBBAA` as wire pixels. FRAME metadata occupies 48 bytes; dimensions
|
||||
must match readiness and payload length exactly. Zoom is entirely a Studio concern.
|
||||
INPUT bits 0..11 are up/down/left/right/a/b/x/y/l/r/start/select; bit 12 is touch.
|
||||
Other bits are invalid. Apply samples in order at the canonical tick boundary; this
|
||||
does not introduce event retention beyond canonical button sampling.
|
||||
|
||||
The machine starts only after START. Pause suspends simulation/audio and neutralizes
|
||||
input; resume retains the same execution. A new input epoch invalidates queued input
|
||||
across pause/resume. PAUSE is also admitted in READY: a subsequent START arms execution
|
||||
while retaining that pause, and only an explicit RESUME begins ticks. This lets focus
|
||||
loss during startup take effect before the first game tick. Control and heartbeat work
|
||||
while paused. Stop preserves the
|
||||
existing save/teardown checks; save refusal is a RESULT and keeps the session alive.
|
||||
An explicitly disposable session permits discarding only its selected transient data.
|
||||
|
||||
Frame publication never waits for IO or presentation. One frame can be in flight;
|
||||
FRAME_RECEIVED releases credit after full reception/validation, not after painting.
|
||||
The sender selects the most recent complete publication when credit is available.
|
||||
It must finish a partly written message or fail. The receiver drains independently
|
||||
of the FX thread and replaces only an unowned pending complete image. Three local
|
||||
receiver buffers cover receive, pending and FX-copy ownership; WritableImage owns its
|
||||
own pixels. At most one pending FX notification is permitted.
|
||||
|
||||
Handshake deadline: 10 seconds. Command deadline: 5 seconds. Heartbeat interval:
|
||||
1 second, failed after 5 seconds without valid control progress. Video silence while
|
||||
paused and slow FX painting are not connection failures. Unexpected EOF on either
|
||||
required channel or malformed data ends the runtime and reports available logs.
|
||||
The Studio confirms exit and cleanup before releasing execution ownership; it does
|
||||
not claim failed-process saves were flushed or rolled back. Normal EOF after STOPPED
|
||||
is expected. Termination uses a 2-second bounded wait and a further 2-second forced
|
||||
termination observation when required. The child also exits on lost parent control.
|
||||
|
||||
Language-neutral fixtures live in `devtools/studio-protocol/fixtures/` and are consumed
|
||||
by both codecs. Qualification includes fragmented IO, invalid payloads, late session
|
||||
messages, slow painting/sending, failure of each channel and headless regressions.
|
||||
@@ -91,6 +91,7 @@ In the current state, no chapter under the active `docs/specs/runtime/` root is
|
||||
| [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) | machine diagnostics | normative |
|
||||
| [`11-portability-and-cross-platform-execution.md`](11-portability-and-cross-platform-execution.md) | portability contract | normative |
|
||||
| [`11a-headless-automation-protocol.md`](11a-headless-automation-protocol.md) | external headless host automation | normative |
|
||||
| [`11b-studio-play-protocol.md`](11b-studio-play-protocol.md) | interactive Studio binary IPC, separate from headless | normative |
|
||||
| [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) | firmware and system orchestration | normative |
|
||||
| [`13-cartridge.md`](13-cartridge.md) | cartridge package | normative |
|
||||
| [`14-boot-profiles.md`](14-boot-profiles.md) | firmware boot flow | normative |
|
||||
|
||||
@@ -53,6 +53,14 @@ prefix must be assigned before the ownership audit can pass.
|
||||
|
||||
## How test suites contribute
|
||||
|
||||
The current repository pipeline executes and measures only library/binary unit
|
||||
tests (`--lib --bins`). Integration targets under `tests/`, debugger socket tests,
|
||||
installed qualification and physical-device checks are excluded. Selected suites
|
||||
are orchestrated by `../tooling`; their tests and fixtures stay in this repository.
|
||||
Selecting them explicitly is separate from the unit quality gate.
|
||||
The cross-suite contribution descriptions and previous measurements below retain
|
||||
historical context; they do not imply integration execution in the current gate.
|
||||
|
||||
VM unit/integration tests, including numeric_contract and the portable
|
||||
MPFR-generated fixture, exercise vm/core. Bytecode round-trip and Registry
|
||||
admission tests exercise bytecode; end-to-end loading can also exercise
|
||||
@@ -74,7 +82,7 @@ they do not create separate gates with zero executable lines.
|
||||
Only crate src paths participate in this domain denominator; integration
|
||||
test directories, examples, benches, external dependencies and standalone
|
||||
Python oracle code are outside it. The LLVM instrumentation/report remains
|
||||
the existing workspace all-features default-profile measurement. Unit tests
|
||||
the workspace all-features default-profile, library/binary-unit measurement. Unit tests
|
||||
colocated in src retain the tool's existing reporting behavior.
|
||||
|
||||
The standalone MPFR precision/bit comparison remains complementary numeric
|
||||
@@ -129,12 +137,11 @@ The ordered checks are:
|
||||
1. Clean previous LLVM coverage instrumentation and reports.
|
||||
2. Check formatting.
|
||||
3. Run workspace Clippy with warnings denied.
|
||||
4. Run workspace tests across all targets and features.
|
||||
5. Run the five ignored debugger socket tests.
|
||||
6. Generate workspace coverage, HTML, full JSON, Cobertura and summary JSON.
|
||||
7. Audit source ownership/evidence and check every fixed coverage domain floor.
|
||||
4. Run library/binary unit tests across all workspace features (`make test-unit`).
|
||||
5. Generate unit-only workspace coverage, HTML, full JSON, Cobertura and summary JSON.
|
||||
6. Audit source ownership/evidence and check every fixed coverage domain floor.
|
||||
|
||||
The socket command is deliberately restricted:
|
||||
The optional socket command is deliberately restricted and is not part of CI:
|
||||
|
||||
```sh
|
||||
cargo test -p prometeu-host-desktop-winit --lib runner::tests -- --ignored
|
||||
@@ -194,9 +201,8 @@ scripts/coverage-domain-evidence.sh --check --verbose hal/core
|
||||
|
||||
### Explicit manual qualification
|
||||
|
||||
Ordinary all-target tests and coverage leave ignored device/measurement tests
|
||||
ignored. The shared target only opts in to the five socket tests above. It does
|
||||
not certify the following manual workloads:
|
||||
Unit tests and coverage leave ignored device/measurement tests ignored. The shared
|
||||
target does not opt in to socket tests and does not certify the following manual workloads:
|
||||
|
||||
```sh
|
||||
# Physical desktop audio, exact named test.
|
||||
@@ -269,7 +275,26 @@ The full local `make ci-domains` validation passed with 939 tests passed and
|
||||
in verification; its final floor uses the lower measurement. All gates were
|
||||
rechecked against the verification report after that final adjustment.
|
||||
|
||||
## Current coverage measurement
|
||||
## Unit-only baseline revision
|
||||
|
||||
The gate now measures only `--lib --bins` unit harnesses. Two independent fresh
|
||||
measurements agreed on bytecode 86.51%, host/headless 58.74%, and tooling 50.96%.
|
||||
Their explicitly approved unit floors use five percentage points of headroom:
|
||||
|
||||
| Domain | Unit measurement | Unit floor | Previous combined floor |
|
||||
| --- | ---: | ---: | ---: |
|
||||
| bytecode | 86.51% | 81.51% | 88.26% |
|
||||
| host/headless | 58.74% | 53.74% | 83.39% |
|
||||
| tooling | 50.96% | 45.96% | 59.75% |
|
||||
|
||||
The other twelve floors and all source ownership paths are unchanged. The config
|
||||
identifies `test_suite: unit` and preserves each replaced combined floor in
|
||||
`previous_combined_baseline_percent`. This is a reviewed change of measurement
|
||||
scope, not an automatic response to future coverage failures. Subsequent unit
|
||||
regressions remain subject to these fixed floors. Earlier combined measurements
|
||||
below remain historical and are not current unit coverage claims.
|
||||
|
||||
## Previous combined-suite coverage measurement
|
||||
|
||||
The [current evidence](COVERAGE_DOMAINS_CURRENT.json) identifies the committed
|
||||
source by HEAD and content fingerprints, records the strict shared gate and
|
||||
|
||||
Vendored
+4
-5
@@ -32,12 +32,11 @@ pipeline {
|
||||
stage('Clippy') {
|
||||
steps { sh 'make -j1 clippy' }
|
||||
}
|
||||
stage('Workspace tests') {
|
||||
steps { sh 'make -j1 test-local' }
|
||||
}
|
||||
stage('Debugger socket tests') {
|
||||
steps { sh 'make -j1 test-debugger-socket' }
|
||||
stage('Unit tests') {
|
||||
steps { sh 'make -j1 test-unit' }
|
||||
}
|
||||
// Integration/socket/installed qualification is orchestrated by ../tooling;
|
||||
// it is intentionally not invoked by this repository pipeline.
|
||||
stage('Coverage') {
|
||||
steps { sh 'make -j1 coverage' }
|
||||
}
|
||||
|
||||
@@ -1,5 +1,6 @@
|
||||
{
|
||||
"version": 1,
|
||||
"test_suite": "unit",
|
||||
"domains": {
|
||||
"system/os": {
|
||||
"baseline_percent": 77.24,
|
||||
@@ -54,7 +55,8 @@
|
||||
]
|
||||
},
|
||||
"host/headless": {
|
||||
"baseline_percent": 83.39,
|
||||
"baseline_percent": 53.74,
|
||||
"previous_combined_baseline_percent": 83.39,
|
||||
"paths": [
|
||||
"crates/host/prometeu-host-headless/src/"
|
||||
]
|
||||
@@ -66,7 +68,8 @@
|
||||
]
|
||||
},
|
||||
"bytecode": {
|
||||
"baseline_percent": 88.26,
|
||||
"baseline_percent": 81.51,
|
||||
"previous_combined_baseline_percent": 88.26,
|
||||
"paths": [
|
||||
"crates/console/prometeu-bytecode/src/"
|
||||
]
|
||||
@@ -111,7 +114,8 @@
|
||||
]
|
||||
},
|
||||
"tooling": {
|
||||
"baseline_percent": 59.75,
|
||||
"baseline_percent": 45.96,
|
||||
"previous_combined_baseline_percent": 59.75,
|
||||
"paths": [
|
||||
"crates/tools/prometeu-cli/src/",
|
||||
"crates/tools/pbxgen-dummy-boy/src/",
|
||||
|
||||
Reference in New Issue
Block a user