Compare commits
50
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
89101d1b20
|
||
|
|
2516fae4fc | ||
|
|
e0c08c8b00
|
||
|
|
5b106af0f3 | ||
|
|
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
|
Generated
+21
@@ -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"
|
||||
@@ -1664,6 +1674,17 @@ dependencies = [
|
||||
"winit",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "prometeu-host-headless"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"prometeu-bytecode",
|
||||
"prometeu-drivers",
|
||||
"prometeu-firmware",
|
||||
"prometeu-hal",
|
||||
"prometeu-system",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "prometeu-layer-tests"
|
||||
version = "0.1.0"
|
||||
|
||||
@@ -7,7 +7,9 @@ members = [
|
||||
"crates/console/prometeu-system",
|
||||
"crates/console/prometeu-vm",
|
||||
"crates/host/prometeu-host-desktop-winit",
|
||||
"crates/host/prometeu-host-headless",
|
||||
"crates/tools/prometeu-cli",
|
||||
"crates/tools/pbxgen-dummy-boy",
|
||||
"crates/tools/pbxgen-stress",
|
||||
"crates/dev/prometeu-test-support",
|
||||
"crates/dev/prometeu-layer-tests",
|
||||
|
||||
@@ -135,6 +135,7 @@ Current canonical domains:
|
||||
- `asset/bank`
|
||||
- `firmware`
|
||||
- `host-dependent`
|
||||
- `host/headless`
|
||||
|
||||
Global coverage artifacts:
|
||||
|
||||
@@ -157,6 +158,7 @@ Domain-oriented evidence helpers:
|
||||
make coverage-domain-list
|
||||
make coverage-domain-evidence DOMAIN=firmware
|
||||
make coverage-domain-evidence DOMAIN=host-dependent
|
||||
make coverage-domain-evidence DOMAIN=host/headless
|
||||
```
|
||||
|
||||
Per-domain baselines currently start around `60`.
|
||||
|
||||
@@ -11,14 +11,14 @@ mod program_image;
|
||||
mod value;
|
||||
|
||||
pub use abi::{
|
||||
TrapInfo, TRAP_BAD_RET_SLOTS, TRAP_DIV_ZERO, TRAP_EXPLICIT, TRAP_ILLEGAL_INSTRUCTION,
|
||||
TRAP_INVALID_FUNC, TRAP_INVALID_INTRINSIC, TRAP_INVALID_LOCAL, TRAP_INVALID_SYSCALL, TRAP_OOB,
|
||||
TRAP_STACK_UNDERFLOW, TRAP_TYPE,
|
||||
SourceSpan, TrapInfo, TRAP_BAD_RET_SLOTS, TRAP_DIV_ZERO, TRAP_EXPLICIT,
|
||||
TRAP_ILLEGAL_INSTRUCTION, TRAP_INVALID_FUNC, TRAP_INVALID_INTRINSIC, TRAP_INVALID_LOCAL,
|
||||
TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_STACK_UNDERFLOW, TRAP_TYPE,
|
||||
};
|
||||
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
|
||||
|
||||
@@ -191,10 +191,10 @@ impl GlyphAssetSlotIndex {
|
||||
}
|
||||
}
|
||||
|
||||
const GLYPH_BANK_PALETTE_COUNT_V1: usize = 64;
|
||||
const GLYPH_BANK_MAX_PALETTE_COUNT_V1: usize = 64;
|
||||
const GLYPH_BANK_COLORS_PER_PALETTE: usize = 16;
|
||||
const GLYPH_BANK_PALETTE_BYTES_V1: usize =
|
||||
GLYPH_BANK_PALETTE_COUNT_V1 * GLYPH_BANK_COLORS_PER_PALETTE * size_of::<u32>();
|
||||
const GLYPH_BANK_PALETTE_BYTES_PER_PALETTE: usize =
|
||||
GLYPH_BANK_COLORS_PER_PALETTE * size_of::<u32>();
|
||||
|
||||
/// Resident metadata for a decoded/materialized asset inside a BankPolicy.
|
||||
#[derive(Debug)]
|
||||
@@ -599,7 +599,7 @@ impl AssetBridge for AssetManager {
|
||||
impl AssetManager {
|
||||
fn decode_glyph_bank_layout(
|
||||
entry: &AssetEntry,
|
||||
) -> Result<(TileSize, usize, usize, usize), String> {
|
||||
) -> Result<(TileSize, usize, usize, usize, usize, usize), String> {
|
||||
let meta = entry.metadata_as_glyph_bank()?;
|
||||
|
||||
let tile_size = match meta.tile_size {
|
||||
@@ -609,7 +609,8 @@ impl AssetManager {
|
||||
_ => return Err(format!("Invalid tile_size: {}", meta.tile_size)),
|
||||
};
|
||||
|
||||
if meta.palette_count as usize != GLYPH_BANK_PALETTE_COUNT_V1 {
|
||||
let palette_count = meta.palette_count as usize;
|
||||
if !(1..=GLYPH_BANK_MAX_PALETTE_COUNT_V1).contains(&palette_count) {
|
||||
return Err(format!("Invalid palette_count: {}", meta.palette_count));
|
||||
}
|
||||
|
||||
@@ -618,12 +619,14 @@ impl AssetManager {
|
||||
|
||||
let logical_pixels = width.checked_mul(height).ok_or("GlyphBank dimensions overflow")?;
|
||||
let serialized_pixel_bytes = logical_pixels.div_ceil(2);
|
||||
let palette_bytes = palette_count
|
||||
.checked_mul(GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
|
||||
.ok_or("GlyphBank palette size overflow")?;
|
||||
let serialized_size = serialized_pixel_bytes
|
||||
.checked_add(GLYPH_BANK_PALETTE_BYTES_V1)
|
||||
.checked_add(palette_bytes)
|
||||
.ok_or("GlyphBank serialized size overflow")?;
|
||||
let decoded_size = logical_pixels
|
||||
.checked_add(GLYPH_BANK_PALETTE_BYTES_V1)
|
||||
.ok_or("GlyphBank decoded size overflow")?;
|
||||
let decoded_size =
|
||||
logical_pixels.checked_add(palette_bytes).ok_or("GlyphBank decoded size overflow")?;
|
||||
|
||||
if entry.size != serialized_size as u64 {
|
||||
return Err(format!(
|
||||
@@ -639,7 +642,7 @@ impl AssetManager {
|
||||
));
|
||||
}
|
||||
|
||||
Ok((tile_size, width, height, serialized_pixel_bytes))
|
||||
Ok((tile_size, width, height, serialized_pixel_bytes, palette_count, palette_bytes))
|
||||
}
|
||||
|
||||
fn unpack_glyph_bank_pixels(packed_pixels: &[u8], logical_pixels: usize) -> Vec<u8> {
|
||||
@@ -1200,19 +1203,18 @@ impl AssetManager {
|
||||
entry: &AssetEntry,
|
||||
buffer: &[u8],
|
||||
) -> Result<GlyphBank, String> {
|
||||
let (tile_size, width, height, packed_pixel_bytes) = Self::decode_glyph_bank_layout(entry)?;
|
||||
if buffer.len() < packed_pixel_bytes + GLYPH_BANK_PALETTE_BYTES_V1 {
|
||||
let (tile_size, width, height, packed_pixel_bytes, palette_count, palette_bytes) =
|
||||
Self::decode_glyph_bank_layout(entry)?;
|
||||
if buffer.len() < packed_pixel_bytes + palette_bytes {
|
||||
return Err("Buffer too small for GLYPHBANK".to_string());
|
||||
}
|
||||
|
||||
let logical_pixels = width * height;
|
||||
let packed_pixels = &buffer[0..packed_pixel_bytes];
|
||||
let pixel_indices = Self::unpack_glyph_bank_pixels(packed_pixels, logical_pixels);
|
||||
let palette_data =
|
||||
&buffer[packed_pixel_bytes..packed_pixel_bytes + GLYPH_BANK_PALETTE_BYTES_V1];
|
||||
let palette_data = &buffer[packed_pixel_bytes..packed_pixel_bytes + palette_bytes];
|
||||
|
||||
let mut palettes =
|
||||
[[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1];
|
||||
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
|
||||
for (p, pal) in palettes.iter_mut().enumerate() {
|
||||
for (c, slot) in pal.iter_mut().enumerate() {
|
||||
let offset = (p * 16 + c) * 4;
|
||||
@@ -1232,7 +1234,8 @@ impl AssetManager {
|
||||
entry: &AssetEntry,
|
||||
reader: &mut impl Read,
|
||||
) -> Result<GlyphBank, String> {
|
||||
let (tile_size, width, height, packed_pixel_bytes) = Self::decode_glyph_bank_layout(entry)?;
|
||||
let (tile_size, width, height, packed_pixel_bytes, palette_count, palette_bytes) =
|
||||
Self::decode_glyph_bank_layout(entry)?;
|
||||
let logical_pixels = width * height;
|
||||
let mut packed_pixels = vec![0_u8; packed_pixel_bytes];
|
||||
reader
|
||||
@@ -1241,13 +1244,12 @@ impl AssetManager {
|
||||
|
||||
let pixel_indices = Self::unpack_glyph_bank_pixels(&packed_pixels, logical_pixels);
|
||||
|
||||
let mut palette_data = [0_u8; GLYPH_BANK_PALETTE_BYTES_V1];
|
||||
let mut palette_data = vec![0_u8; palette_bytes];
|
||||
reader
|
||||
.read_exact(&mut palette_data)
|
||||
.map_err(|_| "Buffer too small for GLYPHBANK".to_string())?;
|
||||
|
||||
let mut palettes =
|
||||
[[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; GLYPH_BANK_PALETTE_COUNT_V1];
|
||||
let mut palettes = vec![[Color::BLACK; GLYPH_BANK_COLORS_PER_PALETTE]; palette_count];
|
||||
for (p, pal) in palettes.iter_mut().enumerate() {
|
||||
for (c, slot) in pal.iter_mut().enumerate() {
|
||||
let offset = (p * 16 + c) * 4;
|
||||
@@ -1858,6 +1860,9 @@ impl AssetManager {
|
||||
self.glyph_slot_index.clear();
|
||||
self.sound_slots.write().unwrap().fill(None);
|
||||
self.scene_slots.write().unwrap().fill(None);
|
||||
self.gfx_installer.clear_glyph_banks();
|
||||
self.sound_installer.clear_sound_banks();
|
||||
self.scene_installer.clear_scene_banks();
|
||||
}
|
||||
|
||||
pub fn glyph_asset_slot_index(&self) -> GlyphAssetSlotIndex {
|
||||
@@ -1880,35 +1885,53 @@ mod tests {
|
||||
use prometeu_hal::tile::Tile;
|
||||
use prometeu_hal::tilemap::TileMap;
|
||||
|
||||
fn expected_glyph_payload_size(width: usize, height: usize) -> usize {
|
||||
(width * height).div_ceil(2) + GLYPH_BANK_PALETTE_BYTES_V1
|
||||
fn expected_glyph_payload_size(width: usize, height: usize, palette_count: usize) -> usize {
|
||||
(width * height).div_ceil(2) + (palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
|
||||
}
|
||||
|
||||
fn expected_glyph_decoded_size(width: usize, height: usize) -> usize {
|
||||
width * height + GLYPH_BANK_PALETTE_BYTES_V1
|
||||
fn expected_glyph_decoded_size(width: usize, height: usize, palette_count: usize) -> usize {
|
||||
width * height + (palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE)
|
||||
}
|
||||
|
||||
fn test_glyph_asset_data() -> Vec<u8> {
|
||||
test_glyph_asset_data_with_palette_count(GLYPH_BANK_MAX_PALETTE_COUNT_V1)
|
||||
}
|
||||
|
||||
fn test_glyph_asset_data_with_palette_count(palette_count: usize) -> Vec<u8> {
|
||||
let mut data = vec![0x11u8; 128];
|
||||
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_BYTES_V1]);
|
||||
data.extend_from_slice(&vec![0u8; palette_count * GLYPH_BANK_PALETTE_BYTES_PER_PALETTE]);
|
||||
data
|
||||
}
|
||||
|
||||
fn test_glyph_asset_entry(asset_name: &str, width: usize, height: usize) -> AssetEntry {
|
||||
test_glyph_asset_entry_with_palette_count(
|
||||
asset_name,
|
||||
width,
|
||||
height,
|
||||
GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||
)
|
||||
}
|
||||
|
||||
fn test_glyph_asset_entry_with_palette_count(
|
||||
asset_name: &str,
|
||||
width: usize,
|
||||
height: usize,
|
||||
palette_count: usize,
|
||||
) -> AssetEntry {
|
||||
AssetEntry {
|
||||
asset_id: 0,
|
||||
asset_name: asset_name.to_string(),
|
||||
bank_type: BankType::GLYPH,
|
||||
offset: 0,
|
||||
size: expected_glyph_payload_size(width, height) as u64,
|
||||
decoded_size: expected_glyph_decoded_size(width, height) as u64,
|
||||
size: expected_glyph_payload_size(width, height, palette_count) as u64,
|
||||
decoded_size: expected_glyph_decoded_size(width, height, palette_count) as u64,
|
||||
codec: AssetCodec::None,
|
||||
metadata: serde_json::json!({
|
||||
"tile_size": 16,
|
||||
"width": width,
|
||||
"height": height,
|
||||
"palette_count": GLYPH_BANK_PALETTE_COUNT_V1,
|
||||
"palette_authored": GLYPH_BANK_PALETTE_COUNT_V1
|
||||
"palette_count": palette_count,
|
||||
"palette_authored": palette_count
|
||||
}),
|
||||
}
|
||||
}
|
||||
@@ -2031,22 +2054,67 @@ mod tests {
|
||||
|
||||
#[test]
|
||||
fn test_decode_glyph_bank_unpacks_packed_pixels_and_reads_palette_colors() {
|
||||
let entry = test_glyph_asset_entry("glyphs", 2, 2);
|
||||
let entry = test_glyph_asset_entry_with_palette_count("glyphs", 2, 2, 1);
|
||||
let mut data = vec![0x10, 0x23];
|
||||
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_BYTES_V1]);
|
||||
data.extend_from_slice(&[0u8; GLYPH_BANK_PALETTE_BYTES_PER_PALETTE]);
|
||||
data[2..6].copy_from_slice(&[0x12, 0x34, 0x56, 0x78]);
|
||||
|
||||
let bank =
|
||||
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
|
||||
|
||||
assert_eq!(bank.pixel_indices, vec![1, 0, 2, 3]);
|
||||
assert_eq!(bank.palette_count(), 1);
|
||||
assert_eq!(bank.palettes[0][0], Color::from_raw(0x12345678));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_decode_glyph_bank_accepts_intermediate_palette_count() {
|
||||
let entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 7);
|
||||
let data = test_glyph_asset_data_with_palette_count(7);
|
||||
|
||||
let bank =
|
||||
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
|
||||
|
||||
assert_eq!(bank.palette_count(), 7);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_decode_glyph_bank_accepts_max_palette_count() {
|
||||
let entry = test_glyph_asset_entry_with_palette_count(
|
||||
"glyphs",
|
||||
16,
|
||||
16,
|
||||
GLYPH_BANK_MAX_PALETTE_COUNT_V1,
|
||||
);
|
||||
let data = test_glyph_asset_data_with_palette_count(GLYPH_BANK_MAX_PALETTE_COUNT_V1);
|
||||
|
||||
let bank =
|
||||
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("glyph decode");
|
||||
|
||||
assert_eq!(bank.palette_count(), GLYPH_BANK_MAX_PALETTE_COUNT_V1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_decode_glyph_bank_reader_matches_buffer_for_variable_palette_count() {
|
||||
let entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 3);
|
||||
let data = test_glyph_asset_data_with_palette_count(3);
|
||||
|
||||
let from_buffer =
|
||||
AssetManager::decode_glyph_bank_from_buffer(&entry, &data).expect("buffer decode");
|
||||
let mut reader = std::io::Cursor::new(data);
|
||||
let from_reader = AssetManager::decode_glyph_bank_from_reader(&entry, &mut reader)
|
||||
.expect("reader decode");
|
||||
|
||||
assert_eq!(from_buffer.palette_count(), from_reader.palette_count());
|
||||
assert_eq!(from_buffer.pixel_indices, from_reader.pixel_indices);
|
||||
assert_eq!(from_buffer.palettes, from_reader.palettes);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_decode_glyph_bank_rejects_short_packed_buffer() {
|
||||
let entry = test_glyph_asset_entry("glyphs", 16, 16);
|
||||
let data = vec![0u8; expected_glyph_payload_size(16, 16) - 1];
|
||||
let data =
|
||||
vec![0u8; expected_glyph_payload_size(16, 16, GLYPH_BANK_MAX_PALETTE_COUNT_V1) - 1];
|
||||
|
||||
let err = match AssetManager::decode_glyph_bank_from_buffer(&entry, &data) {
|
||||
Ok(_) => panic!("glyph decode should reject short buffer"),
|
||||
@@ -2057,9 +2125,9 @@ mod tests {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_decode_glyph_bank_requires_palette_count_64() {
|
||||
fn test_decode_glyph_bank_rejects_palette_count_zero() {
|
||||
let mut entry = test_glyph_asset_entry("glyphs", 16, 16);
|
||||
entry.metadata["palette_count"] = serde_json::json!(32);
|
||||
entry.metadata["palette_count"] = serde_json::json!(0);
|
||||
|
||||
let err =
|
||||
match AssetManager::decode_glyph_bank_from_buffer(&entry, &test_glyph_asset_data()) {
|
||||
@@ -2067,7 +2135,67 @@ mod tests {
|
||||
Err(err) => err,
|
||||
};
|
||||
|
||||
assert_eq!(err, "Invalid palette_count: 32");
|
||||
assert_eq!(err, "Invalid palette_count: 0");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_decode_glyph_bank_rejects_palette_count_above_v1_max() {
|
||||
let mut entry = test_glyph_asset_entry("glyphs", 16, 16);
|
||||
entry.metadata["palette_count"] = serde_json::json!(65);
|
||||
|
||||
let err =
|
||||
match AssetManager::decode_glyph_bank_from_buffer(&entry, &test_glyph_asset_data()) {
|
||||
Ok(_) => panic!("glyph decode should reject invalid palette_count"),
|
||||
Err(err) => err,
|
||||
};
|
||||
|
||||
assert_eq!(err, "Invalid palette_count: 65");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_decode_glyph_bank_rejects_mismatched_variable_decoded_size() {
|
||||
let mut entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 3);
|
||||
entry.decoded_size += 1;
|
||||
|
||||
let err = match AssetManager::decode_glyph_bank_from_buffer(
|
||||
&entry,
|
||||
&test_glyph_asset_data_with_palette_count(3),
|
||||
) {
|
||||
Ok(_) => panic!("glyph decode should reject invalid decoded_size"),
|
||||
Err(err) => err,
|
||||
};
|
||||
|
||||
assert_eq!(
|
||||
err,
|
||||
format!(
|
||||
"Invalid GLYPHBANK decoded_size: expected {}, got {}",
|
||||
expected_glyph_decoded_size(16, 16, 3),
|
||||
expected_glyph_decoded_size(16, 16, 3) + 1
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_decode_glyph_bank_rejects_mismatched_variable_serialized_size() {
|
||||
let mut entry = test_glyph_asset_entry_with_palette_count("glyphs", 16, 16, 3);
|
||||
entry.size += 1;
|
||||
|
||||
let err = match AssetManager::decode_glyph_bank_from_buffer(
|
||||
&entry,
|
||||
&test_glyph_asset_data_with_palette_count(3),
|
||||
) {
|
||||
Ok(_) => panic!("glyph decode should reject invalid serialized size"),
|
||||
Err(err) => err,
|
||||
};
|
||||
|
||||
assert_eq!(
|
||||
err,
|
||||
format!(
|
||||
"Invalid GLYPHBANK serialized size: expected {}, got {}",
|
||||
expected_glyph_payload_size(16, 16, 3),
|
||||
expected_glyph_payload_size(16, 16, 3) + 1
|
||||
)
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
@@ -2668,6 +2796,51 @@ mod tests {
|
||||
assert_eq!(am.slot_info(SlotRef::scene(4)).asset_id, Some(2));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn shutdown_clears_physical_memory_bank_slots() {
|
||||
let banks = Arc::new(MemoryBanks::new());
|
||||
let gfx_installer = Arc::clone(&banks) as Arc<dyn GlyphBankPoolInstaller>;
|
||||
let sound_installer = Arc::clone(&banks) as Arc<dyn SoundBankPoolInstaller>;
|
||||
let scene_installer = Arc::clone(&banks) as Arc<dyn SceneBankPoolInstaller>;
|
||||
|
||||
let glyph_data = test_glyph_asset_data();
|
||||
let scene = test_scene();
|
||||
let scene_data = encode_scene_payload(&scene);
|
||||
let glyph_entry = test_glyph_asset_entry("preload_glyphs", 16, 16);
|
||||
let scene_entry = test_scene_asset_entry("preload_scene", &scene_data, &scene);
|
||||
|
||||
let mut payload = Vec::new();
|
||||
payload.extend_from_slice(&glyph_data);
|
||||
payload.extend_from_slice(&scene_data);
|
||||
let mut shifted_scene_entry = scene_entry;
|
||||
shifted_scene_entry.offset = glyph_data.len() as u64;
|
||||
|
||||
let am = AssetManager::new(
|
||||
vec![],
|
||||
AssetsPayloadSource::empty(),
|
||||
gfx_installer,
|
||||
sound_installer,
|
||||
scene_installer,
|
||||
);
|
||||
am.initialize_for_cartridge(
|
||||
vec![glyph_entry, shifted_scene_entry],
|
||||
vec![PreloadEntry { asset_id: 0, slot: 0 }, PreloadEntry { asset_id: 2, slot: 0 }],
|
||||
AssetsPayloadSource::from_bytes(payload),
|
||||
);
|
||||
|
||||
assert!(banks.glyph_bank_slot(0).is_some());
|
||||
assert!(banks.scene_bank_slot(0).is_some());
|
||||
assert_eq!(am.slot_info(SlotRef::gfx(0)).asset_id, Some(0));
|
||||
assert_eq!(am.slot_info(SlotRef::scene(0)).asset_id, Some(2));
|
||||
|
||||
am.shutdown();
|
||||
|
||||
assert!(banks.glyph_bank_slot(0).is_none());
|
||||
assert!(banks.scene_bank_slot(0).is_none());
|
||||
assert_eq!(am.slot_info(SlotRef::gfx(0)).asset_id, None);
|
||||
assert_eq!(am.slot_info(SlotRef::scene(0)).asset_id, None);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn test_load_returns_asset_not_found() {
|
||||
let banks = Arc::new(MemoryBanks::new());
|
||||
|
||||
@@ -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
|
||||
}
|
||||
|
||||
|
||||
@@ -9,7 +9,6 @@ use prometeu_hal::log::LogSource;
|
||||
use prometeu_hal::telemetry::CertificationConfig;
|
||||
use prometeu_hal::{InputSignals, RuntimePlatform};
|
||||
use prometeu_system::{PrometeuHub, ResidentGameState, SystemOS};
|
||||
use prometeu_vm::VirtualMachine;
|
||||
|
||||
/// PROMETEU Firmware.
|
||||
///
|
||||
@@ -27,8 +26,6 @@ use prometeu_vm::VirtualMachine;
|
||||
/// 2. Delegates the logic update to the current active state.
|
||||
/// 3. Handles state transitions (e.g., from Loading to Playing).
|
||||
pub struct Firmware {
|
||||
/// The execution engine (PVM) for user applications.
|
||||
pub vm: VirtualMachine,
|
||||
/// The underlying OS services (Syscalls, Filesystem, Telemetry).
|
||||
pub os: SystemOS,
|
||||
/// The internal state of the system launcher (Hub).
|
||||
@@ -46,7 +43,6 @@ impl Firmware {
|
||||
/// Initializes the firmware in the `Reset` state.
|
||||
pub fn new(cap_config: Option<CertificationConfig>) -> Self {
|
||||
Self {
|
||||
vm: VirtualMachine::default(),
|
||||
os: SystemOS::new(cap_config),
|
||||
hub: PrometeuHub::new(),
|
||||
state: FirmwareState::Reset(ResetStep),
|
||||
@@ -96,6 +92,15 @@ impl Firmware {
|
||||
signals: &InputSignals,
|
||||
platform: &mut dyn RuntimePlatform,
|
||||
) {
|
||||
let new_state = match new_state {
|
||||
FirmwareState::ResumeResidentGame => {
|
||||
let Some(resume_state) = self.resident_game_resume_state() else {
|
||||
return;
|
||||
};
|
||||
resume_state
|
||||
}
|
||||
state => state,
|
||||
};
|
||||
let entering_game_from_home = matches!(self.state, FirmwareState::HubHome(_))
|
||||
&& matches!(new_state, FirmwareState::GameRunning(_));
|
||||
self.on_exit(signals, platform);
|
||||
@@ -113,7 +118,6 @@ impl Firmware {
|
||||
/// Dispatches the `on_enter` event to the current state implementation.
|
||||
fn on_enter(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
|
||||
let mut req = PrometeuContext {
|
||||
vm: &mut self.vm,
|
||||
os: &mut self.os,
|
||||
hub: &mut self.hub,
|
||||
boot_target: &self.boot_target,
|
||||
@@ -126,6 +130,7 @@ impl Firmware {
|
||||
FirmwareState::LaunchHub(s) => s.on_enter(&mut req),
|
||||
FirmwareState::HubHome(s) => s.on_enter(&mut req),
|
||||
FirmwareState::LoadCartridge(s) => s.on_enter(&mut req),
|
||||
FirmwareState::ResumeResidentGame => {}
|
||||
FirmwareState::GameRunning(s) => s.on_enter(&mut req),
|
||||
FirmwareState::ShellRunning(s) => s.on_enter(&mut req),
|
||||
FirmwareState::AppCrashes(s) => s.on_enter(&mut req),
|
||||
@@ -140,7 +145,6 @@ impl Firmware {
|
||||
platform: &mut dyn RuntimePlatform,
|
||||
) -> Option<FirmwareState> {
|
||||
let mut req = PrometeuContext {
|
||||
vm: &mut self.vm,
|
||||
os: &mut self.os,
|
||||
hub: &mut self.hub,
|
||||
boot_target: &self.boot_target,
|
||||
@@ -153,6 +157,7 @@ impl Firmware {
|
||||
FirmwareState::LaunchHub(s) => s.on_update(&mut req),
|
||||
FirmwareState::HubHome(s) => s.on_update(&mut req),
|
||||
FirmwareState::LoadCartridge(s) => s.on_update(&mut req),
|
||||
FirmwareState::ResumeResidentGame => None,
|
||||
FirmwareState::GameRunning(s) => s.on_update(&mut req),
|
||||
FirmwareState::ShellRunning(s) => s.on_update(&mut req),
|
||||
FirmwareState::AppCrashes(s) => s.on_update(&mut req),
|
||||
@@ -162,7 +167,6 @@ impl Firmware {
|
||||
/// Dispatches the `on_exit` event to the current state implementation.
|
||||
fn on_exit(&mut self, signals: &InputSignals, platform: &mut dyn RuntimePlatform) {
|
||||
let mut req = PrometeuContext {
|
||||
vm: &mut self.vm,
|
||||
os: &mut self.os,
|
||||
hub: &mut self.hub,
|
||||
boot_target: &self.boot_target,
|
||||
@@ -175,6 +179,7 @@ impl Firmware {
|
||||
FirmwareState::LaunchHub(s) => s.on_exit(&mut req),
|
||||
FirmwareState::HubHome(s) => s.on_exit(&mut req),
|
||||
FirmwareState::LoadCartridge(s) => s.on_exit(&mut req),
|
||||
FirmwareState::ResumeResidentGame => {}
|
||||
FirmwareState::GameRunning(s) => s.on_exit(&mut req),
|
||||
FirmwareState::ShellRunning(s) => s.on_exit(&mut req),
|
||||
FirmwareState::AppCrashes(s) => s.on_exit(&mut req),
|
||||
@@ -201,20 +206,32 @@ impl Firmware {
|
||||
}
|
||||
|
||||
pub fn resume_resident_game_from_home(&mut self) -> bool {
|
||||
let Some(task_id) = self.os.lifecycle().resident_game_task() else {
|
||||
let Some(state) = self.resident_game_resume_state() else {
|
||||
return false;
|
||||
};
|
||||
|
||||
if self.os.lifecycle().resume_task(task_id).is_err() {
|
||||
return false;
|
||||
self.state = state;
|
||||
self.state_initialized = false;
|
||||
true
|
||||
}
|
||||
|
||||
fn resident_game_resume_state(&mut self) -> Option<FirmwareState> {
|
||||
let task_id = self.os.lifecycle().resident_game_task()?;
|
||||
|
||||
if let Err(error) = self.os.lifecycle().resume_task(task_id) {
|
||||
self.os.warn(LogSource::Pos, format!("Resident Game resume failed: {error:?}"));
|
||||
return None;
|
||||
}
|
||||
|
||||
let app_id = self.os.vm().current_app_id();
|
||||
let app_id = self
|
||||
.os
|
||||
.sessions()
|
||||
.vm_session_for_task(task_id)
|
||||
.map(|session| session.app_id)
|
||||
.unwrap_or_else(|| self.os.vm().current_app_id());
|
||||
self.os.vm().transition_render_owner(AppMode::Game, app_id);
|
||||
self.state = FirmwareState::GameRunning(GameRunningStep::new(task_id));
|
||||
self.state_initialized = false;
|
||||
self.game_input_barrier_frames = 1;
|
||||
true
|
||||
self.game_input_barrier_frames = self.game_input_barrier_frames.max(1);
|
||||
Some(FirmwareState::GameRunning(GameRunningStep::new(task_id)))
|
||||
}
|
||||
|
||||
pub fn game_lifecycle_audio_paused(&mut self) -> bool {
|
||||
@@ -233,21 +250,24 @@ impl Firmware {
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::firmware::firmware_state::HubHomeStep;
|
||||
use crate::firmware::resident_game_termination::{self, ResidentGameTerminationOutcome};
|
||||
use prometeu_bytecode::assembler::assemble;
|
||||
use prometeu_bytecode::model::{BytecodeModule, FunctionMeta, SyscallDecl};
|
||||
use prometeu_drivers::TestPlatform;
|
||||
use prometeu_drivers::{GlyphBankPoolAccess, SceneBankPoolAccess, TestPlatform};
|
||||
use prometeu_hal::RuntimePlatform;
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::asset::{BankType, SlotRef};
|
||||
use prometeu_hal::cartridge::AssetsPayloadSource;
|
||||
use prometeu_hal::color::Color;
|
||||
use prometeu_hal::log::{LogLevel, LogSource};
|
||||
use prometeu_hal::primitives::Rect;
|
||||
use prometeu_hal::syscalls::{Syscall, caps};
|
||||
use prometeu_system::process::ProcessState;
|
||||
use prometeu_system::task::{TaskId, TaskState};
|
||||
use prometeu_system::windows::WindowOwner;
|
||||
use prometeu_system::{
|
||||
CrashReport, ForegroundOwner, GameLifecycleEventKind, ResidentGameState,
|
||||
discover_games_root,
|
||||
CrashReport, ForegroundOwner, GameLifecycleEventKind, HUB_SUSPENDED_GAME_KILL_CONTROL,
|
||||
ResidentGameState, discover_games_root,
|
||||
};
|
||||
use std::fs;
|
||||
use std::path::PathBuf;
|
||||
@@ -272,20 +292,45 @@ mod tests {
|
||||
}
|
||||
|
||||
fn add_game(&self, name: &str, with_program: bool) -> PathBuf {
|
||||
self.add_game_with_identity(name, 42, "Stress", "1.0.0", with_program)
|
||||
}
|
||||
|
||||
fn add_game_with_identity(
|
||||
&self,
|
||||
name: &str,
|
||||
app_id: u32,
|
||||
title: &str,
|
||||
app_version: &str,
|
||||
with_program: bool,
|
||||
) -> PathBuf {
|
||||
let program = with_program.then(halting_program);
|
||||
self.add_game_with_program(name, app_id, title, app_version, program)
|
||||
}
|
||||
|
||||
fn add_game_with_program(
|
||||
&self,
|
||||
name: &str,
|
||||
app_id: u32,
|
||||
title: &str,
|
||||
app_version: &str,
|
||||
program: Option<Vec<u8>>,
|
||||
) -> PathBuf {
|
||||
let cart = self.path.join(name);
|
||||
fs::create_dir_all(&cart).expect("test cartridge should be created");
|
||||
let manifest = r#"{
|
||||
"magic": "PMTU",
|
||||
"cartridge_version": 1,
|
||||
"app_id": 42,
|
||||
"title": "Stress",
|
||||
"app_version": "1.0.0",
|
||||
"app_mode": "Game"
|
||||
}"#;
|
||||
let manifest = format!(
|
||||
r#"{{
|
||||
"magic": "PMTU",
|
||||
"cartridge_version": 1,
|
||||
"app_id": {app_id},
|
||||
"title": "{title}",
|
||||
"app_version": "{app_version}",
|
||||
"app_mode": "Game"
|
||||
}}"#
|
||||
);
|
||||
fs::write(cart.join("manifest.json"), manifest)
|
||||
.expect("test manifest should be written");
|
||||
if with_program {
|
||||
fs::write(cart.join("program.pbx"), halting_program())
|
||||
if let Some(program) = program {
|
||||
fs::write(cart.join("program.pbx"), program)
|
||||
.expect("test program should be written");
|
||||
}
|
||||
cart
|
||||
@@ -316,6 +361,10 @@ mod tests {
|
||||
.serialize()
|
||||
}
|
||||
|
||||
fn repository_test_cartridges_root() -> PathBuf {
|
||||
PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("../../..").join("test-cartridges")
|
||||
}
|
||||
|
||||
fn invalid_game_cartridge() -> Cartridge {
|
||||
Cartridge {
|
||||
app_id: 7,
|
||||
@@ -367,9 +416,13 @@ mod tests {
|
||||
}
|
||||
|
||||
fn valid_cartridge(app_mode: AppMode) -> Cartridge {
|
||||
valid_cartridge_with(app_mode, 9, "Valid Cart")
|
||||
}
|
||||
|
||||
fn valid_cartridge_with(app_mode: AppMode, app_id: u32, title: &str) -> Cartridge {
|
||||
Cartridge {
|
||||
app_id: 9,
|
||||
title: "Valid Cart".into(),
|
||||
app_id,
|
||||
title: title.into(),
|
||||
app_version: "1.0.0".into(),
|
||||
app_mode,
|
||||
capabilities: caps::NONE,
|
||||
@@ -380,6 +433,16 @@ mod tests {
|
||||
}
|
||||
}
|
||||
|
||||
fn vm_session_tick_index(firmware: &mut Firmware, task_id: TaskId) -> u64 {
|
||||
firmware
|
||||
.os
|
||||
.sessions()
|
||||
.vm_session_for_task(task_id)
|
||||
.expect("VM session should exist")
|
||||
.runtime
|
||||
.tick_index
|
||||
}
|
||||
|
||||
fn load_shell_running_firmware() -> (Firmware, TestPlatform, InputSignals, TaskId) {
|
||||
let mut firmware = Firmware::new(None);
|
||||
let mut platform = TestPlatform::new();
|
||||
@@ -416,6 +479,12 @@ mod tests {
|
||||
windows.set_focus(id);
|
||||
}
|
||||
|
||||
fn front_buffer_pixel(platform: &TestPlatform, x: i32, y: i32) -> u32 {
|
||||
const FRAMEBUFFER_WIDTH: usize = 480;
|
||||
let index = x as usize + y as usize * FRAMEBUFFER_WIDTH;
|
||||
platform.local_hardware().gfx.front_buffer()[index]
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn load_cartridge_transitions_to_app_crashes_when_vm_init_fails() {
|
||||
let mut firmware = Firmware::new(None);
|
||||
@@ -494,6 +563,26 @@ mod tests {
|
||||
assert!(matches!(firmware.state, FirmwareState::LaunchHub(_)));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn reset_clears_vm_sessions_and_runtime_identity() {
|
||||
let mut firmware = Firmware::new(None);
|
||||
let mut platform = TestPlatform::new();
|
||||
let signals = InputSignals::default();
|
||||
|
||||
firmware.load_cartridge(valid_cartridge(AppMode::Game));
|
||||
firmware.tick(&signals, &mut platform);
|
||||
|
||||
assert_eq!(firmware.os.sessions().vm_session_count(), 1);
|
||||
assert_eq!(firmware.os.vm().current_cartridge_title(), "Valid Cart");
|
||||
|
||||
firmware.change_state(FirmwareState::Reset(ResetStep), &signals, &mut platform);
|
||||
|
||||
assert_eq!(firmware.os.sessions().vm_session_count(), 0);
|
||||
assert_eq!(firmware.os.vm().current_cartridge_title(), "");
|
||||
assert_eq!(firmware.os.lifecycle().resident_game(), None);
|
||||
assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn load_cartridge_routes_system_apps_to_system_running() {
|
||||
let mut firmware = Firmware::new(None);
|
||||
@@ -679,6 +768,499 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hub_home_clicking_different_game_terminates_previous_resident_session() {
|
||||
let root = TestGameRoot::new();
|
||||
root.add_game("stress", true);
|
||||
root.add_game_with_identity("zzz-dummy", 43, "Zzz Dummy", "1.0.0", true);
|
||||
|
||||
let (mut firmware, mut platform) = hub_home_firmware();
|
||||
firmware.hub.set_game_library(discover_games_root(&root.path));
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let stress_click =
|
||||
InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
|
||||
firmware.tick(&stress_click, &mut platform);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let first_game_task = match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => step.task_id,
|
||||
other => panic!("expected first GameRunning state, got {:?}", other),
|
||||
};
|
||||
|
||||
firmware.request_home_from_host();
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(first_game_task));
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
let dummy_click =
|
||||
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||
firmware.tick(&dummy_click, &mut platform);
|
||||
|
||||
assert_eq!(firmware.os.lifecycle().task_state(first_game_task), Some(TaskState::Closed));
|
||||
assert_eq!(
|
||||
firmware.os.lifecycle().process_state_for_task(first_game_task),
|
||||
Ok(ProcessState::Stopped)
|
||||
);
|
||||
assert_eq!(
|
||||
firmware
|
||||
.os
|
||||
.sessions()
|
||||
.vm_session_for_task(first_game_task)
|
||||
.map(|session| session.task_id),
|
||||
None
|
||||
);
|
||||
|
||||
let second_game_task = firmware
|
||||
.os
|
||||
.lifecycle()
|
||||
.resident_game_task()
|
||||
.expect("replacement game should be resident");
|
||||
assert_ne!(second_game_task, first_game_task);
|
||||
assert_eq!(
|
||||
firmware
|
||||
.os
|
||||
.sessions()
|
||||
.vm_session_for_task(second_game_task)
|
||||
.map(|session| session.app_id),
|
||||
Some(43)
|
||||
);
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, second_game_task),
|
||||
other => panic!("expected replacement GameRunning state, got {:?}", other),
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn repository_stress_to_dummy_boy_switch_is_end_to_end() {
|
||||
let library = discover_games_root(repository_test_cartridges_root());
|
||||
assert!(
|
||||
library
|
||||
.entries()
|
||||
.iter()
|
||||
.any(|entry| entry.app_id == 1 && entry.title == "Stress Console")
|
||||
);
|
||||
assert!(
|
||||
library.entries().iter().any(|entry| entry.app_id == 2 && entry.title == "Dummy Boy")
|
||||
);
|
||||
|
||||
let (mut firmware, mut platform) = hub_home_firmware();
|
||||
firmware.hub.set_game_library(library);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let stress_click =
|
||||
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||
firmware.tick(&stress_click, &mut platform);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let stress_task = match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => step.task_id,
|
||||
other => panic!("expected Stress GameRunning state, got {:?}", other),
|
||||
};
|
||||
assert_eq!(firmware.os.vm().current_app_id(), 1);
|
||||
assert_eq!(firmware.os.vm().current_cartridge_title(), "Stress Console");
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||
Some(100)
|
||||
);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||
Some(1)
|
||||
);
|
||||
|
||||
firmware.request_home_from_host();
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
let hub_ownership = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(hub_ownership.app_mode, AppMode::Shell);
|
||||
assert_eq!(hub_ownership.app_id, 0);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||
Some(100)
|
||||
);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||
Some(1)
|
||||
);
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
let dummy_click =
|
||||
InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
|
||||
firmware.tick(&dummy_click, &mut platform);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||
None
|
||||
);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||
None
|
||||
);
|
||||
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
|
||||
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
|
||||
|
||||
assert_eq!(firmware.os.lifecycle().task_state(stress_task), Some(TaskState::Closed));
|
||||
assert_eq!(
|
||||
firmware.os.lifecycle().process_state_for_task(stress_task),
|
||||
Ok(ProcessState::Stopped)
|
||||
);
|
||||
assert_eq!(
|
||||
firmware.os.sessions().vm_session_for_task(stress_task).map(|session| session.task_id),
|
||||
None
|
||||
);
|
||||
|
||||
let dummy_task = firmware
|
||||
.os
|
||||
.lifecycle()
|
||||
.resident_game_task()
|
||||
.expect("Dummy Boy should be resident after switch load");
|
||||
assert_ne!(dummy_task, stress_task);
|
||||
assert_eq!(
|
||||
firmware.os.sessions().vm_session_for_task(dummy_task).map(|session| {
|
||||
(session.app_id, session.title.clone(), session.app_version.clone())
|
||||
}),
|
||||
Some((2, "Dummy Boy".to_string(), "0.1.0".to_string()))
|
||||
);
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, dummy_task),
|
||||
other => panic!("expected Dummy Boy GameRunning state, got {:?}", other),
|
||||
}
|
||||
assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Game(dummy_task));
|
||||
assert_eq!(firmware.os.vm().current_app_id(), 2);
|
||||
assert_eq!(firmware.os.vm().current_cartridge_title(), "Dummy Boy");
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let dummy_ownership = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(dummy_ownership.app_mode, AppMode::Game);
|
||||
assert_eq!(dummy_ownership.app_id, 2);
|
||||
|
||||
let front = platform.local_hardware().gfx.front_buffer();
|
||||
let center = 240 + 135 * 480;
|
||||
assert_eq!(front[center], Color::GREEN.raw());
|
||||
|
||||
firmware.request_home_from_host();
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
let hub_ownership = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(hub_ownership.app_mode, AppMode::Shell);
|
||||
assert_eq!(hub_ownership.app_id, 0);
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
let stress_click =
|
||||
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||
firmware.tick(&stress_click, &mut platform);
|
||||
|
||||
assert_eq!(firmware.os.lifecycle().task_state(dummy_task), Some(TaskState::Closed));
|
||||
assert_eq!(
|
||||
firmware.os.lifecycle().process_state_for_task(dummy_task),
|
||||
Ok(ProcessState::Stopped)
|
||||
);
|
||||
assert_eq!(
|
||||
firmware.os.sessions().vm_session_for_task(dummy_task).map(|session| session.task_id),
|
||||
None
|
||||
);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||
Some(100)
|
||||
);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||
Some(1)
|
||||
);
|
||||
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some());
|
||||
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some());
|
||||
|
||||
let second_stress_task = firmware
|
||||
.os
|
||||
.lifecycle()
|
||||
.resident_game_task()
|
||||
.expect("Stress should be resident after switching back");
|
||||
assert_ne!(second_stress_task, stress_task);
|
||||
assert_ne!(second_stress_task, dummy_task);
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, second_stress_task),
|
||||
other => panic!("expected second Stress GameRunning state, got {:?}", other),
|
||||
}
|
||||
assert_eq!(firmware.os.vm().current_app_id(), 1);
|
||||
assert_eq!(firmware.os.vm().current_cartridge_title(), "Stress Console");
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let stress_ownership = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(stress_ownership.app_mode, AppMode::Game);
|
||||
assert_eq!(stress_ownership.app_id, 1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resident_game_termination_noops_when_no_game_is_resident() {
|
||||
let (mut firmware, mut platform) = hub_home_firmware();
|
||||
let ownership_before = firmware.os.vm().active_render_ownership();
|
||||
|
||||
let outcome = resident_game_termination::terminate_resident_game(
|
||||
&mut firmware.os,
|
||||
&mut platform,
|
||||
true,
|
||||
)
|
||||
.expect("no resident game termination should not fail");
|
||||
|
||||
assert_eq!(outcome, ResidentGameTerminationOutcome::NoResidentGame);
|
||||
assert_eq!(firmware.os.vm().active_render_ownership(), ownership_before);
|
||||
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
|
||||
assert!(
|
||||
!firmware
|
||||
.os
|
||||
.recent_logs(16)
|
||||
.iter()
|
||||
.any(|event| event.msg.contains("Resident game killed from Hub"))
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resident_game_termination_closes_session_and_cleans_runtime_state() {
|
||||
let library = discover_games_root(repository_test_cartridges_root());
|
||||
let (mut firmware, mut platform) = hub_home_firmware();
|
||||
firmware.hub.set_game_library(library);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let stress_click =
|
||||
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||
firmware.tick(&stress_click, &mut platform);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let stress_task = match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => step.task_id,
|
||||
other => panic!("expected Stress GameRunning state, got {:?}", other),
|
||||
};
|
||||
|
||||
firmware.request_home_from_host();
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(stress_task));
|
||||
assert!(firmware.game_lifecycle_audio_paused());
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||
Some(100)
|
||||
);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||
Some(1)
|
||||
);
|
||||
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_some());
|
||||
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_some());
|
||||
|
||||
let outcome = resident_game_termination::terminate_resident_game(
|
||||
&mut firmware.os,
|
||||
&mut platform,
|
||||
true,
|
||||
)
|
||||
.expect("resident game termination should succeed");
|
||||
|
||||
assert_eq!(
|
||||
outcome,
|
||||
ResidentGameTerminationOutcome::Terminated {
|
||||
task_id: stress_task,
|
||||
title: "Stress Console".to_string()
|
||||
}
|
||||
);
|
||||
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
|
||||
assert_eq!(firmware.os.lifecycle().task_state(stress_task), Some(TaskState::Closed));
|
||||
assert_eq!(
|
||||
firmware.os.lifecycle().process_state_for_task(stress_task),
|
||||
Ok(ProcessState::Stopped)
|
||||
);
|
||||
assert_eq!(
|
||||
firmware.os.sessions().vm_session_for_task(stress_task).map(|session| session.task_id),
|
||||
None
|
||||
);
|
||||
assert!(!firmware.game_lifecycle_audio_paused());
|
||||
|
||||
let ownership = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(ownership.app_mode, AppMode::Shell);
|
||||
assert_eq!(ownership.app_id, 0);
|
||||
assert_eq!(platform.local_hardware().frame_composer.active_scene_id(), None);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||
None
|
||||
);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||
None
|
||||
);
|
||||
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
|
||||
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
|
||||
|
||||
assert!(
|
||||
firmware.os.recent_logs(32).iter().any(|event| {
|
||||
event.level == LogLevel::Info
|
||||
&& event.source == LogSource::Hub
|
||||
&& event.msg == "Resident game killed from Hub: Stress Console"
|
||||
}),
|
||||
"manual Hub kill should emit an INFO log"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn hub_kill_control_click_terminates_resident_game_and_stays_home() {
|
||||
let library = discover_games_root(repository_test_cartridges_root());
|
||||
let (mut firmware, mut platform) = hub_home_firmware();
|
||||
firmware.hub.set_game_library(library);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let stress_click =
|
||||
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||
firmware.tick(&stress_click, &mut platform);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let stress_task = match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => step.task_id,
|
||||
other => panic!("expected Stress GameRunning state, got {:?}", other),
|
||||
};
|
||||
|
||||
firmware.request_home_from_host();
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(stress_task));
|
||||
|
||||
let kill_sample_x = HUB_SUSPENDED_GAME_KILL_CONTROL.x + 2;
|
||||
let kill_sample_y = HUB_SUSPENDED_GAME_KILL_CONTROL.y + 2;
|
||||
assert_eq!(
|
||||
front_buffer_pixel(&platform, kill_sample_x, kill_sample_y),
|
||||
Color::rgb(164, 32, 40).raw(),
|
||||
"Hub should render the suspended-game kill control before click"
|
||||
);
|
||||
|
||||
let kill_click = InputSignals {
|
||||
f_signal: true,
|
||||
x_pos: HUB_SUSPENDED_GAME_KILL_CONTROL.x,
|
||||
y_pos: HUB_SUSPENDED_GAME_KILL_CONTROL.y,
|
||||
..Default::default()
|
||||
};
|
||||
firmware.tick(&kill_click, &mut platform);
|
||||
|
||||
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||
assert_eq!(firmware.os.lifecycle().foreground_owner(), ForegroundOwner::Hub);
|
||||
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
|
||||
assert_eq!(firmware.os.lifecycle().resident_game(), None);
|
||||
assert_eq!(firmware.os.lifecycle().task_state(stress_task), Some(TaskState::Closed));
|
||||
assert_eq!(
|
||||
firmware.os.lifecycle().process_state_for_task(stress_task),
|
||||
Ok(ProcessState::Stopped)
|
||||
);
|
||||
assert_eq!(
|
||||
firmware.os.sessions().vm_session_for_task(stress_task).map(|session| session.task_id),
|
||||
None
|
||||
);
|
||||
assert!(!firmware.game_lifecycle_audio_paused());
|
||||
assert!(!firmware.resume_resident_game_from_home());
|
||||
|
||||
let ownership = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(ownership.app_mode, AppMode::Shell);
|
||||
assert_eq!(ownership.app_id, 0);
|
||||
assert_eq!(platform.local_hardware().frame_composer.active_scene_id(), None);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::GLYPH, index: 0 }).asset_id,
|
||||
None
|
||||
);
|
||||
assert_eq!(
|
||||
platform.assets().slot_info(SlotRef { asset_type: BankType::SCENE, index: 0 }).asset_id,
|
||||
None
|
||||
);
|
||||
assert!(platform.local_hardware().memory_banks.glyph_bank_slot(0).is_none());
|
||||
assert!(platform.local_hardware().memory_banks.scene_bank_slot(0).is_none());
|
||||
assert!(
|
||||
firmware.os.recent_logs(32).iter().any(|event| {
|
||||
event.level == LogLevel::Info
|
||||
&& event.source == LogSource::Hub
|
||||
&& event.msg == "Resident game killed from Hub: Stress Console"
|
||||
}),
|
||||
"Hub kill control should use the canonical manual kill log"
|
||||
);
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
assert_eq!(
|
||||
front_buffer_pixel(&platform, kill_sample_x, kill_sample_y),
|
||||
Color::rgb(12, 14, 22).raw(),
|
||||
"Hub should stop rendering the kill control after the game is gone"
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn failed_game_switch_returns_home_without_restoring_previous_game() {
|
||||
let root = TestGameRoot::new();
|
||||
root.add_game("stress", true);
|
||||
root.add_game_with_program("zzz-broken", 43, "Zzz Broken", "1.0.0", Some(vec![0, 0, 0, 0]));
|
||||
|
||||
let (mut firmware, mut platform) = hub_home_firmware();
|
||||
firmware.hub.set_game_library(discover_games_root(&root.path));
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let stress_click =
|
||||
InputSignals { f_signal: true, x_pos: 72, y_pos: 90, ..Default::default() };
|
||||
firmware.tick(&stress_click, &mut platform);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let first_game_task = match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => step.task_id,
|
||||
other => panic!("expected first GameRunning state, got {:?}", other),
|
||||
};
|
||||
|
||||
firmware.request_home_from_host();
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
let broken_click =
|
||||
InputSignals { f_signal: true, x_pos: 72, y_pos: 118, ..Default::default() };
|
||||
firmware.tick(&broken_click, &mut platform);
|
||||
|
||||
assert_eq!(firmware.os.lifecycle().task_state(first_game_task), Some(TaskState::Closed));
|
||||
assert_eq!(
|
||||
firmware
|
||||
.os
|
||||
.sessions()
|
||||
.vm_session_for_task(first_game_task)
|
||||
.map(|session| session.task_id),
|
||||
None
|
||||
);
|
||||
let partial_task = firmware
|
||||
.os
|
||||
.lifecycle()
|
||||
.resident_game_task()
|
||||
.expect("failed target should be resident until recovery tick");
|
||||
assert_ne!(partial_task, first_game_task);
|
||||
|
||||
firmware.tick(&InputSignals::default(), &mut platform);
|
||||
|
||||
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||
assert_eq!(firmware.os.lifecycle().resident_game_task(), None);
|
||||
assert_eq!(firmware.os.lifecycle().task_state(first_game_task), Some(TaskState::Closed));
|
||||
assert_eq!(firmware.os.lifecycle().task_state(partial_task), Some(TaskState::Closed));
|
||||
assert_eq!(
|
||||
firmware.os.lifecycle().process_state_for_task(partial_task),
|
||||
Ok(ProcessState::Stopped)
|
||||
);
|
||||
assert_eq!(
|
||||
firmware.os.sessions().vm_session_for_task(partial_task).map(|session| session.task_id),
|
||||
None
|
||||
);
|
||||
assert!(
|
||||
firmware
|
||||
.os
|
||||
.recent_logs(16)
|
||||
.iter()
|
||||
.any(|event| event.msg.contains("Failed to switch to game Zzz Broken app_id 43"))
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn invalid_games_root_candidate_is_omitted_from_home_launch_boundary() {
|
||||
let root = TestGameRoot::new();
|
||||
@@ -861,6 +1443,8 @@ mod tests {
|
||||
};
|
||||
let tick_index_before_home = firmware.os.vm().tick_index();
|
||||
let render_ownership_before_home = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(render_ownership_before_home.app_mode, AppMode::Game);
|
||||
assert_eq!(render_ownership_before_home.app_id, 9);
|
||||
|
||||
firmware.request_home_from_host();
|
||||
|
||||
@@ -892,7 +1476,6 @@ mod tests {
|
||||
let render_ownership_after_home = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(render_ownership_after_home.app_mode, AppMode::Shell);
|
||||
assert_eq!(render_ownership_after_home.app_id, 0);
|
||||
assert!(render_ownership_after_home.epoch > render_ownership_before_home.epoch);
|
||||
assert!(firmware.os.lifecycle().pending_game_lifecycle_events().is_empty());
|
||||
assert_eq!(
|
||||
firmware.os.vm().delivered_game_lifecycle_events().last().map(|event| event.kind),
|
||||
@@ -921,6 +1504,8 @@ mod tests {
|
||||
firmware.request_home_from_host();
|
||||
firmware.tick(&signals, &mut platform);
|
||||
let hub_ownership = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(hub_ownership.app_mode, AppMode::Shell);
|
||||
assert_eq!(hub_ownership.app_id, 0);
|
||||
|
||||
assert!(firmware.resume_resident_game_from_home());
|
||||
assert!(matches!(firmware.state, FirmwareState::GameRunning(_)));
|
||||
@@ -933,7 +1518,6 @@ mod tests {
|
||||
let game_ownership = firmware.os.vm().active_render_ownership();
|
||||
assert_eq!(game_ownership.app_mode, AppMode::Game);
|
||||
assert_eq!(game_ownership.app_id, 9);
|
||||
assert!(game_ownership.epoch > hub_ownership.epoch);
|
||||
|
||||
let held_signals =
|
||||
InputSignals { up_signal: true, f_signal: true, x_pos: 72, y_pos: 90, ..signals };
|
||||
@@ -1015,6 +1599,67 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn resident_game_and_vm_shell_sessions_tick_independently() {
|
||||
let mut firmware = Firmware::new(None);
|
||||
let mut platform = TestPlatform::new();
|
||||
let signals = InputSignals::default();
|
||||
|
||||
firmware.load_cartridge(valid_cartridge_with(AppMode::Game, 9, "Resident Game"));
|
||||
firmware.tick(&signals, &mut platform);
|
||||
|
||||
let game_task = match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => step.task_id,
|
||||
other => panic!("expected GameRunning state, got {:?}", other),
|
||||
};
|
||||
|
||||
firmware.tick(&signals, &mut platform);
|
||||
let game_tick_before_home = vm_session_tick_index(&mut firmware, game_task);
|
||||
|
||||
firmware.request_home_from_host();
|
||||
firmware.tick(&signals, &mut platform);
|
||||
|
||||
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||
assert_eq!(firmware.os.lifecycle().task_state(game_task), Some(TaskState::Suspended));
|
||||
let game_tick_after_suspend = vm_session_tick_index(&mut firmware, game_task);
|
||||
assert_eq!(game_tick_after_suspend, game_tick_before_home + 1);
|
||||
|
||||
firmware.load_cartridge(valid_cartridge_with(AppMode::Shell, 77, "VM Shell"));
|
||||
firmware.tick(&signals, &mut platform);
|
||||
|
||||
let shell_task = match &firmware.state {
|
||||
FirmwareState::ShellRunning(step) => step.task_id,
|
||||
other => panic!("expected ShellRunning state, got {:?}", other),
|
||||
};
|
||||
|
||||
assert_ne!(shell_task, game_task);
|
||||
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(game_task));
|
||||
assert_eq!(firmware.os.lifecycle().task_state(game_task), Some(TaskState::Suspended));
|
||||
|
||||
let shell_tick_before = vm_session_tick_index(&mut firmware, shell_task);
|
||||
for _ in 0..3 {
|
||||
firmware.tick(&signals, &mut platform);
|
||||
}
|
||||
|
||||
assert_eq!(vm_session_tick_index(&mut firmware, game_task), game_tick_after_suspend);
|
||||
assert_eq!(vm_session_tick_index(&mut firmware, shell_task), shell_tick_before + 3);
|
||||
|
||||
let close_shell = InputSignals { start_signal: true, ..Default::default() };
|
||||
firmware.tick(&close_shell, &mut platform);
|
||||
assert!(matches!(firmware.state, FirmwareState::HubHome(_)));
|
||||
assert_eq!(firmware.os.lifecycle().task_state(shell_task), Some(TaskState::Closed));
|
||||
assert_eq!(firmware.os.lifecycle().resident_game_task(), Some(game_task));
|
||||
|
||||
assert!(firmware.resume_resident_game_from_home());
|
||||
firmware.tick(&signals, &mut platform);
|
||||
|
||||
match &firmware.state {
|
||||
FirmwareState::GameRunning(step) => assert_eq!(step.task_id, game_task),
|
||||
other => panic!("expected GameRunning state, got {:?}", other),
|
||||
}
|
||||
assert!(vm_session_tick_index(&mut firmware, game_task) > game_tick_after_suspend);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn direct_game_boot_does_not_depend_on_userland_run_cart_syscall() {
|
||||
assert!(Syscall::from_u32(0x0002).is_none());
|
||||
|
||||
@@ -14,6 +14,7 @@ pub enum FirmwareState {
|
||||
LaunchHub(LaunchHubStep),
|
||||
HubHome(HubHomeStep),
|
||||
LoadCartridge(LoadCartridgeStep),
|
||||
ResumeResidentGame,
|
||||
GameRunning(GameRunningStep),
|
||||
ShellRunning(ShellRunningStep),
|
||||
AppCrashes(AppCrashesStep),
|
||||
|
||||
@@ -37,13 +37,11 @@ impl GameRunningStep {
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
|
||||
ctx.os.vm().deliver_pending_game_lifecycle_events();
|
||||
|
||||
let pause_requested = matches!(
|
||||
ctx.os.lifecycle().resident_game().map(|game| game.state),
|
||||
Some(ResidentGameState::PauseRequested { .. })
|
||||
);
|
||||
let result = ctx.os.vm().tick(ctx.vm, ctx.signals, ctx.platform);
|
||||
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));
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
use crate::firmware::firmware_state::{
|
||||
AppCrashesStep, FirmwareState, GameRunningStep, LoadCartridgeStep, ShellRunningStep,
|
||||
AppCrashesStep, FirmwareState, LoadCartridgeStep, ShellRunningStep,
|
||||
};
|
||||
use crate::firmware::prometeu_context::PrometeuContext;
|
||||
use prometeu_hal::InputSignals;
|
||||
use crate::firmware::resident_game_termination;
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::cartridge_loader::CartridgeLoader;
|
||||
use prometeu_hal::log::{LogLevel, LogSource};
|
||||
@@ -21,14 +21,29 @@ 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 }));
|
||||
}
|
||||
|
||||
match outcome.action {
|
||||
Some(SystemProfileAction::LaunchNativeShell(app)) => {
|
||||
let task_id = ctx.os.sessions().create_native_shell_task(app.app_id(), app.title());
|
||||
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),
|
||||
@@ -38,68 +53,71 @@ impl HubHomeStep {
|
||||
ctx.os.windows().set_focus(id);
|
||||
return Some(FirmwareState::ShellRunning(ShellRunningStep::new(task_id)));
|
||||
}
|
||||
Some(SystemProfileAction::LaunchGame { path }) => match CartridgeLoader::load(&path) {
|
||||
Ok(cartridge) => {
|
||||
if cartridge.app_mode == AppMode::Game
|
||||
&& let Some(task_id) = ctx.os.lifecycle().resident_game_task()
|
||||
{
|
||||
if ctx.os.vm().current_app_id() == cartridge.app_id {
|
||||
match ctx.os.lifecycle().resume_task(task_id) {
|
||||
Ok(()) => {
|
||||
ctx.os
|
||||
.vm()
|
||||
.transition_render_owner(AppMode::Game, cartridge.app_id);
|
||||
ctx.platform
|
||||
.input_mut()
|
||||
.pad_mut()
|
||||
.begin_frame(&InputSignals::default());
|
||||
ctx.platform
|
||||
.input_mut()
|
||||
.touch_mut()
|
||||
.begin_frame(&InputSignals::default());
|
||||
return Some(FirmwareState::GameRunning(GameRunningStep::new(
|
||||
task_id,
|
||||
)));
|
||||
}
|
||||
Err(error) => {
|
||||
ctx.os.log(
|
||||
LogLevel::Warn,
|
||||
LogSource::Hub,
|
||||
0,
|
||||
format!(
|
||||
"Failed to resume resident Home game {}: {error:?}",
|
||||
cartridge.title
|
||||
),
|
||||
);
|
||||
return None;
|
||||
}
|
||||
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;
|
||||
}
|
||||
}
|
||||
|
||||
let resident_app_id = ctx.os.vm().current_app_id();
|
||||
return Some(FirmwareState::LoadCartridge(
|
||||
LoadCartridgeStep::new_game_switch(cartridge),
|
||||
));
|
||||
}
|
||||
Err(error) => {
|
||||
ctx.os.log(
|
||||
LogLevel::Warn,
|
||||
LogLevel::Error,
|
||||
LogSource::Hub,
|
||||
0,
|
||||
format!(
|
||||
"Cannot launch Home game {} while resident game app_id {} is active",
|
||||
cartridge.title, resident_app_id
|
||||
"Failed to launch Home game {}: {:?}",
|
||||
target.path.display(),
|
||||
error
|
||||
),
|
||||
);
|
||||
return None;
|
||||
}
|
||||
|
||||
return Some(FirmwareState::LoadCartridge(LoadCartridgeStep::new(cartridge)));
|
||||
}
|
||||
Err(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 launch Home game {}: {:?}", path.display(), error),
|
||||
format!("Failed to kill resident game from Hub: {error:?}"),
|
||||
);
|
||||
}
|
||||
},
|
||||
}
|
||||
Some(SystemProfileAction::CloseShell) | 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,12 @@ 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);
|
||||
// Reset is a cold-boot boundary. Clearing only the VM session leaves
|
||||
// the lifecycle registry pointing at the old resident game, which
|
||||
// rejects the next cartridge as a second resident game.
|
||||
let _ = ctx.os.lifecycle().terminate_resident_game();
|
||||
ctx.os.sessions().clear_vm_sessions();
|
||||
ctx.os.vm().reset_global_runtime_state();
|
||||
}
|
||||
|
||||
pub fn on_update(&mut self, ctx: &mut PrometeuContext) -> Option<FirmwareState> {
|
||||
|
||||
@@ -74,26 +74,11 @@ impl ShellRunningStep {
|
||||
}
|
||||
};
|
||||
|
||||
let action = match process_kind {
|
||||
let outcome = match process_kind {
|
||||
ProcessKind::VmShell => {
|
||||
let outcome =
|
||||
ctx.hub.update_shell_profile(ctx.os, ctx.vm, ctx.signals, ctx.platform);
|
||||
|
||||
if let Some(report) = outcome.crash {
|
||||
let _ = ctx.os.lifecycle().crash_task(self.task_id, Some(&report));
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
|
||||
outcome.action
|
||||
}
|
||||
ProcessKind::NativeShell => {
|
||||
let mut action = ctx.hub.gui_update(ctx.os, ctx.platform);
|
||||
if ctx.platform.input().pad().start().down {
|
||||
action = Some(SystemProfileAction::CloseShell);
|
||||
}
|
||||
ctx.hub.render(ctx.os, ctx.platform);
|
||||
action
|
||||
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!(
|
||||
@@ -106,7 +91,12 @@ impl ShellRunningStep {
|
||||
}
|
||||
};
|
||||
|
||||
if action == Some(SystemProfileAction::CloseShell) {
|
||||
if let Some(report) = outcome.crash {
|
||||
let _ = ctx.os.lifecycle().crash_task(self.task_id, Some(&report));
|
||||
return Some(FirmwareState::AppCrashes(AppCrashesStep { report }));
|
||||
}
|
||||
|
||||
if outcome.action == Some(SystemProfileAction::CloseShell) {
|
||||
self.close_current_shell(ctx);
|
||||
return Some(FirmwareState::HubHome(HubHomeStep));
|
||||
}
|
||||
|
||||
@@ -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 })
|
||||
}
|
||||
@@ -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);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -6,9 +6,12 @@ mod services;
|
||||
pub use crash_report::CrashReport;
|
||||
pub use os::{
|
||||
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
|
||||
LifecycleOperation, SystemOS,
|
||||
LifecycleOperation, SessionError, SystemOS,
|
||||
};
|
||||
pub use programs::{
|
||||
HUB_SUSPENDED_GAME_KILL_CONTROL, NativeShellApp, PrometeuHub, SystemProfileAction,
|
||||
SystemProfileUpdate,
|
||||
};
|
||||
pub use programs::{NativeShellApp, PrometeuHub, SystemProfileAction, SystemProfileUpdate};
|
||||
pub use prometeu_hal::{RenderWorkerBackend, RenderWorkerFrameSink};
|
||||
pub use services::async_work::{
|
||||
AsyncWorkActiveJob, AsyncWorkCancelToken, AsyncWorkJobContext, AsyncWorkJobId,
|
||||
@@ -20,7 +23,7 @@ pub use services::foreground::{
|
||||
};
|
||||
pub use services::fs;
|
||||
pub use services::game_library::{
|
||||
GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, discover_games_root,
|
||||
GameLibrary, GameLibraryDiagnostic, GameLibraryEntry, GameSwitchTarget, discover_games_root,
|
||||
};
|
||||
pub use services::memcard::MemcardAsyncLaneOperation;
|
||||
pub use services::process;
|
||||
@@ -29,4 +32,5 @@ pub use services::vm_runtime::{
|
||||
LatestRenderFrameStore, RenderWorkerConfig, RenderWorkerController, RenderWorkerHandoff,
|
||||
RenderWorkerHandoffWait, RenderWorkerOwnership, VirtualMachineRuntime,
|
||||
};
|
||||
pub use services::vm_session;
|
||||
pub use services::windows;
|
||||
|
||||
@@ -4,7 +4,7 @@ use crate::os::{
|
||||
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
|
||||
LifecycleOperation,
|
||||
};
|
||||
use crate::process::{ProcessId, ProcessKind, ProcessState};
|
||||
use crate::process::{Process, ProcessId, ProcessKind, ProcessState};
|
||||
use crate::services::foreground::{
|
||||
ForegroundOwner, ForegroundStackError, ResidentGame, ResidentGameState,
|
||||
};
|
||||
@@ -20,21 +20,11 @@ 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> {
|
||||
let process_id = process_id_for_task(self.os, task_id)?;
|
||||
self.os
|
||||
.process_manager
|
||||
.get(process_id)
|
||||
.map(|process| process.kind)
|
||||
.ok_or(LifecycleError::ProcessNotFound(process_id))
|
||||
process_for_task(self.os, task_id).map(|process| process.kind)
|
||||
}
|
||||
|
||||
pub fn set_foreground_task(&mut self, task_id: TaskId) -> Result<(), LifecycleError> {
|
||||
@@ -232,6 +222,28 @@ impl<'a> LifecycleFacade<'a> {
|
||||
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,
|
||||
@@ -267,6 +279,11 @@ 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 } => {
|
||||
|
||||
@@ -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_game_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_shell_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_shell_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::{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, RenderOwnership, RenderWorkerBackend, RenderWorkerError,
|
||||
RenderWorkerFrameSink, RuntimePlatform,
|
||||
};
|
||||
use prometeu_vm::VirtualMachine;
|
||||
use std::sync::atomic::Ordering;
|
||||
|
||||
pub struct VmFacade<'a> {
|
||||
@@ -16,117 +17,225 @@ 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.deliver_pending_game_lifecycle_events();
|
||||
self.deliver_pending_game_lifecycle_events_to_session(task_id);
|
||||
|
||||
self.os.vm_runtime.tick(
|
||||
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 deliver_pending_game_lifecycle_events(&mut self) {
|
||||
if self.os.vm_runtime.current_cartridge_app_mode == AppMode::Game {
|
||||
let resident_game_task = self.os.foreground_stack.resident_game_task();
|
||||
let mut retained = Vec::new();
|
||||
let mut delivered = Vec::new();
|
||||
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;
|
||||
};
|
||||
|
||||
for event in self.os.game_lifecycle_events.drain(..) {
|
||||
if Some(event.task_id) == resident_game_task {
|
||||
delivered.push(event);
|
||||
} else {
|
||||
retained.push(event);
|
||||
}
|
||||
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;
|
||||
self.os.vm_runtime.deliver_game_lifecycle_events(delivered);
|
||||
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 reset(&mut self, vm: &mut VirtualMachine) {
|
||||
self.os.vm_runtime.reset(vm);
|
||||
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_instruction(
|
||||
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 clear_debug_step_request(&mut self) {
|
||||
if let Some(session) = self.active_session_mut() {
|
||||
session.runtime.debug_step_request = false;
|
||||
return;
|
||||
}
|
||||
|
||||
self.os.vm_runtime.debug_step_request = false;
|
||||
}
|
||||
|
||||
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.os.vm_runtime.delivered_game_lifecycle_events()
|
||||
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)
|
||||
@@ -150,6 +259,12 @@ impl<'a> VmFacade<'a> {
|
||||
}
|
||||
|
||||
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()
|
||||
}
|
||||
|
||||
@@ -164,22 +279,61 @@ impl<'a> VmFacade<'a> {
|
||||
}
|
||||
|
||||
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()
|
||||
}
|
||||
}
|
||||
|
||||
@@ -2,7 +2,9 @@ mod facades;
|
||||
mod lifecycle;
|
||||
mod system_os;
|
||||
|
||||
pub use facades::{FsFacade, LifecycleFacade, SessionsFacade, VmFacade, WindowFacade};
|
||||
pub use facades::{
|
||||
FsFacade, LifecycleFacade, SessionError, SessionsFacade, VmFacade, WindowFacade,
|
||||
};
|
||||
pub use lifecycle::{
|
||||
DEFAULT_GAME_PAUSE_BUDGET_TICKS, GameLifecycleEvent, GameLifecycleEventKind, LifecycleError,
|
||||
LifecycleOperation,
|
||||
|
||||
@@ -6,6 +6,7 @@ use crate::os::{
|
||||
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};
|
||||
@@ -18,6 +19,7 @@ pub struct SystemOS {
|
||||
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,
|
||||
@@ -39,6 +41,7 @@ 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,
|
||||
@@ -140,16 +143,33 @@ impl SystemOS {
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
use crate::os::{GameLifecycleEventKind, LifecycleError, LifecycleOperation};
|
||||
use crate::process::{ProcessKind, 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);
|
||||
@@ -198,6 +218,172 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
#[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);
|
||||
@@ -319,6 +505,60 @@ mod tests {
|
||||
);
|
||||
}
|
||||
|
||||
#[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);
|
||||
|
||||
@@ -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,12 +1,12 @@
|
||||
use crate::{CrashReport, GameLibrary, 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;
|
||||
use std::path::PathBuf;
|
||||
|
||||
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 };
|
||||
@@ -20,6 +20,7 @@ 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 };
|
||||
|
||||
@@ -32,6 +33,8 @@ 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 {
|
||||
@@ -83,7 +86,8 @@ impl NativeShellApp {
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum SystemProfileAction {
|
||||
LaunchNativeShell(NativeShellApp),
|
||||
LaunchGame { path: PathBuf },
|
||||
LaunchGame { target: GameSwitchTarget },
|
||||
KillResidentGame,
|
||||
CloseShell,
|
||||
}
|
||||
|
||||
@@ -132,12 +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);
|
||||
}
|
||||
@@ -150,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, self.game_library.entries())
|
||||
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() {
|
||||
@@ -174,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 {
|
||||
@@ -185,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);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -193,6 +221,22 @@ 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(
|
||||
@@ -201,6 +245,7 @@ fn action_for_click(
|
||||
y: i32,
|
||||
pressed: bool,
|
||||
game_entries: &[crate::GameLibraryEntry],
|
||||
suspended_game: Option<&SuspendedGameIndicator>,
|
||||
) -> Option<SystemProfileAction> {
|
||||
if !pressed {
|
||||
return None;
|
||||
@@ -210,6 +255,10 @@ fn action_for_click(
|
||||
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)
|
||||
@@ -217,7 +266,7 @@ fn action_for_click(
|
||||
.find(|(index, _entry)| rect_contains(game_row_rect(*index), x, y))
|
||||
.map(|(_index, entry)| entry)
|
||||
{
|
||||
return Some(SystemProfileAction::LaunchGame { path: entry.path.clone() });
|
||||
return Some(SystemProfileAction::LaunchGame { target: entry.switch_target() });
|
||||
}
|
||||
|
||||
HOME_BUTTONS
|
||||
@@ -226,6 +275,23 @@ fn action_for_click(
|
||||
.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,
|
||||
@@ -250,6 +316,7 @@ 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 });
|
||||
@@ -289,6 +356,11 @@ fn render_home_packet(
|
||||
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)
|
||||
}
|
||||
|
||||
@@ -391,6 +463,39 @@ fn draw_game_row(commands: &mut Vec<GfxUiCommand>, rect: Rect, label: &str, hove
|
||||
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) {
|
||||
commands.push(GfxUiCommand::DrawText { x, y, text: text.to_string(), color });
|
||||
}
|
||||
@@ -398,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))
|
||||
);
|
||||
}
|
||||
@@ -415,7 +556,8 @@ mod tests {
|
||||
SHELL_B_BUTTON.x + SHELL_B_BUTTON.w - 1,
|
||||
SHELL_B_BUTTON.y,
|
||||
true,
|
||||
&[]
|
||||
&[],
|
||||
None
|
||||
),
|
||||
Some(SystemProfileAction::LaunchNativeShell(NativeShellApp::ShellB))
|
||||
);
|
||||
@@ -429,7 +571,8 @@ mod tests {
|
||||
SHELL_A_BUTTON.x + SHELL_A_BUTTON.w,
|
||||
SHELL_A_BUTTON.y,
|
||||
true,
|
||||
&[]
|
||||
&[],
|
||||
None
|
||||
),
|
||||
None
|
||||
);
|
||||
@@ -439,7 +582,8 @@ mod tests {
|
||||
SHELL_A_BUTTON.x,
|
||||
SHELL_A_BUTTON.y + SHELL_A_BUTTON.h,
|
||||
true,
|
||||
&[]
|
||||
&[],
|
||||
None
|
||||
),
|
||||
None
|
||||
);
|
||||
@@ -447,7 +591,10 @@ mod tests {
|
||||
|
||||
#[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]
|
||||
@@ -475,19 +622,35 @@ mod tests {
|
||||
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_for_click(false, GAME_ROW_X, GAME_ROW_Y, true, std::slice::from_ref(&entry)),
|
||||
Some(SystemProfileAction::LaunchGame { path: entry.path.clone() })
|
||||
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]
|
||||
@@ -501,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| {
|
||||
@@ -509,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));
|
||||
@@ -518,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);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -25,6 +25,29 @@ impl GameLibraryEntry {
|
||||
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)]
|
||||
@@ -256,6 +279,31 @@ mod tests {
|
||||
}));
|
||||
}
|
||||
|
||||
#[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();
|
||||
@@ -267,4 +315,22 @@ mod tests {
|
||||
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")
|
||||
}));
|
||||
}
|
||||
}
|
||||
|
||||
@@ -6,4 +6,5 @@ pub mod memcard;
|
||||
pub mod process;
|
||||
pub mod task;
|
||||
pub mod vm_runtime;
|
||||
pub mod vm_session;
|
||||
pub mod windows;
|
||||
|
||||
@@ -65,7 +65,7 @@ pub struct VirtualMachineRuntime {
|
||||
|
||||
impl VirtualMachineRuntime {
|
||||
pub const CYCLES_PER_LOGICAL_FRAME: u64 = 1_500_000;
|
||||
pub const SLICE_PER_TICK: u64 = 1_500_000;
|
||||
pub const SLICE_PER_TICK: u64 = 250_000;
|
||||
pub const MAX_LOG_LEN: usize = 256;
|
||||
pub const MAX_LOGS_PER_FRAME: u32 = 10;
|
||||
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -76,6 +76,9 @@ impl VirtualMachineRuntime {
|
||||
vm: &mut VirtualMachine,
|
||||
platform: &mut dyn RuntimePlatform,
|
||||
) -> Option<CrashReport> {
|
||||
if vm.call_stack_is_empty() {
|
||||
vm.prepare_boot_call();
|
||||
}
|
||||
let step_result = {
|
||||
let mut ctx = HostContext::new_platform(Some(platform));
|
||||
let mut fs = VirtualFS::new();
|
||||
@@ -96,18 +99,28 @@ impl VirtualMachineRuntime {
|
||||
};
|
||||
|
||||
match step_result {
|
||||
Ok(_) => None,
|
||||
Err(e) => {
|
||||
let report = match e {
|
||||
LogicalFrameEndingReason::Trap(trap) => CrashReport::VmTrap { trap },
|
||||
LogicalFrameEndingReason::Panic(message) => {
|
||||
CrashReport::VmPanic { message, pc: Some(vm.pc() as u32) }
|
||||
}
|
||||
other => CrashReport::VmPanic {
|
||||
message: format!("Unexpected fault during step: {:?}", other),
|
||||
pc: Some(vm.pc() as u32),
|
||||
},
|
||||
};
|
||||
Ok(())
|
||||
| Err(
|
||||
LogicalFrameEndingReason::FrameSync
|
||||
| LogicalFrameEndingReason::BudgetExhausted
|
||||
| LogicalFrameEndingReason::Halted
|
||||
| LogicalFrameEndingReason::EndOfRom
|
||||
| LogicalFrameEndingReason::Breakpoint,
|
||||
) => None,
|
||||
Err(LogicalFrameEndingReason::Trap(trap)) => {
|
||||
let report = CrashReport::VmTrap { trap };
|
||||
self.log(
|
||||
log_service,
|
||||
LogLevel::Error,
|
||||
LogSource::Vm,
|
||||
report.log_tag(),
|
||||
format!("PVM Fault during Step: {}", report),
|
||||
);
|
||||
self.last_crash_report = Some(report.clone());
|
||||
Some(report)
|
||||
}
|
||||
Err(LogicalFrameEndingReason::Panic(message)) => {
|
||||
let report = CrashReport::VmPanic { message, pc: Some(vm.pc() as u32) };
|
||||
self.log(
|
||||
log_service,
|
||||
LogLevel::Error,
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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;
|
||||
}
|
||||
}
|
||||
|
||||
@@ -437,9 +444,11 @@ impl ApplicationHandler for HostRunner {
|
||||
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()
|
||||
@@ -505,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]
|
||||
@@ -608,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,14 @@
|
||||
[package]
|
||||
name = "prometeu-host-headless"
|
||||
version = "0.1.0"
|
||||
edition = "2024"
|
||||
license.workspace = true
|
||||
repository.workspace = true
|
||||
description = "In-process Prometeu host that boots and steps cartridges without a window, display, or audio device."
|
||||
|
||||
[dependencies]
|
||||
prometeu-bytecode = { path = "../../console/prometeu-bytecode" }
|
||||
prometeu-drivers = { path = "../../console/prometeu-drivers" }
|
||||
prometeu-firmware = { path = "../../console/prometeu-firmware" }
|
||||
prometeu-hal = { path = "../../console/prometeu-hal" }
|
||||
prometeu-system = { path = "../../console/prometeu-system" }
|
||||
@@ -0,0 +1,425 @@
|
||||
use std::fmt;
|
||||
use std::sync::Arc;
|
||||
|
||||
use prometeu_bytecode::Value;
|
||||
use prometeu_drivers::MemoryBanks;
|
||||
use prometeu_drivers::hardware::Hardware;
|
||||
use prometeu_firmware::firmware_state::{AppCrashesStep, ResetStep};
|
||||
use prometeu_firmware::{BootTarget, Firmware, FirmwareState};
|
||||
use prometeu_hal::{
|
||||
AssetBridge, AudioBridge, FrameId, Game2DFrameComposer, InputPlatform, InputSignals,
|
||||
OwnedRgba8888Frame, RenderBackend, RenderSubmission, RenderSubmissionSink, RenderSubmitError,
|
||||
RuntimePlatform, TelemetryPlatform,
|
||||
};
|
||||
use prometeu_system::{CrashReport, LatestRenderFrameStore};
|
||||
|
||||
const BOOT_TICK_LIMIT: usize = 64;
|
||||
const LOGICAL_FRAME_TICK_LIMIT: usize = 100_000;
|
||||
|
||||
/// One published logical frame plus the automation counter.
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct CapturedFrame {
|
||||
pub logical_frame_index: u64,
|
||||
pub frame: OwnedRgba8888Frame,
|
||||
}
|
||||
|
||||
/// Debugger-shaped execution snapshot.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct HostState {
|
||||
pub pc: usize,
|
||||
pub stack_top: Vec<Value>,
|
||||
pub frame_index: u64,
|
||||
pub tick_index: u64,
|
||||
pub app_id: u32,
|
||||
pub status: HostExecutionStatus,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
||||
pub enum HostExecutionStatus {
|
||||
Running,
|
||||
Paused,
|
||||
Terminated,
|
||||
Faulted,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum AdvanceFrameOutcome {
|
||||
FrameCompleted { logical_frame_index: u64, frame_id: FrameId },
|
||||
Faulted(CrashReport),
|
||||
Terminated,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum AdvanceFramesStop {
|
||||
Completed,
|
||||
Faulted(CrashReport),
|
||||
Terminated,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub struct AdvanceFramesOutcome {
|
||||
pub requested: u64,
|
||||
pub completed: u64,
|
||||
pub stop: AdvanceFramesStop,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, PartialEq, Eq)]
|
||||
pub enum HostError {
|
||||
AlreadyBooted,
|
||||
BootFailed { reason: String, report: Option<CrashReport> },
|
||||
InvalidState { operation: &'static str, status: HostExecutionStatus },
|
||||
LogicalFrameDidNotClose,
|
||||
FrameNotPublished { previous: Option<FrameId> },
|
||||
NoFrameAvailable,
|
||||
}
|
||||
|
||||
impl fmt::Display for HostError {
|
||||
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
||||
match self {
|
||||
Self::AlreadyBooted => write!(f, "boot requires reset before another attempt"),
|
||||
Self::BootFailed { reason, .. } => write!(f, "boot failed: {reason}"),
|
||||
Self::InvalidState { operation, status } => {
|
||||
write!(f, "{operation} is invalid while execution is {status:?}")
|
||||
}
|
||||
Self::LogicalFrameDidNotClose => {
|
||||
write!(f, "logical frame did not reach FrameSync, end of ROM, or a fault")
|
||||
}
|
||||
Self::FrameNotPublished { .. } => {
|
||||
write!(f, "logical frame closed without its canonical published frame")
|
||||
}
|
||||
Self::NoFrameAvailable => write!(f, "no completed frame is available for capture"),
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
impl std::error::Error for HostError {}
|
||||
|
||||
/// In-process host. The desktop winit runner is a separate crate and is not linked here.
|
||||
pub struct HeadlessHost {
|
||||
firmware: Firmware,
|
||||
platform: HeadlessPlatform,
|
||||
signals: InputSignals,
|
||||
boot_attempted: bool,
|
||||
last_completed_frame: Option<CompletedFrame>,
|
||||
}
|
||||
|
||||
#[derive(Debug, Clone, Copy)]
|
||||
struct CompletedFrame {
|
||||
logical_frame_index: u64,
|
||||
frame_id: FrameId,
|
||||
}
|
||||
|
||||
struct HeadlessPlatform {
|
||||
hardware: Hardware,
|
||||
store: LatestRenderFrameStore,
|
||||
}
|
||||
|
||||
impl HeadlessHost {
|
||||
pub fn new() -> Self {
|
||||
let memory_banks = Arc::new(MemoryBanks::new());
|
||||
let hardware = Hardware::new_with_memory_banks(Arc::clone(&memory_banks));
|
||||
let store = LatestRenderFrameStore::default();
|
||||
Self {
|
||||
firmware: Firmware::new(None),
|
||||
platform: HeadlessPlatform { hardware, store },
|
||||
signals: InputSignals::default(),
|
||||
boot_attempted: false,
|
||||
last_completed_frame: None,
|
||||
}
|
||||
}
|
||||
|
||||
/// Load `path` and tick until the firmware is in `GameRunning`.
|
||||
///
|
||||
/// The transition into `GameRunning` is the last tick. The first game
|
||||
/// logical frame stays available for [`Self::advance_frame`].
|
||||
pub fn boot(&mut self, path: impl Into<String>) -> Result<(), HostError> {
|
||||
if self.boot_attempted {
|
||||
return Err(HostError::AlreadyBooted);
|
||||
}
|
||||
self.boot_attempted = true;
|
||||
let path = path.into();
|
||||
self.firmware.boot_target = BootTarget::Cartridge { path, debug: false, debug_port: 7777 };
|
||||
|
||||
for _ in 0..BOOT_TICK_LIMIT {
|
||||
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
|
||||
return Ok(());
|
||||
}
|
||||
if matches!(self.firmware.state, FirmwareState::AppCrashes(_)) {
|
||||
let report = self.get_fault();
|
||||
let reason = report
|
||||
.as_ref()
|
||||
.map(CrashReport::summary)
|
||||
.unwrap_or_else(|| "cartridge crashed during boot".to_string());
|
||||
return Err(HostError::BootFailed { reason, report });
|
||||
}
|
||||
if matches!(self.firmware.state, FirmwareState::HubHome(_)) {
|
||||
return Err(HostError::BootFailed {
|
||||
reason: "cartridge did not load".to_string(),
|
||||
report: None,
|
||||
});
|
||||
}
|
||||
self.tick_once();
|
||||
}
|
||||
|
||||
if matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
|
||||
Ok(())
|
||||
} else {
|
||||
Err(HostError::BootFailed {
|
||||
reason: "boot did not reach the game".to_string(),
|
||||
report: self.get_fault(),
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
pub fn reset(&mut self) {
|
||||
self.signals = InputSignals::default();
|
||||
self.firmware.change_state(
|
||||
FirmwareState::Reset(ResetStep),
|
||||
&self.signals,
|
||||
&mut self.platform,
|
||||
);
|
||||
self.platform.store = LatestRenderFrameStore::default();
|
||||
self.boot_attempted = false;
|
||||
self.last_completed_frame = None;
|
||||
}
|
||||
|
||||
pub fn pause(&mut self) -> Result<(), HostError> {
|
||||
self.require_active("pause")?;
|
||||
self.firmware.os.vm().set_paused(true);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn resume(&mut self) -> Result<(), HostError> {
|
||||
self.require_active("resume")?;
|
||||
self.firmware.os.vm().set_paused(false);
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Execute one VM instruction. This does not close a logical frame.
|
||||
pub fn step(&mut self) -> Result<Option<CrashReport>, HostError> {
|
||||
self.require_active("step")?;
|
||||
self.firmware.os.vm().set_paused(true);
|
||||
let report = self.firmware.os.vm().debug_step_active_session(&mut self.platform);
|
||||
self.platform.hardware.audio.clear_commands();
|
||||
Ok(report)
|
||||
}
|
||||
|
||||
pub fn advance_frame(&mut self) -> Result<AdvanceFrameOutcome, HostError> {
|
||||
if let Some(report) = self.get_fault() {
|
||||
return Ok(AdvanceFrameOutcome::Faulted(report));
|
||||
}
|
||||
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
|
||||
return Ok(AdvanceFrameOutcome::Terminated);
|
||||
}
|
||||
|
||||
let start = self.firmware.os.vm().logical_frame_index();
|
||||
let previous_frame_id = self.platform.store.latest_frame().map(|frame| frame.frame_id);
|
||||
self.firmware.os.vm().set_paused(false);
|
||||
self.firmware.os.vm().request_debug_step();
|
||||
|
||||
for _ in 0..LOGICAL_FRAME_TICK_LIMIT {
|
||||
self.tick_once();
|
||||
if let Some(report) = self.get_fault() {
|
||||
self.finish_frame_step();
|
||||
return Ok(AdvanceFrameOutcome::Faulted(report));
|
||||
}
|
||||
if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
|
||||
return Ok(AdvanceFrameOutcome::Terminated);
|
||||
}
|
||||
|
||||
let logical_frame_index = self.firmware.os.vm().logical_frame_index();
|
||||
if logical_frame_index > start {
|
||||
self.finish_frame_step();
|
||||
let frame = self
|
||||
.platform
|
||||
.store
|
||||
.latest_frame()
|
||||
.ok_or(HostError::FrameNotPublished { previous: previous_frame_id })?;
|
||||
if Some(frame.frame_id) == previous_frame_id {
|
||||
return Err(HostError::FrameNotPublished { previous: previous_frame_id });
|
||||
}
|
||||
self.last_completed_frame =
|
||||
Some(CompletedFrame { logical_frame_index, frame_id: frame.frame_id });
|
||||
return Ok(AdvanceFrameOutcome::FrameCompleted {
|
||||
logical_frame_index,
|
||||
frame_id: frame.frame_id,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
self.finish_frame_step();
|
||||
Err(HostError::LogicalFrameDidNotClose)
|
||||
}
|
||||
|
||||
pub fn advance_frames(&mut self, count: u64) -> Result<AdvanceFramesOutcome, HostError> {
|
||||
let mut completed = 0;
|
||||
for _ in 0..count {
|
||||
match self.advance_frame()? {
|
||||
AdvanceFrameOutcome::FrameCompleted { .. } => completed += 1,
|
||||
AdvanceFrameOutcome::Faulted(report) => {
|
||||
return Ok(AdvanceFramesOutcome {
|
||||
requested: count,
|
||||
completed,
|
||||
stop: AdvanceFramesStop::Faulted(report),
|
||||
});
|
||||
}
|
||||
AdvanceFrameOutcome::Terminated => {
|
||||
return Ok(AdvanceFramesOutcome {
|
||||
requested: count,
|
||||
completed,
|
||||
stop: AdvanceFramesStop::Terminated,
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(AdvanceFramesOutcome { requested: count, completed, stop: AdvanceFramesStop::Completed })
|
||||
}
|
||||
|
||||
pub fn set_input(&mut self, signals: InputSignals) {
|
||||
self.signals = signals;
|
||||
}
|
||||
|
||||
pub fn clear_input(&mut self) {
|
||||
self.signals = InputSignals::default();
|
||||
}
|
||||
|
||||
pub fn set_right(&mut self, down: bool) {
|
||||
self.signals.right_signal = down;
|
||||
}
|
||||
|
||||
pub fn capture_frame(&self) -> Result<CapturedFrame, HostError> {
|
||||
let completed = self.last_completed_frame.ok_or(HostError::NoFrameAvailable)?;
|
||||
let frame = self.platform.store.latest_frame().ok_or(HostError::NoFrameAvailable)?;
|
||||
if frame.frame_id != completed.frame_id {
|
||||
return Err(HostError::FrameNotPublished { previous: Some(completed.frame_id) });
|
||||
}
|
||||
Ok(CapturedFrame { logical_frame_index: completed.logical_frame_index, frame })
|
||||
}
|
||||
|
||||
pub fn get_state(&mut self) -> HostState {
|
||||
let status = self.execution_status();
|
||||
HostState {
|
||||
pc: self.firmware.os.vm().active_pc().unwrap_or(0),
|
||||
stack_top: self.firmware.os.vm().active_operand_stack_top(10),
|
||||
frame_index: self.firmware.os.vm().logical_frame_index(),
|
||||
tick_index: self.firmware.os.vm().tick_index(),
|
||||
app_id: self.firmware.os.vm().current_app_id(),
|
||||
status,
|
||||
}
|
||||
}
|
||||
|
||||
pub fn get_fault(&mut self) -> Option<CrashReport> {
|
||||
if let Some(report) = self.firmware.os.vm().last_crash_report() {
|
||||
return Some(report.clone());
|
||||
}
|
||||
match &self.firmware.state {
|
||||
FirmwareState::AppCrashes(AppCrashesStep { report }) => Some(report.clone()),
|
||||
_ => None,
|
||||
}
|
||||
}
|
||||
|
||||
fn tick_once(&mut self) {
|
||||
self.firmware.tick(&self.signals, &mut self.platform);
|
||||
self.platform.hardware.audio.clear_commands();
|
||||
}
|
||||
|
||||
fn execution_status(&mut self) -> HostExecutionStatus {
|
||||
if self.fault_is_visible() {
|
||||
HostExecutionStatus::Faulted
|
||||
} else if !matches!(self.firmware.state, FirmwareState::GameRunning(_)) {
|
||||
HostExecutionStatus::Terminated
|
||||
} else if self.firmware.os.vm().paused() {
|
||||
HostExecutionStatus::Paused
|
||||
} else {
|
||||
HostExecutionStatus::Running
|
||||
}
|
||||
}
|
||||
|
||||
fn fault_is_visible(&mut self) -> bool {
|
||||
self.firmware.os.vm().last_crash_report().is_some()
|
||||
|| matches!(self.firmware.state, FirmwareState::AppCrashes(_))
|
||||
}
|
||||
|
||||
fn require_active(&mut self, operation: &'static str) -> Result<(), HostError> {
|
||||
let status = self.execution_status();
|
||||
if matches!(status, HostExecutionStatus::Running | HostExecutionStatus::Paused) {
|
||||
Ok(())
|
||||
} else {
|
||||
Err(HostError::InvalidState { operation, status })
|
||||
}
|
||||
}
|
||||
|
||||
fn finish_frame_step(&mut self) {
|
||||
self.firmware.os.vm().set_paused(true);
|
||||
self.firmware.os.vm().clear_debug_step_request();
|
||||
}
|
||||
}
|
||||
|
||||
impl Default for HeadlessHost {
|
||||
fn default() -> Self {
|
||||
Self::new()
|
||||
}
|
||||
}
|
||||
|
||||
impl RenderSubmissionSink for HeadlessPlatform {
|
||||
fn submit_render_submission(
|
||||
&mut self,
|
||||
submission: RenderSubmission,
|
||||
) -> Result<(), RenderSubmitError> {
|
||||
let frame_id = submission.frame_id;
|
||||
let ownership = submission.ownership;
|
||||
self.hardware.submit_render_submission(submission)?;
|
||||
let (width, height) = self.hardware.gfx.size();
|
||||
let pixels = self.hardware.gfx.front_buffer().to_vec();
|
||||
let frame = OwnedRgba8888Frame::packed(frame_id, ownership, width, height, pixels)
|
||||
.map_err(|_| RenderSubmitError::SubmissionRejected)?;
|
||||
self.store.publish_frame(frame);
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
impl RuntimePlatform for HeadlessPlatform {
|
||||
fn display_size(&self) -> (usize, usize) {
|
||||
(Hardware::W, Hardware::H)
|
||||
}
|
||||
|
||||
fn render_submission_sink(&mut self) -> &mut dyn RenderSubmissionSink {
|
||||
self
|
||||
}
|
||||
|
||||
fn render_backend(&mut self) -> &mut dyn RenderBackend {
|
||||
&mut self.hardware
|
||||
}
|
||||
|
||||
fn game2d_frame_composer(&mut self) -> &mut dyn Game2DFrameComposer {
|
||||
&mut self.hardware
|
||||
}
|
||||
|
||||
fn audio(&self) -> &dyn AudioBridge {
|
||||
self.hardware.audio()
|
||||
}
|
||||
|
||||
fn audio_mut(&mut self) -> &mut dyn AudioBridge {
|
||||
self.hardware.audio_mut()
|
||||
}
|
||||
|
||||
fn input(&self) -> &dyn InputPlatform {
|
||||
self.hardware.input()
|
||||
}
|
||||
|
||||
fn input_mut(&mut self) -> &mut dyn InputPlatform {
|
||||
self.hardware.input_mut()
|
||||
}
|
||||
|
||||
fn assets(&self) -> &dyn AssetBridge {
|
||||
self.hardware.assets()
|
||||
}
|
||||
|
||||
fn assets_mut(&mut self) -> &mut dyn AssetBridge {
|
||||
self.hardware.assets_mut()
|
||||
}
|
||||
|
||||
fn telemetry(&self) -> &dyn TelemetryPlatform {
|
||||
self.hardware.telemetry()
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
//! Headless Prometeu host.
|
||||
//!
|
||||
//! This crate boots a directory cartridge and steps logical frames in process.
|
||||
//! It does not open a window, a display surface, or an audio device.
|
||||
//!
|
||||
//! The desktop host's `stepFrame` command still advances on the 60 Hz winit loop.
|
||||
//! That pacing stays in `prometeu-host-desktop-winit` until a later protocol agenda.
|
||||
|
||||
mod host;
|
||||
|
||||
pub use host::{
|
||||
AdvanceFrameOutcome, AdvanceFramesOutcome, AdvanceFramesStop, CapturedFrame, HeadlessHost,
|
||||
HostError, HostExecutionStatus, HostState,
|
||||
};
|
||||
@@ -0,0 +1,639 @@
|
||||
use std::fs;
|
||||
use std::path::Path;
|
||||
use std::time::{Duration, Instant};
|
||||
|
||||
use prometeu_bytecode::SourceSpan;
|
||||
use prometeu_bytecode::assembler::assemble;
|
||||
use prometeu_bytecode::model::{BytecodeModule, DebugInfo, Export, FunctionMeta, SyscallDecl};
|
||||
use prometeu_hal::InputSignals;
|
||||
use prometeu_hal::app_mode::AppMode;
|
||||
use prometeu_hal::color::Color;
|
||||
use prometeu_host_headless::{
|
||||
AdvanceFrameOutcome, AdvanceFramesStop, CapturedFrame, HeadlessHost, HostError,
|
||||
HostExecutionStatus, HostState,
|
||||
};
|
||||
use prometeu_system::CrashReport;
|
||||
|
||||
const RED: u32 = Color::RED.raw();
|
||||
const BLUE: u32 = Color::BLUE.raw();
|
||||
const GREEN: u32 = Color::GREEN.raw();
|
||||
const BLACK: u32 = Color::BLACK.raw();
|
||||
|
||||
#[test]
|
||||
fn headless_source_has_no_timing_wait_or_interactive_backend_dependency() {
|
||||
let source = include_str!("../src/host.rs");
|
||||
let manifest = include_str!("../Cargo.toml");
|
||||
|
||||
for forbidden in
|
||||
["FRAME_PUBLISH_SPINS", "spin_loop", "thread::sleep", "ensure_worker", "RenderWorkerConfig"]
|
||||
{
|
||||
assert!(!source.contains(forbidden), "headless source contains {forbidden}");
|
||||
}
|
||||
for forbidden in ["winit", "pixels", "cpal"] {
|
||||
assert!(!manifest.contains(forbidden), "headless manifest contains {forbidden}");
|
||||
}
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn lifecycle_state_and_preconditions_are_structural() {
|
||||
let mut host = HeadlessHost::new();
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Terminated);
|
||||
assert_eq!(host.capture_frame(), Err(HostError::NoFrameAvailable));
|
||||
assert_eq!(
|
||||
host.pause(),
|
||||
Err(HostError::InvalidState {
|
||||
operation: "pause",
|
||||
status: HostExecutionStatus::Terminated,
|
||||
})
|
||||
);
|
||||
|
||||
let cartridge = color_cartridge();
|
||||
host.boot(&cartridge).expect("boot");
|
||||
let booted = host.get_state();
|
||||
assert_eq!(booted.status, HostExecutionStatus::Running);
|
||||
assert_eq!(booted.pc, 0, "boot must not execute the first game instruction");
|
||||
assert_eq!(host.boot(&cartridge), Err(HostError::AlreadyBooted));
|
||||
|
||||
host.pause().expect("pause");
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
|
||||
host.resume().expect("resume");
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Running);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn step_does_not_complete_a_logical_frame() {
|
||||
let mut host = boot_color();
|
||||
let before = host.get_state();
|
||||
assert_eq!(host.step().expect("step"), None);
|
||||
let after = host.get_state();
|
||||
assert_eq!(after.frame_index, before.frame_index);
|
||||
assert_ne!(after.pc, before.pc);
|
||||
assert_eq!(after.status, HostExecutionStatus::Paused);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn stepping_frame_sync_is_not_a_fault_or_completed_runtime_frame() {
|
||||
let dir = temp_cart("step-frame-sync");
|
||||
write_cartridge(&dir, 51, "Step Frame Sync", &module(asm("FRAME_SYNC\nRET\n"), vec![]), &[]);
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(&dir).expect("boot frame-sync cartridge");
|
||||
let before = host.get_state().frame_index;
|
||||
|
||||
assert_eq!(host.step().expect("step frame sync"), None);
|
||||
assert_eq!(host.get_state().frame_index, before);
|
||||
assert!(host.get_fault().is_none());
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn one_logical_frame_may_span_multiple_internal_ticks() {
|
||||
let dir = temp_cart("multi-tick");
|
||||
write_cartridge(&dir, 47, "Multi Tick", &multi_tick_program(), &[]);
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(&dir).expect("boot multi-tick cartridge");
|
||||
let before = host.get_state();
|
||||
|
||||
completed(host.advance_frame().expect("multi-tick frame"));
|
||||
|
||||
let after = host.get_state();
|
||||
assert_eq!(after.frame_index, before.frame_index + 1);
|
||||
assert!(after.tick_index >= before.tick_index + 2);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn outer_frame_limit_is_a_host_error_and_finishes_paused() {
|
||||
let dir = temp_cart("frame-limit");
|
||||
write_cartridge(&dir, 50, "Frame Limit", &module(asm("JMP 0\n"), vec![]), &[]);
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(&dir).expect("boot non-closing cartridge");
|
||||
|
||||
assert_eq!(host.advance_frame(), Err(HostError::LogicalFrameDidNotClose));
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
|
||||
assert!(host.get_fault().is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn one_frame_returns_and_captures_the_exact_published_frame() {
|
||||
let mut host = boot_color();
|
||||
let before = host.get_state().frame_index;
|
||||
let (logical_frame_index, frame_id) = completed(host.advance_frame().expect("frame"));
|
||||
let captured = host.capture_frame().expect("capture");
|
||||
|
||||
assert_eq!(logical_frame_index, before + 1);
|
||||
assert_eq!(captured.logical_frame_index, logical_frame_index);
|
||||
assert_eq!(captured.frame.frame_id, frame_id);
|
||||
assert_eq!(captured.frame.ownership.app_mode, AppMode::Game);
|
||||
assert_eq!(captured.frame.ownership.app_id, 41);
|
||||
assert_eq!(captured.frame.stride_pixels, captured.frame.width);
|
||||
assert_eq!(captured.frame.pixels.len(), 480 * 270);
|
||||
assert_eq!(host.capture_frame().expect("repeat capture"), captured);
|
||||
|
||||
let mut mutated_clone = captured.clone();
|
||||
mutated_clone.frame.pixels[0] = GREEN;
|
||||
assert_ne!(host.capture_frame().expect("owned capture").frame.pixels[0], GREEN);
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Paused);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn zero_frames_is_an_explicit_noop() {
|
||||
let mut host = boot_color();
|
||||
let before = host.get_state();
|
||||
let outcome = host.advance_frames(0).expect("zero frames");
|
||||
|
||||
assert_eq!(outcome.requested, 0);
|
||||
assert_eq!(outcome.completed, 0);
|
||||
assert_eq!(outcome.stop, AdvanceFramesStop::Completed);
|
||||
let after = host.get_state();
|
||||
assert_eq!(after.frame_index, before.frame_index);
|
||||
assert_eq!(after.tick_index, before.tick_index);
|
||||
assert_eq!(after.status, before.status);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn clear_input_drops_right() {
|
||||
let mut host = boot_color();
|
||||
host.set_right(true);
|
||||
host.clear_input();
|
||||
completed(host.advance_frame().expect("frame"));
|
||||
assert_color(&host.capture_frame().expect("frame"), BLUE);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn right_hold_then_release_changes_pixels() {
|
||||
let mut host = boot_color();
|
||||
let before = host.get_state().frame_index;
|
||||
|
||||
host.set_right(true);
|
||||
assert_completed(host.advance_frames(60).expect("hold"), 60);
|
||||
let held = host.capture_frame().expect("held frame");
|
||||
assert_eq!(host.get_state().frame_index, before + 60);
|
||||
assert_color(&held, RED);
|
||||
assert!(host.get_fault().is_none());
|
||||
|
||||
host.set_right(false);
|
||||
assert_completed(host.advance_frames(1).expect("release"), 1);
|
||||
let released = host.capture_frame().expect("released frame");
|
||||
assert_eq!(released.logical_frame_index, before + 61);
|
||||
assert_color(&released, BLUE);
|
||||
assert!(host.get_fault().is_none());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn normalized_button_press_hold_release_and_clear_are_observable() {
|
||||
let mut host = boot_input_edges();
|
||||
|
||||
let mut signals = InputSignals { right_signal: true, ..InputSignals::default() };
|
||||
host.set_input(signals);
|
||||
completed(host.advance_frame().expect("press"));
|
||||
assert_color(&host.capture_frame().expect("pressed"), RED);
|
||||
|
||||
completed(host.advance_frame().expect("hold"));
|
||||
assert_color(&host.capture_frame().expect("held"), BLUE);
|
||||
|
||||
signals.right_signal = false;
|
||||
host.set_input(signals);
|
||||
completed(host.advance_frame().expect("release"));
|
||||
assert_color(&host.capture_frame().expect("released"), GREEN);
|
||||
|
||||
host.set_input(InputSignals {
|
||||
right_signal: true,
|
||||
f_signal: true,
|
||||
x_pos: 123,
|
||||
y_pos: 45,
|
||||
..InputSignals::default()
|
||||
});
|
||||
host.clear_input();
|
||||
completed(host.advance_frame().expect("clear"));
|
||||
assert_color(&host.capture_frame().expect("cleared"), BLACK);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn normalized_touch_edges_and_coordinates_use_the_same_input_surface() {
|
||||
let mut host = boot_touch_edges();
|
||||
let mut signals =
|
||||
InputSignals { f_signal: true, x_pos: 123, y_pos: 45, ..InputSignals::default() };
|
||||
|
||||
host.set_input(signals);
|
||||
completed(host.advance_frame().expect("touch press"));
|
||||
assert_color(&host.capture_frame().expect("touch pressed"), RED);
|
||||
|
||||
completed(host.advance_frame().expect("touch hold"));
|
||||
assert_color(&host.capture_frame().expect("touch held"), BLUE);
|
||||
|
||||
signals.f_signal = false;
|
||||
host.set_input(signals);
|
||||
completed(host.advance_frame().expect("touch release"));
|
||||
assert_color(&host.capture_frame().expect("touch released"), GREEN);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn two_runs_match_oracle() {
|
||||
let first = run_color_sequence();
|
||||
let second = run_color_sequence();
|
||||
assert_eq!(first.held.logical_frame_index, second.held.logical_frame_index);
|
||||
assert_eq!(first.held.frame.pixels, second.held.frame.pixels);
|
||||
assert_eq!(first.held.frame.frame_id, second.held.frame.frame_id);
|
||||
assert_eq!(first.released.frame.pixels, second.released.frame.pixels);
|
||||
assert_eq!(first.released.frame.frame_id, second.released.frame.frame_id);
|
||||
assert_eq!(first.released.logical_frame_index, second.released.logical_frame_index);
|
||||
assert_same_state(&first.state, &second.state);
|
||||
assert_eq!(first.fault, second.fault);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn reset_matches_fresh_host() {
|
||||
let mut host = boot_color();
|
||||
let _ = run_on(&mut host);
|
||||
host.reset();
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Terminated);
|
||||
assert_eq!(host.capture_frame(), Err(HostError::NoFrameAvailable));
|
||||
host.boot(color_cartridge()).expect("reboot");
|
||||
let after_reset = run_on(&mut host);
|
||||
let fresh = run_color_sequence();
|
||||
|
||||
assert_eq!(after_reset.held.frame.pixels, fresh.held.frame.pixels);
|
||||
assert_eq!(after_reset.released.frame.pixels, fresh.released.frame.pixels);
|
||||
assert_eq!(after_reset.held.frame.frame_id, fresh.held.frame.frame_id);
|
||||
assert_eq!(after_reset.released.frame.frame_id, fresh.released.frame.frame_id);
|
||||
assert_eq!(after_reset.released.logical_frame_index, fresh.released.logical_frame_index);
|
||||
assert_same_state(&after_reset.state, &fresh.state);
|
||||
assert_eq!(after_reset.fault, fresh.fault);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn trap_is_structured() {
|
||||
let dir = temp_cart("fault");
|
||||
write_cartridge(&dir, 42, "Fault", &fault_program(), &[]);
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(&dir).expect("boot fault cartridge");
|
||||
let outcome = host.advance_frame().expect("faulting frame");
|
||||
|
||||
match outcome {
|
||||
AdvanceFrameOutcome::Faulted(CrashReport::VmTrap { trap }) => {
|
||||
assert_eq!(trap.code, prometeu_bytecode::TRAP_EXPLICIT);
|
||||
assert_eq!(trap.opcode, prometeu_bytecode::isa::core::CoreOpCode::Trap as u16);
|
||||
assert_eq!(trap.pc, 0);
|
||||
assert_eq!(trap.span, Some(SourceSpan { file_id: 7, start: 11, end: 15 }));
|
||||
assert!(trap.message.contains("main"));
|
||||
}
|
||||
other => panic!("expected VmTrap outcome, got {other:?}"),
|
||||
}
|
||||
assert!(matches!(host.get_fault(), Some(CrashReport::VmTrap { .. })));
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Faulted);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn instruction_step_fault_remains_structured() {
|
||||
let dir = temp_cart("step-fault");
|
||||
write_cartridge(&dir, 48, "Step Fault", &fault_program(), &[]);
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(&dir).expect("boot fault cartridge");
|
||||
|
||||
let report = host.step().expect("step result").expect("structured step fault");
|
||||
assert!(matches!(report, CrashReport::VmTrap { .. }));
|
||||
assert_eq!(host.get_fault(), Some(report));
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Faulted);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn batch_stops_early_on_fault_and_reports_partial_progress() {
|
||||
let dir = temp_cart("fault-batch");
|
||||
write_cartridge(&dir, 43, "Fault Batch", &delayed_fault_program(), &gfx_syscalls());
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(&dir).expect("boot fault cartridge");
|
||||
|
||||
let outcome = host.advance_frames(5).expect("batch outcome");
|
||||
assert_eq!(outcome.requested, 5);
|
||||
assert_eq!(outcome.completed, 2);
|
||||
assert!(matches!(outcome.stop, AdvanceFramesStop::Faulted(CrashReport::VmTrap { .. })));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn advance_after_reset_reports_termination_without_ticking() {
|
||||
let mut host = boot_color();
|
||||
host.reset();
|
||||
let before = host.get_state().tick_index;
|
||||
|
||||
assert_eq!(host.advance_frame().expect("termination outcome"), AdvanceFrameOutcome::Terminated);
|
||||
assert_eq!(host.get_state().tick_index, before);
|
||||
let batch = host.advance_frames(3).expect("terminated batch");
|
||||
assert_eq!(batch.completed, 0);
|
||||
assert_eq!(batch.stop, AdvanceFramesStop::Terminated);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn vm_init_failure_is_returned_as_structured_boot_failure() {
|
||||
let dir = temp_cart("bad-pbx");
|
||||
write_cartridge(&dir, 44, "Bad PBX", b"not a pbx", &[]);
|
||||
let mut host = HeadlessHost::new();
|
||||
|
||||
let error = host.boot(&dir).expect_err("invalid PBX must fail boot");
|
||||
assert!(matches!(
|
||||
error,
|
||||
HostError::BootFailed { report: Some(CrashReport::VmInit { .. }), .. }
|
||||
));
|
||||
assert_eq!(host.get_state().status, HostExecutionStatus::Faulted);
|
||||
assert!(matches!(host.get_fault(), Some(CrashReport::VmInit { .. })));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn end_of_rom_completes_a_logical_frame() {
|
||||
let dir = temp_cart("end-of-rom");
|
||||
write_cartridge(&dir, 45, "End Of Rom", &module(asm("RET\n"), vec![]), &[]);
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(&dir).expect("boot end-of-rom cartridge");
|
||||
|
||||
let first = completed(host.advance_frame().expect("first frame"));
|
||||
let second = completed(host.advance_frame().expect("second frame"));
|
||||
assert_eq!(second.0, first.0 + 1);
|
||||
assert_ne!(second.1, first.1);
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn three_hundred_frames_finish_without_refresh_sleep() {
|
||||
let mut host = boot_color();
|
||||
let started = Instant::now();
|
||||
assert_completed(host.advance_frames(300).expect("fast frames"), 300);
|
||||
assert!(started.elapsed() < Duration::from_secs(2));
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn audio_play_does_not_need_a_device() {
|
||||
let mut host = boot_color();
|
||||
completed(host.advance_frame().expect("frame with audio.play"));
|
||||
assert!(host.get_fault().is_none());
|
||||
assert_color(&host.capture_frame().expect("frame"), BLUE);
|
||||
}
|
||||
|
||||
struct ColorOracle {
|
||||
held: CapturedFrame,
|
||||
released: CapturedFrame,
|
||||
state: HostState,
|
||||
fault: Option<CrashReport>,
|
||||
}
|
||||
|
||||
fn boot_color() -> HeadlessHost {
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(color_cartridge()).expect("boot color cartridge");
|
||||
host
|
||||
}
|
||||
|
||||
fn boot_input_edges() -> HeadlessHost {
|
||||
let dir = temp_cart("input-edges");
|
||||
write_cartridge(&dir, 46, "Input Edges", &input_edge_program(), &gfx_syscalls());
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(&dir).expect("boot input cartridge");
|
||||
host
|
||||
}
|
||||
|
||||
fn boot_touch_edges() -> HeadlessHost {
|
||||
let dir = temp_cart("touch-edges");
|
||||
write_cartridge(&dir, 49, "Touch Edges", &touch_edge_program(), &gfx_syscalls());
|
||||
let mut host = HeadlessHost::new();
|
||||
host.boot(&dir).expect("boot touch cartridge");
|
||||
host
|
||||
}
|
||||
|
||||
fn color_cartridge() -> String {
|
||||
let dir = temp_cart("color");
|
||||
write_cartridge(&dir, 41, "Right Pixel", &color_program(), &color_syscalls());
|
||||
dir
|
||||
}
|
||||
|
||||
fn run_color_sequence() -> ColorOracle {
|
||||
let mut host = boot_color();
|
||||
run_on(&mut host)
|
||||
}
|
||||
|
||||
fn run_on(host: &mut HeadlessHost) -> ColorOracle {
|
||||
host.set_right(true);
|
||||
assert_completed(host.advance_frames(60).expect("hold"), 60);
|
||||
let held = host.capture_frame().expect("held");
|
||||
host.set_right(false);
|
||||
assert_completed(host.advance_frames(1).expect("release"), 1);
|
||||
let released = host.capture_frame().expect("released");
|
||||
let state = host.get_state();
|
||||
let fault = host.get_fault();
|
||||
ColorOracle { held, released, state, fault }
|
||||
}
|
||||
|
||||
fn completed(outcome: AdvanceFrameOutcome) -> (u64, prometeu_hal::FrameId) {
|
||||
match outcome {
|
||||
AdvanceFrameOutcome::FrameCompleted { logical_frame_index, frame_id } => {
|
||||
(logical_frame_index, frame_id)
|
||||
}
|
||||
other => panic!("expected completed frame, got {other:?}"),
|
||||
}
|
||||
}
|
||||
|
||||
fn assert_completed(outcome: prometeu_host_headless::AdvanceFramesOutcome, expected: u64) {
|
||||
assert_eq!(outcome.requested, expected);
|
||||
assert_eq!(outcome.completed, expected);
|
||||
assert_eq!(outcome.stop, AdvanceFramesStop::Completed);
|
||||
}
|
||||
|
||||
fn assert_color(captured: &CapturedFrame, color: u32) {
|
||||
assert_eq!(captured.frame.width, 480);
|
||||
assert_eq!(captured.frame.height, 270);
|
||||
assert!(captured.frame.pixels.iter().all(|pixel| *pixel == color));
|
||||
}
|
||||
|
||||
fn assert_same_state(left: &HostState, right: &HostState) {
|
||||
assert_eq!(left.pc, right.pc);
|
||||
assert_eq!(left.frame_index, right.frame_index);
|
||||
assert_eq!(left.tick_index, right.tick_index);
|
||||
assert_eq!(left.app_id, right.app_id);
|
||||
assert_eq!(left.status, right.status);
|
||||
assert_eq!(format!("{:?}", left.stack_top), format!("{:?}", right.stack_top));
|
||||
}
|
||||
|
||||
fn temp_cart(name: &str) -> String {
|
||||
let dir = std::env::temp_dir().join(format!(
|
||||
"prometeu-headless-{name}-{}-{}",
|
||||
std::process::id(),
|
||||
std::time::SystemTime::now().duration_since(std::time::UNIX_EPOCH).unwrap().as_nanos()
|
||||
));
|
||||
fs::create_dir_all(&dir).expect("temp cartridge dir");
|
||||
dir.to_string_lossy().into_owned()
|
||||
}
|
||||
|
||||
fn write_cartridge(dir: &str, app_id: u32, title: &str, program: &[u8], syscalls: &[SyscallDecl]) {
|
||||
let path = Path::new(dir);
|
||||
fs::write(path.join("program.pbx"), program).expect("program");
|
||||
fs::write(
|
||||
path.join("manifest.json"),
|
||||
format!(
|
||||
"{{\n \"magic\": \"PMTU\",\n \"cartridge_version\": 1,\n \"app_id\": {app_id},\n \"title\": \"{title}\",\n \"app_version\": \"0.1.0\",\n \"app_mode\": \"Game\",\n \"capabilities\": [\"gfx2d\", \"audio\"]\n}}\n"
|
||||
),
|
||||
)
|
||||
.expect("manifest");
|
||||
let _ = syscalls;
|
||||
}
|
||||
|
||||
fn color_program() -> Vec<u8> {
|
||||
let mut rom = Vec::new();
|
||||
rom.extend(asm("PUSH_I32 0\n\
|
||||
PUSH_I32 0\n\
|
||||
PUSH_I32 0\n\
|
||||
PUSH_I32 255\n\
|
||||
PUSH_I32 128\n\
|
||||
PUSH_I32 1\n\
|
||||
PUSH_I32 0\n\
|
||||
HOSTCALL 1\n\
|
||||
POP_N 1\n\
|
||||
INTRINSIC 0x2000\n\
|
||||
INTRINSIC 0x2013\n\
|
||||
INTRINSIC 0x2032\n"));
|
||||
let jump_to_blue = rom.len() + 2;
|
||||
rom.extend(asm("JMP_IF_FALSE 0"));
|
||||
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
let blue_at = rom.len() as u32;
|
||||
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
rom[jump_to_blue..jump_to_blue + 4].copy_from_slice(&blue_at.to_le_bytes());
|
||||
module(rom, color_syscalls())
|
||||
}
|
||||
|
||||
fn input_edge_program() -> Vec<u8> {
|
||||
let mut rom = Vec::new();
|
||||
let pressed_jump = emit_right_predicate(&mut rom, 0x2030);
|
||||
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
let released_at = rom.len() as u32;
|
||||
rom[pressed_jump..pressed_jump + 4].copy_from_slice(&released_at.to_le_bytes());
|
||||
|
||||
let released_jump = emit_right_predicate(&mut rom, 0x2031);
|
||||
rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
let down_at = rom.len() as u32;
|
||||
rom[released_jump..released_jump + 4].copy_from_slice(&down_at.to_le_bytes());
|
||||
|
||||
let down_jump = emit_right_predicate(&mut rom, 0x2032);
|
||||
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
let idle_at = rom.len() as u32;
|
||||
rom[down_jump..down_jump + 4].copy_from_slice(&idle_at.to_le_bytes());
|
||||
rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
|
||||
module(rom, gfx_syscalls())
|
||||
}
|
||||
|
||||
fn emit_right_predicate(rom: &mut Vec<u8>, predicate: u32) -> usize {
|
||||
rom.extend(asm(&format!("INTRINSIC 0x2000\nINTRINSIC 0x2013\nINTRINSIC {predicate:#x}\n")));
|
||||
let target = rom.len() + 2;
|
||||
rom.extend(asm("JMP_IF_FALSE 0\n"));
|
||||
target
|
||||
}
|
||||
|
||||
fn touch_edge_program() -> Vec<u8> {
|
||||
let mut rom = Vec::new();
|
||||
let pressed_jump = emit_touch_predicate(&mut rom, 0x2030);
|
||||
rom.extend(asm(&format!("PUSH_I64 {RED}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
let released_at = rom.len() as u32;
|
||||
rom[pressed_jump..pressed_jump + 4].copy_from_slice(&released_at.to_le_bytes());
|
||||
|
||||
let released_jump = emit_touch_predicate(&mut rom, 0x2031);
|
||||
rom.extend(asm(&format!("PUSH_I64 {GREEN}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
let down_at = rom.len() as u32;
|
||||
rom[released_jump..released_jump + 4].copy_from_slice(&down_at.to_le_bytes());
|
||||
|
||||
let down_jump = emit_touch_predicate(&mut rom, 0x2032);
|
||||
rom.extend(asm(&format!("PUSH_I64 {BLUE}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
let idle_at = rom.len() as u32;
|
||||
rom[down_jump..down_jump + 4].copy_from_slice(&idle_at.to_le_bytes());
|
||||
rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
|
||||
module(rom, gfx_syscalls())
|
||||
}
|
||||
|
||||
fn emit_touch_predicate(rom: &mut Vec<u8>, predicate: u32) -> usize {
|
||||
rom.extend(asm(&format!(
|
||||
"INTRINSIC 0x2001\nINTRINSIC 0x2020\nINTRINSIC {predicate:#x}\n\
|
||||
INTRINSIC 0x2001\nINTRINSIC 0x2021\nPUSH_I64 123\nEQ\nAND\n\
|
||||
INTRINSIC 0x2001\nINTRINSIC 0x2022\nPUSH_I64 45\nEQ\nAND\n"
|
||||
)));
|
||||
let target = rom.len() + 2;
|
||||
rom.extend(asm("JMP_IF_FALSE 0\n"));
|
||||
target
|
||||
}
|
||||
|
||||
fn fault_program() -> Vec<u8> {
|
||||
// `INTRINSIC 0xDEADBEEF` is rejected by the loader as `VerificationFailed`.
|
||||
// `TRAP` is a legal instruction that becomes `CrashReport::VmTrap` at runtime.
|
||||
module(asm("TRAP\nFRAME_SYNC\nRET\n"), vec![])
|
||||
}
|
||||
|
||||
fn delayed_fault_program() -> Vec<u8> {
|
||||
let mut rom =
|
||||
asm("GET_GLOBAL 0\nPUSH_I32 1\nADD\nSET_GLOBAL 0\nGET_GLOBAL 0\nPUSH_I32 3\nEQ\n");
|
||||
let continue_jump = rom.len() + 2;
|
||||
rom.extend(asm("JMP_IF_FALSE 0\nTRAP\n"));
|
||||
let continue_at = rom.len() as u32;
|
||||
rom[continue_jump..continue_jump + 4].copy_from_slice(&continue_at.to_le_bytes());
|
||||
rom.extend(asm(&format!("PUSH_I64 {BLACK}\nHOSTCALL 0\nFRAME_SYNC\nRET\n")));
|
||||
module(rom, gfx_syscalls())
|
||||
}
|
||||
|
||||
fn multi_tick_program() -> Vec<u8> {
|
||||
let mut rom = asm("PUSH_I32 30000\nSET_LOCAL 0\n");
|
||||
let loop_at = rom.len() as u32;
|
||||
rom.extend(asm("GET_LOCAL 0\nPUSH_I32 1\nSUB\nSET_LOCAL 0\nGET_LOCAL 0\nPUSH_I32 0\nGT\n"));
|
||||
rom.extend(asm(&format!("JMP_IF_TRUE {loop_at}\nFRAME_SYNC\nRET\n")));
|
||||
module_with_locals(rom, vec![], 1)
|
||||
}
|
||||
|
||||
fn color_syscalls() -> Vec<SyscallDecl> {
|
||||
vec![
|
||||
SyscallDecl {
|
||||
module: "gfx2d".into(),
|
||||
name: "clear".into(),
|
||||
version: 1,
|
||||
arg_slots: 1,
|
||||
ret_slots: 0,
|
||||
},
|
||||
SyscallDecl {
|
||||
module: "audio".into(),
|
||||
name: "play".into(),
|
||||
version: 1,
|
||||
arg_slots: 7,
|
||||
ret_slots: 1,
|
||||
},
|
||||
]
|
||||
}
|
||||
|
||||
fn gfx_syscalls() -> Vec<SyscallDecl> {
|
||||
vec![SyscallDecl {
|
||||
module: "gfx2d".into(),
|
||||
name: "clear".into(),
|
||||
version: 1,
|
||||
arg_slots: 1,
|
||||
ret_slots: 0,
|
||||
}]
|
||||
}
|
||||
|
||||
fn module(code: Vec<u8>, syscalls: Vec<SyscallDecl>) -> Vec<u8> {
|
||||
module_with_locals(code, syscalls, 0)
|
||||
}
|
||||
|
||||
fn module_with_locals(code: Vec<u8>, syscalls: Vec<SyscallDecl>, local_slots: u16) -> Vec<u8> {
|
||||
BytecodeModule {
|
||||
version: 0,
|
||||
const_pool: vec![],
|
||||
functions: vec![FunctionMeta {
|
||||
code_offset: 0,
|
||||
code_len: code.len() as u32,
|
||||
param_slots: 0,
|
||||
local_slots,
|
||||
return_slots: 0,
|
||||
max_stack_slots: 8,
|
||||
}],
|
||||
code,
|
||||
debug_info: Some(DebugInfo {
|
||||
pc_to_span: vec![(0, SourceSpan { file_id: 7, start: 11, end: 15 })],
|
||||
function_names: vec![(0, "main".into())],
|
||||
}),
|
||||
exports: vec![Export { symbol: "main".into(), func_idx: 0 }],
|
||||
syscalls,
|
||||
}
|
||||
.serialize()
|
||||
}
|
||||
|
||||
fn asm(source: &str) -> Vec<u8> {
|
||||
assemble(source).expect("assemble")
|
||||
}
|
||||
@@ -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());
|
||||
|
||||
+13
-6
@@ -1,8 +1,11 @@
|
||||
{"type":"meta","next_id":{"DSC":44,"AGD":46,"DEC":38,"PLN":148,"LSN":52,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0043","status":"open","ticket":"system-os-cartridge-switch-orchestrator","title":"SystemOS Cartridge Switch Orchestrator","created_at":"2026-07-03","updated_at":"2026-07-03","tags":["runtime","os","lifecycle","game","cartridge","architecture"],"agendas":[{"id":"AGD-0044","file":"AGD-0044-systemos-cartridge-switch-orchestrator.md","status":"open","created_at":"2026-07-03","updated_at":"2026-07-03"}],"decisions":[],"plans":[],"lessons":[]}
|
||||
{"type":"meta","next_id":{"DSC":51,"AGD":54,"DEC":45,"PLN":176,"LSN":59,"CLSN":1}}
|
||||
{"type":"discussion","id":"DSC-0050","status":"done","ticket":"headless-automation-host-hardening","title":"AGD-0052 Hardening — Headless Automation Host and Deterministic Runtime Control","created_at":"2026-09-22","updated_at":"2026-09-23","tags":["runtime","host","headless","automation","deterministic","concurrency","testing"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0058","file":"discussion/lessons/DSC-0050-headless-automation-host-hardening/LSN-0058-deterministic-observation-must-follow-the-active-producer.md","status":"done","created_at":"2026-09-23","updated_at":"2026-09-23"}]}
|
||||
{"type":"discussion","id":"DSC-0049","status":"done","ticket":"headless-automation-host-and-deterministic-runtime-control","title":"Headless Automation Host and Deterministic Runtime Control","created_at":"2026-09-22","updated_at":"2026-09-22","tags":["runtime","host","headless","automation","testing","ai","deterministic","input","framebuffer","debugger"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0057","file":"discussion/lessons/DSC-0049-headless-automation-host-and-deterministic-runtime-control/LSN-0057-deterministic-host-control-follows-logical-runtime-boundaries.md","status":"done","created_at":"2026-09-22","updated_at":"2026-09-22"}]}
|
||||
{"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":"in_progress","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-04","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":"accepted","created_at":"2026-06-05","updated_at":"2026-07-03"}],"decisions":[{"id":"DEC-0037","file":"DEC-0037-foreground-stack-and-game-pause-contract.md","status":"accepted","created_at":"2026-07-03","updated_at":"2026-07-03","ref_agenda":"AGD-0041"}],"plans":[{"id":"PLN-0136","file":"PLN-0136-route-desktop-home-key-outside-guest-input.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0137","file":"PLN-0137-implement-systemos-foreground-stack-state.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0138","file":"PLN-0138-specify-foreground-pause-and-home-contract.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0139","file":"PLN-0139-validate-game-home-shell-game-end-to-end.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0140","file":"PLN-0140-deliver-game-pause-resume-and-suspension.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0141","file":"PLN-0141-integrate-render-audio-and-input-pause-boundaries.md","status":"done","created_at":"2026-07-03","updated_at":"2026-07-03","ref_decisions":["DEC-0037"]},{"id":"PLN-0142","file":"PLN-0142-deliver-game-lifecycle-events-to-vm-runtime.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0143","file":"PLN-0143-guarantee-cooperative-pause-budget-tick-before-suspension.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0144","file":"PLN-0144-suspend-resident-game-when-shell-takes-foreground.md","status":"done","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0145","file":"PLN-0145-centralize-resident-game-resume-transition.md","status":"open","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0146","file":"PLN-0146-consolidate-lifecycle-process-lookup-helpers.md","status":"open","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]},{"id":"PLN-0147","file":"PLN-0147-move-native-shell-profile-update-into-hub.md","status":"open","created_at":"2026-07-04","updated_at":"2026-07-04","ref_decisions":["DEC-0037"]}],"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,11 +16,12 @@
|
||||
{"type":"discussion","id":"DSC-0022","status":"done","ticket":"tile-bank-vs-glyph-bank-domain-naming","title":"Glyph Bank Domain Naming Contract","created_at":"2026-04-09","updated_at":"2026-04-10","tags":["gfx","runtime","naming","domain-model"],"agendas":[],"decisions":[],"plans":[],"lessons":[{"id":"LSN-0025","file":"discussion/lessons/DSC-0022-glyph-bank-domain-naming/LSN-0025-rename-artifact-by-meaning-not-by-token.md","status":"done","created_at":"2026-04-10","updated_at":"2026-04-10"}]}
|
||||
{"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-0003","status":"open","ticket":"packed-cartridge-loader-pmc","title":"Agenda - Packed Cartridge Loader PMC","created_at":"2026-03-27","updated_at":"2026-09-22","tags":[],"agendas":[{"id":"AGD-0002","file":"AGD-0002-packed-cartridge-loader-pmc.md","status":"open","created_at":"2026-03-27","updated_at":"2026-09-22"}],"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-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-09-22","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-09-22"}],"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-09-22","tags":[],"agendas":[{"id":"AGD-0005","file":"AGD-0005-vm-owned-random-service.md","status":"open","created_at":"2026-03-27","updated_at":"2026-09-22"}],"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":"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"}]}
|
||||
@@ -42,3 +46,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-09-22","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-09-22"}],"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"}]}
|
||||
|
||||
+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.
|
||||
+125
@@ -0,0 +1,125 @@
|
||||
---
|
||||
id: LSN-0057
|
||||
ticket: headless-automation-host-and-deterministic-runtime-control
|
||||
title: Deterministic Host Control Follows Logical Runtime Boundaries
|
||||
created: 2026-09-22
|
||||
tags: [runtime, host, headless, deterministic, testing, input, framebuffer, lifecycle]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Prometeu needed an automation host that could boot and control a real cartridge
|
||||
without a window, display surface, audio device, or refresh-rate delay. The
|
||||
runtime already had the necessary domain boundaries: normalized
|
||||
`InputSignals`, logical-frame execution, structured `CrashReport` values, and
|
||||
worker-published `OwnedRgba8888Frame` values. The missing piece was a host that
|
||||
composed those boundaries without inheriting desktop presentation concerns.
|
||||
|
||||
The implementation introduced the in-process `prometeu-host-headless` library
|
||||
under `DEC-0043`. It proved deterministic input, frame advancement, pixel
|
||||
capture, faults, audio discard, and reset behavior with directory cartridges
|
||||
assembled directly in Rust tests.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### Logical Frames, Not Host Ticks, Are the Automation Unit
|
||||
|
||||
**What:** `advance_frame` repeatedly ticks firmware until the VM closes one
|
||||
logical frame or reports a fault. It temporarily releases VM pause through the
|
||||
existing debug-step request and leaves the VM paused afterward.
|
||||
|
||||
**Why:** A firmware tick is an execution budget slice, not necessarily a guest
|
||||
frame. Exposing ticks would make automation sensitive to budget configuration
|
||||
and host speed. Waiting for `FrameSync`, end-of-ROM, or a fault gives callers a
|
||||
guest-visible boundary.
|
||||
|
||||
**Trade-offs:** One automation operation may execute multiple firmware ticks.
|
||||
The host must therefore drain audio after every tick and must distinguish
|
||||
instruction stepping from logical-frame advancement.
|
||||
|
||||
### Published Worker Frames Are the Pixel Oracle
|
||||
|
||||
**What:** Frame capture reads the `LatestRenderFrameStore` populated by the
|
||||
existing render worker and waits for a frame id newer than the one observed
|
||||
before advancement.
|
||||
|
||||
**Why:** Reading mutable hardware buffers would create a second observation
|
||||
path and could expose partially applied work. The published
|
||||
`OwnedRgba8888Frame` is already the runtime's canonical completed-frame
|
||||
boundary, as described by `LSN-0049`.
|
||||
|
||||
**Trade-offs:** Logical execution and frame publication finish on different
|
||||
threads, so capture must synchronize with publication. That wait is worker
|
||||
completion, not refresh pacing.
|
||||
|
||||
### Cold Reset Must Clear Lifecycle Ownership as Well as VM State
|
||||
|
||||
**What:** Entering `FirmwareState::Reset` terminates the resident game before
|
||||
clearing VM sessions and global runtime cartridge state.
|
||||
|
||||
**Why:** Clearing only the VM session registry leaves the foreground lifecycle
|
||||
stack pointing at the old resident task. The next boot then looks like a second
|
||||
resident game and fails with `ResidentGameAlreadyExists`. A cold boot boundary
|
||||
must clear both execution state and the ownership records that authorize it.
|
||||
|
||||
**Trade-offs:** Reset is destructive lifecycle replacement. It intentionally
|
||||
does not preserve the previous game as resumable state; Home suspend/resume is
|
||||
the separate contract for preservation.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
### Deterministic Frame Advancement
|
||||
|
||||
1. Record the current logical-frame index and latest published frame id.
|
||||
2. Unpause the active VM session and request one debug frame step.
|
||||
3. Tick firmware with the retained `InputSignals`.
|
||||
4. Clear pending audio commands after every tick.
|
||||
5. Continue until the logical-frame index advances or a structured fault is
|
||||
visible.
|
||||
6. Pause the VM again.
|
||||
7. Read the publication store until the worker publishes a different frame id.
|
||||
|
||||
This keeps the oracle independent of wall-clock refresh timing while exercising
|
||||
the same firmware, VM, render worker, input, and audio paths as a real host.
|
||||
|
||||
### Repeatability Oracle
|
||||
|
||||
Compare only stable runtime outputs:
|
||||
|
||||
- logical-frame index;
|
||||
- published RGBA8888 pixels and frame identity progression;
|
||||
- debugger-shaped state (`pc`, stack top, frame index, and app id);
|
||||
- structured fault data.
|
||||
|
||||
Do not compare host CPU time, `Instant` timestamps, or certification budgets.
|
||||
Those values characterize execution conditions, not deterministic guest state.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- One firmware tick is not guaranteed to complete one guest frame.
|
||||
- Instruction `step` and logical-frame advancement have different contracts.
|
||||
- Capturing the hardware front buffer bypasses the canonical worker publication
|
||||
boundary.
|
||||
- Sleeping for a display period makes a headless host inherit presentation
|
||||
pacing and turns 300-frame tests into multi-second runs.
|
||||
- Clearing VM sessions without clearing resident-game lifecycle ownership does
|
||||
not produce a cold reset.
|
||||
- Opening or emulating an audio device is unnecessary when the required sink
|
||||
semantics are simply to consume and discard queued commands.
|
||||
|
||||
## References
|
||||
|
||||
- Decision: `DEC-0043` (Headless Host and Deterministic Frame Control)
|
||||
- Related lesson: `LSN-0049` (Render Workers Publish Frames, Hosts Present Them)
|
||||
- Related lesson: `LSN-0053` (Game Switching Is Lifecycle Replacement, Not Loader Work)
|
||||
- Audio contract: `docs/specs/runtime/05-audio-peripheral.md`
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Automation should advance guest-defined logical boundaries, not host loop
|
||||
iterations.
|
||||
- Deterministic input is a retained normalized value supplied to every tick.
|
||||
- The render worker's publication store is the single trustworthy pixel oracle.
|
||||
- Headless execution can reuse production runtime paths without linking native
|
||||
presentation or audio-device libraries.
|
||||
- A cold reset must clear lifecycle ownership and execution state together.
|
||||
+134
@@ -0,0 +1,134 @@
|
||||
---
|
||||
id: LSN-0058
|
||||
ticket: headless-automation-host-hardening
|
||||
title: Deterministic Observation Must Follow the Active Producer
|
||||
created: 2026-09-23
|
||||
tags: [runtime, host, headless, deterministic, rendering, testing, debugger]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The first headless automation host appeared to synchronize frame capture with a
|
||||
render worker: it started a worker, remembered the latest published frame id,
|
||||
and spun for a bounded number of iterations after logical execution. Source
|
||||
revalidation showed that this story did not match the running system. A Game
|
||||
cartridge executes inside an active `VmSession`, and that session selected the
|
||||
existing `LocalSynchronous` render consumer. The worker started on the global
|
||||
fallback runtime never consumed the active session's submissions.
|
||||
|
||||
The visible frame was already published synchronously through the normal
|
||||
platform sink. The spin was therefore redundant in successful runs and would
|
||||
still have been incorrect for a future asynchronous path because it waited for
|
||||
"any different frame" rather than the specific frame requested by automation.
|
||||
|
||||
## Key Decisions
|
||||
|
||||
### The Observation Contract Follows the Active Execution Owner
|
||||
|
||||
**What:** The headless host intentionally uses the active session's local
|
||||
synchronous consumer and removes the unused global worker and bounded spin.
|
||||
|
||||
**Why:** Synchronization must be defined against the component that actually
|
||||
produces the observed value. Waiting on an unrelated worker creates accidental
|
||||
success and makes the architecture harder to reason about.
|
||||
|
||||
**Trade-offs:** The deterministic headless host does not exercise worker
|
||||
concurrency on every cartridge run. Worker equivalence remains a separate
|
||||
runtime conformance concern rather than part of each game's oracle.
|
||||
|
||||
### Completion Carries Exact Identity
|
||||
|
||||
**What:** Successful frame advancement retains the explicit
|
||||
`{logical_frame_index, FrameId}` pair and capture validates that exact published
|
||||
frame before cloning its `OwnedRgba8888Frame`.
|
||||
|
||||
**Why:** A generation change only proves that something was published. It does
|
||||
not prove which logical operation produced it. Exact identity makes stale or
|
||||
mis-associated observations detectable.
|
||||
|
||||
**Trade-offs:** Logical frame numbers and render frame ids remain separate
|
||||
domains. Callers compare the explicit pair rather than assuming equality or a
|
||||
fixed offset.
|
||||
|
||||
### A Tick Slice Must Be Smaller Than the Logical Budget
|
||||
|
||||
**What:** The runtime's per-firmware-tick execution slice is smaller than the
|
||||
total logical-frame cycle budget. Headless advancement loops across slices
|
||||
until the frame closes or a terminal outcome occurs.
|
||||
|
||||
**Why:** When both limits were equal, `BudgetExhausted` left zero remaining
|
||||
logical budget, so another tick could not make progress. The documented
|
||||
multi-tick contract existed only nominally. Separating the limits makes a tick
|
||||
an implementation slice and keeps a logical frame as the automation unit.
|
||||
|
||||
**Trade-offs:** A computation-heavy logical frame can span several firmware
|
||||
ticks. This is observable through deterministic tick counters but does not
|
||||
change guest frame semantics.
|
||||
|
||||
### Debug Instruction Step Must Prime the Entry Call
|
||||
|
||||
**What:** The shared debugger instruction-step primitive prepares the VM entry
|
||||
call when the call stack is empty before executing one instruction.
|
||||
|
||||
**Why:** Direct boot intentionally stops before the first game instruction. A
|
||||
debug step at that point previously encountered the coroutine safepoint and
|
||||
reported `FrameSync` as an unexpected panic instead of executing the first
|
||||
instruction.
|
||||
|
||||
**Trade-offs:** Entry preparation remains shared runtime behavior. No
|
||||
headless-specific VM branch is introduced.
|
||||
|
||||
## Patterns and Algorithms
|
||||
|
||||
### Deterministic Frame Advance
|
||||
|
||||
1. Record the current logical-frame index and latest canonical frame id.
|
||||
2. Release pause and request the same one-frame stop used by debugger control.
|
||||
3. Tick firmware while feeding the retained normalized `InputSignals`.
|
||||
4. Continue through internal cycle-slice exhaustion.
|
||||
5. Stop on exactly one logical-frame increment, structured fault, lifecycle
|
||||
termination, or a typed host safety-limit error.
|
||||
6. Clear the frame-step request and finish paused.
|
||||
7. On success, require a new canonical frame and retain its exact identity with
|
||||
the completed logical index.
|
||||
|
||||
### Deterministic Oracle Boundary
|
||||
|
||||
Include observations that describe simulated execution: logical frame and
|
||||
frame identity, canonical pixels and layout, guest-visible state, structured
|
||||
status/faults, and deterministic machine counters.
|
||||
|
||||
Exclude observations of the host running the simulation: wall time, CPU time,
|
||||
thread scheduling, presentation cadence, worker timing, and host-only
|
||||
identities.
|
||||
|
||||
## Pitfalls
|
||||
|
||||
- A worker created by a host may not own the active session being automated.
|
||||
- Bounded spinning is neither an acknowledgement nor an identity check.
|
||||
- "Latest changed" is weaker than "the requested frame was published."
|
||||
- Equal slice and logical budgets can make multi-tick continuation impossible
|
||||
even when the control loop appears to support it.
|
||||
- A debug step from a pristine boot boundary must establish the same entry-call
|
||||
precondition as normal execution.
|
||||
- Human-readable fault summaries are useful diagnostics but are not a stable
|
||||
automation interface; retain structured `CrashReport` values.
|
||||
|
||||
## References
|
||||
|
||||
- Decision: `DEC-0044` (Deterministic Headless Automation Host Contract)
|
||||
- Prior lesson: `LSN-0057` (Deterministic Host Control Follows Logical Runtime Boundaries)
|
||||
- Render worker lesson: `LSN-0049` (Render Workers Publish Frames, Hosts Present Them)
|
||||
- Graphics contract: `docs/specs/runtime/04-gfx-peripheral.md`
|
||||
- Debug contract: `docs/specs/runtime/10-debug-inspection-and-profiling.md`
|
||||
- Portability and headless contract: `docs/specs/runtime/11-portability-and-cross-platform-execution.md`
|
||||
|
||||
## Takeaways
|
||||
|
||||
- Revalidate ownership and data flow from source before hardening a wait.
|
||||
- Deterministic observation requires exact completion identity, not timing luck.
|
||||
- Keep logical-frame control above internal execution slices.
|
||||
- Use one production runtime path for interactive debugging and headless
|
||||
automation; vary host transport and pacing, not machine semantics.
|
||||
- Test infrastructure boundaries with counters and structured outcomes instead
|
||||
of sleeps or log parsing.
|
||||
@@ -83,4 +83,36 @@ Pode virar PR quando houver definição escrita de:
|
||||
- arquivos obrigatórios;
|
||||
- erros canônicos;
|
||||
- invariantes de segurança;
|
||||
- estratégia de testes de compatibilidade entre diretório e pacote.
|
||||
- estratégia de testes de compatibilidade entre diretório e pacote;
|
||||
- equivalência observável entre diretório e `.pmc` para qualquer host que use `CartridgeLoader`, incluindo o host desktop e o host headless de `AGD-0052`.
|
||||
|
||||
## Revalidação — 2026-09-22
|
||||
|
||||
Revalidada contra o código atual e contra `AGD-0052` / `DSC-0049` (Headless Automation Host and Deterministic Runtime Control). A agenda permanece aberta.
|
||||
|
||||
### O que permanece
|
||||
|
||||
`PackedCartridgeLoader::load` ainda retorna `CartridgeError::InvalidFormat` sem ler o arquivo. O dispatcher continua aceitando a extensão `.pmc` e delegando para esse stub. O loader de diretório é o caminho real: `manifest.json`, `program.pbx` e `assets.pa` quando a capability de asset exige. Boot direto (`BootTarget::Cartridge`) e o host desktop usam esse mesmo `CartridgeLoader`.
|
||||
|
||||
O problema original segue válido: a plataforma anuncia dois formatos e só o diretório funciona.
|
||||
|
||||
### Efeito da direção headless
|
||||
|
||||
`AGD-0052` coloca o host headless como consumidor novo do loader, e deixa o formato `.pmc` fora do primeiro ciclo. O primeiro boot automatizado usa cartucho de diretório, o mesmo artefato que o host desktop já carrega.
|
||||
|
||||
Consequências para esta agenda:
|
||||
|
||||
- headless, CI e agente não definem o container;
|
||||
- quando `.pmc` existir, diretório e pacote precisam materializar o mesmo cartucho lógico, para o determinismo não depender da origem dos bytes;
|
||||
- a ordem física do container continua impedida de alterar o resultado, como o item de segurança e determinismo já pedia;
|
||||
- esta agenda não absorve captura de framebuffer, replay ou protocolo de automação.
|
||||
|
||||
### O que não mudou no critério
|
||||
|
||||
Formato, arquivos obrigatórios, erros canônicos, invariantes de segurança e testes de equivalência continuam sendo o fechamento. O critério de saída ganhou só a exigência de que essa equivalência valha para todo host do `CartridgeLoader`.
|
||||
|
||||
### Perguntas que continuam abertas
|
||||
|
||||
- [ ] O `.pmc` é zip, tar, formato próprio ou envelope com header e blobs?
|
||||
- [ ] Quais entradas são obrigatórias além das que o loader de diretório já exige?
|
||||
- [ ] Qual matriz de erro determinística substitui o `InvalidFormat` genérico do stub?
|
||||
|
||||
+45
-26
@@ -13,53 +13,72 @@ tags: []
|
||||
|
||||
## Problema
|
||||
|
||||
O dominio `system` e pequeno, mas mistura consulta simples com superficie de controle de fluxo.
|
||||
O domínio `system` exposto à userland ficou pequeno, e a política de retorno dele ainda não está escrita.
|
||||
|
||||
Hoje:
|
||||
Estado em 2026-09-22:
|
||||
|
||||
- `SystemHasCart` responde diretamente;
|
||||
- `SystemRunCart` ainda nao tem efeito real;
|
||||
- a agenda `009` resolve semantica funcional, mas nao fecha por si so a politica de fault do dominio.
|
||||
- a superfície gerada é só `system.has_cart` (`Syscall::SystemHasCart`), com 1 retorno e capability `SYSTEM`;
|
||||
- o dispatch devolve `true` fixo, sem consultar cartucho e sem `status`;
|
||||
- `system.run_cart` saiu da ABI de userland. Launch de cartucho é ação de SystemOS/firmware/host (`LSN-0051`, `DSC-0004`);
|
||||
- fault de execução da VM já tem forma estruturada em `CrashReport` (`VmTrap`, `VmPanic`, `VmInit`), observada pelo host e pelo debugger.
|
||||
|
||||
O texto de 2026-03-27 tratava `SystemRunCart` como operação ainda sem efeito e apontava a agenda `009` e `virtual_machine_runtime/dispatch.rs`. Esses dois pontos ficaram obsoletos. A política de fault do que permanece no domínio `system` continua aberta.
|
||||
|
||||
## Dor
|
||||
|
||||
- sem uma agenda propria, `system` pode herdar fault semantics por acidente;
|
||||
- `run_cart` pode acabar consolidando `Panic` ou `Trap` onde deveria existir retorno operacional;
|
||||
- a fronteira entre falha do app, falha do firmware e falha do runtime fica opaca.
|
||||
- `has_cart` pode permanecer um bool fixo e mascarar ausência, cartucho inválido ou consulta fora de autoridade;
|
||||
- uma futura operação de `system` pode herdar `Trap` ou `Panic` onde o contrato transversal pede `status`;
|
||||
- automação headless (`AGD-0052`) precisa observar fault estruturado sem que esta agenda redesenhe `CrashReport` nem invente syscall de controle para CI ou agente.
|
||||
|
||||
## Hotspots Atuais
|
||||
|
||||
- [dispatch.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs#L114)
|
||||
- [system.rs](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/crates/console/prometeu-hal/src/syscalls/domains/system.rs#L4)
|
||||
- [009-system-run-cart.md](/Users/niltonconstantino/personal/workspace.personal/intrepid/prometeu/runtime/docs/runtime/agendas/009-system-run-cart.md)
|
||||
- `crates/console/prometeu-hal/src/syscalls/domains/system.rs`
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/dispatch.rs` (`SystemHasCart` retorna `true`)
|
||||
- `crates/console/prometeu-system/src/crash_report.rs`
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `discussion/lessons/DSC-0004-system-run-cart/LSN-0051-launch-authority-belongs-to-systemos.md`
|
||||
|
||||
## Alvo da Discussao
|
||||
|
||||
Fechar a politica de fault e retorno do dominio `system`.
|
||||
Fechar a política de fault e retorno do domínio `system` que ainda é visível à userland, e separar essa política da observação de fault de VM feita pelo host.
|
||||
|
||||
## O Que Precisa Ser Definido
|
||||
|
||||
1. Queries simples.
|
||||
Decidir a politica de fault para consultas como `has_cart`.
|
||||
Decidir a política de `has_cart`: bool atual, `status` mais payload, ou outra forma compatível com `16a`. Incluir o que a consulta realmente observa.
|
||||
|
||||
2. `run_cart`.
|
||||
Decidir como falhas operacionais de transicao devem ser expostas:
|
||||
- `status`;
|
||||
- `Trap`;
|
||||
- `Panic`.
|
||||
2. Operações que não voltam para a userland.
|
||||
`run_cart` permanece fora da ABI de convidado. Falha de boot direto continua no caminho de host/firmware (`CartridgeError`, `CrashReport::VmInit`, transição de firmware), não como syscall de app.
|
||||
|
||||
3. Relacao com firmware.
|
||||
Delimitar quando a falha pertence ao app, ao firmware ou ao runtime.
|
||||
3. Relação com firmware e com o host.
|
||||
Delimitar falha de app, falha de firmware e falha de runtime. `CrashReport` é a observação estruturada de Trap/Panic/init. `summary()` e log são apresentação, não o contrato.
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../specs/16a-syscall-policies.md`
|
||||
- `009-system-run-cart.md`
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `LSN-0051` / `DSC-0004`
|
||||
- `AGD-0052` / `DSC-0049`, apenas como consumidor da observação estruturada
|
||||
|
||||
## Critério de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
Pode virar decision quando houver definição escrita sobre:
|
||||
|
||||
- matriz de `status`/`Trap`/`Panic` para `system`;
|
||||
- politica de retorno/falha de `run_cart`;
|
||||
- relacao com firmware e crash surface.
|
||||
- matriz de `status` / `Trap` / `Panic` para as operações userland que o domínio `system` mantém, começando por `has_cart`;
|
||||
- confirmação de que launch de cartucho permanece fora da ABI de convidado;
|
||||
- fronteira entre retorno operacional de syscall, erro de loader/boot e `CrashReport`.
|
||||
|
||||
## Revalidação — 2026-09-22
|
||||
|
||||
Revalidada contra o código atual e contra `AGD-0052`. A agenda permanece aberta. O alvo encolheu: ela não reabre `run_cart`.
|
||||
|
||||
### O que a direção headless muda
|
||||
|
||||
`AGD-0052` exige que automação distinga execução em curso, pause, término, `Trap` e `Panic` lendo dados estruturados. Esse requisito observa `CrashReport` e o estado da VM. Ele não altera a semântica normativa de fault de outros domínios e não cria syscall `system` para controle headless.
|
||||
|
||||
Esta agenda continua dona da matriz de retorno de `system`. A agenda headless continua dona de como o host expõe o fault que já existe.
|
||||
|
||||
### Perguntas que continuam abertas
|
||||
|
||||
- [ ] `has_cart` passa a ter `status` e um significado real de presença de cartucho, ou o bool atual é o contrato e o stub `true` é o bug a corrigir em outra discussão?
|
||||
- [ ] Alguma falha de boot direto precisa ser visível ao convidado, ou toda falha de launch permanece em host, firmware e `CrashReport`?
|
||||
- [ ] Quais campos de `CrashReport` são o contrato observável (`kind`, `pc`, `trap.code`) e quais são só texto de log?
|
||||
|
||||
@@ -50,30 +50,50 @@ Fechar o perfil minimo de random VM-owned em cima do core definido na decisao `0
|
||||
|
||||
## Open Questions de Arquitetura
|
||||
|
||||
1. v1 aceita apenas modo deterministico por seed ou tambem entropy host?
|
||||
1. O caminho determinístico aceita só seed explícita. Entropia de host, se um dia existir, é modo separado e fica fora da timeline automatizada?
|
||||
2. `next` retorna apenas `int` ou precisamos variantes (`u32`, `float`) no mesmo ciclo?
|
||||
3. precisamos de clone/split de gerador no MVP?
|
||||
4. destruicao explicita deve ser obrigatoria para certificacao/custo ou opcional?
|
||||
5. O primeiro oráculo de `AGD-0052` pode provar determinismo com cartucho que não chama random, e qualquer cartucho que chame random espera o fechamento desta agenda?
|
||||
|
||||
## Dependencias
|
||||
|
||||
- `../decisions/006-vm-owned-stateful-core-contract.md`
|
||||
- `../virtual-machine/ISA_CORE.md`
|
||||
- `../specs/16-host-abi-and-syscalls.md`
|
||||
- `../specs/16a-syscall-policies.md`
|
||||
- contexto histórico, já aposentado como decisão viva: `discussion/lessons/DSC-0001-runtime-learn-legacy-import/LSN-0008-historical-vm-core-and-assets.md` cita `006-vm-owned-stateful-core-contract.md`
|
||||
- `docs/vm-arch/ISA_CORE.md`
|
||||
- `docs/specs/runtime/16-host-abi-and-syscalls.md`
|
||||
- `docs/specs/runtime/16a-syscall-policies.md`
|
||||
- `AGD-0052` / `DSC-0049`, como consumidor do contrato determinístico
|
||||
|
||||
Não há arquivo vivo em `discussion/workflow/decisions/` para a decisão `006`. Esta agenda não trata esse texto como contrato atual.
|
||||
|
||||
## Fora de Escopo
|
||||
|
||||
- entropy nao deterministica como contrato base;
|
||||
- PRNGs multiplos no mesmo ciclo de fechamento;
|
||||
- APIs de colecoes stateful;
|
||||
- window/app model.
|
||||
- entropia não determinística como contrato base;
|
||||
- PRNGs múltiplos no mesmo ciclo de fechamento;
|
||||
- APIs de coleções stateful;
|
||||
- window/app model;
|
||||
- formato persistente de replay. Esta agenda define reprodução em memória: seed explícita mais sequência de `next`. Arquivo, versão e timeline de input ficam para a agenda de replay citada por `AGD-0052`.
|
||||
|
||||
## Criterio de Saida Desta Agenda
|
||||
|
||||
Pode virar PR quando houver decisao escrita sobre:
|
||||
Pode virar decision quando houver definição escrita sobre:
|
||||
|
||||
- surface minima de random VM-owned;
|
||||
- contrato de determinismo/replay;
|
||||
- surface mínima de random VM-owned;
|
||||
- contrato de determinismo: seed explícita, ausência de entropia implícita de host, reprodução da sequência;
|
||||
- fault/status de random;
|
||||
- IDs/versionamento e validacoes de verifier para as operacoes do dominio.
|
||||
- IDs/versionamento e validações de verifier para as operações do domínio;
|
||||
- o que um host automatizado precisa fixar (seeds iniciais) para que duas execuções coincidam.
|
||||
|
||||
## Revalidação — 2026-09-22
|
||||
|
||||
Revalidada contra o código atual e contra `AGD-0052`. A agenda permanece aberta. Não existe serviço de random na VM. O scheduler declara ausência de randomness. `prometeu-test-support` oferece `StdRng` semeado para testes Rust; isso não é random de convidado.
|
||||
|
||||
### Efeito da direção headless
|
||||
|
||||
`AGD-0052` diz que random VM-owned usado em execução automatizada obedece ao contrato desta agenda, e que entropia implícita do host não entra no caminho determinístico. Isso reforça a pergunta 1 na direção de seed explícita como único modo determinístico.
|
||||
|
||||
O primeiro teste end-to-end headless pode usar um cartucho que não chama random. Esse teste prova input, frame e fault. Ele não prova random. Cartucho cujo resultado depende de random só serve como oráculo depois que esta agenda fechar seeds, sequência e faults.
|
||||
|
||||
Relógio de parede em telemetria (`host_cpu_time_us`, timestamp de certificação) não é fonte de random e não entra neste contrato.
|
||||
|
||||
Replay em arquivo continua fora daqui e fora do primeiro ciclo headless. O que esta agenda precisa deixar pronto é a reprodução em memória da sequência a partir das seeds.
|
||||
|
||||
@@ -1,178 +0,0 @@
|
||||
---
|
||||
id: AGD-0041
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Foreground Stack, Game Pause, and VM-Backed Shell Coexistence
|
||||
status: accepted
|
||||
created: 2026-06-05
|
||||
resolved: 2026-07-03
|
||||
decision: DEC-0037
|
||||
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
|
||||
|
||||
- [x] Qual e o nome canonico dos estados de Game fora do foreground: `Paused`, `Suspended`, ambos, ou outro?
|
||||
- [x] Ao apertar Home, o Game deve receber um evento/interrupt/trap de pausa antes de parar de executar?
|
||||
- [x] O Hub e um Shell especial sempre presente ou uma task Shell comum?
|
||||
- [x] Um app Shell VM-backed pode substituir o Hub no foreground ou o Hub permanece como owner raiz?
|
||||
- [x] Quando o Shell VM-backed fecha, o retorno vai sempre para Hub ou pode voltar diretamente ao Game?
|
||||
- [x] O input do Game e drenado/limpo ao pausar e ao retomar?
|
||||
- [x] Audio do Game pausa junto com a VM ou tem politica propria?
|
||||
- [x] Existe limite de memoria/residencia para manter Game pausado enquanto Shell app roda?
|
||||
- [x] O retorno ao Game exige novo frame antes de trocar a superficie, ou a tela pode manter Hub/Shell ate a primeira submission valida?
|
||||
- [x] Quais eventos de lifecycle precisam ser visiveis para firmware, OS, VM e host?
|
||||
|
||||
## Resolucao
|
||||
|
||||
Fica aceito o modelo `Game -> Home/Shell -> mesmo Game` com foreground unico e
|
||||
residencia limitada:
|
||||
|
||||
- somente um Game pode estar residente por vez;
|
||||
- somente um Shell pode ser foreground por vez;
|
||||
- Hub e o Shell root/especial e permanece owner raiz/back-stack;
|
||||
- um Shell VM-backed pode assumir o foreground visual, mas segue lifecycle de
|
||||
Shell e nao herda politica de game loop;
|
||||
- fechar um Shell VM-backed retorna ao Hub em v1;
|
||||
- background execution real fica fora de escopo;
|
||||
- no host desktop, `Esc` e a tecla principal para solicitar Home/SystemOS e a
|
||||
tecla fisica `Home` pode existir como alias;
|
||||
- a acao Home/SystemOS e interceptada pelo host/SystemOS e nao entra no pad
|
||||
logico visivel ao Game;
|
||||
- `Paused` e o estado/evento cooperativo visivel ao Game;
|
||||
- `Suspended` e o estado operacional imposto pelo OS/scheduler;
|
||||
- ao sair do foreground, o OS notifica o Game para pausar e concede um budget
|
||||
curto de reacao;
|
||||
- se o Game nao reagir ao pause dentro do budget, o OS suspende a VM mesmo
|
||||
assim;
|
||||
- ao retornar, o OS reativa a VM, notifica o Game para resume/foreground
|
||||
restore e permite que o Game sincronize antes de voltar ao gameplay;
|
||||
- input pendente do Game e drenado/limpo nas fronteiras de pause/resume;
|
||||
- audio do Game pausa junto com a VM em v1;
|
||||
- retorno ao Game deve manter Hub/Shell visivel ate a primeira render submission
|
||||
valida do Game retomado;
|
||||
- render ownership muda junto com o foreground owner e invalida submissions
|
||||
antigas via epoch/generation;
|
||||
- firmware observa transicoes macro; OS observa lifecycle completo; VM observa
|
||||
pause/resume; host observa owner/render epoch e estado de apresentacao.
|
||||
|
||||
## 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.
|
||||
- 2026-07-03: Direcao provisoria aceita para as perguntas 2-10:
|
||||
Game deve receber evento de pausa com budget curto antes da suspensao; Hub e
|
||||
Shell root/especial; Shell VM-backed pode assumir foreground visual, mas Hub
|
||||
permanece como owner raiz/back-stack; fechar Shell VM-backed retorna ao Hub em
|
||||
v1; input do Game deve ser drenado/limpo em pause/resume; audio do Game pausa
|
||||
junto com VM em v1; apenas um Game pausado residente e permitido; retorno ao
|
||||
Game deve manter Hub/Shell visivel ate a primeira submission valida; firmware
|
||||
ve transicoes macro, OS ve lifecycle completo, VM ve pause/resume, host ve
|
||||
owner/render epoch e estado de apresentacao.
|
||||
- 2026-07-03: Pergunta 1 permanece aberta para esclarecer se `Paused` e
|
||||
`Suspended` sao estados distintos, nomes para camadas diferentes, ou se v1
|
||||
deve expor somente um deles.
|
||||
- 2026-07-03: Direcao proposta para pergunta 1: `Paused` e o estado/evento
|
||||
cooperativo visivel ao Game; `Suspended` e o estado operacional imposto pelo
|
||||
OS. Ao sair do foreground, o OS notifica o Game para pausar e concede um
|
||||
budget curto de reacao; se o Game nao reagir, o OS suspende a VM mesmo assim.
|
||||
Ao retornar, o OS notifica o Game antes de recoloca-lo no foreground visual,
|
||||
permitindo sincronizacao/revalidacao. O Game nao controla a suspensao, mas
|
||||
pode observar `pause`/`resume` para ajustar seu estado interno.
|
||||
@@ -1,145 +0,0 @@
|
||||
---
|
||||
id: AGD-0044
|
||||
ticket: system-os-cartridge-switch-orchestrator
|
||||
title: SystemOS Cartridge Switch Orchestrator
|
||||
status: open
|
||||
created: 2026-07-03
|
||||
resolved:
|
||||
decision:
|
||||
tags: [runtime, os, lifecycle, game, cartridge, architecture]
|
||||
---
|
||||
|
||||
## Contexto
|
||||
|
||||
A `AGD-0041` cobre o caso `Game -> Home/Shell -> mesmo Game`: o usuario sai do
|
||||
foreground do jogo, o SO assume a tela, Shell/Hub pode rodar, e depois o mesmo
|
||||
Game e retomado.
|
||||
|
||||
Existe um segundo caso, diferente, que nao deve ser escondido dentro da
|
||||
`AGD-0041`: `Game A -> Home -> Game B`.
|
||||
|
||||
Nesse fluxo, o usuario esta com um Game rodando, aperta Home, volta para o SO e
|
||||
pede para iniciar outro jogo. O SystemOS nao deve simplesmente chamar um loader
|
||||
por cima do estado atual. Ele precisa orquestrar a substituicao do app corrente:
|
||||
fechar ou descartar o Game residente, limpar estado cartridge-scoped, resolver o
|
||||
novo alvo, carregar o proximo cartucho e entrar no novo estado de firmware.
|
||||
|
||||
Essa agenda tambem se relaciona com a `AGD-0003 / system-run-cart`: `run_cart`,
|
||||
se existir, nao e userland e nao e o orquestrador. O carregador de cartucho e
|
||||
apenas uma etapa dentro de uma transicao comandada pelo SystemOS.
|
||||
|
||||
## Problema
|
||||
|
||||
Sem um orquestrador explicito de troca de cartucho no SystemOS, a plataforma
|
||||
pode cair em estados incoerentes:
|
||||
|
||||
- carregar um novo Game sem fechar corretamente o Game anterior;
|
||||
- reaproveitar estado VM, assets, input, audio, render ou telemetria do cartucho
|
||||
anterior;
|
||||
- misturar boot direto por linha de comando com troca de app sob o SO;
|
||||
- deixar o loader decidir lifecycle, quando ele deveria apenas materializar o
|
||||
cartucho alvo;
|
||||
- tentar implementar `Home -> outro Game` antes de existir o contrato de
|
||||
foreground/pausa definido pela `AGD-0041`.
|
||||
|
||||
## Pontos Criticos
|
||||
|
||||
- Esta agenda deve ser executada depois da `AGD-0041`.
|
||||
- `Game -> Home -> mesmo Game` fica fora desta agenda.
|
||||
- O SystemOS deve ser a autoridade da troca entre cartuchos sob o SO.
|
||||
- O loader nao deve possuir politica de fechamento, pausa, foreground ou
|
||||
cleanup.
|
||||
- Boot direto por CLI/debug continua sendo caminho separado e mais simples.
|
||||
- A troca para outro Game deve tratar falha de load sem deixar o sistema em
|
||||
estado parcialmente substituido.
|
||||
- `.pmc`, catalogo completo e UX final de launcher continuam fora de escopo,
|
||||
salvo se forem necessarios para definir o contrato minimo.
|
||||
|
||||
## Opcoes
|
||||
|
||||
### Opcao A - Adiar tudo para depois da AGD-0041
|
||||
|
||||
- **Abordagem:** manter esta agenda como registro de escopo futuro; primeiro
|
||||
fechar e implementar o contrato `Game -> Home -> mesmo Game`.
|
||||
- **Pro:** evita misturar pausa/resume com substituicao de cartucho; reduz risco
|
||||
de reabrir arquitetura durante a `AGD-0041`.
|
||||
- **Contra:** a plataforma continua sem troca `Home -> outro Game` ate uma etapa
|
||||
posterior.
|
||||
- **Manutenibilidade:** alta, porque cada agenda fecha um eixo de lifecycle.
|
||||
|
||||
### Opcao B - Definir agora o contrato conceitual, implementar depois
|
||||
|
||||
- **Abordagem:** fechar uma decisao curta ja dizendo que o orquestrador pertence
|
||||
ao SystemOS, que `run_cart` nao e userland, e que a execucao depende da
|
||||
`AGD-0041`; o plano de codigo fica para depois.
|
||||
- **Pro:** reduz ambiguidade enquanto trabalhamos na `AGD-0041`.
|
||||
- **Contra:** pode produzir uma decisao com pouca evidencia operacional antes
|
||||
do contrato de foreground estar fechado.
|
||||
- **Manutenibilidade:** boa se a decisao for claramente marcada como dependente
|
||||
da `AGD-0041`.
|
||||
|
||||
### Opcao C - Implementar o orquestrador completo agora
|
||||
|
||||
- **Abordagem:** tentar resolver `Game A -> Home -> Game B` antes ou junto da
|
||||
`AGD-0041`.
|
||||
- **Pro:** ataca o fluxo final diretamente.
|
||||
- **Contra:** mistura pausa/resume, fechamento, cleanup, resolucao de alvo e
|
||||
falha de load em uma unica frente; alto risco de contrato instavel.
|
||||
- **Manutenibilidade:** baixa para v1, porque a troca completa depende do
|
||||
contrato de foreground ainda aberto.
|
||||
|
||||
## Sugestao / Recomendacao
|
||||
|
||||
Recomendo a Opcao A agora, com esta agenda aberta como marcador explicito de
|
||||
escopo futuro.
|
||||
|
||||
A ordem preferida passa a ser:
|
||||
|
||||
1. fechar a `AGD-0041` para definir foreground, pausa/suspensao, Shell no
|
||||
foreground e retorno ao mesmo Game;
|
||||
2. voltar para esta agenda e decidir o contrato do orquestrador de troca de
|
||||
cartucho no SystemOS;
|
||||
3. so entao planejar a execucao de `Game A -> Home -> Game B`.
|
||||
|
||||
Se durante a `AGD-0041` aparecer uma decisao que exige antecipar parte do
|
||||
orquestrador, esta agenda deve ser reaberta/atualizada com a dependencia
|
||||
concreta em vez de esconder a troca de cartucho dentro da agenda de foreground.
|
||||
|
||||
## Perguntas em Aberto
|
||||
|
||||
- [ ] Depois da `AGD-0041`, qual estado representa um Game que sera descartado
|
||||
em vez de retomado?
|
||||
- [ ] O fechamento do Game atual e observavel para o firmware/game, ou e uma
|
||||
destruicao interna do SystemOS?
|
||||
- [ ] Quais estados cartridge-scoped devem ser limpos antes do novo load: VM,
|
||||
assets, FS handles, input, audio, render ownership, telemetry, logs?
|
||||
- [ ] Se o novo cartucho falha ao carregar, o sistema volta ao Home, mostra uma
|
||||
tela de erro, ou tenta preservar o Game anterior?
|
||||
- [ ] Como a resolucao do novo alvo e representada sem depender de catalogo
|
||||
completo ou `.pmc`?
|
||||
- [ ] Qual evidencia minima prova `Game A -> Home -> Game B` sem depender de UX
|
||||
final de launcher?
|
||||
|
||||
## Criterio para Encerrar
|
||||
|
||||
A agenda pode virar decisao quando:
|
||||
|
||||
- a `AGD-0041` tiver fechado o contrato de foreground/pausa/resume;
|
||||
- estiver claro que o orquestrador pertence ao SystemOS;
|
||||
- `run_cart`/loader estiver limitado a etapa interna, nao userland;
|
||||
- existir regra para fechar/descartar o Game atual;
|
||||
- existir contrato de limpeza de estado cartridge-scoped;
|
||||
- existir politica para falha de carregamento do novo Game;
|
||||
- houver criterio de teste minimo para `Game A -> Home -> Game B`.
|
||||
|
||||
## Discussao
|
||||
|
||||
- 2026-07-03: Agenda criada a partir da separacao entre `AGD-0041`
|
||||
(`Game -> Home -> mesmo Game`) e `AGD-0003` (`run_cart`/loader nao userland).
|
||||
O novo escopo cobre a troca posterior `Game A -> Home -> Game B`, com
|
||||
orquestracao pelo SystemOS depois que o contrato de foreground estiver
|
||||
fechado.
|
||||
|
||||
## Resolution
|
||||
|
||||
Ainda em aberto.
|
||||
@@ -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,140 @@
|
||||
---
|
||||
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? Encaminhada para `AGD-0052` / `DSC-0049`: o host headless é o lugar dessa prova. Esta agenda continua dona da escolha de backend portátil, não do controle determinístico.
|
||||
- [ ] 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.
|
||||
|
||||
Atualizacao 2026-09-22: `AGD-0052` abre um terceiro host, headless, para teste, CI e controle determinístico em memória. Esse host não substitui o candidato portátil desta agenda e não escolhe SDL. A pergunta de validar input e pacing sem janela em CI passa a ser respondida lá. Extração de loop comum entre winit, SDL e headless continua esperando duplicação real.
|
||||
|
||||
## Resolution
|
||||
@@ -1,191 +0,0 @@
|
||||
---
|
||||
id: DEC-0037
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Foreground Stack and Game Pause Contract
|
||||
status: accepted
|
||||
created: 2026-07-03
|
||||
ref_agenda: AGD-0041
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Status
|
||||
|
||||
Accepted.
|
||||
|
||||
## Contexto
|
||||
|
||||
`AGD-0041` defines the minimum lifecycle contract for `Game -> Home/Shell ->
|
||||
same Game`.
|
||||
|
||||
The issue is not only rendering. The render worker needs a single valid visual
|
||||
owner, but SystemOS must decide which VMs may exist, which owner receives input,
|
||||
which owner may tick, what happens to a Game when Home takes foreground, and how
|
||||
a VM-backed Shell app coexists with a paused Game.
|
||||
|
||||
This decision builds on:
|
||||
|
||||
- `DSC-0031`: runtime mode separation between Game and System/Shell;
|
||||
- `DSC-0032`: SystemOS lifecycle/process/task authority;
|
||||
- `DSC-0035`: task-owned Shell windows and Shell liveness;
|
||||
- `DSC-0036`: Hub/Shell as a lifecycle proving surface;
|
||||
- `DSC-0040`: render ownership/epoch and stale submission invalidation.
|
||||
|
||||
## Decisao
|
||||
|
||||
PROMETEU MUST use a single-foreground-owner model for v1.
|
||||
|
||||
At most one Game MAY be resident at a time. At most one Shell app MAY be the
|
||||
foreground visual owner at a time.
|
||||
|
||||
The Hub MUST be treated as the root/special Shell owner for Home. A VM-backed
|
||||
Shell app MAY replace the Hub as the foreground visual owner, but the Hub
|
||||
remains the root/back-stack controller. In v1, closing a VM-backed Shell app
|
||||
MUST return to Hub/Home, not directly to the Game.
|
||||
|
||||
When the user requests Home while a Game is running, SystemOS MUST start a
|
||||
cooperative pause transition:
|
||||
|
||||
- the Game receives a pause lifecycle notification;
|
||||
- the Game is given a short bounded budget to react;
|
||||
- after that budget, SystemOS MAY suspend the Game VM even if the Game did not
|
||||
cooperate;
|
||||
- the Game remains resident but MUST NOT receive normal gameplay ticks, normal
|
||||
game input, or frame pacing while suspended;
|
||||
- the Shell/Hub foreground owner MAY execute according to Shell lifecycle rules.
|
||||
|
||||
`Paused` is the Game-visible lifecycle state/event. `Suspended` is the
|
||||
OS/scheduler operational state. A Game may observe pause/resume, but it MUST NOT
|
||||
control whether the OS suspends or resumes its VM.
|
||||
|
||||
When returning to the same Game, SystemOS MUST reactivate the Game VM and send a
|
||||
resume or foreground-restore lifecycle notification before restoring visual
|
||||
foreground. The Game MAY remain internally paused while it synchronizes. The
|
||||
system MUST keep Hub/Shell visible until the resumed Game produces a valid new
|
||||
render submission for the current ownership epoch.
|
||||
|
||||
Input pending for the Game MUST be drained or cleared across pause/resume
|
||||
boundaries. Game audio MUST pause with the Game VM in v1. Independent background
|
||||
audio policy is out of scope.
|
||||
|
||||
Render ownership MUST move with the foreground owner. Foreground transitions
|
||||
MUST invalidate stale render submissions through ownership epoch/generation so
|
||||
old Game frames cannot be presented after Shell takes foreground, and old Shell
|
||||
frames cannot be presented after the Game resumes.
|
||||
|
||||
On the desktop host, `Esc` MUST be the primary keyboard request for Home/SystemOS.
|
||||
The physical `Home` key MAY be supported as an alias. This Home request is a
|
||||
host/SystemOS control action and MUST NOT be exposed as a normal guest pad
|
||||
button or userland input capability.
|
||||
|
||||
Real background execution, multiple resident Games, multiple foreground Shells,
|
||||
Game-to-Game switching, Shell app persistence policy, memory eviction policy,
|
||||
and rich multitasking are out of scope for this decision.
|
||||
|
||||
## Rationale
|
||||
|
||||
The chosen model preserves the expected console-like flow: a Game can be
|
||||
paused, Home can run, Shell apps can open, and the same Game can resume without
|
||||
turning the runtime into a general multitasking scheduler.
|
||||
|
||||
Separating `Paused` from `Suspended` keeps authority clear. `Paused` is the
|
||||
contract the Game can observe and react to. `Suspended` is the OS mechanism that
|
||||
prevents the paused Game from continuing to consume ticks, input, audio, and
|
||||
render ownership while another owner is foreground.
|
||||
|
||||
Keeping Hub as root/back-stack prevents VM-backed Shell apps from becoming
|
||||
independent lifecycle roots. Returning to Hub before resuming Game keeps v1
|
||||
navigation deterministic and leaves more complex direct-return behavior for a
|
||||
future decision.
|
||||
|
||||
Keeping Hub/Shell visible until the Game submits a new valid frame avoids
|
||||
presenting stale pixels from the previous Game epoch. This aligns lifecycle
|
||||
state with the render ownership model from `DSC-0040`.
|
||||
|
||||
Using `Esc` as desktop Home makes the control available on compact keyboards.
|
||||
Supporting the physical `Home` key as an alias is acceptable, but the portable
|
||||
contract cannot depend on it.
|
||||
|
||||
## Invariantes / Contrato
|
||||
|
||||
- There is exactly one foreground visual owner at a time.
|
||||
- V1 supports at most one resident Game.
|
||||
- V1 supports at most one foreground Shell app.
|
||||
- Hub/Home is the root Shell owner and back-stack controller.
|
||||
- VM-backed Shell apps follow Shell lifecycle, not Game loop lifecycle.
|
||||
- A paused Game may remain resident, but a suspended Game does not receive
|
||||
normal gameplay ticks, normal game input, or frame pacing.
|
||||
- Pause/resume are cooperative Game-visible lifecycle events.
|
||||
- Suspend/resume scheduling authority belongs to SystemOS.
|
||||
- SystemOS may suspend a Game after the pause budget even if the Game does not
|
||||
cooperate.
|
||||
- Input is cleared or barriered across Game pause/resume boundaries.
|
||||
- Game audio pauses with the Game VM in v1.
|
||||
- Foreground transitions advance render ownership epoch/generation.
|
||||
- Visual foreground returns to Game only after a valid current-epoch Game render
|
||||
submission exists.
|
||||
- Desktop `Esc` is a host/SystemOS Home request; physical `Home` may alias it.
|
||||
- Home/SystemOS is not a guest pad button and is not userland input.
|
||||
- Background execution and general multitasking are explicitly excluded.
|
||||
|
||||
## Impactos
|
||||
|
||||
- **Spec:** runtime lifecycle, firmware/Hub, input, and render ownership specs
|
||||
must document foreground ownership, pause/suspend semantics, Home key mapping,
|
||||
and stale frame invalidation.
|
||||
- **Runtime / SystemOS:** SystemOS needs explicit foreground owner, Hub root,
|
||||
Shell foreground, Game paused, and Game suspended state.
|
||||
- **VM:** VM execution must support pause/resume lifecycle delivery and OS-owned
|
||||
suspension of ticks.
|
||||
- **Firmware:** firmware should observe macro transitions such as GameRunning,
|
||||
Hub/Home, Shell foreground, pause request, and resume request without owning
|
||||
every internal OS detail.
|
||||
- **Host:** host must route desktop `Esc` and optional physical `Home` to a
|
||||
SystemOS Home request instead of guest pad input.
|
||||
- **Input:** Game input must be drained or barriered during pause/resume and
|
||||
Home/SystemOS must stay outside the guest-visible pad ABI.
|
||||
- **Audio:** v1 audio follows Game pause/suspend and does not continue as
|
||||
independent background audio.
|
||||
- **Renderer:** render publication must reject stale submissions after ownership
|
||||
epoch changes and keep previous foreground visible until the resumed Game
|
||||
publishes a valid current-epoch frame.
|
||||
- **Tests:** coverage must prove pause budget behavior, non-foreground VM
|
||||
non-execution, input clearing, host Home routing, Shell return-to-Hub, and
|
||||
stale render rejection.
|
||||
|
||||
## Alternativas Descartadas
|
||||
|
||||
- **Terminate Game when entering Shell:** rejected because it makes
|
||||
`Game -> Shell -> Game` a reload rather than a pause/resume flow.
|
||||
- **Real background execution now:** rejected because it pulls in scheduler,
|
||||
budget, energy, audio, input, IO, memory, and persistence policy beyond v1.
|
||||
- **Multiple resident Games:** rejected for v1 because Game-to-Game switching is
|
||||
owned by `DSC-0043 / AGD-0044`.
|
||||
- **Expose Home as guest input:** rejected because Home changes system
|
||||
foreground authority and must not be handled as ordinary game input.
|
||||
- **Return directly from Shell app to Game in v1:** rejected to keep Hub as the
|
||||
deterministic root/back-stack owner.
|
||||
|
||||
## Referencias
|
||||
|
||||
- Source agenda: `AGD-0041`
|
||||
- Runtime mode separation: `DSC-0031`
|
||||
- SystemOS lifecycle authority: `DSC-0032`
|
||||
- Shell task/window lifecycle: `DSC-0035`
|
||||
- Hub UI direction: `DSC-0036`
|
||||
- Render ownership and stale submission handling: `DSC-0040`
|
||||
- Future Game A -> Home -> Game B switching: `DSC-0043 / AGD-0044`
|
||||
|
||||
## Propagacao Necessaria
|
||||
|
||||
- Update canonical runtime specs for foreground ownership and pause/suspend.
|
||||
- Specify desktop Home request mapping in host/input documentation.
|
||||
- Add plan(s) for SystemOS foreground stack state and Game pause/suspend.
|
||||
- Add plan(s) for VM lifecycle event delivery and forced suspension budget.
|
||||
- Add plan(s) for host `Esc`/`Home` routing outside guest pad input.
|
||||
- Add plan(s) for render epoch integration during Game/Shell transitions.
|
||||
- Add tests covering lifecycle, input, host routing, and render publication
|
||||
invariants.
|
||||
|
||||
## Revision Log
|
||||
|
||||
- 2026-07-03: Initial decision from `AGD-0041`.
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
id: PLN-0136
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Route Desktop Home Key Outside Guest Input
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [host, input, systemos, keyboard, lifecycle]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` makes desktop `Esc` the primary Home/SystemOS request and allows the
|
||||
physical `Home` key as an alias. This request must be intercepted by the
|
||||
host/SystemOS and must not appear as a guest pad button or input intrinsic.
|
||||
|
||||
This plan adds the host input route for the Home request without changing the
|
||||
guest-visible pad surface.
|
||||
|
||||
## Decisions of Origin
|
||||
|
||||
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||
|
||||
## Target
|
||||
|
||||
Route desktop `Esc` and optional physical `Home` key to a SystemOS Home request
|
||||
outside `InputSignals`.
|
||||
|
||||
## Scope
|
||||
|
||||
- Extend `crates/host/prometeu-host-desktop-winit/src/input.rs` or a nearby
|
||||
host input module with a host/system control signal separate from
|
||||
`prometeu_hal::InputSignals`.
|
||||
- Map `KeyCode::Escape` to Home/SystemOS request.
|
||||
- Map `KeyCode::Home` as an alias.
|
||||
- Ensure neither key mutates `start_signal`, `select_signal`, or any pad field.
|
||||
- Route the request through `crates/host/prometeu-host-desktop-winit/src/runner.rs`
|
||||
into firmware/SystemOS.
|
||||
- Add tests proving `Esc` and `Home` do not affect guest pad state.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No pause/resume lifecycle implementation.
|
||||
- No render ownership gating.
|
||||
- No guest-visible Home button.
|
||||
- No gamepad hardware Home mapping unless a future plan defines controller
|
||||
system controls separately.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Define host control state.
|
||||
Add a small host-only type such as `HostSystemControls` with a
|
||||
`home_requested` edge or event. Store it in `HostInputHandler` or in the
|
||||
runner next to the existing input handler.
|
||||
|
||||
2. Update keyboard handling.
|
||||
In `HostInputHandler::handle_event`, recognize `KeyCode::Escape` and
|
||||
`KeyCode::Home` on press. Set the host control event and return without
|
||||
modifying `InputSignals`.
|
||||
|
||||
3. Preserve pad mapping.
|
||||
Keep existing pad mappings unchanged:
|
||||
arrows, `A/D/W/S`, `Q/E`, `Z`, and Shift. Do not reuse `Start` or `Select`
|
||||
for Home.
|
||||
|
||||
4. Route to firmware/SystemOS.
|
||||
In `crates/host/prometeu-host-desktop-winit/src/runner.rs`, consume the
|
||||
host Home event before or during `about_to_wait` and call the firmware or
|
||||
SystemOS method introduced by `PLN-0137` / `PLN-0140`.
|
||||
|
||||
5. Add tests.
|
||||
Add host input tests for `Esc`, physical `Home`, and existing pad mappings.
|
||||
Tests must prove Home produces a system event and no guest pad mutation.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Pressing desktop `Esc` emits a Home/SystemOS host control event.
|
||||
- Pressing physical `Home` emits the same event.
|
||||
- Neither key affects `InputSignals`.
|
||||
- Existing guest pad keyboard mappings still work.
|
||||
- The runner consumes the Home request as a system action.
|
||||
- The implementation does not add a guest syscall, intrinsic, or pad button.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add unit tests in `prometeu-host-desktop-winit` for host input mapping.
|
||||
- Run `cargo test -p prometeu-host-desktop-winit input`.
|
||||
- Run `cargo test -p prometeu-hal input` if pad signal behavior changes.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- `Esc` may conflict with debugger or window-close expectations. Keep debugger
|
||||
start handling on `D` unchanged and do not map `Esc` to process exit.
|
||||
- Physical `Home` is not available on every keyboard, so it must remain an
|
||||
alias rather than the primary portable mapping.
|
||||
@@ -1,116 +0,0 @@
|
||||
---
|
||||
id: PLN-0137
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Implement SystemOS Foreground Stack State
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, foreground, shell, game]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` requires SystemOS to own foreground authority. The system must know
|
||||
which owner is foreground, keep Hub/Home as root, allow only one resident Game,
|
||||
allow only one foreground Shell, and return from VM-backed Shell apps to Hub in
|
||||
v1.
|
||||
|
||||
This plan implements the SystemOS state model only. It does not yet deliver
|
||||
Game pause/resume events, host keyboard routing, or render/audio/input boundary
|
||||
changes.
|
||||
|
||||
## Decisions of Origin
|
||||
|
||||
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||
|
||||
## Target
|
||||
|
||||
Add an explicit SystemOS foreground stack model that can represent Hub, a
|
||||
foreground Shell task, and a paused/suspended resident Game.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add or extend SystemOS-owned foreground state under
|
||||
`crates/console/prometeu-system/src/os/` or
|
||||
`crates/console/prometeu-system/src/services/`.
|
||||
- Represent v1 foreground owners:
|
||||
- Hub/Home root;
|
||||
- Shell task foreground;
|
||||
- Game foreground;
|
||||
- Game paused/suspended resident.
|
||||
- Enforce at most one resident Game and at most one foreground Shell.
|
||||
- Keep Hub as root/back-stack controller.
|
||||
- Ensure Shell close returns to Hub/Home in v1.
|
||||
- Expose focused queries through existing or new facades, likely
|
||||
`crates/console/prometeu-system/src/os/facades/lifecycle.rs` and
|
||||
`crates/console/prometeu-system/src/os/facades/sessions.rs`.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No VM pause/resume event delivery.
|
||||
- No host `Esc`/`Home` keyboard mapping.
|
||||
- No render epoch implementation.
|
||||
- No Game-to-Game switching.
|
||||
- No background execution.
|
||||
- No memory eviction for the resident Game.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Define foreground model types.
|
||||
Add enums/structs for foreground owner and resident Game state in the most
|
||||
local SystemOS module. The model must distinguish Game foreground, Game
|
||||
paused/suspended, Hub foreground, and Shell task foreground.
|
||||
|
||||
2. Add SystemOS storage.
|
||||
Store the foreground model in `SystemOS` from
|
||||
`crates/console/prometeu-system/src/os/system_os.rs` with initialization to
|
||||
Hub/Home root.
|
||||
|
||||
3. Wire lifecycle facade operations.
|
||||
Extend lifecycle/session facades so firmware can request:
|
||||
- set Game foreground;
|
||||
- request Home from Game;
|
||||
- set Shell foreground from Hub;
|
||||
- close Shell and return to Hub;
|
||||
- query current foreground owner;
|
||||
- query resident Game task.
|
||||
|
||||
4. Enforce cardinality.
|
||||
Add checks that reject a second resident Game and a second foreground Shell
|
||||
with typed lifecycle errors. Use existing `LifecycleError` style or add
|
||||
precise variants.
|
||||
|
||||
5. Integrate existing Shell close behavior.
|
||||
Update `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
|
||||
only where needed so closing a Shell task routes through the foreground model
|
||||
and ends in `FirmwareState::HubHome`.
|
||||
|
||||
6. Add tests.
|
||||
Cover initial Hub foreground, Game foreground registration, Home request
|
||||
moving Game to resident paused/suspended state, Shell foreground activation,
|
||||
Shell close returning to Hub, and cardinality rejection.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- SystemOS has an explicit foreground owner model.
|
||||
- Hub/Home is the initialized root foreground owner.
|
||||
- Only one resident Game can exist in v1.
|
||||
- Only one Shell task can be foreground in v1.
|
||||
- VM-backed Shell close returns to Hub/Home.
|
||||
- Foreground queries are available to firmware and later plans.
|
||||
- No implementation path enables background execution.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add focused unit tests in `prometeu-system` around the new model and facade.
|
||||
- Run `cargo test -p prometeu-system lifecycle foreground`.
|
||||
- Run `cargo test -p prometeu-firmware shell`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Existing `TaskState::Foreground` and `TaskState::Suspended` may look like the
|
||||
complete model. Do not overload them until foreground ownership and Hub root
|
||||
authority are explicit.
|
||||
- Shell windows already have focus semantics. Keep window focus as visual/task
|
||||
evidence, not the sole source of SystemOS foreground truth.
|
||||
@@ -1,114 +0,0 @@
|
||||
---
|
||||
id: PLN-0138
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Specify Foreground Pause and Home Contract
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, specs, lifecycle, input, renderer, foreground]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` establishes the v1 foreground stack contract: one foreground visual
|
||||
owner, one resident Game, one foreground Shell, Hub as root, Game-visible
|
||||
pause/resume, OS-owned suspension, desktop `Esc` as Home/SystemOS request, and
|
||||
render epoch invalidation across foreground transitions.
|
||||
|
||||
This plan updates the canonical runtime specs before implementation so code
|
||||
plans cannot drift into guest-owned Home input, background execution, or stale
|
||||
frame presentation.
|
||||
|
||||
## Decisions of Origin
|
||||
|
||||
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||
|
||||
## Target
|
||||
|
||||
Document the foreground, pause/suspend, Home request, input, audio, and render
|
||||
ownership contract in the canonical runtime specs.
|
||||
|
||||
## Scope
|
||||
|
||||
- Update `docs/specs/runtime/12-firmware-pos-and-prometeuhub.md` with:
|
||||
- Hub as root/special Shell owner;
|
||||
- one foreground visual owner;
|
||||
- one resident Game;
|
||||
- one foreground Shell;
|
||||
- `Game -> Home/Shell -> same Game` lifecycle;
|
||||
- VM-backed Shell app return-to-Hub behavior.
|
||||
- Update `docs/specs/runtime/06-input-peripheral.md` with:
|
||||
- Home/SystemOS as host/system control, not pad input;
|
||||
- desktop `Esc` as primary Home request;
|
||||
- physical `Home` key as optional alias;
|
||||
- input clear/barrier requirements across Game pause/resume.
|
||||
- Update `docs/specs/runtime/09-events-and-concurrency.md` with:
|
||||
- pause notification budget;
|
||||
- OS-owned suspension after the budget;
|
||||
- resume/foreground-restore notification before visual return.
|
||||
- Update `docs/specs/runtime/14-boot-profiles.md` only to clarify that this
|
||||
foreground contract is not Game-to-Game switching and does not change direct
|
||||
`--run` or `--games-root` boot semantics.
|
||||
- Update renderer-related spec text in the most local existing runtime spec if
|
||||
present, otherwise add a short subsection to `12-firmware-pos-and-prometeuhub.md`
|
||||
describing ownership epoch invalidation and first-valid-frame gating.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No Rust implementation.
|
||||
- No new guest ABI or pad button.
|
||||
- No background execution policy.
|
||||
- No Game A -> Home -> Game B switching.
|
||||
- No memory eviction policy for resident Games.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Edit `12-firmware-pos-and-prometeuhub.md`.
|
||||
Define foreground owner cardinality, Hub root ownership, Shell foreground
|
||||
behavior, Game resident/suspended behavior, return-to-Hub from Shell, and the
|
||||
requirement to keep Hub/Shell visible until a resumed Game submits a valid
|
||||
current-epoch frame.
|
||||
|
||||
2. Edit `06-input-peripheral.md`.
|
||||
State that Home/SystemOS is outside the guest-visible pad and input
|
||||
intrinsic surface. Document desktop `Esc` as the primary host mapping and
|
||||
physical `Home` as an optional alias.
|
||||
|
||||
3. Edit `09-events-and-concurrency.md`.
|
||||
Add the pause/resume event ordering: Home request, pause notification,
|
||||
bounded reaction budget, OS suspension, resume/foreground-restore
|
||||
notification, first-valid-frame visual return.
|
||||
|
||||
4. Edit `14-boot-profiles.md`.
|
||||
Cross-reference the foreground contract and explicitly keep direct boot,
|
||||
games-root Home launch, and future Game-to-Game switching separate.
|
||||
|
||||
5. Run text checks.
|
||||
Search for wording that implies Home is a guest input button, a guest ABI, or
|
||||
background execution. Replace misleading text with the `DEC-0037` contract.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Specs define `Paused` as Game-visible and `Suspended` as OS-owned.
|
||||
- Specs state that desktop `Esc` is the primary Home request and is not guest
|
||||
pad input.
|
||||
- Specs state that the Game receives pause/resume notifications but does not
|
||||
control OS suspension.
|
||||
- Specs state that Hub is the root Shell owner and Shell app close returns to
|
||||
Hub in v1.
|
||||
- Specs state that visual return to Game waits for a valid current-epoch render
|
||||
submission.
|
||||
- Specs explicitly exclude background execution and Game-to-Game switching.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run `discussion validate`.
|
||||
- Run `rg -n "Home|Esc|Suspended|Paused|foreground|background execution" docs/specs/runtime`.
|
||||
- Verify no edited spec describes Home/SystemOS as a guest-visible pad button.
|
||||
|
||||
## Risks
|
||||
|
||||
- The spec could accidentally reopen Game-to-Game switching; keep that scoped to
|
||||
`DSC-0043 / AGD-0044`.
|
||||
- The input spec could confuse physical keyboard mapping with VM input; keep
|
||||
host/system controls outside the guest input surface.
|
||||
@@ -1,106 +0,0 @@
|
||||
---
|
||||
id: PLN-0139
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Validate Game Home Shell Game End To End
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, validation, firmware, host, lifecycle]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` is not complete until the product flow is proven end to end:
|
||||
a Game runs, the user requests Home, the Game is paused/suspended, Hub or a
|
||||
VM-backed Shell takes foreground, closing Shell returns to Hub, and the same
|
||||
Game can resume only after a valid current-epoch frame exists.
|
||||
|
||||
This plan adds final validation after the spec, SystemOS, VM, host input, and
|
||||
render/audio/input boundary plans are implemented.
|
||||
|
||||
## Decisions of Origin
|
||||
|
||||
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||
|
||||
## Target
|
||||
|
||||
Prove the complete `Game -> Home/Shell -> same Game` lifecycle and prevent
|
||||
regressions around guest input, foreground authority, and stale rendering.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add integration-style tests for:
|
||||
- Game running to Home request;
|
||||
- pause notification and forced suspension;
|
||||
- Hub foreground while Game is resident;
|
||||
- VM-backed Shell foreground while Game is suspended;
|
||||
- Shell close returning to Hub;
|
||||
- resume request returning to same Game;
|
||||
- first-valid-frame visual restore;
|
||||
- host `Esc`/`Home` not entering guest input.
|
||||
- Add manual smoke instructions for desktop host.
|
||||
- Confirm direct `--run` and games-root Home launch remain separate.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No new implementation beyond tests and developer-facing validation notes.
|
||||
- No Game A -> Home -> Game B switching.
|
||||
- No performance tuning.
|
||||
- No polished UI.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Add firmware/SystemOS integration tests.
|
||||
Use the most stable existing seams in `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
and `crates/console/prometeu-system` tests to drive Game foreground, Home
|
||||
request, Shell foreground, Shell close, and Game resume.
|
||||
|
||||
2. Add host input integration tests.
|
||||
Ensure `Esc` and physical `Home` create a host Home event and do not mutate
|
||||
guest `InputSignals`.
|
||||
|
||||
3. Add render publication validation.
|
||||
Assert stale submissions from the pre-pause Game epoch are rejected after
|
||||
Home takes foreground and that the Game is not visually restored until a new
|
||||
current-epoch submission exists.
|
||||
|
||||
4. Add audio/input boundary validation.
|
||||
Assert Game input is cleared or barriered across pause/resume. Assert Game
|
||||
audio pause follows Game suspension.
|
||||
|
||||
5. Add direct boot and games-root regression checks.
|
||||
Ensure direct `--run <cart>` remains independent from Home request handling
|
||||
and that games-root Home launch still enters the Game path.
|
||||
|
||||
6. Document manual smoke commands.
|
||||
Add or update developer-facing spec text with release-mode commands:
|
||||
- `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`
|
||||
Include the expected `Esc -> Home -> Shell -> Hub -> resume Game` behavior
|
||||
once implemented.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Automated tests cover `Game -> Home -> same Game`.
|
||||
- Automated tests cover `Game -> Home -> Shell -> Hub -> same Game`.
|
||||
- Tests prove Home request is host/SystemOS control, not guest pad input.
|
||||
- Tests prove suspended Game does not tick.
|
||||
- Tests prove stale render submissions are not presented.
|
||||
- Tests prove visual return waits for a current-epoch Game frame.
|
||||
- Direct `--run` and games-root Home launch regressions pass.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `cargo test -p prometeu-firmware`.
|
||||
- Run `cargo test -p prometeu-host-desktop-winit`.
|
||||
- Run any targeted render worker tests affected by ownership epoch changes.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- The current test seams may not expose enough host-driven lifecycle behavior.
|
||||
If needed, add narrow test-only helpers rather than testing through sleeps or
|
||||
real-time window loops.
|
||||
- End-to-end validation can become flaky if it depends on wall-clock timing.
|
||||
Use deterministic ticks and explicit state transitions.
|
||||
@@ -1,110 +0,0 @@
|
||||
---
|
||||
id: PLN-0140
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Deliver Game Pause Resume and Suspension
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, vm, lifecycle, pause, suspension]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` separates Game-visible `Paused` from OS-owned `Suspended`. When Home
|
||||
is requested during Game execution, SystemOS must notify the Game, give it a
|
||||
short bounded budget, then suspend the VM even if the Game does not cooperate.
|
||||
When returning, SystemOS must reactivate the VM and send a resume or
|
||||
foreground-restore notification before the visual owner returns to Game.
|
||||
|
||||
This plan implements the pause/resume and suspension mechanics after the
|
||||
foreground state model exists.
|
||||
|
||||
## Decisions of Origin
|
||||
|
||||
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||
|
||||
## Target
|
||||
|
||||
Add Game pause/resume lifecycle delivery and OS-enforced VM suspension for the
|
||||
same resident Game.
|
||||
|
||||
## Scope
|
||||
|
||||
- Add a Game lifecycle event model for pause and resume/foreground-restore.
|
||||
- Add a bounded pause reaction budget owned by SystemOS.
|
||||
- Suspend the Game VM after the budget even if the Game does not cooperate.
|
||||
- Ensure a suspended Game receives no normal gameplay ticks.
|
||||
- Reactivate the VM and deliver resume/foreground-restore before Game visual
|
||||
foreground restoration.
|
||||
- Integrate with `GameRunningStep` and VM runtime tick control.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No render first-valid-frame gating; that is in `PLN-0141`.
|
||||
- No host keyboard routing; that is in `PLN-0136`.
|
||||
- No new guest syscall.
|
||||
- No background execution.
|
||||
- No Game-to-Game switching.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Add lifecycle event representation.
|
||||
Define pause/resume events in the most local runtime lifecycle module,
|
||||
likely under `crates/console/prometeu-system/src/os/lifecycle.rs` or a new
|
||||
SystemOS lifecycle submodule. Events must be observable by the VM/runtime
|
||||
path without giving the Game authority over suspension.
|
||||
|
||||
2. Add pause transition state.
|
||||
Extend the foreground state from `PLN-0137` with a `PauseRequested` or
|
||||
equivalent transition state that records the target Game task and the
|
||||
remaining pause budget.
|
||||
|
||||
3. Gate VM ticks.
|
||||
Update `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
|
||||
and `crates/console/prometeu-system/src/services/vm_runtime/tick.rs` so a
|
||||
suspended Game does not receive normal ticks, normal input, or frame pacing.
|
||||
|
||||
4. Deliver pause notification.
|
||||
Add the mechanism that makes the pause event visible to the running Game
|
||||
before suspension. Use an existing VM event channel if present; otherwise add
|
||||
a narrow lifecycle-event queue owned by SystemOS/VM runtime.
|
||||
|
||||
5. Enforce the budget.
|
||||
Advance the pause budget on firmware ticks. When it expires, transition the
|
||||
Game task/process to suspended through SystemOS lifecycle regardless of Game
|
||||
cooperation.
|
||||
|
||||
6. Deliver resume notification.
|
||||
On return to the resident Game, transition from suspended to resume-requested,
|
||||
reactivate VM execution, deliver resume/foreground-restore, and leave visual
|
||||
restoration to the render boundary plan.
|
||||
|
||||
7. Add tests.
|
||||
Cover cooperative pause, non-cooperative forced suspension, no tick while
|
||||
suspended, resume notification delivery, and no Game-owned ability to cancel
|
||||
OS suspension.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Game receives pause before suspension.
|
||||
- SystemOS suspends after a bounded budget even if the Game does not cooperate.
|
||||
- Suspended Game does not receive normal gameplay ticks.
|
||||
- Resume/foreground-restore is delivered before visual return to Game.
|
||||
- Game cannot prevent OS suspension through guest-visible behavior.
|
||||
- Existing debugger pause behavior remains distinct from lifecycle suspension.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Add unit tests in `prometeu-system` for lifecycle transition state.
|
||||
- Add firmware tests around `GameRunningStep` pause request and suspension.
|
||||
- Add VM runtime tests proving suspended state suppresses normal ticks.
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `cargo test -p prometeu-firmware`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Debugger pause already exists in VM runtime. Keep debug pause separate from
|
||||
lifecycle pause/suspend.
|
||||
- A lifecycle event queue could become a general app event system. Keep this
|
||||
plan limited to pause/resume required by `DEC-0037`.
|
||||
-104
@@ -1,104 +0,0 @@
|
||||
---
|
||||
id: PLN-0141
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Integrate Render Audio and Input Pause Boundaries
|
||||
status: done
|
||||
created: 2026-07-03
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, renderer, audio, input, foreground, lifecycle]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` requires foreground transitions to invalidate stale render
|
||||
submissions, keep Hub/Shell visible until the resumed Game publishes a valid
|
||||
current-epoch frame, clear or barrier Game input across pause/resume, and pause
|
||||
Game audio with the Game VM in v1.
|
||||
|
||||
This plan integrates those boundary effects after SystemOS foreground state and
|
||||
Game pause/resume mechanics exist.
|
||||
|
||||
## Decisions of Origin
|
||||
|
||||
- `DEC-0037` - Foreground Stack and Game Pause Contract.
|
||||
|
||||
## Target
|
||||
|
||||
Make foreground transitions safe at the render, input, and audio boundaries.
|
||||
|
||||
## Scope
|
||||
|
||||
- Advance render ownership epoch/generation whenever foreground owner changes.
|
||||
- Discard stale Game frames after Shell/Hub takes foreground.
|
||||
- Discard stale Shell frames after Game resumes.
|
||||
- Keep Hub/Shell visible until a resumed Game publishes a valid current-epoch
|
||||
submission.
|
||||
- Clear or barrier Game input across pause/resume boundaries.
|
||||
- Pause Game audio with the Game VM in v1.
|
||||
- Add telemetry/tests for stale discards and first-valid-frame gating.
|
||||
|
||||
## Out of Scope
|
||||
|
||||
- No independent background audio policy.
|
||||
- No overlay rendering policy.
|
||||
- No Game-to-Game switch rendering.
|
||||
- No full memory eviction behavior.
|
||||
|
||||
## Execution Plan
|
||||
|
||||
1. Extend render ownership transition calls.
|
||||
Update `crates/console/prometeu-system/src/services/vm_runtime/render_manager.rs`
|
||||
and call sites in `tick.rs` so foreground owner changes explicitly advance
|
||||
ownership epoch/generation, not only app mode/app id changes.
|
||||
|
||||
2. Add foreground restore gating.
|
||||
Add state in SystemOS or firmware that records when visual return to Game is
|
||||
pending. The state must remain in Hub/Shell presentation until a
|
||||
current-epoch Game submission is observed.
|
||||
|
||||
3. Update host presentation selection.
|
||||
Update `crates/host/prometeu-host-desktop-winit/src/runner.rs` if necessary
|
||||
so `should_present_worker_frame` and fallback framebuffer presentation obey
|
||||
the foreground restore gate.
|
||||
|
||||
4. Add stale discard coverage.
|
||||
Extend render manager and render worker tests to prove stale submissions
|
||||
from the previous owner are discarded after epoch change.
|
||||
|
||||
5. Add input boundary clearing.
|
||||
Add a SystemOS or firmware input barrier when Game pause starts and when
|
||||
Game resume starts. The barrier must prevent held or pressed Game input from
|
||||
leaking across the lifecycle boundary.
|
||||
|
||||
6. Add audio pause integration.
|
||||
Ensure Game pause/suspend produces the existing host audio pause command path
|
||||
or a new explicit lifecycle audio pause signal. Keep this separate from
|
||||
debugger pause if the observable cause matters in tests.
|
||||
|
||||
7. Add tests.
|
||||
Cover stale frame discard, first-valid-frame visual return, input clearing,
|
||||
and Game audio pause/resume behavior.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Foreground owner changes advance render ownership epoch/generation.
|
||||
- Old Game frames cannot present after Hub/Shell takes foreground.
|
||||
- Old Hub/Shell frames cannot present after Game resumes.
|
||||
- Visual return to Game waits for a valid current-epoch Game submission.
|
||||
- Game input does not leak across pause/resume boundaries.
|
||||
- Game audio pauses with Game suspension in v1.
|
||||
|
||||
## Tests / Validation
|
||||
|
||||
- Run `cargo test -p prometeu-system render foreground`.
|
||||
- Run `cargo test -p prometeu-firmware pause`.
|
||||
- Run `cargo test -p prometeu-host-desktop-winit presentation`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Risks
|
||||
|
||||
- Existing render epoch logic may already key off app mode/app id. Foreground
|
||||
owner changes must be explicit so Shell/Hub and resumed Game cannot share a
|
||||
stale epoch by accident.
|
||||
- Audio pause currently follows VM paused/debugger state in the host. Keep Game
|
||||
lifecycle pause distinct enough that tests can prove the decision contract.
|
||||
@@ -1,127 +0,0 @@
|
||||
---
|
||||
id: PLN-0142
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Deliver Game Lifecycle Events To VM Runtime
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` requires pause/resume to be Game-visible lifecycle events. The
|
||||
current implementation records `GameLifecycleEvent` values in SystemOS, but no
|
||||
runtime or VM execution path consumes them. Tests currently prove that the OS
|
||||
queue contains events, not that the Game/runtime can observe them before
|
||||
suspension or after resume.
|
||||
|
||||
## Objective
|
||||
|
||||
Deliver Game lifecycle pause/resume events from SystemOS into the VM runtime
|
||||
boundary in a deterministic, testable way, without exposing Home as guest pad
|
||||
input or a userland syscall.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Fixes the lifecycle event delivery gap found after `PLN-0140` and
|
||||
`PLN-0141`.
|
||||
- `PLN-0143` depends on this plan if it needs to prove that the pause event is
|
||||
consumed before the pause budget expires.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Define the runtime-facing lifecycle event delivery API for `Pause` and
|
||||
`ResumeForeground`.
|
||||
- Move events from the SystemOS queue into the VM/runtime tick boundary.
|
||||
- Make delivered events observable in tests without creating a broad app event
|
||||
system.
|
||||
- Preserve the distinction between lifecycle pause and debugger pause.
|
||||
- Ensure events are delivered only to the resident Game task they target.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No guest Home input, pad field, intrinsic, or syscall.
|
||||
- No general userland event bus.
|
||||
- No background execution while suspended.
|
||||
- No new Shell lifecycle event model.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not implement Game-to-Game switching.
|
||||
- Do not change renderer ownership policy except where tests need to assert
|
||||
lifecycle event ordering.
|
||||
- Do not add wall-clock timers or asynchronous callbacks.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a narrow VM runtime lifecycle inbox.
|
||||
- What changes: introduce a small data structure for pending/delivered Game
|
||||
lifecycle events in `VirtualMachineRuntime`.
|
||||
- How it changes: add methods such as `queue_game_lifecycle_events`,
|
||||
`take_delivered_game_lifecycle_events`, or a more idiomatic local name
|
||||
that preserves deterministic frame-boundary delivery.
|
||||
- File(s): `crates/console/prometeu-system/src/services/vm_runtime/mod.rs`,
|
||||
`crates/console/prometeu-system/src/services/vm_runtime/tick.rs`, and
|
||||
focused tests under `crates/console/prometeu-system/src/services/vm_runtime/`.
|
||||
|
||||
2. Route SystemOS events into the VM facade before ticking.
|
||||
- What changes: `VmFacade::tick` must drain lifecycle events from SystemOS
|
||||
and pass only events targeted at the currently running resident Game into
|
||||
the VM runtime lifecycle inbox.
|
||||
- How it changes: use the existing `LifecycleFacade::take_game_lifecycle_events`
|
||||
or replace it with an equivalent internal method if borrowing requires a
|
||||
cleaner API. Do not leave events only observable through
|
||||
`pending_game_lifecycle_events`.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/vm.rs`,
|
||||
`crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
3. Expose deterministic test visibility.
|
||||
- What changes: tests must be able to assert that `Pause` and
|
||||
`ResumeForeground` reached the VM runtime boundary.
|
||||
- How it changes: add test-only or public diagnostic accessors on
|
||||
`VmFacade`/`VirtualMachineRuntime` for delivered lifecycle events, scoped
|
||||
to lifecycle validation rather than a guest ABI.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/vm.rs`,
|
||||
`crates/console/prometeu-system/src/services/vm_runtime/tests.rs`.
|
||||
|
||||
4. Update firmware tests to assert delivery, not only queue presence.
|
||||
- What changes: existing firmware tests that inspect
|
||||
`pending_game_lifecycle_events` should assert VM-runtime delivery at the
|
||||
tick boundary.
|
||||
- How it changes: after a Game pause/resume flow, verify that the VM/runtime
|
||||
observed the lifecycle event in order.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `Pause` is moved from SystemOS into the VM runtime boundary before
|
||||
suspension is allowed to complete.
|
||||
- [ ] `ResumeForeground` is moved into the VM runtime boundary before the Game
|
||||
is considered visually restored.
|
||||
- [ ] Tests fail if events remain only in `SystemOS.game_lifecycle_events`.
|
||||
- [ ] Lifecycle event delivery does not mutate `InputSignals`.
|
||||
- [ ] Debugger pause remains separate from lifecycle pause.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit tests in `prometeu-system` proving VM runtime lifecycle event delivery
|
||||
and drain semantics.
|
||||
- Firmware tests proving Home request delivers `Pause` to the VM/runtime before
|
||||
suspension.
|
||||
- Firmware tests proving resident Game resume delivers `ResumeForeground`
|
||||
before Game foreground restoration.
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `cargo test -p prometeu-firmware`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/mod.rs`
|
||||
- `crates/console/prometeu-system/src/services/vm_runtime/tick.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
-122
@@ -1,122 +0,0 @@
|
||||
---
|
||||
id: PLN-0143
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Guarantee Cooperative Pause Budget Tick Before Suspension
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` requires a Game-visible `Paused` event followed by a bounded
|
||||
cooperative reaction budget before SystemOS imposes `Suspended`. The current
|
||||
implementation uses a one-tick budget and advances it before `vm.tick` in
|
||||
`GameRunningStep`, so the Game can be suspended without any runtime tick in
|
||||
which it could observe or react to pause.
|
||||
|
||||
## Objective
|
||||
|
||||
Guarantee at least one deterministic VM/runtime delivery point for the Game to
|
||||
observe pause before forced suspension, while preserving SystemOS authority to
|
||||
suspend the Game after the budget.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Should be executed after or together with `PLN-0142`, because budget tests
|
||||
must prove delivered lifecycle events, not only queued OS events.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Fix pause budget ordering so the pause budget cannot expire before the VM
|
||||
runtime has a delivery point for `Pause`.
|
||||
- Define the budget in deterministic machine ticks/frames, not wall-clock time.
|
||||
- Ensure a Game receives no normal gameplay ticks after it reaches
|
||||
`PausedSuspended`.
|
||||
- Preserve the existing forced-suspension authority when the budget expires.
|
||||
- Update tests that currently assert no VM tick occurs immediately after Home.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No guest-controlled cancellation of suspension.
|
||||
- No background execution after suspension.
|
||||
- No extension of the pause budget based on host timing.
|
||||
- No direct visual-return behavior; render restore gating remains covered by
|
||||
the existing render boundary work.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not add a general scheduler.
|
||||
- Do not make pause cooperation mandatory for suspension.
|
||||
- Do not conflate lifecycle pause with debugger pause.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Redefine pause budget state transitions.
|
||||
- What changes: `ResidentGameState::PauseRequested` must represent a state
|
||||
in which one or more delivery ticks remain before `PausedSuspended`.
|
||||
- How it changes: adjust `ForegroundStack::advance_pause_budget` or split it
|
||||
into explicit methods such as `mark_pause_delivered` and
|
||||
`advance_pause_budget_after_delivery`.
|
||||
- File(s): `crates/console/prometeu-system/src/services/foreground.rs`.
|
||||
|
||||
2. Move budget advancement after lifecycle delivery.
|
||||
- What changes: `GameRunningStep::on_update` must not suspend before the VM
|
||||
runtime has a chance to receive and process the pause lifecycle event.
|
||||
- How it changes: reorder the GameRunning update so the event delivery path
|
||||
runs first, then the budget is advanced, and only a subsequent eligible
|
||||
boundary can force suspension.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`,
|
||||
`crates/console/prometeu-system/src/os/facades/vm.rs`.
|
||||
|
||||
3. Preserve no-tick-after-suspended behavior.
|
||||
- What changes: once `ResidentGameState::PausedSuspended` and
|
||||
`TaskState::Suspended` are reached, the Game must not receive normal ticks,
|
||||
normal input, or frame pacing.
|
||||
- How it changes: keep the existing early transition to Hub after suspension
|
||||
expires, but ensure it occurs after the cooperative pause window rather
|
||||
than before it.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`.
|
||||
|
||||
4. Update tests to match the corrected semantics.
|
||||
- What changes: tests must stop asserting that the first tick after Home does
|
||||
zero VM work purely because Home was requested.
|
||||
- How it changes: assert that the pause event was delivered during the
|
||||
cooperative window, then assert that a later deterministic tick forces
|
||||
suspension and no further Game ticks occur.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`,
|
||||
`crates/console/prometeu-system/src/os/system_os.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] A Game receives a deterministic pause delivery point before SystemOS
|
||||
suspends it.
|
||||
- [ ] SystemOS still suspends the Game after the bounded budget even if the
|
||||
Game does not cooperate.
|
||||
- [ ] A suspended Game receives no normal gameplay ticks, normal Game input, or
|
||||
frame pacing.
|
||||
- [ ] Tests prove the order: Home request -> pause delivery -> budget expiry ->
|
||||
suspension.
|
||||
- [ ] Debugger pause behavior is unchanged.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit tests in `prometeu-system` for pause budget transitions.
|
||||
- Firmware tests for non-cooperative forced suspension after at least one
|
||||
delivered pause boundary.
|
||||
- Regression tests proving suspended Game tick count does not advance.
|
||||
- Run `cargo test -p prometeu-system foreground lifecycle`.
|
||||
- Run `cargo test -p prometeu-firmware pause`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/services/foreground.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/vm.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_game_running.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
-124
@@ -1,124 +0,0 @@
|
||||
---
|
||||
id: PLN-0144
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Suspend Resident Game When Shell Takes Foreground
|
||||
status: done
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` says a suspended resident Game must not receive normal gameplay
|
||||
ticks, normal Game input, or frame pacing while Hub/Shell owns foreground. The
|
||||
current `set_shell_foreground` path can mark the resident Game as
|
||||
`PausedSuspended` in the foreground stack while `TaskManager::set_foreground`
|
||||
only demotes the previous foreground Game task to `Background`. This creates a
|
||||
state mismatch if a Shell is opened while the Game has not already gone through
|
||||
the Home suspension path.
|
||||
|
||||
## Objective
|
||||
|
||||
Make Shell foreground acquisition either require an already suspended resident
|
||||
Game or perform the necessary OS-owned suspension consistently across
|
||||
foreground stack, task manager, and process manager.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Can be implemented independently of `PLN-0142` and `PLN-0143`, but tests
|
||||
should be rerun with those fixes if they are executed first.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Close the mismatch between `ResidentGameState::PausedSuspended` and
|
||||
`TaskState::Background`.
|
||||
- Ensure Shell foreground cannot leave a resident Game running or backgrounded.
|
||||
- Cover both `create_vm_shell_task` and `create_native_shell_task` paths.
|
||||
- Preserve the rule that only one foreground Shell may exist.
|
||||
- Keep the normal Home -> Shell flow working.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No direct Shell -> Game return behavior; v1 still returns Shell close to Hub.
|
||||
- No background Game execution.
|
||||
- No multiple resident Games.
|
||||
- No Shell persistence policy changes.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not broaden Shell lifecycle semantics.
|
||||
- Do not implement Game-to-Game switching.
|
||||
- Do not add UI controls for resume.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Define the legal Shell foreground precondition.
|
||||
- What changes: decide in code whether Shell foreground requires the
|
||||
resident Game to already be `PausedSuspended`, or whether
|
||||
`set_shell_foreground_task` is responsible for suspending it.
|
||||
- How it changes: prefer centralizing the invariant in
|
||||
`LifecycleFacade::set_shell_foreground_task`, because it owns task/process
|
||||
transitions.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`,
|
||||
`crates/console/prometeu-system/src/services/foreground.rs`.
|
||||
|
||||
2. Synchronize task/process state when Shell takes foreground.
|
||||
- What changes: if a resident Game exists and is not already suspended,
|
||||
mark the Game task and process `Suspended` before or during Shell
|
||||
foreground transition.
|
||||
- How it changes: use `process_id_for_task` for the resident Game and call
|
||||
`task_manager.mark_suspended` and `process_manager.mark_suspended` in the
|
||||
same lifecycle operation that sets Shell foreground.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
3. Tighten foreground stack behavior.
|
||||
- What changes: `ForegroundStack::set_shell_foreground` must not silently
|
||||
hide invalid state transitions.
|
||||
- How it changes: either reject Shell foreground when the resident Game is
|
||||
still `Foreground`/`PauseRequested`, or return enough information for the
|
||||
lifecycle facade to suspend the resident Game explicitly.
|
||||
- File(s): `crates/console/prometeu-system/src/services/foreground.rs`.
|
||||
|
||||
4. Add regression tests for reachable session paths.
|
||||
- What changes: create tests that call `create_vm_shell_task` and
|
||||
`create_native_shell_task` while a Game task is foreground.
|
||||
- How it changes: assert foreground owner is Shell, resident Game remains
|
||||
recorded, Game task state is `Suspended`, and Game process state is
|
||||
`Suspended`.
|
||||
- File(s): `crates/console/prometeu-system/src/os/system_os.rs`,
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware.rs` if the
|
||||
firmware Home/Shell path needs coverage.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] A Shell foreground transition cannot leave the resident Game in
|
||||
`TaskState::Background`.
|
||||
- [ ] Foreground stack state, task state, and process state agree that the
|
||||
resident Game is suspended while Shell is foreground.
|
||||
- [ ] `create_vm_shell_task` and `create_native_shell_task` both preserve the
|
||||
invariant.
|
||||
- [ ] Opening a second foreground Shell remains rejected.
|
||||
- [ ] Closing Shell still returns to Hub/Home, not directly to Game.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit tests in `prometeu-system` for `set_shell_foreground_task` with a
|
||||
resident foreground Game.
|
||||
- Session facade tests for VM Shell and native Shell creation while a Game is
|
||||
resident.
|
||||
- Existing firmware Shell close tests must continue to pass.
|
||||
- Run `cargo test -p prometeu-system foreground lifecycle shell`.
|
||||
- Run `cargo test -p prometeu-firmware shell`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/services/foreground.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- `crates/console/prometeu-system/src/os/facades/sessions.rs`
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
@@ -1,149 +0,0 @@
|
||||
---
|
||||
id: PLN-0145
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Centralize Resident Game Resume Transition
|
||||
status: open
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` requires returning to the same resident Game to reactivate the Game
|
||||
VM, restore render ownership, send a resume/foreground lifecycle notification,
|
||||
and clear or barrier pending Game input. That transition currently exists in
|
||||
more than one firmware path: `Firmware::resume_resident_game_from_home` and the
|
||||
Hub library click path that resumes the selected resident Game by `app_id`.
|
||||
|
||||
The behavior is correct, but the duplication is fragile. Any future change to
|
||||
resume ordering, input barriers, render ownership, or lifecycle event delivery
|
||||
could fix one path while leaving the other path stale.
|
||||
|
||||
## Objective
|
||||
|
||||
Create one firmware-owned resident Game resume helper and route every
|
||||
Home/Hub-to-Game resume path through it.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Depends on the accepted v1 identity rule that `app_id` is unique for all
|
||||
games and may be used to decide whether a Hub game selection refers to the
|
||||
current resident Game.
|
||||
- Should preserve the behavior introduced by `PLN-0142`, `PLN-0143`, and
|
||||
`PLN-0144`.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Centralize resident Game resume orchestration in `Firmware`.
|
||||
- Preserve resume lifecycle event queuing through `LifecycleFacade::resume_task`.
|
||||
- Preserve render ownership transition back to `AppMode::Game`.
|
||||
- Preserve input barrier behavior across all Home/Hub-to-Game resume paths.
|
||||
- Preserve the Hub rule that selecting the same resident Game resumes it, while
|
||||
selecting a different Game remains blocked by v1 scope.
|
||||
- Keep tests proving same-task resume, lifecycle event delivery, and input
|
||||
barriering.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No Game-to-Game switching.
|
||||
- No multiple resident Games.
|
||||
- No change to `app_id` uniqueness policy.
|
||||
- No direct Shell-to-Game close behavior.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not move foreground authority from SystemOS into firmware.
|
||||
- Do not change pause budget or suspend behavior.
|
||||
- Do not add UI affordances beyond the existing Hub game row selection.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Introduce a single resident Game resume helper.
|
||||
- What changes: create a private firmware method that performs the complete
|
||||
resident Game resume operation and returns the target `TaskId` or a typed
|
||||
failure.
|
||||
- How it changes: move the shared sequence currently duplicated across
|
||||
`resume_resident_game_from_home` and `HubHomeStep`: read resident task,
|
||||
call `LifecycleFacade::resume_task`, transition VM render ownership to
|
||||
`AppMode::Game`, install `GameRunningStep`, clear state initialization,
|
||||
and arm the input barrier.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
2. Route explicit resume through the helper.
|
||||
- What changes: `Firmware::resume_resident_game_from_home` becomes a thin
|
||||
wrapper around the centralized helper.
|
||||
- How it changes: preserve its public `bool` return contract for existing
|
||||
tests and call sites.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
3. Route Hub same-game selection through the helper.
|
||||
- What changes: `HubHomeStep` must no longer hand-roll resume task, render
|
||||
ownership, and input clearing.
|
||||
- How it changes: expose a state transition request that lets the firmware
|
||||
perform the centralized helper, or restructure the Hub action handling so
|
||||
the parent `Firmware` owns this transition. Keep `HubHomeStep` responsible
|
||||
only for recognizing that the selected cartridge matches the resident
|
||||
`app_id`.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`,
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`,
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware_state.rs` if a new
|
||||
transition variant is needed.
|
||||
|
||||
4. Keep different-game launch blocked under v1.
|
||||
- What changes: selecting a different `app_id` while a resident Game exists
|
||||
continues to log and remain in Hub.
|
||||
- How it changes: keep the existing warning behavior, but ensure it does not
|
||||
duplicate resume side effects.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`.
|
||||
|
||||
5. Update regression tests.
|
||||
- What changes: tests should prove both explicit resume and Hub same-game
|
||||
selection use the same observable transition.
|
||||
- How it changes: assert same `TaskId`, foreground owner restored to Game,
|
||||
pending resume lifecycle event exists before the next Game tick, delivered
|
||||
resume event after the Game tick, and input barrier suppresses held input.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] There is exactly one implementation of the resident Game resume sequence.
|
||||
- [ ] `Firmware::resume_resident_game_from_home` preserves its external
|
||||
behavior.
|
||||
- [ ] Hub selection of the same resident Game resumes the existing `TaskId`
|
||||
without creating or loading a new Game task.
|
||||
- [ ] The resume path always queues and delivers the Game lifecycle
|
||||
`ResumeForeground` event.
|
||||
- [ ] The resume path always barriers held Game input.
|
||||
- [ ] Selecting a different Game while one Game is resident remains blocked in
|
||||
v1.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit/integration tests in `prometeu-firmware` for explicit resume from Home.
|
||||
- Unit/integration tests in `prometeu-firmware` for Hub same-game selection
|
||||
after Home suspension.
|
||||
- Regression assertion that held input does not leak into the Game immediately
|
||||
after resume.
|
||||
- Run `cargo test -p prometeu-firmware resident_game_resume`.
|
||||
- Run `cargo test -p prometeu-firmware hub_home_clicking_resident_game`.
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_hub_home.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_state.rs`
|
||||
|
||||
## Risks
|
||||
|
||||
- The current step/state architecture gives `HubHomeStep` a `PrometeuContext`
|
||||
but not direct access to private `Firmware` fields. If a new transition
|
||||
variant is introduced, it must stay narrow and must not turn state steps into
|
||||
owners of lifecycle authority.
|
||||
- Duplicating less logic must not accidentally weaken the input barrier that was
|
||||
added for Hub-to-Game transitions.
|
||||
@@ -1,119 +0,0 @@
|
||||
---
|
||||
id: PLN-0146
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Consolidate Lifecycle Process Lookup Helpers
|
||||
status: open
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` depends on SystemOS lifecycle authority being internally
|
||||
consistent. The lifecycle facade now exposes both process state and process kind
|
||||
for a task so firmware can distinguish VM-backed Shell tasks from native Shell
|
||||
tasks. Both accessors repeat the same task-to-process lookup pattern.
|
||||
|
||||
The duplication is small, but this facade is now part of the foreground
|
||||
contract surface. Keeping lookup and error mapping in one place reduces the
|
||||
chance that future lifecycle accessors drift in behavior.
|
||||
|
||||
## Objective
|
||||
|
||||
Consolidate task-to-process lookup in `LifecycleFacade` behind one private
|
||||
helper, while preserving the public lifecycle facade behavior and errors.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Depends on the process/task authority from SystemOS lifecycle work.
|
||||
- Can be implemented independently of `PLN-0145` and `PLN-0147`.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Add one private helper that resolves a `TaskId` to its backing process.
|
||||
- Route `process_state_for_task` and `process_kind_for_task` through that
|
||||
helper.
|
||||
- Preserve `LifecycleError::TaskNotFound` and
|
||||
`LifecycleError::ProcessNotFound` behavior exactly.
|
||||
- Keep the current process/task manager ownership boundaries intact.
|
||||
- Keep the current non-architectural cleanup in `set_foreground_task` if it is
|
||||
still present in the working tree.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No new public process manager API.
|
||||
- No changes to task or process IDs.
|
||||
- No changes to Shell/Game lifecycle semantics.
|
||||
- No broader facade refactor outside lifecycle lookup.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not expose raw process manager access through SystemOS.
|
||||
- Do not change `ProcessKind` or `TaskKind` definitions.
|
||||
- Do not alter foreground stack behavior.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a private lifecycle lookup helper.
|
||||
- What changes: add a private function near `process_id_for_task` that
|
||||
returns a process reference for a `TaskId`.
|
||||
- How it changes: the helper should call `process_id_for_task`, then
|
||||
retrieve the process from `process_manager`, returning
|
||||
`LifecycleError::ProcessNotFound(process_id)` if the process is missing.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
2. Route state and kind accessors through the helper.
|
||||
- What changes: `LifecycleFacade::process_state_for_task` and
|
||||
`LifecycleFacade::process_kind_for_task` stop duplicating the process
|
||||
manager lookup.
|
||||
- How it changes: both methods call the helper and map the process reference
|
||||
to `ProcessState` or `ProcessKind`.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
3. Preserve existing foreground code cleanup.
|
||||
- What changes: keep `set_foreground_task` as an expression-returning match
|
||||
rather than using redundant `return` statements.
|
||||
- How it changes: ensure formatting and clippy stay clean.
|
||||
- File(s): `crates/console/prometeu-system/src/os/facades/lifecycle.rs`.
|
||||
|
||||
4. Tighten tests around lookup behavior.
|
||||
- What changes: extend or keep tests proving VM Shell and native Shell
|
||||
process kinds are observable through lifecycle.
|
||||
- How it changes: add missing-task and missing-process coverage only if the
|
||||
helper changes the observable path enough to justify it.
|
||||
- File(s): `crates/console/prometeu-system/src/os/system_os.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] `process_state_for_task` and `process_kind_for_task` share one private
|
||||
task-to-process lookup implementation.
|
||||
- [ ] Missing task and missing process errors remain unchanged.
|
||||
- [ ] Existing lifecycle tests continue to pass.
|
||||
- [ ] Firmware can still distinguish `ProcessKind::VmShell` from
|
||||
`ProcessKind::NativeShell`.
|
||||
- [ ] Clippy reports no warnings for the touched crates.
|
||||
|
||||
## Tests
|
||||
|
||||
- Unit tests in `prometeu-system` for shell process kind lookup.
|
||||
- Existing lifecycle missing task/process tests must continue to pass.
|
||||
- Run `cargo test -p prometeu-system lifecycle process_kind`.
|
||||
- Run `cargo test -p prometeu-firmware shell`.
|
||||
- Run `cargo clippy -p prometeu-system -p prometeu-firmware --all-targets -- -D warnings`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/os/facades/lifecycle.rs`
|
||||
- `crates/console/prometeu-system/src/os/system_os.rs`
|
||||
|
||||
## Risks
|
||||
|
||||
- Over-generalizing the helper could leak process manager concepts outside the
|
||||
lifecycle facade. Keep it private and narrowly typed.
|
||||
- This is intentionally small cleanup. It must not become a broad SystemOS
|
||||
facade redesign.
|
||||
@@ -1,144 +0,0 @@
|
||||
---
|
||||
id: PLN-0147
|
||||
ticket: foreground-stack-game-pause-shell-vm-backed
|
||||
title: Move Native Shell Profile Update Into Hub
|
||||
status: open
|
||||
created: 2026-07-04
|
||||
ref_decisions: [DEC-0037]
|
||||
tags: [runtime, os, lifecycle, shell, game, vm, foreground, architecture]
|
||||
---
|
||||
|
||||
## Briefing
|
||||
|
||||
`DEC-0037` says a suspended Game must not receive normal gameplay ticks while
|
||||
Hub or Shell owns foreground. A recent fix made `ShellRunningStep` branch on
|
||||
`ProcessKind`: VM-backed Shell tasks use the VM-backed shell profile path, while
|
||||
native Shell tasks call `PrometeuHub::gui_update` and `PrometeuHub::render`
|
||||
without ticking the VM.
|
||||
|
||||
That behavior is correct, but the native Shell update sequence now lives in
|
||||
firmware rather than in the Hub profile API. This duplicates part of
|
||||
`PrometeuHub::update_shell_profile` and creates a drift risk if Shell close,
|
||||
render, or input rules change later.
|
||||
|
||||
## Objective
|
||||
|
||||
Move native Shell profile updating into `PrometeuHub` so `ShellRunningStep`
|
||||
chooses the correct profile API without reimplementing Hub behavior.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Source decision: `DEC-0037`.
|
||||
- Depends on the `ProcessKind::VmShell` vs `ProcessKind::NativeShell`
|
||||
distinction available through `LifecycleFacade::process_kind_for_task`.
|
||||
- May be implemented before or after `PLN-0146`, but should use the consolidated
|
||||
lookup helper if `PLN-0146` has already landed.
|
||||
|
||||
## Scope
|
||||
|
||||
Included:
|
||||
|
||||
- Add a Hub-owned native Shell update API that does not tick the VM.
|
||||
- Keep VM-backed Shell update behavior in the existing VM-backed profile path.
|
||||
- Keep Shell close handling consistent between native and VM-backed Shells.
|
||||
- Keep native Shell rendering in the Hub/Shell UI path.
|
||||
- Keep firmware responsible for choosing which profile applies to the current
|
||||
Shell task.
|
||||
- Preserve regression coverage that a suspended resident Game does not advance
|
||||
while native Shell is foreground.
|
||||
|
||||
Excluded:
|
||||
|
||||
- No change to VM-backed Shell execution semantics.
|
||||
- No change to native Shell UI content.
|
||||
- No direct Shell close to Game.
|
||||
- No multiple foreground Shells.
|
||||
- No background Game ticking.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
- Do not move foreground lifecycle authority into `PrometeuHub`.
|
||||
- Do not make native Shells VM tasks.
|
||||
- Do not introduce a general scheduler abstraction.
|
||||
|
||||
## Execution Method
|
||||
|
||||
1. Add a native Shell profile update method on `PrometeuHub`.
|
||||
- What changes: create `update_native_shell_profile` or an equivalent
|
||||
clearly named method that returns `SystemProfileUpdate`.
|
||||
- How it changes: the method calls `gui_update`, maps Start input to
|
||||
`SystemProfileAction::CloseShell` when a shell window is focused, calls
|
||||
`render`, and always returns `crash: None`.
|
||||
- File(s):
|
||||
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
|
||||
|
||||
2. Keep the VM-backed Shell profile method explicitly VM-backed.
|
||||
- What changes: either keep `update_shell_profile` and document/name its VM
|
||||
tick behavior, or rename/split it if the codebase convention supports that
|
||||
without churn.
|
||||
- How it changes: ensure the VM-backed path is the only Hub profile update
|
||||
method that calls `os.vm().tick(...)`.
|
||||
- File(s):
|
||||
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`.
|
||||
|
||||
3. Simplify `ShellRunningStep`.
|
||||
- What changes: remove manual native Shell `gui_update`, Start handling, and
|
||||
render calls from firmware.
|
||||
- How it changes: branch on `ProcessKind` and call the appropriate Hub
|
||||
profile method; keep crash handling only for the VM-backed method.
|
||||
- File(s):
|
||||
`crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`.
|
||||
|
||||
4. Add Hub-level native profile tests.
|
||||
- What changes: prove native Shell profile update emits close on the close
|
||||
button and on Start, renders Shell UI, and does not tick the VM.
|
||||
- How it changes: use existing Hub/system test helpers where possible; assert
|
||||
VM tick index remains unchanged for native profile update.
|
||||
- File(s):
|
||||
`crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
|
||||
and/or `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
5. Preserve end-to-end regression coverage.
|
||||
- What changes: keep the Game -> Home -> native Shell test asserting that
|
||||
repeated Shell frames do not advance the resident Game VM tick index.
|
||||
- How it changes: rerun the firmware regression added for native Shell
|
||||
foreground.
|
||||
- File(s): `crates/console/prometeu-firmware/src/firmware/firmware.rs`.
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- [ ] Native Shell update behavior is owned by `PrometeuHub`, not hand-coded in
|
||||
`ShellRunningStep`.
|
||||
- [ ] The native Shell profile update never calls `os.vm().tick(...)`.
|
||||
- [ ] VM-backed Shell update remains the only Shell profile path that ticks the
|
||||
VM runtime.
|
||||
- [ ] Start and close-button Shell close behavior remains unchanged for native
|
||||
Shells.
|
||||
- [ ] A suspended resident Game receives no normal gameplay ticks while native
|
||||
Shell is foreground.
|
||||
|
||||
## Tests
|
||||
|
||||
- Hub-level tests for native Shell profile close behavior.
|
||||
- Hub-level or firmware-level tests proving native Shell profile update does not
|
||||
tick the VM.
|
||||
- Existing firmware regression for Game -> Home -> native Shell repeated frames.
|
||||
- Run `cargo test -p prometeu-system native_shell shell_profile`.
|
||||
- Run `cargo test -p prometeu-firmware game_home_shell_hub_same_game_flow`.
|
||||
- Run `cargo test -p prometeu-firmware`.
|
||||
- Run `cargo test -p prometeu-system`.
|
||||
- Run `discussion validate`.
|
||||
|
||||
## Affected Artifacts
|
||||
|
||||
- `crates/console/prometeu-system/src/programs/prometeu_hub/prometeu_hub.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware_step_shell_running.rs`
|
||||
- `crates/console/prometeu-firmware/src/firmware/firmware.rs`
|
||||
|
||||
## Risks
|
||||
|
||||
- Renaming the existing VM-backed shell profile method may create unnecessary
|
||||
churn. Prefer adding the native method and keeping call sites explicit unless
|
||||
the rename is small and clearly improves readability.
|
||||
- Hub APIs must remain UI/profile orchestration only; lifecycle close and task
|
||||
state changes still belong to firmware/SystemOS lifecycle.
|
||||
@@ -75,7 +75,9 @@ palette, host presentation, or compatibility contract.
|
||||
|
||||
### Published owned frame
|
||||
|
||||
The canonical worker-published frame value is `OwnedRgba8888Frame`.
|
||||
The canonical published frame value is `OwnedRgba8888Frame`. It is produced by
|
||||
either the local synchronous consumer or the asynchronous render worker; the
|
||||
consumer path does not change the frame contract.
|
||||
|
||||
`OwnedRgba8888Frame` contains:
|
||||
|
||||
@@ -184,6 +186,13 @@ producer path MUST remain non-blocking with respect to worker rasterization and
|
||||
host present. A slow worker can cause replacement/drop telemetry, but it MUST
|
||||
NOT create an unbounded queue or stall VM logical frame production.
|
||||
|
||||
A local synchronous consumer consumes the same immutable `RenderSubmission`
|
||||
through the same render backend and publishes the same canonical
|
||||
`OwnedRgba8888Frame` before returning. It does not use the asynchronous
|
||||
single-slot handoff and therefore does not weaken or reinterpret the worker's
|
||||
non-blocking producer contract. A host may select this path when an explicit
|
||||
synchronous observation boundary is part of its host contract.
|
||||
|
||||
### 4.4 Frame pacing
|
||||
|
||||
Game logical frames are paced by the runtime frame scheduler, not by render
|
||||
@@ -625,7 +634,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
|
||||
|
||||
@@ -640,7 +650,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
|
||||
|
||||
---
|
||||
|
||||
@@ -649,7 +660,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
|
||||
@@ -667,6 +678,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
|
||||
@@ -766,6 +780,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`
|
||||
@@ -774,7 +790,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
|
||||
@@ -797,4 +813,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.
|
||||
|
||||
@@ -128,12 +128,61 @@ SystemOS resume request
|
||||
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 Render Worker Concurrency
|
||||
## 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
|
||||
@@ -160,7 +209,7 @@ 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.
|
||||
|
||||
## 9 Async Asset and IO Work Lane
|
||||
## 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
|
||||
@@ -184,7 +233,7 @@ 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.
|
||||
|
||||
## 10 Determinism and Best Practices
|
||||
## 11 Determinism and Best Practices
|
||||
|
||||
PROMETEU encourages:
|
||||
|
||||
@@ -199,7 +248,7 @@ PROMETEU discourages:
|
||||
- hidden timing channels;
|
||||
- ambiguous out-of-band execution.
|
||||
|
||||
## 11 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
|
||||
@@ -76,6 +81,25 @@ When the host activates instruction-level inspection, it may observe:
|
||||
- operand stack
|
||||
- call stack
|
||||
|
||||
### 3.3 Debugger and Headless Semantic Alignment
|
||||
|
||||
Interactive debugging and deterministic headless automation share runtime
|
||||
meanings even though their transports and pacing differ:
|
||||
|
||||
| Runtime meaning | Debugger command/observation | Headless operation |
|
||||
| --- | --- | --- |
|
||||
| Pause active VM execution | `pause` | `pause()` |
|
||||
| Resume active VM execution | `resume` | `resume()` |
|
||||
| Execute one VM instruction and remain paused | `step` | `step()` |
|
||||
| Complete one logical frame and remain paused | `stepFrame` | `advance_frame()` |
|
||||
| Read overlapping execution state | `getState` | `get_state()` |
|
||||
| Observe structured current fault | event/current state | `get_fault()` |
|
||||
| Inject normalized input | not defined by the debugger protocol | `set_input()` |
|
||||
| Reset the machine execution | not defined by the debugger protocol | `reset()` |
|
||||
| Capture the canonical published frame | not defined by the debugger protocol | `capture_frame()` |
|
||||
|
||||
The headless API does not define or extend an external automation protocol.
|
||||
|
||||
## 4 State Inspection Boundary
|
||||
|
||||
Detailed state inspection is a host-owned concern. The runtime may expose deterministic machine state to host tooling, but this chapter does not define a general guest ABI for introspection convenience.
|
||||
|
||||
@@ -118,8 +118,8 @@ Hardware differences:
|
||||
The graphics system:
|
||||
|
||||
- produces typed logical render submissions that render to RGBA8888 output
|
||||
- may consume Game submissions through a render worker that publishes owned
|
||||
`OwnedRgba8888Frame` values
|
||||
- consumes Game submissions through either a local synchronous consumer or a
|
||||
render worker, both of which publish owned `OwnedRgba8888Frame` values
|
||||
- uses an indexed palette
|
||||
- does not depend on a specific GPU
|
||||
|
||||
@@ -128,8 +128,8 @@ The platform layer:
|
||||
- exposes typed service facades for render submission, render backend
|
||||
execution, Game 2D composition, input, audio, assets, and telemetry
|
||||
- consumes closed render submissions through a render-surface implementation
|
||||
- transports published RGBA8888 output or worker-published
|
||||
`OwnedRgba8888Frame` pixels into a host presentation surface without
|
||||
- transports published `OwnedRgba8888Frame` pixels into a host presentation
|
||||
surface without
|
||||
injecting host-owned debug overlay pixels
|
||||
- is the runtime-facing portability boundary; runtime and firmware code must not
|
||||
depend on a monolithic hardware bridge or on a concrete hardware aggregate
|
||||
@@ -216,3 +216,72 @@ PROMETEU promises:
|
||||
|
||||
- **identical logical behavior**
|
||||
- **reproducible technical decisions**
|
||||
|
||||
## 13 Deterministic Headless Control
|
||||
|
||||
The headless host is a separate, generic Prometeu host for in-process
|
||||
automation. It runs the same directory cartridge, firmware, active VM session,
|
||||
capability checks, normalized input, render submissions, and fault model as an
|
||||
interactive host. A cartridge cannot detect or request headless execution, and
|
||||
headless execution grants no additional guest capability.
|
||||
|
||||
The headless host requires no native window, display server, physical input,
|
||||
physical audio device, or realtime frame pacing. It uses the explicit local
|
||||
synchronous Game render consumer. A successful logical-frame advance returns
|
||||
only after the exact canonical `OwnedRgba8888Frame` for that advance has been
|
||||
published. It does not start or wait for an asynchronous render worker, and
|
||||
publication correctness does not use spinning, yielding, sleeping, or a
|
||||
wall-clock timeout.
|
||||
|
||||
### 13.1 Control contract
|
||||
|
||||
- `boot(path)` loads a normal directory cartridge and stops on entry to
|
||||
`GameRunning`, before the first game instruction. A second boot attempt
|
||||
requires `reset()` and otherwise returns `AlreadyBooted`.
|
||||
- `reset()` enters the normal firmware reset boundary and clears input, active
|
||||
sessions, structured faults, and headless frame correlation. Capture is
|
||||
unavailable until the new run completes a frame.
|
||||
- `pause()` and `resume()` control the active VM session. `step()` executes one
|
||||
VM instruction and finishes paused without reporting a completed logical
|
||||
frame.
|
||||
- `set_input()` retains one complete `InputSignals` snapshot, including the
|
||||
digital pad and touch signal/coordinates. `clear_input()` restores its
|
||||
default. The normal begin-frame input sampling defined by the input
|
||||
peripheral derives `pressed`, `released`, `down`, and `hold` state.
|
||||
- `advance_frame()` advances internal firmware ticks until exactly one logical
|
||||
frame closes through `FrameSync` or `EndOfRom`, or until a structured fault or
|
||||
lifecycle termination prevents completion. Internal cycle-slice exhaustion
|
||||
continues the same frame; it is not itself a frame boundary.
|
||||
- `advance_frames(n)` is repeated `advance_frame()`. It reports the requested
|
||||
and completed counts plus completed-all, fault, or termination. Zero is a
|
||||
no-op; fault or termination preserves partial completed progress.
|
||||
- A frame advance finishes paused. Guest faults are outcomes represented by
|
||||
`CrashReport`; host precondition, publication, and safety-limit failures are
|
||||
host errors.
|
||||
- `capture_frame()` returns an owned clone of the canonical frame paired with
|
||||
the latest successful advance. The explicit `{logical_frame_index, FrameId}`
|
||||
pair is authoritative; no numeric equality or fixed offset is implied.
|
||||
- `get_state()` classifies execution as running, paused, terminated, or faulted
|
||||
and exposes the overlapping debugger state. `get_fault()` returns structured
|
||||
`CrashReport` data rather than requiring log or summary parsing.
|
||||
- Valid audio commands pass through normal runtime semantics. The headless host
|
||||
drains them into a null/discard sink; it does not synthesize PCM or require an
|
||||
output device.
|
||||
|
||||
### 13.2 Deterministic oracle
|
||||
|
||||
Deterministic comparison includes the logical-frame index and paired `FrameId`,
|
||||
canonical framebuffer pixels (or a stable pixel hash) and dimensions/stride,
|
||||
guest-visible PC/stack/app state, structured execution status and fault data,
|
||||
and deterministic counters describing simulated execution.
|
||||
|
||||
The oracle excludes wall-clock or boot-time timestamps, real elapsed duration,
|
||||
host CPU time, thread-scheduling measurements, presentation cadence,
|
||||
render-worker timing telemetry, and host-owned identities without simulated
|
||||
machine meaning. The same cartridge, initial machine state, and per-frame input
|
||||
timeline must produce the same included observations on independent runs and
|
||||
after reset.
|
||||
|
||||
AI tooling may consume this generic host API from outside the machine. It does
|
||||
not create an AI mode, testing mode, replay protocol, gameplay introspection
|
||||
surface, or guest capability.
|
||||
|
||||
@@ -43,6 +43,9 @@ The VM does not own the machine lifecycle. Firmware does.
|
||||
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
|
||||
@@ -50,13 +53,18 @@ The VM does not own the machine lifecycle. Firmware does.
|
||||
- **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;
|
||||
@@ -68,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:
|
||||
@@ -79,6 +91,8 @@ PrometeuHub is responsible for:
|
||||
- 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.
|
||||
|
||||
@@ -204,19 +218,82 @@ 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`.
|
||||
|
||||
When Home launches a discovered Game entry, the request is a system-owned action
|
||||
@@ -229,6 +306,16 @@ 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:
|
||||
@@ -239,6 +326,7 @@ 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.
|
||||
@@ -286,8 +374,13 @@ Expected behavior:
|
||||
- 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
|
||||
|
||||
|
||||
@@ -186,6 +186,9 @@ For the v1 Home games library:
|
||||
- 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.
|
||||
@@ -193,6 +196,11 @@ For the v1 Home games 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.
|
||||
|
||||
@@ -50,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.
|
||||
|
||||
@@ -95,15 +97,24 @@ The v1 games root contract is:
|
||||
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 part of this boot
|
||||
profile. That orchestration belongs to the foreground/home and cartridge switch
|
||||
contracts.
|
||||
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:
|
||||
@@ -147,6 +158,10 @@ Direct single-cartridge boot remains a separate validation path:
|
||||
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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -65,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:
|
||||
|
||||
```
|
||||
@@ -187,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)`
|
||||
|
||||
@@ -50,6 +50,12 @@
|
||||
"paths": [
|
||||
"crates/host/prometeu-host-desktop-winit/src/"
|
||||
]
|
||||
},
|
||||
"host/headless": {
|
||||
"baseline_percent": 80,
|
||||
"paths": [
|
||||
"crates/host/prometeu-host-headless/src/"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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.
|
||||
@@ -0,0 +1,9 @@
|
||||
{
|
||||
"magic": "PMTU",
|
||||
"cartridge_version": 1,
|
||||
"app_id": 2,
|
||||
"title": "Dummy Boy",
|
||||
"app_version": "0.1.0",
|
||||
"app_mode": "Game",
|
||||
"capabilities": ["gfx2d"]
|
||||
}
|
||||
Binary file not shown.
Binary file not shown.
Reference in New Issue
Block a user