feat(audio): add guest voice controls and reliable lifecycle delivery
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good

This commit is contained in:
2026-10-14 09:08:27 +01:00
parent 3899b7f12c
commit e0e01ed1de
23 changed files with 1442 additions and 482 deletions
@@ -3,7 +3,7 @@ use crate::fs::{FsState, VirtualFS};
use crate::services::memcard::MemcardService;
use prometeu_bytecode::{TRAP_INVALID_SYSCALL, TRAP_OOB, TRAP_TYPE, Value};
use prometeu_hal::app_mode::AppMode;
use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType, SlotRef};
use prometeu_hal::asset::{AssetId, AssetOpStatus, BankType};
use prometeu_hal::color::Color;
use prometeu_hal::glyph::Glyph;
use prometeu_hal::log::{LogLevel, LogSource};
@@ -495,15 +495,17 @@ impl NativeInterface for VmRuntimeHost<'_> {
Ok(())
}
Syscall::AudioPlay => {
let bank_id = expect_int(args, 0)? as u8;
let bank_id_raw = expect_int(args, 0)?;
let sample_id_raw = expect_int(args, 1)?;
let voice_id_raw = expect_int(args, 2)?;
let volume_raw = expect_int(args, 3)?;
let pan_raw = expect_int(args, 4)?;
let pitch = expect_number(args, 5, "pitch")?;
let loop_mode = match expect_int(args, 6)? {
0 => prometeu_hal::LoopMode::Off,
_ => prometeu_hal::LoopMode::On,
let loop_raw = expect_int(args, 6)?;
let loop_mode = if loop_raw == 0 {
prometeu_hal::LoopMode::Off
} else {
prometeu_hal::LoopMode::On
};
if !(0..16).contains(&voice_id_raw) {
@@ -511,18 +513,18 @@ impl NativeInterface for VmRuntimeHost<'_> {
return Ok(());
}
if platform.assets().slot_info(SlotRef::audio(bank_id as usize)).asset_id.is_none()
{
if !(0..16).contains(&bank_id_raw) {
ret.push_int(AudioOpStatus::BankInvalid as i64);
return Ok(());
}
let bank_id = bank_id_raw as u8;
if sample_id_raw < 0
|| sample_id_raw > u16::MAX as i64
|| !(0..=255).contains(&volume_raw)
|| !(0..=255).contains(&pan_raw)
|| !pitch.is_finite()
|| pitch <= 0.0
|| !(0..=1).contains(&loop_raw)
{
ret.push_int(AudioOpStatus::ArgRangeInvalid as i64);
return Ok(());
@@ -541,6 +543,38 @@ impl NativeInterface for VmRuntimeHost<'_> {
ret.push_int(status as i64);
Ok(())
}
Syscall::AudioStop
| Syscall::AudioSetVolume
| Syscall::AudioSetPan
| Syscall::AudioSetPitch => {
let voice = expect_int(args, 0)?;
// Decode all types before reporting operational validation failures.
let value = match syscall {
Syscall::AudioSetVolume | Syscall::AudioSetPan => expect_int(args, 1)?,
_ => 0,
};
let pitch = if syscall == Syscall::AudioSetPitch {
expect_number(args, 1, "pitch")?
} else {
1.0
};
let status = if !(0..16).contains(&voice) {
AudioOpStatus::VoiceInvalid
} else if !(0..=255).contains(&value) || !pitch.is_finite() || pitch <= 0.0 {
AudioOpStatus::ArgRangeInvalid
} else {
let audio = platform.audio_mut();
match syscall {
Syscall::AudioStop => audio.stop(voice as usize),
Syscall::AudioSetVolume => audio.set_volume(voice as usize, value as u8),
Syscall::AudioSetPan => audio.set_pan(voice as usize, value as u8),
Syscall::AudioSetPitch => audio.set_pitch(voice as usize, pitch),
_ => unreachable!(),
}
};
ret.push_int(status as i64);
Ok(())
}
Syscall::FsOpen => {
let path = expect_string(args, 0, "path")?;
if *self.fs_state != FsState::Mounted {
@@ -1602,3 +1602,6 @@ fn tick_composer_emit_sprite_type_mismatch_surfaces_trap_not_panic() {
}
assert!(matches!(runtime.last_crash_report, Some(CrashReport::VmTrap { .. })));
}
#[path = "tests_audio.rs"]
mod audio_controls;
@@ -0,0 +1,218 @@
use super::*;
use prometeu_drivers::{AudioCommand, AudioTransport};
struct Harness {
runtime: VirtualMachineRuntime,
vm: VirtualMachine,
platform: TestPlatform,
log: LogService,
fs: VirtualFS,
fs_state: FsState,
memcard: MemcardService,
files: HashMap<u32, String>,
next: u32,
}
impl Harness {
fn new(code: &str, name: &str, args: u16) -> Self {
let mut runtime = VirtualMachineRuntime::new(None);
let mut vm = VirtualMachine::default();
let mut log = LogService::new(4096);
let program = serialized_single_function_module(
assemble(code).unwrap(),
vec![SyscallDecl {
module: "audio".into(),
name: name.into(),
version: 1,
arg_slots: args,
ret_slots: 1,
}],
);
runtime
.initialize_vm(&mut log, &mut vm, &cartridge_with_program(program, caps::AUDIO))
.unwrap();
Self {
runtime,
vm,
log,
platform: TestPlatform::new(),
fs: VirtualFS::new(),
fs_state: FsState::Unmounted,
memcard: MemcardService::new(),
files: HashMap::new(),
next: 1,
}
}
fn tick(&mut self) -> Option<CrashReport> {
self.runtime.tick(
&mut self.log,
&mut self.fs,
&mut self.fs_state,
&mut self.memcard,
&mut self.files,
&mut self.next,
&mut self.vm,
&InputSignals::default(),
&mut self.platform,
)
}
fn transport(&self) -> AudioTransport {
self.platform.local_hardware().audio.transport()
}
fn step(&mut self) -> Option<CrashReport> {
self.runtime.debug_step_instruction(
&mut self.log,
&mut self.fs,
&mut self.fs_state,
&mut self.memcard,
&mut self.files,
&mut self.next,
&mut self.vm,
&mut self.platform,
)
}
}
#[test]
fn guest_audio_status_matrix_and_type_traps() {
for (name, args, inputs, expected) in [
("stop", 1, "PUSH_I32 0", 0),
("stop", 1, "PUSH_I32 15", 0),
("stop", 1, "PUSH_I32 -1", 1),
("stop", 1, "PUSH_I32 16", 1),
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 0", 0),
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 255", 0),
("set_volume", 2, "PUSH_I32 0\nPUSH_I32 256", 3),
("set_pan", 2, "PUSH_I32 0\nPUSH_I32 -1", 3),
("set_pan", 2, "PUSH_I32 16\nPUSH_I32 -1", 1),
("set_pan", 2, "PUSH_I32 15\nPUSH_I32 255", 0),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 1", 0),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 0", 3),
("set_pitch", 2, "PUSH_I32 0\nPUSH_I32 -1", 3),
(
"play",
7,
"PUSH_I32 256\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 255\nPUSH_I32 0\nPUSH_I32 1\nPUSH_I32 0",
6,
),
] {
let mut h = Harness::new(&format!("{inputs}\nHOSTCALL 0\nFRAME_SYNC\nHALT"), name, args);
assert!(h.tick().is_none(), "{name}: {inputs}");
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(expected)], "{name}: {inputs}");
let batch = h.transport().try_take().unwrap().frame;
assert_eq!(batch.map_or(0, |v| v.len()), usize::from(expected == 0));
}
for name in ["set_volume", "set_pan", "set_pitch"] {
let mut h = Harness::new("PUSH_I32 -1\nPUSH_BOOL 1\nHOSTCALL 0\nFRAME_SYNC\nHALT", name, 2);
assert!(matches!(h.tick(), Some(CrashReport::VmTrap { .. })));
assert!(h.transport().try_take().unwrap().frame.is_none());
}
}
#[test]
fn frame_publication_backpressure_abort_and_debug_steps() {
let mut h = Harness::new(
"PUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nPUSH_I32 1\nHOSTCALL 0\nFRAME_SYNC\nHALT",
"stop",
1,
);
assert!(h.tick().is_none());
let pc = h.vm.pc();
assert!(h.tick().is_none());
assert_eq!(h.vm.pc(), pc, "pending batch stalls guest");
let batch = h.transport().try_take().unwrap().frame.unwrap();
assert!(matches!(batch[0], AudioCommand::Stop { voice_id: 0 }));
assert!(h.tick().is_none());
assert!(matches!(
h.transport().try_take().unwrap().frame.unwrap()[0],
AudioCommand::Stop { voice_id: 1 }
));
for end in ["HALT", "PUSH_BOOL 1\nHOSTCALL 0\nHALT"] {
let mut h = Harness::new(&format!("PUSH_I32 0\nHOSTCALL 0\n{end}"), "stop", 1);
let _ = h.tick();
h.platform.audio_mut().finish_frame();
assert!(h.transport().try_take().unwrap().frame.is_none(), "abort cancels admitted stop");
}
let mut h = Harness::new("PUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nHALT", "stop", 1);
assert!(h.step().is_none());
assert!(h.step().is_none());
assert!(h.transport().try_take().unwrap().frame.is_none());
// Switching from stepping to running must preserve previously staged commands.
assert!(h.tick().is_none());
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
#[test]
fn guest_quota_is_deterministic_and_resets_on_next_frame() {
let repeated = "PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\n".repeat(1024);
let mut h = Harness::new(
&format!(
"{repeated}PUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nPUSH_I32 0\nHOSTCALL 0\nFRAME_SYNC\nHALT"
),
"stop",
1,
);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(7)]);
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1024);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(0)]);
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
#[test]
fn guest_play_validates_raw_bank_loop_and_preserves_both_play_forms() {
use prometeu_drivers::SoundBankPoolInstaller;
use prometeu_hal::{sample::Sample, sound_bank::SoundBank};
for (bank, loop_mode, expected) in
[(0, 0, 0), (0, 1, 0), (0, -1, 3), (0, 2, 3), (256, 0, 6), (-256, 0, 6), (16, 0, 6)]
{
let mut h = Harness::new(
&format!(
"PUSH_I32 {bank}\nPUSH_I32 0\nPUSH_I32 0\nPUSH_I32 255\nPUSH_I32 127\nPUSH_I32 1\nPUSH_I32 {loop_mode}\nHOSTCALL 0\nFRAME_SYNC\nHALT"
),
"play",
7,
);
let banks = Arc::new(MemoryBanks::new());
banks.install_sound_bank(
0,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![1, 2, 3]))])),
);
h.platform = TestPlatform::new_with_memory_banks(banks);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(expected)]);
let batch = h.transport().try_take().unwrap().frame;
assert_eq!(batch.map_or(0, |v| v.len()), usize::from(expected == 0));
}
let mut h = Harness::new(
"PUSH_I32 0\nPUSH_I32 0\nPUSH_I32 255\nPUSH_I32 127\nPUSH_I32 1\nHOSTCALL 0\nFRAME_SYNC\nHALT",
"play_sample",
5,
);
let banks = Arc::new(MemoryBanks::new());
banks.install_sound_bank(
0,
Arc::new(SoundBank::new(vec![Arc::new(Sample::new(48_000, vec![1]))])),
);
h.platform = TestPlatform::new_with_memory_banks(banks);
assert!(h.tick().is_none());
assert_eq!(h.vm.operand_stack_top(1), vec![Value::Int64(0)]);
assert!(matches!(
h.transport().try_take().unwrap().frame.unwrap()[0],
AudioCommand::Play { loop_mode: prometeu_hal::LoopMode::Off, .. }
));
}
#[test]
fn normal_entry_return_is_a_successful_implicit_audio_frame() {
let mut h = Harness::new("PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\nRET", "stop", 1);
for _ in 0..2 {
assert!(h.tick().is_none());
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
let mut h = Harness::new("PUSH_I32 0\nHOSTCALL 0\nPOP_N 1\nRET", "stop", 1);
for _ in 0..4 {
assert!(h.step().is_none());
}
assert_eq!(h.transport().try_take().unwrap().frame.unwrap().len(), 1);
}
@@ -82,14 +82,21 @@ impl VirtualMachineRuntime {
vm: &mut VirtualMachine,
platform: &mut dyn RuntimePlatform,
) -> Option<CrashReport> {
if !platform.audio().ready() {
return None;
}
if vm.memcard_boot_result() == Some(0) && memcard.session.boot_pending() {
return None;
}
let was_memcard_boot = vm.memcard_boot_active();
if was_memcard_boot {
platform.audio_mut().begin_lifecycle();
}
if vm.call_stack_is_empty()
&& let Err(error) = vm.prepare_boot_call()
{
let report = CrashReport::VmInit { error };
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -106,6 +113,15 @@ impl VirtualMachineRuntime {
};
vm.step(&mut host, &mut ctx)
};
// run_budget derives these terminal reasons after executing an instruction;
// single stepping must observe the same publication/cancellation boundary.
let step_result = if step_result.is_ok() && vm.is_halted() {
Err(LogicalFrameEndingReason::Halted)
} else if step_result.is_ok() && !was_memcard_boot && vm.call_stack_is_empty() {
Err(LogicalFrameEndingReason::EndOfRom)
} else {
step_result
};
if was_memcard_boot
&& step_result == Err(LogicalFrameEndingReason::LifecycleComplete)
@@ -119,9 +135,33 @@ impl VirtualMachineRuntime {
message: format!("Memcard bootstrap failed: {error:?}: {}", memcard.diagnostic),
pc: Some(vm.pc() as u32),
};
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
if was_memcard_boot {
match &step_result {
Err(LogicalFrameEndingReason::LifecycleComplete) => {
platform.audio_mut().finish_lifecycle(true)
}
Err(
LogicalFrameEndingReason::Trap(_)
| LogicalFrameEndingReason::Panic(_)
| LogicalFrameEndingReason::Halted,
) => platform.audio_mut().finish_lifecycle(false),
_ => {}
}
}
match &step_result {
Err(LogicalFrameEndingReason::FrameSync | LogicalFrameEndingReason::EndOfRom) => {
platform.audio_mut().finish_frame()
}
Err(LogicalFrameEndingReason::Halted) => platform.audio_mut().reset(),
Err(LogicalFrameEndingReason::Trap(_) | LogicalFrameEndingReason::Panic(_)) => {
platform.audio_mut().abort_frame()
}
_ => {}
}
match step_result {
Ok(())
| Err(
@@ -141,6 +181,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
format!("PVM Fault during Step: {}", report),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
Some(report)
}
@@ -153,6 +194,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
format!("PVM Fault during Step: {}", report),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
Some(report)
}
@@ -176,6 +218,10 @@ impl VirtualMachineRuntime {
if self.paused && !single_step && !self.debug_step_request {
return LogicalFrameEndingReason::Breakpoint;
}
if !platform.audio().lifecycle_ready() {
return LogicalFrameEndingReason::BudgetExhausted;
}
platform.audio_mut().begin_lifecycle();
let result = catch_unwind(AssertUnwindSafe(|| {
let mut ctx = HostContext::new_platform(Some(platform));
let mut host = VmRuntimeHost {
@@ -200,6 +246,16 @@ impl VirtualMachineRuntime {
let reason = result.unwrap_or_else(|payload| {
LogicalFrameEndingReason::Panic(Self::host_panic_payload_to_string(payload))
});
match &reason {
LogicalFrameEndingReason::LifecycleComplete => {
platform.audio_mut().finish_lifecycle(true)
}
LogicalFrameEndingReason::BudgetExhausted | LogicalFrameEndingReason::Breakpoint => {}
_ => {
platform.audio_mut().finish_lifecycle(false);
platform.audio_mut().abort_frame();
}
}
if reason == LogicalFrameEndingReason::Breakpoint || single_step || self.debug_step_request
{
self.paused = true;
@@ -255,6 +311,7 @@ impl VirtualMachineRuntime {
}),
};
if let Some(report) = &failure {
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
}
return failure;
@@ -277,6 +334,9 @@ impl VirtualMachineRuntime {
return None;
}
if !platform.audio().ready() {
return None;
}
self.update_fs(log_service, fs, fs_state);
if !self.logical_frame_active {
if RenderManager::policy_for_app_mode(self.current_cartridge_app_mode)
@@ -293,6 +353,7 @@ impl VirtualMachineRuntime {
if self.needs_prepare_entry_call || vm.call_stack_is_empty() {
if let Err(error) = vm.prepare_boot_call() {
let report = CrashReport::VmInit { error };
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -341,6 +402,9 @@ impl VirtualMachineRuntime {
self.atomic_telemetry.cycles_used.fetch_add(run.cycles_used, Ordering::Relaxed);
self.atomic_telemetry.vm_steps.fetch_add(run.steps_executed, Ordering::Relaxed);
if run.reason == LogicalFrameEndingReason::Halted {
platform.audio_mut().reset();
}
if run.reason == LogicalFrameEndingReason::Breakpoint {
self.paused = true;
self.debug_step_request = false;
@@ -363,6 +427,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
report.summary(),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -376,6 +441,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
report.summary(),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -500,6 +566,8 @@ impl VirtualMachineRuntime {
log_service.reset_count();
// Entry return is the runtime's successful implicit frame end.
platform.audio_mut().finish_frame();
self.logical_frame_index += 1;
self.logical_frame_active = false;
self.logical_frame_remaining_cycles = 0;
@@ -532,6 +600,7 @@ impl VirtualMachineRuntime {
report.log_tag(),
report.summary(),
);
platform.audio_mut().abort_frame();
self.last_crash_report = Some(report.clone());
return Some(report);
}
@@ -582,7 +651,7 @@ impl VirtualMachineRuntime {
platform: &mut dyn RuntimePlatform,
) {
platform.game2d_frame_composer().begin_frame();
platform.audio_mut().clear_commands();
platform.audio_mut().begin_frame();
self.logs_written_this_frame.clear();
}
}