A11a: the ALSA bridge becomes an instrument, with its report

[tap]

What this changes

This is the first of three PRs for the roadmap's A11, the harness Block B's bench runs. It changes the ALSA bridge (async/examples/alsa_bridge.cpp), adds a CSV report script, and makes both CI-proven on Linux.

The bridge:

• hw: devices only. --in and --out are now required, and a plugin device (default, plughw:, dmix) is refused before anything is opened.
• Per-device counters. Each audio thread counts its cumulative frames and its ALSA xruns (-EPIPE), kept apart from its other recoveries.
• Hardware timestamps. Both devices timestamp every pointer update on CLOCK_MONOTONIC_RAW. After each transfer the thread publishes the last one (snd_pcm_htimestamp) as the frames the hardware had moved at that instant, through a sequence counter. A driver without timestamps leaves those fields empty.
• --csv now writes rather than appends. Each per-second row holds:
  • status();
  • CLOCK_MONOTONIC_RAW;
  • both devices' frame counts, xruns and other recoveries;
  • the hardware pairs.
• --rt runs both audio threads SCHED_FIFO with mlockall, and stops if the system refuses either.
• The file is now clang-tidy-clean: braces throughout, and the two conversion helpers renamed to snake_case.

examples/alsa_bridge_report.py (standard library; --plot uses matplotlib) reads that CSV:

• A least-squares line through each device's frames against time gives that crystal's rate, from the thread counts and from the hardware pairs. Their ratio is the true offset in ppm.
• It compares that offset with the servo's mean while locked.
• It reports the ppm wobble, the FIFO's breathing, and the final discontinuity counts.

CI: the Linux build-and-test legs and the clang-tidy job install libasound2-dev.

Why

Block B's verdict on async (row P8) is "clock recovery proven on independent crystals". The bridge reported the servo's own estimate, but nothing measured the crystals independently to check it. It would also silently accept a plugin device that resamples (on a Pi, default is PipeWire), and then measure the wrong clock.

Verification

• --self-test builds a synthetic hour with an 80 ppm offset. The thread counts recover 80.025 ppm and the hardware pairs 80.000 ppm, and the wobble and breathing match the injected noise.
• Two tests run without hardware:
  • async.Examples.AlsaBridgeReportSelfTest runs the self-test wherever Python is.
  • async.Examples.AlsaBridgeRefusesPluginDevices checks that --in default is refused.
• Locally, with libasound2-dev installed:
  • clang 18 -Werror and GCC 13 build the bridge without a warning;
  • clang-tidy is clean;
  • the full clang suite passes, 329 of 329.
• I could not run the bridge itself: there are no audio devices here. Its first real run is Block B's.

Notes for the reviewer

• Behaviour change: the bridge no longer defaults to "default"; --in/--out must be hw: devices. The book's commands already used hw:1,0/hw:2,0.
• A11b (pico2_cyccnt gains bridge and rational cases and copy_to_ram) and A11c (the UAC2 asynchronous-mode firmware) follow as their own PRs.

🤖 Generated with Claude Code

https://claude.ai/code/session_016GKzq1VSdcMYCRMhddiMaf

---

Generated by Claude Code