added comments extensively

This commit is contained in:
2026-03-24 13:40:18 +00:00
parent 9ba2aab1a5
commit 075fe8526c
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,