feat(runtime): add optional pause and resume lifecycle hooks
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...
This commit is contained in:
@@ -83,6 +83,40 @@ impl Firmware {
|
||||
self.state_initialized = true;
|
||||
}
|
||||
|
||||
// Hooks run after leaving gameplay and before completing OS suspension/resume.
|
||||
if let Some((task_id, result)) = self.os.vm().poll_pending_lifecycle(platform) {
|
||||
if let Err(report) = result {
|
||||
let _ = self.os.lifecycle().crash_task(task_id, Some(&report));
|
||||
self.change_state(
|
||||
FirmwareState::AppCrashes(crate::firmware::firmware_state::AppCrashesStep {
|
||||
report,
|
||||
}),
|
||||
effective_signals,
|
||||
platform,
|
||||
);
|
||||
} else if matches!(self.state, FirmwareState::GameRunning(_))
|
||||
&& matches!(
|
||||
self.os.lifecycle().task_state(task_id),
|
||||
Some(
|
||||
prometeu_system::task::TaskState::Suspended
|
||||
| prometeu_system::task::TaskState::Closed
|
||||
)
|
||||
)
|
||||
{
|
||||
self.os.vm().transition_render_owner(AppMode::Shell, 0);
|
||||
let state = match self.os.lifecycle().foreground_owner() {
|
||||
prometeu_system::ForegroundOwner::Shell(task_id) => {
|
||||
FirmwareState::ShellRunning(
|
||||
crate::firmware::firmware_state::ShellRunningStep::new(task_id),
|
||||
)
|
||||
}
|
||||
_ => FirmwareState::HubHome(crate::firmware::firmware_state::HubHomeStep),
|
||||
};
|
||||
self.change_state(state, effective_signals, platform);
|
||||
}
|
||||
return;
|
||||
}
|
||||
|
||||
// 3. Update the current state and check for transitions.
|
||||
if let Some(next_state) = self.on_update(effective_signals, platform) {
|
||||
self.change_state(next_state, effective_signals, platform);
|
||||
@@ -352,6 +386,7 @@ mod tests {
|
||||
TestProgram {
|
||||
const_pool: vec![],
|
||||
functions: vec![FunctionDecl {
|
||||
lifecycle_role: Default::default(),
|
||||
code_offset: 0,
|
||||
code_len: code.len() as u32,
|
||||
|
||||
@@ -392,6 +427,7 @@ mod tests {
|
||||
let program = TestProgram {
|
||||
const_pool: vec![],
|
||||
functions: vec![FunctionDecl {
|
||||
lifecycle_role: Default::default(),
|
||||
code_offset: 0,
|
||||
code_len: code.len() as u32,
|
||||
|
||||
@@ -1714,4 +1750,226 @@ mod tests {
|
||||
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
|
||||
assert_eq!(firmware.os.vm().current_cartridge_title(), "Valid Cart");
|
||||
}
|
||||
fn lifecycle_cartridge(pause: &str, resume: &str) -> Cartridge {
|
||||
use prometeu_bytecode::registry::LifecycleRole;
|
||||
let mut program = TestProgram::single(
|
||||
assemble("FRAME_SYNC\nJMP 0").unwrap(),
|
||||
int64_signature(0, 0),
|
||||
0,
|
||||
8,
|
||||
);
|
||||
for (role, source) in
|
||||
[(LifecycleRole::BeforePause, pause), (LifecycleRole::BeforeResume, resume)]
|
||||
{
|
||||
if source.is_empty() {
|
||||
continue;
|
||||
}
|
||||
let code = assemble(source).unwrap();
|
||||
program.functions.push(FunctionDecl {
|
||||
lifecycle_role: role,
|
||||
code_offset: program.code.len() as u32,
|
||||
code_len: code.len() as u32,
|
||||
max_stack_slots: 8,
|
||||
..Default::default()
|
||||
});
|
||||
program.code.extend(code);
|
||||
}
|
||||
let mut cartridge = valid_cartridge(AppMode::Game);
|
||||
cartridge.program = program.serialize();
|
||||
cartridge
|
||||
}
|
||||
|
||||
fn load_lifecycle(pause: &str, resume: &str) -> (Firmware, TestPlatform, TaskId) {
|
||||
let mut firmware = Firmware::new(None);
|
||||
let mut platform = TestPlatform::new();
|
||||
firmware.load_cartridge(lifecycle_cartridge(pause, resume));
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
let task = firmware.os.lifecycle().resident_game_task().unwrap();
|
||||
(firmware, platform, task)
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lifecycle_home_resume_callbacks_are_outside_frames_and_preserve_pc() {
|
||||
let (mut fw, mut platform, task) = load_lifecycle("RET", "RET");
|
||||
let signals = InputSignals::default();
|
||||
assert!(!fw.os.lifecycle().advance_game_pause_budget(task).unwrap());
|
||||
assert!(fw.os.vm().poll_pending_lifecycle(&mut platform).is_none());
|
||||
fw.request_home_from_host();
|
||||
fw.tick(&signals, &mut platform); // existing handoff tick
|
||||
let pc = fw.os.vm().active_pc();
|
||||
let ticks = vm_session_tick_index(&mut fw, task);
|
||||
let frames = fw.os.vm().completed_logical_frames();
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground));
|
||||
fw.tick(&signals, &mut platform); // BeforePause only
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
|
||||
assert_eq!(fw.os.vm().active_pc(), pc);
|
||||
assert_eq!(vm_session_tick_index(&mut fw, task), ticks);
|
||||
assert!(fw.resume_resident_game_from_home());
|
||||
fw.tick(&signals, &mut platform); // BeforeResume only
|
||||
assert_eq!(fw.os.vm().active_pc(), pc);
|
||||
assert_eq!(vm_session_tick_index(&mut fw, task), ticks);
|
||||
assert_eq!(fw.os.vm().completed_logical_frames(), frames);
|
||||
assert_eq!(fw.os.lifecycle().resident_game().unwrap().state, ResidentGameState::Foreground);
|
||||
fw.tick(&signals, &mut platform);
|
||||
assert_eq!(vm_session_tick_index(&mut fw, task), ticks + 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lifecycle_direct_suspend_and_shell_handoff_wait_for_callback() {
|
||||
let (mut fw, mut platform, task) = load_lifecycle("RET", "RET");
|
||||
fw.os.lifecycle().suspend_task(task).unwrap();
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground));
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
|
||||
assert!(fw.resume_resident_game_from_home());
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
let shell = fw.os.sessions().try_create_native_shell_task(99, "Tools").unwrap();
|
||||
assert_eq!(fw.os.lifecycle().foreground_owner(), ForegroundOwner::Game(task));
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
assert_eq!(fw.os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lifecycle_debugger_retains_budget_and_steps_without_game_frames() {
|
||||
let (mut fw, mut platform, task) = load_lifecycle("PUSH_I32 7\nSET_GLOBAL 0\nRET", "RET");
|
||||
fw.os.lifecycle().suspend_task(task).unwrap();
|
||||
let offset = assemble("FRAME_SYNC\nJMP 0").unwrap().len();
|
||||
fw.os.vm().insert_active_breakpoint(offset);
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
assert!(fw.os.vm().paused());
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Foreground));
|
||||
let remaining =
|
||||
fw.os.sessions().vm_session_for_task(task).unwrap().vm.lifecycle_remaining_cycles();
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
assert_eq!(
|
||||
fw.os.sessions().vm_session_for_task(task).unwrap().vm.lifecycle_remaining_cycles(),
|
||||
remaining
|
||||
);
|
||||
for _ in 0..3 {
|
||||
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
|
||||
}
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
|
||||
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lifecycle_faults_exhaustion_and_halt_never_resume_gameplay() {
|
||||
for body in ["FRAME_SYNC\nRET", "JMP 0", "HALT"] {
|
||||
let (mut fw, mut platform, task) = load_lifecycle(body, "RET");
|
||||
fw.os.lifecycle().suspend_task(task).unwrap();
|
||||
for _ in 0..8 {
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
if fw.os.lifecycle().task_state(task) != Some(TaskState::Foreground) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
if body == "HALT" {
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Closed));
|
||||
assert!(matches!(fw.state, FirmwareState::HubHome(_)));
|
||||
} else {
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Crashed));
|
||||
let FirmwareState::AppCrashes(step) = &fw.state else { panic!("expected crash") };
|
||||
assert!(step.report.to_string().contains("BeforePause"));
|
||||
}
|
||||
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
|
||||
}
|
||||
}
|
||||
#[test]
|
||||
fn lifecycle_debugger_hostcalls_use_real_session_handles() {
|
||||
use prometeu_bytecode::registry::LifecycleRole;
|
||||
let main = assemble("FRAME_SYNC\nJMP 0").unwrap();
|
||||
let mut program = TestProgram::single(main, int64_signature(0, 0), 0, 8);
|
||||
let hook =
|
||||
assemble("PUSH_CONST 0\nHOSTCALL 0\nPOP_N 1\nPUSH_I32 42\nHOSTCALL 1\nRET").unwrap();
|
||||
program
|
||||
.const_pool
|
||||
.push(prometeu_bytecode::model::ConstantPoolEntry::String("/missing".into()));
|
||||
program.syscalls.push(SyscallDecl {
|
||||
module: "fs".into(),
|
||||
name: "open".into(),
|
||||
version: 1,
|
||||
arg_slots: 1,
|
||||
ret_slots: 1,
|
||||
});
|
||||
program.functions.push(FunctionDecl {
|
||||
lifecycle_role: LifecycleRole::BeforePause,
|
||||
code_offset: program.code.len() as u32,
|
||||
code_len: hook.len() as u32,
|
||||
max_stack_slots: 8,
|
||||
..Default::default()
|
||||
});
|
||||
program.code.extend(hook);
|
||||
program.syscalls.push(SyscallDecl {
|
||||
module: "fs".into(),
|
||||
name: "close".into(),
|
||||
version: 1,
|
||||
arg_slots: 1,
|
||||
ret_slots: 0,
|
||||
});
|
||||
let mut cartridge = valid_cartridge(AppMode::Game);
|
||||
cartridge.capabilities = caps::FS;
|
||||
cartridge.program = program.serialize();
|
||||
let mut fw = Firmware::new(None);
|
||||
let mut platform = TestPlatform::new();
|
||||
fw.load_cartridge(cartridge);
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
let task = fw.os.lifecycle().resident_game_task().unwrap();
|
||||
fw.os
|
||||
.sessions()
|
||||
.vm_session_for_task_mut(task)
|
||||
.unwrap()
|
||||
.open_files
|
||||
.insert(42, "/save".into());
|
||||
fw.os.lifecycle().suspend_task(task).unwrap();
|
||||
fw.os.vm().set_paused(true);
|
||||
assert_eq!(
|
||||
fw.os.sessions().vm_session_for_task(task).unwrap().fs_state,
|
||||
prometeu_system::fs::FsState::Unmounted
|
||||
);
|
||||
// fs.open returns an ordinary error value on this unmounted session.
|
||||
for _ in 0..6 {
|
||||
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
|
||||
}
|
||||
assert!(fw.os.sessions().vm_session_for_task(task).unwrap().open_files.is_empty());
|
||||
let pc = fw.os.vm().active_pc();
|
||||
assert!(fw.os.vm().debug_step_active_session(&mut platform).is_none());
|
||||
assert_eq!(fw.os.vm().active_pc(), pc);
|
||||
assert!(fw.os.vm().tick_session(task, &InputSignals::default(), &mut platform).is_none());
|
||||
assert_eq!(fw.os.vm().active_pc(), pc);
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
assert!(matches!(fw.state, FirmwareState::HubHome(_)));
|
||||
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lifecycle_resume_failure_blocks_gameplay_and_conflicting_pause_request() {
|
||||
let (mut fw, mut platform, task) = load_lifecycle("RET", "FRAME_SYNC\nRET");
|
||||
fw.os.lifecycle().suspend_task(task).unwrap();
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
assert!(fw.resume_resident_game_from_home());
|
||||
assert!(fw.os.lifecycle().request_home_from_game(task).is_err());
|
||||
assert!(fw.os.lifecycle().suspend_task(task).is_err());
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
let FirmwareState::AppCrashes(step) = &fw.state else { panic!("expected failure") };
|
||||
assert!(step.report.to_string().contains("BeforeResume"));
|
||||
assert_eq!(vm_session_tick_index(&mut fw, task), 0);
|
||||
}
|
||||
#[test]
|
||||
fn lifecycle_roles_are_independently_optional() {
|
||||
for (pause, resume) in [("", "RET"), ("RET", "")] {
|
||||
let (mut fw, mut platform, task) = load_lifecycle(pause, resume);
|
||||
fw.request_home_from_host();
|
||||
for _ in 0..2 {
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
}
|
||||
assert_eq!(fw.os.lifecycle().task_state(task), Some(TaskState::Suspended));
|
||||
assert!(fw.resume_resident_game_from_home());
|
||||
fw.tick(&InputSignals::default(), &mut platform);
|
||||
assert_eq!(
|
||||
fw.os.lifecycle().resident_game().unwrap().state,
|
||||
ResidentGameState::Foreground
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -27,6 +27,15 @@ impl GameRunningStep {
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
};
|
||||
|
||||
if matches!(task_state, TaskState::Suspended | TaskState::Closed) {
|
||||
ctx.os.vm().transition_render_owner(AppMode::Shell, 0);
|
||||
return Some(match ctx.os.lifecycle().foreground_owner() {
|
||||
prometeu_system::ForegroundOwner::Shell(task_id) => FirmwareState::ShellRunning(
|
||||
crate::firmware::firmware_state::ShellRunningStep::new(task_id),
|
||||
),
|
||||
_ => FirmwareState::HubHome(HubHomeStep),
|
||||
});
|
||||
}
|
||||
if task_state != TaskState::Foreground {
|
||||
// TODO: is it panic?
|
||||
let report = CrashReport::VmPanic {
|
||||
|
||||
Reference in New Issue
Block a user