add headless automation
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good

This commit is contained in:
2026-09-22 13:28:31 +01:00
parent 5b106af0f3
commit e0c08c8b00
15 changed files with 883 additions and 47 deletions
@@ -0,0 +1,333 @@
use std::fmt;
use std::sync::Arc;
use prometeu_bytecode::Value;
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,
};
use prometeu_system::{CrashReport, LatestRenderFrameStore, RenderWorkerConfig};
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)]
pub struct CapturedFrame {
pub logical_frame_index: u64,
pub frame: OwnedRgba8888Frame,
}
/// Debugger-shaped execution snapshot.
#[derive(Debug, Clone)]
pub struct HostState {
pub pc: usize,
pub stack_top: Vec<Value>,
pub frame_index: u64,
pub app_id: u32,
}
#[derive(Debug)]
pub enum HostError {
BootFailed(String),
LogicalFrameDidNotClose,
FrameNotPublished,
RenderWorker(RenderWorkerError),
}
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::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:?}"),
}
}
}
impl std::error::Error for HostError {}
/// In-process host. The desktop winit runner is a separate crate and is not linked here.
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>,
}
struct HeadlessPlatform {
hardware: Hardware,
store: LatestRenderFrameStore,
}
impl HeadlessHost {
pub fn new() -> Self {
let memory_banks = Arc::new(MemoryBanks::new());
let hardware = Hardware::new_with_memory_banks(Arc::clone(&memory_banks));
let store = LatestRenderFrameStore::default();
Self {
firmware: Firmware::new(None),
platform: HeadlessPlatform { hardware, store },
signals: InputSignals::default(),
previous_frame_id: None,
}
}
/// Load `path` and tick until the firmware is in `GameRunning`.
///
/// 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> {
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())
.unwrap_or_else(|| "cartridge crashed during boot".to_string());
return Err(HostError::BootFailed(detail));
}
if matches!(self.firmware.state, FirmwareState::HubHome(_)) {
return Err(HostError::BootFailed("cartridge did not load".to_string()));
}
self.tick_once();
}
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
Ok(())
} else {
Err(HostError::BootFailed("boot did not reach the game".to_string()))
}
}
pub fn reset(&mut self) {
self.signals = InputSignals::default();
self.firmware.change_state(
FirmwareState::Reset(ResetStep),
&self.signals,
&mut self.platform,
);
self.previous_frame_id = self.platform.store.latest_frame().map(|frame| frame.frame_id);
}
pub fn pause(&mut self) {
self.firmware.os.vm().set_paused(true);
}
pub fn resume(&mut self) {
self.firmware.os.vm().set_paused(false);
}
/// Execute one VM instruction. This does not close a logical frame.
pub fn step(&mut self) -> Option<CrashReport> {
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
}
pub fn advance_frame(&mut self) -> Result<(), HostError> {
let start = self.firmware.os.vm().logical_frame_index();
self.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 self.firmware.os.vm().logical_frame_index() > start {
self.firmware.os.vm().set_paused(true);
return Ok(());
}
}
Err(HostError::LogicalFrameDidNotClose)
}
pub fn advance_frames(&mut self, count: u64) -> Result<(), HostError> {
for _ in 0..count {
self.advance_frame()?;
}
Ok(())
}
pub fn set_input(&mut self, signals: InputSignals) {
self.signals = signals;
}
pub fn clear_input(&mut self) {
self.signals = InputSignals::default();
}
pub fn set_right(&mut self, down: bool) {
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 get_state(&mut self) -> HostState {
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(),
app_id: self.firmware.os.vm().current_app_id(),
}
}
pub fn get_fault(&mut self) -> Option<CrashReport> {
if let Some(report) = self.firmware.os.vm().last_crash_report() {
return Some(report.clone());
}
match &self.firmware.state {
FirmwareState::AppCrashes(AppCrashesStep { report }) => Some(report.clone()),
_ => None,
}
}
fn tick_once(&mut self) {
self.firmware.tick(&self.signals, &mut self.platform);
self.platform.hardware.audio.clear_commands();
}
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(());
}
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)
}
}
impl Default for HeadlessHost {
fn default() -> Self {
Self::new()
}
}
impl RenderSubmissionSink for HeadlessPlatform {
fn submit_render_submission(
&mut self,
submission: RenderSubmission,
) -> Result<(), RenderSubmitError> {
let frame_id = submission.frame_id;
let ownership = submission.ownership;
self.hardware.submit_render_submission(submission)?;
let (width, height) = self.hardware.gfx.size();
let pixels = self.hardware.gfx.front_buffer().to_vec();
let frame = OwnedRgba8888Frame::packed(frame_id, ownership, width, height, pixels)
.map_err(|_| RenderSubmitError::SubmissionRejected)?;
self.store.publish_frame(frame);
Ok(())
}
}
impl RuntimePlatform for HeadlessPlatform {
fn display_size(&self) -> (usize, usize) {
(Hardware::W, Hardware::H)
}
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
self
}
fn render_backend(&mut self) -> &mut dyn RenderBackend {
&mut self.hardware
}
fn game2d_frame_composer(&mut self) -> &mut dyn Game2DFrameComposer {
&mut self.hardware
}
fn audio(&self) -> &dyn AudioBridge {
self.hardware.audio()
}
fn audio_mut(&mut self) -> &mut dyn AudioBridge {
self.hardware.audio_mut()
}
fn input(&self) -> &dyn InputPlatform {
self.hardware.input()
}
fn input_mut(&mut self) -> &mut dyn InputPlatform {
self.hardware.input_mut()
}
fn assets(&self) -> &dyn AssetBridge {
self.hardware.assets()
}
fn assets_mut(&mut self) -> &mut dyn AssetBridge {
self.hardware.assets_mut()
}
fn telemetry(&self) -> &dyn TelemetryPlatform {
self.hardware.telemetry()
}
}