Compare commits
81
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
6ef376763c
|
||
|
|
f50a3f127f
|
||
|
|
f0f3f972ce
|
||
|
|
b2d2533acb
|
||
|
|
4b499288e2
|
||
|
|
aa3b31deb5 | ||
|
|
f784ccd774
|
||
|
|
7cced0709b
|
||
|
|
e2a5a67621
|
||
|
|
fbe4d0cac0
|
||
|
|
4c0f1cb9ad
|
||
|
|
94ffd241bd
|
||
|
|
a415c172c7
|
||
|
|
c89116b6f8
|
||
|
|
dc279fe72b
|
||
|
|
01221769cd
|
||
|
|
3cce8a2b25 | ||
|
|
de53eb5ad7
|
||
|
|
49cb16b6cb
|
||
|
|
3aec829c70
|
||
|
|
73c8246c8d
|
||
|
|
fa0a768b84
|
||
|
|
62573e9574
|
||
|
|
c814e057dc
|
||
|
|
8d719843c7
|
||
|
|
d6afa6ae6b
|
||
|
|
3df8227ebf
|
||
|
|
b30ff73e3d
|
||
|
|
dcd3479b1d
|
||
|
|
0ffb3467b1
|
||
|
|
313b896e7b | ||
|
|
6dc8cb5372
|
||
|
|
c34bbaf936
|
||
|
|
e613ab43c9
|
||
|
|
4e05daf280
|
||
|
|
8098dbd7f4
|
||
|
|
e01b463e1f
|
||
|
|
b8fc5a0534
|
||
|
|
f26731413f
|
||
|
|
fa2e329d4b
|
||
|
|
c3d6b70b0c
|
||
|
|
49a676ff86
|
||
|
|
23a181de46
|
||
|
|
bd27f5eb63
|
||
|
|
6646ccfbb5
|
||
|
|
0ecab2910b
|
||
|
|
3eeda25e97
|
||
|
|
a22215392d
|
||
|
|
e19409a2ef
|
||
|
|
a517a24978
|
||
|
|
a771f6320e
|
||
|
|
d645bbb7bd
|
||
|
|
5ff273f167
|
||
|
|
33f70d1c6e
|
||
|
|
999136fef3
|
||
|
|
1b29b2f985
|
||
|
|
29e002c5f3
|
||
|
|
57c9af939b
|
||
|
|
d54dadf2a5
|
||
|
|
126bffa37d
|
||
|
|
4bc9ce2b73 | ||
|
|
95465869b1
|
||
|
|
377cb41a3f
|
||
|
|
6593581954
|
||
|
|
badc9b8874
|
||
|
|
f49accc796
|
||
|
|
46b2fae514
|
||
|
|
7307870414
|
||
|
|
5137592cdd
|
||
|
|
68fd3bcd65
|
||
|
|
d39e03c7d9
|
||
|
|
2ab5c43334
|
||
|
|
23d3ed641e | ||
|
|
5d3db4c22a
|
||
|
|
b84946a3a0
|
||
|
|
0adec90f23
|
||
|
|
8747c4f4cf
|
||
|
|
961557583b
|
||
|
|
30c24a4ea7
|
||
|
|
7598a15782
|
||
|
|
54dad3b398
|
Generated
+10
@@ -1469,6 +1469,16 @@ version = "1.0.15"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "57c0d7b74b563b49d38dae00a0c37d4d6de9b432382b2892f0574ddcae73fd0a"
|
||||
|
||||
[[package]]
|
||||
name = "pbxgen-dummy-boy"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"prometeu-bytecode",
|
||||
"prometeu-hal",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "pbxgen-stress"
|
||||
version = "0.1.0"
|
||||
|
||||
@@ -8,6 +8,7 @@ members = [
|
||||
"crates/console/prometeu-vm",
|
||||
"crates/host/prometeu-host-desktop-winit",
|
||||
"crates/tools/prometeu-cli",
|
||||
"crates/tools/pbxgen-dummy-boy",
|
||||
"crates/tools/pbxgen-stress",
|
||||
"crates/dev/prometeu-test-support",
|
||||
"crates/dev/prometeu-layer-tests",
|
||||
|
||||
@@ -19,6 +19,6 @@ pub use assembler::{assemble, AsmError};
|
||||
pub use decoder::{decode_next, DecodeError};
|
||||
pub use disassembler::disassemble;
|
||||
pub use layout::{compute_function_layouts, FunctionLayout};
|
||||
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl};
|
||||
pub use model::{BytecodeLoader, FunctionMeta, LoadError, SyscallDecl, PBX_MAGIC};
|
||||
pub use program_image::ProgramImage;
|
||||
pub use value::{string_materialization_count, HeapRef, Value};
|
||||
|
||||
@@ -80,9 +80,11 @@ const SECTION_KIND_DEBUG: u32 = 3;
|
||||
const SECTION_KIND_EXPORTS: u32 = 4;
|
||||
const SECTION_KIND_SYSCALLS: u32 = 5;
|
||||
|
||||
/// Represents the final serialized format of a PBS v0 module.
|
||||
pub const PBX_MAGIC: [u8; 4] = *b"PBX\0";
|
||||
|
||||
/// Represents the final serialized format of a PBX v0 module.
|
||||
///
|
||||
/// This structure is a pure data container for the PBS format. It does NOT
|
||||
/// This structure is a pure data container for the PBX format. It does NOT
|
||||
/// contain any linker-like logic (symbol resolution, patching, etc.).
|
||||
/// All multi-module programs must be flattened and linked by the compiler
|
||||
/// before being serialized into this format.
|
||||
@@ -126,8 +128,8 @@ impl BytecodeModule {
|
||||
final_sections.push((SECTION_KIND_SYSCALLS, syscall_data));
|
||||
|
||||
let mut out = Vec::new();
|
||||
// Magic "PBS\0"
|
||||
out.extend_from_slice(b"PBS\0");
|
||||
// Magic "PBX\0"
|
||||
out.extend_from_slice(&PBX_MAGIC);
|
||||
// Version 0
|
||||
out.extend_from_slice(&0u16.to_le_bytes());
|
||||
// Endianness 0 (Little Endian), Reserved
|
||||
@@ -272,8 +274,8 @@ impl BytecodeLoader {
|
||||
return Err(LoadError::UnexpectedEof);
|
||||
}
|
||||
|
||||
// Magic "PBS\0"
|
||||
if &bytes[0..4] != b"PBS\0" {
|
||||
// Magic "PBX\0"
|
||||
if bytes[0..4] != PBX_MAGIC[..] {
|
||||
return Err(LoadError::InvalidMagic);
|
||||
}
|
||||
|
||||
@@ -708,7 +710,7 @@ mod tests {
|
||||
|
||||
fn create_header(section_count: u32) -> Vec<u8> {
|
||||
let mut h = vec![0u8; 32];
|
||||
h[0..4].copy_from_slice(b"PBS\0");
|
||||
h[0..4].copy_from_slice(&PBX_MAGIC);
|
||||
h[4..6].copy_from_slice(&0u16.to_le_bytes()); // version
|
||||
h[6] = 0; // endianness
|
||||
h[8..12].copy_from_slice(§ion_count.to_le_bytes());
|
||||
@@ -727,7 +729,7 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
fn build_pbs_with_sections(sections: Vec<(u32, Vec<u8>)>) -> Vec<u8> {
|
||||
fn build_pbx_with_sections(sections: Vec<(u32, Vec<u8>)>) -> Vec<u8> {
|
||||
let mut data = create_header(sections.len() as u32);
|
||||
let mut offset = 32 + (sections.len() as u32 * 12);
|
||||
|
||||
@@ -748,7 +750,7 @@ mod tests {
|
||||
#[test]
|
||||
fn test_invalid_magic() {
|
||||
let mut data = create_header(0);
|
||||
data[0] = b'X';
|
||||
data[0..4].copy_from_slice(b"PBS\0");
|
||||
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidMagic));
|
||||
}
|
||||
|
||||
@@ -897,7 +899,7 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn test_malformed_sysc_section_is_rejected() {
|
||||
let data = build_pbs_with_sections(vec![(SECTION_KIND_SYSCALLS, vec![1, 0, 0])]);
|
||||
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, vec![1, 0, 0])]);
|
||||
|
||||
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::MalformedSection));
|
||||
}
|
||||
@@ -914,7 +916,7 @@ mod tests {
|
||||
sysc.extend_from_slice(&0u16.to_le_bytes());
|
||||
sysc.extend_from_slice(&0u16.to_le_bytes());
|
||||
|
||||
let data = build_pbs_with_sections(vec![(SECTION_KIND_SYSCALLS, sysc)]);
|
||||
let data = build_pbx_with_sections(vec![(SECTION_KIND_SYSCALLS, sysc)]);
|
||||
|
||||
assert_eq!(BytecodeLoader::load(&data), Err(LoadError::InvalidUtf8));
|
||||
}
|
||||
|
||||
@@ -4,7 +4,7 @@ use crate::value::Value;
|
||||
use std::collections::HashMap;
|
||||
use std::sync::Arc;
|
||||
|
||||
/// Represents a fully linked, executable PBS program image.
|
||||
/// Represents a fully linked, executable PBX program image.
|
||||
///
|
||||
/// Under the Prometeu architecture, the ProgramImage is a "closed-world" artifact
|
||||
/// produced by the compiler. All linking, relocation, and symbol resolution
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -557,8 +557,9 @@ mod tests {
|
||||
|
||||
fn make_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) -> GlyphBank {
|
||||
let size = tile_size as usize;
|
||||
let mut bank = GlyphBank::new(tile_size, size, size);
|
||||
bank.palettes[palette_id as usize][1] = color;
|
||||
let mut bank =
|
||||
GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
|
||||
bank.palette_mut(palette_id).unwrap()[1] = color;
|
||||
for pixel in &mut bank.pixel_indices {
|
||||
*pixel = 1;
|
||||
}
|
||||
|
||||
@@ -812,7 +812,14 @@ impl Gfx {
|
||||
let fetch_x = if tile.entry.flip_x() { size - 1 - local_x } else { local_x };
|
||||
let fetch_y = if tile.entry.flip_y() { size - 1 - local_y } else { local_y };
|
||||
let px_index = tile.bank.get_pixel_index(tile.entry.glyph_id, fetch_x, fetch_y);
|
||||
let color = tile.bank.resolve_color(tile.entry.palette_id, px_index);
|
||||
let color = tile.bank.resolve_color(tile.entry.palette_id, px_index).unwrap_or_else(
|
||||
|| {
|
||||
panic!(
|
||||
"SCENE composition fatal: palette_id {} is not resident for glyph asset {}",
|
||||
tile.entry.palette_id, tile.entry.glyph_asset_id
|
||||
)
|
||||
},
|
||||
);
|
||||
if color.alpha() == 0 {
|
||||
continue;
|
||||
}
|
||||
@@ -862,7 +869,14 @@ impl Gfx {
|
||||
let fetch_y = if sprite.flip_y { size - 1 - local_y } else { local_y };
|
||||
|
||||
let px_index = bank.get_pixel_index(sprite.glyph.glyph_id, fetch_x, fetch_y);
|
||||
let color = bank.resolve_color(sprite.glyph.palette_id, px_index);
|
||||
let color = bank.resolve_color(sprite.glyph.palette_id, px_index).unwrap_or_else(
|
||||
|| {
|
||||
panic!(
|
||||
"SPRITE composition fatal: palette_id {} is not resident for glyph bank {}",
|
||||
sprite.glyph.palette_id, sprite.bank_id
|
||||
)
|
||||
},
|
||||
);
|
||||
if color.alpha() == 0 {
|
||||
continue;
|
||||
}
|
||||
@@ -1010,9 +1024,14 @@ mod tests {
|
||||
|
||||
fn make_glyph_bank(tile_size: TileSize, palette_colors: &[(u8, u8, Color)]) -> GlyphBank {
|
||||
let size = tile_size as usize;
|
||||
let mut bank = GlyphBank::new(tile_size, size, size);
|
||||
let palette_count = palette_colors
|
||||
.iter()
|
||||
.map(|(palette_id, _, _)| *palette_id as usize + 1)
|
||||
.max()
|
||||
.unwrap_or(1);
|
||||
let mut bank = GlyphBank::with_palette_count(tile_size, size, size, palette_count);
|
||||
for (palette_id, color_index, color) in palette_colors {
|
||||
bank.palettes[*palette_id as usize][*color_index as usize] = *color;
|
||||
bank.palette_mut(*palette_id).unwrap()[*color_index as usize] = *color;
|
||||
}
|
||||
bank
|
||||
}
|
||||
@@ -1152,6 +1171,26 @@ mod tests {
|
||||
assert_eq!(back[0], Color::RED.raw());
|
||||
}
|
||||
|
||||
#[test]
|
||||
#[should_panic(expected = "SPRITE composition fatal: palette_id 1 is not resident")]
|
||||
fn sprite_draw_panics_for_invalid_palette_reference() {
|
||||
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
|
||||
let mut back = vec![Color::BLACK.raw(); 8 * 8];
|
||||
let sprite = Sprite {
|
||||
glyph: Glyph { glyph_id: 0, palette_id: 1 },
|
||||
x: 0,
|
||||
y: 0,
|
||||
layer: 0,
|
||||
flip_x: false,
|
||||
flip_y: false,
|
||||
bank_id: 0,
|
||||
active: true,
|
||||
priority: 0,
|
||||
};
|
||||
|
||||
Gfx::draw_sprite_pixel_by_pixel(&mut back, 8, 8, &sprite, &bank);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_cached_tile_draws_opaque_color_index_zero() {
|
||||
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
|
||||
@@ -1194,6 +1233,26 @@ mod tests {
|
||||
assert_eq!(target.back[0], Color::RED.raw());
|
||||
}
|
||||
|
||||
#[test]
|
||||
#[should_panic(expected = "SCENE composition fatal: palette_id 1 is not resident")]
|
||||
fn cached_tile_draw_panics_for_invalid_palette_reference() {
|
||||
let bank = make_filled_glyph_bank(TileSize::Size8, 0, &[(0, 0, Color::GREEN)]);
|
||||
let mut back = vec![Color::BLACK.raw(); 8 * 8];
|
||||
let mut target = RenderTarget { back: &mut back, screen_w: 8, screen_h: 8 };
|
||||
let entry = CachedTileEntry {
|
||||
active: true,
|
||||
glyph_id: 0,
|
||||
palette_id: 1,
|
||||
flags: 0,
|
||||
glyph_asset_id: 0,
|
||||
};
|
||||
|
||||
Gfx::draw_cached_tile_pixels(
|
||||
&mut target,
|
||||
CachedTileDraw { x: 0, y: 0, entry, bank: &bank, tile_size: TileSize::Size8 },
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_draw_rect() {
|
||||
let banks = Arc::new(MemoryBanks::new());
|
||||
|
||||
@@ -118,7 +118,11 @@ impl Game2DFrameComposer for Hardware {
|
||||
}
|
||||
|
||||
fn emit_sprite(&mut self, sprite: Sprite) -> prometeu_hal::ComposerOpStatus {
|
||||
if self.gfx.glyph_banks.glyph_bank_slot(sprite.bank_id as usize).is_none() {
|
||||
let Some(bank) = self.gfx.glyph_banks.glyph_bank_slot(sprite.bank_id as usize) else {
|
||||
return prometeu_hal::ComposerOpStatus::BankInvalid;
|
||||
};
|
||||
|
||||
if !bank.contains_palette(sprite.glyph.palette_id) {
|
||||
return prometeu_hal::ComposerOpStatus::BankInvalid;
|
||||
}
|
||||
|
||||
@@ -261,7 +265,7 @@ mod tests {
|
||||
|
||||
fn make_glyph_bank() -> GlyphBank {
|
||||
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
||||
bank.palettes[0][1] = Color::RED;
|
||||
bank.palette_mut(0).unwrap()[1] = Color::RED;
|
||||
for pixel in &mut bank.pixel_indices {
|
||||
*pixel = 1;
|
||||
}
|
||||
@@ -433,4 +437,28 @@ mod tests {
|
||||
|
||||
assert_eq!(hardware.gfx.front_buffer()[0], Color::RED.raw());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn emit_sprite_rejects_palette_id_outside_loaded_glyph_bank() {
|
||||
let banks = Arc::new(MemoryBanks::new());
|
||||
banks.install_glyph_bank(0, Arc::new(make_glyph_bank()));
|
||||
let mut hardware = Hardware::new_with_memory_banks(banks);
|
||||
|
||||
let status = Game2DFrameComposer::emit_sprite(
|
||||
&mut hardware,
|
||||
Sprite {
|
||||
glyph: Glyph { glyph_id: 0, palette_id: 1 },
|
||||
x: 0,
|
||||
y: 0,
|
||||
layer: 0,
|
||||
bank_id: 0,
|
||||
active: false,
|
||||
flip_x: false,
|
||||
flip_y: false,
|
||||
priority: 0,
|
||||
},
|
||||
);
|
||||
|
||||
assert_eq!(status, prometeu_hal::ComposerOpStatus::BankInvalid);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -24,6 +24,8 @@ pub trait GlyphBankPoolAccess: Send + Sync {
|
||||
pub trait GlyphBankPoolInstaller: Send + Sync {
|
||||
/// Atomically swaps the resident GlyphBank in the specified slot.
|
||||
fn install_glyph_bank(&self, slot: usize, bank: Arc<GlyphBank>);
|
||||
/// Clears all resident GlyphBank slots.
|
||||
fn clear_glyph_banks(&self);
|
||||
}
|
||||
|
||||
/// Non-generic interface for peripherals to access sound banks.
|
||||
@@ -38,6 +40,8 @@ pub trait SoundBankPoolAccess: Send + Sync {
|
||||
pub trait SoundBankPoolInstaller: Send + Sync {
|
||||
/// Atomically swaps the resident SoundBank in the specified slot.
|
||||
fn install_sound_bank(&self, slot: usize, bank: Arc<SoundBank>);
|
||||
/// Clears all resident SoundBank slots.
|
||||
fn clear_sound_banks(&self);
|
||||
}
|
||||
|
||||
/// Non-generic interface for peripherals to access scene banks.
|
||||
@@ -52,6 +56,8 @@ pub trait SceneBankPoolAccess: Send + Sync {
|
||||
pub trait SceneBankPoolInstaller: Send + Sync {
|
||||
/// Atomically swaps the resident SceneBank in the specified slot.
|
||||
fn install_scene_bank(&self, slot: usize, bank: Arc<SceneBank>);
|
||||
/// Clears all resident SceneBank slots.
|
||||
fn clear_scene_banks(&self);
|
||||
}
|
||||
|
||||
/// Centralized container for all hardware memory banks.
|
||||
@@ -100,6 +106,10 @@ impl GlyphBankPoolInstaller for MemoryBanks {
|
||||
pool[slot] = Some(bank);
|
||||
}
|
||||
}
|
||||
|
||||
fn clear_glyph_banks(&self) {
|
||||
self.glyph_bank_pool.write().unwrap().fill(None);
|
||||
}
|
||||
}
|
||||
|
||||
impl SoundBankPoolAccess for MemoryBanks {
|
||||
@@ -120,6 +130,10 @@ impl SoundBankPoolInstaller for MemoryBanks {
|
||||
pool[slot] = Some(bank);
|
||||
}
|
||||
}
|
||||
|
||||
fn clear_sound_banks(&self) {
|
||||
self.sound_bank_pool.write().unwrap().fill(None);
|
||||
}
|
||||
}
|
||||
|
||||
impl SceneBankPoolAccess for MemoryBanks {
|
||||
@@ -140,6 +154,10 @@ impl SceneBankPoolInstaller for MemoryBanks {
|
||||
pool[slot] = Some(bank);
|
||||
}
|
||||
}
|
||||
|
||||
fn clear_scene_banks(&self) {
|
||||
self.scene_bank_pool.write().unwrap().fill(None);
|
||||
}
|
||||
}
|
||||
|
||||
impl HalRenderResourceAccess for MemoryBanks {
|
||||
@@ -178,7 +196,7 @@ mod tests {
|
||||
|
||||
fn make_glyph_bank() -> GlyphBank {
|
||||
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
||||
bank.palettes[0][1] = Color::WHITE;
|
||||
bank.palette_mut(0).unwrap()[1] = Color::WHITE;
|
||||
bank
|
||||
}
|
||||
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -14,6 +14,7 @@ pub enum FirmwareState {
|
||||
LaunchHub(LaunchHubStep),
|
||||
HubHome(HubHomeStep),
|
||||
LoadCartridge(LoadCartridgeStep),
|
||||
ResumeResidentGame,
|
||||
GameRunning(GameRunningStep),
|
||||
ShellRunning(ShellRunningStep),
|
||||
AppCrashes(AppCrashesStep),
|
||||
|
||||
@@ -1,8 +1,9 @@
|
||||
use crate::firmware::firmware_state::{AppCrashesStep, FirmwareState};
|
||||
use crate::firmware::firmware_state::{AppCrashesStep, FirmwareState, HubHomeStep};
|
||||
use crate::firmware::prometeu_context::PrometeuContext;
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::log::{LogLevel, LogSource};
|
||||
use prometeu_system::CrashReport;
|
||||
use prometeu_system::task::{TaskId, TaskState};
|
||||
use prometeu_system::{CrashReport, ResidentGameState};
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct GameRunningStep {
|
||||
@@ -36,13 +37,35 @@ impl GameRunningStep {
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
|
||||
let result = ctx.os.vm().tick(ctx.vm, ctx.signals, ctx.platform);
|
||||
let pause_requested = matches!(
|
||||
ctx.os.lifecycle().resident_game().map(|game| game.state),
|
||||
Some(ResidentGameState::PauseRequested { .. })
|
||||
);
|
||||
let result = ctx.os.vm().tick_session(self.task_id, ctx.signals, ctx.platform);
|
||||
|
||||
if let Some(report) = result {
|
||||
let _ = ctx.os.lifecycle().crash_task(self.task_id, Some(&report));
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
|
||||
if pause_requested {
|
||||
match ctx.os.lifecycle().advance_game_pause_budget(self.task_id) {
|
||||
Ok(true) => {
|
||||
ctx.os.vm().transition_render_owner(AppMode::Shell, 0);
|
||||
return Some(FirmwareState::HubHome(HubHomeStep));
|
||||
}
|
||||
Ok(false) => {}
|
||||
Err(_) => {
|
||||
let report = CrashReport::VmPanic {
|
||||
message: "failed to advance game pause budget".to_string(),
|
||||
pc: None,
|
||||
};
|
||||
let _ = ctx.os.lifecycle().crash_task(self.task_id, Some(&report));
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
None
|
||||
}
|
||||
|
||||
|
||||
@@ -1,5 +1,10 @@
|
||||
use crate::firmware::firmware_state::{AppCrashesStep, FirmwareState, ShellRunningStep};
|
||||
use crate::firmware::firmware_state::{
|
||||
AppCrashesStep, FirmwareState, LoadCartridgeStep, ShellRunningStep,
|
||||
};
|
||||
use crate::firmware::prometeu_context::PrometeuContext;
|
||||
use crate::firmware::resident_game_termination;
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::cartridge_loader::CartridgeLoader;
|
||||
use prometeu_hal::log::{LogLevel, LogSource};
|
||||
use prometeu_hal::primitives::Rect;
|
||||
use prometeu_system::SystemProfileAction;
|
||||
@@ -16,21 +21,104 @@ impl HubHomeStep {
|
||||
}
|
||||
|
||||
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
|
||||
let outcome = ctx.hub.update_shell_profile(ctx.os, ctx.vm, ctx.signals, ctx.platform);
|
||||
let outcome = ctx.hub.update_shell_profile(ctx.os, ctx.platform);
|
||||
if let Some(report) = outcome.crash {
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
|
||||
if let Some(SystemProfileAction::LaunchNativeShell(app)) = outcome.action {
|
||||
let task_id = ctx.os.sessions().create_native_shell_task(app.app_id(), app.title());
|
||||
let id = ctx.os.windows().add_window(
|
||||
app.title().to_string(),
|
||||
WindowOwner::Task(task_id),
|
||||
Rect { x: 40, y: 20, w: 400, h: 220 },
|
||||
app.color(),
|
||||
);
|
||||
ctx.os.windows().set_focus(id);
|
||||
return Some(FirmwareState::ShellRunning(ShellRunningStep::new(task_id)));
|
||||
match outcome.action {
|
||||
Some(SystemProfileAction::LaunchNativeShell(app)) => {
|
||||
let task_id = match ctx
|
||||
.os
|
||||
.sessions()
|
||||
.try_create_native_shell_task(app.app_id(), app.title())
|
||||
{
|
||||
Ok(task_id) => task_id,
|
||||
Err(error) => {
|
||||
ctx.os.log(
|
||||
LogLevel::Warn,
|
||||
LogSource::Hub,
|
||||
0,
|
||||
format!("Failed to launch native shell {}: {:?}", app.title(), error),
|
||||
);
|
||||
return None;
|
||||
}
|
||||
};
|
||||
let id = ctx.os.windows().add_window(
|
||||
app.title().to_string(),
|
||||
WindowOwner::Task(task_id),
|
||||
Rect { x: 40, y: 20, w: 400, h: 220 },
|
||||
app.color(),
|
||||
);
|
||||
ctx.os.windows().set_focus(id);
|
||||
return Some(FirmwareState::ShellRunning(ShellRunningStep::new(task_id)));
|
||||
}
|
||||
Some(SystemProfileAction::LaunchGame { target }) => {
|
||||
match CartridgeLoader::load(&target.path) {
|
||||
Ok(cartridge) => {
|
||||
if cartridge.app_mode == AppMode::Game
|
||||
&& let Some(resident_task_id) = ctx.os.lifecycle().resident_game_task()
|
||||
{
|
||||
let resident_app_id = ctx
|
||||
.os
|
||||
.sessions()
|
||||
.vm_session_for_task(resident_task_id)
|
||||
.map(|session| session.app_id)
|
||||
.unwrap_or(0);
|
||||
|
||||
if resident_app_id == cartridge.app_id {
|
||||
return Some(FirmwareState::ResumeResidentGame);
|
||||
}
|
||||
|
||||
if let Err(error) = resident_game_termination::terminate_resident_game(
|
||||
ctx.os,
|
||||
ctx.platform,
|
||||
false,
|
||||
) {
|
||||
ctx.os.log(
|
||||
LogLevel::Error,
|
||||
LogSource::Hub,
|
||||
0,
|
||||
format!(
|
||||
"Failed to terminate resident game app_id {} before launching {}: {:?}",
|
||||
resident_app_id, cartridge.title, error
|
||||
),
|
||||
);
|
||||
return None;
|
||||
}
|
||||
}
|
||||
|
||||
return Some(FirmwareState::LoadCartridge(
|
||||
LoadCartridgeStep::new_game_switch(cartridge),
|
||||
));
|
||||
}
|
||||
Err(error) => {
|
||||
ctx.os.log(
|
||||
LogLevel::Error,
|
||||
LogSource::Hub,
|
||||
0,
|
||||
format!(
|
||||
"Failed to launch Home game {}: {:?}",
|
||||
target.path.display(),
|
||||
error
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
Some(SystemProfileAction::KillResidentGame) => {
|
||||
if let Err(error) =
|
||||
resident_game_termination::terminate_resident_game(ctx.os, ctx.platform, true)
|
||||
{
|
||||
ctx.os.log(
|
||||
LogLevel::Error,
|
||||
LogSource::Hub,
|
||||
0,
|
||||
format!("Failed to kill resident game from Hub: {error:?}"),
|
||||
);
|
||||
}
|
||||
}
|
||||
Some(SystemProfileAction::CloseShell) | None => {}
|
||||
}
|
||||
|
||||
None
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
use crate::firmware::firmware_state::{
|
||||
AppCrashesStep, FirmwareState, GameRunningStep, ShellRunningStep,
|
||||
AppCrashesStep, FirmwareState, GameRunningStep, HubHomeStep, ShellRunningStep,
|
||||
};
|
||||
use crate::firmware::prometeu_context::PrometeuContext;
|
||||
use crate::firmware::resident_game_termination;
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::cartridge::Cartridge;
|
||||
use prometeu_hal::color::Color;
|
||||
@@ -14,11 +15,30 @@ use prometeu_system::windows::WindowOwner;
|
||||
pub struct LoadCartridgeStep {
|
||||
pub cartridge: Cartridge,
|
||||
init_error: Option<CrashReport>,
|
||||
loaded_task_id: Option<prometeu_system::task::TaskId>,
|
||||
loaded_app_mode: Option<AppMode>,
|
||||
failure_recovery: LoadCartridgeFailureRecovery,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
enum LoadCartridgeFailureRecovery {
|
||||
AppCrash,
|
||||
ReturnToHub,
|
||||
}
|
||||
|
||||
impl LoadCartridgeStep {
|
||||
pub fn new(cartridge: Cartridge) -> Self {
|
||||
Self { cartridge, init_error: None }
|
||||
Self {
|
||||
cartridge,
|
||||
init_error: None,
|
||||
loaded_task_id: None,
|
||||
loaded_app_mode: None,
|
||||
failure_recovery: LoadCartridgeFailureRecovery::AppCrash,
|
||||
}
|
||||
}
|
||||
|
||||
pub fn new_game_switch(cartridge: Cartridge) -> Self {
|
||||
Self { failure_recovery: LoadCartridgeFailureRecovery::ReturnToHub, ..Self::new(cartridge) }
|
||||
}
|
||||
|
||||
pub fn on_enter(&mut self, ctx: &mut PrometeuContext) {
|
||||
@@ -29,6 +49,8 @@ impl LoadCartridgeStep {
|
||||
format!("Loading cartridge: {}", self.cartridge.title),
|
||||
);
|
||||
|
||||
ctx.platform.game2d_frame_composer().unbind_scene();
|
||||
|
||||
// Initialize Asset Manager
|
||||
ctx.platform.assets_mut().initialize_for_cartridge(
|
||||
self.cartridge.asset_table.clone(),
|
||||
@@ -36,19 +58,66 @@ impl LoadCartridgeStep {
|
||||
self.cartridge.assets.clone(),
|
||||
);
|
||||
|
||||
self.init_error = ctx.os.vm().initialize(ctx.vm, &self.cartridge).err();
|
||||
match ctx.os.sessions().load_vm_cartridge(&self.cartridge) {
|
||||
Ok(loaded) => {
|
||||
self.loaded_task_id = Some(loaded.task_id);
|
||||
self.loaded_app_mode = Some(loaded.app_mode);
|
||||
}
|
||||
Err(report) => {
|
||||
self.init_error = Some(report.into_crash_report("load VM cartridge into session"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
|
||||
if let Some(report) = self.init_error.take() {
|
||||
if self.failure_recovery == LoadCartridgeFailureRecovery::ReturnToHub {
|
||||
if self.cartridge.app_mode == AppMode::Game
|
||||
&& let Some(task_id) = ctx.os.lifecycle().resident_game_task()
|
||||
{
|
||||
let is_partial_target = ctx
|
||||
.os
|
||||
.sessions()
|
||||
.vm_session_for_task(task_id)
|
||||
.map(|session| session.app_id == self.cartridge.app_id)
|
||||
.unwrap_or(false);
|
||||
|
||||
if is_partial_target {
|
||||
let _ = resident_game_termination::terminate_resident_game(
|
||||
ctx.os,
|
||||
ctx.platform,
|
||||
false,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
ctx.os.log(
|
||||
LogLevel::Error,
|
||||
LogSource::Hub,
|
||||
0,
|
||||
format!(
|
||||
"Failed to switch to game {} app_id {}; returning to Home: {:?}",
|
||||
self.cartridge.title, self.cartridge.app_id, report
|
||||
),
|
||||
);
|
||||
return Some(FirmwareState::HubHome(HubHomeStep));
|
||||
}
|
||||
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
|
||||
if self.cartridge.app_mode == AppMode::Shell {
|
||||
let task_id = ctx
|
||||
.os
|
||||
.sessions()
|
||||
.create_vm_shell_task(self.cartridge.app_id, self.cartridge.title.clone());
|
||||
let Some(task_id) = self.loaded_task_id.take() else {
|
||||
let report = CrashReport::VmPanic {
|
||||
message: format!(
|
||||
"cartridge {} was not loaded into a VM session",
|
||||
self.cartridge.title
|
||||
),
|
||||
pc: None,
|
||||
};
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
};
|
||||
|
||||
if self.loaded_app_mode == Some(AppMode::Shell) {
|
||||
let id = ctx.os.windows().add_window(
|
||||
self.cartridge.title.clone(),
|
||||
WindowOwner::Task(task_id),
|
||||
@@ -59,10 +128,6 @@ impl LoadCartridgeStep {
|
||||
return Some(FirmwareState::ShellRunning(ShellRunningStep::new(task_id)));
|
||||
}
|
||||
|
||||
let task_id = ctx
|
||||
.os
|
||||
.sessions()
|
||||
.create_vm_game_task(self.cartridge.app_id, self.cartridge.title.clone());
|
||||
Some(FirmwareState::GameRunning(GameRunningStep::new(task_id)))
|
||||
}
|
||||
|
||||
|
||||
@@ -9,7 +9,8 @@ pub struct ResetStep;
|
||||
impl ResetStep {
|
||||
pub fn on_enter(&mut self, ctx: &mut PrometeuContext) {
|
||||
ctx.os.log(LogLevel::Info, LogSource::Pos, 0, "Firmware Reset".to_string());
|
||||
ctx.os.vm().reset(ctx.vm);
|
||||
ctx.os.sessions().clear_vm_sessions();
|
||||
ctx.os.vm().reset_global_runtime_state();
|
||||
}
|
||||
|
||||
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
use crate::firmware::firmware_state::{AppCrashesStep, FirmwareState, HubHomeStep};
|
||||
use crate::firmware::prometeu_context::PrometeuContext;
|
||||
use prometeu_hal::log::LogSource;
|
||||
use prometeu_system::process::ProcessKind;
|
||||
use prometeu_system::task::{TaskId, TaskState};
|
||||
use prometeu_system::{CrashReport, SystemProfileAction};
|
||||
|
||||
@@ -59,7 +60,36 @@ impl ShellRunningStep {
|
||||
}
|
||||
}
|
||||
|
||||
let outcome = ctx.hub.update_shell_profile(ctx.os, ctx.vm, ctx.signals, ctx.platform);
|
||||
let process_kind = match ctx.os.lifecycle().process_kind_for_task(self.task_id) {
|
||||
Ok(process_kind) => process_kind,
|
||||
Err(error) => {
|
||||
let report = CrashReport::VmPanic {
|
||||
message: format!(
|
||||
"ShellRunningStep cannot resolve process for {:?}: {:?}",
|
||||
self.task_id, error,
|
||||
),
|
||||
pc: None,
|
||||
};
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
};
|
||||
|
||||
let outcome = match process_kind {
|
||||
ProcessKind::VmShell => {
|
||||
ctx.hub.update_vm_shell_profile(ctx.os, self.task_id, ctx.signals, ctx.platform)
|
||||
}
|
||||
ProcessKind::NativeShell => ctx.hub.update_native_shell_profile(ctx.os, ctx.platform),
|
||||
ProcessKind::VmGame => {
|
||||
let report = CrashReport::VmPanic {
|
||||
message: format!(
|
||||
"ShellRunningStep expected shell process for {:?}, got VmGame",
|
||||
self.task_id,
|
||||
),
|
||||
pc: None,
|
||||
};
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
};
|
||||
|
||||
if let Some(report) = outcome.crash {
|
||||
let _ = ctx.os.lifecycle().crash_task(self.task_id, Some(&report));
|
||||
|
||||
@@ -12,6 +12,7 @@ pub(crate) mod firmware_step_reset;
|
||||
pub(crate) mod firmware_step_shell_running;
|
||||
pub(crate) mod firmware_step_splash_screen;
|
||||
mod prometeu_context;
|
||||
pub(crate) mod resident_game_termination;
|
||||
|
||||
pub use boot_target::BootTarget;
|
||||
pub use firmware::Firmware;
|
||||
|
||||
@@ -1,10 +1,8 @@
|
||||
use crate::firmware::boot_target::BootTarget;
|
||||
use prometeu_hal::{InputSignals, RuntimePlatform};
|
||||
use prometeu_system::{PrometeuHub, SystemOS};
|
||||
use prometeu_vm::VirtualMachine;
|
||||
|
||||
pub struct PrometeuContext<'a> {
|
||||
pub vm: &'a mut VirtualMachine,
|
||||
pub os: &'a mut SystemOS,
|
||||
pub hub: &'a mut PrometeuHub,
|
||||
pub boot_target: &'a BootTarget,
|
||||
|
||||
@@ -0,0 +1,42 @@
|
||||
use prometeu_hal::RuntimePlatform;
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::log::LogSource;
|
||||
use prometeu_system::task::TaskId;
|
||||
use prometeu_system::{LifecycleError, SystemOS};
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub(crate) enum ResidentGameTerminationOutcome {
|
||||
NoResidentGame,
|
||||
Terminated { task_id: TaskId, title: String },
|
||||
}
|
||||
|
||||
pub(crate) fn terminate_resident_game(
|
||||
os: &mut SystemOS,
|
||||
platform: &mut dyn RuntimePlatform,
|
||||
log_manual_hub_kill: bool,
|
||||
) -> Result<ResidentGameTerminationOutcome, LifecycleError> {
|
||||
let Some(task_id) = os.lifecycle().resident_game_task() else {
|
||||
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
|
||||
};
|
||||
|
||||
let title = os
|
||||
.sessions()
|
||||
.vm_session_for_task(task_id)
|
||||
.map(|session| session.title.clone())
|
||||
.unwrap_or_else(|| "<unknown>".to_string());
|
||||
|
||||
let terminated = os.lifecycle().terminate_resident_game()?;
|
||||
let Some(task_id) = terminated else {
|
||||
return Ok(ResidentGameTerminationOutcome::NoResidentGame);
|
||||
};
|
||||
|
||||
os.vm().transition_render_owner(AppMode::Shell, 0);
|
||||
platform.game2d_frame_composer().unbind_scene();
|
||||
platform.assets_mut().shutdown();
|
||||
|
||||
if log_manual_hub_kill {
|
||||
os.info(LogSource::Hub, format!("Resident game killed from Hub: {title}"));
|
||||
}
|
||||
|
||||
Ok(ResidentGameTerminationOutcome::Terminated { task_id, title })
|
||||
}
|
||||
@@ -112,6 +112,12 @@ pub enum LoadStatus {
|
||||
CANCELED = 4,
|
||||
ERROR = 5,
|
||||
UnknownHandle = 6,
|
||||
QUEUED = 7,
|
||||
ACTIVE = 8,
|
||||
SUPERSEDED = 9,
|
||||
EMPTY = 10,
|
||||
INVALID = 11,
|
||||
BackendUnavailable = 12,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
@@ -129,6 +135,36 @@ pub enum AssetOpStatus {
|
||||
Ok = 0,
|
||||
UnknownHandle = 1,
|
||||
InvalidState = 2,
|
||||
Superseded = 3,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct AssetBacklogInfo {
|
||||
pub status: AssetOpStatus,
|
||||
pub pending_count: u32,
|
||||
pub active_handle: HandleId,
|
||||
pub active_asset_id: Option<AssetId>,
|
||||
pub active_bank_type: Option<BankType>,
|
||||
pub active_slot: Option<usize>,
|
||||
pub active_progress: u16,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct AssetBacklogPosition {
|
||||
pub status: AssetOpStatus,
|
||||
pub state: LoadStatus,
|
||||
pub position: u32,
|
||||
pub progress: u16,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct AssetTargetStatus {
|
||||
pub status: AssetOpStatus,
|
||||
pub asset_id: Option<AssetId>,
|
||||
pub handle: HandleId,
|
||||
pub state: LoadStatus,
|
||||
pub position: u32,
|
||||
pub progress: u16,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
|
||||
@@ -1,6 +1,7 @@
|
||||
use crate::asset::{
|
||||
AssetEntry, AssetId, AssetLoadError, AssetOpStatus, BankTelemetry, HandleId, LoadStatus,
|
||||
PreloadEntry, SlotRef, SlotStats,
|
||||
AssetBacklogInfo, AssetBacklogPosition, AssetEntry, AssetId, AssetLoadError, AssetOpStatus,
|
||||
AssetTargetStatus, BankTelemetry, BankType, HandleId, LoadStatus, PreloadEntry, SlotRef,
|
||||
SlotStats,
|
||||
};
|
||||
use crate::cartridge::AssetsPayloadSource;
|
||||
|
||||
@@ -15,6 +16,12 @@ pub trait AssetBridge {
|
||||
fn status(&self, handle: HandleId) -> LoadStatus;
|
||||
fn commit(&self, handle: HandleId) -> AssetOpStatus;
|
||||
fn cancel(&self, handle: HandleId) -> AssetOpStatus;
|
||||
fn backlog_info(&self) -> AssetBacklogInfo;
|
||||
fn backlog_position(&self, handle: HandleId) -> AssetBacklogPosition;
|
||||
fn backlog_move(&self, handle: HandleId, new_position: usize) -> AssetOpStatus;
|
||||
fn backlog_promote(&self, handle: HandleId) -> AssetOpStatus;
|
||||
fn backlog_demote(&self, handle: HandleId) -> AssetOpStatus;
|
||||
fn target_status(&self, bank_type: BankType, slot: usize) -> AssetTargetStatus;
|
||||
fn apply_commits(&self);
|
||||
fn bank_telemetry(&self) -> Vec<BankTelemetry>;
|
||||
fn slot_info(&self, slot: SlotRef) -> SlotStats;
|
||||
|
||||
@@ -297,7 +297,7 @@ pub enum Capability {
|
||||
All,
|
||||
}
|
||||
|
||||
#[derive(Deserialize)]
|
||||
#[derive(Debug, Clone, Deserialize)]
|
||||
pub struct CartridgeManifest {
|
||||
pub magic: String,
|
||||
pub cartridge_version: u32,
|
||||
|
||||
@@ -203,7 +203,7 @@ mod tests {
|
||||
use super::*;
|
||||
use crate::asset::{AssetCodec, AssetEntry, BankType, PreloadEntry};
|
||||
use crate::cartridge::{ASSETS_PA_MAGIC, ASSETS_PA_SCHEMA_VERSION, AssetsPackPrelude};
|
||||
use crate::glyph_bank::GLYPH_BANK_PALETTE_COUNT_V1;
|
||||
use crate::glyph_bank::GLYPH_BANK_MAX_PALETTE_COUNT_V1;
|
||||
use serde_json::json;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::sync::atomic::{AtomicU64, Ordering};
|
||||
@@ -369,14 +369,14 @@ mod tests {
|
||||
bank_type: BankType::GLYPH,
|
||||
offset,
|
||||
size,
|
||||
decoded_size: 16 * 16 + (GLYPH_BANK_PALETTE_COUNT_V1 as u64 * 16 * 4),
|
||||
decoded_size: 16 * 16 + (GLYPH_BANK_MAX_PALETTE_COUNT_V1 as u64 * 16 * 4),
|
||||
codec: AssetCodec::None,
|
||||
metadata: json!({
|
||||
"tile_size": 16,
|
||||
"width": 16,
|
||||
"height": 16,
|
||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
||||
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||
}),
|
||||
}
|
||||
}
|
||||
@@ -452,14 +452,14 @@ mod tests {
|
||||
bank_type: BankType::GLYPH,
|
||||
offset: 4,
|
||||
size: 4,
|
||||
decoded_size: 16 * 16 + (GLYPH_BANK_PALETTE_COUNT_V1 as u64 * 16 * 4),
|
||||
decoded_size: 16 * 16 + (GLYPH_BANK_MAX_PALETTE_COUNT_V1 as u64 * 16 * 4),
|
||||
codec: AssetCodec::None,
|
||||
metadata: json!({
|
||||
"tile_size": 16,
|
||||
"width": 16,
|
||||
"height": 16,
|
||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
||||
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||
}),
|
||||
},
|
||||
];
|
||||
@@ -519,8 +519,8 @@ mod tests {
|
||||
"tile_size": 16,
|
||||
"width": 16,
|
||||
"height": 16,
|
||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
||||
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||
}
|
||||
}],
|
||||
"preload": []
|
||||
@@ -561,8 +561,8 @@ mod tests {
|
||||
"tile_size": 16,
|
||||
"width": 16,
|
||||
"height": 16,
|
||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
||||
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||
}
|
||||
}],
|
||||
"preload": []
|
||||
|
||||
@@ -40,7 +40,7 @@ pub enum DebugResponse {
|
||||
Breakpoints { pcs: Vec<usize> },
|
||||
}
|
||||
|
||||
#[derive(Debug, Serialize, Deserialize)]
|
||||
#[derive(Debug, Clone, Serialize, Deserialize)]
|
||||
pub struct HandshakeCartridge {
|
||||
pub app_id: u32,
|
||||
pub title: String,
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
use crate::color::Color;
|
||||
use serde::{Deserialize, Serialize};
|
||||
|
||||
pub const GLYPH_BANK_PALETTE_COUNT_V1: usize = 64;
|
||||
pub const GLYPH_BANK_MAX_PALETTE_COUNT_V1: usize = 64;
|
||||
pub const GLYPH_BANK_COLORS_PER_PALETTE: usize = 16;
|
||||
|
||||
/// Standard sizes for square tiles.
|
||||
@@ -35,22 +35,59 @@ pub struct GlyphBank {
|
||||
/// Palette indices are ordinary indices; transparency is resolved through
|
||||
/// the RGBA alpha channel of the palette entry.
|
||||
pub pixel_indices: Vec<u8>,
|
||||
/// Runtime-facing v1 palette table: 64 palettes of 16 RGBA8888 colors each.
|
||||
pub palettes: [[Color; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1],
|
||||
/// Runtime-facing v1 palette table.
|
||||
///
|
||||
/// Palette identity is the direct index in this vector. A resident glyph
|
||||
/// bank carries exactly the palettes materialized from its payload.
|
||||
pub palettes: Vec<[Color; GLYPH_BANK_COLORS_PER_PALETTE]>,
|
||||
}
|
||||
|
||||
impl GlyphBank {
|
||||
/// Creates an empty glyph bank with the specified dimensions.
|
||||
/// Creates an empty glyph bank with one palette.
|
||||
pub fn new(tile_size: TileSize, width: usize, height: usize) -> Self {
|
||||
Self::with_palette_count(tile_size, width, height, 1)
|
||||
}
|
||||
|
||||
/// Creates an empty glyph bank with the specified resident palette count.
|
||||
pub fn with_palette_count(
|
||||
tile_size: TileSize,
|
||||
width: usize,
|
||||
height: usize,
|
||||
palette_count: usize,
|
||||
) -> Self {
|
||||
assert!(
|
||||
(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count),
|
||||
"glyph bank palette_count must be in 1..={}",
|
||||
GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||
);
|
||||
|
||||
Self {
|
||||
tile_size,
|
||||
width,
|
||||
height,
|
||||
pixel_indices: vec![0; width * height],
|
||||
palettes: [[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1],
|
||||
palettes: vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count],
|
||||
}
|
||||
}
|
||||
|
||||
/// Returns the number of resident palettes.
|
||||
pub fn palette_count(&self) -> usize {
|
||||
self.palettes.len()
|
||||
}
|
||||
|
||||
/// Returns true when the palette id is valid for this resident bank.
|
||||
pub fn contains_palette(&self, palette_id: u8) -> bool {
|
||||
(palette_id as usize) < self.palette_count()
|
||||
}
|
||||
|
||||
/// Returns a mutable palette slot when the palette exists.
|
||||
pub fn palette_mut(
|
||||
&mut self,
|
||||
palette_id: u8,
|
||||
) -> Option<&mut [Color; GLYPH_BANK_COLORS_PER_PALETTE]> {
|
||||
self.palettes.get_mut(palette_id as usize)
|
||||
}
|
||||
|
||||
/// 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)
|
||||
@@ -71,11 +108,48 @@ impl GlyphBank {
|
||||
}
|
||||
|
||||
/// Maps a 4-bit index to a real RGBA8888 Color using the specified palette.
|
||||
pub fn resolve_color(&self, palette_id: u8, pixel_index: u8) -> Color {
|
||||
pub fn resolve_color(&self, palette_id: u8, pixel_index: u8) -> Option<Color> {
|
||||
self.palettes
|
||||
.get(palette_id as usize)
|
||||
.and_then(|palette| palette.get(pixel_index as usize))
|
||||
.copied()
|
||||
.unwrap_or(Color::TRANSPARENT)
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn new_glyph_bank_uses_single_resident_palette() {
|
||||
let bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
||||
|
||||
assert_eq!(bank.palette_count(), 1);
|
||||
assert!(bank.contains_palette(0));
|
||||
assert!(!bank.contains_palette(1));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn glyph_bank_can_materialize_v1_max_palette_count() {
|
||||
let bank =
|
||||
GlyphBank::with_palette_count(TileSize::Size8, 8, 8, GLYPH_BANK_MAX_PALETTE_COUNT_V1);
|
||||
|
||||
assert_eq!(bank.palette_count(), GLYPH_BANK_MAX_PALETTE_COUNT_V1);
|
||||
assert!(bank.contains_palette((GLYPH_BANK_MAX_PALETTE_COUNT_V1 - 1) as u8));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invalid_palette_lookup_is_distinct_from_transparent_color() {
|
||||
let mut bank = GlyphBank::new(TileSize::Size8, 8, 8);
|
||||
bank.palette_mut(0).unwrap()[1] = Color::TRANSPARENT;
|
||||
|
||||
assert_eq!(bank.resolve_color(0, 1), Some(Color::TRANSPARENT));
|
||||
assert_eq!(bank.resolve_color(1, 1), None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
#[should_panic(expected = "glyph bank palette_count must be in 1..=64")]
|
||||
fn glyph_bank_rejects_zero_resident_palettes() {
|
||||
let _ = GlyphBank::with_palette_count(TileSize::Size8, 8, 8, 0);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -29,7 +29,6 @@ pub use resolver::{
|
||||
#[repr(u32)]
|
||||
pub enum Syscall {
|
||||
SystemHasCart = 0x0001,
|
||||
SystemRunCart = 0x0002,
|
||||
GfxClear = 0x1001,
|
||||
GfxFillRect = 0x1002,
|
||||
GfxDrawLine = 0x1003,
|
||||
@@ -69,6 +68,12 @@ pub enum Syscall {
|
||||
AssetStatus = 0x6002,
|
||||
AssetCommit = 0x6003,
|
||||
AssetCancel = 0x6004,
|
||||
AssetBacklogInfo = 0x6005,
|
||||
AssetBacklogPosition = 0x6006,
|
||||
AssetBacklogMove = 0x6007,
|
||||
AssetBacklogPromote = 0x6008,
|
||||
AssetBacklogDemote = 0x6009,
|
||||
AssetTargetStatus = 0x600A,
|
||||
BankInfo = 0x6101,
|
||||
}
|
||||
|
||||
|
||||
@@ -24,4 +24,40 @@ pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
|
||||
.caps(caps::ASSET)
|
||||
.non_deterministic()
|
||||
.cost(20),
|
||||
SyscallRegistryEntry::builder(Syscall::AssetBacklogInfo, "asset", "backlog_info")
|
||||
.args(0)
|
||||
.rets(7)
|
||||
.caps(caps::ASSET)
|
||||
.non_deterministic()
|
||||
.cost(5),
|
||||
SyscallRegistryEntry::builder(Syscall::AssetBacklogPosition, "asset", "backlog_position")
|
||||
.args(1)
|
||||
.rets(4)
|
||||
.caps(caps::ASSET)
|
||||
.non_deterministic()
|
||||
.cost(5),
|
||||
SyscallRegistryEntry::builder(Syscall::AssetBacklogMove, "asset", "backlog_move")
|
||||
.args(2)
|
||||
.rets(1)
|
||||
.caps(caps::ASSET)
|
||||
.non_deterministic()
|
||||
.cost(10),
|
||||
SyscallRegistryEntry::builder(Syscall::AssetBacklogPromote, "asset", "backlog_promote")
|
||||
.args(1)
|
||||
.rets(1)
|
||||
.caps(caps::ASSET)
|
||||
.non_deterministic()
|
||||
.cost(10),
|
||||
SyscallRegistryEntry::builder(Syscall::AssetBacklogDemote, "asset", "backlog_demote")
|
||||
.args(1)
|
||||
.rets(1)
|
||||
.caps(caps::ASSET)
|
||||
.non_deterministic()
|
||||
.cost(10),
|
||||
SyscallRegistryEntry::builder(Syscall::AssetTargetStatus, "asset", "target_status")
|
||||
.args(2)
|
||||
.rets(6)
|
||||
.caps(caps::ASSET)
|
||||
.non_deterministic()
|
||||
.cost(5),
|
||||
];
|
||||
|
||||
@@ -1,11 +1,6 @@
|
||||
use crate::syscalls::{Syscall, SyscallRegistryEntry, caps};
|
||||
|
||||
pub(crate) const ENTRIES: &[SyscallRegistryEntry] = &[
|
||||
SyscallRegistryEntry::builder(Syscall::SystemHasCart, "system", "has_cart")
|
||||
pub(crate) const ENTRIES: &[SyscallRegistryEntry] =
|
||||
&[SyscallRegistryEntry::builder(Syscall::SystemHasCart, "system", "has_cart")
|
||||
.rets(1)
|
||||
.caps(caps::SYSTEM),
|
||||
SyscallRegistryEntry::builder(Syscall::SystemRunCart, "system", "run_cart")
|
||||
.caps(caps::SYSTEM)
|
||||
.non_deterministic()
|
||||
.cost(50),
|
||||
];
|
||||
.caps(caps::SYSTEM)];
|
||||
|
||||
@@ -13,7 +13,6 @@ impl Syscall {
|
||||
pub fn from_u32(id: u32) -> Option<Self> {
|
||||
match id {
|
||||
0x0001 => Some(Self::SystemHasCart),
|
||||
0x0002 => Some(Self::SystemRunCart),
|
||||
0x1001 => Some(Self::GfxClear),
|
||||
0x1002 => Some(Self::GfxFillRect),
|
||||
0x1003 => Some(Self::GfxDrawLine),
|
||||
@@ -53,6 +52,12 @@ impl Syscall {
|
||||
0x6002 => Some(Self::AssetStatus),
|
||||
0x6003 => Some(Self::AssetCommit),
|
||||
0x6004 => Some(Self::AssetCancel),
|
||||
0x6005 => Some(Self::AssetBacklogInfo),
|
||||
0x6006 => Some(Self::AssetBacklogPosition),
|
||||
0x6007 => Some(Self::AssetBacklogMove),
|
||||
0x6008 => Some(Self::AssetBacklogPromote),
|
||||
0x6009 => Some(Self::AssetBacklogDemote),
|
||||
0x600A => Some(Self::AssetTargetStatus),
|
||||
0x6101 => Some(Self::BankInfo),
|
||||
_ => None,
|
||||
}
|
||||
@@ -69,7 +74,6 @@ impl Syscall {
|
||||
pub fn name(&self) -> &'static str {
|
||||
match self {
|
||||
Self::SystemHasCart => "SystemHasCart",
|
||||
Self::SystemRunCart => "SystemRunCart",
|
||||
Self::GfxClear => "GfxClear",
|
||||
Self::GfxFillRect => "GfxFillRect",
|
||||
Self::GfxDrawLine => "GfxDrawLine",
|
||||
@@ -109,6 +113,12 @@ impl Syscall {
|
||||
Self::AssetStatus => "AssetStatus",
|
||||
Self::AssetCommit => "AssetCommit",
|
||||
Self::AssetCancel => "AssetCancel",
|
||||
Self::AssetBacklogInfo => "AssetBacklogInfo",
|
||||
Self::AssetBacklogPosition => "AssetBacklogPosition",
|
||||
Self::AssetBacklogMove => "AssetBacklogMove",
|
||||
Self::AssetBacklogPromote => "AssetBacklogPromote",
|
||||
Self::AssetBacklogDemote => "AssetBacklogDemote",
|
||||
Self::AssetTargetStatus => "AssetTargetStatus",
|
||||
Self::BankInfo => "BankInfo",
|
||||
}
|
||||
}
|
||||
|
||||
@@ -72,6 +72,33 @@ fn resolver_rejects_removed_legacy_gfx_set_sprite_identity() {
|
||||
assert_eq!(err, LoadError::UnknownSyscall { module: "gfx2d", name: "set_sprite", version: 1 });
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resolver_rejects_userland_system_run_cart_identity() {
|
||||
assert!(Syscall::from_u32(0x0002).is_none());
|
||||
assert!(resolve_syscall("system", "run_cart", 1).is_none());
|
||||
|
||||
let requested = [SyscallIdentity { module: "system", name: "run_cart", version: 1 }];
|
||||
let err = resolve_program_syscalls(&requested, caps::ALL).unwrap_err();
|
||||
assert_eq!(err, LoadError::UnknownSyscall { module: "system", name: "run_cart", version: 1 });
|
||||
|
||||
let declared = [prometeu_bytecode::SyscallDecl {
|
||||
module: "system".into(),
|
||||
name: "run_cart".into(),
|
||||
version: 1,
|
||||
arg_slots: 0,
|
||||
ret_slots: 0,
|
||||
}];
|
||||
let err = resolve_declared_program_syscalls(&declared, caps::ALL).unwrap_err();
|
||||
assert_eq!(
|
||||
err,
|
||||
DeclaredLoadError::UnknownSyscall {
|
||||
module: "system".into(),
|
||||
name: "run_cart".into(),
|
||||
version: 1,
|
||||
}
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resolver_enforces_capabilities() {
|
||||
let requested = [SyscallIdentity { module: "gfx2d", name: "clear", version: 1 }];
|
||||
@@ -258,6 +285,30 @@ fn status_first_syscall_signatures_are_pinned() {
|
||||
assert_eq!(asset_cancel.arg_slots, 1);
|
||||
assert_eq!(asset_cancel.ret_slots, 1);
|
||||
|
||||
let asset_backlog_info = meta_for(Syscall::AssetBacklogInfo);
|
||||
assert_eq!(asset_backlog_info.arg_slots, 0);
|
||||
assert_eq!(asset_backlog_info.ret_slots, 7);
|
||||
|
||||
let asset_backlog_position = meta_for(Syscall::AssetBacklogPosition);
|
||||
assert_eq!(asset_backlog_position.arg_slots, 1);
|
||||
assert_eq!(asset_backlog_position.ret_slots, 4);
|
||||
|
||||
let asset_backlog_move = meta_for(Syscall::AssetBacklogMove);
|
||||
assert_eq!(asset_backlog_move.arg_slots, 2);
|
||||
assert_eq!(asset_backlog_move.ret_slots, 1);
|
||||
|
||||
let asset_backlog_promote = meta_for(Syscall::AssetBacklogPromote);
|
||||
assert_eq!(asset_backlog_promote.arg_slots, 1);
|
||||
assert_eq!(asset_backlog_promote.ret_slots, 1);
|
||||
|
||||
let asset_backlog_demote = meta_for(Syscall::AssetBacklogDemote);
|
||||
assert_eq!(asset_backlog_demote.arg_slots, 1);
|
||||
assert_eq!(asset_backlog_demote.ret_slots, 1);
|
||||
|
||||
let asset_target_status = meta_for(Syscall::AssetTargetStatus);
|
||||
assert_eq!(asset_target_status.arg_slots, 2);
|
||||
assert_eq!(asset_target_status.ret_slots, 6);
|
||||
|
||||
let bank_info = meta_for(Syscall::BankInfo);
|
||||
assert_eq!(bank_info.arg_slots, 1);
|
||||
assert_eq!(bank_info.ret_slots, 2);
|
||||
|
||||
@@ -4,14 +4,33 @@ mod programs;
|
||||
mod services;
|
||||
|
||||
pub use crash_report::CrashReport;
|
||||
pub use os::{LifecycleError, LifecycleOperation, SystemOS};
|
||||
pub use programs::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
|
||||
pub use os::{
|
||||
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
|
||||
LifecycleOperation, SessionError, SystemOS,
|
||||
};
|
||||
pub use programs::{
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
|
||||
SystemProfileUpdate,
|
||||
};
|
||||
pub use prometeu_hal::{RenderWorkerBackend, RenderWorkerFrameSink};
|
||||
pub use services::async_work::{
|
||||
AsyncWorkActiveJob, AsyncWorkCancelToken, AsyncWorkJobContext, AsyncWorkJobId,
|
||||
AsyncWorkJobKind, AsyncWorkJobOutcome, AsyncWorkLane, AsyncWorkLaneConfig,
|
||||
AsyncWorkLaneController, AsyncWorkLaneError, AsyncWorkLaneTelemetry, AsyncWorkPriority,
|
||||
};
|
||||
pub use services::foreground::{
|
||||
ForegroundOwner, ForegroundStack, ForegroundStackError, ResidentGame, ResidentGameState,
|
||||
};
|
||||
pub use services::fs;
|
||||
pub use services::game_library::{
|
||||
GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, GameSwitchTarget, discover_games_root,
|
||||
};
|
||||
pub use services::memcard::MemcardAsyncLaneOperation;
|
||||
pub use services::process;
|
||||
pub use services::task;
|
||||
pub use services::vm_runtime::{
|
||||
LatestRenderFrameStore, RenderWorkerConfig, RenderWorkerController, RenderWorkerHandoff,
|
||||
RenderWorkerHandoffWait, RenderWorkerOwnership, VirtualMachineRuntime,
|
||||
};
|
||||
pub use services::vm_session;
|
||||
pub use services::windows;
|
||||
|
||||
@@ -1,8 +1,14 @@
|
||||
use crate::CrashReport;
|
||||
use crate::os::SystemOS;
|
||||
use crate::os::{LifecycleError, LifecycleOperation};
|
||||
use crate::process::{ProcessId, ProcessState};
|
||||
use crate::task::{TaskId, TaskState};
|
||||
use crate::os::{
|
||||
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
|
||||
LifecycleOperation,
|
||||
};
|
||||
use crate::process::{Process, ProcessId, ProcessKind, ProcessState};
|
||||
use crate::services::foreground::{
|
||||
ForegroundOwner, ForegroundStackError, ResidentGame, ResidentGameState,
|
||||
};
|
||||
use crate::task::{TaskId, TaskKind, TaskState};
|
||||
|
||||
pub struct LifecycleFacade<'a> {
|
||||
pub(in crate::os) os: &'a mut SystemOS,
|
||||
@@ -14,28 +20,145 @@ impl<'a> LifecycleFacade<'a> {
|
||||
}
|
||||
|
||||
pub fn process_state_for_task(&self, task_id: TaskId) -> Result<ProcessState, LifecycleError> {
|
||||
let process_id = process_id_for_task(self.os, task_id)?;
|
||||
self.os
|
||||
.process_manager
|
||||
.get(process_id)
|
||||
.map(|process| process.state)
|
||||
.ok_or(LifecycleError::ProcessNotFound(process_id))
|
||||
process_for_task(self.os, task_id).map(|process| process.state)
|
||||
}
|
||||
|
||||
pub fn process_kind_for_task(&self, task_id: TaskId) -> Result<ProcessKind, LifecycleError> {
|
||||
process_for_task(self.os, task_id).map(|process| process.kind)
|
||||
}
|
||||
|
||||
pub fn set_foreground_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
|
||||
match task_kind_for_task(self.os, task_id)? {
|
||||
TaskKind::Game => self.set_game_foreground_task(task_id),
|
||||
TaskKind::Shell => self.set_shell_foreground_task(task_id),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn set_game_foreground_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
|
||||
let process_id = process_id_for_task(self.os, task_id)?;
|
||||
|
||||
if task_kind_for_task(self.os, task_id)? != TaskKind::Game {
|
||||
return Err(LifecycleError::InvalidTransition {
|
||||
task_id,
|
||||
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
|
||||
operation: LifecycleOperation::SetForeground,
|
||||
});
|
||||
}
|
||||
|
||||
self.os.foreground_stack.set_game_foreground(task_id).map_err(map_foreground_error)?;
|
||||
self.os.task_manager.set_foreground(task_id);
|
||||
self.os.process_manager.mark_running(process_id);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn set_shell_foreground_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
|
||||
let process_id = process_id_for_task(self.os, task_id)?;
|
||||
|
||||
if task_kind_for_task(self.os, task_id)? != TaskKind::Shell {
|
||||
return Err(LifecycleError::InvalidTransition {
|
||||
task_id,
|
||||
from: self.task_state(task_id).unwrap_or(TaskState::Closed),
|
||||
operation: LifecycleOperation::SetForeground,
|
||||
});
|
||||
}
|
||||
|
||||
if let Some(game_task_id) = self.os.foreground_stack.resident_game_task()
|
||||
&& game_task_id != task_id
|
||||
&& self.task_state(game_task_id) != Some(TaskState::Suspended)
|
||||
{
|
||||
let game_process_id = process_id_for_task(self.os, game_task_id)?;
|
||||
self.os.task_manager.mark_suspended(game_task_id);
|
||||
self.os.process_manager.mark_suspended(game_process_id);
|
||||
}
|
||||
|
||||
self.os.foreground_stack.set_shell_foreground(task_id).map_err(map_foreground_error)?;
|
||||
self.os.task_manager.set_foreground(task_id);
|
||||
self.os.process_manager.mark_running(process_id);
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn foreground_owner(&self) -> ForegroundOwner {
|
||||
self.os.foreground_stack.owner()
|
||||
}
|
||||
|
||||
pub fn resident_game(&self) -> Option<ResidentGame> {
|
||||
self.os.foreground_stack.resident_game()
|
||||
}
|
||||
|
||||
pub fn resident_game_task(&self) -> Option<TaskId> {
|
||||
self.os.foreground_stack.resident_game_task()
|
||||
}
|
||||
|
||||
pub fn request_home_from_game(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
|
||||
let _process_id = process_id_for_task(self.os, task_id)?;
|
||||
let previous = self.os.foreground_stack.resident_game();
|
||||
|
||||
self.os
|
||||
.foreground_stack
|
||||
.request_home_from_game(task_id, DEFAULT_GAME_PAUSE_BUDGET_TICKS)
|
||||
.map_err(map_foreground_error)?;
|
||||
|
||||
if !matches!(
|
||||
previous.map(|game| game.state),
|
||||
Some(ResidentGameState::PauseRequested { .. } | ResidentGameState::PausedSuspended)
|
||||
) {
|
||||
self.os
|
||||
.game_lifecycle_events
|
||||
.push(GameLifecycleEvent { task_id, kind: GameLifecycleEventKind::Pause });
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn advance_game_pause_budget(&mut self, task_id: TaskId) -> Result<bool, LifecycleError> {
|
||||
let expired =
|
||||
self.os.foreground_stack.advance_pause_budget(task_id).map_err(map_foreground_error)?;
|
||||
|
||||
if expired {
|
||||
let process_id = process_id_for_task(self.os, task_id)?;
|
||||
self.os.task_manager.mark_suspended(task_id);
|
||||
self.os.process_manager.mark_suspended(process_id);
|
||||
}
|
||||
|
||||
Ok(expired)
|
||||
}
|
||||
|
||||
pub fn pending_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
|
||||
&self.os.game_lifecycle_events
|
||||
}
|
||||
|
||||
pub fn take_game_lifecycle_events(&mut self) -> Vec<GameLifecycleEvent> {
|
||||
std::mem::take(&mut self.os.game_lifecycle_events)
|
||||
}
|
||||
|
||||
pub fn return_to_hub(&mut self) {
|
||||
self.os.foreground_stack.return_to_hub();
|
||||
self.os.task_manager.clear_foreground();
|
||||
}
|
||||
|
||||
pub fn suspend_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
|
||||
let process_id = process_id_for_task(self.os, task_id)?;
|
||||
|
||||
self.os.task_manager.mark_suspended(task_id);
|
||||
self.os.process_manager.mark_suspended(process_id);
|
||||
match self.os.foreground_stack.owner() {
|
||||
ForegroundOwner::Game(owner) if owner == task_id => {
|
||||
self.os
|
||||
.foreground_stack
|
||||
.request_home_from_game(task_id, DEFAULT_GAME_PAUSE_BUDGET_TICKS)
|
||||
.map_err(map_foreground_error)?;
|
||||
self.os
|
||||
.foreground_stack
|
||||
.advance_pause_budget(task_id)
|
||||
.map_err(map_foreground_error)?;
|
||||
}
|
||||
ForegroundOwner::Shell(owner) if owner == task_id => {
|
||||
self.os.foreground_stack.return_to_hub();
|
||||
}
|
||||
_ => {}
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
@@ -54,8 +177,32 @@ impl<'a> LifecycleFacade<'a> {
|
||||
|
||||
let process_id = process_id_for_task(self.os, task_id)?;
|
||||
|
||||
self.os.task_manager.set_foreground(task_id);
|
||||
self.os.process_manager.mark_running(process_id);
|
||||
match task_kind_for_task(self.os, task_id)? {
|
||||
TaskKind::Game => {
|
||||
self.os
|
||||
.foreground_stack
|
||||
.request_resume_game(task_id)
|
||||
.map_err(map_foreground_error)?;
|
||||
self.os.task_manager.set_foreground(task_id);
|
||||
self.os.process_manager.mark_running(process_id);
|
||||
self.os.game_lifecycle_events.push(GameLifecycleEvent {
|
||||
task_id,
|
||||
kind: GameLifecycleEventKind::ResumeForeground,
|
||||
});
|
||||
self.os
|
||||
.foreground_stack
|
||||
.complete_resume_game(task_id)
|
||||
.map_err(map_foreground_error)?;
|
||||
}
|
||||
TaskKind::Shell => {
|
||||
self.os
|
||||
.foreground_stack
|
||||
.set_shell_foreground(task_id)
|
||||
.map_err(map_foreground_error)?;
|
||||
self.os.task_manager.set_foreground(task_id);
|
||||
self.os.process_manager.mark_running(process_id);
|
||||
}
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
@@ -65,10 +212,38 @@ impl<'a> LifecycleFacade<'a> {
|
||||
|
||||
self.os.task_manager.close_task(task_id);
|
||||
self.os.process_manager.mark_stopped(process_id);
|
||||
if self.os.foreground_stack.resident_game_task() == Some(task_id) {
|
||||
self.os.foreground_stack.clear_resident_game(task_id);
|
||||
} else if matches!(self.os.foreground_stack.owner(), ForegroundOwner::Shell(owner) if owner == task_id)
|
||||
{
|
||||
self.os.foreground_stack.return_to_hub();
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn terminate_resident_game(&mut self) -> Result<Option<TaskId>, LifecycleError> {
|
||||
let Some(task_id) = self.os.foreground_stack.resident_game_task() else {
|
||||
return Ok(None);
|
||||
};
|
||||
|
||||
let process_id = process_id_for_task(self.os, task_id)?;
|
||||
|
||||
self.os.task_manager.close_task(task_id);
|
||||
self.os.process_manager.mark_stopped(process_id);
|
||||
self.os.foreground_stack.clear_resident_game(task_id);
|
||||
self.os.vm_sessions.remove_for_task(task_id);
|
||||
self.os.game_lifecycle_events.retain(|event| event.task_id != task_id);
|
||||
|
||||
if matches!(self.os.foreground_stack.owner(), ForegroundOwner::Game(owner) if owner == task_id)
|
||||
{
|
||||
self.os.foreground_stack.return_to_hub();
|
||||
self.os.task_manager.clear_foreground();
|
||||
}
|
||||
|
||||
Ok(Some(task_id))
|
||||
}
|
||||
|
||||
pub fn crash_task(
|
||||
&mut self,
|
||||
task_id: TaskId,
|
||||
@@ -78,11 +253,22 @@ impl<'a> LifecycleFacade<'a> {
|
||||
|
||||
self.os.task_manager.mark_crashed(task_id);
|
||||
self.os.process_manager.mark_crashed(process_id);
|
||||
if self.os.foreground_stack.resident_game_task() == Some(task_id) {
|
||||
self.os.foreground_stack.clear_resident_game(task_id);
|
||||
} else if matches!(self.os.foreground_stack.owner(), ForegroundOwner::Shell(owner) if owner == task_id)
|
||||
{
|
||||
self.os.foreground_stack.return_to_hub();
|
||||
}
|
||||
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
fn task_kind_for_task(os: &SystemOS, task_id: TaskId) -> Result<TaskKind, LifecycleError> {
|
||||
let task = os.task_manager.get(task_id).ok_or(LifecycleError::TaskNotFound(task_id))?;
|
||||
Ok(task.kind)
|
||||
}
|
||||
|
||||
fn process_id_for_task(os: &SystemOS, task_id: TaskId) -> Result<ProcessId, LifecycleError> {
|
||||
let task = os.task_manager.get(task_id).ok_or(LifecycleError::TaskNotFound(task_id))?;
|
||||
|
||||
@@ -92,3 +278,22 @@ fn process_id_for_task(os: &SystemOS, task_id: TaskId) -> Result<ProcessId, Life
|
||||
|
||||
Ok(task.process_id)
|
||||
}
|
||||
|
||||
fn process_for_task(os: &SystemOS, task_id: TaskId) -> Result<&Process, LifecycleError> {
|
||||
let process_id = process_id_for_task(os, task_id)?;
|
||||
os.process_manager.get(process_id).ok_or(LifecycleError::ProcessNotFound(process_id))
|
||||
}
|
||||
|
||||
fn map_foreground_error(error: ForegroundStackError) -> LifecycleError {
|
||||
match error {
|
||||
ForegroundStackError::ResidentGameAlreadyExists { existing, requested } => {
|
||||
LifecycleError::ResidentGameAlreadyExists { existing, requested }
|
||||
}
|
||||
ForegroundStackError::ForegroundShellAlreadyExists { existing, requested } => {
|
||||
LifecycleError::ForegroundShellAlreadyExists { existing, requested }
|
||||
}
|
||||
ForegroundStackError::TaskIsNotResidentGame(task_id) => {
|
||||
LifecycleError::TaskIsNotResidentGame(task_id)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -6,6 +6,6 @@ mod window;
|
||||
|
||||
pub use fs::FsFacade;
|
||||
pub use lifecycle::LifecycleFacade;
|
||||
pub use sessions::SessionsFacade;
|
||||
pub use sessions::{SessionError, SessionsFacade};
|
||||
pub use vm::VmFacade;
|
||||
pub use window::WindowFacade;
|
||||
|
||||
@@ -1,44 +1,209 @@
|
||||
use crate::CrashReport;
|
||||
use crate::os::LifecycleError;
|
||||
use crate::os::SystemOS;
|
||||
use crate::process::ProcessId;
|
||||
use crate::task::TaskId;
|
||||
use crate::vm_session::{VmSession, VmSessionError};
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::cartridge::Cartridge;
|
||||
use std::sync::Arc;
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct LoadedVmCartridge {
|
||||
pub task_id: TaskId,
|
||||
pub app_mode: AppMode,
|
||||
pub reused_existing_session: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum SessionError {
|
||||
Lifecycle(LifecycleError),
|
||||
VmSession(VmSessionError),
|
||||
TaskNotFound(TaskId),
|
||||
ProcessNotFound(ProcessId),
|
||||
MissingVmSession(TaskId),
|
||||
Initialization(CrashReport),
|
||||
}
|
||||
|
||||
impl SessionError {
|
||||
pub fn into_crash_report(self, operation: &str) -> CrashReport {
|
||||
match self {
|
||||
Self::Initialization(report) => report,
|
||||
error => {
|
||||
CrashReport::VmPanic { message: format!("{operation} failed: {error:?}"), pc: None }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl From<LifecycleError> for SessionError {
|
||||
fn from(error: LifecycleError) -> Self {
|
||||
Self::Lifecycle(error)
|
||||
}
|
||||
}
|
||||
|
||||
impl From<VmSessionError> for SessionError {
|
||||
fn from(error: VmSessionError) -> Self {
|
||||
Self::VmSession(error)
|
||||
}
|
||||
}
|
||||
|
||||
pub struct SessionsFacade<'a> {
|
||||
pub(in crate::os) os: &'a mut SystemOS,
|
||||
}
|
||||
|
||||
impl<'a> SessionsFacade<'a> {
|
||||
#[cfg(test)]
|
||||
pub fn create_vm_game_task(&mut self, app_id: u32, title: impl Into<String>) -> TaskId {
|
||||
self.try_create_vm_game_task(app_id, title)
|
||||
.expect("test/setup VM game creation should succeed")
|
||||
}
|
||||
|
||||
pub fn try_create_vm_game_task(
|
||||
&mut self,
|
||||
app_id: u32,
|
||||
title: impl Into<String>,
|
||||
) -> Result<TaskId, SessionError> {
|
||||
if let Some(session) = self.os.vm_sessions.resident_game_for_app(app_id) {
|
||||
return Ok(session.task_id);
|
||||
}
|
||||
|
||||
let title = title.into();
|
||||
let process_id = self.os.process_manager.spawn_vm_game(app_id, title.clone());
|
||||
let task_id = self.os.task_manager.create_game_task(process_id, app_id, title);
|
||||
self.os
|
||||
.lifecycle()
|
||||
.set_foreground_task(task_id)
|
||||
.expect("newly created game task should have an associated process");
|
||||
self.os.lifecycle().set_game_foreground_task(task_id)?;
|
||||
self.try_create_vm_session_for_task(task_id)?;
|
||||
|
||||
task_id
|
||||
Ok(task_id)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
pub fn create_vm_shell_task(&mut self, app_id: u32, title: impl Into<String>) -> TaskId {
|
||||
self.try_create_vm_shell_task(app_id, title)
|
||||
.expect("test/setup VM shell creation should succeed")
|
||||
}
|
||||
|
||||
pub fn try_create_vm_shell_task(
|
||||
&mut self,
|
||||
app_id: u32,
|
||||
title: impl Into<String>,
|
||||
) -> Result<TaskId, SessionError> {
|
||||
let title = title.into();
|
||||
let process_id = self.os.process_manager.spawn_vm_shell(app_id, title.clone());
|
||||
let task_id = self.os.task_manager.create_shell_task(process_id, app_id, title);
|
||||
self.os
|
||||
.lifecycle()
|
||||
.set_foreground_task(task_id)
|
||||
.expect("newly created shell task should have an associated process");
|
||||
self.os.lifecycle().set_shell_foreground_task(task_id)?;
|
||||
self.try_create_vm_session_for_task(task_id)?;
|
||||
|
||||
task_id
|
||||
Ok(task_id)
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
pub fn create_native_shell_task(&mut self, app_id: u32, title: impl Into<String>) -> TaskId {
|
||||
self.try_create_native_shell_task(app_id, title)
|
||||
.expect("test/setup native shell creation should succeed")
|
||||
}
|
||||
|
||||
pub fn try_create_native_shell_task(
|
||||
&mut self,
|
||||
app_id: u32,
|
||||
title: impl Into<String>,
|
||||
) -> Result<TaskId, SessionError> {
|
||||
let title = title.into();
|
||||
let process_id = self.os.process_manager.spawn_native_shell(app_id, title.clone());
|
||||
let task_id = self.os.task_manager.create_shell_task(process_id, app_id, title);
|
||||
self.os
|
||||
.lifecycle()
|
||||
.set_foreground_task(task_id)
|
||||
.expect("newly created native shell task should have an associated process");
|
||||
self.os.lifecycle().set_shell_foreground_task(task_id)?;
|
||||
|
||||
task_id
|
||||
Ok(task_id)
|
||||
}
|
||||
|
||||
pub fn load_vm_cartridge(
|
||||
&mut self,
|
||||
cartridge: &Cartridge,
|
||||
) -> Result<LoadedVmCartridge, SessionError> {
|
||||
let existing_game_task = if cartridge.app_mode == AppMode::Game {
|
||||
self.os
|
||||
.vm_sessions
|
||||
.resident_game_for_app(cartridge.app_id)
|
||||
.map(|session| session.task_id)
|
||||
} else {
|
||||
None
|
||||
};
|
||||
|
||||
let (task_id, reused_existing_session) = if let Some(task_id) = existing_game_task {
|
||||
(task_id, true)
|
||||
} else if cartridge.app_mode == AppMode::Shell {
|
||||
(self.try_create_vm_shell_task(cartridge.app_id, cartridge.title.clone())?, false)
|
||||
} else {
|
||||
let task_id =
|
||||
self.try_create_vm_game_task(cartridge.app_id, cartridge.title.clone())?;
|
||||
(task_id, false)
|
||||
};
|
||||
|
||||
if !reused_existing_session {
|
||||
self.try_initialize_session_cartridge(task_id, cartridge)?;
|
||||
}
|
||||
|
||||
Ok(LoadedVmCartridge { task_id, app_mode: cartridge.app_mode, reused_existing_session })
|
||||
}
|
||||
|
||||
pub fn vm_session_for_task(&self, task_id: TaskId) -> Option<&VmSession> {
|
||||
self.os.vm_sessions.for_task(task_id)
|
||||
}
|
||||
|
||||
pub fn vm_session_for_task_mut(&mut self, task_id: TaskId) -> Option<&mut VmSession> {
|
||||
self.os.vm_sessions.for_task_mut(task_id)
|
||||
}
|
||||
|
||||
pub fn resident_game_session_for_app(&self, app_id: u32) -> Option<&VmSession> {
|
||||
self.os.vm_sessions.resident_game_for_app(app_id)
|
||||
}
|
||||
|
||||
pub fn vm_session_count(&self) -> usize {
|
||||
self.os.vm_sessions.len()
|
||||
}
|
||||
|
||||
pub fn clear_vm_sessions(&mut self) {
|
||||
self.os.vm_sessions.clear();
|
||||
}
|
||||
|
||||
pub fn try_create_vm_session_for_task(&mut self, task_id: TaskId) -> Result<(), SessionError> {
|
||||
let task =
|
||||
self.os.task_manager.get(task_id).ok_or(SessionError::TaskNotFound(task_id))?.clone();
|
||||
let process = self
|
||||
.os
|
||||
.process_manager
|
||||
.get(task.process_id)
|
||||
.ok_or(SessionError::ProcessNotFound(task.process_id))?
|
||||
.clone();
|
||||
|
||||
let cap_config = self.os.vm_runtime.certifier.config;
|
||||
let logs_count = Arc::clone(&self.os.log_service.logs_count);
|
||||
self.os
|
||||
.vm_sessions
|
||||
.create_for_task(&task, &process, "", Some(cap_config), logs_count)
|
||||
.map(|_| ())
|
||||
.map_err(SessionError::from)
|
||||
}
|
||||
|
||||
pub fn try_initialize_session_cartridge(
|
||||
&mut self,
|
||||
task_id: TaskId,
|
||||
cartridge: &Cartridge,
|
||||
) -> Result<(), SessionError> {
|
||||
let session = self
|
||||
.os
|
||||
.vm_sessions
|
||||
.for_task_mut(task_id)
|
||||
.ok_or(SessionError::MissingVmSession(task_id))?;
|
||||
|
||||
session.app_id = cartridge.app_id;
|
||||
session.title = cartridge.title.clone();
|
||||
session.app_version = cartridge.app_version.clone();
|
||||
session.app_mode = cartridge.app_mode;
|
||||
session.clear_cartridge_service_state();
|
||||
session
|
||||
.runtime
|
||||
.initialize_vm(&mut self.os.log_service, &mut session.vm, cartridge)
|
||||
.map_err(SessionError::Initialization)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,14 +1,15 @@
|
||||
use crate::CrashReport;
|
||||
use crate::os::SystemOS;
|
||||
use crate::os::{GameLifecycleEvent, SystemOS};
|
||||
use crate::task::TaskId;
|
||||
use crate::vm_session::VmSession;
|
||||
use crate::{RenderWorkerConfig, RenderWorkerController};
|
||||
use prometeu_bytecode::Value;
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::cartridge::Cartridge;
|
||||
use prometeu_hal::telemetry::{CertificationConfig, TelemetryFrame};
|
||||
use prometeu_hal::{
|
||||
FrameId, InputSignals, RenderWorkerBackend, RenderWorkerError, RenderWorkerFrameSink,
|
||||
RuntimePlatform,
|
||||
FrameId, InputSignals, RenderOwnership, RenderWorkerBackend, RenderWorkerError,
|
||||
RenderWorkerFrameSink, RuntimePlatform,
|
||||
};
|
||||
use prometeu_vm::VirtualMachine;
|
||||
use std::sync::atomic::Ordering;
|
||||
|
||||
pub struct VmFacade<'a> {
|
||||
@@ -16,88 +17,216 @@ pub struct VmFacade<'a> {
|
||||
}
|
||||
|
||||
impl<'a> VmFacade<'a> {
|
||||
pub fn initialize(
|
||||
pub fn tick_session(
|
||||
&mut self,
|
||||
vm: &mut VirtualMachine,
|
||||
cartridge: &Cartridge,
|
||||
) -> Result<(), CrashReport> {
|
||||
self.os.clear_cartridge_service_state();
|
||||
self.os.vm_runtime.initialize_vm(&mut self.os.log_service, vm, cartridge)
|
||||
}
|
||||
|
||||
pub fn tick(
|
||||
&mut self,
|
||||
vm: &mut VirtualMachine,
|
||||
task_id: TaskId,
|
||||
signals: &InputSignals,
|
||||
platform: &mut dyn RuntimePlatform,
|
||||
) -> Option<CrashReport> {
|
||||
self.os.vm_runtime.tick(
|
||||
self.deliver_pending_game_lifecycle_events_to_session(task_id);
|
||||
|
||||
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
|
||||
return Some(CrashReport::VmPanic {
|
||||
message: format!("task {:?} has no VM session", task_id),
|
||||
pc: None,
|
||||
});
|
||||
};
|
||||
|
||||
session.runtime.tick(
|
||||
&mut self.os.log_service,
|
||||
&mut self.os.fs,
|
||||
&mut self.os.fs_state,
|
||||
&mut session.fs_state,
|
||||
&mut self.os.memcard,
|
||||
&mut self.os.open_files,
|
||||
&mut self.os.next_handle,
|
||||
vm,
|
||||
&mut session.open_files,
|
||||
&mut session.next_handle,
|
||||
&mut session.vm,
|
||||
signals,
|
||||
platform,
|
||||
)
|
||||
}
|
||||
|
||||
pub fn reset(&mut self, vm: &mut VirtualMachine) {
|
||||
self.os.vm_runtime.reset(vm);
|
||||
fn deliver_pending_game_lifecycle_events_to_session(&mut self, task_id: TaskId) {
|
||||
let Some(session) = self.os.vm_sessions.for_task(task_id) else {
|
||||
return;
|
||||
};
|
||||
|
||||
if session.runtime.current_cartridge_app_mode != AppMode::Game {
|
||||
return;
|
||||
}
|
||||
|
||||
let mut retained = Vec::new();
|
||||
let mut delivered = Vec::new();
|
||||
|
||||
for event in self.os.game_lifecycle_events.drain(..) {
|
||||
if event.task_id == task_id {
|
||||
delivered.push(event);
|
||||
} else {
|
||||
retained.push(event);
|
||||
}
|
||||
}
|
||||
|
||||
self.os.game_lifecycle_events = retained;
|
||||
if let Some(session) = self.os.vm_sessions.for_task_mut(task_id) {
|
||||
session.runtime.deliver_game_lifecycle_events(delivered);
|
||||
}
|
||||
}
|
||||
|
||||
pub fn debug_step_instruction(
|
||||
pub fn reset_global_runtime_state(&mut self) {
|
||||
self.os.clear_cartridge_service_state();
|
||||
self.os.vm_runtime.clear_cartridge_state();
|
||||
}
|
||||
|
||||
pub fn debug_step_active_session(
|
||||
&mut self,
|
||||
vm: &mut VirtualMachine,
|
||||
platform: &mut dyn RuntimePlatform,
|
||||
) -> Option<CrashReport> {
|
||||
self.os.vm_runtime.debug_step_instruction(&mut self.os.log_service, vm, platform)
|
||||
let Some(task_id) = self.active_session_task_id() else {
|
||||
return Some(CrashReport::VmPanic {
|
||||
message: "debug step requested without an active VM session".to_string(),
|
||||
pc: None,
|
||||
});
|
||||
};
|
||||
let Some(session) = self.os.vm_sessions.for_task_mut(task_id) else {
|
||||
return Some(CrashReport::VmPanic {
|
||||
message: format!("active debug task {:?} has no VM session", task_id),
|
||||
pc: None,
|
||||
});
|
||||
};
|
||||
|
||||
session.runtime.debug_step_instruction(&mut self.os.log_service, &mut session.vm, platform)
|
||||
}
|
||||
|
||||
pub fn active_pc(&self) -> Option<usize> {
|
||||
self.active_session().map(|session| session.vm.pc())
|
||||
}
|
||||
|
||||
pub fn active_operand_stack_top(&self, n: usize) -> Vec<Value> {
|
||||
self.active_session().map(|session| session.vm.operand_stack_top(n)).unwrap_or_default()
|
||||
}
|
||||
|
||||
pub fn insert_active_breakpoint(&mut self, pc: usize) -> bool {
|
||||
if let Some(session) = self.active_session_mut() {
|
||||
session.vm.insert_breakpoint(pc);
|
||||
return true;
|
||||
}
|
||||
|
||||
false
|
||||
}
|
||||
|
||||
pub fn remove_active_breakpoint(&mut self, pc: usize) -> bool {
|
||||
if let Some(session) = self.active_session_mut() {
|
||||
session.vm.remove_breakpoint(pc);
|
||||
return true;
|
||||
}
|
||||
|
||||
false
|
||||
}
|
||||
|
||||
pub fn active_breakpoints_list(&self) -> Vec<usize> {
|
||||
self.active_session().map(|session| session.vm.breakpoints_list()).unwrap_or_default()
|
||||
}
|
||||
|
||||
pub fn paused(&self) -> bool {
|
||||
self.os.vm_runtime.paused
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.paused)
|
||||
.unwrap_or(self.os.vm_runtime.paused)
|
||||
}
|
||||
|
||||
pub fn set_paused(&mut self, paused: bool) {
|
||||
if let Some(session) = self.active_session_mut() {
|
||||
session.runtime.paused = paused;
|
||||
return;
|
||||
}
|
||||
|
||||
self.os.vm_runtime.paused = paused;
|
||||
}
|
||||
|
||||
pub fn set_inspection_active(&mut self, active: bool) {
|
||||
if let Some(session) = self.active_session_mut() {
|
||||
session.runtime.inspection_active = active;
|
||||
return;
|
||||
}
|
||||
|
||||
self.os.vm_runtime.inspection_active = active;
|
||||
}
|
||||
|
||||
pub fn request_debug_step(&mut self) {
|
||||
if let Some(session) = self.active_session_mut() {
|
||||
session.runtime.debug_step_request = true;
|
||||
return;
|
||||
}
|
||||
|
||||
self.os.vm_runtime.debug_step_request = true;
|
||||
}
|
||||
|
||||
pub fn debug_step_requested(&self) -> bool {
|
||||
self.os.vm_runtime.debug_step_request
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.debug_step_request)
|
||||
.unwrap_or(self.os.vm_runtime.debug_step_request)
|
||||
}
|
||||
|
||||
pub fn logical_frame_active(&self) -> bool {
|
||||
self.os.vm_runtime.logical_frame_active
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.logical_frame_active)
|
||||
.unwrap_or(self.os.vm_runtime.logical_frame_active)
|
||||
}
|
||||
|
||||
pub fn delivered_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.delivered_game_lifecycle_events())
|
||||
.unwrap_or_else(|| self.os.vm_runtime.delivered_game_lifecycle_events())
|
||||
}
|
||||
|
||||
pub fn take_delivered_game_lifecycle_events(&mut self) -> Vec<GameLifecycleEvent> {
|
||||
if let Some(session) = self.active_session_mut() {
|
||||
return session.runtime.take_delivered_game_lifecycle_events();
|
||||
}
|
||||
|
||||
self.os.vm_runtime.take_delivered_game_lifecycle_events()
|
||||
}
|
||||
|
||||
pub fn tick_index(&self) -> u64 {
|
||||
self.os.vm_runtime.tick_index
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.tick_index)
|
||||
.unwrap_or(self.os.vm_runtime.tick_index)
|
||||
}
|
||||
|
||||
pub fn logical_frame_index(&self) -> u64 {
|
||||
self.os.vm_runtime.logical_frame_index
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.logical_frame_index)
|
||||
.unwrap_or(self.os.vm_runtime.logical_frame_index)
|
||||
}
|
||||
|
||||
pub fn last_frame_cpu_time_us(&self) -> u64 {
|
||||
self.os.vm_runtime.last_frame_cpu_time_us
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.last_frame_cpu_time_us)
|
||||
.unwrap_or(self.os.vm_runtime.last_frame_cpu_time_us)
|
||||
}
|
||||
|
||||
pub fn completed_logical_frames(&self) -> u64 {
|
||||
self.os.vm_runtime.atomic_telemetry.completed_logical_frames.load(Ordering::Relaxed).into()
|
||||
self.active_session()
|
||||
.map(|session| {
|
||||
session
|
||||
.runtime
|
||||
.atomic_telemetry
|
||||
.completed_logical_frames
|
||||
.load(Ordering::Relaxed)
|
||||
.into()
|
||||
})
|
||||
.unwrap_or_else(|| {
|
||||
self.os
|
||||
.vm_runtime
|
||||
.atomic_telemetry
|
||||
.completed_logical_frames
|
||||
.load(Ordering::Relaxed)
|
||||
.into()
|
||||
})
|
||||
}
|
||||
|
||||
pub fn telemetry_snapshot(&self) -> TelemetryFrame {
|
||||
self.os.vm_runtime.atomic_telemetry.snapshot()
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.atomic_telemetry.snapshot())
|
||||
.unwrap_or_else(|| self.os.vm_runtime.atomic_telemetry.snapshot())
|
||||
}
|
||||
|
||||
pub fn start_render_worker<B, S>(&mut self, config: RenderWorkerConfig, backend: B, sink: S)
|
||||
@@ -120,27 +249,82 @@ impl<'a> VmFacade<'a> {
|
||||
self.os.vm_runtime.record_repeated_render_worker_frame(frame_id);
|
||||
}
|
||||
|
||||
pub fn active_render_ownership(&self) -> RenderOwnership {
|
||||
if let Some(task_id) = self.foreground_session_task_id()
|
||||
&& let Some(session) = self.os.vm_sessions.for_task(task_id)
|
||||
{
|
||||
return session.runtime.render_manager.active_ownership();
|
||||
}
|
||||
|
||||
self.os.vm_runtime.render_manager.active_ownership()
|
||||
}
|
||||
|
||||
pub fn transition_render_owner(&mut self, app_mode: AppMode, app_id: u32) {
|
||||
self.os.vm_runtime.render_manager.transition_render_owner(app_mode, app_id);
|
||||
self.os.vm_runtime.sync_render_worker_ownership();
|
||||
self.os.vm_runtime.render_manager.sync_telemetry(&self.os.vm_runtime.atomic_telemetry);
|
||||
}
|
||||
|
||||
pub fn cert_config(&self) -> &CertificationConfig {
|
||||
&self.os.vm_runtime.certifier.config
|
||||
}
|
||||
|
||||
pub fn last_crash_report(&self) -> Option<&CrashReport> {
|
||||
self.os.vm_runtime.last_crash_report.as_ref()
|
||||
self.active_session()
|
||||
.and_then(|session| session.runtime.last_crash_report.as_ref())
|
||||
.or(self.os.vm_runtime.last_crash_report.as_ref())
|
||||
}
|
||||
|
||||
pub fn current_app_id(&self) -> u32 {
|
||||
self.os.vm_runtime.current_app_id
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.current_app_id)
|
||||
.unwrap_or(self.os.vm_runtime.current_app_id)
|
||||
}
|
||||
|
||||
pub fn current_cartridge_title(&self) -> String {
|
||||
self.os.vm_runtime.current_cartridge_title.clone()
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.current_cartridge_title.clone())
|
||||
.unwrap_or_else(|| self.os.vm_runtime.current_cartridge_title.clone())
|
||||
}
|
||||
|
||||
pub fn current_cartridge_app_version(&self) -> String {
|
||||
self.os.vm_runtime.current_cartridge_app_version.clone()
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.current_cartridge_app_version.clone())
|
||||
.unwrap_or_else(|| self.os.vm_runtime.current_cartridge_app_version.clone())
|
||||
}
|
||||
|
||||
pub fn current_cartridge_app_mode(&self) -> AppMode {
|
||||
self.os.vm_runtime.current_cartridge_app_mode
|
||||
self.active_session()
|
||||
.map(|session| session.runtime.current_cartridge_app_mode)
|
||||
.unwrap_or(self.os.vm_runtime.current_cartridge_app_mode)
|
||||
}
|
||||
|
||||
fn active_session(&self) -> Option<&VmSession> {
|
||||
self.os
|
||||
.task_manager
|
||||
.foreground_task()
|
||||
.and_then(|task_id| self.os.vm_sessions.for_task(task_id))
|
||||
.or_else(|| {
|
||||
self.os
|
||||
.foreground_stack
|
||||
.resident_game_task()
|
||||
.and_then(|task_id| self.os.vm_sessions.for_task(task_id))
|
||||
})
|
||||
}
|
||||
|
||||
fn active_session_mut(&mut self) -> Option<&mut VmSession> {
|
||||
let task_id = self.active_session_task_id()?;
|
||||
self.os.vm_sessions.for_task_mut(task_id)
|
||||
}
|
||||
|
||||
fn active_session_task_id(&self) -> Option<TaskId> {
|
||||
self.os
|
||||
.task_manager
|
||||
.foreground_task()
|
||||
.or_else(|| self.os.foreground_stack.resident_game_task())
|
||||
}
|
||||
|
||||
fn foreground_session_task_id(&self) -> Option<TaskId> {
|
||||
self.os.task_manager.foreground_task()
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,20 @@
|
||||
use crate::process::ProcessId;
|
||||
use crate::task::{TaskId, TaskState};
|
||||
|
||||
pub const DEFAULT_GAME_PAUSE_BUDGET_TICKS: u8 = 1;
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum GameLifecycleEventKind {
|
||||
Pause,
|
||||
ResumeForeground,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct GameLifecycleEvent {
|
||||
pub task_id: TaskId,
|
||||
pub kind: GameLifecycleEventKind,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum LifecycleOperation {
|
||||
SetForeground,
|
||||
@@ -15,4 +29,7 @@ pub enum LifecycleError {
|
||||
TaskNotFound(TaskId),
|
||||
ProcessNotFound(ProcessId),
|
||||
InvalidTransition { task_id: TaskId, from: TaskState, operation: LifecycleOperation },
|
||||
ResidentGameAlreadyExists { existing: TaskId, requested: TaskId },
|
||||
ForegroundShellAlreadyExists { existing: TaskId, requested: TaskId },
|
||||
TaskIsNotResidentGame(TaskId),
|
||||
}
|
||||
|
||||
@@ -2,6 +2,11 @@ mod facades;
|
||||
mod lifecycle;
|
||||
mod system_os;
|
||||
|
||||
pub use facades::{FsFacade, LifecycleFacade, SessionsFacade, VmFacade, WindowFacade};
|
||||
pub use lifecycle::{LifecycleError, LifecycleOperation};
|
||||
pub use facades::{
|
||||
FsFacade, LifecycleFacade, SessionError, SessionsFacade, VmFacade, WindowFacade,
|
||||
};
|
||||
pub use lifecycle::{
|
||||
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
|
||||
LifecycleOperation,
|
||||
};
|
||||
pub use system_os::SystemOS;
|
||||
|
||||
@@ -1,8 +1,12 @@
|
||||
use crate::VirtualMachineRuntime;
|
||||
use crate::fs::{FsState, VirtualFS};
|
||||
use crate::os::{FsFacade, LifecycleFacade, SessionsFacade, VmFacade, WindowFacade};
|
||||
use crate::os::{
|
||||
FsFacade, GameLifecycleEvent, LifecycleFacade, SessionsFacade, VmFacade, WindowFacade,
|
||||
};
|
||||
use crate::process::ProcessManager;
|
||||
use crate::services::foreground::ForegroundStack;
|
||||
use crate::services::memcard::MemcardService;
|
||||
use crate::services::vm_session::VmSessionRegistry;
|
||||
use crate::services::windows::WindowManager;
|
||||
use crate::task::TaskManager;
|
||||
use prometeu_hal::log::{LogEvent, LogLevel, LogService, LogSource};
|
||||
@@ -14,6 +18,9 @@ pub struct SystemOS {
|
||||
pub(super) vm_runtime: VirtualMachineRuntime,
|
||||
pub(super) process_manager: ProcessManager,
|
||||
pub(super) task_manager: TaskManager,
|
||||
pub(super) foreground_stack: ForegroundStack,
|
||||
pub(super) vm_sessions: VmSessionRegistry,
|
||||
pub(super) game_lifecycle_events: Vec<GameLifecycleEvent>,
|
||||
pub(super) window_manager: WindowManager,
|
||||
pub(super) log_service: LogService,
|
||||
pub(super) fs: VirtualFS,
|
||||
@@ -33,6 +40,9 @@ impl SystemOS {
|
||||
),
|
||||
process_manager: ProcessManager::new(),
|
||||
task_manager: TaskManager::new(),
|
||||
foreground_stack: ForegroundStack::new(),
|
||||
vm_sessions: VmSessionRegistry::new(),
|
||||
game_lifecycle_events: Vec::new(),
|
||||
window_manager: WindowManager::new(),
|
||||
log_service,
|
||||
fs: VirtualFS::new(),
|
||||
@@ -133,15 +143,33 @@ impl SystemOS {
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::os::{LifecycleError, LifecycleOperation};
|
||||
use crate::process::ProcessState;
|
||||
use crate::os::{GameLifecycleEventKind, LifecycleError, LifecycleOperation, SessionError};
|
||||
use crate::process::{ProcessId, ProcessKind, ProcessState};
|
||||
use crate::services::foreground::{ForegroundOwner, ResidentGame, ResidentGameState};
|
||||
use crate::task::{TaskId, TaskState};
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::cartridge::{AssetsPayloadSource, Cartridge};
|
||||
use prometeu_hal::syscalls::caps;
|
||||
|
||||
fn process_state_for_task(os: &SystemOS, task_id: TaskId) -> ProcessState {
|
||||
let task = os.task_manager.get(task_id).expect("task should exist");
|
||||
os.process_manager.get(task.process_id).expect("process should exist").state
|
||||
}
|
||||
|
||||
fn session_test_cartridge(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
|
||||
Cartridge {
|
||||
app_id,
|
||||
title: title.to_string(),
|
||||
app_version: "1.0.0".to_string(),
|
||||
app_mode,
|
||||
capabilities: caps::NONE,
|
||||
program: vec![],
|
||||
assets: AssetsPayloadSource::empty(),
|
||||
asset_table: vec![],
|
||||
preload: vec![],
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn set_foreground_task_marks_task_and_process_running() {
|
||||
let mut os = SystemOS::new(None);
|
||||
@@ -157,6 +185,394 @@ mod tests {
|
||||
assert_eq!(process_state_for_task(&os, task_id), ProcessState::Running);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn foreground_stack_starts_at_hub() {
|
||||
let os = SystemOS::new(None);
|
||||
|
||||
assert_eq!(os.foreground_stack.owner(), ForegroundOwner::Hub);
|
||||
assert_eq!(os.foreground_stack.resident_game(), None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn game_session_registers_single_resident_game() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let task_id = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
|
||||
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Game(task_id));
|
||||
assert_eq!(
|
||||
os.lifecycle().resident_game(),
|
||||
Some(ResidentGame { task_id, state: ResidentGameState::Foreground })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn second_resident_game_is_rejected() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let first = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
let process_id = os.process_manager.spawn_vm_game(43, "Second");
|
||||
let second = os.task_manager.create_game_task(process_id, 43, "Second");
|
||||
|
||||
assert_eq!(
|
||||
os.lifecycle().set_game_foreground_task(second),
|
||||
Err(LifecycleError::ResidentGameAlreadyExists { existing: first, requested: second })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn terminate_resident_game_closes_task_and_removes_vm_session() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
|
||||
os.lifecycle().request_home_from_game(game).expect("home request should succeed");
|
||||
assert_eq!(os.lifecycle().pending_game_lifecycle_events().len(), 1);
|
||||
|
||||
assert_eq!(os.lifecycle().terminate_resident_game(), Ok(Some(game)));
|
||||
|
||||
assert_eq!(os.lifecycle().resident_game(), None);
|
||||
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
|
||||
assert_eq!(os.lifecycle().task_state(game), Some(TaskState::Closed));
|
||||
assert_eq!(process_state_for_task(&os, game), ProcessState::Stopped);
|
||||
assert_eq!(os.sessions().vm_session_for_task(game).map(|session| session.task_id), None);
|
||||
assert!(os.lifecycle().pending_game_lifecycle_events().is_empty());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn terminate_resident_game_preserves_foreground_shell() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
os.lifecycle().request_home_from_game(game).expect("home request should succeed");
|
||||
os.lifecycle().advance_game_pause_budget(game).expect("budget should expire");
|
||||
let shell = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
|
||||
assert_eq!(os.lifecycle().terminate_resident_game(), Ok(Some(game)));
|
||||
|
||||
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
|
||||
assert_eq!(os.lifecycle().resident_game(), None);
|
||||
assert_eq!(os.lifecycle().task_state(game), Some(TaskState::Closed));
|
||||
assert_eq!(process_state_for_task(&os, game), ProcessState::Stopped);
|
||||
assert_eq!(os.sessions().vm_session_for_task(game).map(|session| session.task_id), None);
|
||||
assert_eq!(os.lifecycle().task_state(shell), Some(TaskState::Foreground));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn vm_game_task_creates_vm_session() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let task_id = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
|
||||
let sessions = os.sessions();
|
||||
let session = sessions.vm_session_for_task(task_id).expect("VM session should exist");
|
||||
|
||||
assert_eq!(session.task_id, task_id);
|
||||
assert_eq!(session.app_id, 42);
|
||||
assert_eq!(session.title, "Sector Crawl");
|
||||
assert_eq!(session.app_mode, AppMode::Game);
|
||||
assert_eq!(sessions.vm_session_count(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn vm_shell_task_creates_vm_session() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let task_id = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
|
||||
let sessions = os.sessions();
|
||||
let session = sessions.vm_session_for_task(task_id).expect("VM session should exist");
|
||||
|
||||
assert_eq!(session.task_id, task_id);
|
||||
assert_eq!(session.app_id, 7);
|
||||
assert_eq!(session.title, "Settings");
|
||||
assert_eq!(session.app_mode, AppMode::Shell);
|
||||
assert_eq!(sessions.vm_session_count(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn native_shell_task_does_not_create_vm_session() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let task_id = os.sessions().create_native_shell_task(7, "Settings");
|
||||
|
||||
let sessions = os.sessions();
|
||||
|
||||
assert!(sessions.vm_session_for_task(task_id).is_none());
|
||||
assert_eq!(sessions.vm_session_count(), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn same_resident_game_app_reuses_existing_vm_session() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let first = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
let second = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
|
||||
let sessions = os.sessions();
|
||||
|
||||
assert_eq!(second, first);
|
||||
assert_eq!(
|
||||
sessions.resident_game_session_for_app(42).map(|session| session.task_id),
|
||||
Some(first)
|
||||
);
|
||||
assert_eq!(sessions.vm_session_count(), 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn vm_sessions_hold_independent_runtime_state() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
os.lifecycle().request_home_from_game(game).expect("home request should succeed");
|
||||
os.lifecycle().advance_game_pause_budget(game).expect("budget should expire");
|
||||
let shell = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
|
||||
{
|
||||
let mut sessions = os.sessions();
|
||||
let game_session =
|
||||
sessions.vm_session_for_task_mut(game).expect("game VM session should exist");
|
||||
game_session.runtime.tick_index = 100;
|
||||
game_session.open_files.insert(1, "/game.dat".to_string());
|
||||
}
|
||||
|
||||
{
|
||||
let mut sessions = os.sessions();
|
||||
let shell_session =
|
||||
sessions.vm_session_for_task_mut(shell).expect("shell VM session should exist");
|
||||
shell_session.runtime.tick_index = 5;
|
||||
shell_session.open_files.insert(1, "/shell.dat".to_string());
|
||||
}
|
||||
|
||||
let sessions = os.sessions();
|
||||
let game_session =
|
||||
sessions.vm_session_for_task(game).expect("game VM session should exist");
|
||||
let shell_session =
|
||||
sessions.vm_session_for_task(shell).expect("shell VM session should exist");
|
||||
|
||||
assert_eq!(game_session.runtime.tick_index, 100);
|
||||
assert_eq!(shell_session.runtime.tick_index, 5);
|
||||
assert_eq!(game_session.open_files.get(&1).map(String::as_str), Some("/game.dat"));
|
||||
assert_eq!(shell_session.open_files.get(&1).map(String::as_str), Some("/shell.dat"));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn vm_debug_operations_target_foreground_shell_before_resident_game() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
os.lifecycle().request_home_from_game(game).expect("home request should succeed");
|
||||
os.lifecycle().advance_game_pause_budget(game).expect("budget should expire");
|
||||
let shell = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
|
||||
{
|
||||
let mut sessions = os.sessions();
|
||||
let game_session =
|
||||
sessions.vm_session_for_task_mut(game).expect("game VM session should exist");
|
||||
game_session.vm.insert_breakpoint(10);
|
||||
}
|
||||
|
||||
assert!(os.vm().insert_active_breakpoint(20));
|
||||
assert_eq!(os.vm().active_breakpoints_list(), vec![20]);
|
||||
|
||||
let sessions = os.sessions();
|
||||
assert_eq!(
|
||||
sessions
|
||||
.vm_session_for_task(game)
|
||||
.expect("game VM session should exist")
|
||||
.vm
|
||||
.breakpoints_list(),
|
||||
vec![10]
|
||||
);
|
||||
assert_eq!(
|
||||
sessions
|
||||
.vm_session_for_task(shell)
|
||||
.expect("shell VM session should exist")
|
||||
.vm
|
||||
.breakpoints_list(),
|
||||
vec![20]
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn home_request_notifies_game_before_budget_suspends_it() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let task_id = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
|
||||
os.lifecycle().request_home_from_game(task_id).expect("home request should succeed");
|
||||
|
||||
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Game(task_id));
|
||||
assert_eq!(
|
||||
os.lifecycle().resident_game(),
|
||||
Some(ResidentGame {
|
||||
task_id,
|
||||
state: ResidentGameState::PauseRequested { remaining_ticks: 1 },
|
||||
})
|
||||
);
|
||||
assert_eq!(
|
||||
os.lifecycle().pending_game_lifecycle_events()[0].kind,
|
||||
GameLifecycleEventKind::Pause
|
||||
);
|
||||
assert_eq!(
|
||||
os.task_manager.get(task_id).expect("task should exist").state,
|
||||
TaskState::Foreground
|
||||
);
|
||||
|
||||
assert!(os.lifecycle().advance_game_pause_budget(task_id).expect("budget should advance"));
|
||||
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
|
||||
assert_eq!(
|
||||
os.lifecycle().resident_game(),
|
||||
Some(ResidentGame { task_id, state: ResidentGameState::PausedSuspended })
|
||||
);
|
||||
assert_eq!(
|
||||
os.task_manager.get(task_id).expect("task should exist").state,
|
||||
TaskState::Suspended
|
||||
);
|
||||
assert_eq!(process_state_for_task(&os, task_id), ProcessState::Suspended);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn shell_foreground_keeps_game_resident_and_marks_it_suspended() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
os.lifecycle().request_home_from_game(game).expect("home request should succeed");
|
||||
os.lifecycle().advance_game_pause_budget(game).expect("budget should expire");
|
||||
let shell = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
|
||||
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
|
||||
assert_eq!(
|
||||
os.lifecycle().resident_game(),
|
||||
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn vm_shell_foreground_suspends_foreground_resident_game() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
|
||||
let shell = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
|
||||
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
|
||||
assert_eq!(
|
||||
os.lifecycle().resident_game(),
|
||||
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
|
||||
);
|
||||
assert_eq!(
|
||||
os.task_manager.get(game).expect("game should exist").state,
|
||||
TaskState::Suspended
|
||||
);
|
||||
assert_eq!(process_state_for_task(&os, game), ProcessState::Suspended);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn native_shell_foreground_suspends_foreground_resident_game() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let game = os.sessions().create_vm_game_task(42, "Sector Crawl");
|
||||
|
||||
let shell = os.sessions().create_native_shell_task(7, "Settings");
|
||||
|
||||
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Shell(shell));
|
||||
assert_eq!(
|
||||
os.lifecycle().resident_game(),
|
||||
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
|
||||
);
|
||||
assert_eq!(
|
||||
os.task_manager.get(game).expect("game should exist").state,
|
||||
TaskState::Suspended
|
||||
);
|
||||
assert_eq!(process_state_for_task(&os, game), ProcessState::Suspended);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lifecycle_exposes_process_kind_for_shell_tasks() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let vm_shell = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
os.lifecycle().close_task(vm_shell).expect("vm shell should close");
|
||||
|
||||
let native_shell = os.sessions().create_native_shell_task(8, "Files");
|
||||
|
||||
assert_eq!(os.lifecycle().process_kind_for_task(vm_shell), Ok(ProcessKind::VmShell));
|
||||
assert_eq!(
|
||||
os.lifecycle().process_kind_for_task(native_shell),
|
||||
Ok(ProcessKind::NativeShell)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn second_foreground_shell_is_rejected() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let first = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
let process_id = os.process_manager.spawn_vm_shell(8, "Files");
|
||||
let second = os.task_manager.create_shell_task(process_id, 8, "Files");
|
||||
|
||||
assert_eq!(
|
||||
os.lifecycle().set_shell_foreground_task(second),
|
||||
Err(LifecycleError::ForegroundShellAlreadyExists {
|
||||
existing: first,
|
||||
requested: second,
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn vm_shell_load_returns_typed_error_when_foreground_shell_exists() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let first = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
let cartridge = session_test_cartridge(AppMode::Shell, 8, "Files");
|
||||
|
||||
let error = os.sessions().load_vm_cartridge(&cartridge).expect_err("load should fail");
|
||||
|
||||
match error {
|
||||
SessionError::Lifecycle(LifecycleError::ForegroundShellAlreadyExists {
|
||||
existing,
|
||||
requested,
|
||||
}) => {
|
||||
assert_eq!(existing, first);
|
||||
assert_ne!(requested, first);
|
||||
}
|
||||
other => panic!("expected foreground shell lifecycle error, got {:?}", other),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn vm_session_creation_returns_typed_error_for_missing_task() {
|
||||
let mut os = SystemOS::new(None);
|
||||
|
||||
assert_eq!(
|
||||
os.sessions().try_create_vm_session_for_task(TaskId(999)),
|
||||
Err(SessionError::TaskNotFound(TaskId(999)))
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn vm_session_creation_returns_typed_error_for_missing_process() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let task_id = os.task_manager.create_game_task(ProcessId(999), 42, "Broken");
|
||||
|
||||
assert_eq!(
|
||||
os.sessions().try_create_vm_session_for_task(task_id),
|
||||
Err(SessionError::ProcessNotFound(ProcessId(999)))
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn session_cartridge_initialization_returns_typed_error_for_missing_session() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let process_id = os.process_manager.spawn_vm_game(42, "Sector Crawl");
|
||||
let task_id = os.task_manager.create_game_task(process_id, 42, "Sector Crawl");
|
||||
let cartridge = session_test_cartridge(AppMode::Game, 42, "Sector Crawl");
|
||||
|
||||
assert_eq!(
|
||||
os.sessions().try_initialize_session_cartridge(task_id, &cartridge),
|
||||
Err(SessionError::MissingVmSession(task_id))
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn closing_foreground_shell_returns_to_hub() {
|
||||
let mut os = SystemOS::new(None);
|
||||
let shell = os.sessions().create_vm_shell_task(7, "Settings");
|
||||
|
||||
os.lifecycle().close_task(shell).expect("close should succeed");
|
||||
|
||||
assert_eq!(os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
|
||||
assert_eq!(
|
||||
os.task_manager.get(shell).expect("shell should remain").state,
|
||||
TaskState::Closed
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn suspend_task_marks_task_and_process_suspended() {
|
||||
let mut os = SystemOS::new(None);
|
||||
@@ -184,6 +600,10 @@ mod tests {
|
||||
TaskState::Foreground
|
||||
);
|
||||
assert_eq!(process_state_for_task(&os, task_id), ProcessState::Running);
|
||||
assert_eq!(
|
||||
os.lifecycle().pending_game_lifecycle_events().last().map(|event| event.kind),
|
||||
Some(GameLifecycleEventKind::ResumeForeground)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
||||
@@ -1,3 +1,6 @@
|
||||
mod prometeu_hub;
|
||||
|
||||
pub use prometeu_hub::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
|
||||
pub use prometeu_hub::{
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
|
||||
SystemProfileUpdate,
|
||||
};
|
||||
|
||||
@@ -1,4 +1,7 @@
|
||||
#[allow(clippy::module_inception)]
|
||||
mod prometeu_hub;
|
||||
|
||||
pub use prometeu_hub::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
|
||||
pub use prometeu_hub::{
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
|
||||
SystemProfileUpdate,
|
||||
};
|
||||
|
||||
@@ -1,18 +1,26 @@
|
||||
use crate::{CrashReport, SystemOS};
|
||||
use crate::task::TaskId;
|
||||
use crate::{CrashReport, GameLibrary, GameSwitchTarget, SystemOS};
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::color::Color;
|
||||
use prometeu_hal::primitives::Rect;
|
||||
use prometeu_hal::{
|
||||
FrameId, GfxUiCommand, InputPlatform, InputSignals, RenderSubmission, RuntimePlatform,
|
||||
ShellUiFramePacket,
|
||||
};
|
||||
use prometeu_vm::VirtualMachine;
|
||||
|
||||
const SHELL_A_BUTTON: Rect = Rect { x: 112, y: 108, w: 112, h: 48 };
|
||||
const SHELL_B_BUTTON: Rect = Rect { x: 256, y: 108, w: 112, h: 48 };
|
||||
const SHELL_A_BUTTON: Rect = Rect { x: 112, y: 172, w: 112, h: 32 };
|
||||
const SHELL_B_BUTTON: Rect = Rect { x: 256, y: 172, w: 112, h: 32 };
|
||||
const CLOSE_BUTTON: Rect = Rect { x: 420, y: 24, w: 16, h: 16 };
|
||||
const VIEWPORT: Rect = Rect { x: 0, y: 0, w: 480, h: 270 };
|
||||
const HOME_PANEL: Rect = Rect { x: 48, y: 58, w: 384, h: 154 };
|
||||
const TITLE_PANEL: Rect = Rect { x: 72, y: 34, w: 336, h: 28 };
|
||||
const GAME_ROW_X: i32 = 72;
|
||||
const GAME_ROW_Y: i32 = 90;
|
||||
const GAME_ROW_W: i32 = 336;
|
||||
const GAME_ROW_H: i32 = 22;
|
||||
const GAME_ROW_GAP: i32 = 6;
|
||||
const MAX_HOME_GAME_ROWS: usize = 3;
|
||||
pub const HUB_SUSPENDED_GAME_KILL_CONTROL: Rect = Rect { x: 288, y: 230, w: 168, h: 24 };
|
||||
#[cfg(test)]
|
||||
const SHELL_FRAME: Rect = Rect { x: 40, y: 20, w: 400, h: 220 };
|
||||
|
||||
@@ -25,10 +33,13 @@ const COLOR_TEXT: Color = Color::rgb(230, 236, 224);
|
||||
const COLOR_MUTED: Color = Color::rgb(91, 112, 128);
|
||||
const COLOR_BUTTON: Color = Color::rgb(45, 59, 82);
|
||||
const COLOR_BUTTON_ACTIVE: Color = Color::rgb(72, 91, 122);
|
||||
const COLOR_KILL: Color = Color::rgb(164, 32, 40);
|
||||
const COLOR_KILL_ACTIVE: Color = Color::rgb(206, 46, 54);
|
||||
|
||||
/// PrometeuHub: Launcher and system UI environment.
|
||||
pub struct PrometeuHub {
|
||||
home_input_armed: bool,
|
||||
game_library: GameLibrary,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
@@ -72,9 +83,11 @@ impl NativeShellApp {
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum SystemProfileAction {
|
||||
LaunchNativeShell(NativeShellApp),
|
||||
LaunchGame { target: GameSwitchTarget },
|
||||
KillResidentGame,
|
||||
CloseShell,
|
||||
}
|
||||
|
||||
@@ -91,13 +104,21 @@ impl Default for PrometeuHub {
|
||||
|
||||
impl PrometeuHub {
|
||||
pub fn new() -> Self {
|
||||
Self { home_input_armed: false }
|
||||
Self { home_input_armed: false, game_library: GameLibrary::empty() }
|
||||
}
|
||||
|
||||
pub fn init(&mut self) {
|
||||
self.home_input_armed = false;
|
||||
}
|
||||
|
||||
pub fn set_game_library(&mut self, game_library: GameLibrary) {
|
||||
self.game_library = game_library;
|
||||
}
|
||||
|
||||
pub fn game_library(&self) -> &GameLibrary {
|
||||
&self.game_library
|
||||
}
|
||||
|
||||
pub fn gui_update(
|
||||
&mut self,
|
||||
os: &mut SystemOS,
|
||||
@@ -115,11 +136,14 @@ impl PrometeuHub {
|
||||
}
|
||||
|
||||
let input = platform.input();
|
||||
let suspended_game = if in_shell { None } else { resident_game_indicator(os) };
|
||||
if let Some(action) = action_for_click(
|
||||
in_shell,
|
||||
input.touch().x(),
|
||||
input.touch().y(),
|
||||
input.touch().f().pressed,
|
||||
self.game_library.entries(),
|
||||
suspended_game.as_ref(),
|
||||
) {
|
||||
return Some(action);
|
||||
}
|
||||
@@ -132,7 +156,13 @@ impl PrometeuHub {
|
||||
let pointer_y = platform.input().touch().y();
|
||||
|
||||
let packet = if os.windows().window_count() == 0 {
|
||||
render_home_packet(pointer_x, pointer_y)
|
||||
let suspended_game = resident_game_indicator(os);
|
||||
render_home_packet(
|
||||
pointer_x,
|
||||
pointer_y,
|
||||
self.game_library.entries(),
|
||||
suspended_game.as_ref(),
|
||||
)
|
||||
} else {
|
||||
let mut commands = Vec::new();
|
||||
for window in os.windows().windows() {
|
||||
@@ -156,7 +186,23 @@ impl PrometeuHub {
|
||||
pub fn update_shell_profile(
|
||||
&mut self,
|
||||
os: &mut SystemOS,
|
||||
vm: &mut VirtualMachine,
|
||||
platform: &mut dyn RuntimePlatform,
|
||||
) -> SystemProfileUpdate {
|
||||
let mut action = self.gui_update(os, platform);
|
||||
|
||||
if os.windows().focused_window().is_some() && platform.input().pad().start().down {
|
||||
action = Some(SystemProfileAction::CloseShell);
|
||||
}
|
||||
|
||||
self.render(os, platform);
|
||||
|
||||
SystemProfileUpdate { crash: None, action }
|
||||
}
|
||||
|
||||
pub fn update_vm_shell_profile(
|
||||
&mut self,
|
||||
os: &mut SystemOS,
|
||||
task_id: TaskId,
|
||||
signals: &InputSignals,
|
||||
platform: &mut dyn RuntimePlatform,
|
||||
) -> SystemProfileUpdate {
|
||||
@@ -167,7 +213,7 @@ impl PrometeuHub {
|
||||
if platform.input().pad().start().down {
|
||||
action = Some(SystemProfileAction::CloseShell);
|
||||
} else if action != Some(SystemProfileAction::CloseShell) {
|
||||
crash = os.vm().tick(vm, signals, platform);
|
||||
crash = os.vm().tick_session(task_id, signals, platform);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -175,9 +221,32 @@ impl PrometeuHub {
|
||||
|
||||
SystemProfileUpdate { crash, action }
|
||||
}
|
||||
|
||||
pub fn update_native_shell_profile(
|
||||
&mut self,
|
||||
os: &mut SystemOS,
|
||||
platform: &mut dyn RuntimePlatform,
|
||||
) -> SystemProfileUpdate {
|
||||
let mut action = self.gui_update(os, platform);
|
||||
|
||||
if os.windows().focused_window().is_some() && platform.input().pad().start().down {
|
||||
action = Some(SystemProfileAction::CloseShell);
|
||||
}
|
||||
|
||||
self.render(os, platform);
|
||||
|
||||
SystemProfileUpdate { crash: None, action }
|
||||
}
|
||||
}
|
||||
|
||||
fn action_for_click(in_shell: bool, x: i32, y: i32, pressed: bool) -> Option<SystemProfileAction> {
|
||||
fn action_for_click(
|
||||
in_shell: bool,
|
||||
x: i32,
|
||||
y: i32,
|
||||
pressed: bool,
|
||||
game_entries: &[crate::GameLibraryEntry],
|
||||
suspended_game: Option<&SuspendedGameIndicator>,
|
||||
) -> Option<SystemProfileAction> {
|
||||
if !pressed {
|
||||
return None;
|
||||
}
|
||||
@@ -186,12 +255,52 @@ fn action_for_click(in_shell: bool, x: i32, y: i32, pressed: bool) -> Option<Sys
|
||||
return rect_contains(CLOSE_BUTTON, x, y).then_some(SystemProfileAction::CloseShell);
|
||||
}
|
||||
|
||||
if suspended_game.is_some() && rect_contains(HUB_SUSPENDED_GAME_KILL_CONTROL, x, y) {
|
||||
return Some(SystemProfileAction::KillResidentGame);
|
||||
}
|
||||
|
||||
if let Some(entry) = game_entries
|
||||
.iter()
|
||||
.take(MAX_HOME_GAME_ROWS)
|
||||
.enumerate()
|
||||
.find(|(index, _entry)| rect_contains(game_row_rect(*index), x, y))
|
||||
.map(|(_index, entry)| entry)
|
||||
{
|
||||
return Some(SystemProfileAction::LaunchGame { target: entry.switch_target() });
|
||||
}
|
||||
|
||||
HOME_BUTTONS
|
||||
.iter()
|
||||
.find(|button| rect_contains(button.rect, x, y))
|
||||
.map(|button| SystemProfileAction::LaunchNativeShell(button.app))
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
struct SuspendedGameIndicator {
|
||||
title: String,
|
||||
}
|
||||
|
||||
fn resident_game_indicator(os: &mut SystemOS) -> Option<SuspendedGameIndicator> {
|
||||
let task_id = os.lifecycle().resident_game_task()?;
|
||||
let sessions = os.sessions();
|
||||
let session = sessions.vm_session_for_task(task_id)?;
|
||||
|
||||
if session.app_mode != AppMode::Game {
|
||||
return None;
|
||||
}
|
||||
|
||||
Some(SuspendedGameIndicator { title: session.title.clone() })
|
||||
}
|
||||
|
||||
fn game_row_rect(index: usize) -> Rect {
|
||||
Rect {
|
||||
x: GAME_ROW_X,
|
||||
y: GAME_ROW_Y + (GAME_ROW_H + GAME_ROW_GAP) * index as i32,
|
||||
w: GAME_ROW_W,
|
||||
h: GAME_ROW_H,
|
||||
}
|
||||
}
|
||||
|
||||
fn rect_contains(rect: Rect, x: i32, y: i32) -> bool {
|
||||
x >= rect.x && x < rect.x + rect.w && y >= rect.y && y < rect.y + rect.h
|
||||
}
|
||||
@@ -203,7 +312,12 @@ fn activation_input_down(input: &dyn InputPlatform) -> bool {
|
||||
|| input.pad().start().down
|
||||
}
|
||||
|
||||
fn render_home_packet(pointer_x: i32, pointer_y: i32) -> ShellUiFramePacket {
|
||||
fn render_home_packet(
|
||||
pointer_x: i32,
|
||||
pointer_y: i32,
|
||||
game_entries: &[crate::GameLibraryEntry],
|
||||
suspended_game: Option<&SuspendedGameIndicator>,
|
||||
) -> ShellUiFramePacket {
|
||||
let mut commands = Vec::new();
|
||||
commands.push(GfxUiCommand::Clear { color: COLOR_BG });
|
||||
fill_rect(&mut commands, VIEWPORT, COLOR_BG);
|
||||
@@ -217,26 +331,36 @@ fn render_home_packet(pointer_x: i32, pointer_y: i32) -> ShellUiFramePacket {
|
||||
);
|
||||
|
||||
draw_panel(&mut commands, HOME_PANEL, COLOR_PANEL, COLOR_BORDER);
|
||||
draw_buffer_text(
|
||||
&mut commands,
|
||||
HOME_PANEL.x + 26,
|
||||
HOME_PANEL.y + 22,
|
||||
"Native Shell Apps",
|
||||
COLOR_TEXT,
|
||||
);
|
||||
draw_buffer_text(&mut commands, HOME_PANEL.x + 26, HOME_PANEL.y + 22, "Games", COLOR_TEXT);
|
||||
draw_buffer_text(
|
||||
&mut commands,
|
||||
HOME_PANEL.x + 26,
|
||||
HOME_PANEL.y + 40,
|
||||
"first retro ui slice",
|
||||
"local library",
|
||||
COLOR_MUTED,
|
||||
);
|
||||
|
||||
if game_entries.is_empty() {
|
||||
draw_buffer_text(&mut commands, GAME_ROW_X, GAME_ROW_Y + 6, "No games found", COLOR_MUTED);
|
||||
} else {
|
||||
for (index, entry) in game_entries.iter().take(MAX_HOME_GAME_ROWS).enumerate() {
|
||||
let rect = game_row_rect(index);
|
||||
let hovered = rect_contains(rect, pointer_x, pointer_y);
|
||||
let text = format!("{} #{} {}", entry.title, entry.app_id, entry.app_version);
|
||||
draw_game_row(&mut commands, rect, &text, hovered);
|
||||
}
|
||||
}
|
||||
|
||||
for button in HOME_BUTTONS {
|
||||
let hovered = rect_contains(button.rect, pointer_x, pointer_y);
|
||||
draw_button(&mut commands, button.rect, button.label, hovered);
|
||||
}
|
||||
|
||||
if let Some(suspended_game) = suspended_game {
|
||||
let hovered = rect_contains(HUB_SUSPENDED_GAME_KILL_CONTROL, pointer_x, pointer_y);
|
||||
draw_suspended_game_kill_control(&mut commands, suspended_game, hovered);
|
||||
}
|
||||
|
||||
ShellUiFramePacket::new(commands)
|
||||
}
|
||||
|
||||
@@ -326,9 +450,50 @@ fn draw_button(commands: &mut Vec<GfxUiCommand>, rect: Rect, label: &str, hovere
|
||||
Rect { x: rect.x + 3, y: rect.y + 3, w: rect.w - 6, h: rect.h - 6 },
|
||||
COLOR_MUTED,
|
||||
);
|
||||
fill_rect(commands, Rect { x: rect.x + 12, y: rect.y + 12, w: 16, h: 24 }, border);
|
||||
draw_rect(commands, Rect { x: rect.x + 34, y: rect.y + 12, w: 62, h: 24 }, COLOR_PANEL_DARK);
|
||||
draw_buffer_text(commands, rect.x + 40, rect.y + 21, label, COLOR_TEXT);
|
||||
fill_rect(commands, Rect { x: rect.x + 12, y: rect.y + 8, w: 14, h: 16 }, border);
|
||||
draw_rect(commands, Rect { x: rect.x + 34, y: rect.y + 8, w: 62, h: 16 }, COLOR_PANEL_DARK);
|
||||
draw_buffer_text(commands, rect.x + 40, rect.y + 13, label, COLOR_TEXT);
|
||||
}
|
||||
|
||||
fn draw_game_row(commands: &mut Vec<GfxUiCommand>, rect: Rect, label: &str, hovered: bool) {
|
||||
let fill = if hovered { COLOR_BUTTON_ACTIVE } else { COLOR_PANEL_DARK };
|
||||
let border = if hovered { COLOR_HILITE } else { COLOR_MUTED };
|
||||
fill_rect(commands, rect, fill);
|
||||
draw_rect(commands, rect, border);
|
||||
draw_buffer_text(commands, rect.x + 8, rect.y + 7, label, COLOR_TEXT);
|
||||
}
|
||||
|
||||
fn draw_suspended_game_kill_control(
|
||||
commands: &mut Vec<GfxUiCommand>,
|
||||
suspended_game: &SuspendedGameIndicator,
|
||||
hovered: bool,
|
||||
) {
|
||||
let fill = if hovered { COLOR_KILL_ACTIVE } else { COLOR_KILL };
|
||||
let border = if hovered { COLOR_HILITE } else { COLOR_BORDER };
|
||||
fill_rect(commands, HUB_SUSPENDED_GAME_KILL_CONTROL, fill);
|
||||
draw_rect(commands, HUB_SUSPENDED_GAME_KILL_CONTROL, border);
|
||||
draw_buffer_text(
|
||||
commands,
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.x + 8,
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.y + 8,
|
||||
&fit_text_to_control(&suspended_game.title, HUB_SUSPENDED_GAME_KILL_CONTROL.w - 16),
|
||||
COLOR_TEXT,
|
||||
);
|
||||
}
|
||||
|
||||
fn fit_text_to_control(text: &str, max_width: i32) -> String {
|
||||
let max_chars = (max_width / 8).max(0) as usize;
|
||||
if text.chars().count() <= max_chars {
|
||||
return text.to_string();
|
||||
}
|
||||
|
||||
if max_chars <= 2 {
|
||||
return text.chars().take(max_chars).collect();
|
||||
}
|
||||
|
||||
let mut fitted: String = text.chars().take(max_chars - 2).collect();
|
||||
fitted.push_str("..");
|
||||
fitted
|
||||
}
|
||||
|
||||
fn draw_buffer_text(commands: &mut Vec<GfxUiCommand>, x: i32, y: i32, text: &str, color: Color) {
|
||||
@@ -338,11 +503,47 @@ fn draw_buffer_text(commands: &mut Vec<GfxUiCommand>, x: i32, y: i32, text: &str
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::task::TaskId;
|
||||
use crate::windows::WindowOwner;
|
||||
use prometeu_drivers::TestPlatform;
|
||||
use prometeu_hal::{InputSignals, RuntimePlatform};
|
||||
use std::path::PathBuf;
|
||||
|
||||
fn focused_native_shell_fixture(
|
||||
signals: &InputSignals,
|
||||
) -> (PrometeuHub, SystemOS, TestPlatform) {
|
||||
let hub = PrometeuHub::new();
|
||||
let mut os = SystemOS::new(None);
|
||||
let mut platform = TestPlatform::new();
|
||||
|
||||
{
|
||||
let mut windows = os.windows();
|
||||
let id = windows.add_window(
|
||||
"ShellA".to_string(),
|
||||
WindowOwner::Task(TaskId(7)),
|
||||
SHELL_FRAME,
|
||||
Color::GREEN,
|
||||
);
|
||||
windows.set_focus(id);
|
||||
}
|
||||
|
||||
platform.input_mut().pad_mut().begin_frame(signals);
|
||||
platform.input_mut().touch_mut().begin_frame(signals);
|
||||
|
||||
(hub, os, platform)
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn shell_a_button_click_emits_launch_action() {
|
||||
assert_eq!(
|
||||
action_for_click(false, HOME_BUTTONS[0].rect.x, HOME_BUTTONS[0].rect.y, true),
|
||||
action_for_click(
|
||||
false,
|
||||
HOME_BUTTONS[0].rect.x,
|
||||
HOME_BUTTONS[0].rect.y,
|
||||
true,
|
||||
&[],
|
||||
None
|
||||
),
|
||||
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellA))
|
||||
);
|
||||
}
|
||||
@@ -354,7 +555,9 @@ mod tests {
|
||||
false,
|
||||
SHELL_B_BUTTON.x + SHELL_B_BUTTON.w - 1,
|
||||
SHELL_B_BUTTON.y,
|
||||
true
|
||||
true,
|
||||
&[],
|
||||
None
|
||||
),
|
||||
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellB))
|
||||
);
|
||||
@@ -363,18 +566,35 @@ mod tests {
|
||||
#[test]
|
||||
fn button_hit_test_excludes_right_and_bottom_edges() {
|
||||
assert_eq!(
|
||||
action_for_click(false, SHELL_A_BUTTON.x + SHELL_A_BUTTON.w, SHELL_A_BUTTON.y, true),
|
||||
action_for_click(
|
||||
false,
|
||||
SHELL_A_BUTTON.x + SHELL_A_BUTTON.w,
|
||||
SHELL_A_BUTTON.y,
|
||||
true,
|
||||
&[],
|
||||
None
|
||||
),
|
||||
None
|
||||
);
|
||||
assert_eq!(
|
||||
action_for_click(false, SHELL_A_BUTTON.x, SHELL_A_BUTTON.y + SHELL_A_BUTTON.h, true),
|
||||
action_for_click(
|
||||
false,
|
||||
SHELL_A_BUTTON.x,
|
||||
SHELL_A_BUTTON.y + SHELL_A_BUTTON.h,
|
||||
true,
|
||||
&[],
|
||||
None
|
||||
),
|
||||
None
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn held_pointer_does_not_emit_click_action() {
|
||||
assert_eq!(action_for_click(false, SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, false), None);
|
||||
assert_eq!(
|
||||
action_for_click(false, SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, false, &[], None),
|
||||
None
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -383,13 +603,54 @@ mod tests {
|
||||
assert!(!hub.home_input_armed);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn game_row_click_emits_launch_game_action() {
|
||||
let entry = crate::GameLibraryEntry {
|
||||
manifest: prometeu_hal::cartridge::CartridgeManifest {
|
||||
magic: "PMTU".to_string(),
|
||||
cartridge_version: 1,
|
||||
app_id: 42,
|
||||
title: "Stress".to_string(),
|
||||
app_version: "1.0.0".to_string(),
|
||||
app_mode: prometeu_hal::app_mode::AppMode::Game,
|
||||
capabilities: vec![],
|
||||
},
|
||||
title: "Stress".to_string(),
|
||||
app_id: 42,
|
||||
app_version: "1.0.0".to_string(),
|
||||
path: PathBuf::from("test-cartridges/stress-console"),
|
||||
discovered_at: std::time::SystemTime::UNIX_EPOCH,
|
||||
};
|
||||
|
||||
let action = action_for_click(
|
||||
false,
|
||||
GAME_ROW_X,
|
||||
GAME_ROW_Y,
|
||||
true,
|
||||
std::slice::from_ref(&entry),
|
||||
None,
|
||||
);
|
||||
|
||||
assert_eq!(
|
||||
action,
|
||||
Some(SystemProfileAction::LaunchGame {
|
||||
target: GameSwitchTarget {
|
||||
path: entry.path.clone(),
|
||||
app_id: 42,
|
||||
title: "Stress".to_string(),
|
||||
app_version: "1.0.0".to_string(),
|
||||
}
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn close_button_click_emits_close_only_in_shell() {
|
||||
assert_eq!(
|
||||
action_for_click(true, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true),
|
||||
action_for_click(true, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[], None),
|
||||
Some(SystemProfileAction::CloseShell)
|
||||
);
|
||||
assert_eq!(action_for_click(false, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true), None);
|
||||
assert_eq!(action_for_click(false, CLOSE_BUTTON.x, CLOSE_BUTTON.y, true, &[], None), None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -403,7 +664,7 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn home_render_produces_shell_ui_packet_commands() {
|
||||
let packet = render_home_packet(SHELL_A_BUTTON.x, SHELL_A_BUTTON.y);
|
||||
let packet = render_home_packet(SHELL_A_BUTTON.x, SHELL_A_BUTTON.y, &[], None);
|
||||
|
||||
assert!(matches!(packet.commands.first(), Some(GfxUiCommand::Clear { .. })));
|
||||
assert!(packet.commands.iter().any(|command| {
|
||||
@@ -411,6 +672,123 @@ mod tests {
|
||||
}));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resident_game_indicator_uses_only_resident_game_sessions() {
|
||||
let mut os = SystemOS::new(None);
|
||||
assert_eq!(resident_game_indicator(&mut os), None);
|
||||
|
||||
let shell = os.sessions().create_vm_shell_task(7, "VM Shell");
|
||||
assert_eq!(resident_game_indicator(&mut os), None);
|
||||
os.lifecycle().suspend_task(shell).expect("shell suspend should succeed");
|
||||
assert_eq!(resident_game_indicator(&mut os), None);
|
||||
|
||||
let game = os.sessions().create_vm_game_task(42, "Stress Console");
|
||||
os.lifecycle().suspend_task(game).expect("game suspend should succeed");
|
||||
|
||||
assert_eq!(
|
||||
resident_game_indicator(&mut os),
|
||||
Some(SuspendedGameIndicator { title: "Stress Console".to_string() })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn home_render_shows_suspended_game_kill_control_when_game_is_resident() {
|
||||
let suspended_game = SuspendedGameIndicator { title: "Stress Console".to_string() };
|
||||
let packet = render_home_packet(
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||
&[],
|
||||
Some(&suspended_game),
|
||||
);
|
||||
|
||||
assert!(packet.commands.iter().any(|command| {
|
||||
matches!(
|
||||
command,
|
||||
GfxUiCommand::FillRect { rect, color }
|
||||
if *rect == HUB_SUSPENDED_GAME_KILL_CONTROL && *color == COLOR_KILL_ACTIVE
|
||||
)
|
||||
}));
|
||||
assert!(packet.commands.iter().any(|command| {
|
||||
matches!(
|
||||
command,
|
||||
GfxUiCommand::DrawText { x, y, text, .. }
|
||||
if *x == HUB_SUSPENDED_GAME_KILL_CONTROL.x + 8
|
||||
&& *y == HUB_SUSPENDED_GAME_KILL_CONTROL.y + 8
|
||||
&& text == "Stress Console"
|
||||
)
|
||||
}));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn home_render_omits_suspended_game_kill_control_without_resident_game() {
|
||||
let packet = render_home_packet(
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||
&[],
|
||||
None,
|
||||
);
|
||||
|
||||
assert!(!packet.commands.iter().any(|command| {
|
||||
matches!(
|
||||
command,
|
||||
GfxUiCommand::FillRect { rect, color }
|
||||
if *rect == HUB_SUSPENDED_GAME_KILL_CONTROL
|
||||
&& (*color == COLOR_KILL || *color == COLOR_KILL_ACTIVE)
|
||||
)
|
||||
}));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn suspended_game_kill_control_click_emits_kill_action() {
|
||||
let suspended_game = SuspendedGameIndicator { title: "Stress Console".to_string() };
|
||||
|
||||
assert_eq!(
|
||||
action_for_click(
|
||||
false,
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||
true,
|
||||
&[],
|
||||
Some(&suspended_game),
|
||||
),
|
||||
Some(SystemProfileAction::KillResidentGame)
|
||||
);
|
||||
assert_eq!(
|
||||
action_for_click(
|
||||
false,
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||
true,
|
||||
&[],
|
||||
None,
|
||||
),
|
||||
None
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn suspended_game_kill_control_truncates_long_titles() {
|
||||
let long_title =
|
||||
SuspendedGameIndicator { title: "Extremely Long Resident Game Title".to_string() };
|
||||
let packet = render_home_packet(0, 0, &[], Some(&long_title));
|
||||
let label = packet
|
||||
.commands
|
||||
.iter()
|
||||
.find_map(|command| match command {
|
||||
GfxUiCommand::DrawText { x, y, text, .. }
|
||||
if *x == HUB_SUSPENDED_GAME_KILL_CONTROL.x + 8
|
||||
&& *y == HUB_SUSPENDED_GAME_KILL_CONTROL.y + 8 =>
|
||||
{
|
||||
Some(text)
|
||||
}
|
||||
_ => None,
|
||||
})
|
||||
.expect("kill control text should render");
|
||||
|
||||
assert!(label.ends_with(".."));
|
||||
assert!(label.chars().count() <= ((HUB_SUSPENDED_GAME_KILL_CONTROL.w - 16) / 8) as usize);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn shell_close_button_sits_inside_shell_frame() {
|
||||
assert!(rect_contains(SHELL_FRAME, CLOSE_BUTTON.x, CLOSE_BUTTON.y));
|
||||
@@ -420,4 +798,35 @@ mod tests {
|
||||
CLOSE_BUTTON.y + CLOSE_BUTTON.h - 1
|
||||
));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn native_shell_profile_start_close_does_not_tick_vm() {
|
||||
let signals = InputSignals { start_signal: true, ..Default::default() };
|
||||
let (mut hub, mut os, mut platform) = focused_native_shell_fixture(&signals);
|
||||
|
||||
let tick_index_before_update = os.vm().tick_index();
|
||||
let outcome = hub.update_native_shell_profile(&mut os, &mut platform);
|
||||
|
||||
assert_eq!(outcome.action, Some(SystemProfileAction::CloseShell));
|
||||
assert!(outcome.crash.is_none());
|
||||
assert_eq!(os.vm().tick_index(), tick_index_before_update);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn native_shell_profile_close_button_does_not_tick_vm() {
|
||||
let signals = InputSignals {
|
||||
f_signal: true,
|
||||
x_pos: CLOSE_BUTTON.x,
|
||||
y_pos: CLOSE_BUTTON.y,
|
||||
..Default::default()
|
||||
};
|
||||
let (mut hub, mut os, mut platform) = focused_native_shell_fixture(&signals);
|
||||
|
||||
let tick_index_before_update = os.vm().tick_index();
|
||||
let outcome = hub.update_native_shell_profile(&mut os, &mut platform);
|
||||
|
||||
assert_eq!(outcome.action, Some(SystemProfileAction::CloseShell));
|
||||
assert!(outcome.crash.is_none());
|
||||
assert_eq!(os.vm().tick_index(), tick_index_before_update);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,601 @@
|
||||
use std::collections::VecDeque;
|
||||
use std::panic::{AssertUnwindSafe, catch_unwind};
|
||||
use std::sync::atomic::{AtomicBool, Ordering};
|
||||
use std::sync::mpsc::{self, Receiver, RecvTimeoutError};
|
||||
use std::sync::{Arc, Condvar, Mutex};
|
||||
use std::thread::{self, JoinHandle};
|
||||
use std::time::Duration;
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
||||
pub struct AsyncWorkJobId(u64);
|
||||
|
||||
impl AsyncWorkJobId {
|
||||
pub const ZERO: Self = Self(0);
|
||||
|
||||
pub fn new(value: u64) -> Self {
|
||||
Self(value)
|
||||
}
|
||||
|
||||
pub fn get(self) -> u64 {
|
||||
self.0
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum AsyncWorkJobKind {
|
||||
Asset,
|
||||
Memcard,
|
||||
Fs,
|
||||
Test,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum AsyncWorkPriority {
|
||||
MemcardCommitWrite,
|
||||
FsWriteConfig,
|
||||
AssetLoad,
|
||||
NonCriticalReadList,
|
||||
}
|
||||
|
||||
impl AsyncWorkPriority {
|
||||
const fn rank(self) -> u8 {
|
||||
match self {
|
||||
Self::MemcardCommitWrite => 0,
|
||||
Self::FsWriteConfig => 1,
|
||||
Self::AssetLoad => 2,
|
||||
Self::NonCriticalReadList => 3,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl AsyncWorkJobKind {
|
||||
pub const fn default_priority(self) -> AsyncWorkPriority {
|
||||
match self {
|
||||
Self::Memcard => AsyncWorkPriority::MemcardCommitWrite,
|
||||
Self::Fs => AsyncWorkPriority::FsWriteConfig,
|
||||
Self::Asset => AsyncWorkPriority::AssetLoad,
|
||||
Self::Test => AsyncWorkPriority::NonCriticalReadList,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum AsyncWorkJobOutcome {
|
||||
Completed,
|
||||
Canceled,
|
||||
Failed,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum AsyncWorkLaneError {
|
||||
Shutdown,
|
||||
WorkerPanic,
|
||||
ShutdownTimeout,
|
||||
InternalFailure,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct AsyncWorkLaneConfig {
|
||||
pub shutdown_timeout: Duration,
|
||||
}
|
||||
|
||||
impl Default for AsyncWorkLaneConfig {
|
||||
fn default() -> Self {
|
||||
Self { shutdown_timeout: Duration::from_millis(250) }
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct AsyncWorkActiveJob {
|
||||
pub id: AsyncWorkJobId,
|
||||
pub kind: AsyncWorkJobKind,
|
||||
pub priority: AsyncWorkPriority,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
|
||||
pub struct AsyncWorkLaneTelemetry {
|
||||
pub submitted_jobs: u64,
|
||||
pub started_jobs: u64,
|
||||
pub completed_jobs: u64,
|
||||
pub canceled_jobs: u64,
|
||||
pub failed_jobs: u64,
|
||||
pub shutdown_discards: u64,
|
||||
pub pending_depth: usize,
|
||||
pub max_pending_depth: usize,
|
||||
pub active_job_id: Option<AsyncWorkJobId>,
|
||||
pub last_submitted_job_id: Option<AsyncWorkJobId>,
|
||||
pub last_started_job_id: Option<AsyncWorkJobId>,
|
||||
pub last_closed_job_id: Option<AsyncWorkJobId>,
|
||||
}
|
||||
|
||||
impl AsyncWorkLaneTelemetry {
|
||||
fn record_submitted(&mut self, job_id: AsyncWorkJobId, pending_depth: usize) {
|
||||
self.submitted_jobs += 1;
|
||||
self.pending_depth = pending_depth;
|
||||
self.max_pending_depth = self.max_pending_depth.max(pending_depth);
|
||||
self.last_submitted_job_id = Some(job_id);
|
||||
}
|
||||
|
||||
fn record_started(&mut self, job_id: AsyncWorkJobId, pending_depth: usize) {
|
||||
self.started_jobs += 1;
|
||||
self.pending_depth = pending_depth;
|
||||
self.active_job_id = Some(job_id);
|
||||
self.last_started_job_id = Some(job_id);
|
||||
}
|
||||
|
||||
fn record_closed(&mut self, job_id: AsyncWorkJobId, outcome: AsyncWorkJobOutcome) {
|
||||
match outcome {
|
||||
AsyncWorkJobOutcome::Completed => self.completed_jobs += 1,
|
||||
AsyncWorkJobOutcome::Canceled => self.canceled_jobs += 1,
|
||||
AsyncWorkJobOutcome::Failed => self.failed_jobs += 1,
|
||||
}
|
||||
self.active_job_id = None;
|
||||
self.last_closed_job_id = Some(job_id);
|
||||
}
|
||||
|
||||
fn record_shutdown_discards(&mut self, count: usize) {
|
||||
self.shutdown_discards += count as u64;
|
||||
self.pending_depth = 0;
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct AsyncWorkCancelToken {
|
||||
canceled: Arc<AtomicBool>,
|
||||
}
|
||||
|
||||
impl AsyncWorkCancelToken {
|
||||
fn new() -> Self {
|
||||
Self { canceled: Arc::new(AtomicBool::new(false)) }
|
||||
}
|
||||
|
||||
pub fn cancel(&self) {
|
||||
self.canceled.store(true, Ordering::Relaxed);
|
||||
}
|
||||
|
||||
pub fn is_canceled(&self) -> bool {
|
||||
self.canceled.load(Ordering::Relaxed)
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Clone, Debug)]
|
||||
pub struct AsyncWorkJobContext {
|
||||
pub job_id: AsyncWorkJobId,
|
||||
pub kind: AsyncWorkJobKind,
|
||||
pub priority: AsyncWorkPriority,
|
||||
cancel_token: AsyncWorkCancelToken,
|
||||
}
|
||||
|
||||
impl AsyncWorkJobContext {
|
||||
pub fn is_canceled(&self) -> bool {
|
||||
self.cancel_token.is_canceled()
|
||||
}
|
||||
}
|
||||
|
||||
type AsyncWorkFn = Box<dyn FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static>;
|
||||
|
||||
struct PendingAsyncWorkJob {
|
||||
id: AsyncWorkJobId,
|
||||
kind: AsyncWorkJobKind,
|
||||
priority: AsyncWorkPriority,
|
||||
cancel_token: AsyncWorkCancelToken,
|
||||
work: AsyncWorkFn,
|
||||
}
|
||||
|
||||
struct RunningAsyncWorkJob {
|
||||
id: AsyncWorkJobId,
|
||||
kind: AsyncWorkJobKind,
|
||||
priority: AsyncWorkPriority,
|
||||
cancel_token: AsyncWorkCancelToken,
|
||||
work: AsyncWorkFn,
|
||||
}
|
||||
|
||||
#[derive(Default)]
|
||||
struct AsyncWorkLaneState {
|
||||
next_job_id: u64,
|
||||
pending: VecDeque<PendingAsyncWorkJob>,
|
||||
active: Option<AsyncWorkActiveJob>,
|
||||
active_cancel_token: Option<AsyncWorkCancelToken>,
|
||||
shutdown_requested: bool,
|
||||
telemetry: AsyncWorkLaneTelemetry,
|
||||
}
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct AsyncWorkLane {
|
||||
state: Mutex<AsyncWorkLaneState>,
|
||||
ready: Condvar,
|
||||
}
|
||||
|
||||
impl AsyncWorkLane {
|
||||
pub fn submit(
|
||||
&self,
|
||||
kind: AsyncWorkJobKind,
|
||||
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
|
||||
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
|
||||
self.submit_with_priority(kind, kind.default_priority(), work)
|
||||
}
|
||||
|
||||
pub fn submit_with_priority(
|
||||
&self,
|
||||
kind: AsyncWorkJobKind,
|
||||
priority: AsyncWorkPriority,
|
||||
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
|
||||
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
|
||||
let mut state = self.state.lock().map_err(|_| AsyncWorkLaneError::InternalFailure)?;
|
||||
if state.shutdown_requested {
|
||||
return Err(AsyncWorkLaneError::Shutdown);
|
||||
}
|
||||
|
||||
state.next_job_id += 1;
|
||||
let id = AsyncWorkJobId::new(state.next_job_id);
|
||||
let cancel_token = AsyncWorkCancelToken::new();
|
||||
let job = PendingAsyncWorkJob { id, kind, priority, cancel_token, work: Box::new(work) };
|
||||
let insert_at = state
|
||||
.pending
|
||||
.iter()
|
||||
.position(|pending| priority.rank() < pending.priority.rank())
|
||||
.unwrap_or(state.pending.len());
|
||||
state.pending.insert(insert_at, job);
|
||||
let pending_depth = state.pending.len();
|
||||
state.telemetry.record_submitted(id, pending_depth);
|
||||
self.ready.notify_one();
|
||||
Ok(id)
|
||||
}
|
||||
|
||||
pub fn submit_memcard_commit_write(
|
||||
&self,
|
||||
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
|
||||
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
|
||||
self.submit_with_priority(
|
||||
AsyncWorkJobKind::Memcard,
|
||||
AsyncWorkPriority::MemcardCommitWrite,
|
||||
work,
|
||||
)
|
||||
}
|
||||
|
||||
pub fn submit_fs_write_config(
|
||||
&self,
|
||||
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
|
||||
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
|
||||
self.submit_with_priority(AsyncWorkJobKind::Fs, AsyncWorkPriority::FsWriteConfig, work)
|
||||
}
|
||||
|
||||
pub fn submit_asset_load(
|
||||
&self,
|
||||
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
|
||||
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
|
||||
self.submit_with_priority(AsyncWorkJobKind::Asset, AsyncWorkPriority::AssetLoad, work)
|
||||
}
|
||||
|
||||
pub fn submit_non_critical_read_list(
|
||||
&self,
|
||||
kind: AsyncWorkJobKind,
|
||||
work: impl FnOnce(AsyncWorkJobContext) -> AsyncWorkJobOutcome + Send + 'static,
|
||||
) -> Result<AsyncWorkJobId, AsyncWorkLaneError> {
|
||||
self.submit_with_priority(kind, AsyncWorkPriority::NonCriticalReadList, work)
|
||||
}
|
||||
|
||||
pub fn request_cancel(&self, job_id: AsyncWorkJobId) -> bool {
|
||||
let state = self.state.lock().unwrap();
|
||||
if let Some(token) = state
|
||||
.active
|
||||
.filter(|active| active.id == job_id)
|
||||
.and(state.active_cancel_token.as_ref())
|
||||
{
|
||||
token.cancel();
|
||||
return true;
|
||||
}
|
||||
|
||||
for pending in &state.pending {
|
||||
if pending.id == job_id {
|
||||
pending.cancel_token.cancel();
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
false
|
||||
}
|
||||
|
||||
pub fn active_job(&self) -> Option<AsyncWorkActiveJob> {
|
||||
self.state.lock().unwrap().active
|
||||
}
|
||||
|
||||
pub fn pending_depth(&self) -> usize {
|
||||
self.state.lock().unwrap().pending.len()
|
||||
}
|
||||
|
||||
pub fn telemetry(&self) -> AsyncWorkLaneTelemetry {
|
||||
self.state.lock().unwrap().telemetry
|
||||
}
|
||||
|
||||
pub fn request_shutdown(&self) {
|
||||
let mut state = self.state.lock().unwrap();
|
||||
state.shutdown_requested = true;
|
||||
if let Some(token) = &state.active_cancel_token {
|
||||
token.cancel();
|
||||
}
|
||||
self.ready.notify_all();
|
||||
}
|
||||
|
||||
fn wait_take(&self) -> Option<RunningAsyncWorkJob> {
|
||||
self.wait_take_with_hook(|| {})
|
||||
}
|
||||
|
||||
fn wait_take_with_hook(&self, mut before_wait: impl FnMut()) -> Option<RunningAsyncWorkJob> {
|
||||
let mut state = self.state.lock().unwrap();
|
||||
loop {
|
||||
if state.shutdown_requested {
|
||||
let discarded = state.pending.len();
|
||||
state.pending.clear();
|
||||
state.telemetry.record_shutdown_discards(discarded);
|
||||
return None;
|
||||
}
|
||||
|
||||
if let Some(pending) = state.pending.pop_front() {
|
||||
let active = AsyncWorkActiveJob {
|
||||
id: pending.id,
|
||||
kind: pending.kind,
|
||||
priority: pending.priority,
|
||||
};
|
||||
state.active = Some(active);
|
||||
state.active_cancel_token = Some(pending.cancel_token.clone());
|
||||
let pending_depth = state.pending.len();
|
||||
state.telemetry.record_started(pending.id, pending_depth);
|
||||
return Some(RunningAsyncWorkJob {
|
||||
id: pending.id,
|
||||
kind: pending.kind,
|
||||
priority: pending.priority,
|
||||
cancel_token: pending.cancel_token,
|
||||
work: pending.work,
|
||||
});
|
||||
}
|
||||
|
||||
before_wait();
|
||||
state = self.ready.wait(state).unwrap();
|
||||
}
|
||||
}
|
||||
|
||||
fn record_finished(&self, job_id: AsyncWorkJobId, outcome: AsyncWorkJobOutcome) {
|
||||
let mut state = self.state.lock().unwrap();
|
||||
if state.active.is_some_and(|active| active.id == job_id) {
|
||||
state.active = None;
|
||||
state.active_cancel_token = None;
|
||||
}
|
||||
state.telemetry.record_closed(job_id, outcome);
|
||||
}
|
||||
}
|
||||
|
||||
pub struct AsyncWorkLaneController {
|
||||
config: AsyncWorkLaneConfig,
|
||||
lane: Arc<AsyncWorkLane>,
|
||||
handle: Option<JoinHandle<()>>,
|
||||
done_rx: Receiver<Result<(), AsyncWorkLaneError>>,
|
||||
}
|
||||
|
||||
impl AsyncWorkLaneController {
|
||||
pub fn start(config: AsyncWorkLaneConfig, lane: Arc<AsyncWorkLane>) -> Self {
|
||||
let worker_lane = Arc::clone(&lane);
|
||||
let (done_tx, done_rx) = mpsc::channel();
|
||||
let handle = thread::spawn(move || {
|
||||
let result = catch_unwind(AssertUnwindSafe(|| run_async_work_loop(worker_lane)))
|
||||
.map_err(|_| AsyncWorkLaneError::WorkerPanic);
|
||||
let _ = done_tx.send(result);
|
||||
});
|
||||
|
||||
Self { config, lane, handle: Some(handle), done_rx }
|
||||
}
|
||||
|
||||
pub fn lane(&self) -> Arc<AsyncWorkLane> {
|
||||
Arc::clone(&self.lane)
|
||||
}
|
||||
|
||||
pub fn stop(&mut self) -> Result<(), AsyncWorkLaneError> {
|
||||
self.lane.request_shutdown();
|
||||
match self.done_rx.recv_timeout(self.config.shutdown_timeout) {
|
||||
Ok(result) => {
|
||||
if let Some(handle) = self.handle.take()
|
||||
&& handle.join().is_err()
|
||||
{
|
||||
return Err(AsyncWorkLaneError::WorkerPanic);
|
||||
}
|
||||
result
|
||||
}
|
||||
Err(RecvTimeoutError::Timeout) => Err(AsyncWorkLaneError::ShutdownTimeout),
|
||||
Err(RecvTimeoutError::Disconnected) => Err(AsyncWorkLaneError::InternalFailure),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for AsyncWorkLaneController {
|
||||
fn drop(&mut self) {
|
||||
if self.handle.is_some() {
|
||||
let _ = self.stop();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn run_async_work_loop(lane: Arc<AsyncWorkLane>) {
|
||||
while let Some(job) = lane.wait_take() {
|
||||
let context = AsyncWorkJobContext {
|
||||
job_id: job.id,
|
||||
kind: job.kind,
|
||||
priority: job.priority,
|
||||
cancel_token: job.cancel_token,
|
||||
};
|
||||
let result = catch_unwind(AssertUnwindSafe(|| (job.work)(context)))
|
||||
.unwrap_or(AsyncWorkJobOutcome::Failed);
|
||||
lane.record_finished(job.id, result);
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use std::sync::mpsc;
|
||||
|
||||
#[test]
|
||||
fn async_work_lane_runs_jobs_in_submission_order() {
|
||||
let lane = Arc::new(AsyncWorkLane::default());
|
||||
let mut controller =
|
||||
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), Arc::clone(&lane));
|
||||
let (tx, rx) = mpsc::channel();
|
||||
|
||||
lane.submit(AsyncWorkJobKind::Test, {
|
||||
let tx = tx.clone();
|
||||
move |_| {
|
||||
tx.send(1).unwrap();
|
||||
AsyncWorkJobOutcome::Completed
|
||||
}
|
||||
})
|
||||
.unwrap();
|
||||
lane.submit(AsyncWorkJobKind::Test, {
|
||||
let tx = tx.clone();
|
||||
move |_| {
|
||||
tx.send(2).unwrap();
|
||||
AsyncWorkJobOutcome::Completed
|
||||
}
|
||||
})
|
||||
.unwrap();
|
||||
|
||||
assert_eq!(rx.recv().unwrap(), 1);
|
||||
assert_eq!(rx.recv().unwrap(), 2);
|
||||
controller.stop().unwrap();
|
||||
|
||||
let telemetry = lane.telemetry();
|
||||
assert_eq!(telemetry.submitted_jobs, 2);
|
||||
assert_eq!(telemetry.started_jobs, 2);
|
||||
assert_eq!(telemetry.completed_jobs, 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn async_work_lane_runs_higher_priority_io_before_assets() {
|
||||
let lane = Arc::new(AsyncWorkLane::default());
|
||||
let (tx, rx) = mpsc::channel();
|
||||
|
||||
lane.submit_asset_load({
|
||||
let tx = tx.clone();
|
||||
move |ctx| {
|
||||
tx.send((ctx.kind, ctx.priority)).unwrap();
|
||||
AsyncWorkJobOutcome::Completed
|
||||
}
|
||||
})
|
||||
.unwrap();
|
||||
lane.submit_non_critical_read_list(AsyncWorkJobKind::Fs, {
|
||||
let tx = tx.clone();
|
||||
move |ctx| {
|
||||
tx.send((ctx.kind, ctx.priority)).unwrap();
|
||||
AsyncWorkJobOutcome::Completed
|
||||
}
|
||||
})
|
||||
.unwrap();
|
||||
lane.submit_memcard_commit_write({
|
||||
let tx = tx.clone();
|
||||
move |ctx| {
|
||||
tx.send((ctx.kind, ctx.priority)).unwrap();
|
||||
AsyncWorkJobOutcome::Completed
|
||||
}
|
||||
})
|
||||
.unwrap();
|
||||
lane.submit_fs_write_config({
|
||||
let tx = tx.clone();
|
||||
move |ctx| {
|
||||
tx.send((ctx.kind, ctx.priority)).unwrap();
|
||||
AsyncWorkJobOutcome::Completed
|
||||
}
|
||||
})
|
||||
.unwrap();
|
||||
|
||||
let mut controller =
|
||||
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), Arc::clone(&lane));
|
||||
|
||||
assert_eq!(
|
||||
rx.recv().unwrap(),
|
||||
(AsyncWorkJobKind::Memcard, AsyncWorkPriority::MemcardCommitWrite)
|
||||
);
|
||||
assert_eq!(rx.recv().unwrap(), (AsyncWorkJobKind::Fs, AsyncWorkPriority::FsWriteConfig));
|
||||
assert_eq!(rx.recv().unwrap(), (AsyncWorkJobKind::Asset, AsyncWorkPriority::AssetLoad));
|
||||
assert_eq!(
|
||||
rx.recv().unwrap(),
|
||||
(AsyncWorkJobKind::Fs, AsyncWorkPriority::NonCriticalReadList)
|
||||
);
|
||||
controller.stop().unwrap();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn async_work_lane_has_one_active_job() {
|
||||
let lane = Arc::new(AsyncWorkLane::default());
|
||||
let mut controller =
|
||||
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), Arc::clone(&lane));
|
||||
let (first_started_tx, first_started_rx) = mpsc::channel();
|
||||
let (release_first_tx, release_first_rx) = mpsc::channel();
|
||||
let (second_started_tx, second_started_rx) = mpsc::channel();
|
||||
|
||||
let first = lane
|
||||
.submit(AsyncWorkJobKind::Test, move |_| {
|
||||
first_started_tx.send(()).unwrap();
|
||||
release_first_rx.recv().unwrap();
|
||||
AsyncWorkJobOutcome::Completed
|
||||
})
|
||||
.unwrap();
|
||||
let second = lane
|
||||
.submit(AsyncWorkJobKind::Test, move |_| {
|
||||
second_started_tx.send(()).unwrap();
|
||||
AsyncWorkJobOutcome::Completed
|
||||
})
|
||||
.unwrap();
|
||||
|
||||
first_started_rx.recv().unwrap();
|
||||
assert_eq!(lane.active_job().unwrap().id, first);
|
||||
assert_eq!(lane.pending_depth(), 1);
|
||||
assert!(second_started_rx.try_recv().is_err());
|
||||
|
||||
release_first_tx.send(()).unwrap();
|
||||
second_started_rx.recv().unwrap();
|
||||
assert_eq!(lane.telemetry().last_started_job_id, Some(second));
|
||||
controller.stop().unwrap();
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn async_work_lane_supports_cooperative_cancellation() {
|
||||
let lane = Arc::new(AsyncWorkLane::default());
|
||||
let mut controller =
|
||||
AsyncWorkLaneController::start(AsyncWorkLaneConfig::default(), Arc::clone(&lane));
|
||||
let (started_tx, started_rx) = mpsc::channel();
|
||||
|
||||
let job_id = lane
|
||||
.submit(AsyncWorkJobKind::Test, move |ctx| {
|
||||
started_tx.send(()).unwrap();
|
||||
while !ctx.is_canceled() {
|
||||
std::thread::yield_now();
|
||||
}
|
||||
AsyncWorkJobOutcome::Canceled
|
||||
})
|
||||
.unwrap();
|
||||
|
||||
started_rx.recv().unwrap();
|
||||
assert!(lane.request_cancel(job_id));
|
||||
controller.stop().unwrap();
|
||||
assert_eq!(lane.telemetry().canceled_jobs, 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn async_work_lane_rejects_submit_after_shutdown() {
|
||||
let lane = Arc::new(AsyncWorkLane::default());
|
||||
lane.request_shutdown();
|
||||
|
||||
let result = lane.submit(AsyncWorkJobKind::Test, |_| AsyncWorkJobOutcome::Completed);
|
||||
assert_eq!(result, Err(AsyncWorkLaneError::Shutdown));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn async_work_lane_shutdown_discards_pending_jobs() {
|
||||
let lane = Arc::new(AsyncWorkLane::default());
|
||||
lane.submit(AsyncWorkJobKind::Test, |_| AsyncWorkJobOutcome::Completed).unwrap();
|
||||
assert_eq!(lane.pending_depth(), 1);
|
||||
|
||||
lane.request_shutdown();
|
||||
assert!(lane.wait_take().is_none());
|
||||
assert_eq!(lane.pending_depth(), 0);
|
||||
assert_eq!(lane.telemetry().shutdown_discards, 1);
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,330 @@
|
||||
use crate::task::TaskId;
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum ForegroundOwner {
|
||||
Hub,
|
||||
Game(TaskId),
|
||||
Shell(TaskId),
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum ResidentGameState {
|
||||
Foreground,
|
||||
PauseRequested { remaining_ticks: u8 },
|
||||
ResumeRequested,
|
||||
PausedSuspended,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct ResidentGame {
|
||||
pub task_id: TaskId,
|
||||
pub state: ResidentGameState,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum ForegroundStackError {
|
||||
ResidentGameAlreadyExists { existing: TaskId, requested: TaskId },
|
||||
ForegroundShellAlreadyExists { existing: TaskId, requested: TaskId },
|
||||
TaskIsNotResidentGame(TaskId),
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct ForegroundStack {
|
||||
owner: ForegroundOwner,
|
||||
resident_game: Option<ResidentGame>,
|
||||
}
|
||||
|
||||
impl Default for ForegroundStack {
|
||||
fn default() -> Self {
|
||||
Self { owner: ForegroundOwner::Hub, resident_game: None }
|
||||
}
|
||||
}
|
||||
|
||||
impl ForegroundStack {
|
||||
pub fn new() -> Self {
|
||||
Self::default()
|
||||
}
|
||||
|
||||
pub fn owner(&self) -> ForegroundOwner {
|
||||
self.owner
|
||||
}
|
||||
|
||||
pub fn resident_game(&self) -> Option<ResidentGame> {
|
||||
self.resident_game
|
||||
}
|
||||
|
||||
pub fn resident_game_task(&self) -> Option<TaskId> {
|
||||
self.resident_game.map(|game| game.task_id)
|
||||
}
|
||||
|
||||
pub fn set_game_foreground(&mut self, task_id: TaskId) -> Result<(), ForegroundStackError> {
|
||||
if let Some(game) = self.resident_game
|
||||
&& game.task_id != task_id
|
||||
{
|
||||
return Err(ForegroundStackError::ResidentGameAlreadyExists {
|
||||
existing: game.task_id,
|
||||
requested: task_id,
|
||||
});
|
||||
}
|
||||
|
||||
self.resident_game = Some(ResidentGame { task_id, state: ResidentGameState::Foreground });
|
||||
self.owner = ForegroundOwner::Game(task_id);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn request_home_from_game(
|
||||
&mut self,
|
||||
task_id: TaskId,
|
||||
pause_budget_ticks: u8,
|
||||
) -> Result<(), ForegroundStackError> {
|
||||
match self.resident_game {
|
||||
Some(game) if game.task_id == task_id => {
|
||||
if !matches!(
|
||||
game.state,
|
||||
ResidentGameState::PauseRequested { .. } | ResidentGameState::PausedSuspended
|
||||
) {
|
||||
self.resident_game = Some(ResidentGame {
|
||||
task_id,
|
||||
state: ResidentGameState::PauseRequested {
|
||||
remaining_ticks: pause_budget_ticks.max(1),
|
||||
},
|
||||
});
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
_ => Err(ForegroundStackError::TaskIsNotResidentGame(task_id)),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn advance_pause_budget(&mut self, task_id: TaskId) -> Result<bool, ForegroundStackError> {
|
||||
match self.resident_game {
|
||||
Some(game)
|
||||
if game.task_id == task_id
|
||||
&& matches!(
|
||||
game.state,
|
||||
ResidentGameState::PauseRequested { remaining_ticks: 1 }
|
||||
) =>
|
||||
{
|
||||
self.resident_game =
|
||||
Some(ResidentGame { task_id, state: ResidentGameState::PausedSuspended });
|
||||
self.owner = ForegroundOwner::Hub;
|
||||
Ok(true)
|
||||
}
|
||||
Some(game)
|
||||
if game.task_id == task_id
|
||||
&& matches!(game.state, ResidentGameState::PauseRequested { .. }) =>
|
||||
{
|
||||
let ResidentGameState::PauseRequested { remaining_ticks } = game.state else {
|
||||
unreachable!();
|
||||
};
|
||||
self.resident_game = Some(ResidentGame {
|
||||
task_id,
|
||||
state: ResidentGameState::PauseRequested {
|
||||
remaining_ticks: remaining_ticks.saturating_sub(1).max(1),
|
||||
},
|
||||
});
|
||||
Ok(false)
|
||||
}
|
||||
Some(game) if game.task_id == task_id => Ok(false),
|
||||
_ => Err(ForegroundStackError::TaskIsNotResidentGame(task_id)),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn request_resume_game(&mut self, task_id: TaskId) -> Result<(), ForegroundStackError> {
|
||||
match self.resident_game {
|
||||
Some(game) if game.task_id == task_id => {
|
||||
self.resident_game =
|
||||
Some(ResidentGame { task_id, state: ResidentGameState::ResumeRequested });
|
||||
Ok(())
|
||||
}
|
||||
_ => Err(ForegroundStackError::TaskIsNotResidentGame(task_id)),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn complete_resume_game(&mut self, task_id: TaskId) -> Result<(), ForegroundStackError> {
|
||||
match self.resident_game {
|
||||
Some(game) if game.task_id == task_id => {
|
||||
self.resident_game =
|
||||
Some(ResidentGame { task_id, state: ResidentGameState::Foreground });
|
||||
self.owner = ForegroundOwner::Game(task_id);
|
||||
Ok(())
|
||||
}
|
||||
_ => Err(ForegroundStackError::TaskIsNotResidentGame(task_id)),
|
||||
}
|
||||
}
|
||||
|
||||
pub fn set_shell_foreground(&mut self, task_id: TaskId) -> Result<(), ForegroundStackError> {
|
||||
if let ForegroundOwner::Shell(existing) = self.owner
|
||||
&& existing != task_id
|
||||
{
|
||||
return Err(ForegroundStackError::ForegroundShellAlreadyExists {
|
||||
existing,
|
||||
requested: task_id,
|
||||
});
|
||||
}
|
||||
|
||||
if let Some(game) = self.resident_game {
|
||||
self.resident_game = Some(ResidentGame {
|
||||
task_id: game.task_id,
|
||||
state: ResidentGameState::PausedSuspended,
|
||||
});
|
||||
}
|
||||
self.owner = ForegroundOwner::Shell(task_id);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn return_to_hub(&mut self) {
|
||||
self.owner = ForegroundOwner::Hub;
|
||||
}
|
||||
|
||||
pub fn clear_resident_game(&mut self, task_id: TaskId) {
|
||||
if self.resident_game_task() == Some(task_id) {
|
||||
self.resident_game = None;
|
||||
}
|
||||
|
||||
if self.owner == ForegroundOwner::Game(task_id) {
|
||||
self.owner = ForegroundOwner::Hub;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn foreground_stack_starts_at_hub() {
|
||||
let stack = ForegroundStack::new();
|
||||
|
||||
assert_eq!(stack.owner(), ForegroundOwner::Hub);
|
||||
assert_eq!(stack.resident_game(), None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn setting_game_foreground_registers_resident_game() {
|
||||
let mut stack = ForegroundStack::new();
|
||||
let game = TaskId(7);
|
||||
|
||||
stack.set_game_foreground(game).expect("game should become foreground");
|
||||
|
||||
assert_eq!(stack.owner(), ForegroundOwner::Game(game));
|
||||
assert_eq!(
|
||||
stack.resident_game(),
|
||||
Some(ResidentGame { task_id: game, state: ResidentGameState::Foreground })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn second_resident_game_is_rejected() {
|
||||
let mut stack = ForegroundStack::new();
|
||||
|
||||
stack.set_game_foreground(TaskId(1)).expect("first game should be accepted");
|
||||
|
||||
assert_eq!(
|
||||
stack.set_game_foreground(TaskId(2)),
|
||||
Err(ForegroundStackError::ResidentGameAlreadyExists {
|
||||
existing: TaskId(1),
|
||||
requested: TaskId(2),
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn home_request_moves_resident_game_to_pause_requested() {
|
||||
let mut stack = ForegroundStack::new();
|
||||
let game = TaskId(3);
|
||||
|
||||
stack.set_game_foreground(game).expect("game should be foreground");
|
||||
stack.request_home_from_game(game, 2).expect("home request should pause game");
|
||||
|
||||
assert_eq!(stack.owner(), ForegroundOwner::Game(game));
|
||||
assert_eq!(
|
||||
stack.resident_game(),
|
||||
Some(ResidentGame {
|
||||
task_id: game,
|
||||
state: ResidentGameState::PauseRequested { remaining_ticks: 2 },
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn pause_budget_expiry_suspends_game_and_returns_to_hub() {
|
||||
let mut stack = ForegroundStack::new();
|
||||
let game = TaskId(3);
|
||||
|
||||
stack.set_game_foreground(game).expect("game should be foreground");
|
||||
stack.request_home_from_game(game, 1).expect("home request should pause game");
|
||||
|
||||
assert!(stack.advance_pause_budget(game).expect("budget should advance"));
|
||||
assert_eq!(stack.owner(), ForegroundOwner::Hub);
|
||||
assert_eq!(
|
||||
stack.resident_game(),
|
||||
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn pause_budget_decrements_before_expiry() {
|
||||
let mut stack = ForegroundStack::new();
|
||||
let game = TaskId(3);
|
||||
|
||||
stack.set_game_foreground(game).expect("game should be foreground");
|
||||
stack.request_home_from_game(game, 2).expect("home request should pause game");
|
||||
|
||||
assert!(!stack.advance_pause_budget(game).expect("budget should advance"));
|
||||
assert_eq!(stack.owner(), ForegroundOwner::Game(game));
|
||||
assert_eq!(
|
||||
stack.resident_game(),
|
||||
Some(ResidentGame {
|
||||
task_id: game,
|
||||
state: ResidentGameState::PauseRequested { remaining_ticks: 1 },
|
||||
})
|
||||
);
|
||||
|
||||
assert!(stack.advance_pause_budget(game).expect("budget should expire"));
|
||||
assert_eq!(stack.owner(), ForegroundOwner::Hub);
|
||||
assert_eq!(
|
||||
stack.resident_game(),
|
||||
Some(ResidentGame { task_id: game, state: ResidentGameState::PausedSuspended })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resume_request_precedes_game_foreground_restore() {
|
||||
let mut stack = ForegroundStack::new();
|
||||
let game = TaskId(3);
|
||||
|
||||
stack.set_game_foreground(game).expect("game should be foreground");
|
||||
stack.request_home_from_game(game, 1).expect("home request should pause game");
|
||||
stack.advance_pause_budget(game).expect("budget should expire");
|
||||
|
||||
stack.request_resume_game(game).expect("resume should be requested");
|
||||
assert_eq!(stack.owner(), ForegroundOwner::Hub);
|
||||
assert_eq!(
|
||||
stack.resident_game(),
|
||||
Some(ResidentGame { task_id: game, state: ResidentGameState::ResumeRequested })
|
||||
);
|
||||
|
||||
stack.complete_resume_game(game).expect("resume should complete");
|
||||
assert_eq!(stack.owner(), ForegroundOwner::Game(game));
|
||||
assert_eq!(
|
||||
stack.resident_game(),
|
||||
Some(ResidentGame { task_id: game, state: ResidentGameState::Foreground })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn shell_foreground_keeps_resident_game() {
|
||||
let mut stack = ForegroundStack::new();
|
||||
let game = TaskId(3);
|
||||
let shell = TaskId(4);
|
||||
|
||||
stack.set_game_foreground(game).expect("game should be foreground");
|
||||
stack.request_home_from_game(game, 1).expect("home request should suspend game");
|
||||
stack.advance_pause_budget(game).expect("budget should expire");
|
||||
stack.set_shell_foreground(shell).expect("shell should become foreground");
|
||||
|
||||
assert_eq!(stack.owner(), ForegroundOwner::Shell(shell));
|
||||
assert_eq!(stack.resident_game_task(), Some(game));
|
||||
}
|
||||
}
|
||||
@@ -8,4 +8,4 @@ pub use fs_backend::FsBackend;
|
||||
pub use fs_entry::FsEntry;
|
||||
pub use fs_error::FsError;
|
||||
pub use fs_state::FsState;
|
||||
pub use virtual_fs::VirtualFS;
|
||||
pub use virtual_fs::{FsAsyncLaneOperation, VirtualFS};
|
||||
|
||||
@@ -1,4 +1,5 @@
|
||||
use crate::fs::{FsBackend, FsEntry, FsError};
|
||||
use crate::services::async_work::{AsyncWorkJobKind, AsyncWorkPriority};
|
||||
|
||||
/// Virtual Filesystem (VFS) interface for Prometeu.
|
||||
///
|
||||
@@ -13,6 +14,29 @@ pub struct VirtualFS {
|
||||
backend: Option<Box<dyn FsBackend>>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum FsAsyncLaneOperation {
|
||||
Write,
|
||||
Delete,
|
||||
Config,
|
||||
Read,
|
||||
ListDir,
|
||||
Exists,
|
||||
}
|
||||
|
||||
impl FsAsyncLaneOperation {
|
||||
pub const fn job_kind(self) -> AsyncWorkJobKind {
|
||||
AsyncWorkJobKind::Fs
|
||||
}
|
||||
|
||||
pub const fn priority(self) -> AsyncWorkPriority {
|
||||
match self {
|
||||
Self::Write | Self::Delete | Self::Config => AsyncWorkPriority::FsWriteConfig,
|
||||
Self::Read | Self::ListDir | Self::Exists => AsyncWorkPriority::NonCriticalReadList,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for VirtualFS {
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
@@ -242,4 +266,18 @@ mod tests {
|
||||
assert!(matches!(vfs.delete("/"), Err(FsError::PermissionDenied)));
|
||||
assert_eq!(calls.delete.load(Ordering::Relaxed), 0);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn fs_async_lane_operations_classify_priority_without_public_api_changes() {
|
||||
assert_eq!(FsAsyncLaneOperation::Write.job_kind(), AsyncWorkJobKind::Fs);
|
||||
assert_eq!(FsAsyncLaneOperation::Write.priority(), AsyncWorkPriority::FsWriteConfig);
|
||||
assert_eq!(FsAsyncLaneOperation::Delete.priority(), AsyncWorkPriority::FsWriteConfig);
|
||||
assert_eq!(FsAsyncLaneOperation::Config.priority(), AsyncWorkPriority::FsWriteConfig);
|
||||
assert_eq!(FsAsyncLaneOperation::Read.priority(), AsyncWorkPriority::NonCriticalReadList);
|
||||
assert_eq!(
|
||||
FsAsyncLaneOperation::ListDir.priority(),
|
||||
AsyncWorkPriority::NonCriticalReadList
|
||||
);
|
||||
assert_eq!(FsAsyncLaneOperation::Exists.priority(), AsyncWorkPriority::NonCriticalReadList);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,336 @@
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::cartridge::CartridgeManifest;
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
use std::time::SystemTime;
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct GameLibraryEntry {
|
||||
pub manifest: CartridgeManifest,
|
||||
pub title: String,
|
||||
pub app_id: u32,
|
||||
pub app_version: String,
|
||||
pub path: PathBuf,
|
||||
pub discovered_at: SystemTime,
|
||||
}
|
||||
|
||||
impl GameLibraryEntry {
|
||||
fn new(path: PathBuf, manifest: CartridgeManifest, discovered_at: SystemTime) -> Self {
|
||||
Self {
|
||||
title: manifest.title.clone(),
|
||||
app_id: manifest.app_id,
|
||||
app_version: manifest.app_version.clone(),
|
||||
manifest,
|
||||
path,
|
||||
discovered_at,
|
||||
}
|
||||
}
|
||||
|
||||
pub fn switch_target(&self) -> GameSwitchTarget {
|
||||
GameSwitchTarget::from_entry(self)
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct GameSwitchTarget {
|
||||
pub path: PathBuf,
|
||||
pub app_id: u32,
|
||||
pub title: String,
|
||||
pub app_version: String,
|
||||
}
|
||||
|
||||
impl GameSwitchTarget {
|
||||
pub fn from_entry(entry: &GameLibraryEntry) -> Self {
|
||||
Self {
|
||||
path: entry.path.clone(),
|
||||
app_id: entry.app_id,
|
||||
title: entry.title.clone(),
|
||||
app_version: entry.app_version.clone(),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct GameLibraryDiagnostic {
|
||||
pub path: PathBuf,
|
||||
pub reason: GameLibraryDiagnosticReason,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum GameLibraryDiagnosticReason {
|
||||
RootNotDirectory,
|
||||
CandidateReadFailed,
|
||||
MissingManifest,
|
||||
InvalidManifest,
|
||||
UnsupportedVersion,
|
||||
MissingProgram,
|
||||
NonGameAppMode,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Default)]
|
||||
pub struct GameLibrary {
|
||||
entries: Vec<GameLibraryEntry>,
|
||||
diagnostics: Vec<GameLibraryDiagnostic>,
|
||||
}
|
||||
|
||||
impl GameLibrary {
|
||||
pub fn empty() -> Self {
|
||||
Self::default()
|
||||
}
|
||||
|
||||
pub fn entries(&self) -> &[GameLibraryEntry] {
|
||||
&self.entries
|
||||
}
|
||||
|
||||
pub fn diagnostics(&self) -> &[GameLibraryDiagnostic] {
|
||||
&self.diagnostics
|
||||
}
|
||||
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.entries.is_empty()
|
||||
}
|
||||
}
|
||||
|
||||
pub fn discover_games_root(root: impl AsRef<Path>) -> GameLibrary {
|
||||
let root = root.as_ref();
|
||||
let discovered_at = SystemTime::now();
|
||||
|
||||
if !root.is_dir() {
|
||||
return GameLibrary {
|
||||
entries: Vec::new(),
|
||||
diagnostics: vec![GameLibraryDiagnostic {
|
||||
path: root.to_path_buf(),
|
||||
reason: GameLibraryDiagnosticReason::RootNotDirectory,
|
||||
}],
|
||||
};
|
||||
}
|
||||
|
||||
let read_dir = match fs::read_dir(root) {
|
||||
Ok(read_dir) => read_dir,
|
||||
Err(_) => {
|
||||
return GameLibrary {
|
||||
entries: Vec::new(),
|
||||
diagnostics: vec![GameLibraryDiagnostic {
|
||||
path: root.to_path_buf(),
|
||||
reason: GameLibraryDiagnosticReason::CandidateReadFailed,
|
||||
}],
|
||||
};
|
||||
}
|
||||
};
|
||||
|
||||
let mut entries = Vec::new();
|
||||
let mut diagnostics = Vec::new();
|
||||
|
||||
for item in read_dir {
|
||||
let Ok(item) = item else {
|
||||
diagnostics.push(GameLibraryDiagnostic {
|
||||
path: root.to_path_buf(),
|
||||
reason: GameLibraryDiagnosticReason::CandidateReadFailed,
|
||||
});
|
||||
continue;
|
||||
};
|
||||
|
||||
let path = item.path();
|
||||
if !path.is_dir() {
|
||||
continue;
|
||||
}
|
||||
|
||||
match discover_candidate(&path, discovered_at) {
|
||||
Ok(entry) => entries.push(entry),
|
||||
Err(reason) => diagnostics.push(GameLibraryDiagnostic { path, reason }),
|
||||
}
|
||||
}
|
||||
|
||||
entries.sort_by(|left, right| {
|
||||
left.title
|
||||
.cmp(&right.title)
|
||||
.then_with(|| left.app_id.cmp(&right.app_id))
|
||||
.then_with(|| left.path.cmp(&right.path))
|
||||
});
|
||||
|
||||
GameLibrary { entries, diagnostics }
|
||||
}
|
||||
|
||||
fn discover_candidate(
|
||||
path: &Path,
|
||||
discovered_at: SystemTime,
|
||||
) -> Result<GameLibraryEntry, GameLibraryDiagnosticReason> {
|
||||
let manifest_path = path.join("manifest.json");
|
||||
if !manifest_path.exists() {
|
||||
return Err(GameLibraryDiagnosticReason::MissingManifest);
|
||||
}
|
||||
|
||||
let manifest_content = fs::read_to_string(manifest_path)
|
||||
.map_err(|_| GameLibraryDiagnosticReason::InvalidManifest)?;
|
||||
let manifest: CartridgeManifest = serde_json::from_str(&manifest_content)
|
||||
.map_err(|_| GameLibraryDiagnosticReason::InvalidManifest)?;
|
||||
|
||||
if manifest.magic != "PMTU" {
|
||||
return Err(GameLibraryDiagnosticReason::InvalidManifest);
|
||||
}
|
||||
if manifest.cartridge_version != 1 {
|
||||
return Err(GameLibraryDiagnosticReason::UnsupportedVersion);
|
||||
}
|
||||
if manifest.app_mode != AppMode::Game {
|
||||
return Err(GameLibraryDiagnosticReason::NonGameAppMode);
|
||||
}
|
||||
if !path.join("program.pbx").exists() {
|
||||
return Err(GameLibraryDiagnosticReason::MissingProgram);
|
||||
}
|
||||
|
||||
Ok(GameLibraryEntry::new(path.to_path_buf(), manifest, discovered_at))
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use serde_json::json;
|
||||
use std::sync::atomic::{AtomicU64, Ordering};
|
||||
use std::time::UNIX_EPOCH;
|
||||
|
||||
static TEST_DIR_COUNTER: AtomicU64 = AtomicU64::new(0);
|
||||
|
||||
struct TestRoot {
|
||||
path: PathBuf,
|
||||
}
|
||||
|
||||
impl TestRoot {
|
||||
fn new() -> Self {
|
||||
let unique = TEST_DIR_COUNTER.fetch_add(1, Ordering::Relaxed);
|
||||
let path = std::env::temp_dir().join(format!(
|
||||
"prometeu-game-library-test-{}-{}",
|
||||
std::process::id(),
|
||||
unique
|
||||
));
|
||||
fs::create_dir_all(&path).expect("test root should be created");
|
||||
Self { path }
|
||||
}
|
||||
|
||||
fn add_candidate(&self, name: &str, manifest: serde_json::Value, with_program: bool) {
|
||||
let candidate = self.path.join(name);
|
||||
fs::create_dir_all(&candidate).expect("candidate should be created");
|
||||
fs::write(candidate.join("manifest.json"), manifest.to_string())
|
||||
.expect("manifest should be written");
|
||||
if with_program {
|
||||
fs::write(candidate.join("program.pbx"), [0_u8])
|
||||
.expect("program should be written");
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl Drop for TestRoot {
|
||||
fn drop(&mut self) {
|
||||
let _ = fs::remove_dir_all(&self.path);
|
||||
}
|
||||
}
|
||||
|
||||
fn manifest(title: &str, app_id: u32, app_mode: &str) -> serde_json::Value {
|
||||
json!({
|
||||
"magic": "PMTU",
|
||||
"cartridge_version": 1,
|
||||
"app_id": app_id,
|
||||
"title": title,
|
||||
"app_version": "1.0.0",
|
||||
"app_mode": app_mode
|
||||
})
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn discovery_returns_only_immediate_valid_game_directories() {
|
||||
let root = TestRoot::new();
|
||||
root.add_candidate("zeta", manifest("Zeta", 2, "Game"), true);
|
||||
root.add_candidate("alpha", manifest("Alpha", 1, "Game"), true);
|
||||
root.add_candidate("shell", manifest("Shell", 3, "Shell"), true);
|
||||
root.add_candidate("missing-program", manifest("Missing Program", 4, "Game"), false);
|
||||
fs::write(root.path.join("loose-file.txt"), "ignored").expect("file should be written");
|
||||
|
||||
let nested_parent = root.path.join("nested-parent");
|
||||
fs::create_dir_all(nested_parent.join("nested-game")).expect("nested dir should exist");
|
||||
fs::write(
|
||||
nested_parent.join("nested-game").join("manifest.json"),
|
||||
manifest("Nested", 5, "Game").to_string(),
|
||||
)
|
||||
.expect("nested manifest should be written");
|
||||
fs::write(nested_parent.join("nested-game").join("program.pbx"), [0_u8])
|
||||
.expect("nested program should be written");
|
||||
|
||||
let library = discover_games_root(&root.path);
|
||||
|
||||
assert_eq!(library.entries().len(), 2);
|
||||
assert_eq!(library.entries()[0].title, "Alpha");
|
||||
assert_eq!(library.entries()[0].app_id, 1);
|
||||
assert_eq!(library.entries()[0].app_version, "1.0.0");
|
||||
assert_eq!(library.entries()[0].manifest.app_mode, AppMode::Game);
|
||||
assert!(library.entries()[0].path.ends_with("alpha"));
|
||||
assert!(library.entries()[0].discovered_at >= UNIX_EPOCH);
|
||||
assert_eq!(library.entries()[1].title, "Zeta");
|
||||
|
||||
assert!(library.diagnostics().iter().any(|diagnostic| {
|
||||
diagnostic.path.ends_with("shell")
|
||||
&& diagnostic.reason == GameLibraryDiagnosticReason::NonGameAppMode
|
||||
}));
|
||||
assert!(library.diagnostics().iter().any(|diagnostic| {
|
||||
diagnostic.path.ends_with("missing-program")
|
||||
&& diagnostic.reason == GameLibraryDiagnosticReason::MissingProgram
|
||||
}));
|
||||
assert!(library.diagnostics().iter().any(|diagnostic| {
|
||||
diagnostic.path.ends_with("nested-parent")
|
||||
&& diagnostic.reason == GameLibraryDiagnosticReason::MissingManifest
|
||||
}));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn switch_target_preserves_resolved_identity() {
|
||||
let path = PathBuf::from("test-cartridges/stress-console");
|
||||
let entry = GameLibraryEntry::new(
|
||||
path.clone(),
|
||||
CartridgeManifest {
|
||||
magic: "PMTU".to_string(),
|
||||
cartridge_version: 1,
|
||||
app_id: 42,
|
||||
title: "Stress".to_string(),
|
||||
app_version: "1.0.0".to_string(),
|
||||
app_mode: AppMode::Game,
|
||||
capabilities: vec![],
|
||||
},
|
||||
UNIX_EPOCH,
|
||||
);
|
||||
|
||||
let target = entry.switch_target();
|
||||
|
||||
assert_eq!(target.path, path);
|
||||
assert_eq!(target.app_id, 42);
|
||||
assert_eq!(target.title, "Stress");
|
||||
assert_eq!(target.app_version, "1.0.0");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn missing_root_returns_diagnostic_and_no_entries() {
|
||||
let root = TestRoot::new();
|
||||
let missing = root.path.join("missing");
|
||||
|
||||
let library = discover_games_root(&missing);
|
||||
|
||||
assert!(library.is_empty());
|
||||
assert_eq!(library.diagnostics().len(), 1);
|
||||
assert_eq!(library.diagnostics()[0].reason, GameLibraryDiagnosticReason::RootNotDirectory);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn repository_test_cartridges_include_stress_and_dummy_boy() {
|
||||
let games_root =
|
||||
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges");
|
||||
|
||||
let library = discover_games_root(games_root);
|
||||
let entries = library.entries();
|
||||
|
||||
assert!(entries.iter().any(|entry| {
|
||||
entry.app_id == 1
|
||||
&& entry.title == "Stress Console"
|
||||
&& entry.path.ends_with("stress-console")
|
||||
}));
|
||||
assert!(entries.iter().any(|entry| {
|
||||
entry.app_id == 2 && entry.title == "Dummy Boy" && entry.path.ends_with("dummy-boy")
|
||||
}));
|
||||
}
|
||||
}
|
||||
@@ -1,4 +1,5 @@
|
||||
use crate::fs::{FsError, VirtualFS};
|
||||
use crate::services::async_work::{AsyncWorkJobKind, AsyncWorkPriority};
|
||||
use std::collections::HashMap;
|
||||
|
||||
pub const MEMCARD_SLOT_COUNT: usize = 32;
|
||||
@@ -50,6 +51,30 @@ pub struct MemcardWriteResult {
|
||||
pub bytes_written: u32,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum MemcardAsyncLaneOperation {
|
||||
SlotWrite,
|
||||
SlotCommit,
|
||||
SlotClear,
|
||||
SlotRead,
|
||||
SlotStat,
|
||||
}
|
||||
|
||||
impl MemcardAsyncLaneOperation {
|
||||
pub const fn job_kind(self) -> AsyncWorkJobKind {
|
||||
AsyncWorkJobKind::Memcard
|
||||
}
|
||||
|
||||
pub const fn priority(self) -> AsyncWorkPriority {
|
||||
match self {
|
||||
Self::SlotWrite | Self::SlotCommit | Self::SlotClear => {
|
||||
AsyncWorkPriority::MemcardCommitWrite
|
||||
}
|
||||
Self::SlotRead | Self::SlotStat => AsyncWorkPriority::NonCriticalReadList,
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
struct SlotImage {
|
||||
payload: Vec<u8>,
|
||||
@@ -428,4 +453,29 @@ mod tests {
|
||||
let stat = mem.slot_stat(&fs, 7, 2);
|
||||
assert_eq!(stat.state, MemcardSlotState::Corrupt);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn memcard_async_lane_operations_classify_priority_without_changing_public_api() {
|
||||
assert_eq!(MemcardAsyncLaneOperation::SlotWrite.job_kind(), AsyncWorkJobKind::Memcard);
|
||||
assert_eq!(
|
||||
MemcardAsyncLaneOperation::SlotWrite.priority(),
|
||||
AsyncWorkPriority::MemcardCommitWrite
|
||||
);
|
||||
assert_eq!(
|
||||
MemcardAsyncLaneOperation::SlotCommit.priority(),
|
||||
AsyncWorkPriority::MemcardCommitWrite
|
||||
);
|
||||
assert_eq!(
|
||||
MemcardAsyncLaneOperation::SlotClear.priority(),
|
||||
AsyncWorkPriority::MemcardCommitWrite
|
||||
);
|
||||
assert_eq!(
|
||||
MemcardAsyncLaneOperation::SlotRead.priority(),
|
||||
AsyncWorkPriority::NonCriticalReadList
|
||||
);
|
||||
assert_eq!(
|
||||
MemcardAsyncLaneOperation::SlotStat.priority(),
|
||||
AsyncWorkPriority::NonCriticalReadList
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1,6 +1,10 @@
|
||||
pub mod async_work;
|
||||
pub mod foreground;
|
||||
pub mod fs;
|
||||
pub mod game_library;
|
||||
pub mod memcard;
|
||||
pub mod process;
|
||||
pub mod task;
|
||||
pub mod vm_runtime;
|
||||
pub mod vm_session;
|
||||
pub mod windows;
|
||||
|
||||
@@ -168,13 +168,9 @@ impl NativeInterface for VmRuntimeHost<'_> {
|
||||
VmFault::Trap(TRAP_INVALID_SYSCALL, format!("Unknown syscall: 0x{:08X}", id))
|
||||
})?;
|
||||
|
||||
match syscall {
|
||||
Syscall::SystemHasCart => {
|
||||
ret.push_bool(true);
|
||||
return Ok(());
|
||||
}
|
||||
Syscall::SystemRunCart => return Ok(()),
|
||||
_ => {}
|
||||
if syscall == Syscall::SystemHasCart {
|
||||
ret.push_bool(true);
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
self.ensure_game_profile_syscall(syscall)?;
|
||||
@@ -183,7 +179,6 @@ impl NativeInterface for VmRuntimeHost<'_> {
|
||||
|
||||
match syscall {
|
||||
Syscall::SystemHasCart => unreachable!(),
|
||||
Syscall::SystemRunCart => unreachable!(),
|
||||
Syscall::GfxClear => {
|
||||
let color = self.get_color(expect_int(args, 0)?)?;
|
||||
self.gfx2d_commands.push(Gfx2dCommand::Clear { color });
|
||||
@@ -757,6 +752,64 @@ impl NativeInterface for VmRuntimeHost<'_> {
|
||||
ret.push_int(status as i64);
|
||||
Ok(())
|
||||
}
|
||||
Syscall::AssetBacklogInfo => {
|
||||
let info = platform.assets().backlog_info();
|
||||
ret.push_int(info.status as i64);
|
||||
ret.push_int(info.pending_count as i64);
|
||||
ret.push_int(info.active_handle as i64);
|
||||
ret.push_int(info.active_asset_id.unwrap_or(0) as i64);
|
||||
ret.push_int(info.active_bank_type.map(|bank| bank as i64).unwrap_or(0));
|
||||
ret.push_int(info.active_slot.map(|slot| slot as i64).unwrap_or(0));
|
||||
ret.push_int(info.active_progress as i64);
|
||||
Ok(())
|
||||
}
|
||||
Syscall::AssetBacklogPosition => {
|
||||
let position = platform.assets().backlog_position(expect_int(args, 0)? as u32);
|
||||
ret.push_int(position.status as i64);
|
||||
ret.push_int(position.state as i64);
|
||||
ret.push_int(position.position as i64);
|
||||
ret.push_int(position.progress as i64);
|
||||
Ok(())
|
||||
}
|
||||
Syscall::AssetBacklogMove => {
|
||||
let new_position = expect_non_negative_usize(args, 1, "new_position")?;
|
||||
let status =
|
||||
platform.assets().backlog_move(expect_int(args, 0)? as u32, new_position);
|
||||
ret.push_int(status as i64);
|
||||
Ok(())
|
||||
}
|
||||
Syscall::AssetBacklogPromote => {
|
||||
let status = platform.assets().backlog_promote(expect_int(args, 0)? as u32);
|
||||
ret.push_int(status as i64);
|
||||
Ok(())
|
||||
}
|
||||
Syscall::AssetBacklogDemote => {
|
||||
let status = platform.assets().backlog_demote(expect_int(args, 0)? as u32);
|
||||
ret.push_int(status as i64);
|
||||
Ok(())
|
||||
}
|
||||
Syscall::AssetTargetStatus => {
|
||||
let bank_type = match expect_int(args, 0)? {
|
||||
0 => BankType::GLYPH,
|
||||
1 => BankType::SOUNDS,
|
||||
2 => BankType::SCENE,
|
||||
other => {
|
||||
return Err(VmFault::Trap(
|
||||
TRAP_TYPE,
|
||||
format!("Invalid asset bank type: {}", other),
|
||||
));
|
||||
}
|
||||
};
|
||||
let slot = expect_non_negative_usize(args, 1, "slot")?;
|
||||
let target = platform.assets().target_status(bank_type, slot);
|
||||
ret.push_int(target.status as i64);
|
||||
ret.push_int(target.asset_id.unwrap_or(0) as i64);
|
||||
ret.push_int(target.handle as i64);
|
||||
ret.push_int(target.state as i64);
|
||||
ret.push_int(target.position as i64);
|
||||
ret.push_int(target.progress as i64);
|
||||
Ok(())
|
||||
}
|
||||
Syscall::BankInfo => {
|
||||
let asset_type = match expect_int(args, 0)? as u32 {
|
||||
0 => BankType::GLYPH,
|
||||
|
||||
@@ -32,6 +32,7 @@ impl VirtualMachineRuntime {
|
||||
gfx2d_commands: Vec::new(),
|
||||
gfxui_commands: Vec::new(),
|
||||
logs_written_this_frame: HashMap::new(),
|
||||
game_lifecycle_events_delivered: Vec::new(),
|
||||
atomic_telemetry,
|
||||
last_crash_report: None,
|
||||
certifier: Certifier::new(cap_config.unwrap_or_default()),
|
||||
@@ -135,6 +136,7 @@ impl VirtualMachineRuntime {
|
||||
self.gfx2d_commands.clear();
|
||||
self.gfxui_commands.clear();
|
||||
self.logs_written_this_frame.clear();
|
||||
self.game_lifecycle_events_delivered.clear();
|
||||
|
||||
self.last_crash_report = None;
|
||||
|
||||
@@ -191,6 +193,21 @@ impl VirtualMachineRuntime {
|
||||
}
|
||||
}
|
||||
|
||||
pub fn deliver_game_lifecycle_events<I>(&mut self, events: I)
|
||||
where
|
||||
I: IntoIterator<Item = GameLifecycleEvent>,
|
||||
{
|
||||
self.game_lifecycle_events_delivered.extend(events);
|
||||
}
|
||||
|
||||
pub fn delivered_game_lifecycle_events(&self) -> &[GameLifecycleEvent] {
|
||||
&self.game_lifecycle_events_delivered
|
||||
}
|
||||
|
||||
pub fn take_delivered_game_lifecycle_events(&mut self) -> Vec<GameLifecycleEvent> {
|
||||
std::mem::take(&mut self.game_lifecycle_events_delivered)
|
||||
}
|
||||
|
||||
pub fn initialize_vm(
|
||||
&mut self,
|
||||
log_service: &mut LogService,
|
||||
@@ -224,3 +241,26 @@ impl VirtualMachineRuntime {
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::os::{GameLifecycleEvent, GameLifecycleEventKind};
|
||||
use crate::task::TaskId;
|
||||
|
||||
#[test]
|
||||
fn vm_runtime_records_and_drains_delivered_game_lifecycle_events() {
|
||||
let mut runtime = VirtualMachineRuntime::new(None);
|
||||
let pause = GameLifecycleEvent { task_id: TaskId(7), kind: GameLifecycleEventKind::Pause };
|
||||
let resume = GameLifecycleEvent {
|
||||
task_id: TaskId(7),
|
||||
kind: GameLifecycleEventKind::ResumeForeground,
|
||||
};
|
||||
|
||||
runtime.deliver_game_lifecycle_events([pause, resume]);
|
||||
|
||||
assert_eq!(runtime.delivered_game_lifecycle_events(), &[pause, resume]);
|
||||
assert_eq!(runtime.take_delivered_game_lifecycle_events(), vec![pause, resume]);
|
||||
assert!(runtime.delivered_game_lifecycle_events().is_empty());
|
||||
}
|
||||
}
|
||||
|
||||
@@ -13,6 +13,7 @@ mod tests;
|
||||
mod tick;
|
||||
|
||||
use crate::CrashReport;
|
||||
use crate::os::GameLifecycleEvent;
|
||||
pub use frame_scheduler::FrameScheduler;
|
||||
use prometeu_bytecode::string_materialization_count;
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
@@ -49,6 +50,7 @@ pub struct VirtualMachineRuntime {
|
||||
pub gfx2d_commands: Vec<Gfx2dCommand>,
|
||||
pub gfxui_commands: Vec<GfxUiCommand>,
|
||||
pub logs_written_this_frame: HashMap<u32, u32>,
|
||||
pub game_lifecycle_events_delivered: Vec<GameLifecycleEvent>,
|
||||
pub atomic_telemetry: Arc<AtomicTelemetry>,
|
||||
pub last_crash_report: Option<CrashReport>,
|
||||
pub certifier: Certifier,
|
||||
|
||||
@@ -15,7 +15,7 @@ use prometeu_hal::asset::{
|
||||
use prometeu_hal::cartridge::{AssetsPayloadSource, Cartridge};
|
||||
use prometeu_hal::color::Color;
|
||||
use prometeu_hal::glyph::Glyph;
|
||||
use prometeu_hal::glyph_bank::{GLYPH_BANK_PALETTE_COUNT_V1, GlyphBank, TileSize};
|
||||
use prometeu_hal::glyph_bank::{GLYPH_BANK_MAX_PALETTE_COUNT_V1, GlyphBank, TileSize};
|
||||
use prometeu_hal::scene_bank::SceneBank;
|
||||
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
|
||||
use prometeu_hal::syscalls::caps;
|
||||
@@ -113,11 +113,12 @@ fn serialized_single_function_module_with_consts(
|
||||
}
|
||||
|
||||
fn test_glyph_payload_size(width: usize, height: usize) -> usize {
|
||||
(width * height).div_ceil(2) + (GLYPH_BANK_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
|
||||
(width * height).div_ceil(2)
|
||||
+ (GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
|
||||
}
|
||||
|
||||
fn test_glyph_decoded_size(width: usize, height: usize) -> usize {
|
||||
width * height + (GLYPH_BANK_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
|
||||
width * height + (GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * std::mem::size_of::<u32>())
|
||||
}
|
||||
|
||||
fn test_glyph_asset_entry(asset_name: &str, data_len: usize) -> AssetEntry {
|
||||
@@ -133,23 +134,23 @@ fn test_glyph_asset_entry(asset_name: &str, data_len: usize) -> AssetEntry {
|
||||
"tile_size": 16,
|
||||
"width": 16,
|
||||
"height": 16,
|
||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
||||
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||
}),
|
||||
}
|
||||
}
|
||||
|
||||
fn test_glyph_asset_data() -> Vec<u8> {
|
||||
let mut data =
|
||||
vec![0x11u8; test_glyph_payload_size(16, 16) - (GLYPH_BANK_PALETTE_COUNT_V1 * 16 * 4)];
|
||||
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_COUNT_V1 * 16 * 4]);
|
||||
vec![0x11u8; test_glyph_payload_size(16, 16) - (GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * 4)];
|
||||
data.extend_from_slice(&[0u8; GLYPH_BANK_MAX_PALETTE_COUNT_V1 * 16 * 4]);
|
||||
data
|
||||
}
|
||||
|
||||
fn runtime_test_glyph_bank(tile_size: TileSize, palette_id: u8, color: Color) -> GlyphBank {
|
||||
let size = tile_size as usize;
|
||||
let mut bank = GlyphBank::new(tile_size, size, size);
|
||||
bank.palettes[palette_id as usize][1] = color;
|
||||
let mut bank = GlyphBank::with_palette_count(tile_size, size, size, palette_id as usize + 1);
|
||||
bank.palette_mut(palette_id).unwrap()[1] = color;
|
||||
for pixel in &mut bank.pixel_indices {
|
||||
*pixel = 1;
|
||||
}
|
||||
@@ -1275,6 +1276,53 @@ fn tick_composer_emit_sprite_operational_error_returns_status_not_crash() {
|
||||
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(ComposerOpStatus::BankInvalid as i64)]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn tick_composer_emit_sprite_invalid_palette_returns_bank_invalid() {
|
||||
let mut runtime = VirtualMachineRuntime::new(None);
|
||||
let mut log_service = LogService::new(4096);
|
||||
let mut fs = VirtualFS::new();
|
||||
let mut fs_state = FsState::Unmounted;
|
||||
let mut memcard = MemcardService::new();
|
||||
let mut open_files: HashMap<u32, String> = HashMap::new();
|
||||
let mut next_handle = 1;
|
||||
let mut vm = VirtualMachine::default();
|
||||
let banks = Arc::new(MemoryBanks::new());
|
||||
banks.install_glyph_bank(0, Arc::new(runtime_test_glyph_bank(TileSize::Size8, 0, Color::BLUE)));
|
||||
let mut platform = TestPlatform::new_with_memory_banks(banks);
|
||||
let signals = InputSignals::default();
|
||||
let code = assemble(
|
||||
"PUSH_I32 0\nPUSH_I32 1\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 0\nPUSH_BOOL 0\nPUSH_BOOL 0\nPUSH_I32 0\nHOSTCALL 0\nHALT",
|
||||
)
|
||||
.expect("assemble");
|
||||
let program = serialized_single_function_module(
|
||||
code,
|
||||
vec![SyscallDecl {
|
||||
module: "composer".into(),
|
||||
name: "emit_sprite".into(),
|
||||
version: 1,
|
||||
arg_slots: 9,
|
||||
ret_slots: 1,
|
||||
}],
|
||||
);
|
||||
let cartridge = cartridge_with_program(program, caps::GFX);
|
||||
|
||||
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
|
||||
let report = runtime.tick(
|
||||
&mut log_service,
|
||||
&mut fs,
|
||||
&mut fs_state,
|
||||
&mut memcard,
|
||||
&mut open_files,
|
||||
&mut next_handle,
|
||||
&mut vm,
|
||||
&signals,
|
||||
&mut platform,
|
||||
);
|
||||
assert!(report.is_none(), "invalid palette must not crash VM execution");
|
||||
assert!(vm.is_halted());
|
||||
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(ComposerOpStatus::BankInvalid as i64)]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn tick_composer_emit_sprite_invalid_layer_returns_status_not_crash() {
|
||||
let mut runtime = VirtualMachineRuntime::new(None);
|
||||
|
||||
@@ -180,6 +180,102 @@ fn tick_asset_status_unknown_handle_returns_status_not_crash() {
|
||||
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(LoadStatus::UnknownHandle as i64)]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn tick_asset_target_status_empty_slot_returns_status_first_payload() {
|
||||
let mut runtime = VirtualMachineRuntime::new(None);
|
||||
let mut log_service = LogService::new(4096);
|
||||
let mut fs = VirtualFS::new();
|
||||
let mut fs_state = FsState::Unmounted;
|
||||
let mut memcard = MemcardService::new();
|
||||
let mut open_files: HashMap<u32, String> = HashMap::new();
|
||||
let mut next_handle = 1;
|
||||
let mut vm = VirtualMachine::default();
|
||||
let mut platform = TestPlatform::new();
|
||||
let signals = InputSignals::default();
|
||||
let code = assemble("PUSH_I32 0\nPUSH_I32 0\nHOSTCALL 0\nHALT").expect("assemble");
|
||||
let program = serialized_single_function_module(
|
||||
code,
|
||||
vec![SyscallDecl {
|
||||
module: "asset".into(),
|
||||
name: "target_status".into(),
|
||||
version: 1,
|
||||
arg_slots: 2,
|
||||
ret_slots: 6,
|
||||
}],
|
||||
);
|
||||
let cartridge = cartridge_with_program(program, caps::ASSET);
|
||||
|
||||
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
|
||||
let report = runtime.tick(
|
||||
&mut log_service,
|
||||
&mut fs,
|
||||
&mut fs_state,
|
||||
&mut memcard,
|
||||
&mut open_files,
|
||||
&mut next_handle,
|
||||
&mut vm,
|
||||
&signals,
|
||||
&mut platform,
|
||||
);
|
||||
|
||||
assert!(report.is_none(), "target_status must not crash for empty slots");
|
||||
assert!(vm.is_halted());
|
||||
assert_eq!(
|
||||
vm.operand_stack_top(6),
|
||||
vec![
|
||||
Value::Int64(0),
|
||||
Value::Int64(0),
|
||||
Value::Int64(LoadStatus::EMPTY as i64),
|
||||
Value::Int64(1),
|
||||
Value::Int64(0),
|
||||
Value::Int64(AssetOpStatus::Ok as i64),
|
||||
]
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn tick_asset_backlog_promote_unknown_handle_returns_status_not_crash() {
|
||||
let mut runtime = VirtualMachineRuntime::new(None);
|
||||
let mut log_service = LogService::new(4096);
|
||||
let mut fs = VirtualFS::new();
|
||||
let mut fs_state = FsState::Unmounted;
|
||||
let mut memcard = MemcardService::new();
|
||||
let mut open_files: HashMap<u32, String> = HashMap::new();
|
||||
let mut next_handle = 1;
|
||||
let mut vm = VirtualMachine::default();
|
||||
let mut platform = TestPlatform::new();
|
||||
let signals = InputSignals::default();
|
||||
let code = assemble("PUSH_I32 999\nHOSTCALL 0\nHALT").expect("assemble");
|
||||
let program = serialized_single_function_module(
|
||||
code,
|
||||
vec![SyscallDecl {
|
||||
module: "asset".into(),
|
||||
name: "backlog_promote".into(),
|
||||
version: 1,
|
||||
arg_slots: 1,
|
||||
ret_slots: 1,
|
||||
}],
|
||||
);
|
||||
let cartridge = cartridge_with_program(program, caps::ASSET);
|
||||
|
||||
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
|
||||
let report = runtime.tick(
|
||||
&mut log_service,
|
||||
&mut fs,
|
||||
&mut fs_state,
|
||||
&mut memcard,
|
||||
&mut open_files,
|
||||
&mut next_handle,
|
||||
&mut vm,
|
||||
&signals,
|
||||
&mut platform,
|
||||
);
|
||||
|
||||
assert!(report.is_none(), "unknown backlog handle must not crash");
|
||||
assert!(vm.is_halted());
|
||||
assert_eq!(vm.operand_stack_top(1), vec![Value::Int64(AssetOpStatus::UnknownHandle as i64)]);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn tick_bank_info_returns_slot_summary_not_json() {
|
||||
let mut runtime = VirtualMachineRuntime::new(None);
|
||||
@@ -391,20 +487,15 @@ fn tick_asset_cancel_invalid_transition_returns_status_not_crash() {
|
||||
|
||||
runtime.initialize_vm(&mut log_service, &mut vm, &cartridge).expect("runtime must initialize");
|
||||
|
||||
let mut asset_ready = false;
|
||||
for _ in 0..1_000 {
|
||||
match platform.local_hardware().assets.status(handle) {
|
||||
LoadStatus::READY => {
|
||||
asset_ready = true;
|
||||
break;
|
||||
}
|
||||
LoadStatus::PENDING | LoadStatus::LOADING => {
|
||||
std::thread::yield_now();
|
||||
}
|
||||
other => panic!("unexpected asset status before commit: {:?}", other),
|
||||
}
|
||||
let start = Instant::now();
|
||||
let mut status = platform.local_hardware().assets.status(handle);
|
||||
while matches!(status, LoadStatus::PENDING | LoadStatus::LOADING)
|
||||
&& start.elapsed() < std::time::Duration::from_secs(5)
|
||||
{
|
||||
std::thread::sleep(std::time::Duration::from_millis(10));
|
||||
status = platform.local_hardware().assets.status(handle);
|
||||
}
|
||||
assert!(asset_ready, "asset did not become ready before commit");
|
||||
assert_eq!(status, LoadStatus::READY, "asset did not become ready before commit");
|
||||
|
||||
assert_eq!(platform.local_hardware().assets.commit(handle), AssetOpStatus::Ok);
|
||||
platform.local_hardware().assets.apply_commits();
|
||||
|
||||
@@ -0,0 +1,310 @@
|
||||
use crate::VirtualMachineRuntime;
|
||||
use crate::fs::FsState;
|
||||
use crate::process::{Process, ProcessId, ProcessKind};
|
||||
use crate::task::{Task, TaskId, TaskKind};
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::telemetry::CertificationConfig;
|
||||
use prometeu_vm::VirtualMachine;
|
||||
use std::collections::HashMap;
|
||||
use std::sync::Arc;
|
||||
use std::sync::atomic::AtomicU32;
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
|
||||
pub struct VmSessionId(pub TaskId);
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum VmSessionError {
|
||||
SessionAlreadyExists(TaskId),
|
||||
TaskProcessMismatch { task_id: TaskId, task_process: ProcessId, process_id: ProcessId },
|
||||
TaskKindMismatch { task_id: TaskId, task_kind: TaskKind, process_kind: ProcessKind },
|
||||
ProcessIsNotVmBacked(ProcessId),
|
||||
}
|
||||
|
||||
pub struct VmSession {
|
||||
pub id: VmSessionId,
|
||||
pub task_id: TaskId,
|
||||
pub process_id: ProcessId,
|
||||
pub app_id: u32,
|
||||
pub title: String,
|
||||
pub app_version: String,
|
||||
pub app_mode: AppMode,
|
||||
pub vm: VirtualMachine,
|
||||
pub runtime: VirtualMachineRuntime,
|
||||
pub fs_state: FsState,
|
||||
pub open_files: HashMap<u32, String>,
|
||||
pub next_handle: u32,
|
||||
}
|
||||
|
||||
impl VmSession {
|
||||
fn new(
|
||||
task: &Task,
|
||||
process: &Process,
|
||||
app_mode: AppMode,
|
||||
app_version: impl Into<String>,
|
||||
cap_config: Option<CertificationConfig>,
|
||||
logs_count: Arc<AtomicU32>,
|
||||
) -> Self {
|
||||
Self {
|
||||
id: VmSessionId(task.id),
|
||||
task_id: task.id,
|
||||
process_id: process.id,
|
||||
app_id: task.app_id,
|
||||
title: task.title.clone(),
|
||||
app_version: app_version.into(),
|
||||
app_mode,
|
||||
vm: VirtualMachine::default(),
|
||||
runtime: VirtualMachineRuntime::new_with_log_counter(cap_config, logs_count),
|
||||
fs_state: FsState::Unmounted,
|
||||
open_files: HashMap::new(),
|
||||
next_handle: 1,
|
||||
}
|
||||
}
|
||||
|
||||
pub fn clear_cartridge_service_state(&mut self) {
|
||||
self.open_files.clear();
|
||||
self.next_handle = 1;
|
||||
}
|
||||
}
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct VmSessionRegistry {
|
||||
sessions: HashMap<VmSessionId, VmSession>,
|
||||
}
|
||||
|
||||
impl VmSessionRegistry {
|
||||
pub fn new() -> Self {
|
||||
Self { sessions: HashMap::new() }
|
||||
}
|
||||
|
||||
pub fn create_for_task(
|
||||
&mut self,
|
||||
task: &Task,
|
||||
process: &Process,
|
||||
app_version: impl Into<String>,
|
||||
cap_config: Option<CertificationConfig>,
|
||||
logs_count: Arc<AtomicU32>,
|
||||
) -> Result<VmSessionId, VmSessionError> {
|
||||
if task.process_id != process.id {
|
||||
return Err(VmSessionError::TaskProcessMismatch {
|
||||
task_id: task.id,
|
||||
task_process: task.process_id,
|
||||
process_id: process.id,
|
||||
});
|
||||
}
|
||||
|
||||
let app_mode = app_mode_for_task_and_process(task, process)?;
|
||||
let id = VmSessionId(task.id);
|
||||
if self.sessions.contains_key(&id) {
|
||||
return Err(VmSessionError::SessionAlreadyExists(task.id));
|
||||
}
|
||||
|
||||
self.sessions.insert(
|
||||
id,
|
||||
VmSession::new(task, process, app_mode, app_version, cap_config, logs_count),
|
||||
);
|
||||
Ok(id)
|
||||
}
|
||||
|
||||
pub fn get(&self, id: VmSessionId) -> Option<&VmSession> {
|
||||
self.sessions.get(&id)
|
||||
}
|
||||
|
||||
pub fn get_mut(&mut self, id: VmSessionId) -> Option<&mut VmSession> {
|
||||
self.sessions.get_mut(&id)
|
||||
}
|
||||
|
||||
pub fn for_task(&self, task_id: TaskId) -> Option<&VmSession> {
|
||||
self.get(VmSessionId(task_id))
|
||||
}
|
||||
|
||||
pub fn for_task_mut(&mut self, task_id: TaskId) -> Option<&mut VmSession> {
|
||||
self.get_mut(VmSessionId(task_id))
|
||||
}
|
||||
|
||||
pub fn remove_for_task(&mut self, task_id: TaskId) -> Option<VmSession> {
|
||||
self.sessions.remove(&VmSessionId(task_id))
|
||||
}
|
||||
|
||||
pub fn resident_game(&self) -> Option<&VmSession> {
|
||||
self.sessions.values().find(|session| session.app_mode == AppMode::Game)
|
||||
}
|
||||
|
||||
pub fn resident_game_for_app(&self, app_id: u32) -> Option<&VmSession> {
|
||||
self.sessions
|
||||
.values()
|
||||
.find(|session| session.app_mode == AppMode::Game && session.app_id == app_id)
|
||||
}
|
||||
|
||||
pub fn len(&self) -> usize {
|
||||
self.sessions.len()
|
||||
}
|
||||
|
||||
pub fn is_empty(&self) -> bool {
|
||||
self.sessions.is_empty()
|
||||
}
|
||||
|
||||
pub fn clear(&mut self) {
|
||||
self.sessions.clear();
|
||||
}
|
||||
}
|
||||
|
||||
fn app_mode_for_task_and_process(
|
||||
task: &Task,
|
||||
process: &Process,
|
||||
) -> Result<AppMode, VmSessionError> {
|
||||
match (task.kind, process.kind) {
|
||||
(TaskKind::Game, ProcessKind::VmGame) => Ok(AppMode::Game),
|
||||
(TaskKind::Shell, ProcessKind::VmShell) => Ok(AppMode::Shell),
|
||||
(_, ProcessKind::NativeShell) => Err(VmSessionError::ProcessIsNotVmBacked(process.id)),
|
||||
_ => Err(VmSessionError::TaskKindMismatch {
|
||||
task_id: task.id,
|
||||
task_kind: task.kind,
|
||||
process_kind: process.kind,
|
||||
}),
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::process::Process;
|
||||
use crate::task::Task;
|
||||
|
||||
#[test]
|
||||
fn creates_vm_game_session_for_vm_game_task() {
|
||||
let process = Process::new(ProcessId(1), 42, "Stress", ProcessKind::VmGame);
|
||||
let task = Task::new(TaskId(7), process.id, 42, "Stress", TaskKind::Game);
|
||||
let mut registry = VmSessionRegistry::new();
|
||||
|
||||
let id = registry
|
||||
.create_for_task(&task, &process, "", None, Arc::new(AtomicU32::new(0)))
|
||||
.expect("session should create");
|
||||
let session = registry.get(id).expect("session should exist");
|
||||
|
||||
assert_eq!(session.id, VmSessionId(task.id));
|
||||
assert_eq!(session.task_id, task.id);
|
||||
assert_eq!(session.process_id, process.id);
|
||||
assert_eq!(session.app_id, 42);
|
||||
assert_eq!(session.title, "Stress");
|
||||
assert_eq!(session.app_mode, AppMode::Game);
|
||||
assert_eq!(session.runtime.current_app_id, 0);
|
||||
assert_eq!(session.fs_state, FsState::Unmounted);
|
||||
assert_eq!(session.next_handle, 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn creates_vm_shell_session_for_vm_shell_task() {
|
||||
let process = Process::new(ProcessId(1), 7, "Shell", ProcessKind::VmShell);
|
||||
let task = Task::new(TaskId(3), process.id, 7, "Shell", TaskKind::Shell);
|
||||
let mut registry = VmSessionRegistry::new();
|
||||
|
||||
let id = registry
|
||||
.create_for_task(&task, &process, "1.0", None, Arc::new(AtomicU32::new(0)))
|
||||
.expect("session should create");
|
||||
let session = registry.get(id).expect("session should exist");
|
||||
|
||||
assert_eq!(session.app_mode, AppMode::Shell);
|
||||
assert_eq!(session.app_version, "1.0");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn rejects_native_shell_process() {
|
||||
let process = Process::new(ProcessId(1), 7, "Shell", ProcessKind::NativeShell);
|
||||
let task = Task::new(TaskId(3), process.id, 7, "Shell", TaskKind::Shell);
|
||||
let mut registry = VmSessionRegistry::new();
|
||||
|
||||
assert_eq!(
|
||||
registry.create_for_task(&task, &process, "", None, Arc::new(AtomicU32::new(0))),
|
||||
Err(VmSessionError::ProcessIsNotVmBacked(process.id))
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn finds_resident_game_by_app_id() {
|
||||
let process = Process::new(ProcessId(1), 42, "Stress", ProcessKind::VmGame);
|
||||
let task = Task::new(TaskId(7), process.id, 42, "Stress", TaskKind::Game);
|
||||
let mut registry = VmSessionRegistry::new();
|
||||
registry
|
||||
.create_for_task(&task, &process, "", None, Arc::new(AtomicU32::new(0)))
|
||||
.expect("session should create");
|
||||
|
||||
assert_eq!(
|
||||
registry.resident_game_for_app(42).map(|session| session.task_id),
|
||||
Some(task.id)
|
||||
);
|
||||
assert_eq!(registry.resident_game_for_app(43).map(|session| session.task_id), None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn remove_for_task_removes_only_matching_session() {
|
||||
let game_process = Process::new(ProcessId(1), 42, "Stress", ProcessKind::VmGame);
|
||||
let game_task = Task::new(TaskId(7), game_process.id, 42, "Stress", TaskKind::Game);
|
||||
let shell_process = Process::new(ProcessId(2), 9, "Shell", ProcessKind::VmShell);
|
||||
let shell_task = Task::new(TaskId(8), shell_process.id, 9, "Shell", TaskKind::Shell);
|
||||
let mut registry = VmSessionRegistry::new();
|
||||
|
||||
registry
|
||||
.create_for_task(&game_task, &game_process, "", None, Arc::new(AtomicU32::new(0)))
|
||||
.expect("game session should create");
|
||||
registry
|
||||
.create_for_task(&shell_task, &shell_process, "", None, Arc::new(AtomicU32::new(0)))
|
||||
.expect("shell session should create");
|
||||
|
||||
let removed = registry.remove_for_task(game_task.id).expect("game session should remove");
|
||||
|
||||
assert_eq!(removed.task_id, game_task.id);
|
||||
assert_eq!(registry.for_task(game_task.id).map(|session| session.task_id), None);
|
||||
assert_eq!(
|
||||
registry.for_task(shell_task.id).map(|session| session.task_id),
|
||||
Some(shell_task.id)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn session_runtime_state_is_independent_per_session() {
|
||||
let game_process = Process::new(ProcessId(1), 42, "Stress", ProcessKind::VmGame);
|
||||
let game_task = Task::new(TaskId(7), game_process.id, 42, "Stress", TaskKind::Game);
|
||||
let shell_process = Process::new(ProcessId(2), 9, "Shell", ProcessKind::VmShell);
|
||||
let shell_task = Task::new(TaskId(8), shell_process.id, 9, "Shell", TaskKind::Shell);
|
||||
let mut registry = VmSessionRegistry::new();
|
||||
|
||||
registry
|
||||
.create_for_task(&game_task, &game_process, "", None, Arc::new(AtomicU32::new(0)))
|
||||
.expect("game session should create");
|
||||
registry
|
||||
.create_for_task(&shell_task, &shell_process, "", None, Arc::new(AtomicU32::new(0)))
|
||||
.expect("shell session should create");
|
||||
|
||||
registry
|
||||
.for_task_mut(game_task.id)
|
||||
.expect("game session should exist")
|
||||
.runtime
|
||||
.tick_index = 11;
|
||||
registry
|
||||
.for_task_mut(shell_task.id)
|
||||
.expect("shell session should exist")
|
||||
.runtime
|
||||
.tick_index = 3;
|
||||
registry
|
||||
.for_task_mut(game_task.id)
|
||||
.expect("game session should exist")
|
||||
.open_files
|
||||
.insert(1, "/game.save".to_string());
|
||||
|
||||
assert_eq!(
|
||||
registry.for_task(game_task.id).map(|session| session.runtime.tick_index),
|
||||
Some(11)
|
||||
);
|
||||
assert_eq!(
|
||||
registry.for_task(shell_task.id).map(|session| session.runtime.tick_index),
|
||||
Some(3)
|
||||
);
|
||||
assert!(
|
||||
registry
|
||||
.for_task(shell_task.id)
|
||||
.expect("shell session should exist")
|
||||
.open_files
|
||||
.is_empty()
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -2627,7 +2627,7 @@ mod tests {
|
||||
fn test_loader_hardening_unsupported_version() {
|
||||
let mut vm = VirtualMachine::default();
|
||||
let mut header = vec![0u8; 32];
|
||||
header[0..4].copy_from_slice(b"PBS\0");
|
||||
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
|
||||
header[4..6].copy_from_slice(&1u16.to_le_bytes()); // version 1 (unsupported)
|
||||
|
||||
let res = vm.initialize(header);
|
||||
@@ -2635,16 +2635,16 @@ mod tests {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_loader_hardening_malformed_pbs_v0() {
|
||||
fn test_loader_hardening_malformed_pbx_v0() {
|
||||
let mut vm = VirtualMachine::default();
|
||||
let mut header = vec![0u8; 32];
|
||||
header[0..4].copy_from_slice(b"PBS\0");
|
||||
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
|
||||
header[8..12].copy_from_slice(&1u32.to_le_bytes()); // 1 section claimed but none provided
|
||||
|
||||
let res = vm.initialize(header);
|
||||
match res {
|
||||
Err(VmInitError::ImageLoadFailed(prometeu_bytecode::LoadError::UnexpectedEof)) => {}
|
||||
_ => panic!("Expected PbsV0LoadFailed(UnexpectedEof), got {:?}", res),
|
||||
_ => panic!("Expected PBX v0 load failure UnexpectedEof, got {:?}", res),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -2695,6 +2695,13 @@ mod tests {
|
||||
assert_eq!(vm.pc, 0);
|
||||
assert_eq!(vm.program.rom.len(), 2);
|
||||
assert_eq!(vm.cycles, 0);
|
||||
|
||||
vm.prepare_boot_call();
|
||||
let mut native = MockNative;
|
||||
let mut ctx = HostContext::new(None);
|
||||
let report = vm.run_budget(100, &mut native, &mut ctx).expect("run loaded PBX");
|
||||
assert_eq!(report.reason, LogicalFrameEndingReason::Halted);
|
||||
assert!(vm.is_halted());
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -3084,7 +3091,7 @@ mod tests {
|
||||
fn test_loader_hardening_missing_sysc_section() {
|
||||
let mut vm = VirtualMachine::default();
|
||||
let mut header = vec![0u8; 32];
|
||||
header[0..4].copy_from_slice(b"PBS\0");
|
||||
header[0..4].copy_from_slice(&prometeu_bytecode::PBX_MAGIC);
|
||||
|
||||
let res = vm.initialize(header);
|
||||
|
||||
|
||||
@@ -83,30 +83,32 @@ impl VirtualMachine {
|
||||
self.scheduler = Scheduler::new();
|
||||
self.current_coro = None;
|
||||
|
||||
let program = if program_bytes.starts_with(b"PBS\0") {
|
||||
match prometeu_bytecode::BytecodeLoader::load(&program_bytes) {
|
||||
Ok(mut module) => {
|
||||
patch_module_hostcalls(&mut module, self.capabilities)
|
||||
.map_err(VmInitError::LoaderPatchFailed)?;
|
||||
let program = match prometeu_bytecode::BytecodeLoader::load(&program_bytes) {
|
||||
Ok(mut module) => {
|
||||
patch_module_hostcalls(&mut module, self.capabilities)
|
||||
.map_err(VmInitError::LoaderPatchFailed)?;
|
||||
|
||||
let max_stacks = Verifier::verify(&module.code, &module.functions)
|
||||
.map_err(|e| VmInitError::VerificationFailed(format!("{:?}", e)))?;
|
||||
let max_stacks = Verifier::verify(&module.code, &module.functions)
|
||||
.map_err(|e| VmInitError::VerificationFailed(format!("{:?}", e)))?;
|
||||
|
||||
let mut program = ProgramImage::from(module);
|
||||
let mut functions = program.functions.as_ref().to_vec();
|
||||
for (func, max_stack) in functions.iter_mut().zip(max_stacks) {
|
||||
func.max_stack_slots = max_stack;
|
||||
}
|
||||
program.functions = std::sync::Arc::from(functions);
|
||||
program
|
||||
let mut program = ProgramImage::from(module);
|
||||
let mut functions = program.functions.as_ref().to_vec();
|
||||
for (func, max_stack) in functions.iter_mut().zip(max_stacks) {
|
||||
func.max_stack_slots = max_stack;
|
||||
}
|
||||
Err(prometeu_bytecode::LoadError::InvalidVersion) => {
|
||||
return Err(VmInitError::UnsupportedFormat);
|
||||
}
|
||||
Err(e) => return Err(VmInitError::ImageLoadFailed(e)),
|
||||
program.functions = std::sync::Arc::from(functions);
|
||||
program
|
||||
}
|
||||
} else {
|
||||
return Err(VmInitError::InvalidFormat);
|
||||
Err(prometeu_bytecode::LoadError::InvalidVersion) => {
|
||||
return Err(VmInitError::UnsupportedFormat);
|
||||
}
|
||||
Err(prometeu_bytecode::LoadError::InvalidMagic) => {
|
||||
return Err(VmInitError::InvalidFormat);
|
||||
}
|
||||
Err(prometeu_bytecode::LoadError::UnexpectedEof) if program_bytes.len() < 32 => {
|
||||
return Err(VmInitError::InvalidFormat);
|
||||
}
|
||||
Err(e) => return Err(VmInitError::ImageLoadFailed(e)),
|
||||
};
|
||||
|
||||
let pc = program
|
||||
|
||||
@@ -2,8 +2,8 @@ use prometeu_vm::{VirtualMachine, VmInitError};
|
||||
|
||||
#[test]
|
||||
fn invalid_image_format_is_rejected_before_execution() {
|
||||
// Provide bytes that are not a valid PBS image. The VM must reject it with InvalidFormat.
|
||||
let program_bytes = b"NOT_PBS_IMAGE".to_vec();
|
||||
// Provide bytes that are not a valid PBX image. The VM must reject it with InvalidFormat.
|
||||
let program_bytes = b"NOT_PBX_IMAGE".to_vec();
|
||||
let mut vm = VirtualMachine::default();
|
||||
let result = vm.initialize(program_bytes);
|
||||
assert!(matches!(result, Err(VmInitError::InvalidFormat)));
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
const TARGET_MANIFESTS: &[&str] =
|
||||
&["crates/console/prometeu-bytecode/Cargo.toml", "crates/console/prometeu-vm/Cargo.toml"];
|
||||
|
||||
const FORBIDDEN_DEPENDENCY_FRAGMENTS: &[&str] = &["compiler", "frontend"];
|
||||
|
||||
#[test]
|
||||
fn pbx_and_pvm_crates_must_not_depend_on_compiler_or_frontend_crates() {
|
||||
let workspace_root = find_workspace_root().expect("runtime workspace root");
|
||||
let mut violations = Vec::new();
|
||||
|
||||
for relative_path in TARGET_MANIFESTS {
|
||||
let manifest_path = workspace_root.join(relative_path);
|
||||
let manifest = fs::read_to_string(&manifest_path)
|
||||
.unwrap_or_else(|error| panic!("failed to read {}: {error}", manifest_path.display()));
|
||||
|
||||
for dependency in dependency_names(&manifest) {
|
||||
let normalized = dependency.to_ascii_lowercase();
|
||||
if FORBIDDEN_DEPENDENCY_FRAGMENTS.iter().any(|fragment| normalized.contains(fragment)) {
|
||||
violations.push(format!("{relative_path}: forbidden dependency `{dependency}`"));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
assert!(
|
||||
violations.is_empty(),
|
||||
"PBX/PVM crates must remain independent of compiler and frontend crates:\n{}",
|
||||
violations.join("\n")
|
||||
);
|
||||
}
|
||||
|
||||
fn dependency_names(manifest: &str) -> Vec<&str> {
|
||||
let mut names = Vec::new();
|
||||
let mut in_dependency_section = false;
|
||||
|
||||
for raw_line in manifest.lines() {
|
||||
let line = raw_line.trim();
|
||||
if line.starts_with('[') && line.ends_with(']') {
|
||||
let section = &line[1..line.len() - 1];
|
||||
in_dependency_section = section == "dependencies"
|
||||
|| section == "dev-dependencies"
|
||||
|| section == "build-dependencies"
|
||||
|| section.ends_with(".dependencies")
|
||||
|| section.ends_with(".dev-dependencies")
|
||||
|| section.ends_with(".build-dependencies");
|
||||
continue;
|
||||
}
|
||||
|
||||
if !in_dependency_section || line.is_empty() || line.starts_with('#') {
|
||||
continue;
|
||||
}
|
||||
|
||||
if let Some((name, _)) = line.split_once('=') {
|
||||
names.push(name.trim().trim_matches('"'));
|
||||
}
|
||||
}
|
||||
|
||||
names
|
||||
}
|
||||
|
||||
fn find_workspace_root() -> Option<PathBuf> {
|
||||
let mut cursor = Path::new(env!("CARGO_MANIFEST_DIR")).to_path_buf();
|
||||
loop {
|
||||
let manifest = cursor.join("Cargo.toml");
|
||||
if fs::read_to_string(&manifest).is_ok_and(|contents| contents.contains("[workspace]")) {
|
||||
return Some(cursor);
|
||||
}
|
||||
if !cursor.pop() {
|
||||
return None;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -28,6 +28,8 @@ pub struct HostDebugger {
|
||||
last_telemetry_frame: u64,
|
||||
/// Last fault summary sent to the debugger client.
|
||||
last_fault_summary: Option<String>,
|
||||
/// Debug cartridge metadata captured before the VM session exists.
|
||||
debug_cartridge: Option<HandshakeCartridge>,
|
||||
}
|
||||
|
||||
impl Default for HostDebugger {
|
||||
@@ -46,19 +48,25 @@ impl HostDebugger {
|
||||
last_log_seq: 0,
|
||||
last_telemetry_frame: 0,
|
||||
last_fault_summary: None,
|
||||
debug_cartridge: None,
|
||||
}
|
||||
}
|
||||
|
||||
/// Configures the debugger based on the boot target.
|
||||
/// If debug mode is enabled, it binds to the specified TCP port.
|
||||
pub fn setup_boot_target(&mut self, boot_target: &BootTarget, firmware: &mut Firmware) {
|
||||
pub fn setup_boot_target(&mut self, boot_target: &BootTarget, _firmware: &mut Firmware) {
|
||||
if let BootTarget::Cartridge { path, debug: true, debug_port } = boot_target {
|
||||
self.waiting_for_start = true;
|
||||
|
||||
// Pre-load cartridge metadata so the Handshake message can contain
|
||||
// valid information about the App being debugged.
|
||||
// valid information before the VM session is created.
|
||||
if let Ok(cartridge) = CartridgeLoader::load(path) {
|
||||
let _ = firmware.os.vm().initialize(&mut firmware.vm, &cartridge);
|
||||
self.debug_cartridge = Some(HandshakeCartridge {
|
||||
app_id: cartridge.app_id,
|
||||
title: cartridge.title,
|
||||
app_version: cartridge.app_version,
|
||||
app_mode: cartridge.app_mode,
|
||||
});
|
||||
}
|
||||
|
||||
match TcpListener::bind(format!("127.0.0.1:{}", debug_port)) {
|
||||
@@ -116,12 +124,7 @@ impl HostDebugger {
|
||||
let handshake = DebugResponse::Handshake {
|
||||
protocol_version: DEVTOOLS_PROTOCOL_VERSION,
|
||||
runtime_version: "0.1".to_string(),
|
||||
cartridge: HandshakeCartridge {
|
||||
app_id: firmware.os.vm().current_app_id(),
|
||||
title: firmware.os.vm().current_cartridge_title(),
|
||||
app_version: firmware.os.vm().current_cartridge_app_version(),
|
||||
app_mode: firmware.os.vm().current_cartridge_app_mode(),
|
||||
},
|
||||
cartridge: self.handshake_cartridge(firmware),
|
||||
};
|
||||
self.send_response(handshake);
|
||||
} else {
|
||||
@@ -201,7 +204,7 @@ impl HostDebugger {
|
||||
DebugCommand::Step => {
|
||||
// Execute exactly one instruction and keep paused.
|
||||
firmware.os.vm().set_paused(true);
|
||||
let _ = firmware.os.vm().debug_step_instruction(&mut firmware.vm, platform);
|
||||
let _ = firmware.os.vm().debug_step_active_session(platform);
|
||||
}
|
||||
DebugCommand::StepFrame => {
|
||||
// Execute until the end of the current logical frame.
|
||||
@@ -210,10 +213,10 @@ impl HostDebugger {
|
||||
}
|
||||
DebugCommand::GetState => {
|
||||
// Return detailed VM register and stack state.
|
||||
let stack_top = firmware.vm.operand_stack_top(10);
|
||||
let stack_top = firmware.os.vm().active_operand_stack_top(10);
|
||||
|
||||
let resp = DebugResponse::GetState {
|
||||
pc: firmware.vm.pc(),
|
||||
pc: firmware.os.vm().active_pc().unwrap_or(0),
|
||||
stack_top,
|
||||
frame_index: firmware.os.vm().logical_frame_index(),
|
||||
app_id: firmware.os.vm().current_app_id(),
|
||||
@@ -221,18 +224,37 @@ impl HostDebugger {
|
||||
self.send_response(resp);
|
||||
}
|
||||
DebugCommand::SetBreakpoint { pc } => {
|
||||
firmware.vm.insert_breakpoint(pc);
|
||||
let _ = firmware.os.vm().insert_active_breakpoint(pc);
|
||||
}
|
||||
DebugCommand::ListBreakpoints => {
|
||||
let pcs = firmware.vm.breakpoints_list();
|
||||
let pcs = firmware.os.vm().active_breakpoints_list();
|
||||
self.send_response(DebugResponse::Breakpoints { pcs });
|
||||
}
|
||||
DebugCommand::ClearBreakpoint { pc } => {
|
||||
firmware.vm.remove_breakpoint(pc);
|
||||
let _ = firmware.os.vm().remove_active_breakpoint(pc);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn handshake_cartridge(&self, firmware: &mut Firmware) -> HandshakeCartridge {
|
||||
let app_id = firmware.os.vm().current_app_id();
|
||||
if app_id != 0 {
|
||||
return HandshakeCartridge {
|
||||
app_id,
|
||||
title: firmware.os.vm().current_cartridge_title(),
|
||||
app_version: firmware.os.vm().current_cartridge_app_version(),
|
||||
app_mode: firmware.os.vm().current_cartridge_app_mode(),
|
||||
};
|
||||
}
|
||||
|
||||
self.debug_cartridge.clone().unwrap_or_else(|| HandshakeCartridge {
|
||||
app_id,
|
||||
title: firmware.os.vm().current_cartridge_title(),
|
||||
app_version: firmware.os.vm().current_cartridge_app_version(),
|
||||
app_mode: firmware.os.vm().current_cartridge_app_mode(),
|
||||
})
|
||||
}
|
||||
|
||||
pub(crate) fn cert_event_from_snapshot(
|
||||
tag: u16,
|
||||
telemetry: TelemetryFrame,
|
||||
@@ -315,7 +337,7 @@ impl HostDebugger {
|
||||
// Map specific internal log tags to protocol events.
|
||||
if event.tag == 0xDEB1 {
|
||||
self.send_event(DebugEvent::BreakpointHit {
|
||||
pc: firmware.vm.pc(),
|
||||
pc: firmware.os.vm().active_pc().unwrap_or(0),
|
||||
frame_index: firmware.os.vm().logical_frame_index(),
|
||||
});
|
||||
}
|
||||
@@ -409,6 +431,52 @@ mod tests {
|
||||
assert!(firmware.os.vm().debug_step_requested());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn breakpoint_commands_mutate_active_vm_session() {
|
||||
let mut debugger = HostDebugger::new();
|
||||
let mut firmware = Firmware::new(None);
|
||||
let mut platform = TestPlatform::new();
|
||||
let task_id = firmware
|
||||
.os
|
||||
.sessions()
|
||||
.try_create_vm_game_task(42, "Sector Crawl")
|
||||
.expect("debugger test should create a game session");
|
||||
|
||||
debugger.handle_command(
|
||||
DebugCommand::SetBreakpoint { pc: 123 },
|
||||
&mut firmware,
|
||||
&mut platform,
|
||||
);
|
||||
|
||||
assert_eq!(
|
||||
firmware
|
||||
.os
|
||||
.sessions()
|
||||
.vm_session_for_task(task_id)
|
||||
.expect("game VM session should exist")
|
||||
.vm
|
||||
.breakpoints_list(),
|
||||
vec![123]
|
||||
);
|
||||
|
||||
debugger.handle_command(
|
||||
DebugCommand::ClearBreakpoint { pc: 123 },
|
||||
&mut firmware,
|
||||
&mut platform,
|
||||
);
|
||||
|
||||
assert!(
|
||||
firmware
|
||||
.os
|
||||
.sessions()
|
||||
.vm_session_for_task(task_id)
|
||||
.expect("game VM session should exist")
|
||||
.vm
|
||||
.breakpoints_list()
|
||||
.is_empty()
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn handle_command_start_leaves_waiting_for_start_mode() {
|
||||
let mut debugger = HostDebugger::new();
|
||||
|
||||
@@ -43,9 +43,27 @@ impl FbViewport {
|
||||
|
||||
pub struct HostInputHandler {
|
||||
pub signals: InputSignals,
|
||||
system_controls: HostSystemControls,
|
||||
display_size: (usize, usize),
|
||||
}
|
||||
|
||||
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq)]
|
||||
pub struct HostSystemControls {
|
||||
home_requested: bool,
|
||||
}
|
||||
|
||||
impl HostSystemControls {
|
||||
pub fn request_home(&mut self) {
|
||||
self.home_requested = true;
|
||||
}
|
||||
|
||||
pub fn take_home_requested(&mut self) -> bool {
|
||||
let requested = self.home_requested;
|
||||
self.home_requested = false;
|
||||
requested
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for HostInputHandler {
|
||||
fn default() -> Self {
|
||||
Self::new((480, 270))
|
||||
@@ -54,35 +72,51 @@ impl Default for HostInputHandler {
|
||||
|
||||
impl HostInputHandler {
|
||||
pub fn new(display_size: (usize, usize)) -> Self {
|
||||
Self { signals: InputSignals::default(), display_size }
|
||||
Self {
|
||||
signals: InputSignals::default(),
|
||||
system_controls: HostSystemControls::default(),
|
||||
display_size,
|
||||
}
|
||||
}
|
||||
|
||||
pub fn take_home_requested(&mut self) -> bool {
|
||||
self.system_controls.take_home_requested()
|
||||
}
|
||||
|
||||
pub fn clear_guest_signals(&mut self) {
|
||||
self.signals = InputSignals::default();
|
||||
}
|
||||
|
||||
pub fn handle_key_code(&mut self, code: KeyCode, state: ElementState) {
|
||||
let is_down = state == ElementState::Pressed;
|
||||
|
||||
match code {
|
||||
KeyCode::Escape | KeyCode::Home if is_down => self.system_controls.request_home(),
|
||||
|
||||
KeyCode::ArrowUp => self.signals.up_signal = is_down,
|
||||
KeyCode::ArrowDown => self.signals.down_signal = is_down,
|
||||
KeyCode::ArrowLeft => self.signals.left_signal = is_down,
|
||||
KeyCode::ArrowRight => self.signals.right_signal = is_down,
|
||||
|
||||
KeyCode::KeyA => self.signals.a_signal = is_down,
|
||||
KeyCode::KeyD => self.signals.b_signal = is_down,
|
||||
KeyCode::KeyW => self.signals.x_signal = is_down,
|
||||
KeyCode::KeyS => self.signals.y_signal = is_down,
|
||||
KeyCode::KeyQ => self.signals.l_signal = is_down,
|
||||
KeyCode::KeyE => self.signals.r_signal = is_down,
|
||||
|
||||
KeyCode::KeyZ => self.signals.start_signal = is_down,
|
||||
KeyCode::ShiftLeft | KeyCode::ShiftRight => self.signals.select_signal = is_down,
|
||||
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
|
||||
pub fn handle_event(&mut self, event: &WindowEvent, window: &Window) {
|
||||
match event {
|
||||
WindowEvent::KeyboardInput { event, .. } => {
|
||||
if let PhysicalKey::Code(code) = event.physical_key {
|
||||
let is_down = event.state == ElementState::Pressed;
|
||||
|
||||
match code {
|
||||
KeyCode::ArrowUp => self.signals.up_signal = is_down,
|
||||
KeyCode::ArrowDown => self.signals.down_signal = is_down,
|
||||
KeyCode::ArrowLeft => self.signals.left_signal = is_down,
|
||||
KeyCode::ArrowRight => self.signals.right_signal = is_down,
|
||||
|
||||
KeyCode::KeyA => self.signals.a_signal = is_down,
|
||||
KeyCode::KeyD => self.signals.b_signal = is_down,
|
||||
KeyCode::KeyW => self.signals.x_signal = is_down,
|
||||
KeyCode::KeyS => self.signals.y_signal = is_down,
|
||||
KeyCode::KeyQ => self.signals.l_signal = is_down,
|
||||
KeyCode::KeyE => self.signals.r_signal = is_down,
|
||||
|
||||
KeyCode::KeyZ => self.signals.start_signal = is_down,
|
||||
KeyCode::ShiftLeft | KeyCode::ShiftRight => {
|
||||
self.signals.select_signal = is_down
|
||||
}
|
||||
|
||||
_ => {}
|
||||
}
|
||||
self.handle_key_code(code, event.state);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -134,3 +168,81 @@ impl HostInputHandler {
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
fn assert_no_pad_signal(signals: InputSignals) {
|
||||
assert!(!signals.up_signal);
|
||||
assert!(!signals.down_signal);
|
||||
assert!(!signals.left_signal);
|
||||
assert!(!signals.right_signal);
|
||||
assert!(!signals.a_signal);
|
||||
assert!(!signals.b_signal);
|
||||
assert!(!signals.x_signal);
|
||||
assert!(!signals.y_signal);
|
||||
assert!(!signals.l_signal);
|
||||
assert!(!signals.r_signal);
|
||||
assert!(!signals.start_signal);
|
||||
assert!(!signals.select_signal);
|
||||
assert!(!signals.f_signal);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn escape_requests_home_without_mutating_guest_pad() {
|
||||
let mut input = HostInputHandler::default();
|
||||
|
||||
input.handle_key_code(KeyCode::Escape, ElementState::Pressed);
|
||||
|
||||
assert!(input.take_home_requested());
|
||||
assert!(!input.take_home_requested());
|
||||
assert_no_pad_signal(input.signals);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn physical_home_requests_home_without_mutating_guest_pad() {
|
||||
let mut input = HostInputHandler::default();
|
||||
|
||||
input.handle_key_code(KeyCode::Home, ElementState::Pressed);
|
||||
|
||||
assert!(input.take_home_requested());
|
||||
assert_no_pad_signal(input.signals);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn home_release_does_not_emit_a_new_home_request() {
|
||||
let mut input = HostInputHandler::default();
|
||||
|
||||
input.handle_key_code(KeyCode::Home, ElementState::Released);
|
||||
|
||||
assert!(!input.take_home_requested());
|
||||
assert_no_pad_signal(input.signals);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn existing_keyboard_pad_mapping_is_preserved() {
|
||||
let mut input = HostInputHandler::default();
|
||||
|
||||
input.handle_key_code(KeyCode::KeyZ, ElementState::Pressed);
|
||||
input.handle_key_code(KeyCode::ShiftLeft, ElementState::Pressed);
|
||||
input.handle_key_code(KeyCode::ArrowUp, ElementState::Pressed);
|
||||
|
||||
assert!(input.signals.start_signal);
|
||||
assert!(input.signals.select_signal);
|
||||
assert!(input.signals.up_signal);
|
||||
assert!(!input.take_home_requested());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn clearing_guest_signals_preserves_system_home_control() {
|
||||
let mut input = HostInputHandler::default();
|
||||
|
||||
input.handle_key_code(KeyCode::ArrowUp, ElementState::Pressed);
|
||||
input.handle_key_code(KeyCode::Escape, ElementState::Pressed);
|
||||
input.clear_guest_signals();
|
||||
|
||||
assert_no_pad_signal(input.signals);
|
||||
assert!(input.take_home_requested());
|
||||
}
|
||||
}
|
||||
|
||||
@@ -33,6 +33,10 @@ struct Cli {
|
||||
#[arg(long, value_name = "PATH")]
|
||||
fs_root: Option<String>,
|
||||
|
||||
/// Root directory for local game cartridge discovery
|
||||
#[arg(long, value_name = "PATH")]
|
||||
games_root: Option<String>,
|
||||
|
||||
/// Path to the capability configuration file
|
||||
#[arg(long, value_name = "PATH")]
|
||||
cap: Option<String>,
|
||||
@@ -55,6 +59,9 @@ pub fn run() -> Result<(), Box<dyn std::error::Error>> {
|
||||
let event_loop = EventLoop::new()?;
|
||||
|
||||
let mut runner = HostRunner::new(fs_root, cap_config);
|
||||
if let Some(games_root) = cli.games_root {
|
||||
runner.set_games_root(games_root);
|
||||
}
|
||||
runner.set_boot_target(boot_target);
|
||||
|
||||
event_loop.run_app(&mut runner)?;
|
||||
|
||||
@@ -10,9 +10,9 @@ use pixels::{Pixels, PixelsBuilder, SurfaceTexture};
|
||||
use prometeu_drivers::hardware::Hardware;
|
||||
use prometeu_drivers::{AudioCommand, LocalFramebufferRenderBackend, MemoryBanks};
|
||||
use prometeu_firmware::{BootTarget, Firmware, FirmwareState};
|
||||
use prometeu_hal::RuntimePlatform;
|
||||
use prometeu_hal::telemetry::CertificationConfig;
|
||||
use prometeu_system::{LatestRenderFrameStore, RenderWorkerConfig};
|
||||
use prometeu_hal::{OwnedRgba8888Frame, RenderOwnership, RuntimePlatform};
|
||||
use prometeu_system::{LatestRenderFrameStore, RenderWorkerConfig, discover_games_root};
|
||||
use std::sync::Arc;
|
||||
use std::time::{Duration, Instant};
|
||||
use winit::application::ApplicationHandler;
|
||||
@@ -26,16 +26,22 @@ const IDLE_HOST_POLL_DT: Duration = Duration::from_millis(100);
|
||||
|
||||
#[derive(Debug, Clone)]
|
||||
struct PresentationState {
|
||||
latest_published_frame: u64,
|
||||
last_presented_frame: Option<u64>,
|
||||
latest_published_frame: Option<PresentationFrameMarker>,
|
||||
last_presented_frame: Option<PresentationFrameMarker>,
|
||||
host_invalidated: bool,
|
||||
redraw_requested: bool,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
struct PresentationFrameMarker {
|
||||
ownership: RenderOwnership,
|
||||
frame_id: u64,
|
||||
}
|
||||
|
||||
impl Default for PresentationState {
|
||||
fn default() -> Self {
|
||||
Self {
|
||||
latest_published_frame: 0,
|
||||
latest_published_frame: None,
|
||||
last_presented_frame: None,
|
||||
host_invalidated: true,
|
||||
redraw_requested: false,
|
||||
@@ -44,9 +50,10 @@ impl Default for PresentationState {
|
||||
}
|
||||
|
||||
impl PresentationState {
|
||||
fn note_published_frame(&mut self, frame_index: u64) {
|
||||
if frame_index > self.latest_published_frame {
|
||||
self.latest_published_frame = frame_index;
|
||||
fn note_published_frame(&mut self, ownership: RenderOwnership, frame_id: u64) {
|
||||
let marker = PresentationFrameMarker { ownership, frame_id };
|
||||
if self.latest_published_frame != Some(marker) {
|
||||
self.latest_published_frame = Some(marker);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -55,7 +62,7 @@ impl PresentationState {
|
||||
}
|
||||
|
||||
fn needs_redraw(&self) -> bool {
|
||||
self.host_invalidated || self.last_presented_frame != Some(self.latest_published_frame)
|
||||
self.host_invalidated || self.last_presented_frame != self.latest_published_frame
|
||||
}
|
||||
|
||||
fn should_request_redraw(&mut self) -> bool {
|
||||
@@ -70,7 +77,7 @@ impl PresentationState {
|
||||
fn mark_presented(&mut self) {
|
||||
self.redraw_requested = false;
|
||||
self.host_invalidated = false;
|
||||
self.last_presented_frame = Some(self.latest_published_frame);
|
||||
self.last_presented_frame = self.latest_published_frame;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -88,8 +95,12 @@ fn desired_control_flow(
|
||||
}
|
||||
}
|
||||
|
||||
fn should_present_worker_frame(state: &FirmwareState) -> bool {
|
||||
matches!(state, FirmwareState::GameRunning(_))
|
||||
fn should_present_worker_frame(
|
||||
state: &FirmwareState,
|
||||
frame: &OwnedRgba8888Frame,
|
||||
active_ownership: RenderOwnership,
|
||||
) -> bool {
|
||||
matches!(state, FirmwareState::GameRunning(_)) && frame.ownership == active_ownership
|
||||
}
|
||||
|
||||
/// The Desktop implementation of the PROMETEU Runtime.
|
||||
@@ -151,6 +162,18 @@ impl HostRunner {
|
||||
self.debugger.setup_boot_target(&boot_target, &mut self.firmware);
|
||||
}
|
||||
|
||||
pub(crate) fn set_games_root(&mut self, games_root: String) {
|
||||
let library = discover_games_root(&games_root);
|
||||
for diagnostic in library.diagnostics() {
|
||||
eprintln!(
|
||||
"games-root: omitted candidate {}: {:?}",
|
||||
diagnostic.path.display(),
|
||||
diagnostic.reason
|
||||
);
|
||||
}
|
||||
self.firmware.hub.set_game_library(library);
|
||||
}
|
||||
|
||||
/// Creates a new desktop runner instance.
|
||||
pub(crate) fn new(fs_root: Option<String>, cap_config: Option<CertificationConfig>) -> Self {
|
||||
let target_fps = 60;
|
||||
@@ -300,8 +323,13 @@ impl ApplicationHandler for HostRunner {
|
||||
{
|
||||
let frame = pixels.frame_mut();
|
||||
|
||||
if should_present_worker_frame(&self.firmware.state)
|
||||
&& let Some(worker_frame) = self.render_frame_store.latest_frame()
|
||||
let active_ownership = self.firmware.os.vm().active_render_ownership();
|
||||
if let Some(worker_frame) = self.render_frame_store.latest_frame()
|
||||
&& should_present_worker_frame(
|
||||
&self.firmware.state,
|
||||
&worker_frame,
|
||||
active_ownership,
|
||||
)
|
||||
{
|
||||
self.firmware
|
||||
.os
|
||||
@@ -360,6 +388,13 @@ impl ApplicationHandler for HostRunner {
|
||||
self.firmware.os.fs().mount(Box::new(backend));
|
||||
}
|
||||
|
||||
if self.input.take_home_requested() {
|
||||
self.input.clear_guest_signals();
|
||||
self.firmware.request_home_from_host();
|
||||
self.invalidate_host_surface();
|
||||
self.request_redraw_if_needed();
|
||||
}
|
||||
|
||||
// 3. Timing Management (The heart of determinism).
|
||||
// We measure the elapsed time since the last iteration and add it to an
|
||||
// accumulator. We then execute exactly as many 60Hz slices as the
|
||||
@@ -387,7 +422,10 @@ impl ApplicationHandler for HostRunner {
|
||||
// Sync pause state with audio.
|
||||
// We do this AFTER firmware.tick to avoid MasterPause/Resume commands
|
||||
// being cleared by the OS if a new logical frame starts in this tick.
|
||||
let is_paused = self.firmware.os.vm().paused() || self.debugger.waiting_for_start;
|
||||
let lifecycle_audio_paused = self.firmware.game_lifecycle_audio_paused();
|
||||
let is_paused = lifecycle_audio_paused
|
||||
|| self.firmware.os.vm().paused()
|
||||
|| self.debugger.waiting_for_start;
|
||||
if is_paused != self.last_paused_state {
|
||||
self.last_paused_state = is_paused;
|
||||
let cmd =
|
||||
@@ -402,12 +440,15 @@ impl ApplicationHandler for HostRunner {
|
||||
self.stats.record_frame();
|
||||
}
|
||||
|
||||
if should_present_worker_frame(&self.firmware.state)
|
||||
&& let Some(worker_frame) = self.render_frame_store.latest_frame()
|
||||
let active_ownership = self.firmware.os.vm().active_render_ownership();
|
||||
if let Some(worker_frame) = self.render_frame_store.latest_frame()
|
||||
&& should_present_worker_frame(&self.firmware.state, &worker_frame, active_ownership)
|
||||
{
|
||||
self.presentation.note_published_frame(worker_frame.frame_id.get());
|
||||
self.presentation
|
||||
.note_published_frame(worker_frame.ownership, worker_frame.frame_id.get());
|
||||
} else {
|
||||
self.presentation.note_published_frame(self.firmware.os.frame_index());
|
||||
self.presentation
|
||||
.note_published_frame(active_ownership, self.firmware.os.frame_index());
|
||||
}
|
||||
|
||||
if was_debugger_connected != self.debugger.stream.is_some()
|
||||
@@ -473,14 +514,37 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn presentation_state_requests_redraw_for_new_frame_publication() {
|
||||
let ownership = RenderOwnership::new(1, AppMode::Game, 1);
|
||||
let mut state = PresentationState::default();
|
||||
state.mark_presented();
|
||||
|
||||
state.note_published_frame(1);
|
||||
state.note_published_frame(ownership, 1);
|
||||
|
||||
assert!(state.should_request_redraw());
|
||||
state.mark_presented();
|
||||
assert_eq!(state.last_presented_frame, Some(1));
|
||||
assert_eq!(
|
||||
state.last_presented_frame,
|
||||
Some(PresentationFrameMarker { ownership, frame_id: 1 })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn presentation_state_requests_redraw_when_ownership_changes_with_lower_frame_id() {
|
||||
let first = RenderOwnership::new(3, AppMode::Game, 1);
|
||||
let next = RenderOwnership::new(4, AppMode::Game, 2);
|
||||
let mut state = PresentationState::default();
|
||||
|
||||
state.note_published_frame(first, 120);
|
||||
state.mark_presented();
|
||||
|
||||
state.note_published_frame(next, 0);
|
||||
|
||||
assert!(state.should_request_redraw());
|
||||
state.mark_presented();
|
||||
assert_eq!(
|
||||
state.last_presented_frame,
|
||||
Some(PresentationFrameMarker { ownership: next, frame_id: 0 })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -524,14 +588,39 @@ mod tests {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn worker_frame_presentation_is_game_only() {
|
||||
assert!(should_present_worker_frame(&FirmwareState::GameRunning(GameRunningStep::new(
|
||||
TaskId(1),
|
||||
))));
|
||||
assert!(!should_present_worker_frame(&FirmwareState::ShellRunning(ShellRunningStep::new(
|
||||
TaskId(2)
|
||||
),)));
|
||||
assert!(!should_present_worker_frame(&FirmwareState::HubHome(HubHomeStep)));
|
||||
fn worker_frame_presentation_requires_game_state_and_current_ownership() {
|
||||
let active = RenderOwnership::new(3, AppMode::Game, 1);
|
||||
let current = OwnedRgba8888Frame::packed(FrameId::new(9), active, 1, 1, vec![0xFF00FFFF])
|
||||
.expect("test frame");
|
||||
let stale = OwnedRgba8888Frame::packed(
|
||||
FrameId::new(8),
|
||||
RenderOwnership::new(2, AppMode::Game, 1),
|
||||
1,
|
||||
1,
|
||||
vec![0xFF00FFFF],
|
||||
)
|
||||
.expect("test frame");
|
||||
|
||||
assert!(should_present_worker_frame(
|
||||
&FirmwareState::GameRunning(GameRunningStep::new(TaskId(1))),
|
||||
¤t,
|
||||
active,
|
||||
));
|
||||
assert!(!should_present_worker_frame(
|
||||
&FirmwareState::GameRunning(GameRunningStep::new(TaskId(1),)),
|
||||
&stale,
|
||||
active,
|
||||
));
|
||||
assert!(!should_present_worker_frame(
|
||||
&FirmwareState::ShellRunning(ShellRunningStep::new(TaskId(2))),
|
||||
¤t,
|
||||
active,
|
||||
));
|
||||
assert!(!should_present_worker_frame(
|
||||
&FirmwareState::HubHome(HubHomeStep),
|
||||
¤t,
|
||||
active,
|
||||
));
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -551,11 +640,14 @@ mod tests {
|
||||
let mut presentation = PresentationState::default();
|
||||
presentation.mark_presented();
|
||||
let published = store.latest_frame().expect("published frame");
|
||||
presentation.note_published_frame(published.frame_id.get());
|
||||
presentation.note_published_frame(published.ownership, published.frame_id.get());
|
||||
|
||||
assert!(presentation.should_request_redraw());
|
||||
presentation.mark_presented();
|
||||
assert_eq!(presentation.last_presented_frame, Some(9));
|
||||
assert_eq!(
|
||||
presentation.last_presented_frame,
|
||||
Some(PresentationFrameMarker { ownership: published.ownership, frame_id: 9 })
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
[package]
|
||||
name = "pbxgen-dummy-boy"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
|
||||
[dependencies]
|
||||
anyhow = "1"
|
||||
prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
|
||||
prometeu-hal = { path = "../../console/prometeu-hal" }
|
||||
|
||||
[dev-dependencies]
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,147 @@
|
||||
use anyhow::Result;
|
||||
use prometeu_bytecode::assembler::assemble;
|
||||
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl};
|
||||
use prometeu_hal::color::Color;
|
||||
use std::fs;
|
||||
use std::path::PathBuf;
|
||||
|
||||
const APP_ID: u32 = 2;
|
||||
const TITLE: &str = "Dummy Boy";
|
||||
const APP_VERSION: &str = "0.1.0";
|
||||
|
||||
fn asm(s: &str) -> Vec<u8> {
|
||||
assemble(s).expect("assemble")
|
||||
}
|
||||
|
||||
pub fn generate() -> Result<()> {
|
||||
let out_dir = cartridge_dir();
|
||||
fs::create_dir_all(&out_dir)?;
|
||||
fs::write(out_dir.join("program.pbx"), build_program())?;
|
||||
fs::write(out_dir.join("manifest.json"), manifest_json())?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn build_program() -> Vec<u8> {
|
||||
let mut rom = Vec::new();
|
||||
|
||||
rom.extend(asm("GET_GLOBAL 0\nPUSH_I32 1\nADD\nSET_GLOBAL 0"));
|
||||
rom.extend(asm(&format!("PUSH_I64 {}\nHOSTCALL 0", Color::BLACK.raw())));
|
||||
|
||||
rom.extend(asm("GET_GLOBAL 0\nPUSH_I32 3\nMOD\nPUSH_I32 0\nEQ"));
|
||||
let jump_to_green_case_offset = rom.len() + 2;
|
||||
rom.extend(asm("JMP_IF_FALSE 0"));
|
||||
rom.extend(asm(&format!("PUSH_I64 {}\nSET_LOCAL 0", Color::RED.raw())));
|
||||
let jump_to_draw_after_red_offset = rom.len() + 2;
|
||||
rom.extend(asm("JMP 0"));
|
||||
|
||||
let green_case = rom.len() as u32;
|
||||
rom.extend(asm("GET_GLOBAL 0\nPUSH_I32 3\nMOD\nPUSH_I32 1\nEQ"));
|
||||
let jump_to_blue_case_offset = rom.len() + 2;
|
||||
rom.extend(asm("JMP_IF_FALSE 0"));
|
||||
rom.extend(asm(&format!("PUSH_I64 {}\nSET_LOCAL 0", Color::GREEN.raw())));
|
||||
let jump_to_draw_after_green_offset = rom.len() + 2;
|
||||
rom.extend(asm("JMP 0"));
|
||||
|
||||
let blue_case = rom.len() as u32;
|
||||
rom.extend(asm(&format!("PUSH_I64 {}\nSET_LOCAL 0", Color::BLUE.raw())));
|
||||
|
||||
let draw = rom.len() as u32;
|
||||
rom.extend(asm(&format!(
|
||||
"PUSH_I32 180\n\
|
||||
PUSH_I32 75\n\
|
||||
PUSH_I32 120\n\
|
||||
PUSH_I32 120\n\
|
||||
PUSH_I64 {}\n\
|
||||
GET_LOCAL 0\n\
|
||||
HOSTCALL 1\n\
|
||||
FRAME_SYNC\n\
|
||||
RET",
|
||||
Color::WHITE.raw()
|
||||
)));
|
||||
|
||||
patch_jump(&mut rom, jump_to_green_case_offset, green_case);
|
||||
patch_jump(&mut rom, jump_to_draw_after_red_offset, draw);
|
||||
patch_jump(&mut rom, jump_to_blue_case_offset, blue_case);
|
||||
patch_jump(&mut rom, jump_to_draw_after_green_offset, draw);
|
||||
|
||||
BytecodeModule {
|
||||
version: 0,
|
||||
const_pool: vec![],
|
||||
functions: vec![FunctionMeta {
|
||||
code_offset: 0,
|
||||
code_len: rom.len() as u32,
|
||||
param_slots: 0,
|
||||
local_slots: 1,
|
||||
return_slots: 0,
|
||||
max_stack_slots: 8,
|
||||
}],
|
||||
code: rom,
|
||||
debug_info: Some(DebugInfo {
|
||||
pc_to_span: vec![],
|
||||
function_names: vec![(0, "main".into())],
|
||||
}),
|
||||
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
|
||||
syscalls: vec![
|
||||
SyscallDecl {
|
||||
module: "gfx2d".into(),
|
||||
name: "clear".into(),
|
||||
version: 1,
|
||||
arg_slots: 1,
|
||||
ret_slots: 0,
|
||||
},
|
||||
SyscallDecl {
|
||||
module: "gfx2d".into(),
|
||||
name: "draw_square".into(),
|
||||
version: 1,
|
||||
arg_slots: 6,
|
||||
ret_slots: 0,
|
||||
},
|
||||
],
|
||||
}
|
||||
.serialize()
|
||||
}
|
||||
|
||||
pub fn manifest_json() -> Vec<u8> {
|
||||
format!(
|
||||
"{{\n \"magic\": \"PMTU\",\n \"cartridge_version\": 1,\n \"app_id\": {APP_ID},\n \"title\": \"{TITLE}\",\n \"app_version\": \"{APP_VERSION}\",\n \"app_mode\": \"Game\",\n \"capabilities\": [\"gfx2d\"]\n}}\n"
|
||||
)
|
||||
.into_bytes()
|
||||
}
|
||||
|
||||
fn cartridge_dir() -> PathBuf {
|
||||
let mut out_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR"));
|
||||
out_dir.pop();
|
||||
out_dir.pop();
|
||||
out_dir.pop();
|
||||
out_dir.push("test-cartridges");
|
||||
out_dir.push("dummy-boy");
|
||||
out_dir
|
||||
}
|
||||
|
||||
fn patch_jump(buf: &mut [u8], imm_offset: usize, target: u32) {
|
||||
buf[imm_offset..imm_offset + 4].copy_from_slice(&target.to_le_bytes());
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn generated_program_is_pbx_module_with_expected_syscalls() {
|
||||
let bytes = build_program();
|
||||
|
||||
assert!(bytes.starts_with(&prometeu_bytecode::PBX_MAGIC));
|
||||
assert!(bytes.len() > 64);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn manifest_declares_distinct_game_identity() {
|
||||
let manifest: serde_json::Value =
|
||||
serde_json::from_slice(&manifest_json()).expect("manifest should parse");
|
||||
|
||||
assert_eq!(manifest["app_id"], APP_ID);
|
||||
assert_eq!(manifest["title"], TITLE);
|
||||
assert_eq!(manifest["app_mode"], "Game");
|
||||
assert_eq!(manifest["capabilities"], serde_json::json!(["gfx2d"]));
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
use anyhow::Result;
|
||||
|
||||
fn main() -> Result<()> {
|
||||
pbxgen_dummy_boy::generate()
|
||||
}
|
||||
@@ -14,7 +14,7 @@ use prometeu_hal::cartridge::{
|
||||
use prometeu_hal::color::Color;
|
||||
use prometeu_hal::glyph::Glyph;
|
||||
use prometeu_hal::glyph_bank::{
|
||||
TileSize, GLYPH_BANK_COLORS_PER_PALETTE, GLYPH_BANK_PALETTE_COUNT_V1,
|
||||
TileSize, GLYPH_BANK_COLORS_PER_PALETTE, GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||
};
|
||||
use prometeu_hal::scene_bank::SceneBank;
|
||||
use prometeu_hal::scene_layer::{ParallaxFactor, SceneLayer};
|
||||
@@ -275,15 +275,15 @@ fn build_glyph_asset() -> (AssetEntry, Vec<u8>) {
|
||||
bank_type: BankType::GLYPH,
|
||||
offset: 0,
|
||||
size: payload.len() as u64,
|
||||
decoded_size: (8 * 8 + GLYPH_BANK_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4)
|
||||
decoded_size: (8 * 8 + GLYPH_BANK_MAX_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4)
|
||||
as u64,
|
||||
codec: AssetCodec::None,
|
||||
metadata: serde_json::json!({
|
||||
"tile_size": 8,
|
||||
"width": 8,
|
||||
"height": 8,
|
||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
||||
"palette_count": GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_MAX_PALETTE_COUNT_V1
|
||||
}),
|
||||
};
|
||||
|
||||
@@ -292,8 +292,8 @@ fn build_glyph_asset() -> (AssetEntry, Vec<u8>) {
|
||||
|
||||
fn build_palette_bytes() -> Vec<u8> {
|
||||
let mut bytes =
|
||||
Vec::with_capacity(GLYPH_BANK_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4);
|
||||
for palette_id in 0..GLYPH_BANK_PALETTE_COUNT_V1 {
|
||||
Vec::with_capacity(GLYPH_BANK_MAX_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * 4);
|
||||
for palette_id in 0..GLYPH_BANK_MAX_PALETTE_COUNT_V1 {
|
||||
for color_index in 0..GLYPH_BANK_COLORS_PER_PALETTE {
|
||||
let color = if color_index == 1 { stress_color(palette_id) } else { Color::BLACK };
|
||||
bytes.extend_from_slice(&color.raw().to_be_bytes());
|
||||
|
||||
+10
-4
@@ -1,7 +1,9 @@
|
||||
{"type":"meta","next_id":{"DSC":43,"AGD":44,"DEC":35,"PLN":129,"LSN":50,"CLSN":1}}
|
||||
{"type":"meta","next_id":{"DSC":49,"AGD":52,"DEC":43,"PLN":174,"LSN":57,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0044","status":"done","ticket":"hub-suspended-game-kill-affordance","title":"Hub Suspended Game Kill Affordance","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["hub","lifecycle","game","ui"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0054","file":"discussion/lessons/DSC-0044-hub-suspended-game-kill-affordance/LSN-0054-manual-hub-kill-must-share-game-termination-cleanup.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
|
||||
{"type":"discussion","id":"DSC-0043","status":"done","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0053","file":"discussion/lessons/DSC-0043-system-os-cartridge-switch-orchestrator/LSN-0053-game-switching-is-lifecycle-replacement-not-loader-work.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
|
||||
{"type":"discussion","id":"DSC-0039","status":"abandoned","ticket":"render-pipeline-family-and-future-3d","title":"Render Pipeline Family and Future 3D","created_at":"2026-06-04","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","architecture","pipeline"],"agendas":[{"id":"AGD-0039","file":"AGD-0039-render-pipeline-family-and-future-3d.md","status":"abandoned","created_at":"2026-06-04","updated_at":"2026-06-04","_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to close this agenda without a new decision because DSC-0038 already established enough architecture for future extension, and 3D is intentionally deferred."}
|
||||
{"type":"discussion","id":"DSC-0040","status":"done","ticket":"vm-render-parallel-execution-boundary","title":"VM and Render Parallel Execution Boundary","created_at":"2026-06-04","updated_at":"2026-06-06","tags":["runtime","renderer","vm","concurrency","architecture","perf"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0048","file":"discussion/lessons/DSC-0040-vm-render-parallel-execution-boundary/LSN-0048-render-workers-need-a-closed-packet-contract.md","status":"done","created_at":"2026-06-06","updated_at":"2026-06-06"}]}
|
||||
{"type":"discussion","id":"DSC-0041","status":"open","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-06-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[{"id":"AGD-0041","file":"AGD-0041-foreground-stack-game-pause-shell-vm-backed.md","status":"open","created_at":"2026-06-05","updated_at":"2026-06-05"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0041","status":"done","ticket":"foreground-stack-game-pause-shell-vm-backed","title":"Foreground Stack, Game Pause, and VM-Backed Shell Coexistence","created_at":"2026-06-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","shell","game","vm","foreground","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0052","file":"discussion/lessons/DSC-0041-foreground-stack-game-pause-shell-vm-backed/LSN-0052-foreground-ownership-and-vm-session-ownership-are-separate.md","status":"done","created_at":"2026-07-05","updated_at":"2026-07-05"}]}
|
||||
{"type":"discussion","id":"DSC-0042","status":"done","ticket":"real-render-worker-establishment","title":"Real Render Worker Establishment","created_at":"2026-06-06","updated_at":"2026-06-20","tags":["runtime","renderer","worker","concurrency","host","hal","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0049","file":"discussion/lessons/DSC-0042-real-render-worker-establishment/LSN-0049-render-worker-publication-boundary.md","status":"done","created_at":"2026-06-20","updated_at":"2026-06-20"}]}
|
||||
{"type":"discussion","id":"DSC-0038","status":"done","ticket":"render-frame-packet-boundary","title":"Logical Render Pipelines and Command Packets","created_at":"2026-05-25","updated_at":"2026-06-04","tags":["gfx","renderer","runtime","frame-composer","architecture","ui","pipeline"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0047","file":"discussion/lessons/DSC-0038-render-frame-packet-boundary/LSN-0047-typed-render-submissions-preserve-domain-boundaries.md","status":"done","created_at":"2026-06-04","updated_at":"2026-06-04"}]}
|
||||
{"type":"discussion","id":"DSC-0035","status":"done","ticket":"task-owned-shell-windows","title":"Agenda - Task-Owned Shell Windows","created_at":"2026-05-15","updated_at":"2026-05-15","tags":["runtime","os","task","window-manager","shell","lifecycle"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0044","file":"discussion/lessons/DSC-0035-task-owned-shell-windows/LSN-0044-task-window-liveness-belongs-to-the-task.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
|
||||
@@ -13,12 +15,13 @@
|
||||
{"type":"discussion","id":"DSC-0001","status":"done","ticket":"legacy-runtime-learn-import","title":"Import legacy runtime learn into discussion lessons","created_at":"2026-03-27","updated_at":"2026-03-27","tags":["migration","tech-debt"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0001","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0001-prometeu-learn-index.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0002","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0002-historical-asset-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0003","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0003-historical-audio-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0004","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0004-historical-cartridge-boot-protocol-and-manifest-authority.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0005","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0005-historical-game-memcard-slots-surface-and-semantics.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0006","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0006-historical-gfx-status-first-fault-and-return-contract.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0007","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0007-historical-retired-fault-and-input-decisions.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0008","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0009","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0009-mental-model-asset-management.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0010","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0010-mental-model-audio.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0011","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0011-mental-model-gfx.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0012","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0012-mental-model-input.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0013","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0013-mental-model-observability-and-debugging.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0014","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0014-mental-model-portability-and-cross-platform.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0015","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0015-mental-model-save-memory-and-memcard.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0016","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0016-mental-model-status-first-and-fault-thinking.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0017","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0017-mental-model-time-and-cycles.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"},{"id":"LSN-0018","file":"discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0018-mental-model-touch.md","status":"done","created_at":"2026-03-27","updated_at":"2026-03-27"}]}
|
||||
{"type":"discussion","id":"DSC-0002","status":"done","ticket":"runtime-edge-test-plan","title":"Agenda - Runtime Edge Test Plan","created_at":"2026-03-27","updated_at":"2026-04-21","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0037","file":"discussion/lessons/DSC-0002-runtime-edge-test-plan/LSN-0037-domain-gates-must-be-owned-by-the-repository.md","status":"done","created_at":"2026-04-21","updated_at":"2026-04-21"}]}
|
||||
{"type":"discussion","id":"DSC-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"open","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0003","file":"AGD-0003-system-run-cart.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0004","status":"done","ticket":"system-run-cart","title":"Agenda - System Run Cart","created_at":"2026-03-27","updated_at":"2026-07-03","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0051","file":"discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03"}]}
|
||||
{"type":"discussion","id":"DSC-0005","status":"open","ticket":"system-fault-semantics-and-control-surface","title":"Agenda - System Fault Semantics and Control Surface","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0004","file":"AGD-0004-system-fault-semantics-and-control-surface.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0006","status":"open","ticket":"vm-owned-random-service","title":"Agenda - VM-Owned Random Service","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0007","status":"open","ticket":"app-home-filesystem-surface-and-semantics","title":"Agenda - App Home Filesystem Surface and Semantics","created_at":"2026-03-27","updated_at":"2026-03-27","tags":[],"agendas":[{"id":"AGD-0006","file":"AGD-0006-app-home-filesystem-surface-and-semantics.md","status":"open","created_at":"2026-03-27","updated_at":"2026-03-27"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0045","status":"open","ticket":"background-service-audio-execution","title":"Background Service and Audio Execution","created_at":"2026-07-05","updated_at":"2026-07-05","tags":["runtime","os","lifecycle","service","audio","background","architecture"],"agendas":[{"id":"AGD-0048","file":"AGD-0048-background-service-audio-execution.md","status":"open","created_at":"2026-07-05","updated_at":"2026-07-05"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0008","status":"done","ticket":"perf-runtime-telemetry-hot-path","title":"Agenda - [PERF] Runtime Telemetry Hot Path","created_at":"2026-03-27","updated_at":"2026-06-04","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0026","file":"discussion/lessons/DSC-0008-perf-runtime-telemetry-hot-path/LSN-0026-push-based-telemetry-model.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"in_progress","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-06-28","tags":["perf","asset","fs","async","scheduler","runtime"],"agendas":[{"id":"AGD-0008","file":"AGD-0008-perf-async-background-work-lanes-for-assets-and-fs.md","status":"accepted","created_at":"2026-03-27","updated_at":"2026-06-28"}],"decisions":[{"id":"DEC-0034","file":"DEC-0034-async-work-lane-and-asset-backlog-contract.md","status":"accepted","created_at":"2026-06-28","updated_at":"2026-06-28","ref_agenda":"AGD-0008"}],"plans":[{"id":"PLN-0123","file":"PLN-0123-async-work-lane-specification-propagation.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0124","file":"PLN-0124-async-work-lane-runtime-infrastructure.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0125","file":"PLN-0125-asset-backlog-and-stable-slot-handles.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0126","file":"PLN-0126-asset-backlog-public-api-and-status-surface.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0127","file":"PLN-0127-async-lane-memcard-and-fs-integration-boundaries.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]},{"id":"PLN-0128","file":"PLN-0128-async-asset-pipeline-contract-tests-and-telemetry.md","status":"open","created_at":"2026-06-28","updated_at":"2026-06-28","ref_decisions":["DEC-0034"]}],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0009","status":"done","ticket":"perf-async-background-work-lanes-for-assets-and-fs","title":"Agenda - [PERF] Async Background Work Lanes for Assets and FS","created_at":"2026-03-27","updated_at":"2026-07-01","tags":["perf","asset","fs","async","scheduler","runtime"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0050","file":"discussion/lessons/DSC-0009-perf-async-background-work-lanes-for-assets-and-fs/LSN-0050-serial-async-lanes-bound-backlog-complexity.md","status":"done","created_at":"2026-07-01","updated_at":"2026-07-01"}]}
|
||||
{"type":"discussion","id":"DSC-0010","status":"done","ticket":"perf-host-desktop-frame-pacing-and-presentation","title":"Agenda - [PERF] Host Desktop Frame Pacing and Presentation","created_at":"2026-03-27","updated_at":"2026-04-20","tags":[],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0036","file":"discussion/lessons/DSC-0010-perf-host-desktop-frame-pacing-and-presentation/LSN-0036-frame-publication-and-host-invalidation-must-be-separate.md","status":"done","created_at":"2026-04-20","updated_at":"2026-04-20"}]}
|
||||
{"type":"discussion","id":"DSC-0011","status":"abandoned","ticket":"perf-gfx-render-pipeline-and-dirty-regions","title":"Agenda - [PERF] GFX Render Pipeline and Dirty Regions","created_at":"2026-03-27","updated_at":"2026-06-28","tags":[],"agendas":[{"id":"AGD-0010","file":"AGD-0010-perf-gfx-render-pipeline-and-dirty-regions.md","status":"abandoned","created_at":"2026-03-27","updated_at":"2026-06-28","_override_reason":"User explicitly chose to remove this agenda because it no longer applies to the current render scenario; future optimizations can be discussed when needed."}],"decisions":[],"plans":[],"lessons":[],"_override_reason":"User explicitly chose to abandon this discussion because it no longer applies to the current render scenario; future optimizations can be discussed when needed."}
|
||||
{"type":"discussion","id":"DSC-0012","status":"done","ticket":"perf-runtime-introspection-syscalls","title":"Agenda - [PERF] Runtime Introspection Syscalls","created_at":"2026-03-27","updated_at":"2026-04-19","tags":["perf","runtime","syscall","telemetry","debug","asset"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0034","file":"discussion/lessons/DSC-0012-perf-runtime-introspection-syscalls/LSN-0034-host-owned-debug-boundaries.md","status":"done","created_at":"2026-04-19","updated_at":"2026-04-19"}]}
|
||||
@@ -41,3 +44,6 @@
|
||||
{"type":"discussion","id":"DSC-0033","status":"done","ticket":"system-os-service-ownership-and-module-layout","title":"Agenda - SystemOS Service Ownership and Module Layout","created_at":"2026-05-14","updated_at":"2026-05-15","tags":["runtime","os","services","module-layout","vm","window-manager","logging"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0042","file":"discussion/lessons/DSC-0033-system-os-service-ownership-and-module-layout/LSN-0042-systemos-service-ownership-boundary.md","status":"done","created_at":"2026-05-15","updated_at":"2026-05-15"}]}
|
||||
{"type":"discussion","id":"DSC-0036","status":"done","ticket":"prometeu-hub-ui-direction","title":"Agenda - Prometeu Hub UI Direction","created_at":"2026-05-15","updated_at":"2026-05-22","tags":["hub","ui","shell","system-apps","lifecycle","design-system"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0045","file":"discussion/lessons/DSC-0036-prometeu-hub-ui-direction/LSN-0045-hub-ui-slices-should-prove-os-boundaries.md","status":"done","created_at":"2026-05-22","updated_at":"2026-05-22"}]}
|
||||
{"type":"discussion","id":"DSC-0037","status":"done","ticket":"rgba8888-framebuffer-and-pixel-format-direction","title":"Agenda - RGBA8888 Framebuffer and Pixel Format Direction","created_at":"2026-05-22","updated_at":"2026-05-23","tags":["gfx","framebuffer","rgb565","rgba8888","renderer","assets","host","backend"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0046","file":"discussion/lessons/DSC-0037-rgba8888-framebuffer-and-pixel-format-direction/LSN-0046-pixel-format-contracts-must-move-as-one-surface.md","status":"done","created_at":"2026-05-23","updated_at":"2026-05-23"}]}
|
||||
{"type":"discussion","id":"DSC-0046","status":"done","ticket":"runtime-owned-variable-glyph-bank-palette-protocol","title":"Runtime-Owned Variable Glyph Bank Palette Protocol","created_at":"2026-07-14","updated_at":"2026-07-14","tags":["runtime","gfx","assets","glyph-bank","palette-serialization","protocol"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0055","file":"discussion/lessons/DSC-0046-runtime-owned-variable-glyph-bank-palette-protocol/LSN-0055-runtime-owned-asset-protocols-must-align-payload-residency-and-lookup.md","status":"done","created_at":"2026-07-14","updated_at":"2026-07-14"}]}
|
||||
{"type":"discussion","id":"DSC-0047","status":"open","ticket":"portable-host-backend-strategy","title":"Portable Host Backend Strategy","created_at":"2026-07-14","updated_at":"2026-07-14","tags":["host","desktop","portable","sdl","backend","rendering","input","audio","linux","android","handheld"],"agendas":[{"id":"AGD-0050","file":"AGD-0050-portable-host-backend-strategy.md","status":"open","created_at":"2026-07-14","updated_at":"2026-07-14"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"discussion","id":"DSC-0048","status":"done","ticket":"corrigir-identificacao-formato-pbx","title":"Corrigir Identificacao do Formato PBX","created_at":"2026-07-15","updated_at":"2026-07-15","tags":["runtime","bytecode","pbx","loader","format","architecture"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0056","file":"discussion/lessons/DSC-0048-corrigir-identificacao-formato-pbx/LSN-0056-runtime-artifact-identity-must-not-borrow-frontend-names.md","status":"done","created_at":"2026-07-15","updated_at":"2026-07-15"}]}
|
||||
|
||||
+118
@@ -0,0 +1,118 @@
|
||||
---
|
||||
id: LSN-0051
|
||||
ticket: system-run-cart
|
||||
title: Launch Authority Belongs to SystemOS
|
||||
created: 2026-07-03
|
||||
tags: [runtime, systemos, cartridge, launch, abi, home]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The `system.run_cart` workflow resolved two related questions: whether a guest
|
||||
should have an app-callable cartridge launch syscall, and how Home should start
|
||||
games from a local library.
|
||||
|
||||
The final model removes `system.run_cart` from the userland ABI while preserving
|
||||
direct host-controlled cartridge boot. Home launch is restored as a
|
||||
system-owned path: the host may provide `--games-root <dir>`, SystemOS/Home
|
||||
discovers valid Game directory cartridges, and selecting an entry routes through
|
||||
firmware into `LoadCartridge`.
|
||||
|
||||
The important distinction is authority. A launch can be a valid product action
|
||||
without being a guest capability.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Remove Guest Cartridge Launch
|
||||
|
||||
**What:** Prometeu removed `system.run_cart` from the public userland syscall
|
||||
surface, generated guest metadata, and runtime dispatch.
|
||||
|
||||
**Why:** A guest syscall made cartridge launch look like app-owned navigation.
|
||||
That gave userland implied authority over target resolution, lifecycle cleanup,
|
||||
failure policy, and system navigation.
|
||||
|
||||
**Trade-offs:** Obsolete guest code cannot keep a compatibility stub. The
|
||||
runtime instead keeps direct boot as a host/system entrypoint and lets stale
|
||||
guest attempts fail through the invalid syscall path.
|
||||
|
||||
### Preserve Direct Boot Outside The Guest ABI
|
||||
|
||||
**What:** Host, CLI, debugger, tests, and single-game flows continue to boot a
|
||||
selected cartridge directly.
|
||||
|
||||
**Why:** Direct boot is still essential for development, automation, and future
|
||||
single-game distribution. Those flows start with a host-selected target before
|
||||
VM execution, so they do not need a guest syscall.
|
||||
|
||||
**Trade-offs:** The loader remains reusable, but it is not lifecycle
|
||||
orchestration authority. Higher-level transitions must be owned by firmware or
|
||||
SystemOS.
|
||||
|
||||
### Model Home Launch As A System Action
|
||||
|
||||
**What:** `--games-root <dir>` configures a local games library for Home. V1
|
||||
discovery scans immediate child directories, keeps only valid Game cartridges,
|
||||
and exposes enough internal metadata to launch a selected entry.
|
||||
|
||||
**Why:** Home needs a product path for "choose a game and start it", but that
|
||||
action belongs to the system profile. SystemOS can present the library and ask
|
||||
firmware to enter `LoadCartridge` without reintroducing guest-controlled launch.
|
||||
|
||||
**Trade-offs:** V1 intentionally excludes recursive discovery, `.pmc`, non-game
|
||||
apps, rich catalog metadata, return-to-Home, and game-to-game switching. Those
|
||||
need separate lifecycle and orchestration decisions.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
### Authority-Based API Classification
|
||||
|
||||
Before exposing an operation to guest/userland code, classify what authority it
|
||||
implies. If the operation selects another executable target, changes process
|
||||
lifecycle, or controls navigation between system-owned modes, it is probably a
|
||||
SystemOS or firmware action rather than an app syscall.
|
||||
|
||||
### Separate Selection From Loading
|
||||
|
||||
Home owns user selection and presentation. SystemOS owns the launch request.
|
||||
Firmware owns the transition into `LoadCartridge`. The cartridge loader remains
|
||||
the mechanism that validates and materializes a cartridge, not the authority
|
||||
that decides when navigation is allowed.
|
||||
|
||||
### Expandable Internal Catalog Records
|
||||
|
||||
Home can render a small v1 list while the internal entry retains manifest data,
|
||||
title, app id, app version, cartridge path, and discovery metadata. This keeps
|
||||
the UI simple without reducing the model to a display-only DTO.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
### Compatibility Stubs Preserve False Contracts
|
||||
|
||||
A syscall that returns success without doing real lifecycle work is worse than
|
||||
an absent syscall. It teaches callers that the platform supports app-driven
|
||||
launch while hiding that no complete transition happened.
|
||||
|
||||
### A Product Flow Is Not Automatically A Guest API
|
||||
|
||||
"Home can launch a game" and "a guest can launch a cartridge" are different
|
||||
claims. Product behavior should be mapped to the component with the correct
|
||||
authority instead of mirrored into the nearest callable ABI.
|
||||
|
||||
### Generic Library Roots Prematurely Expand Scope
|
||||
|
||||
The first launcher path is a games library, not a marketplace or full app
|
||||
catalog. Shell apps, System apps, packages, icons, search, and recursive layouts
|
||||
carry separate contracts and should not be smuggled into the v1 games-root path.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Cartridge launch is system navigation, not a userland syscall.
|
||||
- Direct boot can remain host-controlled without appearing in guest metadata.
|
||||
- Home launch should emit a system action and let firmware enter
|
||||
`LoadCartridge`.
|
||||
- Loader reuse does not imply loader ownership of lifecycle policy.
|
||||
- Keep v1 discovery narrow: immediate child directory cartridges with
|
||||
`app_mode: Game`.
|
||||
- Preserve internal catalog metadata even when the Home UI renders only a small
|
||||
subset.
|
||||
+100
@@ -0,0 +1,100 @@
|
||||
---
|
||||
id: LSN-0050
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Serial Async Lanes Bound Backlog Complexity
|
||||
created: 2026-07-01
|
||||
tags: [runtime, asset, async, scheduler, telemetry]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The async asset work moved from request-owned worker creation toward a
|
||||
runtime-owned serial lane. The important shift is not just "use a worker
|
||||
thread"; it is the introduction of a third logical execution lane with explicit
|
||||
ownership, priority, cancellation, progress, and telemetry.
|
||||
|
||||
This work followed `DEC-0034` and plans `PLN-0123` through `PLN-0128`. The
|
||||
published model separates:
|
||||
|
||||
- main runtime execution, where guest-visible state is committed;
|
||||
- render worker execution, where closed render packets are consumed;
|
||||
- async IO/decode/persistence work, where one background job is active at a
|
||||
time.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Async Work Lane and Asset Backlog Contract
|
||||
|
||||
**What:** Asset IO/decode and compatible persistence work use a runtime-owned
|
||||
serial async lane. Asset requests are queued by target bank slot, not by
|
||||
unbounded transient request identity.
|
||||
|
||||
**Why:** A serial lane keeps the runtime observable and portable. It preserves
|
||||
the intended hardware mental model while avoiding a desktop-biased thread pool
|
||||
or one OS thread per asset request.
|
||||
|
||||
**Trade-offs:** The lane intentionally sacrifices parallel decode throughput in
|
||||
exchange for bounded state, deterministic ownership, simpler telemetry, and
|
||||
clear priority rules. If future implementations add more physical parallelism,
|
||||
they still need to preserve the logical serial contract where the spec requires
|
||||
it.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
The asset backlog is bounded by target identity. A request targets a concrete
|
||||
bank type and slot. A newer request for the same target supersedes the older
|
||||
pending request, and an older active result is discarded when its generation is
|
||||
no longer current.
|
||||
|
||||
Stable handles observe slots. A handle should not be treated as a worker job or
|
||||
thread token. The durable identity is the bank slot plus request generation:
|
||||
slot state says what is resident; request state says what is queued, active,
|
||||
ready, canceled, superseded, or failed.
|
||||
|
||||
Commit remains a main-lane operation. The background lane may read and decode,
|
||||
but publication into resident runtime state happens at predictable ownership
|
||||
points. This keeps VM execution, render handoff, and frame observation from
|
||||
racing with background mutation.
|
||||
|
||||
Progress and telemetry are closure-oriented. Use integer progress and update
|
||||
expensive aggregate telemetry when jobs close, not inside decode loops. Tests
|
||||
should synchronize on explicit state transitions rather than sleeps.
|
||||
|
||||
Priority is part of the lane contract. Memcard commit/write work can outrank
|
||||
ordinary asset loads, FS write/config work can be represented internally, and
|
||||
non-critical read/list work belongs below asset loads. Public FS semantics
|
||||
remain owned by the filesystem discussion; sharing the lane is not permission
|
||||
to decide the FS API here.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
Do not hide concurrency behind per-request `thread::spawn`. That appears simple
|
||||
locally but loses boundedness, priority, cancellation, and telemetry.
|
||||
|
||||
Do not let a handle mean "the current background job." Handles must survive
|
||||
empty slots, completed work, cancellation, superseding, errors, and already
|
||||
resident fast paths.
|
||||
|
||||
Do not install background results directly from the worker. Decode completion is
|
||||
not the same as publication. Use request generation checks before committing a
|
||||
result.
|
||||
|
||||
Do not turn operational states into traps. Queued, active, canceled,
|
||||
superseded, error, and backend-unavailable outcomes belong in status-first
|
||||
surfaces unless the caller violated the structural ABI.
|
||||
|
||||
Do not reopen FS public API scope while wiring internal async-lane consumers.
|
||||
The lane can support FS-style work without deciding request/poll semantics.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- A runtime async lane is an ownership boundary, not just an implementation
|
||||
thread.
|
||||
- Backlog keying by target slot bounds complexity better than queue length
|
||||
limits exposed to the guest.
|
||||
- Stable slot handles plus request generations prevent stale async results from
|
||||
mutating newer state.
|
||||
- Main-lane commit keeps background IO/decode compatible with deterministic
|
||||
runtime publication.
|
||||
- Telemetry belongs at state transitions and job closure, not inside hot decode
|
||||
loops.
|
||||
+145
@@ -0,0 +1,145 @@
|
||||
---
|
||||
id: LSN-0052
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Foreground Ownership and VM Session Ownership Are Separate
|
||||
created: 2026-07-05
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
# LSN-0052: Foreground Ownership and VM Session Ownership Are Separate
|
||||
|
||||
## Context
|
||||
|
||||
DSC-0041 closed the `Game -> Home/Shell -> same Game` lifecycle for the first
|
||||
runtime implementation that supports both native Shell apps and VM-backed Shell
|
||||
apps. The important architectural shift was not only pausing the Game. The
|
||||
runtime also had to stop treating one firmware-owned VM as the place where all
|
||||
guest execution state lives.
|
||||
|
||||
The final model separates two questions:
|
||||
|
||||
- Who owns the foreground visual/input authority right now?
|
||||
- Which VM-backed process owns a mutable VM execution context?
|
||||
|
||||
Foreground ownership is global SystemOS policy. VM execution state belongs to a
|
||||
session associated with a task/process. A suspended resident Game is not a saved
|
||||
snapshot and not a special global VM. It is a live VM session that is temporarily
|
||||
ineligible for normal foreground ticks, input, frame pacing, and render
|
||||
publication.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Foreground Stack and Game Pause Contract
|
||||
|
||||
**What:** PROMETEU uses a single foreground owner in v1. Hub/Home is the root
|
||||
Shell owner, a Game may remain resident, and one foreground Shell app may run in
|
||||
front of the resident Game. Pressing desktop `Esc` is a host/SystemOS Home
|
||||
request, not guest input.
|
||||
|
||||
**Why:** This preserves console-like navigation without turning the runtime into
|
||||
a general multitasking scheduler. It lets the system pause and suspend a Game,
|
||||
run Hub or Shell, then resume the same Game deterministically.
|
||||
|
||||
**Trade-offs:** The model intentionally rejects multiple resident Games, direct
|
||||
Shell-to-Game return, background execution, and Game-to-Game switching in v1.
|
||||
Those features remain future work, but the lifecycle structure now has a place
|
||||
to add them.
|
||||
|
||||
### VM Session Ownership for VM-Backed Processes
|
||||
|
||||
**What:** VM-backed mutable execution state is owned by VM sessions. A
|
||||
VM-backed Game and a VM-backed Shell never share the same VM, stack, heap, PC,
|
||||
open handles, cartridge identity, or VM-scoped runtime state.
|
||||
|
||||
**Why:** A single firmware-owned VM cannot represent a suspended resident Game
|
||||
and a foreground VM Shell at the same time. Loading the Shell into that global
|
||||
VM would overwrite the Game context that the lifecycle model says is resident.
|
||||
|
||||
**Trade-offs:** Session ownership is more explicit than one global VM, but it
|
||||
keeps the model simpler than snapshot/restore. It also prepares the runtime for
|
||||
future background-capable sessions without committing to background scheduling
|
||||
yet.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
### Pause Is Cooperative, Suspension Is OS Authority
|
||||
|
||||
The Game receives lifecycle events such as pause and resume, but the OS owns the
|
||||
actual scheduling state. If the Game does not cooperate within the bounded pause
|
||||
budget, SystemOS can suspend it anyway. On resume, the Game receives a foreground
|
||||
restore event and may still keep its internal pause screen while it
|
||||
synchronizes.
|
||||
|
||||
This distinction prevents userland from owning system navigation. The Game may
|
||||
observe and react. It cannot veto Home.
|
||||
|
||||
### Foreground Owner Is Not the Same as Tick Eligibility
|
||||
|
||||
Foreground ownership controls input, visual authority, render ownership, and
|
||||
normal frame pacing. Tick eligibility controls whether a VM session may execute.
|
||||
In v1, only the foreground VM session receives normal ticks, and the resident
|
||||
Game does not tick while Shell or Hub is foreground.
|
||||
|
||||
The important design detail is that the data model does not assume this must be
|
||||
true forever. Sessions can later become background-eligible without changing who
|
||||
owns render/input foreground.
|
||||
|
||||
### VM Sessions Are the Unit of Mutable Guest State
|
||||
|
||||
Each VM-backed task/process maps to a `VmSession`. The session owns the VM,
|
||||
runtime state, session-scoped filesystem state, open file handles, next handle
|
||||
allocation, cartridge identity, lifecycle delivery state, and debug state.
|
||||
|
||||
Cartridge loading creates or reuses a VM session through SystemOS session
|
||||
services. Firmware orchestrates macro states such as `LoadCartridge`,
|
||||
`GameRunning`, `HubHome`, and `ShellRunning`, but it no longer owns a canonical
|
||||
guest VM.
|
||||
|
||||
### Debugger and Host Inspection Must Follow the Active Session
|
||||
|
||||
Host debugging must inspect and mutate the active session VM, not a transitional
|
||||
global VM. PC, operand stack, breakpoints, debug-step execution, cartridge
|
||||
identity, and breakpoint-hit events all need to resolve through active session
|
||||
state.
|
||||
|
||||
This keeps debugger behavior aligned with actual execution. A debugger that
|
||||
observes a different VM than the scheduler ticks is worse than no debugger: it
|
||||
creates false confidence and hides lifecycle bugs.
|
||||
|
||||
### Operational Failures Should Cross Facades as Typed Errors
|
||||
|
||||
Session creation and loading are operational boundaries. Missing task, missing
|
||||
process, duplicate VM session, missing VM session during initialization, and
|
||||
foreground Shell rejection should be typed errors. Firmware can then choose a
|
||||
controlled crash report, a launch rejection, or a logged no-transition outcome.
|
||||
|
||||
Panics are reserved for test/setup wrappers or impossible internal invariants
|
||||
that have already been proven by prior checks.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Do not use a global VM as a compatibility bridge after session ownership is
|
||||
introduced. It will eventually become stale or contradictory.
|
||||
- Do not let Home/SystemOS be guest input. It changes OS authority, so it must
|
||||
bypass guest pad state.
|
||||
- Do not present old frames after foreground ownership changes. Render ownership
|
||||
and epoch validation are part of lifecycle correctness, not renderer polish.
|
||||
- Do not model pause and suspension as the same state. Pause is visible to the
|
||||
Game; suspension is the scheduler mechanism.
|
||||
- Do not encode v1 limits such as one resident Game or one foreground Shell by
|
||||
collapsing storage into one VM. Express those limits as lifecycle/session
|
||||
policy.
|
||||
- Do not let debugger state drift from scheduler state. The debugger must use
|
||||
the same active session as normal execution.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Foreground ownership is global policy; VM execution state is session-owned.
|
||||
- A suspended Game is a preserved session, not a serialized VM and not a global
|
||||
VM waiting to be reused.
|
||||
- Shell apps can be native or VM-backed, but only VM-backed processes need VM
|
||||
sessions.
|
||||
- Session ownership is the foundation for future background-capable processes,
|
||||
even before background execution exists.
|
||||
- Typed session/lifecycle errors make launch and recovery behavior explicit at
|
||||
firmware boundaries.
|
||||
+67
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: LSN-0053
|
||||
ticket: system-os-cartridge-switch-orchestrator
|
||||
title: Game Switching Is Lifecycle Replacement, Not Loader Work
|
||||
created: 2026-07-05
|
||||
tags: [runtime, os, lifecycle, game, cartridge]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
PROMETEU supports two superficially similar flows:
|
||||
|
||||
- `Game -> Home -> same Game`, which is pause/suspend/resume.
|
||||
- `Game A -> Home -> Game B`, which is destructive replacement.
|
||||
|
||||
The second flow is not a loader feature. It is a SystemOS lifecycle operation
|
||||
that happens to use the cartridge loader after the old resident Game has been
|
||||
removed from resumable state.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### SystemOS Game Cartridge Switch Orchestrator
|
||||
|
||||
**What:** A different-Game launch from Home terminates the previous resident
|
||||
Game before loading the new cartridge. The new Game receives a fresh VM session.
|
||||
|
||||
**Why:** Reusing or preserving the old Game while the new Game loads creates a
|
||||
rollback problem across VM state, handles, assets, input, audio, render
|
||||
ownership, debug state, and lifecycle delivery. V1 does not need that
|
||||
transactional model.
|
||||
|
||||
**Trade-offs:** Failed replacement returns to Home and does not restore the old
|
||||
Game. This is intentionally simpler than snapshot/rollback and makes state
|
||||
ownership visible in tests.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
Use a resolved SystemOS switch target, not a guest syscall, for Home launches.
|
||||
The target carries cartridge path and identity, while SystemOS owns the policy:
|
||||
|
||||
1. detect whether the selected Game matches the resident `app_id`;
|
||||
2. resume if it is the same Game;
|
||||
3. terminate the old resident Game if it is different;
|
||||
4. load the new cartridge through the normal loader;
|
||||
5. create and initialize a fresh VM session;
|
||||
6. return to Home on replacement failure without restoring the previous Game.
|
||||
|
||||
The loader stays a materializer. It does not close tasks, remove sessions,
|
||||
repair foreground state, or own failure recovery.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- Treating a different Game as a resume path leaks VM execution state.
|
||||
- Letting the loader own lifecycle cleanup hides policy in the wrong layer.
|
||||
- Keeping the old Game as rollback state requires correctness across assets,
|
||||
render ownership, input barriers, audio, open handles, and debugger state.
|
||||
- A switch test with only one cartridge cannot prove identity replacement.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Same-Game Home selection is resume; different-Game Home selection is
|
||||
destructive replacement.
|
||||
- SystemOS owns cartridge switching policy; the cartridge loader only loads.
|
||||
- Replacement failure should be a clean Home state, not a rollback to the old
|
||||
Game.
|
||||
- End-to-end switch tests need visually distinct cartridges to catch stale
|
||||
session or stale frame reuse.
|
||||
+72
@@ -0,0 +1,72 @@
|
||||
---
|
||||
id: LSN-0054
|
||||
ticket: hub-suspended-game-kill-affordance
|
||||
title: Manual Hub Kill Must Share Game Termination Cleanup
|
||||
created: 2026-07-05
|
||||
tags: [hub, lifecycle, game, ui, assets]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
After a Game returns to Home, the Game can remain resident and suspended so it
|
||||
can be resumed later. That state needs a visible, direct way to terminate the
|
||||
resident Game without launching another cartridge just to force replacement.
|
||||
|
||||
The Hub kill affordance solved the UX gap, but the durable engineering lesson is
|
||||
the cleanup boundary: manual kill must not become a second, partial termination
|
||||
path.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Hub Suspended Game Kill Affordance
|
||||
|
||||
**What:** Hub renders a red bottom-right control when a Game is resident and
|
||||
suspended. The control shows only the Game title. Clicking it immediately
|
||||
terminates the resident Game and keeps the user in Hub.
|
||||
|
||||
**Why:** The user can distinguish "resume this Game" from "discard this resident
|
||||
Game" without starting a different cartridge. Reusing the canonical termination
|
||||
path prevents a repeat of stale scene/glyph/asset state bugs.
|
||||
|
||||
**Trade-offs:** V1 has no confirmation step. The destructive nature is carried
|
||||
by placement, color, and the fact that the target Game is already out of
|
||||
foreground.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
Manual Hub kill and destructive Game replacement should call the same resident
|
||||
Game termination helper. That helper is responsible for the whole runtime
|
||||
surface:
|
||||
|
||||
- close the Game task;
|
||||
- stop the process;
|
||||
- remove the VM session;
|
||||
- clear resident Game state and task-scoped lifecycle delivery;
|
||||
- restore Shell/Hub render ownership;
|
||||
- clear lifecycle audio pause state;
|
||||
- unbind the Game2D composer scene;
|
||||
- shut down cartridge-scoped asset manager state and physical banks;
|
||||
- emit explicit Hub/POS observability for manual kill.
|
||||
|
||||
The Hub itself should emit a high-level action such as `KillResidentGame`; it
|
||||
should not know how to clean runtime subsystems.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- A UI-only kill that removes a task but leaves assets or composer binding alive
|
||||
can still fail later when another Game renders.
|
||||
- A cleanup-only helper without an end-to-end Hub click test can miss the
|
||||
interaction between hitbox, foreground ownership, render owner, and no-resume.
|
||||
- Hard-coded click coordinates in tests make the UI contract harder to maintain;
|
||||
expose the layout hitbox when tests need to exercise it.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Visible system controls should produce system actions, not direct subsystem
|
||||
mutation from UI code.
|
||||
- Manual kill and Game replacement are variants of the same resident Game
|
||||
termination contract.
|
||||
- Cleanup tests should prove both logical state removal and visible-frame
|
||||
behavior: the control appears before kill and disappears after kill.
|
||||
- "No resume after kill" is as important as "task closed" because resumability
|
||||
is the user-facing state.
|
||||
+97
@@ -0,0 +1,97 @@
|
||||
---
|
||||
id: LSN-0055
|
||||
ticket: runtime-owned-variable-glyph-bank-palette-protocol
|
||||
title: Runtime-Owned Asset Protocols Must Align Payload, Residency, and Lookup
|
||||
created: 2026-07-14
|
||||
tags: [runtime, assets, glyph-bank, palette-serialization, protocol]
|
||||
decision: DEC-0041
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The runtime changed the `GLYPH/indexed_v1` glyph-bank palette contract from a
|
||||
fixed 64-palette payload and resident table to variable palette serialization
|
||||
and variable resident palette storage.
|
||||
|
||||
The initiating pressure came from packer/studio: fixed RGBA8888 palette padding
|
||||
made small glyph banks pay for `64 * 16 * 4` palette bytes even when they used
|
||||
far fewer palettes. The important architectural point was that the runtime, not
|
||||
the packer, had to decide the protocol. The packer can only emit payloads that
|
||||
conform to the runtime contract once the runtime spec is published.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Variable Glyph Bank Palette Protocol
|
||||
|
||||
**What:**
|
||||
`palette_count` became the number of serialized palettes and the number of
|
||||
resident palettes in the loaded `GlyphBank`. The valid range is `1..=64`.
|
||||
`palette_id` remains a direct palette identity and is valid only when
|
||||
`palette_id < palette_count` for the referenced resident bank.
|
||||
|
||||
**Why:**
|
||||
Keeping serialized count variable while retaining a fixed 64-slot resident
|
||||
table would preserve two meanings for palette capacity. The runtime would save
|
||||
payload bytes but still carry a split contract between payload shape, resident
|
||||
shape, and lookup validity. Making all three agree gives the runtime one
|
||||
source of truth.
|
||||
|
||||
**Trade-offs:**
|
||||
Palette validity is now bank-dependent. Scene and sprite composition must check
|
||||
the referenced loaded bank instead of relying on a global `0..63` rule. This
|
||||
adds validation work, but it prevents invalid references from silently becoming
|
||||
transparent or default colors.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
Let the runtime own runtime-facing asset protocols. Tooling can discover pain,
|
||||
but the runtime spec must define effective metadata, payload shape, resident
|
||||
shape, and failure semantics.
|
||||
|
||||
Make count fields material. A count such as `palette_count` should not describe
|
||||
only what the producer authored or only what the payload happens to include. If
|
||||
runtime lookup depends on it, the count must also define resident state and
|
||||
validation boundaries.
|
||||
|
||||
Keep identity direct unless a real remapping problem exists. Sparse-to-dense
|
||||
palette remapping was rejected because it would add a second identity layer
|
||||
across scenes, sprites, packer output, and runtime lookup. V1 keeps palette id
|
||||
`N` as palette slot `N` in the resident bank.
|
||||
|
||||
Separate transparent color from invalid lookup. RGBA alpha is valid color data.
|
||||
An invalid palette reference must be observable as invalid; it must not be
|
||||
collapsed into `Color::TRANSPARENT`.
|
||||
|
||||
Use residue scans after protocol migrations. Search for fixed byte formulas,
|
||||
old constants, fixture helpers, and spec phrases. Legitimate hits should be
|
||||
renamed as maximum-bound concepts, not left as accidental active contracts.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
Partially variable specs are worse than fixed specs. The asset spec already had
|
||||
variable size formulas in some places but still required `palette_count = 64`
|
||||
elsewhere. That contradiction made it unclear which rule was canonical.
|
||||
|
||||
Resident data structures can preserve obsolete protocol assumptions after the
|
||||
payload changes. A fixed array in `GlyphBank` would have kept the old model
|
||||
alive even if decode accepted variable payloads.
|
||||
|
||||
Fallback rendering hides contract errors. Returning transparent for an invalid
|
||||
palette id makes bad assets and bad scene references look like intentional
|
||||
alpha, which is exactly the wrong failure mode for a runtime protocol.
|
||||
|
||||
Fixture generators are part of the contract surface. Stress cartridges and
|
||||
test payload builders must express whether they are using a variable count or
|
||||
the v1 maximum; otherwise they reintroduce fixed-padding assumptions.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Runtime-facing asset protocols should align payload size, resident memory,
|
||||
and lookup validity.
|
||||
- `palette_count` is effective runtime metadata, not producer commentary.
|
||||
- Direct identity is simpler than remapping until a concrete remapping need
|
||||
exists.
|
||||
- Invalid palette references should fail explicitly; transparent remains a
|
||||
valid RGBA color, not an error substitute.
|
||||
- Protocol migrations need spec edits, code changes, fixture updates, and
|
||||
residue scans in the same workflow.
|
||||
+61
@@ -0,0 +1,61 @@
|
||||
---
|
||||
id: LSN-0056
|
||||
ticket: corrigir-identificacao-formato-pbx
|
||||
title: Runtime Artifact Identity Must Not Borrow Frontend Names
|
||||
created: 2026-07-15
|
||||
tags: [runtime, bytecode, pbx, frontend, format-boundary]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Prometeu accepts bytecode produced by multiple frontends. PBS is the base
|
||||
frontend language, while PBX is the executable bytecode artifact consumed by the
|
||||
runtime.
|
||||
|
||||
The runtime had inherited PBS terminology in the executable bytecode path,
|
||||
including the serialized magic number, comments, tests, and VM loader checks.
|
||||
That made one frontend appear to own the runtime executable format.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### PBX Executable Format Identity
|
||||
|
||||
**What:** PBX is the runtime executable bytecode format, and `PBX\0` is its only
|
||||
valid magic number.
|
||||
|
||||
**Why:** Runtime artifact identity must be independent from any frontend that can
|
||||
produce the artifact. Naming the executable format after PBS would make the
|
||||
runtime boundary look language-specific.
|
||||
|
||||
**Trade-offs:** The correction intentionally rejects old PBS-prefixed executable
|
||||
artifacts instead of carrying a compatibility alias. This keeps the format
|
||||
contract singular, but requires stale generated fixtures to be regenerated or
|
||||
updated.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
Put file-format identity in the module that serializes and deserializes the
|
||||
format. Loaders and higher-level runtime code should call that boundary instead
|
||||
of duplicating magic-number checks.
|
||||
|
||||
When renaming an artifact identity, update all fixture construction and generator
|
||||
assertions in the same pass as production serialization. Mixed fixture identity
|
||||
usually means tests are asserting historical spelling rather than current
|
||||
contract.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
Do not globally erase frontend names. PBS remains correct when the subject is
|
||||
the PBS language, stdlib, or frontend-facing API. It is wrong only when it names
|
||||
the executable bytecode artifact.
|
||||
|
||||
Do not preserve old magic values just to make a rename feel less disruptive. If
|
||||
there is no compatibility requirement for old artifacts, aliases keep the
|
||||
incorrect model alive.
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Runtime artifact names should describe the runtime contract, not the compiler
|
||||
or frontend that produced the artifact.
|
||||
- Magic numbers are normative format identity, not cosmetic labels.
|
||||
- Loader code should delegate file-format validation to the format owner.
|
||||
@@ -1,94 +0,0 @@
|
||||
---
|
||||
id: AGD-0003
|
||||
ticket: system-run-cart
|
||||
title: Agenda - System Run Cart
|
||||
status: open
|
||||
created: 2026-03-27
|
||||
resolved:
|
||||
decision:
|
||||
tags: []
|
||||
---
|
||||
|
||||
# Agenda - System Run Cart
|
||||
|
||||
## Problema
|
||||
|
||||
A syscall `system.run_cart` existe na ABI pública, mas hoje não produz efeito real no runtime.
|
||||
|
||||
Isso cria uma falsa promessa de plataforma:
|
||||
|
||||
- o programa consegue declarar e chamar a syscall;
|
||||
- o loader aceita sua existência;
|
||||
- o runtime retorna sucesso vazio;
|
||||
- nenhuma troca de cartucho, transição de firmware, validação de alvo ou política de segurança ocorre.
|
||||
|
||||
## Dor
|
||||
|
||||
- A ABI expõe uma capability de sistema que, na prática, nao existe.
|
||||
- O guest pode acreditar que solicitou uma troca de app quando nada aconteceu.
|
||||
- Isso corrói a confiabilidade da plataforma: a interface pública deixa de ser contrato e vira placebo.
|
||||
- Qualquer ferramenta, SDK ou documentação construída sobre essa syscall passa a modelar um comportamento inexistente.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Definir o contrato real de `system.run_cart` do ponto de vista:
|
||||
|
||||
- do guest;
|
||||
- do runtime;
|
||||
- do firmware;
|
||||
- do host/cartridge loader.
|
||||
|
||||
Ao final da discussão, deve ficar claro se a syscall:
|
||||
|
||||
- permanece na ABI e ganha implementação completa; ou
|
||||
- sai temporariamente da ABI até existir fluxo fechado.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Semântica da operação.
|
||||
O que significa "run cart": trocar imediatamente, agendar para o próximo frame, retornar ao firmware, reiniciar VM atual, ou apenas emitir uma intenção?
|
||||
|
||||
2. Origem do alvo.
|
||||
Como o guest identifica o cartucho alvo: id numérico, nome canônico, path virtual, handle, manifesto, ou nenhum argumento nesta primeira versão?
|
||||
|
||||
3. Modelo de segurança.
|
||||
Quem pode chamar isso, sob qual capability, e com quais restrições para evitar que um app force navegação arbitrária do sistema?
|
||||
|
||||
4. Ponto de integração.
|
||||
Onde a transição vive: `VirtualMachineRuntime`, firmware, host, ou combinação dos três?
|
||||
|
||||
5. Efeitos observáveis.
|
||||
O que acontece com:
|
||||
- estado do app atual;
|
||||
- FS aberto;
|
||||
- assets carregados;
|
||||
- telemetria;
|
||||
- crash reports;
|
||||
- logs.
|
||||
|
||||
6. Contrato de erro.
|
||||
Quais falhas retornam trap ao guest e quais viram evento de sistema.
|
||||
|
||||
## O Que Necessita Para Resolver
|
||||
|
||||
- fluxo fechado entre syscall -> runtime -> firmware -> loader -> novo app;
|
||||
- modelo explícito para seleção do alvo;
|
||||
- definição de lifecycle da troca de cartucho;
|
||||
- testes de integração cobrindo transição bem-sucedida, alvo inválido, capability insuficiente e cleanup de estado.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- catálogo completo de apps instalados;
|
||||
- UX final do launcher/hub;
|
||||
- resolução remota ou download de cartuchos;
|
||||
- política de marketplace/distribuição.
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Esta agenda só pode virar PR de implementação quando existir decisão escrita para:
|
||||
|
||||
- assinatura final da syscall;
|
||||
- local canônico da troca de estado;
|
||||
- política de erro;
|
||||
- limpeza de recursos;
|
||||
- cobertura mínima de testes de integração.
|
||||
@@ -22,6 +22,19 @@ Sem um contrato claro de `home` por app, a API tende a crescer com semantica inc
|
||||
1. Todo `app` acessa somente sua `home` logica.
|
||||
2. Nunca ha acesso direto ao filesystem global do host pela userland.
|
||||
3. O runtime `fs` interno continua cobrindo tanto `game` quanto `app`.
|
||||
4. Existe uma async IO lane compartilhavel por assets, memcard e FS. Esta
|
||||
agenda deve decidir a API publica de FS considerando essa lane, mas a
|
||||
existencia da lane ja esta fechada por `DEC-0034`.
|
||||
|
||||
## Fronteira com a Async IO Lane
|
||||
|
||||
`DEC-0034` fecha a existencia de uma lane serial para trabalho async de IO. FS
|
||||
pode consumir essa lane internamente para escrita, configuracao, leitura ou
|
||||
listagem, conforme prioridade operacional definida pelo runtime.
|
||||
|
||||
Esta agenda continua dona da decisao sobre API publica de FS para `app home`.
|
||||
Portanto, a existencia da lane nao implica criar agora request handles, polling
|
||||
publico ou novas syscalls de FS. Esses shapes permanecem em aberto aqui.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
@@ -116,6 +129,8 @@ No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para
|
||||
2. `rename` entra no MVP ou pode ficar para fase seguinte?
|
||||
3. Qual conjunto minimo de metadados garante portabilidade real entre hosts?
|
||||
4. Qual grau de atomicidade e obrigatorio para escrita de arquivo no v1?
|
||||
5. Quais operacoes de FS devem consumir a async IO lane e quais permanecem
|
||||
sincrono-aparentes para a userland?
|
||||
|
||||
## Dependencias
|
||||
|
||||
|
||||
-557
@@ -1,557 +0,0 @@
|
||||
---
|
||||
id: AGD-0008
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Agenda - [PERF] Async Background Work Lanes for Assets and FS
|
||||
status: accepted
|
||||
created: 2026-03-27
|
||||
resolved: 2026-06-28
|
||||
decision: DEC-0034
|
||||
tags: [perf, asset, fs, async, scheduler, runtime]
|
||||
---
|
||||
|
||||
# Agenda - [PERF] Async Background Work Lanes for Assets and FS
|
||||
|
||||
## Contexto
|
||||
|
||||
Depois das decisoes de render worker, a concorrencia de render saiu do escopo
|
||||
desta agenda. O problema restante e a lane de trabalho assincrono para IO,
|
||||
decode e persistencia.
|
||||
|
||||
O modelo de execucao que queremos discutir agora assume uma terceira core/lane
|
||||
dedicada a trabalhos assincronos de runtime:
|
||||
|
||||
```text
|
||||
Core/lane 1: VM, firmware, SystemOS e frame logico
|
||||
Core/lane 2: render worker / rasterizacao assincrona
|
||||
Core/lane 3: async work lane para asset IO/decode e possivelmente FS
|
||||
```
|
||||
|
||||
Essa terceira lane nao deve virar um pool grande e solto. A intencao e ter uma
|
||||
fila previsivel, com capacidade limitada, telemetria e regras de saturacao.
|
||||
|
||||
Para assets, a necessidade e concreta: `asset.load()` ainda cria uma thread do
|
||||
SO por requisicao. Para FS, a motivacao provavel era evitar que operacoes de
|
||||
leitura/escrita/listagem/delete, hoje chamadas de forma sincrona pelo dispatch,
|
||||
roubem tempo do frame quando o backend real envolver IO. Precisamos verificar
|
||||
se FS deve usar a mesma lane agora ou apenas reservar compatibilidade.
|
||||
|
||||
## Problema
|
||||
|
||||
`asset.load()` hoje dispara `thread::spawn` por requisicao de asset nao
|
||||
residente. Isso escala mal, cria jitter e deixa o runtime sem uma politica
|
||||
unica de backpressure.
|
||||
|
||||
O dominio `fs` tambem tem operacoes potencialmente bloqueantes (`read`,
|
||||
`write`, `list_dir`, `delete`, memcard commit/read/write) e a tabela de
|
||||
syscalls ja as marca como nao deterministicas/custosas. Ainda assim, a
|
||||
implementacao atual executa essas chamadas diretamente no caminho de dispatch.
|
||||
|
||||
Sem um contrato explicito, cada dominio pode inventar sua propria concorrencia:
|
||||
asset criando threads, FS bloqueando o frame, e memcard herdando comportamento
|
||||
acidental do backend.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- `thread::spawn` por request escala mal e cria jitter.
|
||||
- A terceira core/lane deve ser um recurso de plataforma controlado, nao uma
|
||||
permissao geral para criar threads.
|
||||
- Asset loading precisa de um pool/fila limitada para multiplos loads
|
||||
pendentes.
|
||||
- FS pode justificar a mesma lane quando envolver IO real, mas nao devemos
|
||||
assinar uma API assincrona ampla sem entender a semantica de retorno.
|
||||
- Commit/install em bancos residentes pode ter restricoes de determinismo e
|
||||
ownership; decode pode ser assincrono, mas publicacao/instalacao talvez tenha
|
||||
que cruzar de volta para a lane principal.
|
||||
- A estrategia precisa funcionar em hardware alvo com poucos cores e tambem no
|
||||
host desktop sem transformar desktop em referencia de custo errada.
|
||||
- Render worker ja tem seu proprio contrato e nao deve compartilhar essa lane.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L438) - `AssetManager::load`.
|
||||
- [asset.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-drivers/src/asset.rs#L507) - `thread::spawn` por load.
|
||||
- [fs.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/fs.rs#L4) - `fs` e `mem` marcados como superficies custosas/nao deterministicas.
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs#L549) - chamadas `fs.*` executam no dispatch.
|
||||
- [virtual_fs.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/services/fs/virtual_fs.rs#L69) - VFS normaliza path e chama backend diretamente.
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar um modelo de terceira core/lane para trabalho assincrono de runtime,
|
||||
comecando por asset loading e avaliando se FS deve entrar na mesma lane no v1.
|
||||
|
||||
O alvo nao e criar multitarefa geral, callbacks para guest, ou um scheduler
|
||||
paralelo da VM. A lane deve executar trabalho de IO/decode/sync e publicar
|
||||
resultados observaveis por status/polling em pontos previsiveis.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Topologia da terceira lane.
|
||||
Definir:
|
||||
- uma async work lane dedicada, separada da VM e do render worker;
|
||||
- se a lane e uma thread fixa no host e uma core dedicada no hardware alvo;
|
||||
- fallback quando nao houver core fisico dedicado;
|
||||
- proibicao explicita de `thread::spawn` por request no caminho normal.
|
||||
|
||||
2. Pool/fila de asset loading.
|
||||
Definir:
|
||||
- backlog de pedidos sem limite operacional fixo;
|
||||
- exatamente um job ativo por vez na lane;
|
||||
- o "pool" significa backlog e estados de job, nao multiplos workers reais;
|
||||
- politica de substituicao/cancelamento para pedidos que miram o mesmo
|
||||
bank/slot;
|
||||
- status para pending/backlog, ativo, progresso, cancelamento, erro de
|
||||
decode e sucesso.
|
||||
|
||||
3. Fases do asset load.
|
||||
Separar:
|
||||
- request e alocacao de handle;
|
||||
- leitura de bytes;
|
||||
- decode/materializacao;
|
||||
- staging de resultado;
|
||||
- install/commit em banco residente.
|
||||
|
||||
Ponto a fechar: quais fases rodam na terceira lane e quais voltam para a
|
||||
lane principal por determinismo/ownership.
|
||||
|
||||
4. Inclusao de FS na mesma lane.
|
||||
Verificar se `fs` deve usar a terceira lane no v1 para:
|
||||
- leituras grandes;
|
||||
- escritas;
|
||||
- listagem;
|
||||
- delete;
|
||||
- memcard commit/read/write.
|
||||
|
||||
Ponto a fechar: FS sync publico continua bloqueante/status-first, vira
|
||||
request/poll, ou ganha apenas uma implementacao interna que drena trabalho em
|
||||
pontos de frame.
|
||||
|
||||
5. Separacao por dominio.
|
||||
Decidir se `asset` e `fs` compartilham uma fila com classes de prioridade ou
|
||||
se a terceira lane contem subfilas dedicadas.
|
||||
|
||||
6. Politica de prioridade.
|
||||
Definir:
|
||||
- prioridade de loads visuais vs audio;
|
||||
- prioridade de save/config;
|
||||
- prioridade de memcard commit;
|
||||
- starvation prevention;
|
||||
- limite de trabalho de instalacao/publicacao por frame.
|
||||
|
||||
7. Modelo de retorno e telemetria.
|
||||
Fechar como guest/runtime observa:
|
||||
- `pending`;
|
||||
- `loading`;
|
||||
- `ready`;
|
||||
- `canceled`;
|
||||
- `backend_unavailable`;
|
||||
- backlog;
|
||||
- posicao de um asset no backlog;
|
||||
- progresso percentual do asset ativo;
|
||||
- drops/retries quando aplicavel.
|
||||
|
||||
8. Orcamento para hardware barato.
|
||||
Definir o baseline:
|
||||
- VM principal;
|
||||
- render worker;
|
||||
- terceira async work lane;
|
||||
- limites de memoria para jobs pendentes e buffers temporarios.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Terceira lane unica com subfilas e pool limitado de assets
|
||||
|
||||
- **Abordagem:** criar uma async work lane dedicada. Assets usam um pool/fila
|
||||
de jobs nessa lane; FS tambem pode submeter jobs na mesma lane, com
|
||||
prioridade menor ou classe separada.
|
||||
- **Pro:** modelo simples de budget; evita explosao de threads; encaixa no alvo
|
||||
de terceira core; permite compartilhar backpressure e telemetria.
|
||||
- **Contra:** assets e FS podem competir por IO; precisa politica clara para
|
||||
evitar que save/config fique atras de loads longos.
|
||||
- **Manutenibilidade:** boa se a lane tiver tipos de job e estados explicitos.
|
||||
|
||||
### Opcao B - Lane de assets agora, FS apenas reservado
|
||||
|
||||
- **Abordagem:** fechar v1 somente para asset loading, removendo `spawn` por
|
||||
request. FS continua sincrono por enquanto, mas o contrato da lane reserva
|
||||
compatibilidade para FS no futuro.
|
||||
- **Pro:** menor escopo; resolve a dor concreta de assets rapidamente; evita
|
||||
alterar semantica de FS antes da agenda de app home filesystem.
|
||||
- **Contra:** nao resolve stalls reais de FS/memcard; pode exigir refatorar a
|
||||
lane depois para aceitar FS.
|
||||
- **Manutenibilidade:** boa no curto prazo, com risco de segunda migracao.
|
||||
|
||||
### Opcao C - Lanes separadas para asset e FS
|
||||
|
||||
- **Abordagem:** criar uma lane/pool para assets e outra para FS.
|
||||
- **Pro:** isolamento forte; FS/save nao compete diretamente com loads de
|
||||
textura/audio/cena.
|
||||
- **Contra:** consome mais threads/cores; contraria a premissa de terceira core
|
||||
unica; pior para hardware simples.
|
||||
- **Manutenibilidade:** media; isolamento ajuda, mas a topologia fica pesada.
|
||||
|
||||
### Opcao D - Pool global pequeno sem nocao de terceira lane
|
||||
|
||||
- **Abordagem:** trocar `spawn` por request por um pool global fixo.
|
||||
- **Pro:** simples de implementar em host desktop.
|
||||
- **Contra:** perde a arquitetura de lanes por core; pode mascarar custo em
|
||||
desktop; fica menos claro como mapear para hardware alvo.
|
||||
- **Manutenibilidade:** baixa para o modelo de console se virar dependencia
|
||||
acidental de scheduler do SO.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendo seguir com a Opcao A como direcao de arquitetura, mas fechar a
|
||||
decisao em duas camadas:
|
||||
|
||||
1. Contrato obrigatorio agora:
|
||||
- terceira async work lane como recurso runtime;
|
||||
- assets deixam de usar `thread::spawn` por requisicao;
|
||||
- asset loading passa por backlog consultavel/reordenavel;
|
||||
- status, progresso e telemetria de backlog ficam explicitos.
|
||||
|
||||
2. Contrato condicionado para FS:
|
||||
- FS deve ser analisado como consumidor legitimo da mesma lane porque suas
|
||||
operacoes podem envolver IO real e ja sao custosas/nao deterministicas;
|
||||
- a decisao precisa escolher entre incluir FS no v1 ou reservar a lane para
|
||||
FS sem mudar ainda a superficie publica;
|
||||
- memcard precisa ser considerado junto com FS, porque usa a mesma
|
||||
capacidade e backend de persistencia.
|
||||
|
||||
O ponto importante: a terceira core/lane deve ser a unidade de concorrencia.
|
||||
O pool de assets deve existir dentro desse modelo, nao como criacao livre de
|
||||
threads por load.
|
||||
|
||||
## Respostas Consolidadas Ate Aqui
|
||||
|
||||
1. O pool de assets deve ser uma lane serial.
|
||||
- Ha exatamente um job ativo na async work lane.
|
||||
- O pool representa backlog, estados e controle de ordem, nao multiplos
|
||||
workers executando em paralelo.
|
||||
|
||||
2. O backlog de pedidos deve ser semanticamente ilimitado.
|
||||
- Nao existe `queue_full` como status normal do dominio.
|
||||
- Como cada pedido mira um `bank_type/slot` e pedidos novos para o mesmo
|
||||
alvo substituem os anteriores, o backlog efetivo fica limitado pela soma
|
||||
dos slots dos bancos.
|
||||
- O contrato nao precisa expor limite de fila, mas a implementacao deve
|
||||
garantir que metadados de handles cancelados/superseded nao crescam sem
|
||||
coleta.
|
||||
|
||||
3. Asset loading precisa expor consulta e reordenacao do backlog.
|
||||
- Deve existir API publica/runtime para consultar onde um asset esta no
|
||||
backlog.
|
||||
- Deve existir capacidade de adiantar ou atrasar um pedido de asset na fila.
|
||||
- O asset ativo deve expor progresso percentual.
|
||||
- Requests novos para o mesmo `bank_type/slot` devem cancelar pedidos
|
||||
anteriores pendentes para aquele alvo, evitando carregar asset que ja foi
|
||||
substituido antes de executar.
|
||||
- Se o alvo ja estiver carregado com o mesmo `asset_id`, o novo request nao
|
||||
entra no backlog; ele retorna imediatamente pronto com handle disponivel.
|
||||
- Se um novo request substituir o alvo atualmente ativo, a lane deve cancelar
|
||||
em ponto cooperativo quando possivel; se o trabalho nao puder ser
|
||||
interrompido, o resultado antigo deve ser descartado ao final por geracao
|
||||
superseded.
|
||||
- `superseded` significa que um request foi substituido por outro request
|
||||
mais novo para o mesmo `bank_type/slot`. Nao e erro e nao e cancelamento
|
||||
manual; e obsolescencia operacional do pedido antigo.
|
||||
- Handles representam o slot do bank como alvo estavel. Dentro do estado do
|
||||
handle deve existir uma secao de request/backlog para aquele slot,
|
||||
informando se ha pedido pendente/ativo, qual asset foi solicitado,
|
||||
progresso, posicao e geracao.
|
||||
- Handles devem ser capazes de consultar o estado do alvo `bank_type/slot`
|
||||
a qualquer momento. Se nao houver asset valido carregado e tambem nao
|
||||
houver request pendente para aquele alvo, a consulta deve retornar estado
|
||||
explicito de vazio/invalido, nao falhar por ausencia de request ativo.
|
||||
|
||||
4. Decode/materializacao fria rodam na terceira lane.
|
||||
- Leitura e decode de asset podem acontecer fora da lane principal.
|
||||
- O resultado deve voltar como material pronto/staged.
|
||||
|
||||
5. Install/commit em bancos residentes continua na lane principal.
|
||||
- A async lane prepara trabalho.
|
||||
- A lane principal publica/instala em pontos previsiveis por ownership,
|
||||
determinismo e integracao com bancos/render/audio.
|
||||
|
||||
6. FS e memcard entram como consumidores possiveis da mesma lane, mas precisam
|
||||
ser melhor amarrados com a agenda de app home filesystem.
|
||||
- A `DSC-0007` / `AGD-0006` deve ser ajustada para estabelecer melhor a
|
||||
superficie publica e o modelo async/sync de FS.
|
||||
- Esta agenda deve afirmar a existencia da lane para trabalhos async de IO
|
||||
desse tipo e permitir que FS a consuma.
|
||||
- Questoes de API publica de FS, request/poll e semantica de app home devem
|
||||
ficar a cargo da agenda 6.
|
||||
- FS, memcard e assets nao devem operar sobrepostos quando isso gerar
|
||||
concorrencia real de backend; se houver competicao, a fila unica resolve a
|
||||
ordem.
|
||||
|
||||
7. Prioridade quando houver competicao:
|
||||
- memcard commit/write;
|
||||
- FS write/config;
|
||||
- asset visual/audio load;
|
||||
- list/read nao critico.
|
||||
|
||||
8. Status-first continua valendo.
|
||||
- `backend_unavailable`, `canceled`, erro de decode e estados de job sao
|
||||
status operacionais.
|
||||
- Cancelamento por superseding de pedido no mesmo bank/slot e resultado
|
||||
operacional normal, nao fault.
|
||||
- Nao ha `queue_full` no contrato esperado.
|
||||
- Trap permanece para violacao estrutural, como argumento invalido,
|
||||
capability ausente ou handle estruturalmente invalido.
|
||||
|
||||
9. Telemetria minima:
|
||||
- backlog atual;
|
||||
- posicao por asset;
|
||||
- progresso percentual do asset ativo;
|
||||
- jobs submetidos, concluidos, falhos e cancelados;
|
||||
- tempo por job;
|
||||
- percentis por asset enquanto estiver carregando na lane.
|
||||
|
||||
10. Escopo da agenda.
|
||||
- O foco desta agenda e a lane, assets e memcard/game persistence.
|
||||
- FS entra como consumidor permitido da lane de IO, mas as decisoes de API
|
||||
publica de FS pertencem a `AGD-0006`.
|
||||
|
||||
11. API de backlog.
|
||||
- A API inicial sugerida cobre os casos esperados.
|
||||
- `asset.backlog_promote(handle)` deve ser mantido como atalho oficial para
|
||||
`asset.backlog_move(handle, 1)`.
|
||||
- `asset.backlog_demote(handle)` deve ser mantido como atalho oficial para
|
||||
mover o pedido para o fim dos pendentes.
|
||||
- Os atalhos nao criam semantica nova; apenas evitam que o caller calcule
|
||||
posicoes comuns.
|
||||
- O handle deve permitir consulta estavel do slot do bank mesmo quando nao ha
|
||||
asset valido carregado.
|
||||
- O estado do handle deve separar:
|
||||
- estado do slot/residencia atual;
|
||||
- estado do request/backlog atual para aquele slot.
|
||||
- Operacoes que mudam estado, como commit/cancel/reorder, atuam sobre a
|
||||
secao de request/backlog do handle e precisam validar geracao/request atual
|
||||
para nao agir sobre um pedido substituido.
|
||||
|
||||
12. Cancelamento por substituicao.
|
||||
- Quando um request novo chega para o mesmo `bank_type/slot`, o request
|
||||
anterior e marcado imediatamente como `superseded`.
|
||||
- Se o request anterior ainda estiver no backlog, ele sai da fila.
|
||||
- Se o request anterior estiver ativo, a lane tenta cancelar
|
||||
cooperativamente quando a fase atual permitir.
|
||||
- Se a fase ativa nao puder ser interrompida com baixo custo, ela termina e
|
||||
o resultado e descartado ao final porque a geracao do alvo ja mudou.
|
||||
- Como o handle pertence ao slot do bank, ele continua consultavel; sua
|
||||
secao de request deve indicar que a geracao anterior foi `superseded` ou
|
||||
que nao ha request ativo para aquele alvo.
|
||||
|
||||
13. Fases de progresso.
|
||||
- `read/decode/stage` e suficiente como modelo minimo para `GLYPH`, `SOUND`
|
||||
e `SCENE`.
|
||||
- Subfases futuras podem detalhar progresso dentro de `decode` sem mudar o
|
||||
contrato geral.
|
||||
|
||||
14. Percentis.
|
||||
- Percentis devem existir por `bank_type` como telemetria principal.
|
||||
- Percentis por `asset_id` tambem sao uteis, mas podem usar janela pequena
|
||||
ou agregador leve.
|
||||
- Percentis sao atualizados no fechamento do job, nao durante o hot path.
|
||||
|
||||
15. Ajuste esperado na agenda de FS.
|
||||
- `AGD-0006` deve registrar que existe uma async IO lane compartilhavel por
|
||||
FS/memcard/assets.
|
||||
- Esta agenda so decide que FS pode consumir a lane.
|
||||
- A API publica de FS, incluindo request/poll ou sync aparente, pertence a
|
||||
`AGD-0006`.
|
||||
|
||||
## API Inicial Sugerida Para Assets
|
||||
|
||||
Esta agenda ainda nao fecha nomes finais de ABI, mas a direcao inicial sugerida
|
||||
e manter `asset.load/status/commit/cancel` e adicionar uma superficie pequena
|
||||
para backlog:
|
||||
|
||||
1. `asset.backlog_info() -> (status, pending_count, active_handle, active_asset_id, active_bank_type, active_slot, active_progress)`
|
||||
- Consulta o estado geral da lane de assets.
|
||||
- `active_progress` usa escala inteira, preferencialmente `0..10000` para
|
||||
permitir duas casas decimais sem float.
|
||||
|
||||
2. `asset.backlog_position(handle) -> (status, state, position, progress)`
|
||||
- Consulta um pedido especifico.
|
||||
- `position = 0` significa job ativo.
|
||||
- `position > 0` significa posicao no backlog.
|
||||
- `position = -1` pode representar nao enfileirado/pronto/cancelado,
|
||||
dependendo do `state`.
|
||||
|
||||
3. `asset.backlog_move(handle, new_position) -> status`
|
||||
- Move um pedido pendente para uma posicao absoluta.
|
||||
- `new_position = 1` significa primeiro pendente depois do ativo.
|
||||
- Nao interrompe diretamente o job ativo; substituicao do mesmo
|
||||
`bank_type/slot` usa a regra de superseding.
|
||||
|
||||
4. `asset.backlog_promote(handle) -> status`
|
||||
- Atalho para mover o pedido para a frente do backlog pendente.
|
||||
|
||||
5. `asset.backlog_demote(handle) -> status`
|
||||
- Atalho para mover o pedido para o fim do backlog pendente.
|
||||
|
||||
6. `asset.target_status(bank_type, slot) -> (status, asset_id, handle, state, position, progress)`
|
||||
- Consulta por alvo operacional, que e o que realmente controla superseding.
|
||||
- Ajuda quando o caller quer saber "o que esta programado para este slot".
|
||||
|
||||
Estados sugeridos para `state`:
|
||||
|
||||
- `empty`;
|
||||
- `invalid`;
|
||||
- `queued`;
|
||||
- `active`;
|
||||
- `ready`;
|
||||
- `committed`;
|
||||
- `canceled`;
|
||||
- `superseded`;
|
||||
- `error`;
|
||||
- `backend_unavailable`.
|
||||
|
||||
Regra de design: APIs de backlog sao operacionais e status-first. Reordenar um
|
||||
handle inexistente, ja concluido ou ja superseded retorna status operacional
|
||||
apropriado quando o handle e conhecido; violações estruturais continuam Trap.
|
||||
|
||||
Handles sao observaveis e representam slots de banks. Um handle conhecido pode
|
||||
ser consultado mesmo quando o slot alvo nao contem asset valido carregado; nesse
|
||||
caso a consulta deve retornar estado como `empty` ou `invalid`.
|
||||
|
||||
O estado do handle deve conter pelo menos duas partes:
|
||||
|
||||
```text
|
||||
slot_state:
|
||||
loaded_asset_id
|
||||
resident_state
|
||||
|
||||
request_state:
|
||||
requested_asset_id
|
||||
generation
|
||||
queued/active/ready/canceled/superseded/error
|
||||
backlog_position
|
||||
progress
|
||||
```
|
||||
|
||||
Mutacoes seguem regras mais estritas e devem falhar operacionalmente quando a
|
||||
secao de request/backlog do handle nao representa a geracao atual.
|
||||
|
||||
## Progresso e Percentis
|
||||
|
||||
### Progresso percentual
|
||||
|
||||
Sugestao:
|
||||
|
||||
- usar progresso em base inteira `0..10000`;
|
||||
- quando o tamanho total de bytes for conhecido, calcular progresso por fases
|
||||
ponderadas;
|
||||
- quando o decode nao for linear ou nao houver tamanho confiavel, expor
|
||||
progresso por fase com marcos conservadores.
|
||||
|
||||
Modelo inicial de fases:
|
||||
|
||||
```text
|
||||
queued -> 0
|
||||
read -> 0..4000
|
||||
decode -> 4000..9000
|
||||
stage -> 9000..10000
|
||||
ready -> 10000
|
||||
```
|
||||
|
||||
Se uma fase nao consegue reportar progresso interno, ela deve manter o ultimo
|
||||
marco e saltar para o proximo marco ao concluir. Isso evita progresso falso
|
||||
sem perder visibilidade de fase.
|
||||
|
||||
### Percentis por asset
|
||||
|
||||
Sugestao:
|
||||
|
||||
- registrar duracoes por asset no fim de cada job, nao por tick/frame;
|
||||
- manter agregadores pequenos por `asset_id` e por `bank_type`;
|
||||
- calcular percentis a partir de janela/ring buffer pequeno ou histograma
|
||||
barato por bucket de duracao;
|
||||
- nunca atualizar percentis no loop quente de decode por item/pixel;
|
||||
- o job ativo pode expor tempo decorrido e fase atual; percentis sao atualizados
|
||||
apenas no fechamento do job.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [x] A agenda esta madura para virar decisao normativa ou ainda falta algum
|
||||
caso de asset/memcard/lane?
|
||||
- [x] A estrutura minima de `slot_state` e `request_state` no handle esta
|
||||
completa ou falta algum campo para commit/cancel/reorder seguro?
|
||||
|
||||
## Resolucao
|
||||
|
||||
A agenda esta madura para decisao normativa.
|
||||
|
||||
A decisao deve formalizar:
|
||||
|
||||
- a terceira async work lane serial;
|
||||
- um job ativo por vez;
|
||||
- backlog efetivamente limitado pela unicidade de `bank_type/slot`;
|
||||
- handles como observadores estaveis de slots de bank;
|
||||
- `slot_state` e `request_state` dentro do handle;
|
||||
- cancelamento/superseding por novo request para o mesmo alvo;
|
||||
- load pronto imediato quando o asset ja esta residente no alvo;
|
||||
- decode/materializacao na lane async;
|
||||
- commit/install na lane principal;
|
||||
- memcard como consumidor prioritario da mesma lane;
|
||||
- FS como consumidor permitido, deixando API publica de FS para `AGD-0006`;
|
||||
- progresso por fases e percentis atualizados no fechamento do job.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `docs/specs/runtime/09-events-and-concurrency.md`
|
||||
- `docs/specs/runtime/15-asset-management.md`
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md`
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
|
||||
- existencia e papel da terceira async work lane;
|
||||
- relacao dessa lane com a terceira core no hardware alvo e fallback no host;
|
||||
- desenho do backlog serial de asset loading;
|
||||
- regra de cancelamento/substituicao para requests no mesmo bank/slot;
|
||||
- proibicao de `thread::spawn` por load no caminho normal;
|
||||
- fases de asset load que rodam na lane vs lane principal;
|
||||
- inclusao condicionada de FS/memcard nessa mesma lane;
|
||||
- API de consulta e reordenacao do backlog de assets;
|
||||
- comportamento de request imediato quando o asset ja esta residente no alvo;
|
||||
- regra de bounded backlog por unicidade de `bank_type/slot`;
|
||||
- politica de prioridade entre asset, FS e memcard;
|
||||
- status e telemetria para backlog, progresso, percentis, cancelamento e falha.
|
||||
|
||||
## Discussao
|
||||
|
||||
- 2026-06-28: Agenda atualizada para remover render worker do escopo, assumir
|
||||
uma terceira core/lane para trabalhos assincronos, exigir pool/fila limitada
|
||||
para asset loading e reavaliar o papel de FS/memcard como consumidores da
|
||||
mesma lane.
|
||||
- 2026-06-28: Discussao consolidou que a async work lane deve ser serial, com
|
||||
um job ativo, backlog semanticamente ilimitado, consulta/reordenacao publica
|
||||
de backlog de assets, progresso percentual do asset ativo, decode na lane
|
||||
async, install/commit na lane principal, e FS/memcard como consumidores a
|
||||
alinhar com a agenda de app home filesystem.
|
||||
- 2026-06-28: Acrescentada regra de asset pipe: requests para o mesmo bank/slot
|
||||
devem cancelar pedidos anteriores pendentes para aquele alvo, tratando o
|
||||
pedido mais novo como substituto operacional.
|
||||
- 2026-06-28: Discussao refinou que o alvo canonico e `bank_type/slot`; um
|
||||
asset ja residente deve retornar handle pronto sem entrar no backlog; o
|
||||
backlog efetivo e limitado pela soma dos slots dos bancos; FS fica como
|
||||
consumidor permitido da lane, enquanto API publica de FS permanece na agenda
|
||||
6; progresso deve usar fases conservadoras e percentis devem ser atualizados
|
||||
no fechamento do job, nao no hot path.
|
||||
- 2026-06-28: Open questions restantes foram consolidadas: API de backlog
|
||||
aceita com `promote/demote` como atalhos; superseding marca requests
|
||||
substituidos por outro request para o mesmo `bank_type/slot`; cancelamento do
|
||||
ativo e cooperativo quando barato e descarte por geracao quando nao for;
|
||||
`read/decode/stage` cobre GLYPH/SOUND/SCENE; percentis ficam por `bank_type`
|
||||
e por `asset_id`; API publica de FS permanece em `AGD-0006`.
|
||||
- 2026-06-28: Adicionada a expectativa de que handles possam consultar o alvo
|
||||
`bank_type/slot` a qualquer momento, inclusive quando nao houver asset valido
|
||||
carregado; mutacoes devem continuar protegidas por request/geracao para evitar
|
||||
commit/cancel acidental de pedidos substituidos.
|
||||
- 2026-06-28: Refinado o modelo de handle: o handle pertence ao slot do bank e
|
||||
contem uma secao de estado de request/backlog para aquele slot. Consulta e
|
||||
residencia ficam estaveis por alvo; mutacoes atuam sobre a geracao atual do
|
||||
request dentro do handle.
|
||||
@@ -1,126 +0,0 @@
|
||||
---
|
||||
id: AGD-0041
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
|
||||
status: open
|
||||
created: 2026-06-05
|
||||
resolved:
|
||||
decision:
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
Durante a discussao da `DSC-0040` sobre separar VM e render worker, surgiu um caso que nao pertence somente ao render: `Game -> Shell -> Game`.
|
||||
|
||||
O caso minimo e:
|
||||
|
||||
- um Game esta rodando;
|
||||
- o usuario aperta Home;
|
||||
- o Game deve sair do foreground sem ser encerrado;
|
||||
- o Hub/Shell assume a tela;
|
||||
- o usuario pode abrir um app Shell, inclusive VM-backed;
|
||||
- depois o usuario retorna ao mesmo Game.
|
||||
|
||||
O render worker precisa saber qual visual owner pode apresentar frames, mas a decisao principal e de lifecycle: quais VMs existem, quais podem executar, o que significa pausar um Game, e como Shell apps coexistem com um Game pausado.
|
||||
|
||||
Material relacionado:
|
||||
|
||||
- `DSC-0031`: separacao entre perfis Game e System/Shell.
|
||||
- `DSC-0032`: SystemOS como autoridade de lifecycle/process/task.
|
||||
- `DSC-0035`: janelas Shell pertencem a tasks e definem liveness do app.
|
||||
- `DSC-0036`: Hub/Shell prova fatias de lifecycle.
|
||||
- `DSC-0040`: render ownership/epoch durante transicoes e paralelismo VM/render.
|
||||
|
||||
## Problema
|
||||
|
||||
Precisamos definir o contrato de foreground para impedir ambiguidades como:
|
||||
|
||||
- Game pausado continuando a executar frames logicos enquanto Shell esta no foreground;
|
||||
- Shell VM-backed competindo com Game por pacing, input, superficie ou render ownership;
|
||||
- multiplos Shells foreground ou multiplos Games ativos sem uma politica explicita;
|
||||
- retorno ao Game sem clareza sobre estado pausado, input, render invalidation e retomada da VM.
|
||||
|
||||
Sem esse contrato, a separacao VM/render da `DSC-0040` pode ficar tecnicamente correta, mas o SystemOS ainda pode permitir estados incoerentes.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- Existe apenas um foreground visual owner por vez.
|
||||
- Background execution e outro assunto e deve ficar fora da primeira decisao, salvo se for necessario definir uma proibicao explicita.
|
||||
- Shell VM-backed nao deve herdar politica de game loop so por usar VM.
|
||||
- Game pausado provavelmente deve reter estado, mas nao deve consumir frames logicos.
|
||||
- O Hub/Shell precisa ser capaz de rodar enquanto o Game esta suspenso.
|
||||
- A transicao deve invalidar render submissions antigas para impedir present de frames obsoletos.
|
||||
- O modelo precisa caber no SystemOS/lifecycle existente, nao diretamente no render worker.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Foreground unico, Game suspenso, Shell unico
|
||||
|
||||
- **Abordagem:** permitir no maximo um Game carregado e no maximo um Shell foreground; ao apertar Home, o Game entra em estado pausado/suspenso e Shell/Hub assume o foreground. Shell VM-backed pode executar apenas enquanto for o foreground Shell.
|
||||
- **Pro:** modelo simples, previsivel e alinhado com console; reduz concorrencia real entre VMs; combina com a regra de render ownership unico.
|
||||
- **Contra:** nao cobre multitarefa/background; futuras features de overlay ou apps persistentes precisarao expandir o contrato.
|
||||
- **Manutenibilidade:** alta; SystemOS pode modelar uma pilha pequena de foreground/suspended sem virar scheduler generico.
|
||||
|
||||
### Opcao B - Multiplas VMs residentes, somente foreground executa
|
||||
|
||||
- **Abordagem:** permitir que Game e Shell VM-backed coexistam como VMs residentes, mas somente a entidade foreground executa. O Game pausado fica residente, sem tick; Shell VM-backed roda sob lifecycle Shell.
|
||||
- **Pro:** preserva estado e permite retorno rapido; nao exige background execution.
|
||||
- **Contra:** precisa contrato claro de memoria, ownership de input, foco, cancelamento e fechamento.
|
||||
- **Manutenibilidade:** boa se os estados forem explicitos; ruim se a residencia for confundida com execucao em background.
|
||||
|
||||
### Opcao C - Encerrar Game ao entrar no Shell VM-backed
|
||||
|
||||
- **Abordagem:** Home fecha/salva o Game antes de abrir Shell VM-backed, evitando coexistencia.
|
||||
- **Pro:** simplifica o runtime.
|
||||
- **Contra:** quebra a expectativa de console moderno; torna `Game -> Shell -> Game` um reload, nao uma pausa.
|
||||
- **Manutenibilidade:** simples no curto prazo, mas provavelmente gera mais excecoes e UX ruim depois.
|
||||
|
||||
### Opcao D - Background real desde ja
|
||||
|
||||
- **Abordagem:** permitir Game pausado ou Shell apps rodando em background com politicas de prioridade.
|
||||
- **Pro:** cobre casos futuros ricos.
|
||||
- **Contra:** amplia demais escopo: scheduler, budget, energia, audio, input, IO e memoria.
|
||||
- **Manutenibilidade:** baixa para v1; mistura a decisao de foreground com multitarefa real.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendo seguir com a combinacao das opcoes A e B:
|
||||
|
||||
- somente um Game residente por vez;
|
||||
- somente um Shell foreground por vez;
|
||||
- Game pode ficar pausado/suspenso enquanto Shell esta foreground;
|
||||
- Shell VM-backed pode existir junto com Game pausado, mas segue lifecycle Shell;
|
||||
- somente o owner foreground executa VM/tick/event loop conforme sua politica;
|
||||
- background execution fica explicitamente fora de escopo;
|
||||
- render ownership muda junto com foreground owner e deve invalidar submissions antigas via epoch/generation, conforme `DSC-0040`.
|
||||
|
||||
Isso preserva o ciclo `Game -> Home/Shell -> Game` sem transformar o runtime em multitarefa geral agora.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] Qual e o nome canonico dos estados de Game fora do foreground: `Paused`, `Suspended`, ambos, ou outro?
|
||||
- [ ] Ao apertar Home, o Game deve receber um evento/interrupt/trap de pausa antes de parar de executar?
|
||||
- [ ] O Hub e um Shell especial sempre presente ou uma task Shell comum?
|
||||
- [ ] Um app Shell VM-backed pode substituir o Hub no foreground ou o Hub permanece como owner raiz?
|
||||
- [ ] Quando o Shell VM-backed fecha, o retorno vai sempre para Hub ou pode voltar diretamente ao Game?
|
||||
- [ ] O input do Game e drenado/limpo ao pausar e ao retomar?
|
||||
- [ ] Audio do Game pausa junto com a VM ou tem politica propria?
|
||||
- [ ] Existe limite de memoria/residencia para manter Game pausado enquanto Shell app roda?
|
||||
- [ ] O retorno ao Game exige novo frame antes de trocar a superficie, ou a tela pode manter Hub/Shell ate a primeira submission valida?
|
||||
- [ ] Quais eventos de lifecycle precisam ser visiveis para firmware, OS, VM e host?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
A agenda pode ser encerrada quando tivermos uma decisao clara sobre:
|
||||
|
||||
- cardinalidade de Games e Shells residentes/foreground;
|
||||
- semantica de Game pausado/suspenso;
|
||||
- politica de execucao para Shell VM-backed durante Game pausado;
|
||||
- regra de foreground visual owner e render invalidation;
|
||||
- comportamento minimo do ciclo `Game -> Shell -> Game`;
|
||||
- itens explicitamente fora de escopo, especialmente background execution real.
|
||||
|
||||
## Discussao
|
||||
|
||||
- 2026-06-05: Agenda criada a partir da `DSC-0040`, quando o caso de Shell VM-backed aberto sobre um Game pausado mostrou que a discussao pertence ao lifecycle/SystemOS, nao apenas ao render worker.
|
||||
@@ -0,0 +1,208 @@
|
||||
---
|
||||
id: AGD-0048
|
||||
ticket: background-service-audio-execution
|
||||
title: Agenda - Background Service and Audio Execution
|
||||
status: open
|
||||
created: 2026-07-05
|
||||
resolved:
|
||||
decision:
|
||||
tags: [runtime, os, lifecycle, service, audio, background, architecture]
|
||||
---
|
||||
|
||||
# Agenda - Background Service and Audio Execution
|
||||
|
||||
## Contexto
|
||||
|
||||
O runtime ja tem sinais claros de preparacao para multitarefa controlada:
|
||||
|
||||
- `TaskState::Background` existe como estado de tarefa;
|
||||
- `VmSession` separa estado mutavel de VM por tarefa/processo;
|
||||
- `SystemOS` e dono de lifecycle, task/process, VM sessions, filesystem,
|
||||
memcard, windows e logging;
|
||||
- a spec de eventos separa foreground ownership de execution eligibility;
|
||||
- o contrato atual declara que execucao real em background fica fora do v1, mas
|
||||
o modelo foi desenhado para permitir servicos ou processos de midia no futuro.
|
||||
|
||||
O caso motivador e:
|
||||
|
||||
```text
|
||||
Game foreground -> Home -> music player -> escolher musica -> voltar ao Game
|
||||
```
|
||||
|
||||
Depois disso, o Game deve voltar ao foreground enquanto o player continua
|
||||
executando e produzindo audio junto com audio do Game.
|
||||
|
||||
## Problema
|
||||
|
||||
Hoje o runtime preserva sessoes, mas nao tem contrato para uma sessao continuar
|
||||
executando quando nao e foreground.
|
||||
|
||||
Os pontos atuais que bloqueiam o caso:
|
||||
|
||||
- `TaskKind` so distingue `Game` e `Shell`;
|
||||
- `ProcessKind` so distingue `VmGame`, `VmShell` e `NativeShell`;
|
||||
- `ProcessState` nao possui estado normativo de background-running;
|
||||
- `GameRunningStep` ticka apenas o Game foreground;
|
||||
- `ShellRunningStep` ticka apenas o Shell foreground;
|
||||
- `HubHomeStep` nao ticka sessoes VM em background;
|
||||
- `Audio` e `AudioMixer` usam vozes globais sem namespace por tarefa/sessao;
|
||||
- cada logical frame chama `platform.audio_mut().clear_commands()`, o que torna
|
||||
perigoso tickar dois produtores de audio no mesmo frame;
|
||||
- pausa de lifecycle hoje emite `MasterPause`, afetando o mixer inteiro.
|
||||
|
||||
Sem uma decisao, background service pode virar apenas "tickar mais uma VM", mas
|
||||
isso quebraria isolamento, audio, debugger, lifecycle e previsibilidade.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
1. **Execution eligibility nao e foreground.**
|
||||
O contrato atual ja separa os conceitos, mas a implementacao ainda so ticka o
|
||||
owner foreground. Precisamos introduzir uma politica explicita de quem pode
|
||||
executar em background.
|
||||
|
||||
2. **Servico nao e Shell escondido.**
|
||||
Um music player pode ter UI de Shell para escolher musica, mas a reproducao
|
||||
continua como servico quando a UI deixa o foreground. Fechar isso como
|
||||
`Shell` em background confundiria janela, tarefa, sessao e servico.
|
||||
|
||||
3. **Audio precisa de origem.**
|
||||
Hoje `voice_id` e global no mixer. Se Game e player usam `voice_id = 0`, um
|
||||
sobrescreve o outro. Precisamos decidir se o mixer tera namespaces por
|
||||
`AudioOwner`, se servicos terao pool dedicado, ou se o player nao usara a
|
||||
mesma superficie `audio.*`.
|
||||
|
||||
4. **Pausa de Game nao pode pausar servico de midia.**
|
||||
`MasterPause` global serve para o contrato atual de pausa/debug, mas nao
|
||||
expressa "pausar Game audio e manter music player". Pausa precisa virar
|
||||
escopo por origem ou politica de mixer.
|
||||
|
||||
5. **Servico precisa de lifecycle proprio.**
|
||||
Deve existir contrato para start, foreground UI, background-running, stop,
|
||||
crash, terminate, recurso negado, e talvez wake/resume de UI.
|
||||
|
||||
6. **Budget e determinismo precisam ser fechados.**
|
||||
Se servicos rodam junto com Game, precisamos decidir cota por frame, ordem de
|
||||
ticks, starvation, crash isolation, e se background service participa do
|
||||
mesmo tempo deterministico da maquina.
|
||||
|
||||
7. **Sistema de apps precisa descobrir e lancar o player.**
|
||||
Hoje Home lista Game cartridges e tem Shells nativos fixos. O caso de music
|
||||
player exige decidir se ele e cartridge `System`, app instalado, Shell nativo,
|
||||
ou novo perfil `Service`.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Background Service como novo tipo de processo/sessao
|
||||
|
||||
Criar contrato explicito para `Service`:
|
||||
|
||||
- `TaskKind::Service` ou entidade equivalente;
|
||||
- `ProcessKind::VmService` / `NativeService`;
|
||||
- execution eligibility independente de foreground;
|
||||
- UI de controle opcional via Shell task associada ao servico;
|
||||
- audio com origem por service/session;
|
||||
- lifecycle proprio: start, background, foreground-control, stop, crash.
|
||||
|
||||
**Pros:**
|
||||
- modela diretamente music player e futuros servicos;
|
||||
- preserva a separacao entre UI foreground e execucao;
|
||||
- evita transformar Shell em "processo que tambem e daemon";
|
||||
- facilita quotas, permissao e observabilidade.
|
||||
|
||||
**Contras:**
|
||||
- maior mudanca arquitetural;
|
||||
- exige novo contrato em specs, SystemOS, firmware, audio e testes;
|
||||
- precisa fechar politica de recursos antes de implementar.
|
||||
|
||||
**Manutencao:**
|
||||
- melhor base para crescer com qualidade, desde que o MVP seja pequeno.
|
||||
|
||||
### Opcao B - Shell em background com audio permitido
|
||||
|
||||
Permitir que uma VM Shell continue tickando quando sai do foreground e use audio
|
||||
normalmente.
|
||||
|
||||
**Pros:**
|
||||
- reaproveita Shell, WindowManager e VM session existentes;
|
||||
- menor numero de novos tipos no curto prazo.
|
||||
|
||||
**Contras:**
|
||||
- mistura UI e servico;
|
||||
- torna `TaskState::Background` semantico antes de definir `ProcessState`;
|
||||
- abre precedente para qualquer Shell continuar executando;
|
||||
- nao resolve sozinho namespace de audio, pause por origem, quotas e debugging.
|
||||
|
||||
**Manutencao:**
|
||||
- atraente como atalho, mas tende a espalhar excecoes pela firmware state
|
||||
machine.
|
||||
|
||||
### Opcao C - Audio player como servico nativo OS-owned, sem VM background
|
||||
|
||||
Implementar music player como servico nativo de SystemOS, controlado por uma
|
||||
Shell UI. A reproducao continua no host/OS sem tickar VM em background.
|
||||
|
||||
**Pros:**
|
||||
- entrega o caso de musica com menor risco para scheduler VM;
|
||||
- evita abrir execucao arbitraria de background agora;
|
||||
- audio service pode ser projetado como recurso OS-owned e depois exposto.
|
||||
|
||||
**Contras:**
|
||||
- nao resolve background VM services em geral;
|
||||
- player deixa de ser app userland completo no primeiro ciclo;
|
||||
- precisa ainda fechar origem/mixagem de audio e relacao com UI.
|
||||
|
||||
**Manutencao:**
|
||||
- bom MVP se o objetivo imediato for media playback, mas deve ser declarado como
|
||||
`media service` nativo, nao como contrato geral de background VM.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendo fechar em duas camadas:
|
||||
|
||||
1. **Decisao de arquitetura:** introduzir o conceito de service/background
|
||||
execution como contrato de SystemOS, separado de foreground Shell e Game.
|
||||
Essa decisao deve definir execution eligibility, lifecycle, quotas, crash
|
||||
policy, controle de UI e relacao com VM sessions.
|
||||
|
||||
2. **MVP de media:** implementar primeiro um `media/audio service` com escopo
|
||||
reduzido, preferencialmente OS-owned ou `Service` bem delimitado, antes de
|
||||
permitir background VM arbitrario.
|
||||
|
||||
Para excelente qualidade, o primeiro plano nao deve tentar "qualquer app em
|
||||
background". O alvo deve ser: um unico servico de audio/midia, com origem de
|
||||
audio propria, controle por Hub/Shell, execucao enquanto Game esta foreground,
|
||||
e testes end-to-end de mistura e lifecycle.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- O music player deve ser um cartridge `System`, um novo `Service`, ou um
|
||||
servico nativo do OS controlado por Shell?
|
||||
- A UI do player e a reproducao pertencem a mesma tarefa ou a tarefas
|
||||
separadas?
|
||||
- Um servico pode ter janela foreground temporaria e continuar sem janela?
|
||||
- Quantos servicos background podem existir no MVP: um media service ou N
|
||||
servicos?
|
||||
- O background service recebe ticks todo frame, tick rate reduzido, ou apenas
|
||||
eventos?
|
||||
- O audio mixer deve isolar vozes por `TaskId`, `ProcessId`, `VmSessionId`,
|
||||
`AppId`, ou novo `AudioOwner`?
|
||||
- Como pausar apenas o audio do Game durante Home/debug sem pausar musica?
|
||||
- O debugger inspeciona foreground session apenas ou tambem sessoes background?
|
||||
- Como crash de servico e exibido: toast/log, janela de crash, ou parada
|
||||
silenciosa com diagnostico?
|
||||
- Que capacidades sao necessarias para media service: `audio`, `fs`, `asset`,
|
||||
talvez `background_audio`?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
Esta agenda pode virar decisao quando houver resposta escrita para:
|
||||
|
||||
- modelo de entidade (`Service` novo vs Shell background vs native OS service);
|
||||
- execution eligibility e ordem de ticks;
|
||||
- lifecycle e estados de task/process;
|
||||
- ownership/namespace de audio e politica de pausa por origem;
|
||||
- relacao entre UI foreground do player e reproducao background;
|
||||
- escopo do MVP e explicitamente o que fica fora;
|
||||
- testes obrigatorios de lifecycle, audio mixing, crash isolation e regressao do
|
||||
contrato Game/Home/Shell existente.
|
||||
|
||||
@@ -0,0 +1,138 @@
|
||||
---
|
||||
id: AGD-0050
|
||||
ticket: portable-host-backend-strategy
|
||||
title: Portable Host Backend Strategy
|
||||
status: open
|
||||
created: 2026-07-14
|
||||
resolved:
|
||||
decision:
|
||||
tags: [host, desktop, portable, sdl, backend, rendering, input, audio, linux, android, handheld]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
O runtime ja tem uma fronteira de host relativamente clara: o host desktop atual vive em `crates/host/prometeu-host-desktop-winit`, usando `winit`, `pixels` e `cpal` para janela, apresentacao de framebuffer, input e audio.
|
||||
|
||||
A direcao desejada nao e substituir esse host de forma disruptiva no primeiro corte. A proposta e estudar e construir um segundo host portatil para servir como runtime host em handhelds e consoles portateis, especialmente hardwares chineses que rodam Linux internamente e, em alguns casos, Android customizado. O mesmo host tambem deve servir como base para uma futura versao DIY do hardware, desde que ela rode sobre um Linux base compatível. SDL e a hipotese principal, mas a agenda tambem deve avaliar outras familias de host/backend antes de virar decisao normativa.
|
||||
|
||||
Esse novo host deve conviver com o host atual durante estabilizacao, mas nao e descartavel: ele e candidato a se tornar o host principal quando provar paridade e estabilidade.
|
||||
|
||||
A troca deve ficar isolada no dominio de host: contratos de runtime, firmware, frame, input semantico e audio semantico nao devem mudar por causa da escolha de backend. Essa separacao e justamente o objetivo arquitetural que permite que um host portatil evolua para principal sem arrastar o runtime.
|
||||
|
||||
## Problema
|
||||
|
||||
Hoje a existencia de um unico host desktop torna dificil separar problemas do runtime de problemas do adaptador de plataforma. Um novo host portatil pode ajudar em testes, portabilidade, comparacao operacional e reducao de dependencia de uma pilha unica de janela/render/audio. O alvo "mobile" desta agenda nao significa telefone/tablet como produto primario; significa hardware portatil dedicado, geralmente com controles fisicos, framebuffer/display integrado, Linux customizado e distribuicao fora do modelo desktop tradicional. O alvo tambem inclui um possivel handheld DIY futuro, em que o valor esperado e ja existir um host pronto se o dispositivo expuser um Linux base suficiente.
|
||||
|
||||
O risco e tratar uma tecnologia especifica como resposta antes de comparar os requisitos reais de Linux handheld e Android. A agenda precisa cravar o modelo de host paralelo em estabilizacao, com destino de host principal, e entao escolher a familia de backend que melhor atende esse objetivo.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- A troca de host deve ser simples e local ao host, sem exigir mudancas em runtime, firmware, asset protocol, render packet, VM ou syscalls.
|
||||
- O novo host precisa consumir as mesmas saidas canonicas do runtime: frames RGBA8888, comandos semanticos de audio e eventos de input normalizados.
|
||||
- A estrategia deve preservar o host `winit` enquanto o novo host ainda nao provar equivalencia operacional, mas o novo host e candidato a virar o host principal depois dessa prova.
|
||||
- O alvo primario e portabilidade operacional para handhelds Linux e consoles portateis com controles fisicos; Android customizado e um alvo possivel que deve influenciar a escolha de API, packaging e input/audio.
|
||||
- O host portatil deve ser viavel em um futuro hardware DIY rodando Linux base, sem exigir um runtime especial ou fork de contratos.
|
||||
- Testes devem distinguir contrato comum de host de detalhes especificos de backend.
|
||||
- SDL2 pode ter ecossistema Rust mais estabelecido; SDL3 pode estar mais alinhado com a direcao upstream. A escolha da versao e uma pergunta separada da decisao de criar um segundo host.
|
||||
- A arquitetura deve evitar duplicar logica de runtime loop, pacing, debugger, stats e presentation policy quando essa logica for comum a qualquer host.
|
||||
- Outras familias de host tambem devem ser avaliadas: evoluir `winit`, SDL2/SDL3, backend Android nativo, ou uma camada multiplataforma alternativa.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Manter apenas o host winit atual
|
||||
|
||||
- **Abordagem:** continuar evoluindo `prometeu-host-desktop-winit` como unico host desktop.
|
||||
- **Pro:** menor custo imediato; evita nova dependencia nativa.
|
||||
- **Con:** mantem a pilha de plataforma unica como ponto de acoplamento pratico.
|
||||
- **Tradeoff:** bom para estabilidade curta, fraco para provar independencia real do host.
|
||||
|
||||
### Opcao B - Migrar diretamente do host winit para outro backend
|
||||
|
||||
- **Abordagem:** substituir o host desktop atual por um novo backend portatil assim que a escolha tecnologica for feita.
|
||||
- **Pro:** reduz a manutencao para um unico host depois da migracao.
|
||||
- **Con:** aumenta risco de regressao e mistura decisao de backend com mudanca operacional.
|
||||
- **Tradeoff:** so faz sentido depois de prova local de superioridade e paridade, o que ainda nao existe.
|
||||
|
||||
### Opcao C - Criar um host SDL paralelo com destino de principal
|
||||
|
||||
- **Abordagem:** adicionar um novo crate/binario de host SDL que implemente os mesmos contratos externos do host atual, mantendo `winit` como referencia e rollback ate haver evidencia de equivalencia.
|
||||
- **Pro:** permite teste A/B, reduz risco, valida se a fronteira de host esta realmente limpa, atende a meta de handheld Linux/Android customizado/DIY e preserva caminho para tornar SDL o host principal.
|
||||
- **Con:** aumenta temporariamente manutencao e exige fatorar partes comuns se houver duplicacao.
|
||||
- **Tradeoff:** melhor caminho para chegar a um host principal portatil sem reabrir runtime.
|
||||
|
||||
### Opcao D - Evoluir winit/pixels/cpal como host portatil
|
||||
|
||||
- **Abordagem:** manter a familia atual e investir em configuracao, input, fullscreen, packaging e compatibilidade de Linux handheld/Android/DIY dentro dela.
|
||||
- **Pro:** reaproveita o host existente e reduz dependencias nativas novas.
|
||||
- **Con:** pode nao resolver os problemas praticos de distribuicao, gamepad/device handling, fullscreen/scaling, Android customizado e ambientes handheld.
|
||||
- **Tradeoff:** forte se a pilha atual suportar bem os alvos; fraco se o problema real for portabilidade operacional.
|
||||
|
||||
### Opcao E - Host Android nativo separado
|
||||
|
||||
- **Abordagem:** tratar Linux handheld e Android como hosts diferentes: SDL ou winit para Linux; Android com camada nativa/propria quando o alvo amadurecer.
|
||||
- **Pro:** permite respeitar o ciclo de vida, packaging, input e audio do Android sem contaminar o host Linux.
|
||||
- **Con:** duplica mais superficie e adia a promessa de um host portatil unico.
|
||||
- **Tradeoff:** bom se Android tiver requisitos proprios demais; ruim se SDL conseguir cobrir Android bem o bastante.
|
||||
|
||||
### Opcao F - Camada multiplataforma alternativa
|
||||
|
||||
- **Abordagem:** avaliar alternativas como uma camada Rust-first ou game-framework-level para janela, input, audio e render.
|
||||
- **Pro:** pode reduzir FFI nativa e integrar melhor com Cargo.
|
||||
- **Con:** pode ser menos madura para Linux handheld/Android real, packaging e controles.
|
||||
- **Tradeoff:** deve ser considerada, mas precisa provar vantagem concreta sobre SDL para justificar risco.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendacao inicial: manter a **Opcao C** como favorita, mas ampliar a fase de agenda para comparar SDL com as demais familias de host antes da decisao. O resultado desejado continua sendo um segundo host portatil, inicialmente paralelo, com destino explicito de se tornar o host principal quando atingir paridade e estabilidade.
|
||||
|
||||
O caminho recomendado e:
|
||||
|
||||
1. Definir o contrato minimo de equivalencia entre hosts: janela, framebuffer RGBA8888, input, audio, pacing, debugger/logs e encerramento.
|
||||
2. Identificar o que e comum ao host e o que e backend especifico.
|
||||
3. Comparar as familias candidatas contra esse contrato: SDL2, SDL3, winit atual evoluido, Android nativo separado e alternativas Rust-first.
|
||||
4. Implementar o candidato escolhido como novo crate/binario sem remover `prometeu-host-desktop-winit`.
|
||||
5. Permitir troca simples por binario/comando/feature, mantendo o runtime cego para a escolha.
|
||||
6. Tratar handheld Linux como alvo primario de produto para esse host; tratar Android customizado e DIY Linux como restricoes de desenho quando afetarem backend, packaging, input, audio ou boot/runtime integration.
|
||||
7. Promover o novo host a principal apenas depois de evidencia de estabilidade e paridade.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] A primeira implementacao SDL deve usar SDL2 ou SDL3?
|
||||
- [ ] SDL deve ser a familia escolhida, ou winit evoluido, Android nativo separado ou outra camada oferece melhor caminho?
|
||||
- [ ] A selecao do host deve ser por binario separado, feature Cargo, parametro CLI, ou combinacao desses mecanismos?
|
||||
- [ ] Qual e o menor conjunto de comportamento que define paridade aceitavel com o host winit?
|
||||
- [ ] Quais partes do host atual devem virar modulo comum antes do SDL, e quais devem ser duplicadas primeiro para evitar abstracao prematura?
|
||||
- [ ] O host SDL deve reutilizar `cpal` para audio inicialmente ou usar audio SDL desde o primeiro corte?
|
||||
- [ ] Quais familias de hardware handheld Linux devem ser usadas como referencia inicial?
|
||||
- [ ] Handheld Linux exige controles/gamepad, fullscreen, scaling, latency, sleep/resume, framebuffer/display mode ou packaging especificos desde o primeiro corte?
|
||||
- [ ] Qual e o "Linux base" minimo que um futuro hardware DIY precisaria expor para rodar o host portatil sem fork?
|
||||
- [ ] Android customizado deve ser criterio de escolha entre SDL2 e SDL3 agora, ou deve ficar como compatibilidade futura?
|
||||
- [ ] Como validar input e pacing de forma automatizada sem depender de janela real em CI?
|
||||
- [ ] O nome do crate deve ser `prometeu-host-desktop-sdl`, `prometeu-host-desktop-sdl2`, ou algo neutro a versao?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
A agenda pode virar decision quando estiver claro:
|
||||
|
||||
- se o novo host sera paralelo em estabilizacao, com destino de host principal;
|
||||
- qual familia de backend sera alvo inicial;
|
||||
- se SDL for escolhido, qual versao SDL sera alvo inicial;
|
||||
- como a selecao/troca de host deve funcionar;
|
||||
- quais contratos sao comuns e proibidos de mudar;
|
||||
- quais requisitos minimos de handheld Linux e possivel Android customizado entram no primeiro plano;
|
||||
- qual contrato minimo de Linux base mantem aberta a opcao de hardware DIY;
|
||||
- qual evidencia minima prova paridade suficiente para iniciar planos de implementacao.
|
||||
|
||||
## Discussion
|
||||
|
||||
Ponto inicial aceito pelo usuario: a intencao e ter um segundo host para testes, com troca simples e facil, aproveitando o trabalho ja feito para isolar essa troca no host sem envolver runtime ou outros dominios.
|
||||
|
||||
Atualizacao de escopo: o novo host nao e descartavel. O objetivo e servir como runtime host para sistemas Linux rodando em consoles portateis e hardwares handheld chineses, e possivelmente Android customizado. Assim que estiver estavel, ele deve poder virar o host principal.
|
||||
|
||||
Atualizacao de escopo: outras familias de host/backend tambem devem viver nesta agenda. SDL segue como hipotese forte, mas a decisao deve comparar opcoes antes de cravar a tecnologia.
|
||||
|
||||
Clarificacao: "mobile" nesta agenda nao se refere primariamente a telefone/tablet. O foco sao dispositivos portateis dedicados com Linux interno ou Android customizado, geralmente com controles fisicos e ambiente de distribuicao proprio.
|
||||
|
||||
Clarificacao: a agenda tambem deve preservar a opcao de um futuro hardware DIY. A premissa desejada e que, se esse hardware expuser um Linux base suficiente, o runtime ja tenha um host portatil pronto para rodar nele.
|
||||
|
||||
## Resolution
|
||||
@@ -1,336 +0,0 @@
|
||||
---
|
||||
id: DEC-0034
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Async Work Lane and Asset Backlog Contract
|
||||
status: accepted
|
||||
created: 2026-06-28
|
||||
accepted: 2026-06-28
|
||||
ref_agenda: AGD-0008
|
||||
plans: [PLN-0123, PLN-0124, PLN-0125, PLN-0126, PLN-0127, PLN-0128]
|
||||
tags: [perf, asset, fs, async, scheduler, runtime]
|
||||
---
|
||||
|
||||
# DEC-0034 - Async Work Lane and Asset Backlog Contract
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
## Contexto
|
||||
|
||||
`asset.load()` currently creates an OS thread per non-resident asset request.
|
||||
That behavior does not match the target runtime model: the machine should have
|
||||
explicit execution lanes, bounded ownership, observable backpressure, and no
|
||||
uncontrolled thread creation from guest-visible operations.
|
||||
|
||||
Render worker concurrency is already handled by separate render decisions. This
|
||||
decision covers the third runtime lane for asynchronous IO/decode/persistence
|
||||
work:
|
||||
|
||||
```text
|
||||
Lane 1: VM, firmware, SystemOS, logical frame
|
||||
Lane 2: render worker / asynchronous rasterization
|
||||
Lane 3: async work lane for asset IO/decode and game persistence work
|
||||
```
|
||||
|
||||
The concrete first consumer is asset loading. Game persistence through memcard
|
||||
may also consume this lane. FS is allowed to consume this lane, but public FS API
|
||||
shape belongs to the app-home filesystem agenda.
|
||||
|
||||
## Decisao
|
||||
|
||||
Prometeu MUST introduce a third async work lane as the runtime-owned execution
|
||||
place for asset IO/decode work and compatible persistence IO work.
|
||||
|
||||
The async work lane MUST be serial: it has exactly one active job at a time.
|
||||
The runtime MUST NOT create one OS thread per `asset.load` request in the normal
|
||||
path.
|
||||
|
||||
Asset loading MUST use a backlog keyed by target `bank_type/slot`. A target can
|
||||
have at most one current request. A newer request for the same `bank_type/slot`
|
||||
MUST supersede the previous request for that target.
|
||||
|
||||
Asset handles MUST represent stable bank slots, not transient worker threads.
|
||||
A handle MUST remain queryable even when the slot has no valid loaded asset and
|
||||
even when there is no active request for that slot. The handle state MUST
|
||||
separate resident slot state from request/backlog state.
|
||||
|
||||
Asset IO/read and decode/materialization MUST run on the async work lane.
|
||||
Asset install/commit into resident banks MUST happen on the main runtime lane at
|
||||
predictable ownership points.
|
||||
|
||||
Memcard work MAY consume the same async work lane and has higher priority than
|
||||
ordinary asset loads when contention exists. FS MAY consume the same lane for
|
||||
IO-style work, but this decision does not define the public FS API.
|
||||
|
||||
## Rationale
|
||||
|
||||
A serial lane maps cleanly to the intended third-core mental model and avoids a
|
||||
desktop-biased generic thread pool. It gives the runtime one place to observe
|
||||
IO/decode backlog, progress, priority, cancellation, and telemetry.
|
||||
|
||||
Keying requests by `bank_type/slot` makes the backlog naturally bounded by the
|
||||
sum of bank slots. There is no need for a guest-visible `queue_full` state:
|
||||
there cannot be unbounded distinct pending targets if each target has at most
|
||||
one current request.
|
||||
|
||||
Keeping commit/install on the main lane preserves deterministic publication
|
||||
semantics and avoids letting the async lane mutate resident graphics/audio/scene
|
||||
state while the VM, render handoff, or frame boundary is observing it.
|
||||
|
||||
Separating `slot_state` and `request_state` inside the handle avoids ambiguity:
|
||||
callers can inspect the slot at any time, while mutating operations still remain
|
||||
protected by request generation.
|
||||
|
||||
## Invariantes / Contrato
|
||||
|
||||
### Async Work Lane
|
||||
|
||||
- The async work lane MUST be runtime-owned.
|
||||
- The async work lane MUST be separate from the render worker.
|
||||
- The async work lane MUST execute at most one active job at a time.
|
||||
- The runtime MUST NOT use `thread::spawn` per asset request in the normal
|
||||
asset loading path.
|
||||
- The host may implement the lane as a fixed worker thread. Hardware targets may
|
||||
map it to a dedicated core when available.
|
||||
- If a physical third core is unavailable, the implementation MUST preserve the
|
||||
same logical lane contract.
|
||||
|
||||
### Asset Backlog
|
||||
|
||||
- Asset requests MUST target a concrete `bank_type/slot`.
|
||||
- The backlog is ordered and serial.
|
||||
- Each `bank_type/slot` MUST have at most one current request.
|
||||
- A newer request for the same `bank_type/slot` MUST supersede any earlier
|
||||
pending request for that target.
|
||||
- If the target already contains the requested `asset_id` as a valid resident
|
||||
asset, `asset.load` MUST return a handle in ready state without adding a job
|
||||
to the backlog.
|
||||
- The effective backlog size is bounded by the sum of targetable bank slots,
|
||||
even though the contract does not expose a fixed queue limit.
|
||||
- Implementations MUST collect stale metadata for canceled or superseded
|
||||
requests so the handle/request history does not grow without bound.
|
||||
|
||||
### Handles
|
||||
|
||||
An asset handle MUST represent a stable bank slot target. The handle state MUST
|
||||
include at least:
|
||||
|
||||
```text
|
||||
handle:
|
||||
bank_type
|
||||
slot
|
||||
|
||||
slot_state:
|
||||
loaded_asset_id
|
||||
resident_state
|
||||
slot_generation
|
||||
|
||||
request_state:
|
||||
requested_asset_id
|
||||
request_generation
|
||||
state
|
||||
backlog_position
|
||||
progress
|
||||
```
|
||||
|
||||
The handle MUST be queryable when:
|
||||
|
||||
- the slot is empty;
|
||||
- the slot contains a valid resident asset;
|
||||
- a request is queued;
|
||||
- a request is active;
|
||||
- a request is ready for commit;
|
||||
- a request has been canceled;
|
||||
- a request has been superseded;
|
||||
- a request ended in error.
|
||||
|
||||
Mutating operations such as commit, cancel, promote, demote, or move MUST act on
|
||||
the current request generation. They MUST NOT accidentally mutate a newer
|
||||
request through an older handle view.
|
||||
|
||||
### Superseding
|
||||
|
||||
`superseded` means a request was replaced by a newer request for the same
|
||||
`bank_type/slot`.
|
||||
|
||||
- Superseding is an operational state, not a fault.
|
||||
- If the old request is queued, it MUST be removed from the backlog.
|
||||
- If the old request is active, the lane SHOULD cancel cooperatively when the
|
||||
current phase supports cheap cancellation.
|
||||
- If active work cannot be interrupted cheaply, it MAY finish, but its result
|
||||
MUST be discarded when its generation no longer matches the target's current
|
||||
request generation.
|
||||
|
||||
### Asset Backlog API Direction
|
||||
|
||||
The existing asset operations remain the base surface:
|
||||
|
||||
```text
|
||||
asset.load(asset_id, slot) -> (status, handle)
|
||||
asset.status(handle) -> status
|
||||
asset.commit(handle) -> status
|
||||
asset.cancel(handle) -> status
|
||||
```
|
||||
|
||||
The asset backlog surface SHOULD add a small status-first API:
|
||||
|
||||
```text
|
||||
asset.backlog_info()
|
||||
-> (status, pending_count, active_handle, active_asset_id,
|
||||
active_bank_type, active_slot, active_progress)
|
||||
|
||||
asset.backlog_position(handle)
|
||||
-> (status, state, position, progress)
|
||||
|
||||
asset.backlog_move(handle, new_position)
|
||||
-> status
|
||||
|
||||
asset.backlog_promote(handle)
|
||||
-> status
|
||||
|
||||
asset.backlog_demote(handle)
|
||||
-> status
|
||||
|
||||
asset.target_status(bank_type, slot)
|
||||
-> (status, asset_id, handle, state, position, progress)
|
||||
```
|
||||
|
||||
`asset.backlog_promote(handle)` is an official shortcut for moving a queued
|
||||
request to position `1`, the first pending position after the active job.
|
||||
|
||||
`asset.backlog_demote(handle)` is an official shortcut for moving a queued
|
||||
request to the end of the pending backlog.
|
||||
|
||||
The final ABI names and exact return shapes may be refined during planning, but
|
||||
the implementation MUST preserve the capabilities above.
|
||||
|
||||
### Progress
|
||||
|
||||
Progress MUST be represented without floating point. The recommended scale is
|
||||
`0..10000`.
|
||||
|
||||
The initial phase model is:
|
||||
|
||||
```text
|
||||
queued -> 0
|
||||
read -> 0..4000
|
||||
decode -> 4000..9000
|
||||
stage -> 9000..10000
|
||||
ready -> 10000
|
||||
```
|
||||
|
||||
If a phase cannot report internal progress, it MUST keep the previous progress
|
||||
mark and advance at phase completion. Implementations MUST NOT invent false
|
||||
precision for non-linear decode phases.
|
||||
|
||||
### Telemetry
|
||||
|
||||
Telemetry MUST be cheap and must not add hot-path per-item decode cost.
|
||||
|
||||
Minimum telemetry:
|
||||
|
||||
- current backlog depth;
|
||||
- target/request position;
|
||||
- active job progress;
|
||||
- jobs submitted;
|
||||
- jobs completed;
|
||||
- jobs failed;
|
||||
- jobs canceled;
|
||||
- jobs superseded;
|
||||
- job duration;
|
||||
- percentiles by `bank_type`;
|
||||
- lightweight percentiles or small-window samples by `asset_id`.
|
||||
|
||||
Percentiles MUST be updated when a job closes, not inside the inner decode loop.
|
||||
|
||||
### Priority
|
||||
|
||||
When async lane consumers contend, the initial priority order is:
|
||||
|
||||
1. memcard commit/write;
|
||||
2. FS write/config work;
|
||||
3. asset visual/audio/scene load;
|
||||
4. non-critical list/read work.
|
||||
|
||||
This priority order is a lane arbitration rule. It does not define public FS
|
||||
syscall semantics.
|
||||
|
||||
### FS Boundary
|
||||
|
||||
FS MAY consume the async work lane for IO-style work.
|
||||
|
||||
This decision MUST NOT define the public FS API, app-home FS semantics, or
|
||||
whether FS is exposed as request/poll or sync-appearing operations. Those
|
||||
questions belong to `AGD-0006`.
|
||||
|
||||
`AGD-0006` MUST be updated or interpreted with the existence of this async IO
|
||||
lane in mind.
|
||||
|
||||
## Impactos
|
||||
|
||||
### Spec
|
||||
|
||||
- `docs/specs/runtime/15-asset-management.md` must absorb the async lane,
|
||||
backlog, handle, superseding, progress, and telemetry contract.
|
||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md` must absorb any final public
|
||||
asset backlog syscall names and return shapes.
|
||||
- `docs/specs/runtime/16a-syscall-policies.md` may need status catalog updates
|
||||
for superseded/canceled/backend unavailable states if not already covered by
|
||||
asset domain status.
|
||||
- `docs/specs/runtime/09-events-and-concurrency.md` should mention the async
|
||||
work lane as an implementation-side lane that does not introduce guest
|
||||
callbacks.
|
||||
- `AGD-0006` / future FS spec work must account for FS as a possible consumer of
|
||||
the async IO lane.
|
||||
|
||||
### Runtime
|
||||
|
||||
- Asset loading must stop spawning a thread per request.
|
||||
- AssetManager needs a serial backlog keyed by `bank_type/slot`.
|
||||
- Asset handles need stable slot identity plus separated `slot_state` and
|
||||
`request_state`.
|
||||
- Commit/install remains a main-lane operation.
|
||||
- Superseding and generation checks become required correctness mechanisms.
|
||||
|
||||
### Host
|
||||
|
||||
- Desktop host may implement the async work lane with one fixed worker thread.
|
||||
- Host presentation/render worker remains separate and unaffected.
|
||||
|
||||
### Firmware
|
||||
|
||||
- No direct firmware behavior is required for asset backlog mechanics.
|
||||
- Firmware flows that rely on preload or memcard may later use lane telemetry or
|
||||
priority policy if needed.
|
||||
|
||||
### Tooling
|
||||
|
||||
- Test tools may need support for inspecting backlog state and forcing request
|
||||
ordering.
|
||||
- Asset fixtures should cover queued, active, ready, canceled, superseded, and
|
||||
already-resident paths.
|
||||
|
||||
## Referencias
|
||||
|
||||
- `AGD-0008` - Async Background Work Lanes for Assets and FS.
|
||||
- `docs/specs/runtime/15-asset-management.md`
|
||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `docs/specs/runtime/09-events-and-concurrency.md`
|
||||
- `docs/specs/runtime/08-save-memory-and-memcard.md`
|
||||
- `AGD-0006` - App Home Filesystem Surface and Semantics.
|
||||
|
||||
## Propagacao Necessaria
|
||||
|
||||
1. Update asset management specs with the lane/backlog/handle contract.
|
||||
2. Update syscall specs if backlog APIs become public ABI.
|
||||
3. Update FS agenda/spec work to acknowledge the async IO lane without deciding
|
||||
FS public API in this decision.
|
||||
4. Plan implementation of a serial async work lane and asset backlog.
|
||||
5. Plan tests for superseding, stable slot handles, immediate-ready resident
|
||||
assets, progress, telemetry, and main-lane commit.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-06-28: Initial draft from `AGD-0008`.
|
||||
@@ -1,118 +0,0 @@
|
||||
---
|
||||
id: PLN-0123
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Async Work Lane Specification Propagation
|
||||
status: open
|
||||
created: 2026-06-28
|
||||
completed:
|
||||
ref_decisions: [DEC-0034]
|
||||
tags: [perf, asset, fs, async, scheduler, runtime, spec]
|
||||
---
|
||||
|
||||
# PLN-0123 - Async Work Lane Specification Propagation
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0034` establishes a third serial async work lane, asset backlog semantics,
|
||||
stable bank-slot handles, superseding, progress, telemetry, and FS/memcard lane
|
||||
boundaries. The canonical specs must be updated before code work relies on the
|
||||
new contract.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
|
||||
|
||||
## Alvo
|
||||
|
||||
Publish the accepted async work lane and asset backlog contract in the canonical
|
||||
runtime specs.
|
||||
|
||||
## Escopo
|
||||
|
||||
Included:
|
||||
|
||||
- Update asset management spec.
|
||||
- Update syscall ABI spec if public backlog APIs are named there.
|
||||
- Update syscall policy/status language for operational asset states.
|
||||
- Update events/concurrency spec with the async work lane as an implementation
|
||||
lane that does not introduce guest callbacks.
|
||||
- Add a cross-reference from FS/app-home agenda or notes to the async IO lane.
|
||||
|
||||
Fora de Escopo:
|
||||
|
||||
- Implementing runtime code.
|
||||
- Finalizing public FS API semantics.
|
||||
- Changing render worker contracts.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Update Asset Management
|
||||
|
||||
**What:** Add the third async lane, backlog, handle, superseding, progress, and
|
||||
telemetry contract.
|
||||
|
||||
**How:** Extend `docs/specs/runtime/15-asset-management.md` around the existing
|
||||
`asset.load/status/commit/cancel` section. Preserve the existing
|
||||
`asset.load(asset_id, slot)` identity contract.
|
||||
|
||||
**Files:** `docs/specs/runtime/15-asset-management.md`.
|
||||
|
||||
### Step 2 - Update Host ABI
|
||||
|
||||
**What:** Add the backlog API direction if the ABI spec is the canonical place
|
||||
for syscall shapes.
|
||||
|
||||
**How:** Extend the asset surface section with the planned backlog operations,
|
||||
marking exact numeric ids as implementation-plan work if ids are not assigned
|
||||
yet.
|
||||
|
||||
**Files:** `docs/specs/runtime/16-host-abi-and-syscalls.md`.
|
||||
|
||||
### Step 3 - Update Syscall Policies
|
||||
|
||||
**What:** Clarify that `superseded`, `canceled`, `backend_unavailable`, and
|
||||
decode failures are operational statuses, not faults.
|
||||
|
||||
**How:** Add asset-domain examples under status-first policy.
|
||||
|
||||
**Files:** `docs/specs/runtime/16a-syscall-policies.md`.
|
||||
|
||||
### Step 4 - Update Events and Concurrency
|
||||
|
||||
**What:** Document that the async work lane is an implementation lane.
|
||||
|
||||
**How:** Add a section next to render worker concurrency stating that asset/IO
|
||||
lane work does not introduce guest callbacks or hidden guest execution.
|
||||
|
||||
**Files:** `docs/specs/runtime/09-events-and-concurrency.md`.
|
||||
|
||||
### Step 5 - Cross-Reference FS Work
|
||||
|
||||
**What:** Record that FS may consume the async IO lane, while public FS API
|
||||
semantics remain owned by the app-home filesystem discussion.
|
||||
|
||||
**How:** Add a note in `AGD-0006` or its future decision input, without deciding
|
||||
FS request/poll shape in this plan.
|
||||
|
||||
**Files:** `discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md`.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- [ ] Specs state that the async work lane is serial and separate from render.
|
||||
- [ ] Asset spec states backlog keying by `bank_type/slot`.
|
||||
- [ ] Asset spec states stable slot handles with `slot_state` and `request_state`.
|
||||
- [ ] Asset spec states superseding behavior.
|
||||
- [ ] Asset spec states main-lane commit/install.
|
||||
- [ ] FS is cross-referenced as a permitted lane consumer without public API decisions.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- Run `discussion validate`.
|
||||
- Review spec links for broken relative paths.
|
||||
- No cargo tests are required for this documentation-only plan.
|
||||
|
||||
## Riscos
|
||||
|
||||
- Public ABI names may be refined later; the spec must avoid assigning ids too
|
||||
early if implementation work has not reserved them.
|
||||
- FS scope can leak into this work; keep FS public API decisions in `AGD-0006`.
|
||||
@@ -1,119 +0,0 @@
|
||||
---
|
||||
id: PLN-0124
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Async Work Lane Runtime Infrastructure
|
||||
status: open
|
||||
created: 2026-06-28
|
||||
completed:
|
||||
ref_decisions: [DEC-0034]
|
||||
tags: [perf, asset, fs, async, scheduler, runtime]
|
||||
---
|
||||
|
||||
# PLN-0124 - Async Work Lane Runtime Infrastructure
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0034` requires one runtime-owned async work lane, separate from VM/main
|
||||
execution and separate from render worker execution. This plan introduces the
|
||||
lane infrastructure before migrating asset loading.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
|
||||
|
||||
## Alvo
|
||||
|
||||
Create a serial async work lane primitive that can execute one active job at a
|
||||
time, expose observable state, and support deterministic shutdown.
|
||||
|
||||
## Escopo
|
||||
|
||||
Included:
|
||||
|
||||
- Runtime-owned async work lane type.
|
||||
- Single active job execution.
|
||||
- Ordered pending job storage.
|
||||
- Cooperative cancellation hook.
|
||||
- Shutdown and join behavior.
|
||||
- Basic lane telemetry.
|
||||
|
||||
Fora de Escopo:
|
||||
|
||||
- Public asset backlog syscalls.
|
||||
- Asset handle model migration.
|
||||
- FS public API.
|
||||
- Render worker changes.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Locate Runtime Service Boundary
|
||||
|
||||
**What:** Choose the crate/module boundary for the async lane.
|
||||
|
||||
**How:** Place generic lane infrastructure near VM runtime services, not inside
|
||||
desktop host code and not inside render worker modules.
|
||||
|
||||
**Files:** likely `crates/console/prometeu-system/src/services/` or
|
||||
`crates/console/prometeu-system/src/services/vm_runtime/`.
|
||||
|
||||
### Step 2 - Define Job and Lane Types
|
||||
|
||||
**What:** Add a lane type with pending queue, active job metadata, generation,
|
||||
state, progress, and cancellation flag.
|
||||
|
||||
**How:** Use typed job enums or traits that do not require guest callbacks.
|
||||
Start with internal asset job support but keep the lane generic enough for
|
||||
memcard/FS later.
|
||||
|
||||
**Files:** new module under `prometeu-system` service layer.
|
||||
|
||||
### Step 3 - Implement Serial Worker
|
||||
|
||||
**What:** Implement one worker loop that takes one pending job and runs it to
|
||||
completion or cooperative cancellation.
|
||||
|
||||
**How:** Use a fixed worker thread on host builds. Preserve a logical-lane API
|
||||
so future hardware can map it to a dedicated core.
|
||||
|
||||
**Files:** async lane module; lifecycle wiring in VM runtime service setup.
|
||||
|
||||
### Step 4 - Implement Shutdown
|
||||
|
||||
**What:** Add explicit stop/shutdown behavior.
|
||||
|
||||
**How:** Wake the lane, stop accepting new jobs, report pending jobs as canceled
|
||||
or shutdown-discarded, and join the worker with bounded behavior.
|
||||
|
||||
**Files:** async lane module and VM runtime lifecycle modules.
|
||||
|
||||
### Step 5 - Expose Internal Telemetry
|
||||
|
||||
**What:** Add counters for pending depth, active job, submitted, completed,
|
||||
failed, canceled, and superseded.
|
||||
|
||||
**How:** Use cheap atomics or lane-owned state snapshots. Do not update
|
||||
expensive percentile data inside inner decode loops.
|
||||
|
||||
**Files:** async lane module; telemetry structs where runtime telemetry lives.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- [ ] Lane has one active job maximum.
|
||||
- [ ] Lane is separate from render worker code.
|
||||
- [ ] Lane can be started and stopped deterministically.
|
||||
- [ ] Pending jobs are observable.
|
||||
- [ ] Cooperative cancellation can be signaled.
|
||||
- [ ] No guest callback path is introduced.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- Unit tests for enqueue, single active execution, ordering, cancellation signal,
|
||||
and shutdown.
|
||||
- Concurrency tests must synchronize on real state transitions, not sleeps.
|
||||
- Run targeted `cargo test` for the owning crate.
|
||||
|
||||
## Riscos
|
||||
|
||||
- Accidentally creating a generic pool instead of a serial lane.
|
||||
- Coupling the lane to desktop host thread details.
|
||||
- Reusing render worker handoff semantics where ordered backlog is required.
|
||||
@@ -1,127 +0,0 @@
|
||||
---
|
||||
id: PLN-0125
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Asset Backlog and Stable Slot Handles
|
||||
status: open
|
||||
created: 2026-06-28
|
||||
completed:
|
||||
ref_decisions: [DEC-0034]
|
||||
tags: [perf, asset, async, runtime]
|
||||
---
|
||||
|
||||
# PLN-0125 - Asset Backlog and Stable Slot Handles
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0034` changes asset loading from request-owned thread spawning to a serial
|
||||
backlog keyed by `bank_type/slot`. Handles become stable bank-slot observers
|
||||
with separate resident slot state and request state.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
|
||||
|
||||
## Alvo
|
||||
|
||||
Refactor `AssetManager` so asset requests are tracked by target bank slot,
|
||||
deduplicated/superseded by target, and observable through stable handles.
|
||||
|
||||
## Escopo
|
||||
|
||||
Included:
|
||||
|
||||
- Stable handle structure with `bank_type`, `slot`, `slot_state`, and
|
||||
`request_state`.
|
||||
- Backlog keyed by `bank_type/slot`.
|
||||
- Already-resident fast path.
|
||||
- Superseding for queued and active requests.
|
||||
- Main-lane commit/install boundary.
|
||||
|
||||
Fora de Escopo:
|
||||
|
||||
- Public backlog syscall wiring.
|
||||
- Percentile telemetry.
|
||||
- FS public API.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Model Slot Handles
|
||||
|
||||
**What:** Replace transient load-operation assumptions with stable bank-slot
|
||||
handle state.
|
||||
|
||||
**How:** Introduce structures equivalent to:
|
||||
|
||||
```text
|
||||
handle: bank_type, slot
|
||||
slot_state: loaded_asset_id, resident_state, slot_generation
|
||||
request_state: requested_asset_id, request_generation, state, position, progress
|
||||
```
|
||||
|
||||
**Files:** `crates/console/prometeu-drivers/src/asset.rs` and HAL asset types if
|
||||
public type definitions belong there.
|
||||
|
||||
### Step 2 - Key Backlog by Target
|
||||
|
||||
**What:** Ensure at most one current request per `bank_type/slot`.
|
||||
|
||||
**How:** Add a target index from `(bank_type, slot)` to current request
|
||||
generation/handle state. Enqueue only when the target does not already have the
|
||||
same resident asset and no newer request supersedes it.
|
||||
|
||||
**Files:** `crates/console/prometeu-drivers/src/asset.rs`.
|
||||
|
||||
### Step 3 - Implement Already-Resident Fast Path
|
||||
|
||||
**What:** Return a ready handle immediately when the requested asset already
|
||||
resides in the target slot.
|
||||
|
||||
**How:** Compare requested `asset_id` with the target `slot_state.loaded_asset_id`
|
||||
and resident validity before creating a queued job.
|
||||
|
||||
**Files:** `crates/console/prometeu-drivers/src/asset.rs`.
|
||||
|
||||
### Step 4 - Implement Superseding
|
||||
|
||||
**What:** New request for the same target supersedes previous queued or active
|
||||
request.
|
||||
|
||||
**How:** Remove queued older request immediately. For active work, update target
|
||||
generation so the old result is discarded if it cannot stop cooperatively.
|
||||
|
||||
**Files:** `crates/console/prometeu-drivers/src/asset.rs`; async lane module
|
||||
from `PLN-0124`.
|
||||
|
||||
### Step 5 - Preserve Main-Lane Commit
|
||||
|
||||
**What:** Keep install/commit into resident banks on the main runtime lane.
|
||||
|
||||
**How:** Async lane produces staged materialized result. `asset.commit(handle)`
|
||||
installs only when the request generation is current and ready.
|
||||
|
||||
**Files:** `crates/console/prometeu-drivers/src/asset.rs`; VM runtime dispatch if
|
||||
commit behavior changes.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- [ ] No asset load spawns an OS thread per request.
|
||||
- [ ] At most one request exists per `bank_type/slot`.
|
||||
- [ ] Same-target newer request supersedes older queued request.
|
||||
- [ ] Same-target newer request prevents active stale result from installing.
|
||||
- [ ] Already-resident target returns ready handle without backlog entry.
|
||||
- [ ] Handles remain queryable for empty, queued, active, ready, committed,
|
||||
canceled, superseded, and error states.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- Unit tests for handle state transitions.
|
||||
- Unit tests for target-keyed superseding.
|
||||
- Unit tests for already-resident fast path.
|
||||
- Integration test for stale active result discard.
|
||||
- Existing asset load/commit tests must continue passing.
|
||||
|
||||
## Riscos
|
||||
|
||||
- Confusing handle identity with request generation.
|
||||
- Installing a stale async result after superseding.
|
||||
- Losing compatibility with existing `asset.status/commit/cancel` behavior.
|
||||
@@ -1,124 +0,0 @@
|
||||
---
|
||||
id: PLN-0126
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Asset Backlog Public API and Status Surface
|
||||
status: open
|
||||
created: 2026-06-28
|
||||
completed:
|
||||
ref_decisions: [DEC-0034]
|
||||
tags: [perf, asset, async, syscall, runtime]
|
||||
---
|
||||
|
||||
# PLN-0126 - Asset Backlog Public API and Status Surface
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0034` keeps `asset.load/status/commit/cancel` and adds a small status-first
|
||||
backlog inspection and ordering surface. This plan wires that surface through
|
||||
HAL syscall metadata and runtime dispatch.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
|
||||
|
||||
## Alvo
|
||||
|
||||
Expose asset backlog inspection and reordering while preserving status-first
|
||||
semantics and existing asset load identity.
|
||||
|
||||
## Escopo
|
||||
|
||||
Included:
|
||||
|
||||
- Syscall registry additions for backlog APIs.
|
||||
- Runtime dispatch handlers.
|
||||
- Status enum additions or normalization.
|
||||
- ABI/spec alignment with `PLN-0123`.
|
||||
|
||||
Fora de Escopo:
|
||||
|
||||
- Async lane internals.
|
||||
- Asset decode refactor.
|
||||
- FS API.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Finalize Syscall Shapes
|
||||
|
||||
**What:** Choose final names, arity, and return slots for backlog operations.
|
||||
|
||||
**How:** Start from `DEC-0034`:
|
||||
|
||||
```text
|
||||
asset.backlog_info()
|
||||
asset.backlog_position(handle)
|
||||
asset.backlog_move(handle, new_position)
|
||||
asset.backlog_promote(handle)
|
||||
asset.backlog_demote(handle)
|
||||
asset.target_status(bank_type, slot)
|
||||
```
|
||||
|
||||
**Files:** `crates/console/prometeu-hal/src/syscalls/domains/asset.rs`,
|
||||
`docs/specs/runtime/16-host-abi-and-syscalls.md`.
|
||||
|
||||
### Step 2 - Add Status Values
|
||||
|
||||
**What:** Represent `empty`, `invalid`, `queued`, `active`, `ready`,
|
||||
`committed`, `canceled`, `superseded`, `error`, and `backend_unavailable`.
|
||||
|
||||
**How:** Extend or map existing `LoadStatus` and `AssetOpStatus` without
|
||||
turning operational states into traps.
|
||||
|
||||
**Files:** HAL asset status types and `crates/console/prometeu-drivers/src/asset.rs`.
|
||||
|
||||
### Step 3 - Add Dispatch
|
||||
|
||||
**What:** Wire new syscalls through VM runtime dispatch.
|
||||
|
||||
**How:** Add match arms near existing `AssetLoad`, `AssetStatus`,
|
||||
`AssetCommit`, and `AssetCancel` arms. Return status-first values.
|
||||
|
||||
**Files:** `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs`.
|
||||
|
||||
### Step 4 - Implement API Methods
|
||||
|
||||
**What:** Add AssetManager methods backing each public operation.
|
||||
|
||||
**How:** Methods must read stable handle/target state and reorder only queued
|
||||
requests. `promote` and `demote` are shortcuts over move semantics.
|
||||
|
||||
**Files:** `crates/console/prometeu-drivers/src/asset.rs`.
|
||||
|
||||
### Step 5 - Validate ABI Metadata
|
||||
|
||||
**What:** Ensure registry ids, args, returns, capability, cost, and
|
||||
non-deterministic flags are correct.
|
||||
|
||||
**How:** Update syscall metadata tests and any declared PBS/runtime syscall
|
||||
tables.
|
||||
|
||||
**Files:** `crates/console/prometeu-hal/src/syscalls/tests.rs` and related
|
||||
registry files.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- [ ] Public backlog operations are registered with stable metadata.
|
||||
- [ ] All backlog operations are status-first.
|
||||
- [ ] `promote` is equivalent to moving to first pending position.
|
||||
- [ ] `demote` moves to the end of pending backlog.
|
||||
- [ ] Reordering a non-queued request returns operational status.
|
||||
- [ ] Structural ABI misuse remains Trap.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- HAL syscall metadata tests.
|
||||
- VM runtime dispatch tests for each new syscall.
|
||||
- AssetManager unit tests for move/promote/demote.
|
||||
- Tests for `target_status` on empty, queued, active, ready, and superseded
|
||||
targets.
|
||||
|
||||
## Riscos
|
||||
|
||||
- Adding too many public ABI details before spec propagation is accepted.
|
||||
- Returning payload values that are ambiguous when status is not success.
|
||||
- Treating known but non-mutable states as traps instead of statuses.
|
||||
-120
@@ -1,120 +0,0 @@
|
||||
---
|
||||
id: PLN-0127
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Async Lane Memcard and FS Integration Boundaries
|
||||
status: open
|
||||
created: 2026-06-28
|
||||
completed:
|
||||
ref_decisions: [DEC-0034]
|
||||
tags: [perf, fs, memcard, async, runtime]
|
||||
---
|
||||
|
||||
# PLN-0127 - Async Lane Memcard and FS Integration Boundaries
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0034` allows memcard and FS work to consume the async IO lane but keeps
|
||||
public FS API semantics out of scope. This plan establishes integration
|
||||
boundaries without deciding app-home FS API shape.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
|
||||
|
||||
## Alvo
|
||||
|
||||
Define and implement safe internal boundaries for memcard and FS use of the
|
||||
async work lane, preserving lane priority and keeping FS public API decisions in
|
||||
`AGD-0006`.
|
||||
|
||||
## Escopo
|
||||
|
||||
Included:
|
||||
|
||||
- Memcard as a priority lane consumer candidate.
|
||||
- FS as a permitted internal lane consumer.
|
||||
- Priority ordering in the lane.
|
||||
- Updates to `AGD-0006` to acknowledge the lane.
|
||||
|
||||
Fora de Escopo:
|
||||
|
||||
- Public FS request/poll design.
|
||||
- App-home path/status contract.
|
||||
- Full memcard async conversion if it requires public ABI changes.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Update FS Agenda
|
||||
|
||||
**What:** Record that an async IO lane exists and may be used by FS.
|
||||
|
||||
**How:** Add a concise section to `AGD-0006` stating that FS public API remains
|
||||
owned by that agenda, but implementation may use the async lane from `DEC-0034`.
|
||||
|
||||
**Files:** `discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md`.
|
||||
|
||||
### Step 2 - Identify Memcard Operations
|
||||
|
||||
**What:** List memcard operations that can benefit from async IO.
|
||||
|
||||
**How:** Inspect `crates/console/prometeu-system/src/services/memcard.rs` and
|
||||
VM runtime dispatch for `mem.*` operations. Classify read, write, commit, and
|
||||
clear behavior.
|
||||
|
||||
**Files:** memcard service and VM runtime dispatch modules.
|
||||
|
||||
### Step 3 - Define Lane Priority
|
||||
|
||||
**What:** Encode the initial priority order from `DEC-0034`.
|
||||
|
||||
**How:** Add priority classes:
|
||||
|
||||
```text
|
||||
memcard commit/write
|
||||
FS write/config
|
||||
asset load
|
||||
non-critical list/read
|
||||
```
|
||||
|
||||
**Files:** async lane module from `PLN-0124`.
|
||||
|
||||
### Step 4 - Add Internal Consumer Hooks
|
||||
|
||||
**What:** Provide internal APIs for memcard/FS to submit lane jobs later.
|
||||
|
||||
**How:** Add types/interfaces without changing public FS syscall behavior.
|
||||
No public FS request/poll operations are introduced here.
|
||||
|
||||
**Files:** async lane module; FS/memcard service modules as needed.
|
||||
|
||||
### Step 5 - Preserve Current Public Behavior
|
||||
|
||||
**What:** Ensure existing memcard and FS syscalls keep their current observable
|
||||
surface unless a later plan explicitly changes it.
|
||||
|
||||
**How:** Do not alter return shapes in this plan. Add tests proving existing
|
||||
status-first behavior remains intact.
|
||||
|
||||
**Files:** VM runtime FS/memcard tests.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- [ ] `AGD-0006` acknowledges the async IO lane and keeps FS public API in its
|
||||
own scope.
|
||||
- [ ] Async lane supports priority classes required by `DEC-0034`.
|
||||
- [ ] Memcard and FS can be represented as internal lane consumers.
|
||||
- [ ] Existing public memcard/FS syscall shapes are unchanged.
|
||||
- [ ] No FS public request/poll API is introduced by this plan.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- Existing FS/memcard tests continue passing.
|
||||
- Unit tests for lane priority ordering.
|
||||
- Tests proving asset jobs do not overlap with higher-priority memcard jobs
|
||||
once both are submitted through the lane.
|
||||
|
||||
## Riscos
|
||||
|
||||
- Accidentally deciding FS public API in the wrong discussion.
|
||||
- Making memcard async in a way that changes status-first behavior.
|
||||
- Starving asset loads if priority rules do not include fairness.
|
||||
-126
@@ -1,126 +0,0 @@
|
||||
---
|
||||
id: PLN-0128
|
||||
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
||||
title: Async Asset Pipeline Contract Tests and Telemetry
|
||||
status: open
|
||||
created: 2026-06-28
|
||||
completed:
|
||||
ref_decisions: [DEC-0034]
|
||||
tags: [perf, asset, async, telemetry, tests, runtime]
|
||||
---
|
||||
|
||||
# PLN-0128 - Async Asset Pipeline Contract Tests and Telemetry
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0034` requires observable progress, backlog state, superseding, and cheap
|
||||
telemetry. This plan adds the validation and telemetry evidence needed to prove
|
||||
the new async asset pipeline is correct.
|
||||
|
||||
## Decisions de Origem
|
||||
|
||||
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
|
||||
|
||||
## Alvo
|
||||
|
||||
Provide contract tests and telemetry for the async asset lane so future
|
||||
implementations can be changed without regressing lane semantics.
|
||||
|
||||
## Escopo
|
||||
|
||||
Included:
|
||||
|
||||
- Contract tests for lane and asset backlog behavior.
|
||||
- Progress reporting tests.
|
||||
- Superseding and stale result discard tests.
|
||||
- Telemetry counters and percentile updates.
|
||||
- No-sleep deterministic test helpers where needed.
|
||||
|
||||
Fora de Escopo:
|
||||
|
||||
- Implementing public API wiring if `PLN-0126` has not run.
|
||||
- Full benchmarking infrastructure.
|
||||
- Host UI display of telemetry.
|
||||
|
||||
## Plano de Execucao
|
||||
|
||||
### Step 1 - Build Deterministic Test Hooks
|
||||
|
||||
**What:** Add test hooks for blocking a lane job at read/decode/stage.
|
||||
|
||||
**How:** Use channels/barriers or explicit fake job steps. Do not rely on
|
||||
`thread::sleep` for correctness.
|
||||
|
||||
**Files:** async lane tests; asset test support modules.
|
||||
|
||||
### Step 2 - Test Backlog Ordering
|
||||
|
||||
**What:** Prove queued jobs run serially and in backlog order.
|
||||
|
||||
**How:** Submit multiple target slots and assert active job, pending positions,
|
||||
promote, demote, and move behavior.
|
||||
|
||||
**Files:** asset manager tests and lane tests.
|
||||
|
||||
### Step 3 - Test Superseding
|
||||
|
||||
**What:** Prove newer request for the same `bank_type/slot` supersedes older
|
||||
requests.
|
||||
|
||||
**How:** Cover queued superseding and active superseding. For active work, prove
|
||||
stale completion cannot install.
|
||||
|
||||
**Files:** asset manager tests.
|
||||
|
||||
### Step 4 - Test Stable Handle Observability
|
||||
|
||||
**What:** Prove handles are queryable for empty, queued, active, ready,
|
||||
committed, canceled, superseded, and error states.
|
||||
|
||||
**How:** Use `target_status` and handle status APIs to inspect both `slot_state`
|
||||
and `request_state`.
|
||||
|
||||
**Files:** asset manager tests; VM dispatch tests if public API is available.
|
||||
|
||||
### Step 5 - Test Progress
|
||||
|
||||
**What:** Prove progress uses `0..10000` and phase boundaries.
|
||||
|
||||
**How:** Fake read/decode/stage phases with known completion points. Validate
|
||||
non-linear phases do not report false internal progress.
|
||||
|
||||
**Files:** asset manager tests; telemetry tests.
|
||||
|
||||
### Step 6 - Add Telemetry
|
||||
|
||||
**What:** Add counters and percentile aggregation.
|
||||
|
||||
**How:** Update submitted/completed/failed/canceled/superseded counters when job
|
||||
state closes. Update percentiles by `bank_type` and lightweight `asset_id`
|
||||
window only at job completion.
|
||||
|
||||
**Files:** asset manager telemetry, async lane telemetry, existing runtime
|
||||
telemetry types if shared.
|
||||
|
||||
## Criterios de Aceite
|
||||
|
||||
- [ ] Tests prove one active job at a time.
|
||||
- [ ] Tests prove backlog order and reordering.
|
||||
- [ ] Tests prove queued and active superseding.
|
||||
- [ ] Tests prove stale active results are discarded.
|
||||
- [ ] Tests prove handles remain queryable across all required states.
|
||||
- [ ] Tests prove progress phase behavior.
|
||||
- [ ] Telemetry is updated at job closure, not inside inner decode loops.
|
||||
|
||||
## Tests / Validacao
|
||||
|
||||
- Run targeted cargo tests for asset manager, async lane, and VM runtime
|
||||
dispatch.
|
||||
- Run existing asset-bank tests to prove current behavior remains compatible.
|
||||
- Run `discussion validate` after plan state changes.
|
||||
|
||||
## Riscos
|
||||
|
||||
- Tests that depend on sleeps will be flaky.
|
||||
- Telemetry may become too expensive if updated inside decode loops.
|
||||
- Public API tests must wait for `PLN-0126` if syscall wiring is not present.
|
||||
@@ -239,8 +239,10 @@ The same physical surface may be reused by multiple visual owners, but logical
|
||||
ownership MUST remain explicit.
|
||||
|
||||
Game pause/resume, foreground stack behavior, and coexistence of a paused Game
|
||||
with VM-backed Shell apps are outside this contract and are tracked by the
|
||||
foreground/lifecycle discussion.
|
||||
with VM-backed Shell apps are defined by the foreground/lifecycle contract. The
|
||||
render boundary's responsibility is narrower: foreground owner changes MUST
|
||||
advance ownership, stale submissions MUST be discarded, and visual return to a
|
||||
resumed Game MUST wait for a valid submission from the current ownership epoch.
|
||||
|
||||
### 4.7 Render telemetry
|
||||
|
||||
@@ -623,7 +625,8 @@ Each tilemap cell contains:
|
||||
|
||||
Runtime-facing validity rule for v1:
|
||||
|
||||
- `palette_id` values are valid only in the range `0..63`
|
||||
- `palette_id` values are valid only when `palette_id < palette_count` for the
|
||||
resolved resident glyph bank
|
||||
|
||||
#### Sprite
|
||||
|
||||
@@ -638,7 +641,8 @@ Each sprite draw contains:
|
||||
|
||||
Runtime-facing validity rule for v1:
|
||||
|
||||
- `palette_id` values are valid only in the range `0..63`
|
||||
- `palette_id` values are valid only when `palette_id < palette_count` for the
|
||||
referenced resident glyph bank
|
||||
|
||||
---
|
||||
|
||||
@@ -647,7 +651,7 @@ Runtime-facing validity rule for v1:
|
||||
The pipeline works like this:
|
||||
|
||||
1. Read indexed pixel from tile (value 0..15)
|
||||
2. Resolve:
|
||||
2. Validate and resolve:
|
||||
- real_color = palette[palette_id][index]
|
||||
3. Apply:
|
||||
- flip
|
||||
@@ -665,6 +669,9 @@ else:
|
||||
draw_or_blend(color)
|
||||
```
|
||||
|
||||
The `palette_id` lookup above is valid only after the runtime has established
|
||||
that the referenced resident glyph bank contains that palette.
|
||||
|
||||
---
|
||||
|
||||
### 19.7. Organization of Tile Banks
|
||||
@@ -764,6 +771,8 @@ Rules:
|
||||
- missing glyph dependencies referenced by a resident scene are not a passive `status:int` case;
|
||||
- if scene activation discovers that a layer dependency cannot be resolved to a committed glyph asset, the machine MUST fail fatally and emit a clear log;
|
||||
- if scene composition later discovers that a layer dependency can no longer be resolved, the machine MUST fail fatally and emit a clear log;
|
||||
- if scene activation or composition discovers that a tile references `palette_id >= palette_count` for its resolved glyph bank, the machine MUST fail fatally and emit a clear log;
|
||||
- invalid scene palette references are scene dependency failures and MUST NOT be rendered through transparent, black, or default color substitution;
|
||||
- runtime MUST NOT continue canonical scene composition after such a dependency failure.
|
||||
|
||||
### 20.2 `composer.emit_sprite`
|
||||
@@ -772,7 +781,7 @@ Rules:
|
||||
|
||||
ABI:
|
||||
1. `glyph_id: int` — glyph index within the bank
|
||||
2. `palette_id: int` — palette index
|
||||
2. `palette_id: int` — palette index within the referenced bank; valid only when `palette_id < palette_count` for that resident glyph bank
|
||||
3. `x: int` — x coordinate
|
||||
4. `y: int` — y coordinate
|
||||
5. `layer: int` — composition layer reference
|
||||
@@ -795,4 +804,6 @@ Operational notes:
|
||||
- the canonical public sprite contract is frame-emission based;
|
||||
- no caller-provided sprite index exists in the v1 canonical ABI;
|
||||
- no `active` flag exists in the v1 canonical ABI;
|
||||
- `palette_id >= palette_count` for the referenced glyph bank MUST return `BANK_INVALID`;
|
||||
- invalid sprite palette references MUST NOT be rendered through transparent, black, or default color substitution;
|
||||
- overflow remains non-fatal and must not escalate to trap in v1.
|
||||
|
||||
@@ -107,3 +107,21 @@ Input access is VM-owned and should not be reported as host syscall consumption.
|
||||
All platforms must provide the mandatory input elements (`pad`, `touch`, `button`) to the runtime.
|
||||
|
||||
Platform differences in physical device mapping are resolved outside VM semantics.
|
||||
|
||||
## 9 Host/System Controls
|
||||
|
||||
Host/System controls are not part of the guest-visible input surface.
|
||||
|
||||
The Home/SystemOS request changes machine foreground authority. It must be
|
||||
handled by the host, firmware, or SystemOS before input is exposed to the Game.
|
||||
It must not be represented as `pad.start`, `pad.select`, a new pad field, a VM
|
||||
intrinsic, or a userland syscall.
|
||||
|
||||
For the desktop host, `Esc` is the primary keyboard mapping for the
|
||||
Home/SystemOS request. The physical `Home` key may be supported as an alias.
|
||||
Both mappings are host controls and must not mutate `InputSignals`.
|
||||
|
||||
When a Game leaves or re-enters foreground, pending Game input must be cleared
|
||||
or barriered so held or pressed input cannot leak across pause/resume
|
||||
boundaries. This barrier applies to the Game-facing snapshot; it does not
|
||||
change the meaning of host/system Home controls.
|
||||
|
||||
@@ -100,7 +100,89 @@ Important properties:
|
||||
- no execution occurs outside the frame loop;
|
||||
- frame structure remains observable for host tooling and host-owned certification.
|
||||
|
||||
## 7 Render Worker Concurrency
|
||||
## 7 Foreground Lifecycle Events
|
||||
|
||||
Foreground lifecycle events are system events with bounded delivery points.
|
||||
They do not execute arbitrary guest callbacks at arrival time.
|
||||
|
||||
The Game pause path is:
|
||||
|
||||
```text
|
||||
Home/SystemOS request
|
||||
-> pause event becomes visible to the Game
|
||||
-> bounded pause reaction budget
|
||||
-> SystemOS suspension, even if the Game did not cooperate
|
||||
```
|
||||
|
||||
The Game resume path is:
|
||||
|
||||
```text
|
||||
SystemOS resume request
|
||||
-> VM reactivation
|
||||
-> resume or foreground-restore event becomes visible to the Game
|
||||
-> Game may synchronize while still internally paused
|
||||
-> visual foreground returns after a valid current-epoch render submission
|
||||
```
|
||||
|
||||
`Paused` is the Game-visible event/state. `Suspended` is the OS-owned
|
||||
scheduler/runtime state. A Game may observe pause/resume, but it must not
|
||||
control whether SystemOS suspends or resumes the VM.
|
||||
|
||||
When SystemOS replaces one Game with another from Home, the old Game MAY receive
|
||||
a cooperative terminate/save lifecycle event if the runtime supports such an
|
||||
event. That event is non-blocking in v1. SystemOS remains authoritative and may
|
||||
close the old Game task/session without guest acknowledgement.
|
||||
|
||||
Pause budgets are measured in deterministic machine units, not host wall-clock
|
||||
time. A suspended Game receives no normal gameplay ticks, no normal Game input,
|
||||
and no frame pacing. Real background execution is outside the v1 foreground
|
||||
contract.
|
||||
|
||||
## 8 VM Sessions and Execution Eligibility
|
||||
|
||||
Every VM-backed process MUST own a distinct VM session. A VM session owns the
|
||||
mutable execution context for that process, including the VM instance,
|
||||
per-session runtime counters, lifecycle delivery bookkeeping, debug/pause state,
|
||||
and transient handles opened through VM-facing services.
|
||||
|
||||
Foreground ownership and execution eligibility are related but separate
|
||||
concepts:
|
||||
|
||||
- foreground ownership selects the visual/navigation owner;
|
||||
- execution eligibility selects which sessions may receive VM ticks;
|
||||
- v1 grants normal VM execution only to the foreground VM-backed task, plus the
|
||||
bounded Game pause handoff tick defined above;
|
||||
- a suspended resident Game preserves its VM session but MUST NOT receive
|
||||
normal gameplay ticks, normal Game input, or frame pacing;
|
||||
- a VM-backed Shell owns its own VM session and MUST NOT overwrite or advance
|
||||
the resident Game session while the Shell is foreground;
|
||||
- a native Shell does not own a VM session.
|
||||
|
||||
The model is intentionally compatible with future background execution. Future
|
||||
service or media processes may become execution-eligible without changing the
|
||||
rule that mutable VM context belongs to the owning session. This chapter does
|
||||
not grant any v1 background progress guarantee.
|
||||
|
||||
Durable app data remains keyed by `app_id` where the relevant storage contract
|
||||
requires it. Transient VM handles, open files, lifecycle delivery queues, and
|
||||
staging state are session-scoped unless another spec explicitly makes them
|
||||
durable app data.
|
||||
|
||||
During destructive Game replacement, the old Game VM session MUST be removed
|
||||
from execution eligibility and resumable state before the new Game becomes the
|
||||
foreground Game. The new Game MUST receive a fresh VM session. Failure while
|
||||
loading or initializing the replacement Game MUST return the machine to
|
||||
Hub/Home and MUST NOT restore the previous Game in v1.
|
||||
|
||||
Manual Hub termination of a suspended resident Game has the same session
|
||||
removal authority as destructive Game replacement, except that no replacement
|
||||
Game is started. SystemOS MUST remove the Game from execution eligibility and
|
||||
resumable state, close its task, stop its process, remove its VM session, clear
|
||||
task-scoped pending lifecycle delivery, and keep Hub/Home as the foreground
|
||||
owner. After manual Hub termination, resume queries MUST report no resident
|
||||
Game. A later launch of the same cartridge is a fresh Game session.
|
||||
|
||||
## 9 Render Worker Concurrency
|
||||
|
||||
The render worker is not a machine-visible event source and does not introduce
|
||||
guest callbacks. It is an implementation-side consumer of closed render
|
||||
@@ -127,7 +209,31 @@ Shutdown is explicit and bounded. A shutdown request wakes a waiting worker,
|
||||
causes pending work that will not be consumed to be discarded, and reports a
|
||||
typed failure if the worker cannot join within the configured timeout.
|
||||
|
||||
## 8 Determinism and Best Practices
|
||||
## 10 Async Asset and IO Work Lane
|
||||
|
||||
The asset/IO async work lane is not a machine-visible event source and does not
|
||||
introduce guest callbacks. It is an implementation-side lane for asset
|
||||
IO/decode/materialization and compatible persistence IO work.
|
||||
|
||||
The lane is serial:
|
||||
|
||||
- it has at most one active job;
|
||||
- it keeps an ordered backlog;
|
||||
- it is separate from the render worker;
|
||||
- it must not create one OS thread per guest-visible asset request.
|
||||
|
||||
Asset jobs are keyed by target `bank_type/slot`. A newer request for the same
|
||||
target supersedes the older request. Superseding is an operational status and
|
||||
does not execute guest code.
|
||||
|
||||
Asset install/commit into resident banks happens on the main runtime lane at
|
||||
predictable ownership points. The async lane prepares materialized results; it
|
||||
does not publish resident graphics/audio/scene state directly.
|
||||
|
||||
FS and game persistence services may consume this lane for IO-style work, but
|
||||
public FS API shape is defined by the FS/app-home contract, not by this chapter.
|
||||
|
||||
## 11 Determinism and Best Practices
|
||||
|
||||
PROMETEU encourages:
|
||||
|
||||
@@ -142,7 +248,7 @@ PROMETEU discourages:
|
||||
- hidden timing channels;
|
||||
- ambiguous out-of-band execution.
|
||||
|
||||
## 9 Relationship to Other Specs
|
||||
## 12 Relationship to Other Specs
|
||||
|
||||
- [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) defines coroutine lifecycle and scheduling behavior.
|
||||
- [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) defines observability and diagnostics surfaces.
|
||||
|
||||
@@ -44,6 +44,11 @@ PROMETEU operates in three main modes:
|
||||
|
||||
No mode alters the logical result of the program.
|
||||
|
||||
Debug boot is a host-selected direct cartridge boot profile. It follows the same
|
||||
cartridge/app-mode resolution path as direct boot and is separate from
|
||||
Home-driven Game switching. Debug boot MUST NOT be modeled as a guest-visible
|
||||
Game switch request and MUST NOT reuse a Home switch failure-recovery contract.
|
||||
|
||||
## 3 Execution Control
|
||||
|
||||
### 3.1 Pause and Resume
|
||||
|
||||
@@ -39,13 +39,32 @@ The VM does not own the machine lifecycle. Firmware does.
|
||||
`Hub`, `Task(TaskId)`, and `Overlay`.
|
||||
- **Shell task window**: a `WindowManager` window whose owner is
|
||||
`WindowOwner::Task(TaskId)`.
|
||||
- **Games root**: a host-provided local directory used by Hub/Home to discover
|
||||
Game directory cartridges.
|
||||
- **Library entry**: an internal catalog record retained by Hub/SystemOS for a
|
||||
discovered cartridge.
|
||||
- **Game switch target**: a SystemOS-owned launch target derived from a library
|
||||
entry. It carries the cartridge path plus resolved identity such as `app_id`,
|
||||
`title`, and `app_version`.
|
||||
- **Foreground visual owner**: the single machine owner whose visual output may
|
||||
be presented at a given time.
|
||||
- **Paused**: a Game-visible lifecycle event/state. The Game may observe it and
|
||||
prepare for foreground loss.
|
||||
- **Suspended**: an OS-owned scheduler/runtime state. A suspended Game remains
|
||||
resident but does not receive normal gameplay ticks, normal Game input, or
|
||||
frame pacing.
|
||||
- **VM session**: the POS-owned mutable execution context for one VM-backed
|
||||
process. It contains the VM instance and per-session runtime state.
|
||||
- **Hub resident Game kill control**: a Hub/Home affordance that terminates the
|
||||
current resident Game instead of resuming it.
|
||||
|
||||
## 3 POS Responsibilities
|
||||
|
||||
POS is responsible for:
|
||||
|
||||
- deterministic reset into known machine state;
|
||||
- VM initialization and teardown for cartridge execution;
|
||||
- VM session creation, initialization, activation, and teardown for cartridge
|
||||
execution;
|
||||
- input latching and logical-frame budgeting;
|
||||
- peripheral reset/orchestration;
|
||||
- fault capture and crash-flow transition;
|
||||
@@ -57,6 +76,10 @@ At the VM boundary, POS must preserve:
|
||||
- `FRAME_SYNC` as the canonical frame boundary;
|
||||
- deterministic transition from host tick to VM slice execution.
|
||||
|
||||
Firmware must not treat a single global VM object as the canonical execution
|
||||
owner for all cartridges. The firmware state machine orchestrates macro-state;
|
||||
POS/session services own VM-backed process context.
|
||||
|
||||
## 4 PrometeuHub Responsibilities
|
||||
|
||||
PrometeuHub is responsible for:
|
||||
@@ -65,9 +88,22 @@ PrometeuHub is responsible for:
|
||||
- reading cartridge metadata needed for launch decisions;
|
||||
- deciding launch behavior based on `AppMode`;
|
||||
- managing the system window surface for system-mode apps.
|
||||
- presenting the host-provided local games library when `--games-root <dir>` is
|
||||
configured;
|
||||
- emitting system-owned launch actions for selected Home entries.
|
||||
- presenting a resident Game kill control while Hub/Home owns foreground and a
|
||||
Game is resident/suspended.
|
||||
|
||||
The Hub does not execute bytecode directly. It always delegates execution setup to POS.
|
||||
|
||||
For v1, the local games library is Game-only. Hub/Home must not expose Shell or
|
||||
System cartridges from the games root. The internal library entry must retain
|
||||
the loaded manifest data, `title`, `app_id`, `app_version`, the cartridge path,
|
||||
and discovery metadata such as a timestamp or equivalent discovery marker.
|
||||
|
||||
The Home UI may display only `title`, `app_id`, and `app_version`. Path and
|
||||
operational metadata may remain internal.
|
||||
|
||||
## 5 App Modes
|
||||
|
||||
### Game
|
||||
@@ -139,22 +175,148 @@ Shell task loses its eligible focused window
|
||||
-> FirmwareState::HubHome
|
||||
```
|
||||
|
||||
## 7 Cartridge Load Flow
|
||||
## 7 Foreground Stack and Game Pause
|
||||
|
||||
The v1 foreground contract is single-owner:
|
||||
|
||||
- exactly one foreground visual owner exists at a time;
|
||||
- at most one Game may be resident;
|
||||
- at most one Shell app may be foreground;
|
||||
- Hub/Home is the root Shell owner and back-stack controller.
|
||||
|
||||
The minimal supported navigation cycle is:
|
||||
|
||||
```text
|
||||
Game foreground
|
||||
-> Home request
|
||||
-> Game pause notification
|
||||
-> Game suspended by SystemOS after a bounded budget
|
||||
-> Hub/Home foreground
|
||||
-> optional Shell foreground
|
||||
-> Shell close returns to Hub/Home
|
||||
-> same Game resume/foreground-restore notification
|
||||
-> Game foreground after a valid current-epoch render submission
|
||||
```
|
||||
|
||||
`Paused` is cooperative and visible to the Game. `Suspended` is imposed by
|
||||
SystemOS. The Game may react to pause/resume, but it must not control whether
|
||||
the OS suspends or resumes its VM.
|
||||
|
||||
When Home is requested during Game execution, SystemOS must notify the Game and
|
||||
grant a short bounded pause budget. After the budget, SystemOS may suspend the
|
||||
VM even if the Game did not cooperate. While suspended, the Game must not
|
||||
receive normal gameplay ticks, normal Game input, or frame pacing.
|
||||
|
||||
When returning to the same Game, SystemOS must reactivate the VM and send a
|
||||
resume or foreground-restore notification before visual foreground is restored.
|
||||
The Game may remain internally paused while it synchronizes. Hub/Shell remains
|
||||
visible until the resumed Game publishes a valid render submission for the
|
||||
current ownership epoch.
|
||||
|
||||
Input pending for the Game must be cleared or barriered across pause/resume
|
||||
boundaries. Game audio pauses with the Game VM in v1. Independent background
|
||||
audio, real background execution, multiple resident Games, multiple foreground
|
||||
Shells, and direct Game-to-Game switching are outside this contract.
|
||||
|
||||
The resident Game VM session remains allocated while Hub or Shell is foreground.
|
||||
It preserves Game VM state but is not execution-eligible except for the bounded
|
||||
pause handoff and later foreground resume. A VM-backed Shell has a separate VM
|
||||
session. A native Shell has no VM session.
|
||||
|
||||
When Hub/Home is foreground and a Game cartridge remains resident/suspended,
|
||||
PrometeuHub MUST render a red control in the bottom-right of the Hub viewport.
|
||||
The control MUST display only the resident Game title. It MUST NOT be rendered
|
||||
for no resident Game, Shell tasks, System tasks, or native Shell tasks.
|
||||
|
||||
Clicking the Hub resident Game kill control is a system-owned immediate
|
||||
termination request. Firmware MUST keep the user in Hub/Home, MUST NOT ask for
|
||||
confirmation in v1, and MUST NOT resume the killed Game on subsequent Home
|
||||
actions. The control MUST disappear on the next Hub frame after the resident
|
||||
Game is no longer present.
|
||||
|
||||
## 8 Cartridge Load Flow
|
||||
|
||||
Current high-level flow:
|
||||
|
||||
1. POS receives a cartridge to load;
|
||||
2. asset manager is initialized from the cartridge asset table, preload list, and packed asset bytes;
|
||||
3. POS initializes the VM/runtime for the cartridge;
|
||||
4. launch behavior branches by `AppMode`:
|
||||
3. POS creates or selects the VM session for the cartridge;
|
||||
4. POS initializes the session-owned VM/runtime for the cartridge;
|
||||
5. launch behavior branches by `AppMode`:
|
||||
- `Game` -> transition to the game-running firmware state;
|
||||
- `System` -> create/focus a Hub window and return to the Hub state.
|
||||
|
||||
If VM initialization fails, firmware transitions to the crash path.
|
||||
|
||||
For v1, POS must enforce at most one resident Game session. Selecting the same
|
||||
resident Game from Home resumes that session. Selecting a different Game from
|
||||
Home is a SystemOS-owned Game switch and MUST be destructive replacement:
|
||||
|
||||
```text
|
||||
Game A resident
|
||||
-> Hub/Home selected Game B with different app_id
|
||||
-> SystemOS terminates Game A resident task/session
|
||||
-> SystemOS removes Game A from resumable state
|
||||
-> firmware loads Game B through LoadCartridge
|
||||
-> Game B receives a fresh VM session
|
||||
```
|
||||
|
||||
SystemOS MUST NOT create a second resident Game session. SystemOS MUST NOT
|
||||
reuse the old Game VM session, transient VM handles, pending lifecycle delivery
|
||||
state, render ownership, debug pause state, or crash/debug runtime state for the
|
||||
new Game. Durable app data remains governed by the relevant storage specs and
|
||||
may still be keyed by `app_id`.
|
||||
|
||||
SystemOS MAY emit a cooperative non-blocking terminate/save lifecycle event
|
||||
before closing the old Game when such an event exists. Replacement MUST NOT
|
||||
block on that event in v1. VM-backed Shell loading creates a distinct Shell
|
||||
session and must not overwrite resident Game VM state.
|
||||
|
||||
Manual Hub resident Game kill and destructive different-Game replacement MUST
|
||||
share the canonical resident-Game termination path. That path MUST:
|
||||
|
||||
- close the resident Game task;
|
||||
- mark its process stopped;
|
||||
- remove its VM session;
|
||||
- clear resident Game state and pending Game lifecycle delivery for that task;
|
||||
- keep or return foreground ownership to Hub/Home;
|
||||
- transition render ownership to Shell/Hub (`AppMode::Shell`, `app_id = 0`);
|
||||
- clear the Game lifecycle audio pause state;
|
||||
- unbind the Game2D frame composer scene;
|
||||
- shut down cartridge-scoped asset manager state, including slot identity and
|
||||
physical glyph/scene/sound banks.
|
||||
|
||||
After this operation, the killed Game MUST NOT be resumable. Launching that
|
||||
same Game again from Home is a fresh cartridge load and a fresh VM session.
|
||||
Manual Hub kill MUST emit an INFO Hub log with the message shape:
|
||||
|
||||
```text
|
||||
Resident game killed from Hub: <title>
|
||||
```
|
||||
|
||||
POS selects the cartridge and its execution context, but the cartridge's initial callable is not chosen by firmware metadata. Execution starts from the cartridge boot protocol defined in [`13-cartridge.md`](13-cartridge.md), currently `func_id = 0`.
|
||||
|
||||
## 8 Firmware States
|
||||
When Home launches a discovered Game entry, the request is a system-owned action
|
||||
from PrometeuHub to POS/firmware. Firmware must load the selected cartridge
|
||||
through the normal cartridge loader and transition to `LoadCartridge` on
|
||||
success. This path must not use a guest syscall and must not reintroduce
|
||||
userland `run_cart`.
|
||||
|
||||
If the selected cartridge cannot be loaded, firmware must leave or return the
|
||||
machine in the Hub/Home flow and record the failure through diagnostics or
|
||||
logging. A polished Home error surface is not required by v1.
|
||||
|
||||
If a destructive Game switch has already begun and the new Game fails to load or
|
||||
initialize, firmware MUST return to Hub/Home, MUST discard any partial new Game
|
||||
task/session/window/render/input/audio state, and MUST NOT restore the previous
|
||||
Game. Direct boot and debug boot failures remain governed by the boot profile
|
||||
that requested them and may still transition to the crash path.
|
||||
|
||||
Switch validation MUST include two distinct Game cartridges. The current
|
||||
repository evidence uses `Stress Console` and `Dummy Boy`; those cartridges are
|
||||
test evidence, not required runtime features.
|
||||
|
||||
## 9 Firmware States
|
||||
|
||||
The current firmware state model includes:
|
||||
|
||||
@@ -164,11 +326,12 @@ The current firmware state model includes:
|
||||
- `HubHome`
|
||||
- `LoadCartridge`
|
||||
- `GameRunning`
|
||||
- `ShellRunning`
|
||||
- `AppCrashes`
|
||||
|
||||
These states express machine orchestration above the VM. They are not guest-visible bytecode states.
|
||||
|
||||
## 9 Execution Contract
|
||||
## 10 Execution Contract
|
||||
|
||||
For game-mode execution, firmware/runtime coordination preserves:
|
||||
|
||||
@@ -179,7 +342,7 @@ For game-mode execution, firmware/runtime coordination preserves:
|
||||
|
||||
This keeps the machine model deterministic and observable.
|
||||
|
||||
## 10 Crash Handling
|
||||
## 11 Crash Handling
|
||||
|
||||
Firmware owns terminal fault presentation.
|
||||
|
||||
@@ -191,7 +354,35 @@ When a terminal app fault occurs:
|
||||
|
||||
Crash handling is outside the guest VM execution model.
|
||||
|
||||
## 11 Relationship to Other Specs
|
||||
## 12 Desktop Smoke Validation
|
||||
|
||||
The foreground contract can be smoke-tested on the desktop host with:
|
||||
|
||||
```text
|
||||
cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console
|
||||
cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
|
||||
- direct `--run` still boots the selected Game without using a guest cartridge
|
||||
switching API;
|
||||
- `--games-root` starts in Home and launches Games through the Home library;
|
||||
- while a Game is running, `Esc` opens Home/SystemOS without entering the guest
|
||||
pad input surface;
|
||||
- the Game is paused, then suspended after the bounded SystemOS budget;
|
||||
- Home remains foreground while the Game is resident;
|
||||
- launching and closing a Shell app returns to Home without losing the resident
|
||||
Game;
|
||||
- a VM-backed Shell advances its own VM session and does not tick the suspended
|
||||
resident Game session;
|
||||
- returning to the same Game resumes it through the foreground lifecycle and
|
||||
waits for current-epoch Game rendering before visual Game presentation.
|
||||
- clicking the red bottom-right resident Game kill control terminates the
|
||||
resident Game, keeps Home foreground, clears runtime/cartridge residue, and
|
||||
removes the resume path.
|
||||
|
||||
## 13 Relationship to Other Specs
|
||||
|
||||
- [`02-vm-instruction-set.md`](02-vm-instruction-set.md) defines the VM subsystem run by firmware.
|
||||
- [`09-events-and-concurrency.md`](09-events-and-concurrency.md) defines the frame-boundary model used by firmware.
|
||||
|
||||
@@ -175,10 +175,38 @@ Runtime loading policy:
|
||||
|
||||
This is the working runtime/dev form used by the current loader.
|
||||
|
||||
Directory cartridges are also the only form discovered by the v1 local Home
|
||||
games library. When a host provides `--games-root <dir>`, discovery scans only
|
||||
immediate child directories under that root. Each child directory is a candidate
|
||||
cartridge.
|
||||
|
||||
For the v1 Home games library:
|
||||
|
||||
- a candidate must have a valid `manifest.json`;
|
||||
- the manifest must declare `app_mode: "Game"`;
|
||||
- the library retains the loaded manifest data, `title`, `app_id`,
|
||||
`app_version`, the internal cartridge path, and discovery metadata;
|
||||
- the library entry identity is the input to the SystemOS Game switch target;
|
||||
- `app_id` is the v1 identity used to distinguish same-Game resume from
|
||||
different-Game destructive replacement;
|
||||
- invalid candidates are logged or reported as diagnostics and omitted from the
|
||||
Home list;
|
||||
- valid non-Game cartridges are omitted from the Game library.
|
||||
|
||||
Discovery reads metadata for cataloging. It does not replace the normal
|
||||
cartridge loader used when firmware starts the selected cartridge.
|
||||
|
||||
Selecting a discovered Game from Home is not cartridge self-execution and is not
|
||||
guest-controlled. The cartridge path is consumed by firmware/SystemOS, which
|
||||
owns same-Game resume, different-Game replacement, failure recovery, and VM
|
||||
session creation policy.
|
||||
|
||||
### Packaged `.pmc` form
|
||||
|
||||
This form is recognized conceptually by the loader boundary, but its actual load path is not implemented yet.
|
||||
|
||||
Packaged `.pmc` cartridges are not discovered by the v1 Home games library.
|
||||
|
||||
The cartridge spec therefore distinguishes:
|
||||
|
||||
- supported current load form;
|
||||
|
||||
@@ -18,6 +18,9 @@ enum BootTarget {
|
||||
|
||||
This is a firmware/host orchestration contract, not a guest-visible ABI.
|
||||
|
||||
The local Home games library is not a separate firmware boot target. It is host
|
||||
configuration consumed by the Hub profile after boot.
|
||||
|
||||
## 2 Boot Modes
|
||||
|
||||
### Hub
|
||||
@@ -27,6 +30,10 @@ When the boot target is `Hub`:
|
||||
- firmware boots into the Hub flow;
|
||||
- no cartridge is auto-launched.
|
||||
|
||||
If the host also provides `--games-root <dir>`, the Hub may discover and render
|
||||
valid Game cartridges from that root. Selecting one is a system-owned Home
|
||||
action that requests cartridge loading after the Hub is already running.
|
||||
|
||||
### Cartridge
|
||||
|
||||
When the boot target is `Cartridge`:
|
||||
@@ -43,6 +50,8 @@ For a cartridge boot target:
|
||||
- `Game` cartridges transition into the game-running pipeline;
|
||||
- `System` cartridges transition into a Runtime/Hub pipeline dedicated to
|
||||
system UI and app hosting.
|
||||
- VM-backed cartridges are initialized in a POS-owned VM session associated with
|
||||
the created task/process.
|
||||
|
||||
This preserves the distinction between machine firmware state and app execution mode.
|
||||
|
||||
@@ -59,9 +68,53 @@ Typical host-facing boot intents are:
|
||||
- default start -> enter Hub;
|
||||
- run cartridge -> boot with cartridge target;
|
||||
- debug cartridge -> boot with cartridge target plus debug mode parameters.
|
||||
- games-root start -> enter Hub with a local Game library for Home.
|
||||
|
||||
The CLI is an entry surface for boot target selection; the firmware contract remains the same underneath.
|
||||
|
||||
Host CLI, debugger, and equivalent single-game launch flows are the supported
|
||||
direct cartridge boot surfaces. Direct boot is not requested by guest bytecode
|
||||
through a `system.run_cart` syscall or any other app-callable cartridge boot
|
||||
ABI.
|
||||
|
||||
`--run <cart>` and `--debug <cart>` are direct cartridge boot profiles. They
|
||||
select one cartridge before normal Hub/Home interaction and remain independent
|
||||
from the local library.
|
||||
|
||||
`--games-root <dir>` is a Hub/Home library configuration. It does not
|
||||
auto-launch a cartridge and does not create a guest-visible launch API.
|
||||
|
||||
The v1 games root contract is:
|
||||
|
||||
- the root contains directory cartridges as immediate child directories;
|
||||
- recursive discovery is not performed;
|
||||
- only valid cartridges whose manifest declares `app_mode: "Game"` are listed;
|
||||
- Shell/System apps, packaged `.pmc` cartridges, remote catalogs, marketplace
|
||||
metadata, search, icons, and rich presentation are outside this profile;
|
||||
- invalid candidates are logged and omitted from the Home list;
|
||||
- Home entries may display only `title`, `app_id`, and `app_version`;
|
||||
- selecting a Home entry requests firmware/SystemOS loading for that cartridge
|
||||
and transitions through `LoadCartridge`;
|
||||
- launch failure leaves or returns the machine to Home and records an error.
|
||||
|
||||
Game-to-game switching after a game is already active is not a boot profile.
|
||||
That orchestration belongs to the foreground/home and cartridge switch
|
||||
contracts. In that path, SystemOS owns the switch policy: selecting the same
|
||||
resident Game resumes it, while selecting a different Game performs destructive
|
||||
replacement and creates a fresh VM session for the new Game.
|
||||
|
||||
The foreground/home contract defines `Game -> Home/Shell -> same Game` after a
|
||||
Game is already running. It does not change direct `--run`, debugger direct
|
||||
boot, or `--games-root` Home library startup semantics. Home/SystemOS requests
|
||||
are host/system controls, not guest cartridge boot APIs.
|
||||
|
||||
Direct boot creates the initial VM session for the selected cartridge. It does
|
||||
not create a reusable global VM shared by later Game or Shell cartridges.
|
||||
Direct boot and debug boot MUST NOT be treated as failed-switch recovery paths:
|
||||
load or initialization failures for direct boot may transition to the crash
|
||||
flow, while Home-driven switch failures return to Home and do not restore the
|
||||
previous Game.
|
||||
|
||||
## 5 Firmware State Relationship
|
||||
|
||||
Boot target selection feeds into firmware states such as:
|
||||
@@ -90,7 +143,26 @@ When booting a cartridge in debug mode:
|
||||
|
||||
Debug mode changes orchestration, not the cartridge contract.
|
||||
|
||||
## 7 Relationship to Other Specs
|
||||
## 7 Smoke Validation
|
||||
|
||||
The local Home library path should be smoke tested in release mode for realistic
|
||||
interactive speed:
|
||||
|
||||
```sh
|
||||
cargo run --release -p prometeu-host-desktop-winit -- --games-root test-cartridges
|
||||
```
|
||||
|
||||
Direct single-cartridge boot remains a separate validation path:
|
||||
|
||||
```sh
|
||||
cargo run --release -p prometeu-host-desktop-winit -- --run test-cartridges/stress-console
|
||||
```
|
||||
|
||||
Game switch validation should cover the Home-driven two-cartridge path, for
|
||||
example `Stress Console -> Home -> Dummy Boy`, and assert that the first Game is
|
||||
not resumable after replacement.
|
||||
|
||||
## 8 Relationship to Other Specs
|
||||
|
||||
- [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) defines the firmware state machine that consumes boot targets.
|
||||
- [`13-cartridge.md`](13-cartridge.md) defines cartridge structure.
|
||||
|
||||
@@ -115,7 +115,7 @@ For `BankType::GLYPH`, the v1 runtime-facing contract is:
|
||||
- `codec = NONE`
|
||||
- serialized pixels use packed `u4` palette indices
|
||||
- serialized palettes use `RGBA8888` with canonical RGBA channel order
|
||||
- `palette_count = 64`
|
||||
- `palette_count` is the number of serialized and resident palettes and must be in `1..=64`
|
||||
- runtime materialization may expand pixel indices to one `u8` per pixel
|
||||
|
||||
For `GLYPH`, `NONE` means there is no additional generic codec layer beyond the bank contract itself.
|
||||
@@ -136,7 +136,7 @@ Required effective metadata fields for `GLYPH` at the root level:
|
||||
- `tile_size`: tile edge in pixels; valid values are `8`, `16`, or `32`
|
||||
- `width`: total sheet width in pixels
|
||||
- `height`: total sheet height in pixels
|
||||
- `palette_count`: number of serialized palettes for the bank
|
||||
- `palette_count`: number of serialized palettes and resident runtime palettes for the bank
|
||||
|
||||
Optional informative subtrees:
|
||||
|
||||
@@ -145,7 +145,7 @@ Optional informative subtrees:
|
||||
|
||||
Validation rules for `GLYPH` v1:
|
||||
|
||||
- `palette_count` must be `64`
|
||||
- `palette_count` must be in the inclusive range `1..=64`
|
||||
- `width * height` defines the number of logical indexed pixels in the decoded sheet
|
||||
- extra metadata may exist, but the runtime contract must not depend on it to reconstruct the in-memory bank unless that data is defined at the root as an effective field.
|
||||
|
||||
@@ -158,7 +158,16 @@ The tile-bank payload therefore separates serialized storage form from runtime m
|
||||
|
||||
- serialized pixel plane: packed `4bpp`
|
||||
- decoded pixel plane: expanded `u8` indices, one entry per pixel
|
||||
- palette table: `64 * 16` colors in RGBA8888 channel order
|
||||
- palette table: `palette_count * 16` colors in RGBA8888 channel order
|
||||
|
||||
For `GLYPH` v1:
|
||||
|
||||
```text
|
||||
serialized_pixel_bytes = ceil(width * height / 2)
|
||||
palette_bytes = palette_count * 16 * 4
|
||||
size = serialized_pixel_bytes + palette_bytes
|
||||
decoded_size = (width * height) + palette_bytes
|
||||
```
|
||||
|
||||
For `GLYPH` v1:
|
||||
|
||||
@@ -172,6 +181,11 @@ before they are loaded by the runtime.
|
||||
Palette indices are ordinary indices. Transparency is represented by the alpha
|
||||
channel of the resolved RGBA8888 palette entry, not by reserving index `0`.
|
||||
|
||||
`palette_id` is valid only when it is lower than the referenced resident glyph
|
||||
bank's `palette_count`. Canonical runtime composition MUST NOT substitute
|
||||
transparent, black, or any other default color for `palette_id >=
|
||||
palette_count`.
|
||||
|
||||
### 4.2 `SCENE` asset contract in v1
|
||||
|
||||
For `BankType::SCENE`, the v1 runtime-facing contract is:
|
||||
@@ -393,14 +407,129 @@ Fault boundary:
|
||||
|
||||
Rules:
|
||||
|
||||
- `handle` is valid only when `load` status is `OK`;
|
||||
- `handle` is returned when `load` status is `OK`;
|
||||
- `handle` represents a stable bank slot target, not a worker thread;
|
||||
- a known handle remains queryable even when the slot is empty, has no active
|
||||
request, or has a superseded request;
|
||||
- failed `load` returns `handle = 0`;
|
||||
- `commit` and `cancel` must not be silent no-op for unknown/invalid handle state.
|
||||
- `asset.load` resolves the target bank type from `asset_table` using `asset_id`;
|
||||
- public callers must not supply `asset_name` or `bank_type` to `asset.load`;
|
||||
- slot validation and residency/lifecycle rejection remain in `asset` status space and are not delegated to `bank`.
|
||||
|
||||
### 11.2 Minimum status tables
|
||||
### 11.2 Async work lane and backlog
|
||||
|
||||
Asset loading uses the runtime async work lane. This lane is separate from the
|
||||
VM/main lane and separate from the render worker lane.
|
||||
|
||||
The asset async lane is serial:
|
||||
|
||||
- it executes at most one active asset job at a time;
|
||||
- it keeps an ordered backlog of pending requests;
|
||||
- it must not create one OS thread per `asset.load` request.
|
||||
|
||||
Asset requests are keyed by the target `bank_type/slot`.
|
||||
|
||||
Rules:
|
||||
|
||||
- each `bank_type/slot` has at most one current request;
|
||||
- a newer request for the same `bank_type/slot` supersedes the previous request;
|
||||
- if the previous request is queued, it is removed from the backlog;
|
||||
- if the previous request is active, the lane should cancel cooperatively when
|
||||
the current phase supports cheap cancellation;
|
||||
- if active work cannot stop cheaply, it may finish, but the result must be
|
||||
discarded when its generation no longer matches the target request generation;
|
||||
- if the target already contains the requested `asset_id` as a valid resident
|
||||
asset, `asset.load` returns a ready handle without adding a backlog entry.
|
||||
|
||||
The effective backlog size is bounded by the sum of targetable bank slots,
|
||||
because only one current request can exist per `bank_type/slot`. The runtime
|
||||
does not expose a guest-visible `queue_full` status for the normal asset
|
||||
backlog path.
|
||||
|
||||
### 11.3 Handle state
|
||||
|
||||
An asset handle observes one stable bank slot target. Its observable state has
|
||||
two parts:
|
||||
|
||||
```text
|
||||
handle:
|
||||
bank_type
|
||||
slot
|
||||
|
||||
slot_state:
|
||||
loaded_asset_id
|
||||
resident_state
|
||||
slot_generation
|
||||
|
||||
request_state:
|
||||
requested_asset_id
|
||||
request_generation
|
||||
state
|
||||
backlog_position
|
||||
progress
|
||||
```
|
||||
|
||||
`slot_state` describes what is currently resident in the target slot.
|
||||
`request_state` describes the current or most recent request for that target.
|
||||
|
||||
Mutating operations such as commit, cancel, promote, demote, and move must act
|
||||
on the current request generation. They must not accidentally mutate a newer
|
||||
request through an older handle view.
|
||||
|
||||
### 11.4 Backlog inspection and ordering
|
||||
|
||||
The asset backlog surface may expose these status-first operations:
|
||||
|
||||
- `asset.backlog_info() -> (status, pending_count, active_handle, active_asset_id, active_bank_type, active_slot, active_progress)`
|
||||
- `asset.backlog_position(handle) -> (status, state, position, progress)`
|
||||
- `asset.backlog_move(handle, new_position) -> status`
|
||||
- `asset.backlog_promote(handle) -> status`
|
||||
- `asset.backlog_demote(handle) -> status`
|
||||
- `asset.target_status(bank_type, slot) -> (status, asset_id, handle, state, position, progress)`
|
||||
|
||||
`asset.backlog_promote(handle)` is a shortcut for moving a queued request to
|
||||
position `1`, the first pending position after the active job.
|
||||
|
||||
`asset.backlog_demote(handle)` is a shortcut for moving a queued request to the
|
||||
end of the pending backlog.
|
||||
|
||||
### 11.5 Progress and telemetry
|
||||
|
||||
Asset progress uses integer progress, not floating point. The preferred scale is
|
||||
`0..10000`.
|
||||
|
||||
The initial phase model is:
|
||||
|
||||
```text
|
||||
queued -> 0
|
||||
read -> 0..4000
|
||||
decode -> 4000..9000
|
||||
stage -> 9000..10000
|
||||
ready -> 10000
|
||||
```
|
||||
|
||||
If a phase cannot report internal progress, it keeps the previous progress mark
|
||||
and advances at phase completion. The runtime must not invent false precision
|
||||
for non-linear decode phases.
|
||||
|
||||
Minimum telemetry:
|
||||
|
||||
- current backlog depth;
|
||||
- target/request position;
|
||||
- active job progress;
|
||||
- jobs submitted;
|
||||
- jobs completed;
|
||||
- jobs failed;
|
||||
- jobs canceled;
|
||||
- jobs superseded;
|
||||
- job duration;
|
||||
- percentiles by `bank_type`;
|
||||
- lightweight percentiles or small-window samples by `asset_id`.
|
||||
|
||||
Percentiles are updated when a job closes, not inside the inner decode loop.
|
||||
|
||||
### 11.6 Minimum status tables
|
||||
|
||||
`asset.load` request statuses:
|
||||
|
||||
@@ -418,9 +547,16 @@ Rules:
|
||||
- `4` = `CANCELED`
|
||||
- `5` = `ERROR`
|
||||
- `6` = `UNKNOWN_HANDLE`
|
||||
- `7` = `QUEUED`
|
||||
- `8` = `ACTIVE`
|
||||
- `9` = `SUPERSEDED`
|
||||
- `10` = `EMPTY`
|
||||
- `11` = `INVALID`
|
||||
- `12` = `BACKEND_UNAVAILABLE`
|
||||
|
||||
`asset.commit` and `asset.cancel` operation statuses:
|
||||
|
||||
- `0` = `OK`
|
||||
- `1` = `UNKNOWN_HANDLE`
|
||||
- `2` = `INVALID_STATE`
|
||||
- `3` = `SUPERSEDED`
|
||||
|
||||
@@ -52,6 +52,11 @@ This identity is:
|
||||
|
||||
Input queries are VM-owned intrinsic calls in v1 and are outside the syscall identity space.
|
||||
|
||||
Cartridge boot is also outside the guest syscall identity space. A cartridge,
|
||||
Shell app, or other userland guest must not declare or call `system.run_cart`.
|
||||
Direct cartridge boot is a host/system boot-profile entrypoint, not an
|
||||
app-callable syscall.
|
||||
|
||||
Syscall identity is transport, not the conceptual boundary for runtime
|
||||
profiles. `Game` and `System` may both use syscall transport internally or at
|
||||
their ABI edge, but that does not make their public authoring surfaces the same
|
||||
@@ -60,6 +65,12 @@ dedicated `System` profile ABI and stdlib/framework.
|
||||
|
||||
## 3 Syscall Resolution
|
||||
|
||||
PBX, Prometeu Bytecode Executable, is the runtime executable bytecode format.
|
||||
Its canonical file magic is `PBX\0`. The former PBS-prefixed magic is not valid
|
||||
for PBX artifacts: PBS names a frontend language, while PBX names the executable
|
||||
artifact accepted by the runtime. This distinction is required because Prometeu
|
||||
bytecode can be produced by multiple frontends.
|
||||
|
||||
The host maintains a registry:
|
||||
|
||||
```
|
||||
@@ -182,6 +193,11 @@ The game memcard profile uses module `mem` with status-first return shapes.
|
||||
The `mem` module is a game profile surface. It is not the public storage model
|
||||
for `System` profile apps.
|
||||
|
||||
Durable memcard data is keyed by `app_id` according to the save-memory
|
||||
contract. Runtime handles, open file tables, pending lifecycle delivery, and
|
||||
other mutable VM-facing syscall context are scoped to the owning VM session and
|
||||
MUST NOT be used as durable app identity.
|
||||
|
||||
Canonical operations in v1 are:
|
||||
|
||||
- `mem.slot_count() -> (status, count)`
|
||||
@@ -203,6 +219,12 @@ Canonical operations in v1 are:
|
||||
- `asset.status(handle) -> status`
|
||||
- `asset.commit(handle) -> status`
|
||||
- `asset.cancel(handle) -> status`
|
||||
- `asset.backlog_info() -> (status, pending_count, active_handle, active_asset_id, active_bank_type, active_slot, active_progress)`
|
||||
- `asset.backlog_position(handle) -> (status, state, position, progress)`
|
||||
- `asset.backlog_move(handle, new_position) -> status`
|
||||
- `asset.backlog_promote(handle) -> status`
|
||||
- `asset.backlog_demote(handle) -> status`
|
||||
- `asset.target_status(bank_type, slot) -> (status, asset_id, handle, state, position, progress)`
|
||||
|
||||
For `asset.load`:
|
||||
|
||||
@@ -210,6 +232,18 @@ For `asset.load`:
|
||||
- `slot` is the target slot index;
|
||||
- bank kind is resolved from `asset_table` by `asset_id`, not supplied by the caller.
|
||||
|
||||
Asset handles represent stable bank slot targets. A handle can be queried even
|
||||
when its slot has no resident asset or active request. Internally the handle
|
||||
state separates resident `slot_state` from current `request_state`.
|
||||
|
||||
The asset backlog is keyed by `bank_type/slot`. New requests for the same target
|
||||
supersede older requests for that target. `superseded` is an operational status,
|
||||
not a structural trap.
|
||||
|
||||
`asset.backlog_promote(handle)` and `asset.backlog_demote(handle)` are
|
||||
convenience operations over backlog movement. They do not introduce a second
|
||||
ordering model.
|
||||
|
||||
### Bank diagnostics surface (`bank`, v1)
|
||||
|
||||
`DEC-0009` narrows the public bank contract:
|
||||
|
||||
@@ -44,6 +44,9 @@ Normal operational success and operational failure conditions should be represen
|
||||
Examples:
|
||||
|
||||
- asset not yet loaded;
|
||||
- asset request queued or active;
|
||||
- asset request superseded by a newer request for the same bank slot;
|
||||
- asset backend unavailable;
|
||||
- audio voice unavailable;
|
||||
- persistent storage full.
|
||||
|
||||
@@ -107,6 +110,11 @@ Game memcard operations (`mem.*`) are status-first and use `fs` capability in v1
|
||||
`mem` remains layered on runtime `fs`; no parallel persistence channel is introduced.
|
||||
Domain surface, status catalog and slot semantics are defined in [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md).
|
||||
|
||||
Asset backlog operations are status-first. `queued`, `active`, `ready`,
|
||||
`canceled`, `superseded`, `empty`, `invalid`, decode failure, and backend
|
||||
unavailability are operational results. They must not be reclassified as `Trap`
|
||||
unless the caller violates the structural ABI contract.
|
||||
|
||||
## 3 Interaction with the Garbage Collector
|
||||
|
||||
The VM heap and host-managed memory are separate.
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
# Dummy Boy
|
||||
|
||||
Regenerate this cartridge with:
|
||||
|
||||
```sh
|
||||
cargo run -p pbxgen-dummy-boy
|
||||
```
|
||||
|
||||
Dummy Boy is a minimal visual Game cartridge used by runtime switch tests. It
|
||||
clears the frame and draws a centered square whose fill color cycles
|
||||
deterministically across frames.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user