Files
prometeu-runtime/docs/vm-arch/audio-callback-qualification.md
T
bquarkz 39468740c3
Intrepid/Prometeu/Runtime/pipeline/pr-master There was a failure building this commit
docs: close runtime quality review with consolidated lesson
2026-10-14 14:24:14 +01:00

122 lines
7.2 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.
## Production decode and save pressure
A complementary release observation on 2026-10-14 used the same 1,000-callback,
16-voice synthetic harness while a separate process repeatedly ran
`qualify_file_commits_with_production_asset_decoder` from `prometeu-system`.
Each pressure round performs twenty production glyph loads and durable 64-KiB
FileMemcard commits. Fourteen rounds completed successfully during the audio
process interval. The two test binaries were built before measurement; a worker
started the first pressure process before audio and repeated it until audio
exited, then joined the final invocation. Monotonic process intervals confirm
concurrency in the [measurement record](audio-production-pressure-qualification.json).
Callback p50/p95/p99/max were 14.542/97.667/399.041/1,070.708 microseconds for the
nominal 5,333.333-microsecond period. Allocation and deallocation counts remained
zero; sixteen live sample owners became zero after teardown. All test processes
exited successfully. The record identifies the committed source, toolchain,
per-round save observations and the additional policy tests running on the host.
This measures host contention between processes, not an integrated console
session or a physical callback under this exact workload. The previously named
physical-device observation remains separate. The pressure fixture alternates
loads and saves; deterministic production-decoder tests establish save preemption
during decoding. None of these host-specific maxima is a real-time guarantee.