feat(demag): active demag — freewheel through the FET channel instead of the body diode

[AlexKlimaj]

Summary

Stacked on #24 (demag compensation) — the active-demag half of draft PR #2. During normal PWM chopping AM32 already turns on the opposite-side FET (comp_pwm complementary drive, default on); the remaining body-diode conduction window is post-commutation demag: the winding that just switched off dumps its stored current through a body diode (~0.7–1 V drop) until it decays. This PR turns on the FET whose body diode is carrying that freewheel current, so the demag current circulates through the channel (mΩ Rds(on)) instead — measurable g/W at mid/high load, where demag current is largest.

Rebased 2026-07-06 onto the rebased #24 (perf v4 world), and now includes a comparator interlock (below) that turns the wrong-mapping hazard into a diagnostic counter.

How it works

PeriodElapsedCallback(), after commutate() and the hwci ZC hook (so jitter metrics are unaffected): if active demag is enabled and #24's measurement is armed, activeDemagFetOn() drives the floating phase's conducting-side FET (chosen from step + rising) and re-arms COM_TIMER for active_demag_ticks = half the last measured demag time, re-capped at waitTime/2 at use time. The second COM event hits a guard at the top of the callback that floats the phase again and returns. If the true zero-cross arrives before the off-event, interruptRoutine() force-floats and clears the flag so the pending COM event isn't swallowed.

The FET-on window therefore always ends well before the zero-cross is expected, leaving the BEMF sensing window untouched. The previously conducting FET has been off since comStep() at the top of commutate() several µs earlier, so there is no cross-conduction with the outgoing drive.

Implementation: phaseXHIGH() outputs + activeDemagFetOn/Off() live in each MCU's phaseouts.c (in-TU so the phase bodies inline; f051/g071/g431/l431, HAS_PHASE_HIGH-gated). On F051 the helpers stay in flash deliberately: RAM_FUNC placement cost 504 B and overflowed the HWCI-build RAM; the 1-wait-state penalty is well under the 0.5 µs COM-timer tick that schedules them.

Comparator interlock — wrong mapping becomes a counter, not a damage event

The failure mode if activeDemagFetOn()'s step/rising → FET mapping is wrong for a board/direction combo is not a rail short (the conducting body diode commutates off when the node is pulled to the opposite rail) — it's worse in a quieter way: the full bus voltage lands across the "floating" winding in the re-magnetizing direction, an uncontrolled VBAT/L current ramp (~2.4 A/µs at 24 V/10 µH) that the DRV8328 (no VDS trip) and the 1 kHz firmware current loop cannot catch. The DRV8328's built-in dead-time enforcement does not protect here: only one gate is commanded, which is a perfectly legal input pattern — it only guards same-leg INH/INL overlap.

So this PR adds a one-comparator-read interlock: during demag the floating phase is diode-clamped to the far rail, which the comparator reads as the post-cross level (!rising) — the same signal #24's reversed-polarity demag-edge arm watches. Just before activeDemagFetOn(), if the comparator instead reads the pre-cross level, the mapping is wrong (or demag has already released, where energizing the FET would short the BEMF) — skip the freewheel for that step and count it in active_demag_interlock_skips (perf struct v5, offset 92, fw_interlock_skips in run summaries). Interpretation: ~0 healthy; ≈ one per commutation = wrong mapping — the veto keeps the hardware safe while you scope it.

Bench protocol (still applies — the interlock is a backstop, not a substitute)

1. First runs with DEMAG_COMP=1 only, ACTIVE_DEMAG off, to establish the measurement baseline.
2. Scope the floating phase to confirm the commanded FET matches the freewheel diode's side on both rising polarities and both directions.
3. Then make ARK_4IN1_F051 HWCI_PERF=1 DEMAG_COMP=2 ACTIVE_DEMAG=1, first run low duty with current + FET-thermal watch, checking fw_interlock_skips ≈ 0.
4. efficiency_sweep A/B (ACTIVE_DEMAG=0 vs =1): expect a g/W gain at mid/high load; fw_demag_events == 0, bemf_timeout_samples == 0, fw_interlock_skips ≈ 0, FET temps flat.

USE_INVERTED_HIGH targets get the inverted HIGH_BITREG_ON mapping — compile-time correct but untested on such hardware.

Memory (ARK_4IN1_F051)

Build	FLASH	RAM
HWCI_PERF=1 DEMAG_COMP=2 ACTIVE_DEMAG=1	25328 B (92.4%)	7728 B (96.6%)

272 B RAM free on the HWCI build — flagged as the binding constraint for the next F051 feature.

hwci offline tests: 143 passed. Builds verified: ARK_4IN1_F051 (plain / HWCI_PERF / both knobs), GEN_64K_G071, REF_G431, NEUTRON_L431, SEQURE_4IN1_F421.

🤖 Generated with Claude Code

https://claude.ai/code/session_011pvp2XLcgsviGSVn9PaaP6