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
@@ -1,6 +1,6 @@
use super::*;
use crate::fs::{FsState, VirtualFS};
use crate::services::memcard::{MemcardService, MemcardSlotState, MemcardStatus};
use crate::services::memcard::MemcardService;
use prometeu_bytecode::{TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_TYPE, Value};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType, SlotRef};
@@ -605,101 +605,24 @@ impl NativeInterface for VmRuntimeHost<'_> {
}
Ok(())
}
Syscall::MemSlotCount => {
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_int(0);
return Ok(());
}
ret.push_int(MemcardStatus::Ok as i64);
ret.push_int(self.memcard.slot_count() as i64);
Ok(())
}
Syscall::MemSlotStat => {
let slot = expect_slot_index(args, 0)?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_int(MemcardSlotState::Empty as i64);
ret.push_int(0);
ret.push_int(0);
ret.push_int(0);
return Ok(());
}
let stat = self.memcard.slot_stat(self.fs, self.current_app_id, slot);
let status = if stat.state == MemcardSlotState::Corrupt {
MemcardStatus::Corrupt
} else {
MemcardStatus::Ok
};
ret.push_int(status as i64);
ret.push_int(stat.state as i64);
ret.push_int(stat.used_bytes as i64);
ret.push_int(stat.generation as i64);
ret.push_int(stat.checksum as i64);
Ok(())
}
Syscall::MemSlotRead => {
let slot = expect_slot_index(args, 0)?;
let offset = expect_non_negative_usize(args, 1, "offset")?;
let max_bytes = expect_non_negative_usize(args, 2, "max_bytes")?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_string("")?;
ret.push_int(0);
return Ok(());
}
let read =
self.memcard.slot_read(self.fs, self.current_app_id, slot, offset, max_bytes);
ret.push_int(read.status as i64);
ret.push_hex(&read.bytes)?;
ret.push_int(read.bytes_read as i64);
Ok(())
}
Syscall::MemSlotWrite => {
let slot = expect_slot_index(args, 0)?;
let offset = expect_non_negative_usize(args, 1, "offset")?;
let payload_hex = expect_string(args, 2, "payload_hex")?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
ret.push_int(0);
return Ok(());
}
let payload = hex_decode(&payload_hex)?;
Syscall::MemBootstrap
| Syscall::MemSlotCount
| Syscall::MemSlotStat
| Syscall::MemSlotRead
| Syscall::MemSlotWrite
| Syscall::MemSlotCommit
| Syscall::MemSlotClear
| Syscall::MemQuery
| Syscall::MemRelease
| Syscall::MemInfo
| Syscall::MemMetadata
| Syscall::MemPresentation
| Syscall::MemDiagnostic
| Syscall::MemPublishPresentation => {
let timestamp = platform.wall_clock().utc_unix_seconds();
let app_id = self.current_app_id;
let write = self.memcard.slot_write(self.fs, app_id, slot, offset, &payload);
ret.push_int(write.status as i64);
ret.push_int(write.bytes_written as i64);
Ok(())
}
Syscall::MemSlotCommit => {
let slot = expect_slot_index(args, 0)?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
return Ok(());
}
let status = {
let app_id = self.current_app_id;
let memcard = &mut self.memcard;
let fs = &mut self.fs;
memcard.slot_commit(fs, app_id, slot)
};
ret.push_int(status as i64);
Ok(())
}
Syscall::MemSlotClear => {
let slot = expect_slot_index(args, 0)?;
if self.current_cartridge_app_mode != AppMode::Game {
ret.push_int(MemcardStatus::AccessDenied as i64);
return Ok(());
}
let status = {
let app_id = self.current_app_id;
let memcard = &mut self.memcard;
let fs = &mut self.fs;
memcard.slot_clear(fs, app_id, slot)
};
ret.push_int(status as i64);
Ok(())
let game_profile = self.current_cartridge_app_mode == AppMode::Game;
self.memcard.guest(syscall, args, ret, app_id, timestamp, game_profile)
}
Syscall::LogWrite => {
self.syscall_log_write(
@@ -849,14 +772,6 @@ fn expect_number(args: &[Value], index: usize, field: &str) -> Result<f64, VmFau
}
}
fn expect_slot_index(args: &[Value], index: usize) -> Result<u8, VmFault> {
let slot = expect_int(args, index)?;
if !(0..32).contains(&slot) {
return Err(VmFault::Trap(TRAP_OOB, format!("slot index out of bounds: {}", slot)));
}
Ok(slot as u8)
}
fn expect_non_negative_usize(args: &[Value], index: usize, field: &str) -> Result<usize, VmFault> {
let val = expect_int(args, index)?;
if val < 0 {
@@ -864,32 +779,3 @@ fn expect_non_negative_usize(args: &[Value], index: usize, field: &str) -> Resul
}
Ok(val as usize)
}
fn hex_decode(s: &str) -> Result<Vec<u8>, VmFault> {
fn nibble(c: u8) -> Option<u8> {
match c {
b'0'..=b'9' => Some(c - b'0'),
b'a'..=b'f' => Some(10 + c - b'a'),
b'A'..=b'F' => Some(10 + c - b'A'),
_ => None,
}
}
let bytes = s.as_bytes();
if !bytes.len().is_multiple_of(2) {
return Err(VmFault::Trap(TRAP_TYPE, "payload_hex must have even length".to_string()));
}
let mut out = Vec::with_capacity(bytes.len() / 2);
let mut i = 0usize;
while i < bytes.len() {
let hi = nibble(bytes[i]).ok_or_else(|| {
VmFault::Trap(TRAP_TYPE, "payload_hex contains invalid hex".to_string())
})?;
let lo = nibble(bytes[i + 1]).ok_or_else(|| {
VmFault::Trap(TRAP_TYPE, "payload_hex contains invalid hex".to_string())
})?;
out.push((hi << 4) | lo);
i += 2;
}
Ok(out)
}
@@ -219,6 +219,22 @@ impl VirtualMachineRuntime {
match vm.initialize(cartridge.program.clone()) {
Ok(_) => {
if let Some(count) = cartridge.memcard_slots {
if !(1..=64).contains(&count)
|| cartridge.capabilities & prometeu_hal::syscalls::caps::MEMCARD == 0
{
return Err(CrashReport::VmPanic {
message: "Invalid memcard capability/count".into(),
pc: None,
});
}
vm.require_memcard_boot().map_err(|error| CrashReport::VmInit { error })?;
} else if cartridge.capabilities & prometeu_hal::syscalls::caps::MEMCARD != 0 {
return Err(CrashReport::VmPanic {
message: "Memcard capability requires a slot count".into(),
pc: None,
});
}
self.current_app_id = cartridge.app_id;
self.current_cartridge_title = cartridge.title.clone();
self.current_cartridge_app_version = cartridge.app_version.clone();
@@ -1,5 +1,5 @@
use super::*;
use crate::fs::{FsBackend, FsEntry, FsError, FsState, VirtualFS};
use crate::fs::{FsState, VirtualFS};
use crate::services::memcard::MemcardService;
use prometeu_bytecode::TRAP_TYPE;
use prometeu_bytecode::Value;
@@ -29,50 +29,13 @@ use std::collections::HashMap;
use std::sync::Arc;
use std::sync::atomic::Ordering;
#[derive(Default)]
struct MemFsBackend {
files: HashMap<String, Vec<u8>>,
}
impl FsBackend for MemFsBackend {
fn mount(&mut self) -> Result<(), FsError> {
Ok(())
}
fn unmount(&mut self) {}
fn list_dir(&self, _path: &str) -> Result<Vec<FsEntry>, FsError> {
Ok(Vec::new())
}
fn read_file(&self, path: &str) -> Result<Vec<u8>, FsError> {
self.files.get(path).cloned().ok_or(FsError::NotFound)
}
fn write_file(&mut self, path: &str, data: &[u8]) -> Result<(), FsError> {
self.files.insert(path.to_string(), data.to_vec());
Ok(())
}
fn delete(&mut self, path: &str) -> Result<(), FsError> {
self.files.remove(path).map(|_| ()).ok_or(FsError::NotFound)
}
fn exists(&self, path: &str) -> bool {
self.files.contains_key(path)
}
fn is_healthy(&self) -> bool {
true
}
}
fn cartridge_with_program_and_mode(
program: Vec<u8>,
capabilities: u64,
app_mode: AppMode,
) -> Cartridge {
Cartridge {
memcard_slots: None,
app_id: 42,
title: "Test Cart".into(),
app_version: "1.0.0".into(),
@@ -1,129 +1,155 @@
use super::*;
use prometeu_bytecode::registry::{LifecycleRole, NamedType, Signature, TypeId};
#[test]
fn tick_memcard_slot_roundtrip_for_game_profile() {
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
runtime.mount_fs(&mut log_service, &mut fs, &mut fs_state, Box::new(MemFsBackend::default()));
let mut vm = VirtualMachine::default();
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
let code = assemble(
"PUSH_I32 0\nPUSH_I32 0\nPUSH_CONST 0\nHOSTCALL 0\nPOP_N 2\nPUSH_I32 0\nHOSTCALL 1\nPOP_N 1\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 10\nHOSTCALL 2\nHALT",
)
.expect("assemble");
let program = serialized_single_function_module_with_consts(
fn memcard_cartridge(app_mode: AppMode, hook: &str) -> Cartridge {
let boot =
assemble("HOSTCALL 0\nPOP_N 1\nGET_GLOBAL 0\nGET_GLOBAL 1\nFRAME_SYNC\nHALT").unwrap();
let callback = assemble(hook).unwrap();
let mut code = boot.clone();
code.extend(&callback);
let program = TestProgram {
code,
vec![ConstantPoolEntry::String("6869".into())],
vec![
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: callback.len() as u32,
max_stack_slots: 16,
signature: Signature {
parameters: vec![NamedType { type_id: TypeId(0), name: None }],
results: vec![TypeId(1)],
},
..Default::default()
},
],
syscalls: vec![
SyscallDecl {
module: "mem".into(),
name: "slot_write".into(),
name: "bootstrap".into(),
version: 1,
arg_slots: 3,
arg_slots: 0,
ret_slots: 1,
},
SyscallDecl {
module: "mem".into(),
name: "slot_count".into(),
version: 1,
arg_slots: 1,
ret_slots: 2,
},
SyscallDecl {
module: "mem".into(),
name: "slot_commit".into(),
version: 1,
arg_slots: 1,
ret_slots: 1,
},
SyscallDecl {
module: "mem".into(),
name: "slot_read".into(),
version: 1,
arg_slots: 3,
ret_slots: 3,
arg_slots: 2,
ret_slots: 2,
},
],
);
let cartridge = Cartridge {
..Default::default()
};
Cartridge {
memcard_slots: Some(2),
app_id: 42,
title: "Memcard Game".into(),
app_version: "1.0.0".into(),
app_mode: AppMode::Game,
capabilities: caps::FS,
program,
title: "Memcard test".into(),
app_version: "1".into(),
app_mode,
capabilities: caps::MEMCARD,
program: program.serialize(),
assets: AssetsPayloadSource::empty(),
asset_table: vec![],
preload: vec![],
};
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
let report = runtime.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
);
assert!(report.is_none(), "memcard roundtrip must not crash");
assert!(vm.is_halted());
assert_eq!(
vm.operand_stack_top(3),
vec![Value::Int64(2), Value::String("6869".into()), Value::Int64(0)]
);
}
}
#[test]
fn tick_memcard_access_is_denied_for_non_game_profile() {
fn tick_memcard_boot_receives_admitted_context_and_precedes_first_frame() {
let cartridge = memcard_cartridge(
AppMode::Game,
"GET_LOCAL 0\nHOSTCALL 1\nSET_GLOBAL 0\nPOP_N 1\nGET_LOCAL 0\nPUSH_I32 0\nHOSTCALL 2\nSET_GLOBAL 1\nPOP_N 1\nPUSH_I32 0\nRET",
);
let mut runtime = VirtualMachineRuntime::new(None);
let mut log_service = LogService::new(4096);
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files: HashMap<u32, String> = HashMap::new();
let mut next_handle = 1;
let mut log = LogService::new(4096);
let mut vm = VirtualMachine::default();
runtime.initialize_vm(&mut log, &mut vm, &cartridge).unwrap();
let mut memcard = MemcardService::new();
let context = memcard.session.start_memory(42, 2, 1024 * 1024).unwrap();
memcard.session.begin_boot();
memcard.session.set_presentation(context, "Test", 1, 1, 1, &[0; 560], 0).unwrap();
let mut fs = VirtualFS::new();
let mut state = FsState::Unmounted;
let mut files = HashMap::new();
let mut next = 1;
let mut platform = TestPlatform::new();
let signals = InputSignals::default();
let code = assemble("HOSTCALL 0\nHALT").expect("assemble");
let program = serialized_single_function_module(
code,
vec![SyscallDecl {
module: "mem".into(),
name: "slot_count".into(),
version: 1,
arg_slots: 0,
ret_slots: 2,
}],
for expected in [None, Some(0)] {
assert!(
runtime
.tick(
&mut log,
&mut fs,
&mut state,
&mut memcard,
&mut files,
&mut next,
&mut vm,
&signals,
&mut platform
)
.is_none()
);
assert_eq!(vm.memcard_boot_result(), expected);
assert_eq!(runtime.logical_frame_index, 0);
}
let request = 1;
assert_eq!(
memcard.session.query(context, request).unwrap().state,
crate::memcard::session::RequestState::MemoryOnly
);
let cartridge = Cartridge {
app_id: 101,
title: "System App".into(),
app_version: "1.0.0".into(),
app_mode: AppMode::Shell,
capabilities: caps::FS,
program,
assets: AssetsPayloadSource::empty(),
asset_table: vec![],
preload: vec![],
};
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
let report = runtime.tick(
&mut log_service,
&mut fs,
&mut fs_state,
&mut memcard,
&mut open_files,
&mut next_handle,
&mut vm,
&signals,
&mut platform,
assert!(
runtime
.tick(
&mut log,
&mut fs,
&mut state,
&mut memcard,
&mut files,
&mut next,
&mut vm,
&signals,
&mut platform
)
.is_none()
);
assert!(report.is_none(), "non-game memcard call must return status");
assert!(vm.is_halted());
assert_eq!(vm.operand_stack_top(2), vec![Value::Int64(0), Value::Int64(4)]);
assert_eq!(runtime.logical_frame_index, 1);
assert_eq!(vm.operand_stack_top(2), vec![Value::Int64(1), Value::Int64(2)]);
assert!(vm.begin_memcard_boot(context as i64).is_err());
}
#[test]
fn tick_memcard_boot_is_denied_for_non_game_profile() {
let cartridge = memcard_cartridge(
AppMode::Shell,
"GET_LOCAL 0\nHOSTCALL 1\nPOP_N 2\nGET_LOCAL 0\nPUSH_I32 0\nHOSTCALL 2\nPOP_N 2\nPUSH_I32 0\nRET",
);
let mut runtime = VirtualMachineRuntime::new(None);
let mut log = LogService::new(4096);
let mut vm = VirtualMachine::default();
runtime.initialize_vm(&mut log, &mut vm, &cartridge).unwrap();
let mut memcard = MemcardService::new();
memcard.session.start_memory(42, 2, 1024 * 1024).unwrap();
memcard.session.begin_boot();
let report = runtime.tick(
&mut log,
&mut VirtualFS::new(),
&mut FsState::Unmounted,
&mut memcard,
&mut HashMap::new(),
&mut 1,
&mut vm,
&InputSignals::default(),
&mut TestPlatform::new(),
);
assert!(matches!(report, Some(CrashReport::VmTrap { .. })));
assert_eq!(vm.memcard_boot_result(), None);
}
@@ -70,12 +70,22 @@ impl VirtualMachineRuntime {
(glyph, sounds, scenes)
}
#[allow(clippy::too_many_arguments)]
pub fn debug_step_instruction(
&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,
) -> Option<CrashReport> {
if vm.memcard_boot_result() == Some(0) && memcard.session.boot_pending() {
return None;
}
let was_memcard_boot = vm.memcard_boot_active();
if vm.call_stack_is_empty()
&& let Err(error) = vm.prepare_boot_call()
{
@@ -85,23 +95,33 @@ impl VirtualMachineRuntime {
}
let step_result = {
let mut ctx = HostContext::new_platform(Some(platform));
let mut fs = VirtualFS::new();
let mut fs_state = FsState::Unmounted;
let mut memcard = MemcardService::new();
let mut open_files = HashMap::new();
let mut next_handle = 1;
let mut host = VmRuntimeHost {
runtime: self,
log_service,
fs: &mut fs,
fs_state: &mut fs_state,
memcard: &mut memcard,
open_files: &mut open_files,
next_handle: &mut next_handle,
fs,
fs_state,
memcard,
open_files,
next_handle,
};
vm.step(&mut host, &mut ctx)
};
if was_memcard_boot
&& step_result == Err(LogicalFrameEndingReason::LifecycleComplete)
&& let Err(error) = memcard.session.finish_boot(
vm.memcard_boot_result() == Some(0),
&memcard.lane,
Instant::now(),
)
{
let report = CrashReport::VmPanic {
message: format!("Memcard bootstrap failed: {error:?}: {}", memcard.diagnostic),
pc: Some(vm.pc() as u32),
};
self.last_crash_report = Some(report.clone());
return Some(report);
}
match step_result {
Ok(())
| Err(
@@ -201,6 +221,55 @@ impl VirtualMachineRuntime {
signals: &InputSignals,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if vm.memcard_boot_active() {
let reason = self.tick_lifecycle(
log_service,
fs,
fs_state,
mem_card,
open_files,
next_handle,
vm,
platform,
false,
);
let failure = match reason {
LogicalFrameEndingReason::LifecycleComplete => {
let ready = vm.memcard_boot_result() == Some(0);
mem_card.session.finish_boot(ready, &mem_card.lane, Instant::now()).err().map(
|error| CrashReport::VmPanic {
message: format!(
"Memcard bootstrap failed: {error:?}: {}",
mem_card.diagnostic
),
pc: Some(vm.pc() as u32),
},
)
}
LogicalFrameEndingReason::BudgetExhausted
| LogicalFrameEndingReason::Breakpoint => None,
LogicalFrameEndingReason::Trap(trap) => Some(CrashReport::VmTrap { trap }),
other => Some(CrashReport::VmPanic {
message: format!("Memcard bootstrap stopped: {other:?}"),
pc: Some(vm.pc() as u32),
}),
};
if let Some(report) = &failure {
self.last_crash_report = Some(report.clone());
}
return failure;
}
if vm.memcard_boot_result() == Some(0) {
if let Some(error) = mem_card.session.boot_error() {
return Some(CrashReport::VmPanic {
message: format!("Memcard registration failed: {error:?}"),
pc: Some(vm.pc() as u32),
});
}
if mem_card.session.boot_pending() {
return None;
}
}
let start = Instant::now();
self.tick_index += 1;