harden deterministic headless runtime control
This commit is contained in:
@@ -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();
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user