feat(runtime): add optional pause and resume lifecycle hooks
Intrepid/Prometeu/Runtime/pipeline/pr-master Build started...

This commit is contained in:
2026-10-13 12:18:18 +01:00
parent 23dc6fc66d
commit 0af8b2b1fe
39 changed files with 1381 additions and 70 deletions
@@ -37,6 +37,9 @@ impl LoadCode {
}
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub enum LoadReason {
LifecycleRole,
LifecycleSignature,
DuplicateLifecycleRole,
Magic,
Version,
Endianness,
@@ -57,8 +57,30 @@ pub struct TypeDecl {
pub name: Option<String>,
pub kind: TypeKind,
}
/// Runtime-owned roles; frontend names and FunctionIds are independent.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
#[repr(u8)]
pub enum LifecycleRole {
#[default]
None = 0,
BeforePause = 1,
BeforeResume = 2,
}
impl TryFrom<u8> for LifecycleRole {
type Error = E;
fn try_from(value: u8) -> Result<Self, E> {
match value {
0 => Ok(Self::None),
1 => Ok(Self::BeforePause),
2 => Ok(Self::BeforeResume),
_ => Err(E::new(C::InvalidRegistry, R::LifecycleRole)),
}
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FunctionDecl {
pub lifecycle_role: LifecycleRole,
pub name: Option<String>,
pub signature: Signature,
pub code_offset: u32,
@@ -232,6 +254,7 @@ pub struct FunctionLayout {
#[derive(Debug)]
pub struct Registry {
lifecycle_hooks: [Option<FunctionId>; 2],
declarations: RegistryDeclarations,
layouts: Vec<TypeLayout>,
functions: Vec<FunctionLayout>,
@@ -239,6 +262,13 @@ pub struct Registry {
implementations: Vec<(TypeId, TypeId, ImplementationId)>,
}
impl Registry {
pub fn lifecycle_hook(&self, role: LifecycleRole) -> Option<FunctionId> {
match role {
LifecycleRole::None => None,
LifecycleRole::BeforePause => self.lifecycle_hooks[0],
LifecycleRole::BeforeResume => self.lifecycle_hooks[1],
}
}
pub fn declarations(&self) -> &RegistryDeclarations {
&self.declarations
}
@@ -346,10 +376,31 @@ impl Registry {
});
}
}
let mut lifecycle_hooks = [None; 2];
let mut functions = b.vector(d.functions.len(), Q::RegistryBytes)?;
let mut ranges = b.vector(d.functions.len(), Q::TemporaryBytes)?;
for (i, f) in d.functions.iter().enumerate() {
b.work(1)?;
if f.lifecycle_role != LifecycleRole::None {
let invalid = i == 0
|| !f.signature.parameters.is_empty()
|| !f.signature.results.is_empty()
|| !f.captures.is_empty();
if invalid {
return Err(E::new(C::InvalidEntrypoint, R::LifecycleSignature)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
let slot = &mut lifecycle_hooks[f.lifecycle_role as usize - 1];
if slot.replace(FunctionId(i as u32)).is_some() {
return Err(E::new(C::InvalidRegistry, R::DuplicateLifecycleRole)
.in_section(1)
.record(i as u32)
.in_function(i as u32, None));
}
}
let params = width(f.signature.parameters.iter().map(|p| p.type_id), &layouts, b)?;
let results = width(f.signature.results.iter().copied(), &layouts, b)?;
let frame = u64::from(params) + u64::from(f.local_slots) + u64::from(f.max_stack_slots);
@@ -459,7 +510,7 @@ impl Registry {
.record(pair[1].2 .0));
}
}
Ok(Self { declarations: d, layouts, functions, implementations })
Ok(Self { lifecycle_hooks, declarations: d, layouts, functions, implementations })
}
}
fn overflow() -> E {
@@ -249,11 +249,14 @@ impl<'a, 'b> Reader<'a, 'b> {
Ok(out)
}
fn functions(mut self) -> Result<Vec<FunctionDecl>, E> {
let (mut out, n) = self.list(Q::Functions, 25)?;
let (mut out, n) = self.list(Q::Functions, 26)?;
for i in 0..n {
self.budget.work(1)?;
let f = (|| {
Ok(FunctionDecl {
lifecycle_role: LifecycleRole::try_from(self.byte()?).map_err(|e| {
e.at(1, self.section.offset + self.pos - 1).in_function(i as u32, None)
})?,
name: self.name()?,
signature: self.signature()?,
code_offset: self.u32()?,
@@ -407,6 +410,7 @@ pub fn encode_registry(registry: &Registry, b: &mut LoadBudget) -> Result<Regist
let functions = write_section(b, |w| {
w.count(d.functions.len())?;
for f in &d.functions {
w.byte(f.lifecycle_role as u8)?;
w.name(&f.name)?;
w.signature(&f.signature)?;
w.u32(f.code_offset)?;
@@ -129,6 +129,7 @@ fn captures_section_has_independent_bytes_and_strict_shape() {
let r = resolve(RegistryDeclarations {
types: vec![builtin(BuiltinId::INT32), builtin(BuiltinId::VEC2)],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_len: 2,
captures: vec![TypeId(1), TypeId(0)],
..Default::default()
@@ -167,22 +168,22 @@ fn hex(s: &str) -> Vec<u8> {
// Independently specified PBX, not generated by any production serializer.
// Header 32 bytes, eight directory entries (96 bytes), payload starts at 128.
// constants=128/4, functions=132/29, code=161/2, exports=163/4,
// syscalls=167/4, types=171/10, implementations=181/4. Total=193.
// constants=128/4, functions=132/30, code=162/2, exports=164/4,
// syscalls=168/4, types=172/10, implementations=182/4, captures=186/8. Total=194.
fn minimal_bytes() -> Vec<u8> {
hex("
50 42 58 00 01 00 00 00 08 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 80 00 00 00 04 00 00 00
01 00 00 00 84 00 00 00 1d 00 00 00
02 00 00 00 a1 00 00 00 02 00 00 00
04 00 00 00 a3 00 00 00 04 00 00 00
05 00 00 00 a7 00 00 00 04 00 00 00
06 00 00 00 ab 00 00 00 0a 00 00 00
07 00 00 00 b5 00 00 00 04 00 00 00
08 00 00 00 b9 00 00 00 08 00 00 00
01 00 00 00 84 00 00 00 1e 00 00 00
02 00 00 00 a2 00 00 00 02 00 00 00
04 00 00 00 a4 00 00 00 04 00 00 00
05 00 00 00 a8 00 00 00 04 00 00 00
06 00 00 00 ac 00 00 00 0a 00 00 00
07 00 00 00 b6 00 00 00 04 00 00 00
08 00 00 00 ba 00 00 00 08 00 00 00
00 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 02 00 00 00 00 00 00 00 00 00 00 00
01 00
00 00 00 00
@@ -194,7 +195,11 @@ fn minimal_bytes() -> Vec<u8> {
fn minimal_registry() -> Registry {
resolve(RegistryDeclarations {
types: vec![builtin(BuiltinId::BOOL)],
functions: vec![FunctionDecl { code_len: 2, ..Default::default() }],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_len: 2,
..Default::default()
}],
..Default::default()
})
.unwrap()
@@ -225,10 +230,10 @@ fn writer_matches_independent_minimal_envelope() {
let sections = encode_registry(&minimal_registry(), &mut budget()).unwrap();
let bytes = envelope(&sections.types, &sections.functions, &sections.implementations);
assert_eq!(bytes, minimal_bytes());
assert_eq!(bytes.len(), 193);
assert_eq!(bytes.len(), 194);
let mut b = budget();
let env = PbxEnvelope::parse(&bytes, &mut b).unwrap();
assert_eq!(env.section(2).unwrap().offset, 161);
assert_eq!(env.section(2).unwrap().offset, 162);
let registry = env.resolve_registry(&mut b).unwrap();
assert_eq!(registry.declarations(), minimal_registry().declarations());
assert_eq!(b.used(LoadResource::TemporaryBytes), 0);
@@ -499,7 +504,7 @@ fn representative_records_match_fixed_bytes_and_preserve_names_without_debug() {
01 00 00 00 00 00 00 00 01 01 00 00 00 70
01 00 00 00 00 00 00 00");
let functions = hex("
01 00 00 00 01 01 00 00 00 66
01 00 00 00 00 01 01 00 00 00 66
02 00 00 00 01 00 00 00 00 00 00 00 00 01 01 00 00 00 70
01 00 00 00 00 00 00 00
00 00 00 00 02 00 00 00 00 00 00 00 01 00 00 00");
@@ -721,6 +726,7 @@ fn implemented() -> RegistryDeclarations {
},
],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
signature: Signature { parameters: vec![named(1), named(0)], results: vec![TypeId(0)] },
code_len: 2,
max_stack_slots: 2,
@@ -1024,7 +1030,7 @@ fn reference_map_probe() {
fn independent_multi_slot_signature_fixture_has_no_serialized_widths() {
// vec2 import; fn(vec2)->vec2; GET_LOCAL 0; GET_LOCAL 1; RET.
let types = hex("01 00 00 00 00 00 02 00 00 00");
let functions=hex("01 00 00 00 00 01 00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 0e 00 00 00 00 00 00 00 02 00 00 00");
let functions=hex("01 00 00 00 00 00 01 00 00 00 00 00 00 00 00 01 00 00 00 00 00 00 00 00 00 00 00 0e 00 00 00 00 00 00 00 02 00 00 00");
let code = hex("42 00 00 00 00 00 42 00 01 00 00 00 51 00");
let empty = [0; 4];
let bytes = encode_envelope(
@@ -1055,3 +1061,70 @@ fn independent_multi_slot_signature_fixture_has_no_serialized_widths() {
assert_eq!(sections.functions, functions);
assert_eq!(sections.types, types);
}
#[test]
fn lifecycle_roles_resolve_and_roundtrip_with_strict_validation() {
let functions = vec![
FunctionDecl { code_len: 2, ..Default::default() },
FunctionDecl {
lifecycle_role: LifecycleRole::BeforePause,
code_offset: 2,
code_len: 2,
..Default::default()
},
FunctionDecl {
lifecycle_role: LifecycleRole::BeforeResume,
code_offset: 4,
code_len: 2,
..Default::default()
},
];
let declarations = RegistryDeclarations {
types: vec![builtin(BuiltinId::BOOL)],
functions,
..Default::default()
};
let registry = resolve(declarations.clone()).unwrap();
assert_eq!(registry.lifecycle_hook(LifecycleRole::None), None);
assert_eq!(registry.lifecycle_hook(LifecycleRole::BeforePause), Some(FunctionId(1)));
assert_eq!(registry.lifecycle_hook(LifecycleRole::BeforeResume), Some(FunctionId(2)));
let bytes = PbxModule {
registry: &registry,
code: &[1, 0, 1, 0, 1, 0],
constants: &[],
debug: None,
exports: &[],
syscalls: &[],
}
.serialize(&mut budget())
.unwrap();
let parsed = OwnedPbx::parse(&bytes, &mut budget()).unwrap();
assert_eq!(parsed.registry.declarations(), &declarations);
let env = PbxEnvelope::parse(&bytes, &mut budget()).unwrap();
let role_offset = env.section(1).unwrap().offset + 4;
let mut invalid = bytes.clone();
invalid[role_offset] = 255;
let error = OwnedPbx::parse(&invalid, &mut budget()).unwrap_err();
assert_eq!(error.reason, LoadReason::LifecycleRole);
assert_eq!(error.function, Some(0));
assert_eq!(error.offset, Some(role_offset));
for case in 0..5 {
let mut d = declarations.clone();
match case {
0 => d.functions[0].lifecycle_role = LifecycleRole::BeforePause,
1 => d.functions[2].lifecycle_role = LifecycleRole::BeforePause,
2 => d.functions[1].signature.parameters.push(named(0)),
3 => d.functions[1].signature.results.push(TypeId(0)),
_ => d.functions[1].captures.push(TypeId(0)),
}
let error = resolve(d).unwrap_err();
assert_eq!(
error.reason,
if case == 1 {
LoadReason::DuplicateLifecycleRole
} else {
LoadReason::LifecycleSignature
}
);
}
}
@@ -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 {
@@ -9,6 +9,7 @@ use crate::services::foreground::{
ForegroundOwner, ForegroundStackError, ResidentGame, ResidentGameState,
};
use crate::task::{TaskId, TaskKind, TaskState};
use crate::vm_session::LifecycleTransition;
pub struct LifecycleFacade<'a> {
pub(in crate::os) os: &'a mut SystemOS,
@@ -45,6 +46,27 @@ impl<'a> LifecycleFacade<'a> {
});
}
if self
.os
.vm_sessions
.for_task(task_id)
.is_some_and(|session| session.lifecycle_transition.is_some())
{
return Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::SetForeground,
});
}
if self.task_state(task_id) == Some(TaskState::Suspended)
&& self.os.vm_sessions.for_task(task_id).is_some_and(|session| {
session
.vm
.has_lifecycle_hook(prometeu_bytecode::registry::LifecycleRole::BeforeResume)
})
{
return self.resume_task(task_id);
}
self.os.foreground_stack.set_game_foreground(task_id).map_err(map_foreground_error)?;
self.os.task_manager.set_foreground(task_id);
self.os.process_manager.mark_running(process_id);
@@ -67,6 +89,9 @@ impl<'a> LifecycleFacade<'a> {
&& game_task_id != task_id
&& self.task_state(game_task_id) != Some(TaskState::Suspended)
{
if self.defer_pause(game_task_id, LifecycleTransition::PauseToShell(task_id))? {
return Ok(());
}
let game_process_id = process_id_for_task(self.os, game_task_id)?;
self.os.task_manager.mark_suspended(game_task_id);
self.os.process_manager.mark_suspended(game_process_id);
@@ -93,6 +118,19 @@ impl<'a> LifecycleFacade<'a> {
pub fn request_home_from_game(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let _process_id = process_id_for_task(self.os, task_id)?;
if let Some(pending) =
self.os.vm_sessions.for_task(task_id).and_then(|s| s.lifecycle_transition)
{
return if pending == LifecycleTransition::PauseToHub {
Ok(())
} else {
Err(LifecycleError::InvalidTransition {
task_id,
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
operation: LifecycleOperation::Suspend,
})
};
}
let previous = self.os.foreground_stack.resident_game();
self.os
@@ -113,6 +151,13 @@ impl<'a> LifecycleFacade<'a> {
}
pub fn advance_game_pause_budget(&mut self, task_id: TaskId) -> Result<bool, LifecycleError> {
if self.os.foreground_stack.resident_game().is_some_and(|game| {
game.task_id == task_id
&& game.state == ResidentGameState::PauseRequested { remaining_ticks: 1 }
}) && self.defer_pause(task_id, LifecycleTransition::PauseToHub)?
{
return Ok(false);
}
let expired =
self.os.foreground_stack.advance_pause_budget(task_id).map_err(map_foreground_error)?;
@@ -125,6 +170,34 @@ impl<'a> LifecycleFacade<'a> {
Ok(expired)
}
fn defer_pause(
&mut self,
task_id: TaskId,
transition: LifecycleTransition,
) -> Result<bool, LifecycleError> {
let state = self.task_state(task_id).unwrap_or(TaskState::Closed);
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
return Ok(false);
};
if let Some(pending) = session.lifecycle_transition {
return if pending == transition {
Ok(true)
} else {
Err(LifecycleError::InvalidTransition {
task_id,
from: state,
operation: LifecycleOperation::Suspend,
})
};
}
if session.pause_hook_complete || !session.vm.has_lifecycle_hook(transition.role()) {
return Ok(false);
}
session.lifecycle_transition = Some(transition);
session.lifecycle_started = false;
Ok(true)
}
pub fn pending_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
&self.os.game_lifecycle_events
}
@@ -141,6 +214,11 @@ impl<'a> LifecycleFacade<'a> {
pub fn suspend_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
let process_id = process_id_for_task(self.os, task_id)?;
if task_kind_for_task(self.os, task_id)? == TaskKind::Game
&& self.defer_pause(task_id, LifecycleTransition::PauseToHub)?
{
return Ok(());
}
self.os.task_manager.mark_suspended(task_id);
self.os.process_manager.mark_suspended(process_id);
match self.os.foreground_stack.owner() {
@@ -189,6 +267,16 @@ impl<'a> LifecycleFacade<'a> {
task_id,
kind: GameLifecycleEventKind::ResumeForeground,
});
if let Some(session) = self.os.vm_sessions.for_task_mut(task_id) {
session.pause_hook_complete = false;
if session.vm.has_lifecycle_hook(
prometeu_bytecode::registry::LifecycleRole::BeforeResume,
) {
session.lifecycle_transition = Some(LifecycleTransition::Resume);
session.lifecycle_started = false;
return Ok(());
}
}
self.os
.foreground_stack
.complete_resume_game(task_id)
@@ -1,7 +1,7 @@
use crate::CrashReport;
use crate::os::{GameLifecycleEvent, SystemOS};
use crate::task::TaskId;
use crate::vm_session::VmSession;
use crate::vm_session::{LifecycleTransition, VmSession};
use crate::{RenderWorkerConfig, RenderWorkerController};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame};
@@ -9,6 +9,7 @@ use prometeu_hal::{
FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError,
RenderWorkerFrameSink, RuntimePlatform,
};
use prometeu_vm::LogicalFrameEndingReason;
use std::sync::atomic::Ordering;
pub struct VmFacade<'a> {
@@ -22,6 +23,12 @@ impl<'a> VmFacade<'a> {
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if self.os.lifecycle().task_state(task_id) != Some(crate::task::TaskState::Foreground) {
return None;
}
if self.os.vm_sessions.for_task(task_id).is_some_and(|s| s.lifecycle_transition.is_some()) {
return self.drive_lifecycle(task_id, platform, false).err();
}
self.deliver_pending_game_lifecycle_events_to_session(task_id);
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
@@ -44,6 +51,104 @@ impl<'a> VmFacade<'a> {
)
}
/// Firmware polls this before dispatching ordinary Game/Shell updates.
pub fn poll_pending_lifecycle(
&mut self,
platform: &mut dyn RuntimePlatform,
) -> Option<(TaskId, Result<(), CrashReport>)> {
let task_id = self.os.foreground_stack.resident_game_task()?;
self.os.vm_sessions.for_task(task_id)?.lifecycle_transition?;
Some((task_id, self.drive_lifecycle(task_id, platform, false)))
}
fn drive_lifecycle(
&mut self,
task_id: TaskId,
platform: &mut dyn RuntimePlatform,
single_step: bool,
) -> Result<(), CrashReport> {
self.deliver_pending_game_lifecycle_events_to_session(task_id);
let session = self.os.vm_sessions.for_task_mut(task_id).expect("pending lifecycle session");
let transition = session.lifecycle_transition.expect("pending lifecycle transition");
let role = transition.role();
// A fatal hook remains failed even if a caller tries to tick the same session again.
if let Some(report) = &session.runtime.last_crash_report {
return Err(report.clone());
}
let reason = if !session.lifecycle_started {
session.lifecycle_started = true;
match session.vm.begin_lifecycle(role) {
Ok(true) => None,
Ok(false) => Some(LogicalFrameEndingReason::LifecycleComplete),
Err(error) => Some(LogicalFrameEndingReason::Panic(format!("{error:?}"))),
}
} else {
None
};
let reason = reason.unwrap_or_else(|| {
session.runtime.tick_lifecycle(
&mut self.os.log_service,
&mut self.os.fs,
&mut session.fs_state,
&mut self.os.memcard,
&mut session.open_files,
&mut session.next_handle,
&mut session.vm,
platform,
single_step,
)
});
match reason {
LogicalFrameEndingReason::BudgetExhausted | LogicalFrameEndingReason::Breakpoint => {
Ok(())
}
LogicalFrameEndingReason::LifecycleComplete => {
session.lifecycle_transition = None;
session.lifecycle_started = false;
match transition {
LifecycleTransition::PauseToHub => {
session.pause_hook_complete = true;
self.os.lifecycle().suspend_task(task_id).expect("validated suspension");
}
LifecycleTransition::PauseToShell(shell) => {
session.pause_hook_complete = true;
self.os
.lifecycle()
.set_shell_foreground_task(shell)
.expect("validated Shell transition");
}
LifecycleTransition::Resume => {
self.os
.foreground_stack
.complete_resume_game(task_id)
.expect("validated resume");
}
}
Ok(())
}
LogicalFrameEndingReason::Halted => {
// HALT ends the session; it must never restore or resume gameplay.
session.lifecycle_transition = None;
self.os.lifecycle().close_task(task_id).expect("validated task");
Ok(())
}
failure => {
let report = match failure {
LogicalFrameEndingReason::Trap(mut trap) => {
trap.message = format!("{role:?}: {}", trap.message);
CrashReport::VmTrap { trap }
}
other => CrashReport::VmPanic {
message: format!("{role:?} lifecycle failed: {other:?}"),
pc: Some(session.vm.pc() as u32),
},
};
session.runtime.last_crash_report = Some(report.clone());
Err(report)
}
}
}
fn deliver_pending_game_lifecycle_events_to_session(&mut self, task_id: TaskId) {
let Some(session) = self.os.vm_sessions.for_task(task_id) else {
return;
@@ -85,6 +190,12 @@ impl<'a> VmFacade<'a> {
pc: None,
});
};
if self.os.lifecycle().task_state(task_id) != Some(crate::task::TaskState::Foreground) {
return None;
}
if self.os.vm_sessions.for_task(task_id).is_some_and(|s| s.lifecycle_transition.is_some()) {
return self.drive_lifecycle(task_id, platform, true).err();
}
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
return Some(CrashReport::VmPanic {
message: format!("active debug task {:?} has no VM session", task_id),
@@ -101,6 +101,7 @@ fn serialized_single_function_module_with_consts(
TestProgram {
const_pool,
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
@@ -105,7 +105,8 @@ impl VirtualMachineRuntime {
match step_result {
Ok(())
| Err(
LogicalFrameEndingReason::FrameSync
LogicalFrameEndingReason::LifecycleComplete
| LogicalFrameEndingReason::FrameSync
| LogicalFrameEndingReason::BudgetExhausted
| LogicalFrameEndingReason::Halted
| LogicalFrameEndingReason::EndOfRom
@@ -138,6 +139,55 @@ impl VirtualMachineRuntime {
}
}
/// Uses the session's real services, outside logical-frame accounting.
#[allow(clippy::too_many_arguments)]
pub(crate) fn tick_lifecycle(
&mut self,
log_service: &mut LogService,
fs: &mut VirtualFS,
fs_state: &mut FsState,
memcard: &mut MemcardService,
open_files: &mut HashMap<u32, String>,
next_handle: &mut u32,
vm: &mut VirtualMachine,
platform: &mut dyn RuntimePlatform,
single_step: bool,
) -> LogicalFrameEndingReason {
if self.paused && !single_step && !self.debug_step_request {
return LogicalFrameEndingReason::Breakpoint;
}
let result = catch_unwind(AssertUnwindSafe(|| {
let mut ctx = HostContext::new_platform(Some(platform));
let mut host = VmRuntimeHost {
runtime: self,
log_service,
fs,
fs_state,
memcard,
open_files,
next_handle,
};
if single_step {
vm.step(&mut host, &mut ctx)
.err()
.unwrap_or(LogicalFrameEndingReason::BudgetExhausted)
} else {
vm.run_budget(VirtualMachine::LIFECYCLE_SLICE, &mut host, &mut ctx)
.map(|report| report.reason)
.unwrap_or_else(LogicalFrameEndingReason::Panic)
}
}));
let reason = result.unwrap_or_else(|payload| {
LogicalFrameEndingReason::Panic(Self::host_panic_payload_to_string(payload))
});
if reason == LogicalFrameEndingReason::Breakpoint || single_step || self.debug_step_request
{
self.paused = true;
self.debug_step_request = false;
}
reason
}
#[allow(clippy::too_many_arguments)]
pub fn tick(
&mut self,
@@ -20,7 +20,27 @@ pub enum VmSessionError {
ProcessIsNotVmBacked(ProcessId),
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum LifecycleTransition {
PauseToHub,
PauseToShell(TaskId),
Resume,
}
impl LifecycleTransition {
pub(crate) fn role(self) -> prometeu_bytecode::registry::LifecycleRole {
use prometeu_bytecode::registry::LifecycleRole;
match self {
Self::Resume => LifecycleRole::BeforeResume,
_ => LifecycleRole::BeforePause,
}
}
}
pub struct VmSession {
pub(crate) lifecycle_transition: Option<LifecycleTransition>,
pub(crate) lifecycle_started: bool,
pub(crate) pause_hook_complete: bool,
pub id: VmSessionId,
pub task_id: TaskId,
pub process_id: ProcessId,
@@ -45,6 +65,9 @@ impl VmSession {
logs_count: Arc<AtomicU32>,
) -> Self {
Self {
lifecycle_transition: None,
lifecycle_started: false,
pause_hook_complete: false,
id: VmSessionId(task.id),
task_id: task.id,
process_id: process.id,
@@ -25,6 +25,7 @@ fn fixture(
kind: TypeKind::Builtin(BuiltinId::BOOL),
}],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
name: Some("boot".into()),
code_len: code.len() as u32,
max_stack_slots: max,
@@ -38,7 +38,12 @@ fn registry(code: &[u8], functions: Vec<FunctionDecl>) -> Registry {
.unwrap()
}
fn function(code: &[u8]) -> FunctionDecl {
FunctionDecl { code_len: code.len() as u32, max_stack_slots: 4, ..Default::default() }
FunctionDecl {
lifecycle_role: Default::default(),
code_len: code.len() as u32,
max_stack_slots: 4,
..Default::default()
}
}
fn check(code: &[u8], registry: &Registry) -> Result<(), E> {
validate_registry_instructions(code, registry, 1, &mut LoadBudget::new(Default::default()))
@@ -53,7 +58,14 @@ fn stack_analysis_honors_literal_zero_and_wide_pop_operands() {
let mut code = vec![];
arg(&mut code, Op::PushI32, 0);
op(&mut code, Op::Halt);
let r = registry(&code, vec![FunctionDecl { max_stack_slots: 0, ..function(&code) }]);
let r = registry(
&code,
vec![FunctionDecl {
lifecycle_role: Default::default(),
max_stack_slots: 0,
..function(&code)
}],
);
let e = stacks(&code, &r).unwrap_err();
assert_eq!(
(e.reason, e.requested, e.limit, e.pc),
@@ -78,6 +90,7 @@ fn stack_analysis_cannot_consume_parameters_or_extra_locals_as_temporaries() {
let r = registry(
&code,
vec![FunctionDecl {
lifecycle_role: Default::default(),
local_slots: 100,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(1), name: None }],
@@ -112,8 +125,14 @@ fn stack_analysis_resolves_multislot_calls_and_registry_operations() {
let r = registry(
&code,
vec![
FunctionDecl { code_len: callee as u32, max_stack_slots: 2, ..function(&code) },
FunctionDecl {
lifecycle_role: Default::default(),
code_len: callee as u32,
max_stack_slots: 2,
..function(&code)
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: callee as u32,
code_len: (code.len() - callee) as u32,
signature,
@@ -136,6 +155,7 @@ fn stack_analysis_checks_returns_empty_bodies_and_implicit_end_branches() {
op(&mut code, operation);
}
let f = FunctionDecl {
lifecycle_role: Default::default(),
signature: Signature { parameters: vec![], results: vec![TypeId(0)] },
..function(&code)
};
@@ -172,7 +192,14 @@ fn stack_analysis_rejects_different_join_heights_and_accepts_a_bounded_loop() {
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::StackJoin);
let mut code = vec![];
arg(&mut code, Op::Jmp, 0);
let r = registry(&code, vec![FunctionDecl { max_stack_slots: 0, ..function(&code) }]);
let r = registry(
&code,
vec![FunctionDecl {
lifecycle_role: Default::default(),
max_stack_slots: 0,
..function(&code)
}],
);
assert!(stacks(&code, &r).is_ok());
}
@@ -181,7 +208,14 @@ fn stack_analysis_accounts_only_reachable_transfers_but_preflights_dead_operands
let mut code = vec![];
op(&mut code, Op::Halt);
arg(&mut code, Op::PopN, u32::MAX);
let r = registry(&code, vec![FunctionDecl { max_stack_slots: 0, ..function(&code) }]);
let r = registry(
&code,
vec![FunctionDecl {
lifecycle_role: Default::default(),
max_stack_slots: 0,
..function(&code)
}],
);
assert!(stacks(&code, &r).is_ok());
let mut code = vec![];
op(&mut code, Op::Halt);
@@ -220,7 +254,12 @@ fn stack_analysis_straight_line_storage_is_bounded_by_blocks_not_instruction_fra
op(&mut code, Op::Halt);
let r = registry(
&code,
vec![FunctionDecl { local_slots: 300, max_stack_slots: 0, ..function(&code) }],
vec![FunctionDecl {
lifecycle_role: Default::default(),
local_slots: 300,
max_stack_slots: 0,
..function(&code)
}],
);
let limits = LoadLimits { temporary_bytes: 41_000, ..Default::default() };
let mut b = LoadBudget::new(limits);
@@ -232,6 +271,7 @@ fn stack_analysis_straight_line_storage_is_bounded_by_blocks_not_instruction_fra
fn stack_analysis_accepts_unknown_fn_targets_and_rejects_removed_opcodes() {
let code = prometeu_bytecode::assemble("GET_LOCAL 0\nCALL_CLOSURE 4\nHALT").unwrap();
let f = FunctionDecl {
lifecycle_role: Default::default(),
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(4), name: None }],
results: vec![],
@@ -263,12 +303,19 @@ fn expected_fn_signature_checks_argument_height_after_permutations() {
&code,
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_len: end as u32,
local_slots: 1,
max_stack_slots: 2,
..function(&code)
},
FunctionDecl { signature, code_offset: end as u32, code_len: 2, ..Default::default() },
FunctionDecl {
lifecycle_role: Default::default(),
signature,
code_offset: end as u32,
code_len: 2,
..Default::default()
},
],
);
assert_eq!(stacks(&code, &r).unwrap_err().reason, R::StackUnderflow);
@@ -309,12 +356,14 @@ fn stack_analysis_charges_work_for_loop_reprocessing_and_refunds_on_exhaustion()
&code,
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_len: end as u32,
local_slots: 1,
max_stack_slots: 1,
..function(&code)
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: end as u32,
code_len: (code.len() - end) as u32,
max_stack_slots: 1,
@@ -353,8 +402,13 @@ fn typed_opcodes_and_relative_jumps_are_resolved_in_declared_ranges() {
let r = registry(
&code,
vec![
FunctionDecl { code_len: start as u32, ..function(&code) },
FunctionDecl {
lifecycle_role: Default::default(),
code_len: start as u32,
..function(&code)
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: start as u32,
code_len: 6,
max_stack_slots: 0,
@@ -394,8 +448,13 @@ fn jumps_reject_cross_range_and_mid_instruction_even_when_unreachable() {
let r = registry(
&code,
vec![
FunctionDecl { code_len: 6, ..function(&code) },
FunctionDecl { code_offset: 6, code_len: 2, ..function(&code) },
FunctionDecl { lifecycle_role: Default::default(), code_len: 6, ..function(&code) },
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 6,
code_len: 2,
..function(&code)
},
],
);
let e = check(&code, &r).unwrap_err();
@@ -479,7 +538,10 @@ fn spawn_arity_does_not_truncate_and_closure_function_ids_are_checked() {
#[test]
fn declared_range_is_not_extended_into_gaps_or_neighbor_functions() {
let code = vec![Op::Halt as u8, 0, 0xff, 0xff];
let r = registry(&code, vec![FunctionDecl { code_len: 2, ..function(&code) }]);
let r = registry(
&code,
vec![FunctionDecl { lifecycle_role: Default::default(), code_len: 2, ..function(&code) }],
);
assert!(check(&code, &r).is_ok()); // Unowned gap is outside this phase's ranges.
let r = registry(&code, vec![function(&code)]);
assert_eq!(check(&code, &r).unwrap_err().reason, R::UnknownOpcode);
@@ -493,8 +555,13 @@ fn scratch_is_refunded_per_function_and_preserves_prior_load_ownership() {
let r = registry(
&code,
vec![
FunctionDecl { code_len: 2, ..function(&code) },
FunctionDecl { code_offset: 2, code_len: 2, ..function(&code) },
FunctionDecl { lifecycle_role: Default::default(), code_len: 2, ..function(&code) },
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 2,
code_len: 2,
..function(&code)
},
],
);
let limits = LoadLimits { temporary_bytes: 8, ..Default::default() };
@@ -531,8 +598,13 @@ fn truncated_immediates_cannot_borrow_bytes_from_the_next_function() {
let r = registry(
&code,
vec![
FunctionDecl { code_len: 2, ..function(&code) },
FunctionDecl { code_offset: 2, code_len: 2, ..function(&code) },
FunctionDecl { lifecycle_role: Default::default(), code_len: 2, ..function(&code) },
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 2,
code_len: 2,
..function(&code)
},
],
);
let e = check(&code, &r).unwrap_err();
@@ -32,6 +32,7 @@ fn function(
max: u32,
) -> FunctionDecl {
FunctionDecl {
lifecycle_role: Default::default(),
captures: vec![],
code_offset: offset as u32,
code_len: len as u32,
@@ -7,6 +7,7 @@ mod collections_tests;
mod control;
mod dynamic;
mod gc;
mod lifecycle;
mod loader;
mod random;
mod reference;
@@ -49,6 +50,8 @@ use prometeu_test_support::program::{TestProgram, int64_signature};
pub enum LogicalFrameEndingReason {
/// Execution reached a `FRAME_SYNC` instruction, marking the end of the logical frame.
FrameSync,
/// The outer lifecycle callback returned; gameplay has not resumed.
LifecycleComplete,
/// The cycle budget for the current host tick was exhausted before reaching `FRAME_SYNC`.
BudgetExhausted,
/// A `HALT` instruction was executed, terminating the program.
@@ -109,6 +112,8 @@ pub struct VirtualMachine {
cycles: u64,
/// Stop flag: true if a `HALT` opcode was encountered.
halted: bool,
lifecycle: Option<lifecycle::LifecycleCall>,
lifecycle_failure: Option<LogicalFrameEndingReason>,
/// Set of ROM addresses used for software breakpoints in the debugger.
breakpoints: std::collections::HashSet<usize>,
/// GC: number of newly allocated live objects threshold to trigger a collection at safepoint.
@@ -229,6 +234,8 @@ impl VirtualMachine {
heap: Heap::with_budget(&budget),
cycles: 0,
halted: true,
lifecycle: None,
lifecycle_failure: None,
breakpoints: std::collections::HashSet::new(),
gc_alloc_threshold: 1024, // conservative default; tests may override
last_gc_live_count: 0,
@@ -257,7 +264,7 @@ impl VirtualMachine {
/// 1. Fetch: Read the opcode from memory.
/// 2. Decode: Identify what operation to perform.
/// 3. Execute: Perform the operation, updating stacks, memory, or calling peripherals.
pub fn step(
fn step_inner(
&mut self,
native: &mut dyn NativeInterface,
ctx: &mut HostContext,
@@ -1039,6 +1046,14 @@ impl VirtualMachine {
return self.execute_collection(opcode, ty, field, start_pc as u32);
}
OpCode::FrameSync => {
if self.lifecycle.is_some() {
return Err(self.trap(
TRAP_TYPE,
opcode as u16,
"FRAME_SYNC is forbidden in lifecycle hooks".into(),
start_pc as u32,
));
}
// Marks the logical end of a frame: consume cycles and signal to the driver
self.cycles += OpCode::FrameSync.cycles();
self.handle_safepoint()
@@ -1152,7 +1167,11 @@ mod tests {
typed_test_vm(
code,
constant_pool,
vec![FunctionDecl { max_stack_slots: 256, ..Default::default() }],
vec![FunctionDecl {
lifecycle_role: Default::default(),
max_stack_slots: 256,
..Default::default()
}],
)
}
fn limited_session(code: Vec<u8>, limits: RuntimeLimits) -> VirtualMachine {
@@ -1196,6 +1215,7 @@ mod tests {
TestProgram {
const_pool: vec![],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
@@ -1511,8 +1531,13 @@ mod tests {
rom,
vec![],
vec![
FunctionDecl { max_stack_slots: 256, ..Default::default() },
FunctionDecl {
lifecycle_role: Default::default(),
max_stack_slots: 256,
..Default::default()
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: func_addr as u32,
signature: int64_signature(1, 1),
max_stack_slots: 256,
@@ -1593,8 +1618,13 @@ mod tests {
rom2,
vec![],
vec![
FunctionDecl { max_stack_slots: 256, ..Default::default() },
FunctionDecl {
lifecycle_role: Default::default(),
max_stack_slots: 256,
..Default::default()
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: func_addr2 as u32,
signature: int64_signature(0, 1),
max_stack_slots: 256,
@@ -1834,6 +1864,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -2449,6 +2480,7 @@ mod tests {
let header = TestProgram {
const_pool: vec![],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
@@ -2964,6 +2996,7 @@ mod tests {
vec![],
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f0_start as u32,
signature: scalar_signature(0, 0, 1),
@@ -2974,6 +3007,7 @@ mod tests {
local_slots: 0,
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f1_start,
signature: scalar_signature(2, 1, 1),
@@ -3025,6 +3059,7 @@ mod tests {
vec![],
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f0_start as u32,
signature: scalar_signature(0, 0, 1),
@@ -3035,6 +3070,7 @@ mod tests {
local_slots: 0,
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f1_start,
signature: scalar_signature(0, 2, 1),
@@ -3085,6 +3121,7 @@ mod tests {
vec![],
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f0_start as u32,
signature: scalar_signature(0, 0, 1),
@@ -3095,6 +3132,7 @@ mod tests {
local_slots: 0,
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f1_start,
signature: scalar_signature(1, 0, 1),
@@ -3210,6 +3248,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
local_slots: 1,
@@ -3269,6 +3308,7 @@ mod tests {
vec![],
vec![
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f0_start as u32,
signature: scalar_signature(0, 0, 4),
@@ -3279,6 +3319,7 @@ mod tests {
local_slots: 0,
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: f1_start,
local_slots: 1,
@@ -3391,6 +3432,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3439,6 +3481,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3506,6 +3549,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3556,6 +3600,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3606,6 +3651,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -3661,6 +3707,7 @@ mod tests {
rom.clone(),
vec![],
vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
signature: scalar_signature(0, 0, 1),
@@ -0,0 +1,109 @@
//! Bounded calls that retain the suspended guest continuation and its GC roots.
use super::*;
use prometeu_bytecode::registry::LifecycleRole;
pub(super) struct LifecycleCall {
depth: usize,
pc: usize,
halted: bool,
pub(super) remaining: u64,
pub(super) breakpoint: Option<usize>,
}
impl VirtualMachine {
pub const LIFECYCLE_CYCLES: u64 = 1_500_000;
pub const LIFECYCLE_SLICE: u64 = 250_000;
pub fn has_lifecycle_hook(&self, role: LifecycleRole) -> bool {
self.validated_image.as_ref().is_some_and(|i| i.registry().lifecycle_hook(role).is_some())
}
pub fn lifecycle_active(&self) -> bool {
self.lifecycle.is_some()
}
pub fn lifecycle_remaining_cycles(&self) -> Option<u64> {
self.lifecycle.as_ref().map(|call| call.remaining)
}
/// Returns false for an absent role. Entry is transactional with respect to quotas.
pub fn begin_lifecycle(&mut self, role: LifecycleRole) -> Result<bool, VmInitError> {
if self.lifecycle.is_some() || self.lifecycle_failure.is_some() {
return Err(VmInitError::EntrypointNotFound);
}
let Some(id) =
self.validated_image.as_ref().and_then(|i| i.registry().lifecycle_hook(role))
else {
return Ok(false);
};
let func_idx = id.0 as usize;
let callee = &self.program.functions[func_idx];
let locals = callee.local_slots as usize;
let offset = callee.code_offset as usize;
self.budget.check(RuntimeResource::CallDepth, (self.call_stack.len() + 1) as u64)?;
let operands = self.operand_stack.prepare_growth(locals)?;
let frames = self.call_stack.prepare_growth(1)?;
self.operand_stack.commit_growth(operands);
self.call_stack.commit_growth(frames);
let base = self.operand_stack.len();
let call = LifecycleCall {
depth: self.call_stack.len(),
pc: self.pc,
halted: self.halted,
remaining: Self::LIFECYCLE_CYCLES,
breakpoint: None,
};
for _ in 0..locals {
self.operand_stack.push(Value::Null)?;
}
self.call_stack.push(CallFrame {
return_pc: self.pc as u32,
stack_base: base,
func_idx,
closure: None,
})?;
self.lifecycle = Some(call);
self.pc = offset;
self.halted = false;
Ok(true)
}
/// Both the debugger and normal slices pass through the same accounting boundary.
pub fn step(
&mut self,
native: &mut dyn NativeInterface,
ctx: &mut HostContext,
) -> Result<(), LogicalFrameEndingReason> {
if let Some(reason) = &self.lifecycle_failure {
return Err(reason.clone());
}
if let Some(call) = &mut self.lifecycle {
call.breakpoint = None;
}
let before = self.cycles;
let result = self.step_inner(native, ctx);
let Some(call) = self.lifecycle.as_mut() else {
return result;
};
call.remaining = call.remaining.saturating_sub(self.cycles - before);
if result.is_ok() && !self.halted && self.call_stack.len() == call.depth {
let call = self.lifecycle.take().unwrap();
self.pc = call.pc;
self.halted = call.halted;
return Err(LogicalFrameEndingReason::LifecycleComplete);
}
let failure = match result {
Err(reason) => Some(reason),
Ok(()) if self.halted => Some(LogicalFrameEndingReason::Halted),
Ok(()) if call.remaining == 0 => Some(LogicalFrameEndingReason::Panic(
"lifecycle total cycle budget exhausted".into(),
)),
Ok(()) => None,
};
if let Some(reason) = failure {
self.lifecycle_failure = Some(reason.clone());
return Err(reason);
}
Ok(())
}
}
@@ -55,6 +55,9 @@ impl VirtualMachine {
func_idx: usize,
arguments: &[Value],
) -> Result<(), VmInitError> {
if self.lifecycle.is_some() || self.lifecycle_failure.is_some() {
return Err(VmInitError::EntrypointNotFound);
}
#[cfg(not(test))]
if self.validated_image.is_none() {
return Err(VmInitError::EntrypointNotFound);
@@ -7,6 +7,11 @@ impl VirtualMachine {
native: &mut dyn NativeInterface,
ctx: &mut HostContext,
) -> Result<BudgetReport, String> {
if let Some(reason) = &self.lifecycle_failure {
return Ok(BudgetReport { cycles_used: 0, steps_executed: 0, reason: reason.clone() });
}
let budget =
if self.lifecycle.is_some() { budget.min(Self::LIFECYCLE_SLICE) } else { budget };
let start_cycles = self.cycles;
let mut steps_executed = 0;
let mut ending_reason: Option<LogicalFrameEndingReason> = None;
@@ -15,7 +20,13 @@ impl VirtualMachine {
&& !self.halted
&& self.pc < self.program.rom.len()
{
if steps_executed > 0 && self.breakpoints.contains(&self.pc) {
if self.breakpoints.contains(&self.pc)
&& (steps_executed > 0
|| self.lifecycle.as_ref().is_some_and(|c| c.breakpoint != Some(self.pc)))
{
if let Some(call) = &mut self.lifecycle {
call.breakpoint = Some(self.pc);
}
ending_reason = Some(LogicalFrameEndingReason::Breakpoint);
break;
}
@@ -70,7 +81,8 @@ impl VirtualMachine {
let rep = self.run_budget(budget_per_slice, native, ctx)?;
let terminal = matches!(
rep.reason,
LogicalFrameEndingReason::Halted
LogicalFrameEndingReason::LifecycleComplete
| LogicalFrameEndingReason::Halted
| LogicalFrameEndingReason::EndOfRom
| LogicalFrameEndingReason::Panic(_)
| LogicalFrameEndingReason::Trap(_)
@@ -113,7 +125,8 @@ impl VirtualMachine {
let rep = self.run_budget(budget_per_slice, native, ctx)?;
let terminal = matches!(
rep.reason,
LogicalFrameEndingReason::Halted
LogicalFrameEndingReason::LifecycleComplete
| LogicalFrameEndingReason::Halted
| LogicalFrameEndingReason::EndOfRom
| LogicalFrameEndingReason::Panic(_)
| LogicalFrameEndingReason::Trap(_)
@@ -36,6 +36,7 @@ fn function(
max: u32,
) -> FunctionDecl {
FunctionDecl {
lifecycle_role: Default::default(),
captures: vec![],
name: Some(format!("f{offset}")),
code_offset: offset as u32,
@@ -777,3 +778,171 @@ fn call_growth_refusal_does_not_publish_frame_or_keep_provisional_capacity() {
assert_eq!(vm.budget.used(RuntimeResource::AuxiliaryBytes), before);
assert_eq!(vm.budget.used(RuntimeResource::TemporaryBytes), 0);
}
mod lifecycle_tests {
use super::*;
use prometeu_bytecode::registry::LifecycleRole;
fn machine(hook: Vec<u8>) -> VirtualMachine {
let mut code = vec![];
arg(&mut code, OpCode::PushI32, 17);
op(&mut code, OpCode::FrameSync);
arg(&mut code, OpCode::SetGlobal, 0);
op(&mut code, OpCode::Ret);
let len = code.len();
code.extend(&hook);
let mut callback = function(len, hook.len(), &[], &[], 0, 8);
callback.lifecycle_role = LifecycleRole::BeforePause;
let image = image(&code, vec![function(0, len, &[], &[], 0, 8), callback]);
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
assert_eq!(run(&mut vm), LogicalFrameEndingReason::FrameSync);
vm
}
#[test]
fn lifecycle_preserves_continuation_and_does_not_run_gameplay_after_return() {
let mut hook = vec![];
arg(&mut hook, OpCode::PushI32, 42);
arg(&mut hook, OpCode::SetGlobal, 1);
op(&mut hook, OpCode::Ret);
let mut vm = machine(hook);
let pc = vm.pc;
let depth = vm.call_stack.len();
let stack = vm.operand_stack.to_vec();
assert!(vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap());
assert!(vm.begin_lifecycle(LifecycleRole::BeforePause).is_err());
assert_eq!(run(&mut vm), LogicalFrameEndingReason::LifecycleComplete);
assert_eq!(vm.pc, pc);
assert_eq!(vm.call_stack.len(), depth);
assert_eq!(&vm.operand_stack[..], stack.as_slice());
assert_eq!(vm.globals[1], Value::Int32(42));
assert_eq!(run(&mut vm), LogicalFrameEndingReason::EndOfRom);
assert_eq!(vm.globals[0], Value::Int32(17));
assert!(!vm.begin_lifecycle(LifecycleRole::BeforeResume).unwrap());
}
#[test]
fn lifecycle_budget_survives_slices_breakpoints_and_single_steps() {
let mut hook = vec![];
arg(&mut hook, OpCode::Jmp, 0);
let mut vm = machine(hook);
vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap();
vm.insert_breakpoint(vm.pc);
let rep = vm.run_budget(u64::MAX, &mut Native, &mut HostContext::new(None)).unwrap();
assert_eq!(rep.reason, LogicalFrameEndingReason::Breakpoint);
assert_eq!(rep.cycles_used, 0);
let before = vm.lifecycle_remaining_cycles().unwrap();
vm.step(&mut Native, &mut HostContext::new(None)).unwrap();
assert!(vm.lifecycle_remaining_cycles().unwrap() < before);
vm.breakpoints.clear();
let mut total = VirtualMachine::LIFECYCLE_CYCLES - vm.lifecycle_remaining_cycles().unwrap();
loop {
let rep = vm.run_budget(u64::MAX, &mut Native, &mut HostContext::new(None)).unwrap();
assert!(rep.cycles_used <= VirtualMachine::LIFECYCLE_SLICE + OpCode::Jmp.cycles());
total += rep.cycles_used;
if let LogicalFrameEndingReason::Panic(message) = rep.reason {
assert!(message.contains("total cycle budget"));
break;
}
assert_eq!(rep.reason, LogicalFrameEndingReason::BudgetExhausted);
}
assert!(total >= VirtualMachine::LIFECYCLE_CYCLES);
let pc = vm.pc;
assert!(vm.step(&mut Native, &mut HostContext::new(None)).is_err());
assert_eq!(vm.pc, pc);
}
#[test]
fn lifecycle_normal_return_wins_at_budget_boundary_and_halt_does_not_complete() {
for remaining in [1, OpCode::Ret.cycles()] {
let mut hook = vec![];
op(&mut hook, OpCode::Ret);
let mut vm = machine(hook);
vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap();
vm.lifecycle.as_mut().unwrap().remaining = remaining;
assert_eq!(run(&mut vm), LogicalFrameEndingReason::LifecycleComplete);
}
let mut hook = vec![];
op(&mut hook, OpCode::Halt);
let mut vm = machine(hook);
vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap();
assert_eq!(run(&mut vm), LogicalFrameEndingReason::Halted);
assert!(vm.lifecycle_active());
}
#[test]
fn lifecycle_forbids_frame_sync_and_preserves_failure() {
let mut hook = vec![];
op(&mut hook, OpCode::FrameSync);
op(&mut hook, OpCode::Ret);
let mut vm = machine(hook);
vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap();
let reason = run(&mut vm);
assert!(
matches!(&reason, LogicalFrameEndingReason::Trap(t) if t.message.contains("FRAME_SYNC"))
);
assert_eq!(run(&mut vm), reason);
}
#[test]
fn lifecycle_nested_calls_keep_saved_roots_and_branch_returns_stop_at_boundary() {
let main = prometeu_bytecode::assembler::assemble("FRAME_SYNC\nRET").unwrap();
let hook = prometeu_bytecode::assembler::assemble("CALL 2\nJMP 12").unwrap();
for callee_source in ["PUSH_I32 9\nSET_GLOBAL 0\nRET", "FRAME_SYNC\nRET"] {
let callee = prometeu_bytecode::assembler::assemble(callee_source).unwrap();
let mut callback = function(main.len(), hook.len(), &[], &[], 0, 8);
callback.lifecycle_role = LifecycleRole::BeforePause;
let code = [main.as_slice(), hook.as_slice(), callee.as_slice()].concat();
let image = image(
&code,
vec![
function(0, main.len(), &[], &[], 0, 8),
callback,
function(main.len() + hook.len(), callee.len(), &[], &[], 0, 8),
],
);
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
vm.prepare_boot_call().unwrap();
assert_eq!(run(&mut vm), LogicalFrameEndingReason::FrameSync);
let retained = vm.heap.alloc_closure(0, &[]).unwrap();
vm.operand_stack.push(Value::HeapRef(retained)).unwrap();
vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap();
vm.gc_alloc_threshold = 1;
vm.handle_safepoint().unwrap();
assert!(vm.heap.is_valid(retained));
let result = run(&mut vm);
if callee_source.starts_with("FRAME_SYNC") {
assert!(matches!(result, LogicalFrameEndingReason::Trap(_)));
} else {
assert_eq!(result, LogicalFrameEndingReason::LifecycleComplete);
assert_eq!(vm.call_stack.len(), 1);
assert_eq!(vm.operand_stack.last(), Some(&Value::HeapRef(retained)));
assert_eq!(vm.globals[0], Value::Int32(9));
}
}
}
#[test]
fn lifecycle_entry_quota_refusal_is_transactional_and_empty_context_is_supported() {
let mut vm = machine(prometeu_bytecode::assembler::assemble("RET").unwrap());
let image = vm.validated_image.clone().unwrap();
let limits = RuntimeLimits::default().lowered(RuntimeResource::CallDepth, 1).unwrap();
vm = VirtualMachine::from_image(image.clone(), limits);
vm.prepare_boot_call().unwrap();
let pc = vm.pc;
let stack = vm.operand_stack.to_vec();
assert!(vm.begin_lifecycle(LifecycleRole::BeforePause).is_err());
assert_eq!(vm.pc, pc);
assert_eq!(&vm.operand_stack[..], stack.as_slice());
assert_eq!(vm.call_stack.len(), 1);
assert!(!vm.lifecycle_active());
let mut vm = VirtualMachine::from_image(image, RuntimeLimits::default());
let halted = vm.halted;
let pc = vm.pc;
vm.begin_lifecycle(LifecycleRole::BeforePause).unwrap();
assert_eq!(run(&mut vm), LogicalFrameEndingReason::LifecycleComplete);
assert_eq!(vm.pc, pc);
assert_eq!(vm.halted, halted);
assert!(vm.call_stack.is_empty());
}
}
@@ -45,6 +45,7 @@ fn named_arguments_preserve_source_effect_order_and_call_in_signature_order_with
vec![]
};
functions.push(FunctionDecl {
lifecycle_role: Default::default(),
captures: vec![],
name: Some(["main", "effectX", "effectY", "combine"][index].into()),
signature: Signature {
@@ -7,20 +7,20 @@ use prometeu_vm::{
};
// Independent executable oracle: 32-byte header, eight directory entries,
// payload at 128, one Bool import, one zero-slot HALT function; total 193.
// payload at 128, one Bool import, one zero-slot HALT function; total 194.
fn minimal() -> Vec<u8> {
"50 42 58 00 01 00 00 00 08 00 00 00
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 80 00 00 00 04 00 00 00
01 00 00 00 84 00 00 00 1d 00 00 00
02 00 00 00 a1 00 00 00 02 00 00 00
04 00 00 00 a3 00 00 00 04 00 00 00
05 00 00 00 a7 00 00 00 04 00 00 00
06 00 00 00 ab 00 00 00 0a 00 00 00
07 00 00 00 b5 00 00 00 04 00 00 00
08 00 00 00 b9 00 00 00 08 00 00 00
01 00 00 00 84 00 00 00 1e 00 00 00
02 00 00 00 a2 00 00 00 02 00 00 00
04 00 00 00 a4 00 00 00 04 00 00 00
05 00 00 00 a8 00 00 00 04 00 00 00
06 00 00 00 ac 00 00 00 0a 00 00 00
07 00 00 00 b6 00 00 00 04 00 00 00
08 00 00 00 ba 00 00 00 08 00 00 00
00 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00
01 00 00 00 00 00 00 00 00 00 00 00 00 00
00 00 00 00 02 00 00 00 00 00 00 00 00 00 00 00
01 00
00 00 00 00
@@ -48,7 +48,7 @@ impl NativeInterface for Native {
#[test]
fn independent_v1_bytes_load_publish_and_execute_through_the_public_sealed_boundary() {
let bytes = minimal();
assert_eq!(bytes.len(), 193);
assert_eq!(bytes.len(), 194);
let mut load = LoadBudget::new(Default::default());
let image = ValidatedProgramImage::load(&bytes, &mut load, caps::NONE).unwrap();
assert_eq!(load.used(LoadResource::TemporaryBytes), 0);
@@ -65,9 +65,9 @@ fn independent_v1_bytes_load_publish_and_execute_through_the_public_sealed_bound
fn single_violation_oracles_reject_before_image_publication_with_typed_context() {
for (offset, replacement, code, reason, pc) in [
(4, 0, LoadCode::UnsupportedFormat, LoadReason::Version, None),
(177, 0, LoadCode::UnsupportedFormat, LoadReason::Builtin, None),
(161, 0xff, LoadCode::InvalidCode, LoadReason::UnknownOpcode, Some(0)),
(161, 0x11, LoadCode::InvalidCode, LoadReason::StackUnderflow, Some(0)),
(178, 0, LoadCode::UnsupportedFormat, LoadReason::Builtin, None),
(162, 0xff, LoadCode::InvalidCode, LoadReason::UnknownOpcode, Some(0)),
(162, 0x11, LoadCode::InvalidCode, LoadReason::StackUnderflow, Some(0)),
] {
let mut bytes = minimal();
bytes[offset] = replacement;
@@ -89,6 +89,7 @@ pub fn bytes_with_syscalls(
for (source, signature, captures) in bodies {
let body = assemble(source).unwrap();
functions.push(FunctionDecl {
lifecycle_role: Default::default(),
signature: signature.clone(),
captures: captures.clone(),
code_offset: code.len() as u32,
@@ -60,6 +60,7 @@ pub fn declarations(code_len: usize) -> RegistryDeclarations {
RegistryDeclarations {
types,
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_len: code_len as u32,
local_slots: 0,
max_stack_slots: 32,
@@ -50,6 +50,7 @@ pub fn bytes(bodies: &[Body<'_>]) -> Vec<u8> {
for (text, signature, captures, locals) in bodies {
let body = assemble(text).unwrap();
functions.push(FunctionDecl {
lifecycle_role: Default::default(),
signature: signature.clone(),
captures: captures.clone(),
local_slots: *locals,
@@ -49,6 +49,7 @@ impl TestProgram {
) -> Self {
Self {
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
name: None,
signature,
captures: vec![],
@@ -53,6 +53,7 @@ fn benchmark_cartridge() -> PathBuf {
let module = TestProgram {
const_pool: vec![],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
local_slots: 0,
@@ -64,8 +64,18 @@ fn executed_closure_quota_refusal_reaches_wire_with_machine_fields() {
RegistryDeclarations {
types: vec![TypeDecl { name: None, kind: TypeKind::Fn(Default::default()) }],
functions: vec![
FunctionDecl { code_len: end, max_stack_slots: 1, ..Default::default() },
FunctionDecl { code_offset: end, code_len: 2, ..Default::default() },
FunctionDecl {
lifecycle_role: Default::default(),
code_len: end,
max_stack_slots: 1,
..Default::default()
},
FunctionDecl {
lifecycle_role: Default::default(),
code_offset: end,
code_len: 2,
..Default::default()
},
],
implementations: vec![],
},
@@ -501,6 +501,7 @@ mod tests {
let module = TestProgram {
const_pool: vec![],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
local_slots: 0,
@@ -660,6 +660,7 @@ fn module_with_locals(code: Vec<u8>, syscalls: Vec<SyscallDecl>, local_slots: u1
TestProgram {
const_pool: vec![],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
local_slots: u32::from(local_slots),
+1
View File
@@ -72,6 +72,7 @@ pub fn build_program() -> Vec<u8> {
let registry = Registry::resolve(
RegistryDeclarations {
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_len: code.len() as u32,
local_slots: 1,
max_stack_slots: 8,
+1
View File
@@ -85,6 +85,7 @@ pub fn generate() -> Result<()> {
let registry = Registry::resolve(
RegistryDeclarations {
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_len: rom.len() as u32,
local_slots: 2,
max_stack_slots: 32,
@@ -180,6 +180,7 @@ fn cartridge_bytes(code: Vec<u8>, gfx: bool) -> TempDir {
let module = TestProgram {
const_pool: vec![],
functions: vec![FunctionDecl {
lifecycle_role: Default::default(),
code_offset: 0,
code_len: code.len() as u32,
local_slots: 0,
@@ -0,0 +1,111 @@
---
id: LSN-0066
ticket: guest-lifecycle-pause-and-resume-api
title: Lifecycle Calls Retain the Game Continuation
created: 2026-10-13
tags: [lifecycle, vm, registry, debugger]
---
## Context
Optional BeforePause and BeforeResume functions now run around the existing OS
suspension and reactivation transitions. The implementation derives from accepted
DEC-0054 and PLN-0185, originating in AGD-0065 / DSC-0062. These workflow records
are disposable; the durable contracts are
[Registry roles](../../../docs/specs/runtime/02c-program-registry-and-pbx-v1.md#optional-lifecycle-roles)
and [controlled lifecycle calls](../../../docs/specs/runtime/09a-coroutines-and-cooperative-scheduling.md#controlled-lifecycle-calls).
## Binding Describes a Runtime Event, Not a Frontend Construct
A Registry function has one explicit role byte. Zero means no lifecycle role;
nonzero bindings are unique and optional. The function index is chosen by the
producer. A source name, manifest entry or arbitrary fixed FunctionId would mix
language policy with runtime scheduling. Signature validation at image loading
makes the OS call boundary independent of source syntax.
Init and Frame remain frontend assembly choices behind ordinary entry zero.
The external compiler must emit the new role byte for every Function record,
validate source declarations, and regenerate its PBX v1 artifacts. That compiler
integration was not performed in this runtime delivery. Internal producers and
tracked dummy-boy/stress-console images use the revised layout. Independent
binary oracles were updated field by field, including directory offsets and
malformed-input locations; merely regenerating fixtures would lose that check.
## Retaining the Continuation Avoids a Second Execution Context
The VM appends a hook frame to its own operand and call stacks. The previous PC,
halted flag and boundaries define where to restore execution. Existing values
and closure environments stay in the normal root traversal, so a suspended
caller cannot disappear during collection. Globals and heap mutations made by
the hook persist. Retained frames still count toward call-depth and memory limits.
Boot-entry preparation clears stacks and is therefore the wrong operation for
this boundary. A second VM would separate globals, capabilities, handles and
heap identity. Appending a controlled frame keeps those identities intact. The
critical completion rule is to stop at the outer return immediately: unused
slice fuel must not execute the saved gameplay continuation. A branch to function
end follows the same boundary, including nested ordinary calls.
## A Debugger Is Another Execution Driver
Normal slices and instruction stepping share the VM's total-fuel accounting.
Breakpoints retain that balance, including a breakpoint on the first hook
instruction. Waiting in the debugger costs no cycles. The OS step path uses the
session's actual filesystem state, open handles and memcard service. A dummy
service context would make stepping change the program's meaning.
One total budget survives all slices. Whole instructions retain their ordinary
overshoot semantics; a completed return wins at the boundary, while unfinished
work fails at exhaustion. FRAME_SYNC is forbidden transitively because a hook
must not close or publish a gameplay frame. Normal service errors remain data;
fatal faults and host panics fail the session with the phase in diagnostics.
HALT closes the task rather than completing a hook or returning to gameplay.
## Deferring Completion Preserves Existing OS Policy
The Home path still grants its existing handoff tick. After it leaves gameplay,
the pending transition drives only the callback until suspension completes.
Direct suspension and Shell activation use the same callback boundary without
inventing an extra gameplay tick. Reactivation precedes BeforeResume, and normal
frames remain gated until return. Requests are serialized; repeated requests
cannot replenish fuel or start another invocation.
The firmware also recognizes completion caused by debugger stepping, so its
next update cannot treat a properly suspended task as a crash. Transitions with
no applicable hook retain their immediate behavior.
## Bytecode Fuel Does Not Bound a Blocked Native Call
The executor adds no disk wait or automatic flush and does not cancel owned IO
on hook failure. Existing asset/async-work protocols retain their ownership.
The native audit found that FS read/write and the current memcard commit still
call synchronous backend interfaces. A deterministic cycle cap cannot preempt
one of those host calls. Prompt native return is a host/service obligation;
there is no wall-time guarantee in this delivery.
The new memcard backend must supply bounded asynchronous submission/polling and
own in-flight data until completion or safe release. Its consumer acceptance
belongs to the memcard workflow: explicit commit from a hook, return without
waiting for disk, late completion after lifecycle failure, and availability
checks on resume without automatic reload/save/reinitialization. The runtime
hook mechanism is independently complete and does not implement that backend.
## Evidence
Loaded-bytecode tests exercise optional roles, strict metadata rejection,
retained PC/stacks/roots, nested calls, branch returns, quota refusal, an empty
continuation, exact/overshooting return budgets, multiple slices, breakpoints,
and sticky fatal failures. Firmware tests cover Home, direct suspend, Shell,
resume, independently absent hooks, debugger steps using real handles, phase
failures and HALT. Validation completed with 960 passed / 9 existing ignored across 53 workspace
suites (`cargo test --workspace --all-targets --all-features --no-fail-fast`).
After the final tick/step and boot-entry guards, all 528 affected VM/system/firmware
library tests passed (2 existing ignored). The final pause-request guard was
also revalidated by the 245 system/firmware library tests. Formatting, Clippy,
diff whitespace, published-doc workflow-reference checks and discussion validation
passed. Published lesson links resolve. Internal producer regeneration completed.
The tests also verify ordinary unmounted-FS error data inside a hook, real
session-handle mutation under debugger stepping, and that a suspended session
cannot execute gameplay through direct tick/step requests. Preparing a new boot
entry while a hook is active is refused rather than clearing the retained stacks.
@@ -76,13 +76,15 @@ call and capture access validate whole groups and reserve capacity before consum
or publication. Refusal preserves operands/owners and publishes no partial object
or frame; provisional reservations refund and attempted cycles remain. No quota
rescue GC. Use existing distinct NullReference/InvalidHandle/Type/Resource traps.
Fn can invoke syscalls, mutate and fault: no purity flag, fault isolation, separate
budget, guest unwind or rollback of earlier body effects.
Ordinary Fn calls can invoke syscalls, mutate and fault: no purity flag, fault
isolation, separate budget, guest unwind or rollback of earlier body effects.
SystemOS lifecycle invocations use the separate budget described below.
## 5 Context, GC and Host
VM owns one PC, operand/call stacks and globals directly. FRAME_SYNC retains
frames/locals/environments and resumes next PC in any body. Budget exhaustion
frames/locals/environments and resumes next PC in normal gameplay bodies. It is
forbidden during lifecycle hooks and their callees. Budget exhaustion
retains the same logical frame. Last-root RET completes entry, rooting results
before threshold GC. Recurring host entry remains FunctionId 0 with init once.
@@ -92,8 +94,9 @@ and legally retained native/host roots. Trace whole capture groups and shared
cells; unreachable cycles collect. Results remain roots until consumed/replaced,
reset/unload. No GC at ordinary callee RET or allocation/quota rescue.
HeapRef copies/inspection snapshots establish no guest roots or cross-session
imports. No native registration/delivery/reentry API is created here. Guest
callbacks are ordinary Fn calls in the main execution context.
imports. Ordinary guest callbacks are Fn calls in the main execution context.
Optional SystemOS lifecycle entry uses Registry roles and the controlled boundary
described below; it does not introduce arbitrary native reentry.
See [memory](03-memory-stack-heap-and-allocation.md),
[Registry/PBX](02c-program-registry-and-pbx-v1.md) and
@@ -102,3 +105,14 @@ See [memory](03-memory-stack-heap-and-allocation.md),
## Random core integration
[Random references](02e-vm-owned-random-core.md) are valid capture, parameter and result groups. Existing roots retain the generator; copying captures aliases its state.
## System-owned lifecycle entry
Optional zero-argument, zero-result, capture-free lifecycle targets are bound by
[Registry roles](02c-program-registry-and-pbx-v1.md#optional-lifecycle-roles).
They are ordinary functions called through a controlled SystemOS boundary, not
closure values or replacement boot entries. The boundary retains the existing
stacks and roots, appends its frame, and returns to SystemOS immediately on outer
completion. See [lifecycle execution](09a-coroutines-and-cooperative-scheduling.md#controlled-lifecycle-calls)
for independent fuel, debugger behavior and failure semantics. Frontend Init and
Frame assembly is unchanged.
@@ -81,11 +81,34 @@ Encoding primitives: list=`count:u32` followed by records; optional name=`presen
| Trait payload | ordered method list; each method has optional name, explicit-parameter list, result list; concrete receiver is not repeated here |
| Fn payload | ordered parameter list, result list; names do not define identity |
| Captures section | function_count:u32, then each FunctionId in order: capture_count:u32 and TypeIds:u32; counts match functions, empty lists explicit |
| Function | optional name, parameter list, result list, code_offset:u32, code_len:u32, local_slots:u32, max_stack_slots:u32 |
| Function | lifecycle_role:u8, optional name, parameter list, result list, code_offset:u32, code_len:u32, local_slots:u32, max_stack_slots:u32 |
| Implementation | owner_type_id:u32, trait_type_id:u32, method_count:u32, FunctionIds:u32 in trait-method order; count must match |
Code offsets are relative to Code. Local and temporary counts widen from current u16 without truncation. `max_stack_slots` counts temporaries only; zero means zero, never infer. No guest-controlled builtin layouts or raw Rust structures/pointers are serialized. Remove old/external compatibility; regeneration is mandatory.
## Optional lifecycle roles
The executable Function record carries one role byte before its optional name:
`0=None`, `1=BeforePause`, `2=BeforeResume`. Zero means an ordinary function,
not a callable hook. Unknown values reject with InvalidRegistry/LifecycleRole.
Each nonzero role has at most one target; duplicates reject with
InvalidRegistry/DuplicateLifecycleRole. Targets MUST NOT be FunctionId 0 and
MUST have zero parameters, results and captures; violations reject with
InvalidEntrypoint/LifecycleSignature. Preserve function/section context and the
wire offset when decoding an invalid role. Resolve optional FunctionIds once
in the immutable Registry. Names, exports, manifests and trait Method records
are not the binding mechanism.
Either hook may be absent. Additional roles require a future contract; there is
no termination role. PBX remains version 1, with no old-layout fallback or
external-artifact compatibility. Producers MUST regenerate their images and
emit this byte for every function, including zero for ordinary functions.
Frontend compilers choose their own source syntax and lower it to these roles.
Their existing Init/Frame boot assembly remains frontend-owned; runtime keeps
FunctionId 0 as its ordinary entry and does not introduce Init/Frame roles.
Execution ordering and limits are defined in [lifecycle](09a-coroutines-and-cooperative-scheduling.md).
## Values, storage and initialization
Value remains the generic stack/local representation. Structs/arrays are references; primitive and builtin-value array elements are stored directly. Layout descriptors distinguish value-slot width from heap-instance layout and distinguish GC references from native ownership. Derive offsets/defaults/maps once; access by indices/offsets rather than repeatedly traversing semantic metadata. Measure bitmap versus offset/block lists; changing the map encoding must not change the contract.
@@ -97,7 +97,8 @@ Sync Phase
Important properties:
- events are processed at known points;
- no execution occurs outside the frame loop;
- normal gameplay executes inside the frame loop; optional SystemOS lifecycle
hooks execute outside it with an independent budget;
- frame structure remains observable for host tooling and host-owned certification.
## 7 Foreground Lifecycle Events
@@ -111,7 +112,9 @@ The Game pause path is:
Home/SystemOS request
-> pause event becomes visible to the Game
-> bounded pause reaction budget
-> SystemOS suspension, even if the Game did not cooperate
-> leave gameplay execution
-> optional BeforePause hook
-> SystemOS suspension on normal completion, or session failure
```
The Game resume path is:
@@ -120,7 +123,8 @@ The Game resume path is:
SystemOS resume request
-> VM reactivation
-> resume or foreground-restore event becomes visible to the Game
-> Game may synchronize while still internally paused
-> optional BeforeResume hook
-> normal gameplay becomes eligible after successful return
-> visual foreground returns after a valid current-epoch render submission
```
@@ -128,10 +132,11 @@ SystemOS resume request
scheduler/runtime state. A Game may observe pause/resume, but it must not
control whether SystemOS suspends or resumes the VM.
When SystemOS replaces one Game with another from Home, the old Game MAY receive
a cooperative terminate/save lifecycle event if the runtime supports such an
event. That event is non-blocking in v1. SystemOS remains authoritative and may
close the old Game task/session without guest acknowledgement.
Registry hooks are optional and independent. Their binding, single-context call
boundary, fuel and debugger semantics follow [the lifecycle contract](09a-coroutines-and-cooperative-scheduling.md#controlled-lifecycle-calls).
Existing pending native lifecycle delivery bookkeeping remains separate; it is
not a new guest event API. There is no termination hook. SystemOS may close an
old Game task/session without guest acknowledgement when replacing it.
Pause budgets are measured in deterministic machine units, not host wall-clock
time. A suspended Game receives no normal gameplay ticks, no normal Game input,
@@ -13,7 +13,8 @@ diagnostic decoding can identify retired numbers. No compatibility mode exists.
Other instruction numbers are unchanged.
FRAME_SYNC closes a logical frame and preserves context. It has zero stack effect,
is not a terminator, can occur in any body and resumes next PC. Host MUST NOT
is not a terminator and resumes next PC. It is forbidden while a lifecycle hook
is active, including in its callees. Host MUST NOT
prepare fresh entry solely because sync occurred. Budget exhaustion/breakpoints
preserve the same open frame without draw publication or extra callback budget.
@@ -34,3 +35,53 @@ and invoke typed Fn callbacks. UI/SDK APIs and future coroutine protocols requir
separate contracts. See [Fn](02b-vm-function-values-and-closures.md),
[events](09-events-and-concurrency.md) and
[memory](03-memory-stack-heap-and-allocation.md).
## Controlled lifecycle calls
SystemOS optionally invokes the Registry's BeforePause and BeforeResume roles.
BeforePause runs after leaving the existing gameplay loop/handoff and before OS
suspension completes. BeforeResume runs after reactivation and before any normal
gameplay instruction. Neither hook is required, takes arguments, returns a
value, or vetoes the transition. Absence preserves the existing transition.
Direct suspension and Shell foreground handoff obey the same ordering; they do
not add a gameplay reaction tick. Home retains its existing one-tick handoff.
A controlled call appends a frame and locals to the same VM stacks. It retains
the previous PC, halted state and stack boundaries; all suspended stack values,
frame environments, globals and heap references remain roots. Existing stack,
call-depth and allocation quotas include retained frames. Reserve before entry
mutation. Ordinary calls inside the hook work normally. On successful outer
return (including a branch to function end), restore the continuation and return
immediately to SystemOS, even if the execution slice has unused cycles. Never
clear the stacks with boot-entry preparation or execute gameplay in that slice.
Global/heap mutations persist. There is at most one lifecycle invocation per
session; duplicate requests do not reenter or renew it, and conflicting pending
transitions reject.
Each invocation receives 1,500,000 virtual cycles total, sliced at no more than
250,000 admitted cycles per host update. This budget is independent of normal
logical frames and never renews between slices or debugger stops. Positive
remaining budget admits a whole instruction and allows its existing overshoot.
A normal completed return succeeds even if that final instruction consumes the
remaining budget; an unfinished invocation at exhaustion fails. There is no
wall-clock deadline. Breakpoints preserve the invocation and remaining budget;
while stopped, no cycles or gameplay frames advance. Instruction stepping uses
the same budget and the session's real service context.
FRAME_SYNC traps before frame/GC/publication effects, including from ordinary
callees. Fatal traps, host errors/panics and total exhaustion fail the session,
block gameplay and report the failing phase through the existing crash path.
There is no retry, rollback of earlier mutations or compensating other hook.
Normal service-result errors remain guest data. HALT closes the task through
the OS termination path; it is not successful hook return.
Hooks use the existing services and capability checks. No automatic save,
flush, disk-completion wait, guest event queue or reason argument is added.
Host-owned in-flight work keeps its ownership until the service/host safely
releases it; lifecycle failure does not simulate cancellation or free borrowed
buffers. Native calls must return promptly: VM fuel only bounds bytecode and
cannot preempt a blocked native/host call. Existing FS read/write and the current
memcard commit backend are synchronous interfaces, so this implementation does
not promise a wall-time bound for them. The new asynchronous memcard backend
must expose bounded submission/polling independently; hooks can then submit an
explicit commit without waiting for disk completion.
Binary file not shown.
Binary file not shown.