implements PLN-0141

This commit is contained in:
bQUARKz 2026-07-03 23:15:11 +01:00
parent 1b29b2f985
commit 999136fef3
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
7 changed files with 193 additions and 29 deletions

View File

@ -1,11 +1,14 @@
use crate::firmware::boot_target::BootTarget;
use crate::firmware::firmware_state::{FirmwareState, LoadCartridgeStep, ResetStep};
use crate::firmware::firmware_state::{
FirmwareState, GameRunningStep, LoadCartridgeStep, ResetStep,
};
use crate::firmware::prometeu_context::PrometeuContext;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::Cartridge;
use prometeu_hal::log::LogSource;
use prometeu_hal::telemetry::CertificationConfig;
use prometeu_hal::{InputSignals, RuntimePlatform};
use prometeu_system::{PrometeuHub, SystemOS};
use prometeu_system::{PrometeuHub, ResidentGameState, SystemOS};
use prometeu_vm::VirtualMachine;
/// PROMETEU Firmware.
@ -36,6 +39,7 @@ pub struct Firmware {
pub boot_target: BootTarget,
/// State-machine lifecycle tracker.
state_initialized: bool,
game_input_barrier_frames: u8,
}
impl Firmware {
@ -48,6 +52,7 @@ impl Firmware {
state: FirmwareState::Reset(ResetStep),
boot_target: BootTarget::Hub,
state_initialized: false,
game_input_barrier_frames: 0,
}
}
@ -56,23 +61,31 @@ impl Firmware {
/// This method is called exactly once per Host frame (60Hz).
/// It updates peripheral signals and delegates the logic to the current state.
pub fn tick(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
let barriered_signals = InputSignals::default();
let effective_signals = if self.game_input_barrier_frames > 0 {
self.game_input_barrier_frames -= 1;
&barriered_signals
} else {
signals
};
// 0. Process asset commits at the beginning of the frame boundary.
platform.assets_mut().apply_commits();
// 1. Update the peripheral state using the latest signals from the Host.
// This ensures input is consistent throughout the entire update.
platform.input_mut().pad_mut().begin_frame(signals);
platform.input_mut().touch_mut().begin_frame(signals);
platform.input_mut().pad_mut().begin_frame(effective_signals);
platform.input_mut().touch_mut().begin_frame(effective_signals);
// 2. State machine lifecycle management.
if !self.state_initialized {
self.on_enter(signals, platform);
self.on_enter(effective_signals, platform);
self.state_initialized = true;
}
// 3. Update the current state and check for transitions.
if let Some(next_state) = self.on_update(signals, platform) {
self.change_state(next_state, signals, platform);
if let Some(next_state) = self.on_update(effective_signals, platform) {
self.change_state(next_state, effective_signals, platform);
}
}
@ -176,9 +189,39 @@ impl Firmware {
LogSource::Pos,
format!("Home/SystemOS request could not pause Game: {error:?}"),
);
} else {
self.game_input_barrier_frames = 1;
}
}
}
pub fn resume_resident_game_from_home(&mut self) -> bool {
let Some(task_id) = self.os.lifecycle().resident_game_task() else {
return false;
};
if self.os.lifecycle().resume_task(task_id).is_err() {
return false;
}
let app_id = self.os.vm().current_app_id();
self.os.vm().transition_render_owner(AppMode::Game, app_id);
self.state = FirmwareState::GameRunning(GameRunningStep::new(task_id));
self.state_initialized = false;
self.game_input_barrier_frames = 1;
true
}
pub fn game_lifecycle_audio_paused(&mut self) -> bool {
matches!(
self.os.lifecycle().resident_game().map(|game| game.state),
Some(
ResidentGameState::PauseRequested { .. }
| ResidentGameState::PausedSuspended
| ResidentGameState::ResumeRequested,
)
)
}
}
#[cfg(test)]
@ -188,6 +231,7 @@ mod tests {
use prometeu_bytecode::assembler::assemble;
use prometeu_bytecode::model::{BytecodeModule, FunctionMeta, SyscallDecl};
use prometeu_drivers::TestPlatform;
use prometeu_hal::RuntimePlatform;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::AssetsPayloadSource;
use prometeu_hal::color::Color;
@ -757,9 +801,11 @@ mod tests {
other => panic!("expected GameRunning state, got {:?}", other),
};
let tick_index_before_home = firmware.os.vm().tick_index();
let render_ownership_before_home = firmware.os.vm().active_render_ownership();
firmware.request_home_from_host();
assert!(firmware.game_lifecycle_audio_paused());
assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Game(task_id));
assert_eq!(
firmware.os.lifecycle().resident_game().map(|game| game.state),
@ -770,7 +816,9 @@ mod tests {
Some(GameLifecycleEventKind::Pause)
);
firmware.tick(&signals, &mut platform);
let held_signals =
InputSignals { up_signal: true, f_signal: true, x_pos: 72, y_pos: 90, ..signals };
firmware.tick(&held_signals, &mut platform);
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
assert_eq!(firmware.os.lifecycle().task_state(task_id), Some(TaskState::Suspended));
@ -779,6 +827,53 @@ mod tests {
Ok(ProcessState::Suspended)
);
assert_eq!(firmware.os.vm().tick_index(), tick_index_before_home);
assert!(!platform.input().pad().any());
assert!(!platform.input().touch().f().down);
let render_ownership_after_home = firmware.os.vm().active_render_ownership();
assert_eq!(render_ownership_after_home.app_mode, AppMode::Shell);
assert_eq!(render_ownership_after_home.app_id, 0);
assert!(render_ownership_after_home.epoch > render_ownership_before_home.epoch);
}
#[test]
fn resident_game_resume_restores_render_owner_after_resume_event_and_barriers_input() {
let mut firmware = Firmware::new(None);
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
firmware.load_cartridge(valid_cartridge(AppMode::Game));
firmware.tick(&signals, &mut platform);
let task_id = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected GameRunning state, got {:?}", other),
};
firmware.request_home_from_host();
firmware.tick(&signals, &mut platform);
let hub_ownership = firmware.os.vm().active_render_ownership();
assert!(firmware.resume_resident_game_from_home());
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
assert!(!firmware.game_lifecycle_audio_paused());
assert_eq!(
firmware.os.lifecycle().pending_game_lifecycle_events().last().map(|event| event.kind),
Some(GameLifecycleEventKind::ResumeForeground)
);
let game_ownership = firmware.os.vm().active_render_ownership();
assert_eq!(game_ownership.app_mode, AppMode::Game);
assert_eq!(game_ownership.app_id, 9);
assert!(game_ownership.epoch > hub_ownership.epoch);
let held_signals =
InputSignals { up_signal: true, f_signal: true, x_pos: 72, y_pos: 90, ..signals };
firmware.tick(&held_signals, &mut platform);
assert_eq!(firmware.os.lifecycle().task_state(task_id), Some(TaskState::Foreground));
assert!(!platform.input().pad().any());
assert!(!platform.input().touch().f().down);
}
#[test]

View File

@ -1,5 +1,6 @@
use crate::firmware::firmware_state::{AppCrashesStep, FirmwareState, HubHomeStep};
use crate::firmware::prometeu_context::PrometeuContext;
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::log::{LogLevel, LogSource};
use prometeu_system::CrashReport;
use prometeu_system::task::{TaskId, TaskState};
@ -37,7 +38,10 @@ impl GameRunningStep {
}
match ctx.os.lifecycle().advance_game_pause_budget(self.task_id) {
Ok(true) => return Some(FirmwareState::HubHome(HubHomeStep)),
Ok(true) => {
ctx.os.vm().transition_render_owner(AppMode::Shell, 0);
return Some(FirmwareState::HubHome(HubHomeStep));
}
Ok(false) => {}
Err(_) => {
let report = CrashReport::VmPanic {

View File

@ -5,8 +5,8 @@ use prometeu_hal::app_mode::AppMode;
use prometeu_hal::cartridge::Cartridge;
use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame};
use prometeu_hal::{
FrameId, InputSignals, RenderWorkerBackend, RenderWorkerError, RenderWorkerFrameSink,
RuntimePlatform,
FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError,
RenderWorkerFrameSink, RuntimePlatform,
};
use prometeu_vm::VirtualMachine;
use std::sync::atomic::Ordering;
@ -120,6 +120,16 @@ impl<'a> VmFacade<'a> {
self.os.vm_runtime.record_repeated_render_worker_frame(frame_id);
}
pub fn active_render_ownership(&self) -> RenderOwnership {
self.os.vm_runtime.render_manager.active_ownership()
}
pub fn transition_render_owner(&mut self, app_mode: AppMode, app_id: u32) {
self.os.vm_runtime.render_manager.transition_render_owner(app_mode, app_id);
self.os.vm_runtime.sync_render_worker_ownership();
self.os.vm_runtime.render_manager.sync_telemetry(&self.os.vm_runtime.atomic_telemetry);
}
pub fn cert_config(&self) -> &CertificationConfig {
&self.os.vm_runtime.certifier.config
}

View File

@ -83,6 +83,10 @@ impl HostInputHandler {
self.system_controls.take_home_requested()
}
pub fn clear_guest_signals(&mut self) {
self.signals = InputSignals::default();
}
pub fn handle_key_code(&mut self, code: KeyCode, state: ElementState) {
let is_down = state == ElementState::Pressed;
@ -229,4 +233,16 @@ mod tests {
assert!(input.signals.up_signal);
assert!(!input.take_home_requested());
}
#[test]
fn clearing_guest_signals_preserves_system_home_control() {
let mut input = HostInputHandler::default();
input.handle_key_code(KeyCode::ArrowUp, ElementState::Pressed);
input.handle_key_code(KeyCode::Escape, ElementState::Pressed);
input.clear_guest_signals();
assert_no_pad_signal(input.signals);
assert!(input.take_home_requested());
}
}

View File

@ -10,8 +10,8 @@ use pixels::{Pixels, PixelsBuilder, SurfaceTexture};
use prometeu_drivers::hardware::Hardware;
use prometeu_drivers::{AudioCommand, LocalFramebufferRenderBackend, MemoryBanks};
use prometeu_firmware::{BootTarget, Firmware, FirmwareState};
use prometeu_hal::RuntimePlatform;
use prometeu_hal::telemetry::CertificationConfig;
use prometeu_hal::{OwnedRgba8888Frame, RenderOwnership, RuntimePlatform};
use prometeu_system::{LatestRenderFrameStore, RenderWorkerConfig, discover_games_root};
use std::sync::Arc;
use std::time::{Duration, Instant};
@ -88,8 +88,12 @@ fn desired_control_flow(
}
}
fn should_present_worker_frame(state: &FirmwareState) -> bool {
matches!(state, FirmwareState::GameRunning(_))
fn should_present_worker_frame(
state: &FirmwareState,
frame: &OwnedRgba8888Frame,
active_ownership: RenderOwnership,
) -> bool {
matches!(state, FirmwareState::GameRunning(_)) && frame.ownership == active_ownership
}
/// The Desktop implementation of the PROMETEU Runtime.
@ -312,8 +316,13 @@ impl ApplicationHandler for HostRunner {
{
let frame = pixels.frame_mut();
if should_present_worker_frame(&self.firmware.state)
&& let Some(worker_frame) = self.render_frame_store.latest_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.firmware
.os
@ -373,6 +382,7 @@ impl ApplicationHandler for HostRunner {
}
if self.input.take_home_requested() {
self.input.clear_guest_signals();
self.firmware.request_home_from_host();
self.invalidate_host_surface();
self.request_redraw_if_needed();
@ -405,7 +415,10 @@ impl ApplicationHandler for HostRunner {
// Sync pause state with audio.
// We do this AFTER firmware.tick to avoid MasterPause/Resume commands
// being cleared by the OS if a new logical frame starts in this tick.
let is_paused = self.firmware.os.vm().paused() || self.debugger.waiting_for_start;
let lifecycle_audio_paused = self.firmware.game_lifecycle_audio_paused();
let is_paused = lifecycle_audio_paused
|| self.firmware.os.vm().paused()
|| self.debugger.waiting_for_start;
if is_paused != self.last_paused_state {
self.last_paused_state = is_paused;
let cmd =
@ -420,8 +433,9 @@ impl ApplicationHandler for HostRunner {
self.stats.record_frame();
}
if should_present_worker_frame(&self.firmware.state)
&& let Some(worker_frame) = self.render_frame_store.latest_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.frame_id.get());
} else {
@ -542,14 +556,39 @@ mod tests {
}
#[test]
fn worker_frame_presentation_is_game_only() {
assert!(should_present_worker_frame(&FirmwareState::GameRunning(GameRunningStep::new(
TaskId(1),
))));
assert!(!should_present_worker_frame(&FirmwareState::ShellRunning(ShellRunningStep::new(
TaskId(2)
),)));
assert!(!should_present_worker_frame(&FirmwareState::HubHome(HubHomeStep)));
fn worker_frame_presentation_requires_game_state_and_current_ownership() {
let active = RenderOwnership::new(3, AppMode::Game, 1);
let current = OwnedRgba8888Frame::packed(FrameId::new(9), active, 1, 1, vec![0xFF00FFFF])
.expect("test frame");
let stale = OwnedRgba8888Frame::packed(
FrameId::new(8),
RenderOwnership::new(2, AppMode::Game, 1),
1,
1,
vec![0xFF00FFFF],
)
.expect("test frame");
assert!(should_present_worker_frame(
&FirmwareState::GameRunning(GameRunningStep::new(TaskId(1))),
&current,
active,
));
assert!(!should_present_worker_frame(
&FirmwareState::GameRunning(GameRunningStep::new(TaskId(1),)),
&stale,
active,
));
assert!(!should_present_worker_frame(
&FirmwareState::ShellRunning(ShellRunningStep::new(TaskId(2))),
&current,
active,
));
assert!(!should_present_worker_frame(
&FirmwareState::HubHome(HubHomeStep),
&current,
active,
));
}
#[test]

View File

@ -2,7 +2,7 @@
{"type":"discussion","id":"DSC-0043","status":"open","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-systemos-cartridge-switch-orchestrator.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[],"plans":[],"lessons":[]}
{"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}
{"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]}
{"type":"discussion","id":"DSC-0041","status":"in_progress","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-foreground-stack-and-game-pause-contract.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0041"}],"plans":[{"id":"PLN-0136","file":"PLN-0136-route-desktop-home-key-outside-guest-input.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0137","file":"PLN-0137-implement-systemos-foreground-stack-state.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0138","file":"PLN-0138-specify-foreground-pause-and-home-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0139","file":"PLN-0139-validate-game-home-shell-game-end-to-end.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0140","file":"PLN-0140-deliver-game-pause-resume-and-suspension.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0141","file":"PLN-0141-integrate-render-audio-and-input-pause-boundaries.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0041","status":"in_progress","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"accepted","created_at":"2026-06-05","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-foreground-stack-and-game-pause-contract.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0041"}],"plans":[{"id":"PLN-0136","file":"PLN-0136-route-desktop-home-key-outside-guest-input.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0137","file":"PLN-0137-implement-systemos-foreground-stack-state.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0138","file":"PLN-0138-specify-foreground-pause-and-home-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0139","file":"PLN-0139-validate-game-home-shell-game-end-to-end.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0140","file":"PLN-0140-deliver-game-pause-resume-and-suspension.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0141","file":"PLN-0141-integrate-render-audio-and-input-pause-boundaries.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]}],"lessons":[]}
{"type":"discussion","id":"DSC-0042","status":"done","ticket":"real-render-worker-establishment","title":"Real Render Worker Establishment","created_at":"2026-06-06","updated_at":"2026-06-20","tags":["runtime","renderer","worker","concurrency","host","hal","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0049","file":"discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md","status":"done","created_at":"2026-06-20","updated_at":"2026-06-20"}]}
{"type":"discussion","id":"DSC-0038","status":"done","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0038-render-frame-packet-boundary/LSN-0047-typed-render-submissions-preserve-domain-boundaries.md","status":"done","created_at":"2026-06-04","updated_at":"2026-06-04"}]}
{"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}

View File

@ -2,7 +2,7 @@
id: PLN-0141
ticket: foreground-stack-game-pause-shell-vm-backed
title: Integrate Render Audio and Input Pause Boundaries
status: open
status: done
created: 2026-07-03
ref_decisions: [DEC-0037]
tags: [runtime, renderer, audio, input, foreground, lifecycle]