[Moonshot PR] CPU optimiser pipeasio telemetry

notes/MOONSHOT-CPU-PIPEASIO-TELEMETRY.md

@@ -0,0 +1,68 @@
+# PipeASIO callback timing
+
+Date: 26 August 2026
+
+## Use
+
+Use the timing report to find where each audio callback spends time. Run normal
+CPU comparisons with the default setting.
+
+Start one controlled timing run with:
+
+```sh
+env PIPEASIO_TELEMETRY=on ableton-live
+```
+
+Set `PIPEASIO_TELEMETRY=on` to start telemetry. The default path performs zero
+telemetry clock reads.
+
+The driver reports results once per second. It measures these 3 parts:
+
+- work in PipeASIO before Live receives the buffer
+- time inside Live's buffer callback
+- PipeASIO work after Live returns the buffer
+
+Each part reports elapsed time and callback thread CPU time. The report includes
+`p50`, `p95`, `p99`, and the largest value.
+
+The cycle record separates Live's time-info and legacy callback paths. Its
+`muted` value counts admitted callbacks silenced after a buffer-size mismatch,
+while `dropped` counts timing samples discarded when the fixed queue is full.
+
+Long elapsed time with little CPU use often means that the thread waited. High
+CPU time shows work on the callback thread.
+
+## Audio safety rules
+
+The callback writes fixed numeric samples into a fixed-size queue. A full queue
+discards samples and counts each discarded sample.
+
+A separate worker copies, sorts, and summarises the samples once per second.
+The audio callback continues during that work.
+
+The output write returns immediately when a pipe reaches capacity. The driver
+discards that report. Slow storage can delay the separate worker while the
+callback continues.
+
+During shutdown, the driver removes the shared timing state before it closes
+or frees that state.
+
+## Measurement limits
+
+Each measured callback performs 8 clock reads: 4 `CLOCK_MONOTONIC` reads and 4
+`CLOCK_THREAD_CPUTIME_ID` reads. On the review host, the thread CPU clock cost
+137.5 ns per read and the monotonic clock cost 12.1 ns per read. This adds about
+598 ns to each measured callback. Use default mode for before and after CPU
+results.
+
+Use timing reports with the 30-second benchmark, PipeWire error counts, and
+Live's CPU value. Add a listening result when you assess audible crackle.
+
+## Release checks
+
+The 2 patches apply after PipeASIO patch 0013. Run the unit, ABI, minimal driver,
+ASan, UBSan, and TSan tests with the normal runtime build.
+
+Run PipeWire tests at 32, 64, 128, and 256 frames. Compare default and enabled
+timing runs to measure the added work. Use a slow report destination to check
+discarded reports and audio deadlines.

patches/SERIES.sha256

@@ -104,3 +104,5 @@ adf7f8446f8b4e60ab7df8bf433f50fcfd65ddf123c731027e513f4057ad2207  pipeasio/0010-
 bea289bb6f78f4b217813c4457c54bf2e4224fb74bb0435ac17bbb50a1db5a53  pipeasio/0011-controlpanel-dialog-off-the-host-gui-thread.patch
 8542e3eb5f4e77559783b85bc741c1c21e99027e2e3989a1456909819385227e  pipeasio/0012-recover-selected-routes-after-hotplug.patch
 ec509d3559896a4c5f877ef4a8ba562bedbbb69e44891d18d475892a65d8a704  pipeasio/0013-avoid-redundant-output-fallback-publish.patch
+9979b4946153336604951fec83acfe3c264af0d5fe65d5c3da71757e31ab366d  pipeasio/0014-callback-phase-telemetry.patch
+54833329e71f9b15b15fe0c854464126a686ce64404b1c8bc070a8525a42065d  pipeasio/0015-nonblocking-telemetry-reporting.patch