added comments extensively

This commit is contained in:
Nilton Constantino
2026-01-19 07:47:54 +00:00
parent 0f3105d622
commit 13ecbd1877
10 changed files with 446 additions and 104 deletions
+26 -2
View File
@@ -9,16 +9,28 @@ use crate::virtual_machine::VirtualMachine;
use crate::telemetry::CertificationConfig;
/// PROMETEU Firmware.
///
/// The central orchestrator of the system. It manages the high-level state machine,
/// transitioning between system states like booting, the Hub launcher, and
/// actual application execution.
pub struct Firmware {
/// The Virtual Machine instance.
pub vm: VirtualMachine,
/// The System Operating logic (syscalls, telemetry, logs).
pub os: PrometeuOS,
/// The System UI / Launcher environment.
pub hub: PrometeuHub,
/// Current high-level state of the system.
pub state: FirmwareState,
/// Desired execution target resolved at boot.
pub boot_target: BootTarget,
/// Tracking flag to ensure `on_enter` is called exactly once per state transition.
state_initialized: bool,
}
impl Firmware {
/// Initializes the firmware in the `Reset` state.
pub fn new(cap_config: Option<CertificationConfig>) -> Self {
Self {
vm: VirtualMachine::default(),
@@ -30,31 +42,40 @@ impl Firmware {
}
}
/// The main entry point for the Host to advance the system logic.
///
/// This method is called exactly once per Host frame (60Hz).
/// It updates peripheral signals and delegates the logic to the current state.
pub fn step_frame(&mut self, signals: &InputSignals, hw: &mut dyn HardwareBridge) {
// Updates input once per host frame
// 1. Update peripheral state using the latest signals from the Host.
// This ensures input is consistent throughout the entire update.
hw.pad_mut().begin_frame(signals);
hw.touch_mut().begin_frame(signals);
// 2. State machine lifecycle management.
if !self.state_initialized {
self.on_enter(signals, hw);
self.state_initialized = true;
}
// 3. Update the current state and check for transitions.
if let Some(next_state) = self.on_update(signals, hw) {
self.change_state(next_state, signals, hw);
}
}
/// Transitions the system to a new state, handling lifecycle hooks.
pub fn change_state(&mut self, new_state: FirmwareState, signals: &InputSignals, hw: &mut dyn HardwareBridge) {
self.on_exit(signals, hw);
self.state = new_state;
self.state_initialized = false;
// Enters the new state immediately
// Enter the new state immediately to avoid "empty" frames during transitions.
self.on_enter(signals, hw);
self.state_initialized = true;
}
/// Dispatches the `on_enter` event to the current state implementation.
fn on_enter(&mut self, signals: &InputSignals, hw: &mut dyn HardwareBridge) {
let mut req = PrometeuContext {
vm: &mut self.vm,
@@ -75,6 +96,8 @@ impl Firmware {
}
}
/// Dispatches the `on_update` event to the current state implementation.
/// Returns an optional `FirmwareState` if a transition is requested.
fn on_update(&mut self, signals: &InputSignals, hw: &mut dyn HardwareBridge) -> Option<FirmwareState> {
let mut req = PrometeuContext {
vm: &mut self.vm,
@@ -95,6 +118,7 @@ impl Firmware {
}
}
/// Dispatches the `on_exit` event to the current state implementation.
fn on_exit(&mut self, signals: &InputSignals, hw: &mut dyn HardwareBridge) {
let mut req = PrometeuContext {
vm: &mut self.vm,
+48 -4
View File
@@ -1,22 +1,39 @@
use crate::model::Sample;
use std::sync::Arc;
/// Maximum number of simultaneous audio voices supported by the hardware.
pub const MAX_CHANNELS: usize = 16;
/// Standard sample rate for the final audio output.
pub const OUTPUT_SAMPLE_RATE: u32 = 48000;
#[derive(Clone, Copy, Debug, PartialEq)]
/// Defines if a sample should stop at the end or repeat indefinitely.
#[derive(Clone, Copy, Debug, PartialEq, Default)]
pub enum LoopMode {
/// Play once and stop.
#[default]
Off,
/// Return to the start (or loop_start) when reaching the end.
On,
}
/// State of a single playback voice (channel).
///
/// The Core maintains this state to provide information to the App (e.g., is_playing),
/// but the actual real-time mixing is performed by the Host using commands.
pub struct Channel {
/// Reference to the PCM data being played.
pub sample: Option<Arc<Sample>>,
/// Current playback position within the sample (fractional for pitch shifting).
pub pos: f64,
/// Playback speed multiplier (1.0 = original speed).
pub pitch: f64,
pub volume: u8, // 0..255
pub pan: u8, // 0..255
/// Voice volume (0-255).
pub volume: u8,
/// Stereo panning (0=Full Left, 127=Center, 255=Full Right).
pub pan: u8,
/// Loop configuration for this voice.
pub loop_mode: LoopMode,
/// Playback priority (used for voice stealing policies).
pub priority: u8,
}
@@ -34,7 +51,12 @@ impl Default for Channel {
}
}
/// Commands sent from the Core to the Host audio backend.
///
/// Because the Core logic runs at 60Hz and Audio is generated at 48kHz,
/// we use an asynchronous command queue to synchronize them.
pub enum AudioCommand {
/// Start playing a sample on a specific voice.
Play {
sample: Arc<Sample>,
voice_id: usize,
@@ -44,32 +66,54 @@ pub enum AudioCommand {
priority: u8,
loop_mode: LoopMode,
},
/// Immediately stop playback on a voice.
Stop {
voice_id: usize,
},
/// Update volume of an ongoing playback.
SetVolume {
voice_id: usize,
volume: u8,
},
/// Update panning of an ongoing playback.
SetPan {
voice_id: usize,
pan: u8,
},
/// Update pitch of an ongoing playback.
SetPitch {
voice_id: usize,
pitch: f64,
},
}
/// PROMETEU Audio Subsystem.
///
/// Models a multi-channel PCM sampler.
/// It works like an "Audio CPU": the Game Core sends high-level commands
/// every frame, and the Host backend implements the low-level mixer.
pub struct Audio {
/// Local state of the 16 hardware voices.
pub voices: [Channel; MAX_CHANNELS],
/// Queue of pending commands to be processed by the Host mixer.
pub commands: Vec<AudioCommand>,
}
impl Audio {
/// Initializes the audio system with empty voices.
pub fn new() -> Self {
const EMPTY_CHANNEL: Channel = Channel {
sample: None,
pos: 0.0,
pitch: 1.0,
volume: 255,
pan: 127,
loop_mode: LoopMode::Off,
priority: 0,
};
Self {
voices: Default::default(),
voices: [EMPTY_CHANNEL; MAX_CHANNELS],
commands: Vec::new(),
}
}
+71 -29
View File
@@ -1,42 +1,71 @@
use crate::model::{Color, HudTileLayer, ScrollableTileLayer, Sprite, TileBank, TileMap, TileSize};
use std::mem::size_of;
/// Blending modes inspired by classic 16-bit hardware.
/// Defines how source pixels are combined with existing pixels in the framebuffer.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub enum BlendMode {
/// dst = src
/// No blending: source overwrites destination.
#[default]
None,
/// dst = (src + dst) / 2
/// Average: dst = (src + dst) / 2. Creates a semi-transparent effect.
Half,
/// dst = dst + (src / 2)
/// Additive: dst = dst + (src / 2). Good for glows/light.
HalfPlus,
/// dst = dst - (src / 2)
/// Subtractive: dst = dst - (src / 2). Good for shadows.
HalfMinus,
/// dst = dst + src
/// Full Additive: dst = dst + src. Saturated light effect.
Full,
}
/// PROMETEU Graphics Subsystem (GFX).
///
/// Models a specialized graphics chip with a fixed resolution, double buffering,
/// and a multi-layered tile/sprite architecture.
///
/// Composition Order (back to front):
/// 1. Sprites with priority 0 (optional background objects)
/// 2. Tile Layer 0 + Sprites with priority 1
/// 3. Tile Layer 1 + Sprites with priority 2
/// 4. Tile Layer 2 + Sprites with priority 3
/// 5. Tile Layer 3 + Sprites with priority 4
/// 6. Scene Fade effect
/// 7. HUD Layer (always on top)
/// 8. HUD Fade effect
pub struct Gfx {
/// Width of the internal framebuffer.
w: usize,
/// Height of the internal framebuffer.
h: usize,
/// Front buffer: the one currently being displayed by the Host.
front: Vec<u16>,
/// Back buffer: the one being drawn to during the current frame.
back: Vec<u16>,
/// 4 scrollable backgrounds.
pub layers: [ScrollableTileLayer; 4],
/// 1 fixed layer for User Interface.
pub hud: HudTileLayer,
/// Up to 16 sets of graphical assets (tiles + palettes).
pub banks: [Option<TileBank>; 16],
/// Hardware sprites (Object Attribute Memory equivalent).
pub sprites: [Sprite; 512],
pub scene_fade_level: u8, // 0..31
/// Current transparency level for the main scene (0=invisible, 31=fully visible).
pub scene_fade_level: u8,
/// Color used for the scene fade effect.
pub scene_fade_color: Color,
pub hud_fade_level: u8, // 0..31
/// Current transparency level for the HUD (independent of scene).
pub hud_fade_level: u8,
/// Color used for the HUD fade effect.
pub hud_fade_color: Color,
// Priority cache to avoid per-frame allocations
/// Internal cache used to sort sprites by priority without allocations.
priority_buckets: [Vec<usize>; 5],
}
impl Gfx {
/// Initializes the graphics system with a specific resolution.
pub fn new(w: usize, h: usize) -> Self {
const EMPTY_BANK: Option<TileBank> = None;
const EMPTY_SPRITE: Sprite = Sprite {
@@ -51,7 +80,7 @@ impl Gfx {
};
let len = w * h;
let mut layers = [
let layers = [
ScrollableTileLayer::new(64, 64, TileSize::Size16),
ScrollableTileLayer::new(64, 64, TileSize::Size16),
ScrollableTileLayer::new(64, 64, TileSize::Size16),
@@ -130,15 +159,19 @@ impl Gfx {
}
/// Double buffer swap (O(1), no pixel copying).
/// Typically called by the Host when it's time to display the finished frame.
pub fn present(&mut self) {
std::mem::swap(&mut self.front, &mut self.back);
}
/// Main frame rendering pipeline.
/// Follows the priority order from the manual (Chapter 4.11).
/// The main rendering pipeline.
///
/// This method composes the final frame by rasterizing layers and sprites in the
/// correct priority order into the back buffer.
/// Follows the hardware model where layers and sprites are composed every frame.
pub fn render_all(&mut self) {
// 0. Preparation Phase: Organizes what should be drawn in each layer
// Clears the buckets without deallocating memory
// 0. Preparation Phase: Filter and group sprites by their priority levels.
// This avoids iterating through all 512 sprites for every layer.
for bucket in self.priority_buckets.iter_mut() {
bucket.clear();
}
@@ -149,30 +182,32 @@ impl Gfx {
}
}
// 1. Priority 0 sprites (Behind Layer 0 - the very back)
// 1. Priority 0 sprites: drawn at the very back, behind everything else.
Self::draw_bucket_on_buffer(&mut self.back, self.w, self.h, &self.priority_buckets[0], &self.sprites, &self.banks);
// 2. Main layers and prioritized sprites.
// Order: Layer 0 -> Sprites 1 -> Layer 1 -> Sprites 2 ...
for i in 0..self.layers.len() {
// 2. Game Layers (0 to 3)
let bank_id = self.layers[i].bank_id as usize;
if let Some(Some(bank)) = self.banks.get(bank_id) {
Self::draw_tile_map(&mut self.back, self.w, self.h, &self.layers[i].map, bank, self.layers[i].scroll_x, self.layers[i].scroll_y);
}
// 3. Sprites according to priority
// Draw sprites that belong to this depth level
Self::draw_bucket_on_buffer(&mut self.back, self.w, self.h, &self.priority_buckets[i + 1], &self.sprites, &self.banks);
}
// 4. Applies Scene Fade (Affects everything drawn so far)
// 4. Scene Fade: Applies a color blend to the entire world (excluding HUD).
Self::apply_fade_to_buffer(&mut self.back, self.scene_fade_level, self.scene_fade_color);
// 5. HUD (Always on top)
// 5. HUD: The fixed interface layer, always drawn on top of the world.
self.render_hud();
// 6. Applies HUD Fade (Optional, HUD only)
// 6. HUD Fade: Independent fade effect for the UI.
Self::apply_fade_to_buffer(&mut self.back, self.hud_fade_level, self.hud_fade_color);
}
/// Renders a specific game layer.
pub fn render_layer(&mut self, layer_idx: usize) {
if layer_idx >= self.layers.len() { return; }
@@ -188,7 +223,7 @@ impl Gfx {
Self::draw_tile_map(&mut self.back, self.w, self.h, &self.layers[layer_idx].map, bank, scroll_x, scroll_y);
}
/// Renders the HUD (no scroll).
/// Renders the HUD (fixed position, no scroll).
pub fn render_hud(&mut self) {
let bank_id = self.hud.bank_id as usize;
let bank = match self.banks.get(bank_id) {
@@ -199,6 +234,7 @@ impl Gfx {
Self::draw_tile_map(&mut self.back, self.w, self.h, &self.hud.map, bank, 0, 0);
}
/// Rasterizes a TileMap into the provided pixel buffer using scrolling.
fn draw_tile_map(
back: &mut [u16],
screen_w: usize,
@@ -210,30 +246,34 @@ impl Gfx {
) {
let tile_size = bank.tile_size as usize;
// 1. Calculate how many tiles fit on the screen (with margin of 1 for scroll)
// 1. Determine the range of visible tiles based on the scroll position.
// We add a margin of 1 tile to ensure smooth pixel-perfect scrolling at the borders.
let visible_tiles_x = (screen_w / tile_size) + 1;
let visible_tiles_y = (screen_h / tile_size) + 1;
// 2. Calculate the initial offset (where the first tile starts being drawn)
// 2. Calculate offsets within the tilemap.
let start_tile_x = scroll_x / tile_size as i32;
let start_tile_y = scroll_y / tile_size as i32;
// 3. Fine scroll: how many pixels the tiles are shifted within the first visible cell.
let fine_scroll_x = scroll_x % tile_size as i32;
let fine_scroll_y = scroll_y % tile_size as i32;
// 3. Loop by Tile (Much more efficient)
// 4. Iterate only through the tiles that are actually visible on screen.
for ty in 0..visible_tiles_y {
for tx in 0..visible_tiles_x {
let map_x = (start_tile_x + tx as i32) as usize;
let map_y = (start_tile_y + ty as i32) as usize;
// Skip if outside map bounds
// Bounds check: don't draw if the camera is outside the map.
if map_x >= map.width || map_y >= map.height { continue; }
let tile = map.tiles[map_y * map.width + map_x];
// Optimized skip for empty (ID 0) tiles.
if tile.id == 0 { continue; }
// 4. Draws the tile block on the screen
// 5. Project the tile pixels to screen space.
let screen_tile_x = (tx as i32 * tile_size as i32) - fine_scroll_x;
let screen_tile_y = (ty as i32 * tile_size as i32) - fine_scroll_y;
@@ -242,7 +282,8 @@ impl Gfx {
}
}
// Helper function to draw a block of 8x8, 16x16 or 32x32 pixels
/// Internal helper to copy a single tile's pixels to the framebuffer.
/// Handles flipping and palette resolution.
fn draw_tile_pixels(back: &mut [u16], screen_w: usize, screen_h: usize, x: i32, y: i32, tile: crate::model::Tile, bank: &TileBank) {
let size = bank.tile_size as usize;
@@ -254,16 +295,17 @@ impl Gfx {
let world_x = x + local_x as i32;
if world_x < 0 || world_x >= screen_w as i32 { continue; }
// Handle flip flags by reversing the fetch coordinates.
let fetch_x = if tile.flip_x { size - 1 - local_x } else { local_x };
let fetch_y = if tile.flip_y { size - 1 - local_y } else { local_y };
// 1. Gets the pixel index in the bank
// 1. Get the pixel color index (0-15) from the bank.
let px_index = bank.get_pixel_index(tile.id, fetch_x, fetch_y);
// 2. Rule: Index 0 is transparent
// 2. Hardware rule: Color index 0 is always fully transparent.
if px_index == 0 { continue; }
// 3. Resolves the color using the tile's palette
// 3. Resolve the virtual index to a real RGB565 color using the tile's assigned palette.
let color = bank.resolve_color(tile.palette_id, px_index);
back[world_y as usize * screen_w + world_x as usize] = color.raw();
@@ -1,9 +1,17 @@
use crate::hardware::{Audio, Gfx, HardwareBridge, Pad, Touch};
/// Aggregate structure for all virtual hardware peripherals.
///
/// This struct represents the "Mainboard" of the PROMETEU console,
/// containing instances of GFX, Audio, Input (Pad), and Touch.
pub struct Hardware {
/// The Graphics Processing Unit.
pub gfx: Gfx,
/// The Sound Processing Unit.
pub audio: Audio,
/// The standard digital gamepad.
pub pad: Pad,
/// The absolute pointer input device.
pub touch: Touch,
}
@@ -22,9 +30,12 @@ impl HardwareBridge for Hardware {
}
impl Hardware {
/// Internal hardware width in pixels.
pub const W: usize = 320;
/// Internal hardware height in pixels.
pub const H: usize = 180;
/// Creates a fresh hardware instance with default settings.
pub fn new() -> Self {
Self {
gfx: Gfx::new(Self::W, Self::H),
+23 -8
View File
@@ -1,24 +1,38 @@
use crate::model::Color;
/// Standard sizes for square tiles.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum TileSize {
/// 8x8 pixels.
Size8 = 8,
/// 16x16 pixels.
Size16 = 16,
/// 32x32 pixels.
Size32 = 32,
}
/// A container for graphical assets.
///
/// A TileBank stores both the raw pixel data (as palette indices) and the
/// color palettes themselves. This encapsulates all the information needed
/// to render a set of tiles.
pub struct TileBank {
/// Dimension of each individual tile in the bank.
pub tile_size: TileSize,
pub width: usize, // in pixels
pub height: usize, // in pixels
/// Width of the full bank sheet in pixels.
pub width: usize,
/// Height of the full bank sheet in pixels.
pub height: usize,
/// Now we store indices from 0 to 15 (4 bits per pixel simulated in 8 bits)
/// Pixel data stored as 4-bit indices (packed into 8-bit values).
/// Index 0 is always reserved for transparency.
pub pixel_indices: Vec<u8>,
/// 256 palettes, each with 16 colors (RGB565 as u16)
/// Table of 256 palettes, each containing 16 RGB565 colors.
pub palettes: [[Color; 16]; 256],
}
impl TileBank {
/// Creates an empty tile bank with the specified dimensions.
pub fn new(tile_size: TileSize, width: usize, height: usize) -> Self {
Self {
tile_size,
@@ -29,7 +43,7 @@ impl TileBank {
}
}
/// Returns the color of a specific pixel inside a tile.
/// Resolves a global tile ID and local pixel coordinates to a palette index.
/// tile_id: the tile index in the bank
/// local_x, local_y: the pixel position inside the tile (0 to tile_size-1)
pub fn get_pixel_index(&self, tile_id: u16, local_x: usize, local_y: usize) -> u8 {
@@ -44,13 +58,14 @@ impl TileBank {
if pixel_x < self.width && pixel_y < self.height {
self.pixel_indices[pixel_y * self.width + pixel_x]
} else {
0 // Outside the bank = Transparent
0 // Default to transparent if out of bounds
}
}
/// Resolves a pixel index to a real Color using a palette.
/// Maps a 4-bit index to a real RGB565 Color using the specified palette.
pub fn resolve_color(&self, palette_id: u8, pixel_index: u8) -> Color {
// Rule: Index 0 is always transparent (we use MAGENTA/COLOR_KEY as vacuum)
// Hardware Rule: Index 0 is always transparent.
// We use Magenta as the 'transparent' signal color during composition.
if pixel_index == 0 {
return Color::COLOR_KEY;
}
@@ -10,12 +10,19 @@ use std::sync::Arc;
use std::time::Instant;
/// PrometeuOS (POS): The system firmware/base.
///
/// Maximum authority for boot, peripherals, PVM execution, and fault handling.
/// It acts as the bridge between the high-level PVM applications and the virtual hardware.
pub struct PrometeuOS {
/// Incremented on every host tick (60Hz).
pub tick_index: u64,
/// Incremented every time a logical game frame is successfully completed.
pub logical_frame_index: u64,
/// Indicates if there is an ongoing logical frame that hasn't reached `FRAME_SYNC` yet.
pub logical_frame_active: bool,
/// Number of virtual cycles still available for the current logical frame.
pub logical_frame_remaining_cycles: u64,
/// Real-world CPU time (in microseconds) consumed by the last host tick.
pub last_frame_cpu_time_us: u64,
// Example assets (kept for compatibility with v0 audio syscalls)
@@ -24,36 +31,54 @@ pub struct PrometeuOS {
pub sample_snare: Option<Arc<Sample>>,
// Filesystem
/// The virtual filesystem interface.
pub fs: VirtualFS,
/// Current state of the FS (Mounted, Error, etc).
pub fs_state: FsState,
/// Mapping of numeric handles to file paths for open files.
pub open_files: HashMap<u32, String>,
/// Sequential handle generator for file operations.
pub next_handle: u32,
// Log Service
pub log_service: LogService,
/// Unique ID of the currently running application.
pub current_app_id: u32,
pub current_cartridge_title: String,
pub current_cartridge_app_version: String,
pub current_cartridge_app_mode: crate::model::AppMode,
/// Rate-limiting tracker for application logs to prevent performance degradation.
pub logs_written_this_frame: HashMap<u32, u32>,
// Telemetry and Certification
/// Accumulator for metrics of the frame currently being executed.
pub telemetry_current: TelemetryFrame,
/// Snapshot of the metrics from the last completed logical frame.
pub telemetry_last: TelemetryFrame,
/// Logic for evaluating compliance with the active CAP profile.
pub certifier: Certifier,
/// Global pause flag (used by debugger or system events).
pub paused: bool,
/// Request from debugger to run exactly one instruction or frame.
pub debug_step_request: bool,
/// Instant when the system was initialized.
boot_time: Instant,
}
impl PrometeuOS {
/// Default number of cycles assigned to a single game frame.
pub const CYCLES_PER_LOGICAL_FRAME: u64 = 100_000;
pub const SLICE_PER_TICK: u64 = 100_000; // For now the same, but allows different granularity
/// Maximum number of cycles allowed to execute in a single host tick.
/// Usually the same as CYCLES_PER_LOGICAL_FRAME to target 60FPS.
pub const SLICE_PER_TICK: u64 = 100_000;
/// Maximum characters allowed per log message.
pub const MAX_LOG_LEN: usize = 256;
/// Maximum log entries an App can emit in a single frame.
pub const MAX_LOGS_PER_FRAME: u32 = 10;
/// Creates a new POS instance with optional certification rules.
pub fn new(cap_config: Option<CertificationConfig>) -> Self {
let boot_time = Instant::now();
let mut os = Self {
@@ -158,67 +183,81 @@ impl PrometeuOS {
}
}
/// Executes a host tick (60Hz).
/// Executes a single host tick (nominally 60Hz).
///
/// This method is responsible for managing the logical frame lifecycle.
/// A single host tick might execute a full logical frame, part of it,
/// or multiple frames depending on the configured slices.
pub fn step_frame(&mut self, vm: &mut VirtualMachine, signals: &InputSignals, hw: &mut dyn HardwareBridge) -> Option<String> {
let start = std::time::Instant::now();
self.tick_index += 1;
// If the system is paused, we don't advance unless there's a debug step request.
if self.paused && !self.debug_step_request {
return None;
}
self.update_fs();
// 1. Frame Initialization
// If we are not currently in the middle of a logical frame, start a new one.
if !self.logical_frame_active {
self.logical_frame_active = true;
self.logical_frame_remaining_cycles = Self::CYCLES_PER_LOGICAL_FRAME;
self.begin_logical_frame(signals, hw);
// Beginning of frame: reset telemetry accumulator (but keep frame_index)
// Reset telemetry for the new logical frame
self.telemetry_current = TelemetryFrame {
frame_index: self.logical_frame_index,
..Default::default()
};
}
// Budget for this tick: the minimum between the tick slice and what remains in the logical frame
// 2. Budget Allocation
// Determine how many cycles we can run in this host tick.
let budget = std::cmp::min(Self::SLICE_PER_TICK, self.logical_frame_remaining_cycles);
// 3. VM Execution
if budget > 0 {
// Execute budget
// Run the VM until budget is hit or FRAME_SYNC is reached.
let run_result = vm.run_budget(budget, self, hw);
match run_result {
Ok(run) => {
self.logical_frame_remaining_cycles = self.logical_frame_remaining_cycles.saturating_sub(run.cycles_used);
// Accumulates metrics
// Accumulate metrics for telemetry and certification
self.telemetry_current.cycles_used += run.cycles_used;
self.telemetry_current.vm_steps += run.steps_executed;
// Handle Breakpoints
if run.reason == crate::virtual_machine::LogicalFrameEndingReason::Breakpoint {
self.paused = true;
self.debug_step_request = false;
self.log(LogLevel::Info, LogSource::Vm, 0xDEB1, format!("Breakpoint hit at PC 0x{:X}", vm.pc));
}
// 4. Frame Finalization (FRAME_SYNC reached)
if run.reason == crate::virtual_machine::LogicalFrameEndingReason::FrameSync {
// All drawing commands for this frame are now complete.
// Finalize the framebuffer.
hw.gfx_mut().render_all();
// Finalizes frame telemetry (host_cpu_time will be refined at the end of the tick)
// Finalize frame telemetry
self.telemetry_current.host_cpu_time_us = start.elapsed().as_micros() as u64;
// Certification (CAP)
// Evaluate CAP (Execution Budget Compliance)
let ts_ms = self.boot_time.elapsed().as_millis() as u64;
self.telemetry_current.violations = self.certifier.evaluate(&self.telemetry_current, &mut self.log_service, ts_ms) as u32;
// Latch: what the overlay reads
// Latch telemetry for the Host/Debugger to read.
self.telemetry_last = self.telemetry_current;
self.logical_frame_index += 1;
self.logical_frame_active = false;
self.logical_frame_remaining_cycles = 0;
// If we were doing a "step frame" debug command, pause now that the frame is done.
if self.debug_step_request {
self.paused = true;
self.debug_step_request = false;
@@ -226,6 +265,7 @@ impl PrometeuOS {
}
}
Err(e) => {
// Fatal VM fault (division by zero, invalid memory access, etc).
let err_msg = format!("PVM Fault: {:?}", e);
self.log(LogLevel::Error, LogSource::Vm, 0, err_msg.clone());
return Some(err_msg);
@@ -235,7 +275,7 @@ impl PrometeuOS {
self.last_frame_cpu_time_us = start.elapsed().as_micros() as u64;
// If the frame ended in this tick, we update the final real time in the latch
// If the frame ended exactly in this tick, we update the final real time in the latch.
if !self.logical_frame_active && self.telemetry_last.frame_index == self.logical_frame_index.wrapping_sub(1) {
self.telemetry_last.host_cpu_time_us = self.last_frame_cpu_time_us;
}
@@ -493,23 +533,35 @@ mod tests {
}
impl NativeInterface for PrometeuOS {
/// Dispatches a syscall from the VM to the native implementation.
///
/// Syscalls are grouped by functionality:
/// - 0x0000: System/Cartridge management
/// - 0x1000: Graphics (GFX)
/// - 0x2000: Input
/// - 0x3000: Audio
/// - 0x4000: Filesystem (FS)
/// - 0x5000: Logging
///
/// Each syscall returns the number of virtual cycles it consumed.
fn syscall(&mut self, id: u32, vm: &mut VirtualMachine, hw: &mut dyn HardwareBridge) -> Result<u64, String> {
self.telemetry_current.syscalls += 1;
match id {
// --- System Syscalls ---
// system.has_cart() -> bool
0x0001 => {
// virtual_machine.push(Value::Boolean(self.current_cartridge.is_some()));
// Returns true if a cartridge is available.
Ok(10)
}
// system.run_cart()
0x0002 => {
// if let Some(cart) = self.current_cartridge.as_ref().cloned() {
// self.load_cartridge(&cart);
// } else {
// return Err("No cartridge inserted".into());
// }
// Triggers loading and execution of the current cartridge.
Ok(100)
}
// --- GFX Syscalls ---
// gfx.clear(color_index)
0x1001 => {
let color_idx = vm.pop_integer()? as usize;
@@ -528,6 +580,9 @@ impl NativeInterface for PrometeuOS {
hw.gfx_mut().fill_rect(x, y, w, h, color);
Ok(200)
}
// --- Input Syscalls ---
// input.get_pad(button_id) -> bool
0x2001 => {
let button_id = vm.pop_integer()? as u32;
@@ -535,6 +590,9 @@ impl NativeInterface for PrometeuOS {
vm.push(Value::Boolean(is_down));
Ok(50)
}
// --- Audio Syscalls ---
// audio.play_sample(sample_id, voice_id, volume, pan, pitch)
0x3001 => {
let pitch = vm.pop_number()?;
@@ -559,6 +617,7 @@ impl NativeInterface for PrometeuOS {
// --- Filesystem Syscalls (0x4000) ---
// FS_OPEN(path) -> handle
// Opens a file in the virtual sandbox and returns a numeric handle.
0x4001 => {
let path = match vm.pop()? {
Value::String(s) => s,
@@ -623,7 +682,7 @@ impl NativeInterface for PrometeuOS {
};
match self.fs.list_dir(&path) {
Ok(entries) => {
// For now, returns a string separated by ';'
// Returns a string separated by ';' for simple parsing in PVM.
let names: Vec<String> = entries.into_iter().map(|e| e.name).collect();
vm.push(Value::String(names.join(";")));
Ok(500)
@@ -5,35 +5,61 @@ use crate::virtual_machine::opcode::OpCode;
use crate::virtual_machine::value::Value;
use crate::virtual_machine::Program;
/// Reason why the Virtual Machine stopped execution during a specific run.
/// This allows the system to decide if it should continue execution in the next tick
/// or if the frame is finalized.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LogicalFrameEndingReason {
/// Execution reached a `FRAME_SYNC` instruction, marking the end of the logical frame.
FrameSync,
/// The cycle budget for the current host tick was exhausted before reaching `FRAME_SYNC`.
BudgetExhausted,
/// A `HALT` instruction was executed, terminating the program.
Halted,
/// The Program Counter (PC) reached the end of the available bytecode.
EndOfRom,
/// Execution hit a registered breakpoint.
Breakpoint,
}
/// A report detailing the results of an execution slice (run_budget).
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct BudgetReport {
/// Total virtual cycles consumed during this run.
pub cycles_used: u64,
/// Number of VM instructions executed.
pub steps_executed: u32,
/// The reason why this execution slice ended.
pub reason: LogicalFrameEndingReason,
}
/// The PVM (PROMETEU Virtual Machine).
///
/// A deterministic, stack-based virtual machine designed for educational purposes.
/// It models execution through fixed-cost cycles and explicit memory management.
pub struct VirtualMachine {
/// Program Counter: points to the next byte in the ROM to be executed.
pub pc: usize,
/// Operand Stack: used for intermediate calculations and passing arguments to opcodes.
pub operand_stack: Vec<Value>,
/// Call Stack: stores execution frames for function calls and local variables.
pub call_stack: Vec<CallFrame>,
/// Globals: storage for persistent variables that survive between frames.
pub globals: Vec<Value>,
/// The currently loaded program (Bytecode + Constant Pool).
pub program: Program,
pub heap: Vec<Value>, // Simplified for demo, future real RAM/Heap
/// Dynamic memory region for complex structures (Simplified in current version).
pub heap: Vec<Value>,
/// Total accumulated execution cycles since the last reset.
pub cycles: u64,
/// Flag indicating if the VM has been stopped by a `HALT` instruction.
pub halted: bool,
/// A set of PC addresses where execution should pause.
pub breakpoints: std::collections::HashSet<usize>,
}
impl VirtualMachine {
/// Creates a new VM instance with the provided bytecode and constants.
pub fn new(rom: Vec<u8>, constant_pool: Vec<Value>) -> Self {
Self {
pc: 0,
@@ -48,26 +74,31 @@ impl VirtualMachine {
}
}
/// Resets the VM state and loads a new program.
/// This is typically called by the Firmware when starting a new App/Cartridge.
pub fn initialize(&mut self, program_bytes: Vec<u8>, entrypoint: &str) {
// PBC (Prometeu ByteCode) is a binary format that includes a header,
// constant pool, and the raw ROM (bytecode).
if program_bytes.starts_with(b"PPBC") {
if let Ok((rom, cp)) = self.parse_pbc(&program_bytes) {
self.program = Program::new(rom, cp);
} else {
// Fallback for raw bytes if PBC parsing fails
self.program = Program::new(program_bytes, vec![]);
}
} else {
// For now, we treat the bytes as the ROM directly.
// If it doesn't have the PPBC signature, treat it as raw bytecode.
self.program = Program::new(program_bytes, vec![]);
}
// If the entrypoint is numeric, we can try to use it as the initial PC.
// If not, for now we ignore it or start from 0.
// Resolve the entrypoint. Currently supports numeric addresses.
if let Ok(addr) = entrypoint.parse::<usize>() {
self.pc = addr;
} else {
self.pc = 0;
}
// Full state reset to ensure a clean start for the App
self.operand_stack.clear();
self.call_stack.clear();
self.globals.clear();
@@ -76,9 +107,12 @@ impl VirtualMachine {
self.halted = false;
}
/// Parses the PROMETEU binary format.
/// Format: "PPBC" (4) | CP_COUNT (u32) | CP_ENTRIES[...] | ROM_SIZE (u32) | ROM_BYTES[...]
fn parse_pbc(&self, bytes: &[u8]) -> Result<(Vec<u8>, Vec<Value>), String> {
let mut cursor = 4; // Skip "PPBC"
let mut cursor = 4; // Skip "PPBC" signature
// 1. Parse Constant Pool (literals like strings, ints, floats used in the program)
let cp_count = self.read_u32_at(bytes, &mut cursor)? as usize;
let mut cp = Vec::with_capacity(cp_count);
@@ -88,11 +122,11 @@ impl VirtualMachine {
cursor += 1;
match tag {
1 => { // Integer
1 => { // Integer (64-bit)
let val = self.read_i64_at(bytes, &mut cursor)?;
cp.push(Value::Integer(val));
}
2 => { // Float
2 => { // Float (64-bit)
let val = self.read_f64_at(bytes, &mut cursor)?;
cp.push(Value::Float(val));
}
@@ -102,7 +136,7 @@ impl VirtualMachine {
cursor += 1;
cp.push(Value::Boolean(val));
}
4 => { // String
4 => { // String (UTF-8)
let len = self.read_u32_at(bytes, &mut cursor)? as usize;
if cursor + len > bytes.len() { return Err("Unexpected end of PBC".into()); }
let s = String::from_utf8_lossy(&bytes[cursor..cursor + len]).into_owned();
@@ -113,6 +147,7 @@ impl VirtualMachine {
}
}
// 2. Parse ROM (executable bytecode)
let rom_size = self.read_u32_at(bytes, &mut cursor)? as usize;
if cursor + rom_size > bytes.len() {
return Err("Invalid ROM size in PBC".into());
@@ -151,6 +186,16 @@ impl Default for VirtualMachine {
}
impl VirtualMachine {
/// Executes the VM for a limited number of cycles (budget).
///
/// This is the heart of the deterministic execution model. Instead of running
/// indefinitely, the VM runs until it consumes its allocated budget or reaches
/// a synchronization point (`FRAME_SYNC`).
///
/// # Arguments
/// * `budget` - Maximum number of cycles allowed for this execution slice.
/// * `native` - Interface for handling syscalls (Firmware/OS).
/// * `hw` - Access to virtual hardware peripherals.
pub fn run_budget(
&mut self,
budget: u64,
@@ -165,6 +210,9 @@ impl VirtualMachine {
&& !self.halted
&& self.pc < self.program.rom.len()
{
// Debugger support: stop before executing an instruction if there's a breakpoint.
// Note: we skip the check for the very first step of a slice to avoid
// getting stuck on the same breakpoint repeatedly.
if steps_executed > 0 && self.breakpoints.contains(&self.pc) {
ending_reason = Some(LogicalFrameEndingReason::Breakpoint);
break;
@@ -173,26 +221,31 @@ impl VirtualMachine {
let pc_before = self.pc;
let cycles_before = self.cycles;
// Fast-path: FRAME_SYNC ends the logical frame
// Fast-path for FRAME_SYNC:
// This instruction is special because it marks the end of a logical game frame.
// We peak ahead to handle it efficiently.
let opcode_val = self.peek_u16()?;
let opcode = OpCode::try_from(opcode_val)?;
if opcode == OpCode::FrameSync {
self.pc += 2;
self.pc += 2; // Advance PC past the opcode
self.cycles += OpCode::FrameSync.cycles();
steps_executed += 1;
ending_reason = Some(LogicalFrameEndingReason::FrameSync);
break;
}
// Execute a single step (Fetch-Decode-Execute)
self.step(native, hw)?;
steps_executed += 1;
// ensures real progress
// Integrity check: ensure real progress is being made to avoid infinite loops
// caused by zero-cycle instructions or stuck PC.
if self.pc == pc_before && self.cycles == cycles_before && !self.halted {
return Err(format!("VM stuck at PC 0x{:08X}", self.pc));
}
}
// Determine why we stopped if no explicit reason (FrameSync/Breakpoint) was set.
if ending_reason.is_none() {
if self.halted {
ending_reason = Some(LogicalFrameEndingReason::Halted);
@@ -210,6 +263,7 @@ impl VirtualMachine {
})
}
/// Peeks at the next 16-bit value in the ROM without advancing the PC.
fn peek_u16(&self) -> Result<u16, String> {
if self.pc + 2 > self.program.rom.len() {
return Err("Unexpected end of ROM".into());
@@ -221,14 +275,22 @@ impl VirtualMachine {
Ok(u16::from_le_bytes(bytes))
}
/// Executes a single instruction at the current Program Counter (PC).
///
/// This follows the classic CPU cycle:
/// 1. Fetch: Read the opcode from memory.
/// 2. Decode: Identify what operation to perform.
/// 3. Execute: Perform the operation, updating stacks, memory, or calling peripherals.
pub fn step(&mut self, native: &mut dyn NativeInterface, hw: &mut dyn HardwareBridge) -> Result<(), String> {
if self.halted || self.pc >= self.program.rom.len() {
return Ok(());
}
// Fetch & Decode
let opcode_val = self.read_u16()?;
let opcode = OpCode::try_from(opcode_val)?;
// Execute
match opcode {
OpCode::Nop => {}
OpCode::Halt => {
@@ -369,6 +431,8 @@ impl VirtualMachine {
self.operand_stack[stack_idx] = val;
}
OpCode::Call => {
// addr: destination instruction address
// args_count: how many values from the operand stack become locals in the new frame
let addr = self.read_u32()? as usize;
let args_count = self.read_u32()? as usize;
let stack_base = self.operand_stack.len() - args_count;
@@ -382,18 +446,21 @@ impl VirtualMachine {
OpCode::Ret => {
let frame = self.call_stack.pop().ok_or("Call stack underflow")?;
let return_val = self.pop()?;
// Clean up the operand stack, removing the frame's locals
self.operand_stack.truncate(frame.stack_base);
// Return the result of the function
self.push(return_val);
self.pc = frame.return_address;
}
OpCode::PushScope => {
// Used for blocks within a function that have their own locals
let locals_count = self.read_u32()? as usize;
let stack_base = self.operand_stack.len();
for _ in 0..locals_count {
self.push(Value::Null);
}
self.call_stack.push(CallFrame {
return_address: 0,
return_address: 0, // Scope blocks don't return via PC jump
stack_base,
locals_count,
});
@@ -403,6 +470,7 @@ impl VirtualMachine {
self.operand_stack.truncate(frame.stack_base);
}
OpCode::Alloc => {
// Allocates 'size' values on the heap and pushes a reference to the stack
let size = self.read_u32()? as usize;
let ref_idx = self.heap.len();
for _ in 0..size {
@@ -411,6 +479,7 @@ impl VirtualMachine {
self.push(Value::Ref(ref_idx));
}
OpCode::LoadRef => {
// Reads a value from a heap reference at a specific offset
let offset = self.read_u32()? as usize;
let ref_val = self.pop()?;
if let Value::Ref(base) = ref_val {
@@ -421,6 +490,7 @@ impl VirtualMachine {
}
}
OpCode::StoreRef => {
// Writes a value to a heap reference at a specific offset
let offset = self.read_u32()? as usize;
let val = self.pop()?;
let ref_val = self.pop()?;
@@ -434,15 +504,18 @@ impl VirtualMachine {
}
}
OpCode::Syscall => {
// Calls a native function implemented by the Firmware/OS
let id = self.read_u32()?;
let native_cycles = native.syscall(id, self, hw).map_err(|e| format!("syscall 0x{:08X} failed: {}", id, e))?;
self.cycles += native_cycles;
}
OpCode::FrameSync => {
// Already handled in the run_budget loop for performance
return Ok(());
}
}
// Apply the instruction cost to the cycle counter
self.cycles += opcode.cycles();
Ok(())
}