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

package/src/dt-config/overlay.ts

@@ -1,423 +1,450 @@
-// ---------------------------------------------------------------------------
-// Devicetree overlay generator
-//
-// Generates <project>/app/boards/<board>.overlay — the standard Zephyr overlay
-// path. Content is additive: for each used peripheral with a DT binding the chip
-// 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
-// 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 type { ZephyrChipDescriptor } from '../chips/types.js';
-import type { ZephyrDisplayProfile } from '../display/profiles.js';
-import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
-import type { KconfigUsage } from './kconfig.js';
-
-/**
- * Generate the overlay source for a board + usage. Returns the overlay text
- * (caller writes it to app/boards/<board>.overlay via writeIfChanged).
- */
-/** Display wiring from cuttlefish.config.ts (cs/dc/rst/spiFrequency/spiPins). */
-export interface DisplayWiring {
-  cs?: number;
-  dc?: number;
-  rst?: number;
-  spiFrequency?: number;
-  /** SPI bus pins. When present, the overlay remuxes the SPI controller's
-   *  pinctrl to these pins (the board defaults rarely match a breakout's
-   *  wiring — e.g. demo-st's panel is on SCK=18/MOSI=23, not the devkitc
-   *  default 12/11). */
-  sck?: number;
-  mosi?: number;
-  miso?: number;
-  /** Optional GPIO driving the panel backlight. When set, the overlay emits a
-   *  `gpio-leds` node + DT alias (named by the profile's `backlight`) so the
-   *  display adapter can drive it high at init. When absent (e.g. the panel's
-   *  backlight is hardwired to 3.3V), no node or alias is emitted — the C++
-   *  backlight init is guarded by `DT_HAS_ALIAS` and compiles away. */
-  backlightPin?: number;
-}
-
-/** Touch wiring from cuttlefish.config.ts (irq/resetPin/sda/scl; cs for SPI
- *  resistive controllers, calibration for the XPT2046 DT binding). */
-export interface TouchWiring {
-  /** Touch controller kind — selects the DT node shape (FT6336U node on I2C0
-   *  vs XPT2046 node on the display's SPI bus). Default 'ft6336u'. */
-  controller?: 'ft6336u' | 'xpt2046';
-  irq?: number;
-  resetPin?: number;
-  sda?: number;
-  scl?: number;
-  /** XPT2046 only: SPI CS pin (second cs-gpios entry on the panel's bus). */
-  cs?: number;
-  /** XPT2046 only: raw ADC calibration — feeds the binding's min-x/max-x/
-   *  min-y/max-y (required props). Defaults span the full 12-bit range. */
-  calibration?: { xMin: number; xMax: number; yMin: number; yMax: number };
-  /** XPT2046 only: pen-detect Z1 threshold (binding's z-threshold). Resistive
-   *  panels need a few hundred 12-bit counts; default 400. */
-  minPressure?: number;
-}
-
-export function generateOverlay(
-  chip: ZephyrChipDescriptor,
-  usage: KconfigUsage,
-  display: ZephyrDisplayProfile | undefined,
-  wiring?: DisplayWiring,
-  touch?: TouchWiring,
-): string {
-  const lines: string[] = [
-    '/* Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts. */',
-    '/* Enables peripherals the program uses. West merges this over the board DT. */',
-    '',
-  ];
-
-  // Pinctrl override blocks reference the esp32s3 pinmux tokens; the include
-  // must precede them. Emitted when the display SPI pins are overridden.
-  if (wiring?.sck !== undefined && wiring?.mosi !== undefined) {
-    lines.splice(2, 0, '#include <zephyr/dt-bindings/pinctrl/esp32s3-pinctrl.h>', '');
-  }
-
-  const block = (label: string, extra: string[] = []): void => {
-    lines.push(`&${label} {`);
-    lines.push(`    status = "okay";`);
-    for (const e of extra) lines.push(`    ${e}`);
-    lines.push('};');
-    lines.push('');
-  };
-
-  if (usage.usesI2c && chip.i2c) {
-    for (const c of chip.i2c.controllers) block(c.nodeLabel);
-  }
-  if (usage.usesSpi && chip.spi) {
-    for (const c of chip.spi.controllers) block(c.nodeLabel);
-  }
-  if (usage.usesUart && chip.uart) {
-    for (const c of chip.uart.controllers) block(c.nodeLabel);
-  }
-  // DAC: enable the chip's DAC device node when the program uses dac.*. The
-  // lowering references DEVICE_DT_GET(DT_NODELABEL(<dac.device>)).
-  if (usage.usesDac && chip.dac) {
-    block(chip.dac.device);
-  }
-  if (display) {
-    // Emit a full display DT node definition. Boards like the ESP32 devkit
-    // have no display node in their base DT, so a bare `&display0 { status }`
-    // fails (the nodelabel doesn't exist). Define the node attached to a SPI
-    // controller with the panel's compatible string + dimensions. The pin
-    // wiring (cs/dc/rst) uses ESP32 GPIO defaults from the demo config; a
-    // real board overlay would carry its own binding.
-    // An XPT2046 on the same bus needs its CS as the second cs-gpios entry,
-    // so thread it into the display block (DT assignment replaces the whole
-    // property — both entries must be written together).
-    emitDisplayNode(
-      lines,
-      display,
-      wiring,
-      touch?.controller === 'xpt2046' ? (touch?.cs ?? DEFAULT_XPT2046_CS) : undefined,
-    );
-  }
-  // Touch — FT6336U capacitive on I2C (references DT_NODELABEL(ft6336u)) or
-  // XPT2046 resistive on the display's SPI bus (references
-  // DT_NODELABEL(xpt2046)). Same rationale as the display node: the bare
-  // devkit has no such node. Gated on usesTouch (not usesI2c/chip.i2c) so it
-  // emits even when the chip descriptor doesn't declare bus controllers.
-  if (usage.usesTouch) {
-    emitTouchNode(lines, touch, display);
-  }
-
-  // Preferences (ZMS settings backend): point the settings subsystem at the
-  // board's storage_partition. The backend looks for /chosen
-  // zephyr,settings-partition first, then falls back to a fixed-partition
-  // labeled storage_partition — most Zephyr boards define that label, so this
-  // 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('');
-  }
-
-  // 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.
-  if (usage.psram) {
-    lines.push('&psram0 {');
-    lines.push('    status = "okay";');
-    lines.push('    size = <(DT_SIZE_M(8))>;');
-    lines.push('};');
-    lines.push('');
-  }
-
-  return lines.join('\n');
-}
-
-/**
- * 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
- * DBI SPI bridge. Pin wiring comes from the display config (cs/dc/rst);
- * defaults match the demo-st wiring if absent. The compatible string + node
- * props come from the profile's panel controller (st7796s carries the required
- * pgc/ngc gamma + madctl; ili9341's binding defaults everything else).
- *
- * spiTouchCs: when an XPT2046 SPI touch controller shares the bus, its CS is
- * appended as the second cs-gpios entry (the touch node uses reg = <1>) — DT
- * property assignment replaces, so both entries must be written together.
- */
-function emitDisplayNode(
-  lines: string[],
-  display: ZephyrDisplayProfile,
-  wiring?: DisplayWiring,
-  spiTouchCs?: number,
-): void {
-  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 freq = wiring?.spiFrequency ?? 80000000;
-  // DT node describes the NATIVE panel geometry; the effective (rotated)
-  // dimensions live in the display profile.
-  const nativeW = display.nativeWidth ?? display.width;
-  const nativeH = display.nativeHeight ?? display.height;
-  const sck = wiring?.sck;
-  const mosi = wiring?.mosi;
-  const miso = wiring?.miso;
-  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
-  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
-  // The board's spim2_default pinctrl group usually targets the devkitc's
-  // default SPI pins (SCLK=12/MOSI=11), which rarely match the display's
-  // wiring. When the config declares spiPins, override the pinctrl groups to
-  // remux the controller onto the panel's actual pins. Raw ESP32_PINMUX()
-  // macros are used instead of the named SPIM2_*_GPIOxx tokens because the
-  // bindings header omits GPIOs 22-25 from those lists.
-  if (sck !== undefined && mosi !== undefined) {
-    // 'spi2' → pinctrl group 'spim2_default' (ESP32 SPI-master naming).
-    const pinctrlGroup = bus.replace(/^spi(\d)$/, 'spim$1') + '_default';
-    lines.push(`&${pinctrlGroup} {`);
-    lines.push('    group1 {');
-    lines.push(`        pinmux = <ESP32_PINMUX(${miso ?? 19}, ESP_FSPIQ_IN, ESP_NOSIG)>,`);
-    lines.push(`                 <ESP32_PINMUX(${sck}, ESP_NOSIG, ESP_FSPICLK_OUT)>,`);
-    lines.push('                 <ESP32_PINMUX(10, ESP_NOSIG, ESP_FSPICS0_OUT)>;');
-    lines.push('    };');
-    lines.push('    group2 {');
-    lines.push(`        pinmux = <ESP32_PINMUX(${mosi}, ESP_NOSIG, ESP_FSPID_OUT)>;`);
-    lines.push('        output-low;');
-    lines.push('    };');
-    lines.push('};');
-    lines.push('');
-  }
-  lines.push('&dma {');
-  lines.push('    status = "okay";');
-  lines.push('};');
-  lines.push('');
-  lines.push(`&${bus} {`);
-  lines.push('    status = "okay";');
-  lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>${spiTouchCs !== undefined ? `, <&${gpioController(spiTouchCs)} ${spiTouchCs} GPIO_ACTIVE_LOW>` : ''};`);
-  // Enable GDMA for the SPI2 host. The ESP32 SPI driver uses DMA only when
-  // dma-enabled is set AND dmas wires tx/rx channels to the GDMA controller;
-  // without it, transfers run PIO through the 64-byte FIFO (~4MHz effective at
-  // 80MHz requested). The GDMA driver allocates channels per peripheral based
-  // on spi2's dma-host=<0> (set in the SoC dtsi), so the channel cells are the
-  // GDMA instance's rx/tx slot ids (2 here = an SPI2-dedicated pair; the GDMA
-  // binding's #dma-cells = <1> carries the channel).
-  lines.push('    dma-enabled;');
-  lines.push('    dmas = <&dma 0>, <&dma 1>;');
-  lines.push('    dma-names = "rx", "tx";');
-  lines.push('};');
-  lines.push('');
-  lines.push('/ {');
-  lines.push('    mipi_dbi: mipi-dbi {');
-  lines.push('        compatible = "zephyr,mipi-dbi-spi";');
-  lines.push(`        spi-dev = <&${bus}>;`);
-  lines.push(`        dc-gpios = <&${gpioController(dc)} ${dc} GPIO_ACTIVE_HIGH>;`);
-  lines.push(`        reset-gpios = <&${gpioController(rst)} ${rst} GPIO_ACTIVE_LOW>;`);
-  lines.push('        write-only;');
-  lines.push('        #address-cells = <1>;');
-  lines.push('        #size-cells = <0>;');
-  lines.push(`        ${display.dtLabel}: display@0 {`);
-  lines.push(`            compatible = "${compatible}";`);
-  lines.push('            reg = <0>;');
-            lines.push(`            mipi-max-frequency = <${freq}>;`);
-            lines.push('            mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE";');
-            // Required by the lcd-controller binding (Zephyr 4.x): 0 = RGB565,
-            // matching upstream ILI9341 boards (esp_wrover_kit) and the C++
-            // runtime, which drives these SPI TFTs as RGB565.
-            lines.push('            pixel-format = <0>;');
-  lines.push(`            width = <${nativeW}>;`);
-  lines.push(`            height = <${nativeH}>;`);
-  if (controller === 'st7796s') {
-    // MADCTL: rotation 1 (landscape, MV=1) + BGR bit, matching the adapter's
-    // direct-drive init (0x28). The DT copy keeps the stock driver's init
-    // consistent if it is ever exercised.
-    lines.push('            madctl = <0x28>;');
-    lines.push('            pgc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
-    lines.push('            ngc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
-  } else {
-    // ILI9341: the ilitek,ili9341 binding carries defaults for every register
-    // (gamma, power, porch) and expresses orientation via `rotation` (degrees)
-    // instead of a raw MADCTL — no panel-specific props are required.
-    lines.push(`            rotation = <${display.rotation ?? 0}>;`);
-  }
-  lines.push('        };');
-  lines.push('    };');
-  lines.push('};');
-  lines.push('');
-  // Backlight node: emit only when the config provides a backlight GPIO. The
-  // pin was previously hardcoded to 4, which collided with the FT6336U
-  // reset-gpios on the same pin (demo-st's backlight is hardwired to 3.3V, so
-  // no backlight node is correct there). When present, use the configured pin
-  // and the profile's alias name so the display adapter can drive it.
-  const blPin = wiring?.backlightPin;
-  if (display.backlight && blPin !== undefined) {
-    lines.push('/ {');
-    lines.push('    aliases {');
-    lines.push(`        ${display.backlight} = &bl_led;`);
-    lines.push('    };');
-    lines.push('    bl_gpio: bl-gpio-leds {');
-    lines.push('        compatible = "gpio-leds";');
-    lines.push('        bl_led: led {');
-    lines.push(`            gpios = <&${gpioController(blPin)} ${blPin} GPIO_ACTIVE_HIGH>;`);
-    lines.push('        };');
-    lines.push('    };');
-    lines.push('};');
-    lines.push('');
-  }
-}
-
-/** Default XPT2046 CS/IRQ pins (ESP32-S3 GPIOs clear of the demo-st display
- *  wiring: 5/17/16/15 and the remuxed SPI pins). Config values override. */
-const DEFAULT_XPT2046_CS = 6;
-const DEFAULT_XPT2046_IRQ = 7;
-
-/**
- * Emit the touch DT node for the configured controller.
- *
- * FT6336U (capacitive, I2C): node on i2c0 at the FT6336U default address
- * (0x38); the C++ touch adapter reads it via i2c_write_read_dt.
- *
- * XPT2046 (resistive, SPI): node on the display's SPI bus as CS index 1. The
- * in-tree xptek,xpt2046 binding (drivers/input) is register-matched for the
- * raw SPI access — CONFIG_INPUT stays off, so the in-tree input driver does
- * not build and the adapter owns the chip (same pattern as FT6336U reusing
- * the ft5336 binding). The binding requires int-gpios, touchscreen-size-*,
- * and min/max calibration props, so defaults are filled for anything the
- * config omits.
- */
-function emitTouchNode(
-  lines: string[],
-  touch: TouchWiring | undefined,
-  display: ZephyrDisplayProfile | undefined,
-): void {
-  if (touch?.controller === 'xpt2046') {
-    emitXpt2046Node(lines, touch, display);
-    return;
-  }
-  emitFt6336uNode(lines, touch);
-}
-
-/** FT6336U capacitive touch node on the first I2C controller. */
-function emitFt6336uNode(lines: string[], touch?: TouchWiring): void {
-  const irq = touch?.irq ?? 15;
-  const resetPin = touch?.resetPin;
-  const sda = touch?.sda;
-  const scl = touch?.scl;
-  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
-  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
-  // Zephyr has no ft6336 binding — the FT6336U is register-compatible with the
-  // ft5336 binding (same Focaltech register map: TD_STATUS at 0x02, coordinate
-  // registers 0x03-0x06). The C++ touch adapter reads these directly via I2C,
-  // so the binding just needs to exist for the DT node to resolve.
-  // When SDA/SCL are provided, remux the I2C bus to those pins via pinctrl
-  // (the board's default I2C pins rarely match a breakout's wiring).
-  if (sda !== undefined && scl !== undefined) {
-    lines.push('&pinctrl {');
-    lines.push('    i2c0_touch: i2c0_touch {');
-    lines.push('        group1 {');
-    lines.push(`            pinmux = <I2C0_SDA_GPIO${sda}>, <I2C0_SCL_GPIO${scl}>;`);
-    lines.push('            bias-pull-up;');
-    lines.push('            drive-open-drain;');
-    lines.push('        };');
-    lines.push('    };');
-    lines.push('};');
-    lines.push('');
-    lines.push('&i2c0 {');
-    lines.push('    status = "okay";');
-    lines.push('    pinctrl-0 = <&i2c0_touch>;');
-    lines.push('    pinctrl-names = "default";');
-  } else {
-    lines.push('&i2c0 {');
-    lines.push('    status = "okay";');
-  }
-  lines.push('    ft6336u: ft6336u@38 {');
-  lines.push('        compatible = "focaltech,ft5336";');
-  lines.push('        reg = <0x38>;');
-  // NOTE: int-gpios is intentionally omitted. The ft5336 Zephyr driver
-  // registers a GPIO interrupt on int-gpios, which triggers an assertion
-  // failure in the ESP32 interrupt controller (VECDESC_FL_SHARED conflict).
-  // The cuttlefish touch adapter polls touch_isTouched() via I2C every frame
-  // — it never uses the IRQ pin, so the interrupt registration is unnecessary.
-  if (resetPin !== undefined) {
-    lines.push(`        reset-gpios = <&${gpioController(resetPin)} ${resetPin} GPIO_ACTIVE_LOW>;`);
-  }
-  lines.push('    };');
-  lines.push('};');
-  lines.push('');
-}
-
-/** XPT2046 resistive touch node on the display's SPI bus (CS index 1). */
-function emitXpt2046Node(
-  lines: string[],
-  touch: TouchWiring,
-  display: ZephyrDisplayProfile | undefined,
-): void {
-  const bus = display?.busLabel ?? 'spi2';
-  const cs = touch.cs ?? DEFAULT_XPT2046_CS;
-  const irq = touch.irq ?? DEFAULT_XPT2046_IRQ;
-  const cal = touch.calibration;
-  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
-  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
-  const zThreshold = touch.minPressure ?? 400;
-  // touchscreen-size-* describe the panel the touch layer sits on (the display
-  // profile's effective size); a touch-only build falls back to the 12-bit
-  // full-scale range so the binding's required props still resolve.
-  const sizeX = display?.width ?? cal?.xMax ?? 320;
-  const sizeY = display?.height ?? cal?.yMax ?? 240;
-  // The display block already wrote cs-gpios with both entries (its CS at
-  // index 0, the touch CS at index 1). When there is no display block, enable
-  // the bus here with the touch CS as the only entry.
-  if (!display) {
-    lines.push(`&${bus} {`);
-    lines.push('    status = "okay";');
-    lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>;`);
-    lines.push('};');
-    lines.push('');
-  }
-  lines.push(`&${bus} {`);
-  lines.push('    xpt2046: xpt2046@1 {');
-  lines.push('        compatible = "xptek,xpt2046";');
-  lines.push('        reg = <1>;');
-  // The XPT2046 datasheet max SPI clock is 2.5MHz — the panel bus may run at
-  // 80MHz, but this node's spi-max-frequency gates only its own transactions
-  // (the adapter's SPI_DT_SPEC picks it up).
-  lines.push('        spi-max-frequency = <2500000>;');
-  lines.push(`        int-gpios = <&${gpioController(irq)} ${irq} GPIO_ACTIVE_LOW>;`);
-  lines.push(`        touchscreen-size-x = <${sizeX}>;`);
-  lines.push(`        touchscreen-size-y = <${sizeY}>;`);
-  lines.push(`        min-x = <${cal?.xMin ?? 0}>;`);
-  lines.push(`        max-x = <${cal?.xMax ?? 4095}>;`);
-  lines.push(`        min-y = <${cal?.yMin ?? 0}>;`);
-  lines.push(`        max-y = <${cal?.yMax ?? 4095}>;`);
-  lines.push(`        z-threshold = <${zThreshold}>;`);
-  lines.push('    };');
-  lines.push('};');
-  lines.push('');
-}
+// ---------------------------------------------------------------------------
+// Devicetree overlay generator
+//
+// Generates <project>/app/boards/<board>.overlay — the standard Zephyr overlay
+// path. Content is additive: for each used peripheral with a DT binding the chip
+// 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
+// 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 type { ZephyrChipDescriptor } from '../chips/types.js';
+import type { ZephyrDisplayProfile } from '../display/profiles.js';
+import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
+import type { KconfigUsage } from './kconfig.js';
+
+/**
+ * Generate the overlay source for a board + usage. Returns the overlay text
+ * (caller writes it to app/boards/<board>.overlay via writeIfChanged).
+ */
+/** Display wiring from cuttlefish.config.ts (cs/dc/rst/spiFrequency/spiPins). */
+export interface DisplayWiring {
+  cs?: number;
+  dc?: number;
+  rst?: number;
+  /** Tearing-effect (TE) GPIO from display.tearingEffectPin — emitted as
+   *  te-gpios on the display DT node. Opt-in; most boards don't wire TE. */
+  tearingEffectPin?: number;
+  spiFrequency?: number;
+  /** SPI bus pins. When present, the overlay remuxes the SPI controller's
+   *  pinctrl to these pins (the board defaults rarely match a breakout's
+   *  wiring — e.g. demo-st's panel is on SCK=18/MOSI=23, not the devkitc
+   *  default 12/11). */
+  sck?: number;
+  mosi?: number;
+  miso?: number;
+  /** Optional GPIO driving the panel backlight. When set, the overlay emits a
+   *  `gpio-leds` node + DT alias (named by the profile's `backlight`) so the
+   *  display adapter can drive it high at init. When absent (e.g. the panel's
+   *  backlight is hardwired to 3.3V), no node or alias is emitted — the C++
+   *  backlight init is guarded by `DT_HAS_ALIAS` and compiles away. */
+  backlightPin?: number;
+}
+
+/** Touch wiring from cuttlefish.config.ts (irq/resetPin/sda/scl; cs for SPI
+ *  resistive controllers, calibration for the XPT2046 DT binding). */
+export interface TouchWiring {
+  /** Touch controller kind — selects the DT node shape (FT6336U node on I2C0
+   *  vs XPT2046 node on the display's SPI bus). Default 'ft6336u'. */
+  controller?: 'ft6336u' | 'xpt2046';
+  irq?: number;
+  resetPin?: number;
+  sda?: number;
+  scl?: number;
+  /** XPT2046 only: SPI CS pin (second cs-gpios entry on the panel's bus). */
+  cs?: number;
+  /** XPT2046 only: raw ADC calibration — feeds the binding's min-x/max-x/
+   *  min-y/max-y (required props). Defaults span the full 12-bit range. */
+  calibration?: { xMin: number; xMax: number; yMin: number; yMax: number };
+  /** XPT2046 only: pen-detect Z1 threshold (binding's z-threshold). Resistive
+   *  panels need a few hundred 12-bit counts; default 400. */
+  minPressure?: number;
+}
+
+export interface OverlayDiagnostic {
+  severity: "warning" | "error";
+  message: string;
+}
+
+export function generateOverlay(
+  chip: ZephyrChipDescriptor,
+  usage: KconfigUsage,
+  display: ZephyrDisplayProfile | undefined,
+  wiring?: DisplayWiring,
+  touch?: TouchWiring,
+  diagnostics: OverlayDiagnostic[] = [],
+): string {
+  // An I2C touch controller with no explicit bus pins: the overlay enables
+  // i2c0 and instantiates the node, but nothing remuxes the controller to
+  // the wired SDA/SCL (the board's default I2C pins rarely match a
+  // breakout). Every I2C read then fails and touch silently does nothing —
+  // surface it at build time instead of leaving it to a multimeter.
+  if (touch && touch.controller !== 'xpt2046' && (touch.sda === undefined || touch.scl === undefined)) {
+    diagnostics.push({
+      severity: "warning",
+      message: `touch: I2C controller '${touch.controller}' has no sda/scl pins in cuttlefish.config.ts — the overlay enables the bus without a pin assignment, so the controller may never answer. Add touch.sda and touch.scl (the board's default I2C pins are rarely the wired ones).`,
+    });
+  }
+  const lines: string[] = [
+    '/* Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts. */',
+    '/* Enables peripherals the program uses. West merges this over the board DT. */',
+    '',
+  ];
+
+  // Pinctrl override blocks reference the esp32s3 pinmux tokens; the include
+  // must precede them. Emitted when the display SPI pins are overridden.
+  if (wiring?.sck !== undefined && wiring?.mosi !== undefined) {
+    lines.splice(2, 0, '#include <zephyr/dt-bindings/pinctrl/esp32s3-pinctrl.h>', '');
+  }
+
+  const block = (label: string, extra: string[] = []): void => {
+    lines.push(`&${label} {`);
+    lines.push(`    status = "okay";`);
+    for (const e of extra) lines.push(`    ${e}`);
+    lines.push('};');
+    lines.push('');
+  };
+
+  if (usage.usesI2c && chip.i2c) {
+    for (const c of chip.i2c.controllers) block(c.nodeLabel);
+  }
+  if (usage.usesSpi && chip.spi) {
+    for (const c of chip.spi.controllers) block(c.nodeLabel);
+  }
+  if (usage.usesUart && chip.uart) {
+    for (const c of chip.uart.controllers) block(c.nodeLabel);
+  }
+  // DAC: enable the chip's DAC device node when the program uses dac.*. The
+  // lowering references DEVICE_DT_GET(DT_NODELABEL(<dac.device>)).
+  if (usage.usesDac && chip.dac) {
+    block(chip.dac.device);
+  }
+  if (display) {
+    // Emit a full display DT node definition. Boards like the ESP32 devkit
+    // have no display node in their base DT, so a bare `&display0 { status }`
+    // fails (the nodelabel doesn't exist). Define the node attached to a SPI
+    // controller with the panel's compatible string + dimensions. The pin
+    // wiring (cs/dc/rst) uses ESP32 GPIO defaults from the demo config; a
+    // real board overlay would carry its own binding.
+    // An XPT2046 on the same bus needs its CS as the second cs-gpios entry,
+    // so thread it into the display block (DT assignment replaces the whole
+    // property — both entries must be written together).
+    emitDisplayNode(
+      lines,
+      display,
+      wiring,
+      touch?.controller === 'xpt2046' ? (touch?.cs ?? DEFAULT_XPT2046_CS) : undefined,
+    );
+  }
+  // Touch — FT6336U capacitive on I2C (references DT_NODELABEL(ft6336u)) or
+  // XPT2046 resistive on the display's SPI bus (references
+  // DT_NODELABEL(xpt2046)). Same rationale as the display node: the bare
+  // devkit has no such node. Gated on usesTouch (not usesI2c/chip.i2c) so it
+  // emits even when the chip descriptor doesn't declare bus controllers.
+  if (usage.usesTouch) {
+    emitTouchNode(lines, touch, display);
+  }
+
+  // Preferences (ZMS settings backend): point the settings subsystem at the
+  // board's storage_partition. The backend looks for /chosen
+  // zephyr,settings-partition first, then falls back to a fixed-partition
+  // labeled storage_partition — most Zephyr boards define that label, so this
+  // 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('');
+  }
+
+  // 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.
+  if (usage.psram) {
+    lines.push('&psram0 {');
+    lines.push('    status = "okay";');
+    lines.push('    size = <(DT_SIZE_M(8))>;');
+    lines.push('};');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * 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
+ * DBI SPI bridge. Pin wiring comes from the display config (cs/dc/rst);
+ * defaults match the demo-st wiring if absent. The compatible string + node
+ * props come from the profile's panel controller (st7796s carries the required
+ * pgc/ngc gamma + madctl; ili9341's binding defaults everything else).
+ *
+ * spiTouchCs: when an XPT2046 SPI touch controller shares the bus, its CS is
+ * appended as the second cs-gpios entry (the touch node uses reg = <1>) — DT
+ * property assignment replaces, so both entries must be written together.
+ */
+function emitDisplayNode(
+  lines: string[],
+  display: ZephyrDisplayProfile,
+  wiring?: DisplayWiring,
+  spiTouchCs?: number,
+): void {
+  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 freq = wiring?.spiFrequency ?? 80000000;
+  // DT node describes the NATIVE panel geometry; the effective (rotated)
+  // dimensions live in the display profile.
+  const nativeW = display.nativeWidth ?? display.width;
+  const nativeH = display.nativeHeight ?? display.height;
+  const sck = wiring?.sck;
+  const mosi = wiring?.mosi;
+  const miso = wiring?.miso;
+  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
+  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
+  // The board's spim2_default pinctrl group usually targets the devkitc's
+  // default SPI pins (SCLK=12/MOSI=11), which rarely match the display's
+  // wiring. When the config declares spiPins, override the pinctrl groups to
+  // remux the controller onto the panel's actual pins. Raw ESP32_PINMUX()
+  // macros are used instead of the named SPIM2_*_GPIOxx tokens because the
+  // bindings header omits GPIOs 22-25 from those lists.
+  if (sck !== undefined && mosi !== undefined) {
+    // 'spi2' → pinctrl group 'spim2_default' (ESP32 SPI-master naming).
+    const pinctrlGroup = bus.replace(/^spi(\d)$/, 'spim$1') + '_default';
+    lines.push(`&${pinctrlGroup} {`);
+    lines.push('    group1 {');
+    lines.push(`        pinmux = <ESP32_PINMUX(${miso ?? 19}, ESP_FSPIQ_IN, ESP_NOSIG)>,`);
+    lines.push(`                 <ESP32_PINMUX(${sck}, ESP_NOSIG, ESP_FSPICLK_OUT)>,`);
+    lines.push('                 <ESP32_PINMUX(10, ESP_NOSIG, ESP_FSPICS0_OUT)>;');
+    lines.push('    };');
+    lines.push('    group2 {');
+    lines.push(`        pinmux = <ESP32_PINMUX(${mosi}, ESP_NOSIG, ESP_FSPID_OUT)>;`);
+    lines.push('        output-low;');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+  }
+  lines.push('&dma {');
+  lines.push('    status = "okay";');
+  lines.push('};');
+  lines.push('');
+  lines.push(`&${bus} {`);
+  lines.push('    status = "okay";');
+  lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>${spiTouchCs !== undefined ? `, <&${gpioController(spiTouchCs)} ${spiTouchCs} GPIO_ACTIVE_LOW>` : ''};`);
+  // Enable GDMA for the SPI2 host. The ESP32 SPI driver uses DMA only when
+  // dma-enabled is set AND dmas wires tx/rx channels to the GDMA controller;
+  // without it, transfers run PIO through the 64-byte FIFO (~4MHz effective at
+  // 80MHz requested). The GDMA driver allocates channels per peripheral based
+  // on spi2's dma-host=<0> (set in the SoC dtsi), so the channel cells are the
+  // GDMA instance's rx/tx slot ids (2 here = an SPI2-dedicated pair; the GDMA
+  // binding's #dma-cells = <1> carries the channel).
+  lines.push('    dma-enabled;');
+  lines.push('    dmas = <&dma 0>, <&dma 1>;');
+  lines.push('    dma-names = "rx", "tx";');
+  lines.push('};');
+  lines.push('');
+  lines.push('/ {');
+  lines.push('    mipi_dbi: mipi-dbi {');
+  lines.push('        compatible = "zephyr,mipi-dbi-spi";');
+  lines.push(`        spi-dev = <&${bus}>;`);
+  lines.push(`        dc-gpios = <&${gpioController(dc)} ${dc} GPIO_ACTIVE_HIGH>;`);
+  lines.push(`        reset-gpios = <&${gpioController(rst)} ${rst} GPIO_ACTIVE_LOW>;`);
+  lines.push('        write-only;');
+  lines.push('        #address-cells = <1>;');
+  lines.push('        #size-cells = <0>;');
+  lines.push(`        ${display.dtLabel}: display@0 {`);
+  lines.push(`            compatible = "${compatible}";`);
+  lines.push('            reg = <0>;');
+            if (wiring?.tearingEffectPin !== undefined) {
+              const tePin = wiring.tearingEffectPin!;
+              // Tearing-effect input on the display node: GPIO_DT_SPEC_GET(
+              // DT_NODELABEL(display0), te_gpios) in the adapter. Opt-in —
+              // most modules don't break the TE pad out.
+              lines.push(`            te-gpios = <&${gpioController(tePin)} ${tePin} GPIO_ACTIVE_HIGH>;`);
+            }
+            lines.push(`            mipi-max-frequency = <${freq}>;`);
+            lines.push('            mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE";');
+            // Required by the lcd-controller binding (Zephyr 4.x): 0 = RGB565,
+            // matching upstream ILI9341 boards (esp_wrover_kit) and the C++
+            // runtime, which drives these SPI TFTs as RGB565.
+            lines.push('            pixel-format = <0>;');
+  lines.push(`            width = <${nativeW}>;`);
+  lines.push(`            height = <${nativeH}>;`);
+  if (controller === 'st7796s') {
+    // MADCTL: rotation 1 (landscape, MV=1) + BGR bit, matching the adapter's
+    // direct-drive init (0x28). The DT copy keeps the stock driver's init
+    // consistent if it is ever exercised.
+    lines.push('            madctl = <0x28>;');
+    lines.push('            pgc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
+    lines.push('            ngc = [f0 09 0b 06 04 2e 46 46 39 13 15 12 15 12];');
+  } else {
+    // ILI9341: the ilitek,ili9341 binding carries defaults for every register
+    // (gamma, power, porch) and expresses orientation via `rotation` (degrees)
+    // instead of a raw MADCTL — no panel-specific props are required.
+    lines.push(`            rotation = <${display.rotation ?? 0}>;`);
+  }
+  lines.push('        };');
+  lines.push('    };');
+  lines.push('};');
+  lines.push('');
+  // Backlight node: emit only when the config provides a backlight GPIO. The
+  // pin was previously hardcoded to 4, which collided with the FT6336U
+  // reset-gpios on the same pin (demo-st's backlight is hardwired to 3.3V, so
+  // no backlight node is correct there). When present, use the configured pin
+  // and the profile's alias name so the display adapter can drive it.
+  const blPin = wiring?.backlightPin;
+  if (display.backlight && blPin !== undefined) {
+    lines.push('/ {');
+    lines.push('    aliases {');
+    lines.push(`        ${display.backlight} = &bl_led;`);
+    lines.push('    };');
+    lines.push('    bl_gpio: bl-gpio-leds {');
+    lines.push('        compatible = "gpio-leds";');
+    lines.push('        bl_led: led {');
+    lines.push(`            gpios = <&${gpioController(blPin)} ${blPin} GPIO_ACTIVE_HIGH>;`);
+    lines.push('        };');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+  }
+}
+
+/** Default XPT2046 CS/IRQ pins (ESP32-S3 GPIOs clear of the demo-st display
+ *  wiring: 5/17/16/15 and the remuxed SPI pins). Config values override. */
+const DEFAULT_XPT2046_CS = 6;
+const DEFAULT_XPT2046_IRQ = 7;
+
+/**
+ * Emit the touch DT node for the configured controller.
+ *
+ * FT6336U (capacitive, I2C): node on i2c0 at the FT6336U default address
+ * (0x38); the C++ touch adapter reads it via i2c_write_read_dt.
+ *
+ * XPT2046 (resistive, SPI): node on the display's SPI bus as CS index 1. The
+ * in-tree xptek,xpt2046 binding (drivers/input) is register-matched for the
+ * raw SPI access — CONFIG_INPUT stays off, so the in-tree input driver does
+ * not build and the adapter owns the chip (same pattern as FT6336U reusing
+ * the ft5336 binding). The binding requires int-gpios, touchscreen-size-*,
+ * and min/max calibration props, so defaults are filled for anything the
+ * config omits.
+ */
+function emitTouchNode(
+  lines: string[],
+  touch: TouchWiring | undefined,
+  display: ZephyrDisplayProfile | undefined,
+): void {
+  if (touch?.controller === 'xpt2046') {
+    emitXpt2046Node(lines, touch, display);
+    return;
+  }
+  emitFt6336uNode(lines, touch);
+}
+
+/** FT6336U capacitive touch node on the first I2C controller. */
+function emitFt6336uNode(lines: string[], touch?: TouchWiring): void {
+  const irq = touch?.irq ?? 15;
+  const resetPin = touch?.resetPin;
+  const sda = touch?.sda;
+  const scl = touch?.scl;
+  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
+  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
+  // Zephyr has no ft6336 binding — the FT6336U is register-compatible with the
+  // ft5336 binding (same Focaltech register map: TD_STATUS at 0x02, coordinate
+  // registers 0x03-0x06). The C++ touch adapter reads these directly via I2C,
+  // so the binding just needs to exist for the DT node to resolve.
+  // When SDA/SCL are provided, remux the I2C bus to those pins via pinctrl
+  // (the board's default I2C pins rarely match a breakout's wiring).
+  if (sda !== undefined && scl !== undefined) {
+    lines.push('&pinctrl {');
+    lines.push('    i2c0_touch: i2c0_touch {');
+    lines.push('        group1 {');
+    lines.push(`            pinmux = <I2C0_SDA_GPIO${sda}>, <I2C0_SCL_GPIO${scl}>;`);
+    lines.push('            bias-pull-up;');
+    lines.push('            drive-open-drain;');
+    lines.push('        };');
+    lines.push('    };');
+    lines.push('};');
+    lines.push('');
+    lines.push('&i2c0 {');
+    lines.push('    status = "okay";');
+    lines.push('    pinctrl-0 = <&i2c0_touch>;');
+    lines.push('    pinctrl-names = "default";');
+  } else {
+    lines.push('&i2c0 {');
+    lines.push('    status = "okay";');
+  }
+  lines.push('    ft6336u: ft6336u@38 {');
+  lines.push('        compatible = "focaltech,ft5336";');
+  lines.push('        reg = <0x38>;');
+  // NOTE: int-gpios is intentionally omitted. The ft5336 Zephyr driver
+  // registers a GPIO interrupt on int-gpios, which triggers an assertion
+  // failure in the ESP32 interrupt controller (VECDESC_FL_SHARED conflict).
+  // The cuttlefish touch adapter polls touch_isTouched() via I2C every frame
+  // — it never uses the IRQ pin, so the interrupt registration is unnecessary.
+  if (resetPin !== undefined) {
+    lines.push(`        reset-gpios = <&${gpioController(resetPin)} ${resetPin} GPIO_ACTIVE_LOW>;`);
+  }
+  lines.push('    };');
+  lines.push('};');
+  lines.push('');
+}
+
+/** XPT2046 resistive touch node on the display's SPI bus (CS index 1). */
+function emitXpt2046Node(
+  lines: string[],
+  touch: TouchWiring,
+  display: ZephyrDisplayProfile | undefined,
+): void {
+  const bus = display?.busLabel ?? 'spi2';
+  const cs = touch.cs ?? DEFAULT_XPT2046_CS;
+  const irq = touch.irq ?? DEFAULT_XPT2046_IRQ;
+  const cal = touch.calibration;
+  // ESP32-S3 GPIOs 0-31 are on gpio0, 32-48 on gpio1.
+  const gpioController = (pin: number) => pin <= 31 ? 'gpio0' : 'gpio1';
+  const zThreshold = touch.minPressure ?? 400;
+  // touchscreen-size-* describe the panel the touch layer sits on (the display
+  // profile's effective size); a touch-only build falls back to the 12-bit
+  // full-scale range so the binding's required props still resolve.
+  const sizeX = display?.width ?? cal?.xMax ?? 320;
+  const sizeY = display?.height ?? cal?.yMax ?? 240;
+  // The display block already wrote cs-gpios with both entries (its CS at
+  // index 0, the touch CS at index 1). When there is no display block, enable
+  // the bus here with the touch CS as the only entry.
+  if (!display) {
+    lines.push(`&${bus} {`);
+    lines.push('    status = "okay";');
+    lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>;`);
+    lines.push('};');
+    lines.push('');
+  }
+  lines.push(`&${bus} {`);
+  lines.push('    xpt2046: xpt2046@1 {');
+  lines.push('        compatible = "xptek,xpt2046";');
+  lines.push('        reg = <1>;');
+  // The XPT2046 datasheet max SPI clock is 2.5MHz — the panel bus may run at
+  // 80MHz, but this node's spi-max-frequency gates only its own transactions
+  // (the adapter's SPI_DT_SPEC picks it up).
+  lines.push('        spi-max-frequency = <2500000>;');
+  lines.push(`        int-gpios = <&${gpioController(irq)} ${irq} GPIO_ACTIVE_LOW>;`);
+  lines.push(`        touchscreen-size-x = <${sizeX}>;`);
+  lines.push(`        touchscreen-size-y = <${sizeY}>;`);
+  lines.push(`        min-x = <${cal?.xMin ?? 0}>;`);
+  lines.push(`        max-x = <${cal?.xMax ?? 4095}>;`);
+  lines.push(`        min-y = <${cal?.yMin ?? 0}>;`);
+  lines.push(`        max-y = <${cal?.yMax ?? 4095}>;`);
+  lines.push(`        z-threshold = <${zThreshold}>;`);
+  lines.push('    };');
+  lines.push('};');
+  lines.push('');
+}