harden deterministic headless runtime control
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-09-23 07:09:46 +01:00
parent 2516fae4fc
commit 89101d1b20
14 changed files with 856 additions and 121 deletions
+173 -81
View File
@@ -2,20 +2,19 @@ use std::fmt;
use std::sync::Arc;
use prometeu_bytecode::Value;
use prometeu_drivers::MemoryBanks;
use prometeu_drivers::hardware::Hardware;
use prometeu_drivers::{LocalFramebufferRenderBackend, MemoryBanks};
use prometeu_firmware::firmware_state::{AppCrashesStep, ResetStep};
use prometeu_firmware::{BootTarget, Firmware, FirmwareState};
use prometeu_hal::{
AssetBridge, AudioBridge, FrameId, Game2DFrameComposer, InputPlatform, InputSignals,
OwnedRgba8888Frame, RenderBackend, RenderSubmission, RenderSubmissionSink, RenderSubmitError,
RenderWorkerError, RuntimePlatform, TelemetryPlatform,
RuntimePlatform, TelemetryPlatform,
};
use prometeu_system::{CrashReport, LatestRenderFrameStore, RenderWorkerConfig};
use prometeu_system::{CrashReport, LatestRenderFrameStore};
const BOOT_TICK_LIMIT: usize = 64;
const LOGICAL_FRAME_TICK_LIMIT: usize = 100_000;
const FRAME_PUBLISH_SPINS: usize = 10_000;
/// One published logical frame plus the automation counter.
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -30,26 +29,65 @@ pub struct HostState {
pub pc: usize,
pub stack_top: Vec<Value>,
pub frame_index: u64,
pub tick_index: u64,
pub app_id: u32,
pub status: HostExecutionStatus,
}
#[derive(Debug)]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HostExecutionStatus {
Running,
Paused,
Terminated,
Faulted,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AdvanceFrameOutcome {
FrameCompleted { logical_frame_index: u64, frame_id: FrameId },
Faulted(CrashReport),
Terminated,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum AdvanceFramesStop {
Completed,
Faulted(CrashReport),
Terminated,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct AdvanceFramesOutcome {
pub requested: u64,
pub completed: u64,
pub stop: AdvanceFramesStop,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum HostError {
BootFailed(String),
AlreadyBooted,
BootFailed { reason: String, report: Option<CrashReport> },
InvalidState { operation: &'static str, status: HostExecutionStatus },
LogicalFrameDidNotClose,
FrameNotPublished,
RenderWorker(RenderWorkerError),
FrameNotPublished { previous: Option<FrameId> },
NoFrameAvailable,
}
impl fmt::Display for HostError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
match self {
Self::BootFailed(reason) => write!(f, "boot failed: {reason}"),
Self::AlreadyBooted => write!(f, "boot requires reset before another attempt"),
Self::BootFailed { reason, .. } => write!(f, "boot failed: {reason}"),
Self::InvalidState { operation, status } => {
write!(f, "{operation} is invalid while execution is {status:?}")
}
Self::LogicalFrameDidNotClose => {
write!(f, "logical frame did not reach FrameSync, end of ROM, or a fault")
}
Self::FrameNotPublished => write!(f, "logical frame closed without a published frame"),
Self::RenderWorker(error) => write!(f, "render worker failed: {error:?}"),
Self::FrameNotPublished { .. } => {
write!(f, "logical frame closed without its canonical published frame")
}
Self::NoFrameAvailable => write!(f, "no completed frame is available for capture"),
}
}
}
@@ -61,8 +99,14 @@ pub struct HeadlessHost {
firmware: Firmware,
platform: HeadlessPlatform,
signals: InputSignals,
/// Frame id observed before the logical frame that `capture_frame` should return.
previous_frame_id: Option<FrameId>,
boot_attempted: bool,
last_completed_frame: Option<CompletedFrame>,
}
#[derive(Debug, Clone, Copy)]
struct CompletedFrame {
logical_frame_index: u64,
frame_id: FrameId,
}
struct HeadlessPlatform {
@@ -79,7 +123,8 @@ impl HeadlessHost {
firmware: Firmware::new(None),
platform: HeadlessPlatform { hardware, store },
signals: InputSignals::default(),
previous_frame_id: None,
boot_attempted: false,
last_completed_frame: None,
}
}
@@ -88,26 +133,30 @@ impl HeadlessHost {
/// The transition into `GameRunning` is the last tick. The first game
/// logical frame stays available for [`Self::advance_frame`].
pub fn boot(&mut self, path: impl Into<String>) -> Result<(), HostError> {
if self.boot_attempted {
return Err(HostError::AlreadyBooted);
}
self.boot_attempted = true;
let path = path.into();
self.firmware.boot_target = BootTarget::Cartridge { path, debug: false, debug_port: 7777 };
self.ensure_worker()?;
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
return Ok(());
}
for _ in 0..BOOT_TICK_LIMIT {
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
return Ok(());
}
if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) {
let detail = self
.get_fault()
.map(|report| report.summary())
let report = self.get_fault();
let reason = report
.as_ref()
.map(CrashReport::summary)
.unwrap_or_else(|| "cartridge crashed during boot".to_string());
return Err(HostError::BootFailed(detail));
return Err(HostError::BootFailed { reason, report });
}
if matches!(self.firmware.state, FirmwareState::HubHome(_)) {
return Err(HostError::BootFailed("cartridge did not load".to_string()));
return Err(HostError::BootFailed {
reason: "cartridge did not load".to_string(),
report: None,
});
}
self.tick_once();
}
@@ -115,7 +164,10 @@ impl HeadlessHost {
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
Ok(())
} else {
Err(HostError::BootFailed("boot did not reach the game".to_string()))
Err(HostError::BootFailed {
reason: "boot did not reach the game".to_string(),
report: self.get_fault(),
})
}
}
@@ -126,51 +178,101 @@ impl HeadlessHost {
&self.signals,
&mut self.platform,
);
self.previous_frame_id = self.platform.store.latest_frame().map(|frame| frame.frame_id);
self.platform.store = LatestRenderFrameStore::default();
self.boot_attempted = false;
self.last_completed_frame = None;
}
pub fn pause(&mut self) {
pub fn pause(&mut self) -> Result<(), HostError> {
self.require_active("pause")?;
self.firmware.os.vm().set_paused(true);
Ok(())
}
pub fn resume(&mut self) {
pub fn resume(&mut self) -> Result<(), HostError> {
self.require_active("resume")?;
self.firmware.os.vm().set_paused(false);
Ok(())
}
/// Execute one VM instruction. This does not close a logical frame.
pub fn step(&mut self) -> Option<CrashReport> {
pub fn step(&mut self) -> Result<Option<CrashReport>, HostError> {
self.require_active("step")?;
self.firmware.os.vm().set_paused(true);
let report = self.firmware.os.vm().debug_step_active_session(&mut self.platform);
self.platform.hardware.audio.clear_commands();
report
Ok(report)
}
pub fn advance_frame(&mut self) -> Result<(), HostError> {
pub fn advance_frame(&mut self) -> Result<AdvanceFrameOutcome, HostError> {
if let Some(report) = self.get_fault() {
return Ok(AdvanceFrameOutcome::Faulted(report));
}
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
return Ok(AdvanceFrameOutcome::Terminated);
}
let start = self.firmware.os.vm().logical_frame_index();
self.previous_frame_id = self.platform.store.latest_frame().map(|frame| frame.frame_id);
let previous_frame_id = self.platform.store.latest_frame().map(|frame| frame.frame_id);
self.firmware.os.vm().set_paused(false);
self.firmware.os.vm().request_debug_step();
for _ in 0..LOGICAL_FRAME_TICK_LIMIT {
self.tick_once();
if self.fault_is_visible() {
self.firmware.os.vm().set_paused(true);
return Ok(());
if let Some(report) = self.get_fault() {
self.finish_frame_step();
return Ok(AdvanceFrameOutcome::Faulted(report));
}
if self.firmware.os.vm().logical_frame_index() > start {
self.firmware.os.vm().set_paused(true);
return Ok(());
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
return Ok(AdvanceFrameOutcome::Terminated);
}
let logical_frame_index = self.firmware.os.vm().logical_frame_index();
if logical_frame_index > start {
self.finish_frame_step();
let frame = self
.platform
.store
.latest_frame()
.ok_or(HostError::FrameNotPublished { previous: previous_frame_id })?;
if Some(frame.frame_id) == previous_frame_id {
return Err(HostError::FrameNotPublished { previous: previous_frame_id });
}
self.last_completed_frame =
Some(CompletedFrame { logical_frame_index, frame_id: frame.frame_id });
return Ok(AdvanceFrameOutcome::FrameCompleted {
logical_frame_index,
frame_id: frame.frame_id,
});
}
}
self.finish_frame_step();
Err(HostError::LogicalFrameDidNotClose)
}
pub fn advance_frames(&mut self, count: u64) -> Result<(), HostError> {
pub fn advance_frames(&mut self, count: u64) -> Result<AdvanceFramesOutcome, HostError> {
let mut completed = 0;
for _ in 0..count {
self.advance_frame()?;
match self.advance_frame()? {
AdvanceFrameOutcome::FrameCompleted { .. } => completed += 1,
AdvanceFrameOutcome::Faulted(report) => {
return Ok(AdvanceFramesOutcome {
requested: count,
completed,
stop: AdvanceFramesStop::Faulted(report),
});
}
AdvanceFrameOutcome::Terminated => {
return Ok(AdvanceFramesOutcome {
requested: count,
completed,
stop: AdvanceFramesStop::Terminated,
});
}
}
}
Ok(())
Ok(AdvanceFramesOutcome { requested: count, completed, stop: AdvanceFramesStop::Completed })
}
pub fn set_input(&mut self, signals: InputSignals) {
@@ -185,20 +287,24 @@ impl HeadlessHost {
self.signals.right_signal = down;
}
pub fn capture_frame(&mut self) -> Result<CapturedFrame, HostError> {
let frame = self.wait_for_published_frame(self.previous_frame_id)?;
Ok(CapturedFrame {
logical_frame_index: self.firmware.os.vm().logical_frame_index(),
frame,
})
pub fn capture_frame(&self) -> Result<CapturedFrame, HostError> {
let completed = self.last_completed_frame.ok_or(HostError::NoFrameAvailable)?;
let frame = self.platform.store.latest_frame().ok_or(HostError::NoFrameAvailable)?;
if frame.frame_id != completed.frame_id {
return Err(HostError::FrameNotPublished { previous: Some(completed.frame_id) });
}
Ok(CapturedFrame { logical_frame_index: completed.logical_frame_index, frame })
}
pub fn get_state(&mut self) -> HostState {
let status = self.execution_status();
HostState {
pc: self.firmware.os.vm().active_pc().unwrap_or(0),
stack_top: self.firmware.os.vm().active_operand_stack_top(10),
frame_index: self.firmware.os.vm().logical_frame_index(),
tick_index: self.firmware.os.vm().tick_index(),
app_id: self.firmware.os.vm().current_app_id(),
status,
}
}
@@ -217,49 +323,35 @@ impl HeadlessHost {
self.platform.hardware.audio.clear_commands();
}
fn execution_status(&mut self) -> HostExecutionStatus {
if self.fault_is_visible() {
HostExecutionStatus::Faulted
} else if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
HostExecutionStatus::Terminated
} else if self.firmware.os.vm().paused() {
HostExecutionStatus::Paused
} else {
HostExecutionStatus::Running
}
}
fn fault_is_visible(&mut self) -> bool {
self.firmware.os.vm().last_crash_report().is_some()
|| matches!(self.firmware.state, FirmwareState::AppCrashes(_))
}
fn ensure_worker(&mut self) -> Result<(), HostError> {
if self.firmware.os.vm().render_worker_controller().is_some() {
return Ok(());
fn require_active(&mut self, operation: &'static str) -> Result<(), HostError> {
let status = self.execution_status();
if matches!(status, HostExecutionStatus::Running | HostExecutionStatus::Paused) {
Ok(())
} else {
Err(HostError::InvalidState { operation, status })
}
let backend = LocalFramebufferRenderBackend::new_with_memory_banks(
Hardware::W,
Hardware::H,
Arc::clone(&self.platform.hardware.memory_banks),
self.platform.hardware.assets.glyph_asset_slot_index(),
);
let store = self.platform.store.clone();
self.firmware.os.vm().start_render_worker(RenderWorkerConfig::default(), backend, store);
Ok(())
}
fn wait_for_published_frame(
&mut self,
previous: Option<FrameId>,
) -> Result<OwnedRgba8888Frame, HostError> {
for _ in 0..FRAME_PUBLISH_SPINS {
if let Some(error) = self
.firmware
.os
.vm()
.render_worker_controller()
.and_then(|worker| worker.last_error())
{
return Err(HostError::RenderWorker(error));
}
if let Some(frame) = self.platform.store.latest_frame()
&& Some(frame.frame_id) != previous
{
return Ok(frame);
}
std::hint::spin_loop();
}
Err(HostError::FrameNotPublished)
fn finish_frame_step(&mut self) {
self.firmware.os.vm().set_paused(true);
self.firmware.os.vm().clear_debug_step_request();
}
}
@@ -8,4 +8,7 @@
mod host;
pub use host::{CapturedFrame, HeadlessHost, HostError, HostState};
pub use host::{
AdvanceFrameOutcome, AdvanceFramesOutcome, AdvanceFramesStop, CapturedFrame, HeadlessHost,
HostError, HostExecutionStatus, HostState,
};