Disconnect the board before you tune on it
We flash code onto your device and run it. While a tuning run is going, the board must be completely disconnected from anything around it — nothing wired to its pins, nothing it can drive, nothing it can move, heat, energise or switch.
Why this matters more here than in a normal build
Tuning is not compiling once. It builds many versions of your program and executes each of them on the real part to find out which is fastest. Code runs on that device, repeatedly, in orders and timings you did not choose. If a pin on that board is wired to something in the physical world, that something can be actuated while we are measuring.
A motor turns. A relay closes. A heater energises. None of that is hypothetical for an embedded target, and none of it is something a compiler can undo.
What we do about it, and what we cannot do
What the compiler already refuses
A register your source marks volatile is recognised as talking to a device,
and transformations that would reorder or restructure accesses to it are
refused rather than discouraged — the change cannot be shown to
preserve what your program was specifying, so it is not applied. Timing you wrote
deliberately stays as you wrote it.
What we ship to help
For common hardware we also ship maps of which memory regions perform device accesses, so those are left alone whether or not your source says so.
The gap, stated plainly
Between those two there is a real hole: a memory-mapped register that your
source does not mark volatile and that our device map does not know
about. We cannot tell that apart from ordinary memory, and we may reorder
accesses to it. That is not a hypothetical — it is the specific case the isolation
rule exists for, and it is why the maps are best effort rather than a guarantee.
On a part we have no map for at all, that gap is wider. Tuning still runs — a part we have never seen is exactly the hardware worth tuning, and refusing would only push people into working around the check — but nothing is being avoided on your behalf, so every unmarked memory-mapped register on that chip is in the gap.
Unless you know we have a map for your exact part, assume we do not. That is the safe assumption and it costs you nothing, because the thing it asks for — a disconnected board — is what we ask for either way. The confirmation a run asks for does not tell you which case you are in, so do not wait to be told.
And the part no software can close
Nothing we ship can know what you have physically wired to your board. That is the one fact only you have. Disconnecting the board is what makes the gap above harmless, and it is why this has to be checked before every run rather than agreed to once.
Before every tuning run
- Unplug everything from the board except the cable you program it through.
- If it is mounted in something — a rig, a robot, a machine, a vehicle — take it out, or make sure what it drives is disconnected and cannot be energised.
- Check that nothing downstream is powered from the board or shares its ground.
- Then start the run.
This page explains the warning you will see in the tools. It is not a substitute for it, and it is not a legal document.