Files
prometeu-runtime/docs/vm-arch/audio-callback-qualification.md
T

98 lines
5.7 KiB
Markdown

# Desktop audio callback qualification
The desktop callback moves discarded Sample references and command-vector owners
into two preallocated return packets. Host service reclaims them outside the data
callback. Logical playback completion does not imply immediate physical release.
The [audio peripheral contract](../specs/runtime/05-audio-peripheral.md) is normative.
## Capacity and ownership proof
One publication can contain 1,024 frame commands and a combined 2,048-command
lifecycle batch. Each command introduces at most one Sample reference, and the
mixer starts with at most sixteen. Therefore at most 3,088 Sample owners can retire
in one callback, even if every command replaces a voice and every resulting voice
finishes immediately. Each packet reserves that reference capacity plus two vector
slots before starting the stream. Stale command references remain in the returned
vectors instead of moving into the retired-reference vector.
Exactly two packets circulate through capacity-two SPSC lanes. While the callback
owns a packet, no more than one other packet can occupy the return lane. Enqueue
therefore needs no waiting, resizing or overflow disposal. Symmetrically, service
can always return a reclaimed packet to the free lane. If both packets await service,
the callback leaves publications untouched. Up to sixteen naturally completed
voices retain owners in their existing slots, becoming silent until reclamation
capacity returns. PCM content can be large; this is a bound on references and fixed
metadata, not an additional PCM byte quota.
Service clears retired references, clears commands and caches at most four empty
command vectors for producer reuse. It runs before guest attempts and during pause
or backpressure. Stream stop/drop precedes silent-consumer takeover. No additional
reclamation worker or playback mirror is introduced.
## Allocation and semantic evidence
`tests/audio_callback_allocations.rs` installs a thread-local allocator counter.
Only runtime callback execution is counted; fixture construction, I/O, reporting,
service reclamation and teardown run outside that region. It counts alloc,
alloc_zeroed, realloc and dealloc (realloc contributes to both counters).
The original last-owner natural completion made zero allocations and two
deallocations; applying a control batch freed one vector. After the change,
debug and release counters report zero allocations/deallocations for natural
completion, all controls, repeated play/stop/replacement, pause, epoch reset,
empty samples, bank unload, 16-voice completion without a packet, ten starved
callbacks and recovery. The saturation case combines 3,072 Play commands with
sixteen existing voices and completion, exercising the full 3,088-owner bound.
Weak-reference assertions prove retention until service and final release.
Unit tests additionally check stale-vector identity and deferred release, 1,000
pool recycling cycles, vector-allocation reuse, bounded empty-buffer caching,
failed/stalled stream takeover and teardown. Existing exact PCM tests retain
one-shot tails, loop seams, fractional interpolation, FIFO/prefix order and pause
position. Runtime audio controls and headless tests retain their logical admission
behavior; the Rust silent-consumer interface remains unchanged.
Reproduce allocation qualification with:
```sh
cargo test -p prometeu-host-desktop-winit --test audio_callback_allocations -- --nocapture
cargo test --release -p prometeu-host-desktop-winit --test audio_callback_allocations -- --nocapture
```
## Timing observations
Executed on 2026-10-14, macOS/aarch64, rustc 1.98.1, release profile. Both workloads
used sixteen voices and 256 stereo frames at 48 kHz (nominal period 5.333 ms).
The explicitly named pressure workload reads the checked-in stress-console asset
pack and writes a temporary 1 MiB file through HostDirBackend. It does not execute
guest asset decoding or the memcard save scheduler; it is not a substitute for a
separate full integration workload.
| Workload | Callbacks | I/O cycles | p50 | p95 | p99 | Maximum |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| Synthetic callback invocation, interleaved I/O | 1,000 | 1,000 | 13.791 µs | 30.458 µs | 54.292 µs | 72.166 µs |
| MacBook Pro Speakers, concurrent main-thread I/O | 375 | 273 | 11.458 µs | 12.875 µs | 15.916 µs | 30.458 µs |
Both observed zero runtime allocator calls and sixteen live Sample owners before
teardown, zero afterward. Physical buffers were observed at exactly 256 frames.
Timing includes the runtime render call and counter overhead, excludes I/O and
CPAL/device internals, and does not measure device presentation latency. No timing
threshold is asserted. These are local observations, not cross-device certification.
Explicit commands (both timing tests are ignored by ordinary CI):
```sh
cargo test --release -p prometeu-host-desktop-winit --test audio_callback_allocations callback_duration_16_voices_with_io_pressure -- --ignored --exact --nocapture
cargo test --release -p prometeu-host-desktop-winit --test audio_callback_allocations physical_callback_duration_16_voices_with_io_pressure -- --ignored --exact --nocapture
cargo test -p prometeu-host-desktop-winit --lib audio::control_tests::desktop_audio_device_smoke -- --ignored --exact --nocapture
```
The ordinary physical smoke passed on retry. The first sandboxed attempt could
not open the device; the first unrestricted attempt received no callbacks and
triggered the existing two-second watchdog. Those failures remain part of the
qualification evidence and demonstrate why successful local timing is not an
availability guarantee. No human listening assessment is claimed.
Strict host Clippy passes. Repository-wide strict-gate status remains separate
from these behavioral and device observations.