@typecad/framework-zephyr 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/dt-config/overlay.js

@@ -6,11 +6,15 @@
 // descriptor knows, emit a `&nodelabel { status = "okay"; }` block enabling it.
 // West merges this over the board's base DT; we never rewrite the base.
 //
-// This is the Zephyr analog of Arduino's library-resolution hooks: the artifact
+// Framework library-resolution hook: the artifact
 // that brings external capabilities into a build. (Arduino does it by parsing
 // library headers into .d.ts; Zephyr does it by enabling DT nodes + Kconfig.)
 // ---------------------------------------------------------------------------
 import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
+import { SENSOR_PART_INFO } from '@typecad/hal';
+/** Display panel CS default — shared by the display block and the SPI-sensor
+ *  cs-gpios merge so both sites write the same entry. */
+const DEFAULT_DISPLAY_CS = 5;
 export function generateOverlay(chip, usage, display, wiring, touch, diagnostics = []) {
     // An I2C touch controller with no explicit bus pins: the overlay enables
     // i2c0 and instantiates the node, but nothing remuxes the controller to
@@ -41,22 +45,186 @@ export function generateOverlay(chip, usage, display, wiring, touch, diagnostics
         lines.push('};');
         lines.push('');
     };
-    if (usage.usesI2c && chip.i2c) {
-        for (const c of chip.i2c.controllers)
-            block(c.nodeLabel);
+    // Controllers whose board DT ships no default pinctrl group (rp2xxx uart1)
+    // carry synthesis data: emit the group under &pinctrl, then enable the
+    // controller referencing it. Controllers with a pinctrlRef wire an existing
+    // group instead; `props` adds raw property lines for bindings with
+    // required properties the board only sets on its own wired nodes.
+    // The pinmux header include is collected and spliced before all blocks
+    // (tokens must be defined before use).
+    const pinctrlIncludes = new Map();
+    const controllerBlock = (c) => {
+        const extra = [...(c.props ?? [])];
+        if (c.pinctrl) {
+            pinctrlIncludes.set(c.pinctrl.include, c.pinctrl.defines ? [...c.pinctrl.defines] : []);
+            const group = `${c.nodeLabel}_default`;
+            lines.push('&pinctrl {');
+            lines.push(`    ${group}: ${group} {`);
+            lines.push(`        group1 {`);
+            lines.push(`            pinmux = <${c.pinctrl.pinmux.join(', ')}>;`);
+            lines.push(`        };`);
+            if (c.pinctrl.inputPinmux && c.pinctrl.inputPinmux.length > 0) {
+                lines.push(`        group2 {`);
+                lines.push(`            pinmux = <${c.pinctrl.inputPinmux.join(', ')}>;`);
+                lines.push(`            input-enable;`);
+                lines.push(`        };`);
+            }
+            lines.push(`    };`);
+            lines.push('};');
+            lines.push('');
+            extra.push(`pinctrl-0 = <&${group}>;`, `pinctrl-names = "default";`);
+        }
+        else if (c.pinctrlRef) {
+            extra.push(`pinctrl-0 = <&${c.pinctrlRef}>;`, `pinctrl-names = "default";`);
+        }
+        block(c.nodeLabel, extra);
+    };
+    // Sensors ride a bus: a constructed sensor must enable its controller even
+    // when the program never calls i2c.*/spi.* directly (the sensor device
+    // handle is the only bus user) — merge their instances into the used sets.
+    const sensorParts = usage.sensorParts ?? [];
+    const i2cSensors = sensorParts.filter((s) => s.busKind !== 'spi');
+    const spiSensors = sensorParts.filter((s) => s.busKind === 'spi');
+    const spiTargets = usage.spiTargets ?? [];
+    const i2cInstances = new Set(usage.i2cUsedInstances ?? []);
+    for (const sp of i2cSensors)
+        i2cInstances.add(sp.busIndex);
+    if ((usage.usesI2c || i2cSensors.length > 0) && chip.i2c) {
+        for (const [i, c] of chip.i2c.controllers.entries()) {
+            if (usage.i2cUsedInstances && !i2cInstances.has(i))
+                continue;
+            controllerBlock(c);
+        }
+    }
+    const spiInstances = new Set(usage.spiUsedInstances ?? []);
+    for (const sp of spiSensors)
+        spiInstances.add(sp.busIndex);
+    for (const t of spiTargets)
+        spiInstances.add(t.busIndex);
+    if ((usage.usesSpi || spiSensors.length > 0 || spiTargets.length > 0) && chip.spi) {
+        for (const [i, c] of chip.spi.controllers.entries()) {
+            if (usage.spiUsedInstances && !spiInstances.has(i))
+                continue;
+            controllerBlock(c);
+        }
+    }
+    // One DT child node per constructed I2C sensor — THE enable switch for the
+    // driver (its Kconfig is `default y` on this node's presence). The nodelabel
+    // is derived identically to the lowering's DEVICE_DT_GET target
+    // (lowering/sensor.ts sensorNames) — the two cannot drift.
+    for (const sp of i2cSensors) {
+        const ctrl = chip.i2c?.controllers[sp.busIndex];
+        const info = SENSOR_PART_INFO[sp.part.replace(/^SENSOR\./, '')];
+        if (!ctrl || !info)
+            continue; // the lowering already threw on unknown parts
+        const nodeName = info.compatible.split(',')[1] ?? sp.part;
+        const addrHex = sp.port.toString(16);
+        lines.push(`&${ctrl.nodeLabel} {`);
+        lines.push(`    tc_${sp.part.replace(/^SENSOR\./, '')}_i2c${sp.busIndex}_0x${addrHex}: ${nodeName}@${addrHex} {`);
+        lines.push(`        compatible = "${info.compatible}";`);
+        lines.push(`        reg = <0x${addrHex}>;`);
+        emitAlert(lines, chip, sp.alertPin, info.alert, 8);
+        lines.push('    };');
+        lines.push('};');
+        lines.push('');
     }
     if (usage.usesSpi && chip.spi) {
-        for (const c of chip.spi.controllers)
-            block(c.nodeLabel);
+        for (const [i, c] of chip.spi.controllers.entries()) {
+            if (usage.spiUsedInstances && !usage.spiUsedInstances.includes(i))
+                continue;
+            controllerBlock(c);
+        }
     }
     if (usage.usesUart && chip.uart) {
-        for (const c of chip.uart.controllers)
-            block(c.nodeLabel);
+        for (const [i, c] of chip.uart.controllers.entries()) {
+            if (usage.uartUsedInstances && !usage.uartUsedInstances.includes(i))
+                continue;
+            controllerBlock(c);
+        }
+    }
+    // Synthesized pinctrl groups reference pinmux tokens — splice their header
+    // includes ahead of every block (same slot the display path uses), with
+    // ifndef-guarded #defines for upstream header bugs in front.
+    for (const [include, defines] of pinctrlIncludes) {
+        const pre = [];
+        for (const d of defines) {
+            const name = d.trim().split(/\s+/)[0];
+            pre.push(`#ifndef ${name}`, `#define ${d}`, `#endif`);
+        }
+        lines.splice(2, 0, ...pre, `#include <${include}>`, '');
+    }
+    // Watchdog: the SoC dtsi declares the node disabled (STM32 iwdg ships
+    // status = "disabled" until a board enables it) — the wdt.* lowering
+    // addresses DEVICE_DT_GET(DT_NODELABEL(<nodeLabel>)), which needs the
+    // driver instance built, so enable the node when wdt_* is used.
+    if (usage.usesWdt && chip.wdt) {
+        block(chip.wdt.nodeLabel);
+    }
+    // USB CDC-ACM: the "next" USB device stack composes classes as devicetree
+    // children of the UDC controller node. Enable the controller and declare one
+    // cdc_acm_uart<N> child per instance the chip descriptor declares — the
+    // lowering addresses instance N as DT_NODELABEL(cdc_acm_uart<N>), so the
+    // nodelabels here and in lowering/usb.ts cannot drift. Endpoints and
+    // descriptors are assigned by the class driver at build time.
+    if (usage.usesUsb && chip.usb) {
+        lines.push(`&${chip.usb.controller} {`);
+        lines.push('    status = "okay";');
+        for (let i = 0; i < chip.usb.cdcInstances; i++) {
+            lines.push(`    cdc_acm_uart${i}: cdc-acm-uart${i} {`);
+            lines.push('        compatible = "zephyr,cdc-acm-uart";');
+            lines.push('    };');
+        }
+        lines.push('};');
+        lines.push('');
+    }
+    // PWM: synthesized specs (controller + channel, no board-shipped alias) get
+    // a pwm-leds consumer node + tc-pwm<pin> alias here — the lowering addresses
+    // the channel as PWM_DT_SPEC_GET(DT_ALIAS(tc-pwm<pin>)), so the alias must
+    // exist in the merged DT. pwmDtAlias (lowering/pwm.ts) derives the same
+    // name from the pin; the two sides cannot drift. Filtered to the pins the
+    // program actually drives (pwmUsedPins) so the DT carries no dead channels;
+    // an undefined list (prepare-time overlay) emits all specs.
+    if (usage.usesPwm && chip.pwm) {
+        emitPwmNodes(lines, chip, usage.pwmUsedPins);
+    }
+    // ADC: enable the ADC device node, and on SoCs whose channels carry a
+    // pinctrl label (STM32: the pad stays in GPIO mode unless the ADC node's
+    // pinctrl-0 muxes it analog), rewrite pinctrl-0 to exactly the channels the
+    // program reads. DT assignment replaces the whole property — the board
+    // default (one pad) is deliberately dropped in favor of the used set.
+    if (usage.usesAdc && chip.adc) {
+        emitAdcNode(lines, chip, usage.adcReadPins);
     }
     // DAC: enable the chip's DAC device node when the program uses dac.*. The
-    // lowering references DEVICE_DT_GET(DT_NODELABEL(<dac.device>)).
+    // lowering references DEVICE_DT_GET(DT_NODELABEL(<dac.device>)); the used
+    // channels' pinctrl groups route the output to its pad.
     if (usage.usesDac && chip.dac) {
-        block(chip.dac.device);
+        emitDacNode(lines, chip, usage.dacWritePins);
+    }
+    // Counters: enable the free counter devices when the program uses hwtimer.
+    // Self form (nRF rtc1, STM32 rtc): enable the labeled node. Child form
+    // (ESP32 timer0-3): the counter device is an unlabeled `counter {}`
+    // child — the overlay defines the tc_counter<N> label the descriptor's
+    // nodeLabel references (the same label-less-child move the STM32 pwm
+    // path uses).
+    if (usage.usesHwtimer && chip.hwtimer) {
+        for (const c of chip.hwtimer.controllers) {
+            if (c.counterParent) {
+                lines.push(`&${c.counterParent} {`);
+                lines.push('    status = "okay";');
+                lines.push(`    ${c.nodeLabel}: counter {`);
+                lines.push('        status = "okay";');
+                lines.push('    };');
+                lines.push('};');
+                lines.push('');
+            }
+            else {
+                lines.push(`&${c.nodeLabel} {`);
+                lines.push('    status = "okay";');
+                lines.push('};');
+                lines.push('');
+            }
+        }
     }
     if (display) {
         // Emit a full display DT node definition. Boards like the ESP32 devkit
@@ -85,18 +253,133 @@ export function generateOverlay(chip, usage, display, wiring, touch, diagnostics
     // chosen entry makes the lookup explicit and survives boards that name the
     // partition differently. It only adds a /chosen pointer (never redeclares
     // the partition node — west errors if a node is multiply-defined).
-    if (usage.usesPreferences) {
-        lines.push('/ {');
-        lines.push('    chosen {');
-        lines.push('        zephyr,settings-partition = &storage_partition;');
-        lines.push('    };');
-        lines.push('};');
-        lines.push('');
+    if (usage.usesPreferences || usage.usesFS) {
+        // Boards whose DTS ships no storage_partition (most STM32s define only
+        // the MCUboot boot/slot/scratch set) declare a synthesis region in the
+        // chip descriptor — emit it as a partition@<offset> child of the flash0
+        // partitions node. Adding a NEW child via overlay is legal; redeclaring
+        // an existing one is not, so boards that already carry the label
+        // (descriptor storage.preexisting — ESP32's AMP layout) skip the
+        // synthesis block and only the /chosen pointer lands here.
+        if (chip.storage && !chip.storage.preexisting) {
+            lines.push('&flash0 {');
+            // Explicit compatible + cells: boards whose DTS already carries a
+            // partitions node (rp2040, STM32 MCUboot sets) merge identically, and
+            // boards without one (rpi_pico2) would otherwise hit dtc's spec
+            // default of #address-cells 2 / #size-cells 1 — a 3-cell reg and a
+            // "length 8 not divisible by 12" error for the 2-cell reg below.
+            lines.push('    partitions {');
+            lines.push('        compatible = "fixed-partitions";');
+            lines.push('        #address-cells = <1>;');
+            lines.push('        #size-cells = <1>;');
+            lines.push(`        storage_partition: partition@${chip.storage.offset.toString(16)} {`);
+            lines.push('            label = "storage";');
+            lines.push(`            reg = <0x${chip.storage.offset.toString(16).padStart(8, '0')} 0x${chip.storage.size.toString(16).padStart(8, '0')}>;`);
+            lines.push('        };');
+            lines.push('    };');
+            lines.push('};');
+            lines.push('');
+        }
+        if (usage.usesPreferences) {
+            lines.push('/ {');
+            lines.push('    chosen {');
+            lines.push('        zephyr,settings-partition = &storage_partition;');
+            lines.push('    };');
+            lines.push('};');
+            lines.push('');
+        }
     }
     // PSRAM: enable the psram0 DT node with the correct size. The devkitc board
     // DT defaults to a no-PSRAM module variant (e.g. wroom_n8); a PSRAM-capable
     // module (N16R8, N8R8) needs the node enabled + sized so the linker maps
     // .ext_ram sections into the real PSRAM. OPI on ESP32-S3 = 8MB octal PSRAM.
+    // SPI sensors: children whose reg is their cs-gpios INDEX. DT property
+    // assignment replaces the whole property, so cs-gpios is written here with
+    // every sensor CS on the controller, after the display block — a display
+    // panel sharing the bus is a wiring conflict this layer cannot merge (its
+    // CS comes from config wiring), so warn instead of silently dropping it.
+    // spi-max-frequency defaults to 1 MHz — conservative for sensors whose
+    // datasheet max isn't in any binding; the constructor opts override it.
+    const SPI_SENSOR_HZ = 1000000;
+    const spiByCtrl = new Map();
+    for (const sp of spiSensors) {
+        const list = spiByCtrl.get(sp.busIndex) ?? [];
+        list.push(sp);
+        spiByCtrl.set(sp.busIndex, list);
+    }
+    // Target-only controllers (no sensors) still need the cs-gpios block.
+    for (const t of spiTargets) {
+        if (!spiByCtrl.has(t.busIndex))
+            spiByCtrl.set(t.busIndex, []);
+    }
+    for (const [idx, sensors] of spiByCtrl) {
+        const ctrl = chip.spi?.controllers[idx];
+        if (!ctrl)
+            continue;
+        // A display panel on the same controller already wrote cs-gpios earlier
+        // in this overlay (its CS at index 0, an XPT2046 at 1). DT property
+        // assignment replaces, so this rewrite carries BOTH: the display entries
+        // first — keeping the panel/touch reg indexes stable — then the sensor CS
+        // pins. The entry construction mirrors emitDisplayNode's defaults via the
+        // shared DEFAULT_DISPLAY_CS/DEFAULT_XPT2046_CS constants.
+        const displayEntries = [];
+        if (display && (display.busLabel ?? 'spi2') === ctrl.nodeLabel) {
+            const displayCs = wiring?.cs ?? DEFAULT_DISPLAY_CS;
+            displayEntries.push(`<&gpio${displayCs <= 31 ? '0' : '1'} ${displayCs} GPIO_ACTIVE_LOW>`);
+            if (touch?.controller === 'xpt2046') {
+                const touchCs = touch.cs ?? DEFAULT_XPT2046_CS;
+                displayEntries.push(`<&gpio${touchCs <= 31 ? '0' : '1'} ${touchCs} GPIO_ACTIVE_LOW>`);
+            }
+        }
+        // Thin SPI targets ride this controller too: their CS entries append
+        // after the sensor pins, and their child nodes carry no compatible —
+        // a raw spi_dt_spec peer, not a driver node.
+        const ctrlTargets = spiTargets.filter((t) => t.busIndex === idx);
+        lines.push(`&${ctrl.nodeLabel} {`);
+        lines.push(`    cs-gpios = ${displayEntries.concat(sensors.map((sp) => {
+            const gc = chip.gpioControllers?.find((g) => sp.port >= g.minPin && sp.port <= g.maxPin);
+            const ctrlLabel = gc?.nodelabel ?? 'gpio0';
+            return `<&${ctrlLabel} ${sp.port} GPIO_ACTIVE_LOW>`;
+        }), ctrlTargets.map((t) => {
+            const gc = chip.gpioControllers?.find((g) => t.cs >= g.minPin && t.cs <= g.maxPin);
+            const ctrlLabel = gc?.nodelabel ?? 'gpio0';
+            return `<&${ctrlLabel} ${t.cs} GPIO_ACTIVE_LOW>`;
+        })).join(', ')};`);
+        sensors.forEach((sp, sensorIdx) => {
+            const info = SENSOR_PART_INFO[sp.part.replace(/^SENSOR\./, '')];
+            if (!info)
+                return;
+            const nodeName = info.compatible.split(',')[1] ?? sp.part;
+            const csIndex = displayEntries.length + sensorIdx;
+            lines.push(`    tc_${sp.part}_spi${idx}_cs${sp.port}: ${nodeName}@${csIndex} {`);
+            lines.push(`        compatible = "${info.compatible}";`);
+            lines.push(`        reg = <${csIndex}>;`);
+            lines.push(`        spi-max-frequency = <${sp.spiHz && sp.spiHz > 0 ? sp.spiHz : SPI_SENSOR_HZ}>;`);
+            // mode bits: 1 = CPHA, 2 = CPOL (presence props, no value).
+            if ((sp.spiMode ?? 0) & 2)
+                lines.push('        spi-cpol;');
+            if ((sp.spiMode ?? 0) & 1)
+                lines.push('        spi-cpha;');
+            emitAlert(lines, chip, sp.alertPin, info.alert, 8);
+            lines.push('    };');
+        });
+        ctrlTargets.forEach((t, targetIdx) => {
+            const csIndex = displayEntries.length + sensors.length + targetIdx;
+            lines.push(`    tc_spit_spi${idx}_cs${t.cs}: spidev@${csIndex} {`);
+            // The app-local cuttlefish,spi-target binding (no driver — it makes
+            // gen_defines emit the spi properties SPI_DT_SPEC_GET reads).
+            lines.push(`        compatible = "cuttlefish,spi-target";`);
+            lines.push(`        reg = <${csIndex}>;`);
+            lines.push(`        spi-max-frequency = <${t.hz && t.hz > 0 ? t.hz : SPI_SENSOR_HZ}>;`);
+            if ((t.mode ?? 0) & 2)
+                lines.push('        spi-cpol;');
+            if ((t.mode ?? 0) & 1)
+                lines.push('        spi-cpha;');
+            lines.push('    };');
+        });
+        lines.push('};');
+        lines.push('');
+    }
     if (usage.psram) {
         lines.push('&psram0 {');
         lines.push('    status = "okay";');
@@ -106,6 +389,319 @@ export function generateOverlay(chip, usage, display, wiring, touch, diagnostics
     }
     return lines.join('\n');
 }
+/**
+ * Emit the pwm-leds consumer node + aliases for synthesized PWM specs.
+ *
+ * A board DTS may enable a PWM controller (`pwm4`) without aliasing any
+ * channel — the STM32 pattern — while the lowering addresses channels via
+ * DT_ALIAS. Each synthesized spec gets a `pwm-leds` child whose `pwms` cell
+ * binds the controller+channel (+ period/polarity), and a `tc-pwm<pin>`
+ * alias pointing at it. Alias/label names are valid DT identifiers (lowercase
+ * alphanumerics + dash/underscore).
+ */
+function emitPwmNodes(lines, chip, usedPins) {
+    const staticSynth = (chip.pwm?.specs ?? []).filter((s) => s.controller && s.channel != null && !s.dtSpec).filter((s) => !usedPins || usedPins.includes(s.pin));
+    // Matrix PWM (ESP32 LEDC): channels are assigned here, over the pins the
+    // program actually drives (ascending — the same order lowering/pwm.ts
+    // emits the alias vars in; the C++ is channel-blind, so this is the single
+    // place a channel number is decided). The espressif,esp32-ledc binding
+    // needs three pieces per channel: a pinctrl pinmux token routing the
+    // channel to the pad (LEDC_CH<ch>_GPIO<pin> — every channel×pad pair
+    // exists in esp32s3-pinctrl.h, already included via the SoC dtsi), a
+    // channel child node (the driver's DT_INST_FOREACH_CHILD reads reg +
+    // timer from each), and the pwm-leds consumer the alias resolves to.
+    const m = chip.pwm?.matrix;
+    let matrixSynth = [];
+    if (m) {
+        const pins = [...new Set(usedPins ? usedPins.filter((p) => m.pins.includes(p)) : m.pins)]
+            .sort((a, b) => a - b);
+        if (pins.length > m.channelCount) {
+            throw new Error(`framework-zephyr: the program drives ${pins.length} PWM pins but ${chip.id}'s ` +
+                `${m.controller} exposes only ${m.channelCount} channels — drop ` +
+                `${pins.length - m.channelCount} pwm pin(s).`);
+        }
+        matrixSynth = pins.map((pin, ch) => ({ pin, controller: m.controller, channel: ch }));
+        // nRF shape: channels route to pads via psel (pinctrl psel order IS
+        // channel order — pwm_nrfx reads PSEL.OUT[ch] back), no channel child
+        // nodes, and the overlay carries the nrf pinctrl header for NRF_PSEL.
+        // P<port>.<pin> maps from the global number through the nRF controller
+        // layout (P0 = 0-31, P1 = 32-63).
+        const isNrfMatrix = /^nrf/.test(chip.soc);
+        if (isNrfMatrix) {
+            const inc = '#include <zephyr/dt-bindings/pinctrl/nrf-pinctrl.h>';
+            if (!lines.includes(inc))
+                lines.splice(2, 0, inc, '');
+            lines.push('&pinctrl {');
+            lines.push(`    tc_${m.controller}_default: tc-${m.controller}-default {`);
+            lines.push('        group1 {');
+            lines.push(`            psel = ${pins.map((p, ch) => `<NRF_PSEL(PWM_OUT${ch}, ${Math.floor(p / 32)}, ${p % 32})>`).join(', ')};`);
+            lines.push('        };');
+            lines.push('    };');
+            lines.push('};');
+            lines.push('');
+            lines.push(`&${m.controller} {`);
+            lines.push('    status = "okay";');
+            lines.push(`    pinctrl-0 = <&tc_${m.controller}_default>;`);
+            lines.push('    pinctrl-names = "default";');
+            lines.push('};');
+            lines.push('');
+        }
+        if (!isNrfMatrix) {
+            lines.push('&pinctrl {');
+            lines.push(`    tc_${m.controller}_default: tc-${m.controller}-default {`);
+            lines.push('        group1 {');
+            lines.push(`            pinmux = ${pins.map((p, ch) => `<LEDC_CH${ch}_GPIO${p}>`).join(', ')};`);
+            lines.push('            output-enable;');
+            lines.push('        };');
+            lines.push('    };');
+            lines.push('};');
+            lines.push('');
+            // The four LEDC timers are round-robined so co-driven channels share a
+            // timer only past four (sharing is fine at equal periods; the driver
+            // reconfigures on pwm_set_dt when they differ).
+            lines.push(`&${m.controller} {`);
+            lines.push('    status = "okay";');
+            lines.push(`    pinctrl-0 = <&tc_${m.controller}_default>;`);
+            lines.push('    pinctrl-names = "default";');
+            lines.push('    #address-cells = <1>;');
+            lines.push('    #size-cells = <0>;');
+            for (let ch = 0; ch < pins.length; ch++) {
+                lines.push(`    channel${ch}@${ch} {`);
+                lines.push(`        reg = <${ch}>;`);
+                lines.push(`        timer = <${ch % 4}>;`);
+                lines.push('    };');
+            }
+            lines.push('};');
+            lines.push('');
+        }
+    }
+    const synthesized = staticSynth.concat(matrixSynth);
+    if (synthesized.length === 0)
+        return;
+    // The pwms cells name the polarity as a macro (PWM_POLARITY_NORMAL). It is
+    // NOT universally available: only dts include chains that already use PWM
+    // bindings pull <zephyr/dt-bindings/pwm/pwm.h> in (STM32 does; the
+    // ESP32-S3 chain does not), so the overlay carries its own include.
+    // Spliced after the header comments, the established pattern (see the
+    // esp32s3-pinctrl.h splice above); guarded for the double-emit case.
+    if (!lines.includes('#include <zephyr/dt-bindings/pwm/pwm.h>')) {
+        lines.splice(2, 0, '#include <zephyr/dt-bindings/pwm/pwm.h>', '');
+    }
+    // Enable each distinct PWM controller node (idempotent when already okay).
+    // 16-bit fit: STM32 timers count period cycles in a 16-bit ARR, and the
+    // SoC dtsi default is st,prescaler = <0> (÷1) — a 20 ms servo period at
+    // 96 MHz is 1.92M cycles and pwm_stm32 rejects the channel. When the
+    // descriptor declares the timer clock, derive the smallest divider that
+    // fits the controller's slowest used period and override the prescaler
+    // on the timers parent node (the property lives there, not on the pwm
+    // child). pwm4 → timers4 is the STM32 nodelabel convention. Matrix
+    // controllers are skipped — the block above already enabled them (with
+    // their pinctrl + channel children, which this loop doesn't know).
+    const clockHz = chip.pwm?.clockHz;
+    for (const controller of [...new Set(staticSynth.map((s) => s.controller))]) {
+        const timersMatch = controller.match(/^pwm(\d+)$/);
+        const specs = staticSynth.filter((s) => s.controller === controller);
+        // Macro-form pinctrl tokens (uppercase — DT labels are lowercase by
+        // spec): the overlay synthesizes the pad-routing group itself. RP2's
+        // macros live in a dt-bindings header the board chain may not pull in
+        // (spliced via rp2PinctrlHeader); Kinetis/LPC/GD32 macros come from the
+        // part headers the board's own pinctrl dtsi includes, and Zephyr
+        // preprocesses overlays together with the base DTS — no splice needed.
+        const isMacro = (p) => !!p && /^[A-Z][A-Z0-9_]*$/.test(p);
+        if (!timersMatch && specs.some((s) => isMacro(s.pinctrl))) {
+            const header = rp2PinctrlHeader(chip.soc);
+            if (header) {
+                const inc = `#include <zephyr/dt-bindings/pinctrl/${header}>`;
+                if (!lines.includes(inc))
+                    lines.splice(2, 0, inc, '');
+            }
+            lines.push('&pinctrl {');
+            lines.push('    tc_pwm_default: tc-pwm-default {');
+            lines.push('        group1 {');
+            lines.push(`            pinmux = ${specs.filter((s) => s.pinctrl).map((s) => `<${s.pinctrl}>`).join(', ')};`);
+            lines.push('        };');
+            lines.push('    };');
+            lines.push('};');
+            lines.push('');
+            lines.push(`&${controller} {`);
+            lines.push('    status = "okay";');
+            // Atmel SAM TCC/TC in PWM mode: the SoC dtsi declares the base timer
+            // node (compatible atmel,sam0-tcc / …-tc, with clocks/assigned-clocks/
+            // channels/counter-size already present). The overlay overrides the
+            // compatible to the PWM binding, sets the required prescaler and the
+            // #pwm-cells the binding consts, and reuses the shared pinctrl group.
+            const samPwm = controller.match(/^(tcc|tc)(\d+)$/);
+            if (samPwm) {
+                lines.push(`    compatible = "${samPwm[1] === 'tcc' ? 'atmel,sam0-tcc-pwm' : 'atmel,sam0-tc-pwm'}";`);
+                lines.push('    prescaler = <1024>;');
+                lines.push('    #pwm-cells = <2>;');
+            }
+            lines.push('    pinctrl-0 = <&tc_pwm_default>;');
+            lines.push('    pinctrl-names = "default";');
+            lines.push('};');
+            lines.push('');
+            continue;
+        }
+        if (timersMatch) {
+            // STM32 shape: the SoC dtsi declares a LABEL-LESS pwm child under
+            // timers{N} — the overlay defines the label itself (pwmN: pwm), which
+            // the synthesized pwms cell below references. One block carries the
+            // parent enable, the pad-routing pinctrl groups (harvested silicon
+            // routes on the specs — without them the PWM runs but nothing leaves
+            // the chip), the prescaler, and the child enable.
+            const groups = specs.filter((s) => s.pinctrl).map((s) => `&${s.pinctrl}`);
+            const maxPeriodNs = Math.max(...specs.map((s) => s.periodNs ?? 20_000_000));
+            // cycles = clockHz * period_s / divider ≤ 65536 (driver allows
+            // UINT16_MAX + 1); binding value is divider - 1 (CLK/(prescaler+1)).
+            const divider = clockHz
+                ? Math.max(1, Math.ceil((clockHz * maxPeriodNs) / 1e9 / 65536))
+                : 1;
+            lines.push(`&timers${timersMatch[1]} {`);
+            lines.push('    status = "okay";');
+            if (divider > 1) {
+                lines.push(`    st,prescaler = <${divider - 1}>;`);
+            }
+            lines.push(`    ${controller}: pwm {`);
+            lines.push('        status = "okay";');
+            if (groups.length > 0) {
+                lines.push(`        pinctrl-0 = <${groups.join(' ')}>;`);
+                lines.push('        pinctrl-names = "default";');
+            }
+            lines.push('    };');
+            lines.push('};');
+            lines.push('');
+            continue;
+        }
+        // Lowercase pinctrl tokens (i.MX `iomuxc_…` node labels from the part
+        // dtsi) ride the controller's pinctrl-0 directly.
+        const pinRefs = specs.filter((s) => s.pinctrl && !isMacro(s.pinctrl)).map((s) => `&${s.pinctrl}`);
+        lines.push(`&${controller} {`);
+        lines.push('    status = "okay";');
+        if (pinRefs.length > 0) {
+            lines.push(`    pinctrl-0 = <${pinRefs.join(' ')}>;`);
+            lines.push('    pinctrl-names = "default";');
+        }
+        lines.push('};');
+        lines.push('');
+    }
+    lines.push('/ {');
+    lines.push('    tc_pwm_leds: tc-pwm-leds {');
+    lines.push('        compatible = "pwm-leds";');
+    for (const s of synthesized) {
+        // 20 ms / 50 Hz default — the servo convention; the duty scaling in the
+        // lowering normalizes 0-255 against whatever period is baked in.
+        const period = s.periodNs ?? 20_000_000;
+        const polarity = s.polarity ?? 'PWM_POLARITY_NORMAL';
+        lines.push(`        tc_pwm_${s.pin}: pwm-led-${s.pin} {`);
+        lines.push(`            pwms = <&${s.controller} ${s.channel} ${period} ${polarity}>;`);
+        lines.push('        };');
+    }
+    lines.push('    };');
+    lines.push('    aliases {');
+    for (const s of synthesized) {
+        lines.push(`        tc-pwm${s.pin} = &tc_pwm_${s.pin};`);
+    }
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+}
+/**
+ * Emit the ADC device-node enable (+ optional pinctrl override). The pinctrl
+ * override applies only when the descriptor's channels carry pinctrl labels
+ * AND the caller knows which pins the program reads (compile-time regen scans
+ * the emitted `__tc_adc<N>_setup()` calls); the prepare-time overlay omits it
+ * and the compile regen rewrites the file before west runs.
+ *
+ * Two pinctrl forms by family: NODE labels (STM32's harvested
+ * `adc1_in1_pa1` groups — referenced as `&label`) and MACRO tokens (RP2's
+ * `ADC_CH0_P26` — DT labels are lowercase by spec and macros uppercase, so
+ * the case decides). The macro form synthesizes its own group under
+ * &pinctrl and splices the SoC's pinctrl dt-binding header so the token
+ * resolves in the overlay's compile.
+ *
+ * Multi-controller SoCs: channels may name their owning controller (STM32
+ * adc3-only routes, ESP32 units). One enable block is emitted per controller
+ * that owns used channels — the primary first, others sorted for
+ * deterministic output. Single-controller boards emit exactly one block, as
+ * before.
+ */
+/** The SoC's pinctrl dt-binding header (where the macro tokens are defined)
+ *  — RP2 shapes; undefined for socs that use node-label pinctrl exclusively. */
+function rp2PinctrlHeader(soc) {
+    if (soc === 'rp2040')
+        return 'rpi-pico-rp2040-pinctrl.h';
+    if (soc.startsWith('rp2350a'))
+        return 'rpi-pico-rp2350a-pinctrl.h';
+    if (soc.startsWith('rp2350b'))
+        return 'rpi-pico-rp2350b-pinctrl.h';
+    return undefined;
+}
+function emitAdcNode(lines, chip, readPins) {
+    const adc = chip.adc;
+    const primary = adc.nodeLabel;
+    const controllerOf = (c) => c.controller ?? primary;
+    const used = readPins ? adc.channels.filter((c) => readPins.includes(c.pin)) : adc.channels;
+    const isMacro = (p) => !!p && /^[A-Z][A-Z0-9_]*$/.test(p);
+    const macroChannels = used.filter((c) => isMacro(c.pinctrl));
+    if (macroChannels.length > 0) {
+        const header = rp2PinctrlHeader(chip.soc);
+        if (header) {
+            const inc = `#include <zephyr/dt-bindings/pinctrl/${header}>`;
+            if (!lines.includes(inc))
+                lines.splice(2, 0, inc, '');
+        }
+        lines.push('&pinctrl {');
+        lines.push('    tc_adc_default: tc-adc-default {');
+        lines.push('        group1 {');
+        lines.push(`            pinmux = ${macroChannels.map((c) => `<${c.pinctrl}>`).join(', ')};`);
+        lines.push('        };');
+        lines.push('    };');
+        lines.push('};');
+        lines.push('');
+    }
+    // Every controller that owns a USED channel gets an enable block — a
+    // controller left "disabled" in the SoC dtsi has no device instance, so a
+    // read against it fails to link. Nothing used: enable the primary only.
+    const controllers = used.length > 0
+        ? [...new Set(used.map(controllerOf))]
+            .sort((a, b) => (a === primary ? -1 : b === primary ? 1 : a.localeCompare(b, undefined, { numeric: true })))
+        : [primary];
+    for (const label of controllers) {
+        const mine = used.filter((c) => controllerOf(c) === label && c.pinctrl);
+        lines.push(`&${label} {`);
+        lines.push('    status = "okay";');
+        if (mine.length > 0) {
+            if (mine.every((c) => isMacro(c.pinctrl))) {
+                lines.push('    pinctrl-0 = <&tc_adc_default>;');
+            }
+            else {
+                lines.push(`    pinctrl-0 = <${mine.map((c) => `&${c.pinctrl}`).join(' ')}>;`);
+            }
+            lines.push('    pinctrl-names = "default";');
+        }
+        lines.push('};');
+        lines.push('');
+    }
+}
+/**
+ * Emit the DAC device-node enable + the used output channels' pinctrl
+ * groups (the harvested `dac1_out1_pa4`-style nodes — the st,stm32-dac
+ * binding includes pinctrl-device, so without the group the channel never
+ * reaches its pad). Mirrors emitAdcNode.
+ */
+function emitDacNode(lines, chip, writePins) {
+    const dac = chip.dac;
+    const labeled = dac.channels.filter((c) => c.pinctrl);
+    const used = labeled.filter((c) => !writePins || writePins.includes(c.pin));
+    lines.push(`&${dac.device} {`);
+    lines.push('    status = "okay";');
+    if (used.length > 0) {
+        lines.push(`    pinctrl-0 = <${used.map((c) => `&${c.pinctrl}`).join(' ')}>;`);
+        lines.push('    pinctrl-names = "default";');
+    }
+    lines.push('};');
+    lines.push('');
+}
 /**
  * Emit a display DT node definition. The node is attached to the profile's SPI
  * controller (default spi2, the ESP32's first user SPI controller) via a MIPI
@@ -118,13 +714,22 @@ export function generateOverlay(chip, usage, display, wiring, touch, diagnostics
  * appended as the second cs-gpios entry (the touch node uses reg = <1>) — DT
  * property assignment replaces, so both entries must be written together.
  */
+/** Emit alert-gpios for parts whose binding declares it (active high — the
+ *  bindings describe the sensor's output level, e.g. sht3xd's ALERT). */
+function emitAlert(lines, chip, alertPin, supported, indent) {
+    if (alertPin === undefined || alertPin < 0 || !supported)
+        return;
+    const gc = chip.gpioControllers?.find((g) => alertPin >= g.minPin && alertPin <= g.maxPin);
+    const pad = ' '.repeat(indent);
+    lines.push(`${pad}alert-gpios = <&${gc?.nodelabel ?? 'gpio0'} ${alertPin} GPIO_ACTIVE_HIGH>;`);
+}
 function emitDisplayNode(lines, display, wiring, spiTouchCs) {
     const bus = display.busLabel ?? 'spi2';
     const controller = panelControllerFor(display);
     const compatible = display.dtCompatible ?? PANEL_CONTROLLER_DEFAULTS[controller].dtCompatible;
     const dc = wiring?.dc ?? 17;
     const rst = wiring?.rst ?? 16;
-    const cs = wiring?.cs ?? 5;
+    const cs = wiring?.cs ?? DEFAULT_DISPLAY_CS;
     const freq = wiring?.spiFrequency ?? 80000000;
     // DT node describes the NATIVE panel geometry; the effective (rotated)
     // dimensions live in the display profile.