feat(runtime): implement shared transactional memcard with async saves
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-13 15:24:01 +01:00
parent 0af8b2b1fe
commit 6c2a07e579
65 changed files with 6222 additions and 985 deletions
@@ -61,6 +61,32 @@ impl Firmware {
/// This method is called exactly once per Host frame (60Hz).
/// It updates peripheral signals and delegates the logic to the current state.
pub fn tick(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
self.os.poll_background_io(platform);
if self.os.memcard().host_faulted() {
// Keep the resident VM, snapshots, and worker-owned buffers alive. A
// stuck host operation cannot be repaired by launching another worker.
self.state = FirmwareState::MemoryIoFault;
self.state_initialized = true;
self.on_update(signals, platform);
return;
}
if self.os.memcard().session.removal_pending()
&& let Some(task) = self.os.lifecycle().resident_game_task()
{
if self.os.lifecycle().task_state(task)
== Some(prometeu_system::task::TaskState::Suspended)
{
if !matches!(
self.state,
FirmwareState::MemoryCardRemoved(_) | FirmwareState::ConfirmDiscard(_)
) {
self.state = FirmwareState::MemoryCardRemoved(Default::default());
self.state_initialized = true;
}
} else {
self.request_home_from_host();
}
}
let barriered_signals = InputSignals::default();
let effective_signals = if self.game_input_barrier_frames > 0 {
self.game_input_barrier_frames -= 1;
@@ -167,8 +193,10 @@ impl Firmware {
FirmwareState::SplashScreen(s) => s.on_enter(&mut req),
FirmwareState::LaunchHub(s) => s.on_enter(&mut req),
FirmwareState::HubHome(s) => s.on_enter(&mut req),
FirmwareState::ConfirmDiscard(s) => s.on_enter(&mut req),
FirmwareState::MemoryCardRemoved(s) => s.on_enter(&mut req),
FirmwareState::LoadCartridge(s) => s.on_enter(&mut req),
FirmwareState::ResumeResidentGame => {}
FirmwareState::ResumeResidentGame | FirmwareState::MemoryIoFault => {}
FirmwareState::GameRunning(s) => s.on_enter(&mut req),
FirmwareState::ShellRunning(s) => s.on_enter(&mut req),
FirmwareState::AppCrashes(s) => s.on_enter(&mut req),
@@ -194,8 +222,32 @@ impl Firmware {
FirmwareState::SplashScreen(s) => s.on_update(&mut req),
FirmwareState::LaunchHub(s) => s.on_update(&mut req),
FirmwareState::HubHome(s) => s.on_update(&mut req),
FirmwareState::ConfirmDiscard(s) => s.on_update(&mut req),
FirmwareState::MemoryCardRemoved(s) => s.on_update(&mut req),
FirmwareState::LoadCartridge(s) => s.on_update(&mut req),
FirmwareState::ResumeResidentGame => None,
FirmwareState::MemoryIoFault => {
use prometeu_hal::color::Color;
use prometeu_hal::{FrameId, GfxUiCommand, RenderSubmission, ShellUiFramePacket};
let lines = [
"Memory-card IO did not stop in time.",
"Save outcome may be unknown.",
"Restart the host before using storage again.",
];
let mut commands = vec![GfxUiCommand::Clear { color: Color::BLACK }];
commands.extend(lines.into_iter().enumerate().map(|(i, text)| {
GfxUiCommand::DrawText {
x: 8,
y: 8 + i as i32 * 20,
text: text.into(),
color: Color::WHITE,
}
}));
let _ = req.platform.render_submission_sink().submit_render_submission(
RenderSubmission::shell_ui(FrameId::ZERO, ShellUiFramePacket::new(commands)),
);
None
}
FirmwareState::GameRunning(s) => s.on_update(&mut req),
FirmwareState::ShellRunning(s) => s.on_update(&mut req),
FirmwareState::AppCrashes(s) => s.on_update(&mut req),
@@ -216,8 +268,10 @@ impl Firmware {
FirmwareState::SplashScreen(s) => s.on_exit(&mut req),
FirmwareState::LaunchHub(s) => s.on_exit(&mut req),
FirmwareState::HubHome(s) => s.on_exit(&mut req),
FirmwareState::ConfirmDiscard(s) => s.on_exit(&mut req),
FirmwareState::MemoryCardRemoved(s) => s.on_exit(&mut req),
FirmwareState::LoadCartridge(s) => s.on_exit(&mut req),
FirmwareState::ResumeResidentGame => {}
FirmwareState::ResumeResidentGame | FirmwareState::MemoryIoFault => {}
FirmwareState::GameRunning(s) => s.on_exit(&mut req),
FirmwareState::ShellRunning(s) => s.on_exit(&mut req),
FirmwareState::AppCrashes(s) => s.on_exit(&mut req),
@@ -410,6 +464,7 @@ mod tests {
fn invalid_game_cartridge() -> Cartridge {
Cartridge {
memcard_slots: None,
app_id: 7,
title: "Broken Cart".into(),
app_version: "1.0.0".into(),
@@ -451,6 +506,7 @@ mod tests {
.serialize();
Cartridge {
memcard_slots: None,
app_id: 8,
title: "Trap Cart".into(),
app_version: "1.0.0".into(),
@@ -469,6 +525,7 @@ mod tests {
fn valid_cartridge_with(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
Cartridge {
memcard_slots: None,
app_id,
title: title.into(),
app_version: "1.0.0".into(),
@@ -533,6 +590,15 @@ mod tests {
platform.local_hardware().gfx.front_buffer()[index]
}
fn wait_for_cartridge_preload(firmware: &mut Firmware, platform: &mut TestPlatform) {
let deadline = std::time::Instant::now() + std::time::Duration::from_secs(2);
while matches!(firmware.state, FirmwareState::LoadCartridge(_)) {
assert!(std::time::Instant::now() < deadline, "cartridge admission did not complete");
firmware.tick(&InputSignals::default(), platform);
std::thread::yield_now();
}
}
#[test]
fn load_cartridge_transitions_to_app_crashes_when_vm_init_fails() {
let mut firmware = Firmware::new(None);
@@ -919,6 +985,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -1017,6 +1084,7 @@ mod tests {
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
firmware.tick(&stress_click, &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
assert_eq!(firmware.os.lifecycle().task_state(dummy_task), Some(TaskState::Closed));
assert_eq!(
firmware.os.lifecycle().process_state_for_task(dummy_task),
@@ -1100,6 +1168,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -1188,6 +1257,7 @@ mod tests {
firmware.tick(&stress_click, &mut platform);
firmware.tick(&InputSignals::default(), &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
let stress_task = match &firmware.state {
FirmwareState::GameRunning(step) => step.task_id,
other => panic!("expected Stress GameRunning state, got {:?}", other),
@@ -1972,4 +2042,129 @@ mod tests {
);
}
}
#[test]
fn memory_only_admission_runs_typed_guest_boot_and_warns_before_discard() {
for debug in [false, true] {
use prometeu_bytecode::{
load_limits::LoadBudget,
model::{ConstantPoolEntry, SyscallDecl},
registry::{
LifecycleRole, NamedType, Registry, RegistryDeclarations, Signature, TypeDecl,
TypeId, TypeKind,
},
registry_codec::PbxModule,
};
let boot = assemble("HOSTCALL 0\nPOP_N 1\nFRAME_SYNC\nJMP 12").unwrap();
let hook=assemble("PUSH_I64 560\nARRAY_NEW 9\nSET_GLOBAL 0\nGET_LOCAL 0\nPUSH_CONST 0\nPUSH_I32 1\nPUSH_I32 1\nPUSH_I32 1\nGET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 560\nHOSTCALL 1\nPOP_N 1\nGET_LOCAL 0\nPUSH_I32 0\nPUSH_I32 0\nGET_GLOBAL 0\nPUSH_I32 0\nPUSH_I32 560\nHOSTCALL 2\nPOP_N 2\nGET_LOCAL 0\nPUSH_I32 0\nHOSTCALL 3\nPOP_N 2\nPUSH_I32 0\nRET").unwrap();
let mut code = boot.clone();
code.extend(&hook);
let mut types = prometeu_test_support::program::scalar_catalog();
types.push(TypeDecl { name: None, kind: TypeKind::Array(TypeId(1)) });
let registry = Registry::resolve(
RegistryDeclarations {
types,
functions: vec![
FunctionDecl {
code_len: boot.len() as u32,
max_stack_slots: 16,
..Default::default()
},
FunctionDecl {
lifecycle_role: LifecycleRole::MemcardBoot,
code_offset: boot.len() as u32,
code_len: hook.len() as u32,
max_stack_slots: 16,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![TypeId(1)],
},
..Default::default()
},
],
implementations: vec![],
},
code.len(),
&mut LoadBudget::new(Default::default()),
)
.unwrap();
let syscalls = [
("bootstrap", 0, 1),
("presentation", 8, 1),
("slot_write", 6, 2),
("slot_commit", 2, 2),
]
.map(|(name, arg_slots, ret_slots)| SyscallDecl {
module: "mem".into(),
name: name.into(),
version: 1,
arg_slots,
ret_slots,
});
let constants = [ConstantPoolEntry::String("Guest save".into())];
let program = PbxModule {
registry: &registry,
code: &code,
constants: &constants,
debug: None,
exports: &[],
syscalls: &syscalls,
}
.serialize(&mut LoadBudget::new(Default::default()))
.unwrap();
let mut cartridge = valid_cartridge(AppMode::Game);
cartridge.program = program;
cartridge.memcard_slots = Some(1);
cartridge.capabilities = prometeu_hal::syscalls::caps::MEMCARD;
let mut firmware = Firmware::new(None);
let mut platform = TestPlatform::new();
firmware.load_cartridge(cartridge);
firmware.tick(&InputSignals::default(), &mut platform);
assert!(matches!(firmware.state, FirmwareState::LoadCartridge(_)));
firmware.tick(&InputSignals { x_signal: true, ..Default::default() }, &mut platform);
wait_for_cartridge_preload(&mut firmware, &mut platform);
if debug {
firmware.os.vm().set_paused(true);
for _ in 0..80 {
assert!(firmware.os.vm().debug_step_active_session(&mut platform).is_none());
if !firmware.os.memcard().session.is_boot_active() {
break;
}
}
assert!(!firmware.os.memcard().session.is_boot_active());
firmware.os.vm().set_paused(false);
}
for _ in 0..4 {
firmware.tick(&InputSignals::default(), &mut platform);
}
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
let session = &mut firmware.os.memcard().session;
let context = session.context();
assert_eq!(session.mode(), Some(prometeu_system::memcard::session::Mode::MemoryOnly));
assert_eq!(session.presentation(context).unwrap().unwrap().title, "Guest save");
assert_eq!(session.descriptor(context, 0).unwrap().1, 560);
assert!(session.unsaved());
firmware.request_home_from_host();
firmware.tick(&InputSignals::default(), &mut platform);
firmware.change_state(
FirmwareState::ConfirmDiscard(
super::super::firmware_state::ConfirmDiscardStep::new(None),
),
&InputSignals::default(),
&mut platform,
);
firmware.tick(&InputSignals::default(), &mut platform);
firmware.tick(&InputSignals { b_signal: true, ..Default::default() }, &mut platform);
assert!(firmware.os.memcard().session.unsaved());
firmware.change_state(
FirmwareState::ConfirmDiscard(
super::super::firmware_state::ConfirmDiscardStep::new(None),
),
&InputSignals::default(),
&mut platform,
);
firmware.tick(&InputSignals::default(), &mut platform);
firmware.tick(&InputSignals { a_signal: true, ..Default::default() }, &mut platform);
assert_eq!(firmware.os.memcard().session.mode(), None);
}
}
}