A diagnostic patch for Polyend Tracker+ firmware 1.2.0. It measures, on the device, how
much of each audio block's time the firmware uses, as a share of the block's real
length. It also measures how much of that is the sequencer, with every patch hooked on
it. The numbers set the cost limits in the emulator tests
(docs/TIMING_HEADROOM_PLAN.md). Config shows the
firmware version as 1.2.0-hr1; the two test bundles show 1.2.0-MH1 and
1.2.0-MH2.
It's a tool, not a feature: install one of its builds for a test session, then go back to your usual firmware.
Status: emulator-tested, alone and listed last in both bundles. Not yet tested on hardware.
| Spec | Version | What |
|---|---|---|
patch/headroom/patch.json |
hr1 |
headroom alone, on stock firmware |
patch/headroom/all_headroom.json |
MH1 |
patch/all's patches but tracklen, then headroom |
patch/headroom/all_tracklen_headroom.json |
MH2 |
patch/all's patches (tracklen last), then headroom |
Headroom must be listed last in a bundle. Its sequencer hook then runs before the
other patches' hooks on the same call, so its figure includes them.
tools/emu/test_headroom.py fails on a bundle where it isn't last.
-
Put an empty file named
.developin the SD card's root (from a computer). This turns on the stock firmware's developer lines in Config. -
Install the build. Open a project and play.
-
Open Config. Once a second, the two CPU lines that stock shows there read:
blk 61.3% seq 4.1% 1s 40.2% late 0Figure Meaning blkthe worst audio block since playback started, in % of a block's length seqthe worst sequencer share of a block (with every patch hooked on it) since then 1sthe worst block of about the last second lateblocks that started over 12.5 % late since playback started: the block before took too long, or something held the audio interrupt off. Anything above 0 means a likely click - Over 100 % means a block took longer than the time it has. One such block doesn't drop out (the output has about a block of slack); several close together do, and the clicks then come with the busiest steps. Stock firmware warns from 84 %.
- The figures reset each time playback starts, so loading a project doesn't count.
- An export is never counted: the firmware renders it outside the audio blocks.
headroom: waitingmeans no block has been timed yet.no cycle countermeans the chip's cycle counter is off; stock firmware turns it on at boot, so this shouldn't happen.
"free heap" and "max stack" below stay as in stock firmware.
The Cortex-M7 cycle counter (DWT CYCCNT) is already running: stock firmware starts it
at boot and its own CPU meter reads it twice per block. Headroom reads it too, at three
points:
| Hook | Where | What |
|---|---|---|
mt_hr_block |
app vtable +8, the word at 0x60038724 (chained) |
The whole audio block (app_audio_block), and the period from one block's start to the next |
mt_hr_seq_advance |
bl seq_advance at 0x600aa7f8 (chained) |
The sequencer's share |
mt_hr_line1, mt_hr_line2 |
the two bl snprintf of the Config developer lines (0x600cb570, 0x600cb590, chained) |
Writes the two lines above instead of stock's CPU lines |
- Percentages are of the measured period, a smoothed average of the time between block starts, so no clock rate is assumed.
- Late: a period over 12.5 % above that average counts as a late block.
- Audio-path cost: about 80 instructions per block for both hooks, which is under 0.01 % of a block. Everything else happens in Config's once-a-second update.
- Never written: debug registers, flash, files, settings.
- Size: the code is 757 bytes. The state (48 bytes) is placed by the patcher,
outside SDRAM (
"ram_startup": true).
No compiler needed (the compiled patch is in prebuilt/):
python tools/patch_ptf.py path/to/TrackerPlus_1.2.0.ptf patch/headroom/patch.json build/TrackerPlus_hr1.ptf
python tools/patch_ptf.py path/to/TrackerPlus_1.2.0.ptf patch/headroom/all_headroom.json build/TrackerPlus_MH1.ptf
python tools/patch_ptf.py path/to/TrackerPlus_1.2.0.ptf patch/headroom/all_tracklen_headroom.json build/TrackerPlus_MH2.ptfFrom source, with the Arm GNU Toolchain: patch/headroom/build.sh.
Emulator test (pip install unicorn capstone numpy):
python tools/emu/test_headroom.py build/TrackerPlus_hr1.ptfIt runs whole audio blocks through the app vtable with a fake cycle counter (the instruction count, with a clock the test sets per block). It checks:
- that the patch is first on its sites;
- that MIDI and sequencer state are unchanged by it;
- that its figures equal the instructions of the calls it times;
- the late count, the reset at playback start, the one-second window and export;
- its own cost, that it never writes debug registers, and the Config text.
It only reads the cycle counter and writes its own 48 bytes of RAM. To go back,
install your usual firmware through Config → Firmware. If the unit doesn't boot, put
only the stock TrackerPlus_1.2.0.ptf in /Firmware, power on with the card in, and
press the pinhole button next to the USB-C port.