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

package/src/dt-config/overlay.ts

@@ -6,7 +6,7 @@
 // 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.)
 // ---------------------------------------------------------------------------
@@ -14,8 +14,13 @@
 import type { ZephyrChipDescriptor } from '../chips/types.js';
 import type { ZephyrDisplayProfile } from '../display/profiles.js';
 import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
+import { SENSOR_PART_INFO } from '@typecad/hal';
 import type { KconfigUsage } from './kconfig.js';
 
+/** 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;
+
 /**
  * Generate the overlay source for a board + usage. Returns the overlay text
  * (caller writes it to app/boards/<board>.overlay via writeIfChanged).
@@ -108,14 +113,129 @@ export function generateOverlay(
     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<string, string[]>();
+  const controllerBlock = (c: { nodeLabel: string; pinctrlRef?: string; props?: readonly string[]; pinctrl?: { include: string; pinmux: readonly string[]; inputPinmux?: readonly string[]; defines?: readonly string[] } }): void => {
+    const extra: string[] = [...(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: string[] = [];
+    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
@@ -136,9 +256,34 @@ export function generateOverlay(
     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
@@ -173,19 +318,128 @@ export function generateOverlay(
   // 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<number, typeof spiSensors>();
+  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: string[] = [];
+    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";');
@@ -212,14 +466,190 @@ function emitPwmNodes(
   chip: ZephyrChipDescriptor,
   usedPins?: readonly number[],
 ): void {
-  const synthesized = (chip.pwm?.specs ?? []).filter(
+  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: { pin: number; controller: string; channel: number }[] = [];
+  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).
-  for (const controller of [...new Set(synthesized.map((s) => s.controller!))]) {
+  // 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: string | undefined): boolean => !!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('');
   }
@@ -251,26 +681,99 @@ function emitPwmNodes(
  * 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: string): string | undefined {
+  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: string[],
   chip: ZephyrChipDescriptor,
   readPins?: readonly number[],
 ): void {
   const adc = chip.adc!;
-  const labeled = adc.channels.filter((c) => c.pinctrl);
-  const used = labeled.filter((c) => !readPins || readPins.includes(c.pin));
-  if (labeled.length > 0 && used.length > 0) {
-    lines.push(`&${adc.nodeLabel} {`);
+  const primary = adc.nodeLabel;
+  const controllerOf = (c: { controller?: string }) => c.controller ?? primary;
+  const used = readPins ? adc.channels.filter((c) => readPins.includes(c.pin)) : adc.channels;
+  const isMacro = (p: string | undefined): boolean => !!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";');
-    lines.push(`    pinctrl-0 = <${used.map((c) => `&${c.pinctrl}`).join(' ')}>;`);
-    lines.push('    pinctrl-names = "default";');
+    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('');
-    return;
   }
-  lines.push(`&${adc.nodeLabel} {`);
+}
+
+/**
+ * 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: string[],
+  chip: ZephyrChipDescriptor,
+  writePins?: readonly number[],
+): void {
+  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('');
 }
@@ -287,6 +790,15 @@ function emitAdcNode(
  * 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: string[], chip: ZephyrChipDescriptor, alertPin: number | undefined, supported: boolean, indent: number): void {
+  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: string[],
   display: ZephyrDisplayProfile,
@@ -298,7 +810,7 @@ function emitDisplayNode(
   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.