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

package/src/dt-config/overlay.ts

@@ -13,6 +13,7 @@
 
 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';
 
 /**
@@ -40,12 +41,24 @@ export interface DisplayWiring {
   backlightPin?: number;
 }
 
-/** Touch wiring from cuttlefish.config.ts (irq/resetPin/sda/scl). */
+/** 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(
@@ -96,14 +109,23 @@ export function generateOverlay(
     // 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.
-    emitDisplayNode(lines, display, wiring);
+    // 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,
+    );
   }
-  // FT6336U touch on I2C — defined when the program uses touch (the UI touch
-  // adapter references DT_NODELABEL(ft6336u)). Same rationale: 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 I2C controllers (ESP32).
+  // 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);
+    emitTouchNode(lines, touch, display);
   }
 
   // Preferences (ZMS settings backend): point the settings subsystem at the
@@ -138,11 +160,26 @@ export function generateOverlay(
 }
 
 /**
- * Emit a display DT node definition. The node is attached to 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.
+ * 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): void {
+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;
@@ -163,7 +200,9 @@ function emitDisplayNode(lines: string[], display: ZephyrDisplayProfile, wiring?
   // 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) {
-    lines.push('&spim2_default {');
+    // '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)>,`);
@@ -180,9 +219,9 @@ function emitDisplayNode(lines: string[], display: ZephyrDisplayProfile, wiring?
   lines.push('    status = "okay";');
   lines.push('};');
   lines.push('');
-  lines.push('&spi2 {');
+  lines.push(`&${bus} {`);
   lines.push('    status = "okay";');
-  lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} GPIO_ACTIVE_LOW>;`);
+  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
@@ -198,25 +237,36 @@ function emitDisplayNode(lines: string[], display: ZephyrDisplayProfile, wiring?
   lines.push('/ {');
   lines.push('    mipi_dbi: mipi-dbi {');
   lines.push('        compatible = "zephyr,mipi-dbi-spi";');
-  lines.push('        spi-dev = <&spi2>;');
+  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 = "sitronix,st7796s";');
+  lines.push(`            compatible = "${compatible}";`);
   lines.push('            reg = <0>;');
-  lines.push(`            mipi-max-frequency = <${freq}>;`);
-  lines.push('            mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE";');
+            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}>;`);
-  // 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];');
+  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('};');
@@ -243,13 +293,39 @@ function emitDisplayNode(lines: string[], display: ZephyrDisplayProfile, wiring?
   }
 }
 
+/** 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 an FT6336U touch DT node on the first I2C controller. The node address
- * is the FT6336U default (0x38). The UI touch adapter references
- * DT_NODELABEL(ft6336u). Pin wiring (irq/resetPin/sda/scl) comes from the
- * touch config; defaults match the demo-st wiring if absent.
+ * 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): void {
+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;
@@ -296,3 +372,52 @@ function emitTouchNode(lines: string[], touch?: TouchWiring): void {
   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('');
+}

package/src/framework.manifest.ts

@@ -289,8 +289,13 @@ export default defineFrameworkManifest({
     },
     display: {
       supported: true,
-      partialCoverage: false,
-      unsupportedReason: undefined,
+      partialCoverage: true,
+      // Partial: mono profiles (ssd1306-zephyr) drive display.* ops via the
+      // direct GFX runtime only — no CuttlefishGFX UI rendering path. The
+      // ILI9341 UI adapter shares the ST7796S direct-drive transport with a
+      // per-controller init table (16-bit RGB565 wire format); hardware-tuned
+      // on ST7796S only. E-ink panels are out of scope at this time.
+      unsupportedReason: 'Mono panels (ssd1306) are direct-op only (no UI rendering); ili9341 UI path is ported but not yet hardware-verified; e-ink is out of scope at this time.',
       drivers: ['ili9341-zephyr', 'st7796-zephyr', 'ssd1306-zephyr'],
       colorFormat: 'rgb565',
       ops: {
@@ -499,6 +504,7 @@ export default defineFrameworkManifest({
   polyfills: {
     emitted: [
       { id: 'cuttlefish_halt', domain: 'standard', notes: 'Mapped to a k_msleep halt loop (exceptions disabled)' },
+      { id: 'wiring_compat', domain: 'standard', notes: 'HIGH/LOW/digitalRead/etc. macros routing Wiring tokens (referenced unconditionally by the UI runtime header) to the __tc_gpio_* helpers' },
       { id: 'string_methods', domain: 'embedded', notes: 'STL-free __tc_* string helpers (const char*, inline ASCII case conv, <cstring> only)' },
       { id: 'static_array', domain: 'embedded', notes: 'STL-free __tc_StaticArray<T,N> wrapper for no-<vector> mutated/struct array literals' },
       { id: 'timer_methods', domain: 'embedded', notes: 'k_timer + k_work pool (system workqueue); callbacks run in thread context' },
@@ -509,7 +515,7 @@ export default defineFrameworkManifest({
 
   toolchain: {
     backend: 'west',
-    operations: { prepare: true, compile: true, upload: true, monitor: true },
+    operations: { prepare: true, compile: true, upload: true, monitor: true, debug: true },
   },
 
   libraryResolution: {

package/src/lowering/ble.ts

@@ -393,7 +393,9 @@ export function lowerBle(op: HALOpIR): { code?: string; expression?: string } {
     case 'ble.on_read':
       // Store the typed read handler as void*; __tc_ble_attr_read casts it back
       // to the right signature based on the char's type field. reinterpret_cast
-      // (not a C-style cast) keeps this AUTOSAR-compliant under --autosar=strict.
+      // (not a C-style cast) avoids M5-0-7, but M5-0-10 still flags it — the
+      // whole type-erased table is covered by a knownPatterns deviation on
+      // that rule (see rules.ts, "BLE type-erased callback table").
       return { code: `__tc_ble.on_read[__tc_ble.current_char] = reinterpret_cast<void*>(${s(o.handler)});` };
     case 'ble.on_write':
       return { code: `__tc_ble.on_write[__tc_ble.current_char] = (${s(o.handler)});` };

package/src/strategy.ts

@@ -157,9 +157,10 @@ export class ZephyrStrategy implements PlatformStrategy {
     // program-analysis usesStdString detector doesn't see types generated by
     // the BLE lowering layer — so without forcing <string> here, any BLE server
     // with a Utf8 characteristic fails to compile ('std::string does not name a
-    // type'). Uses <string>, not <string.h>: the latter is the C flat-string
-    // header (already included for the shim's strncpy/strcmp).
-    if (uses('usesBle')) inc.push('<stdlib.h>', '<string.h>', '<string>', '<zephyr/bluetooth/bluetooth.h>', '<zephyr/bluetooth/conn.h>', '<zephyr/bluetooth/gatt.h>', '<zephyr/bluetooth/uuid.h>');
+    // type'). <cstdlib>/<cstring> (not <stdlib.h>/<string.h>) back the shim's
+    // strtol/strcmp/strncpy — the same AUTOSAR-compliant spelling the HTTP,
+    // MQTT, and Preferences paths below already use.
+    if (uses('usesBle')) inc.push('<cstdlib>', '<cstring>', '<string>', '<zephyr/bluetooth/bluetooth.h>', '<zephyr/bluetooth/conn.h>', '<zephyr/bluetooth/gatt.h>', '<zephyr/bluetooth/uuid.h>');
     // Display: the analyzer's usesDisplay flag (set by display.* hal-ops) drives
     // this include. When ctx.analysis is absent (capability query), uses()
     // defaults to true so a real build never strips it.
@@ -407,21 +408,29 @@ export class ZephyrStrategy implements PlatformStrategy {
       '}',
     );
 
-    // Safety shims: when the program uses @typecad/safety, provide __tc_gpio_read
-    // / __tc_gpio_write backed by the raw controller (a best-effort read that
-    // does not depend on a pin having a DT spec). __tc_delay_us uses k_busy_wait.
+    // GPIO read shim: the wiring_compat polyfill routes the UI runtime
+    // header's unconditional digitalRead() poll (init-press-input.ts) to
+    // __tc_gpio_read, so the definition must NOT be gated on @typecad/safety.
+    // The signature is `int` to match wiring_compat's forward declaration —
+    // a uint32_t definition alongside it would leave the declared int
+    // overload undefined (int wins overload resolution for small integer
+    // arguments).
     //
-    // The pin is a RUNTIME value here (safety's voter passes whatever pin it
-    // was handed), so the controller cannot be baked in as a single DT_NODELABEL
-    // on a multi-controller SoC (ESP32-S3: pins 0–31 → gpio0, 32–48 → gpio1).
-    // Emit a tiny __tc_gpio_dev(pin) dispatcher that resolves the owning
-    // controller's device per pin; single-controller SoCs collapse it to a
-    // one-liner. Each DT_NODELABEL is still compile-time-resolved per branch, so
-    // it is always statically valid.
+    // The pin is a RUNTIME value here (the UI pin-watch table and safety's
+    // voter pass whatever pin they were handed), so the controller cannot be
+    // baked in as a single DT_NODELABEL on a multi-controller SoC (ESP32-S3:
+    // pins 0–31 → gpio0, 32–48 → gpio1). Emit a tiny __tc_gpio_dev(pin)
+    // dispatcher that resolves the owning controller's device per pin;
+    // single-controller SoCs collapse it to a one-liner. Each DT_NODELABEL is
+    // still compile-time-resolved per branch, so it is always statically valid.
+    lines.push(...emitGpioDevDispatcher(chip));
+    lines.push(
+      'inline int __tc_gpio_read(int pin) { return gpio_pin_get_raw(__tc_gpio_dev(static_cast<uint32_t>(pin)), static_cast<gpio_pin_t>(pin)); }',
+    );
+    // __tc_gpio_write / __tc_delay_us are only referenced via @typecad/safety
+    // lowering, so they stay gated on it.
     if (program && programUsesSafety(program)) {
-      lines.push(...emitGpioDevDispatcher(chip));
       lines.push(
-        'inline int __tc_gpio_read(uint32_t pin) { return gpio_pin_get_raw(__tc_gpio_dev(pin), pin); }',
         'inline void __tc_gpio_write(uint32_t pin, uint32_t value) { gpio_pin_set_raw(__tc_gpio_dev(pin), pin, value); }',
         '#ifndef __TC_DELAY_US_DEFINED',
         '#define __TC_DELAY_US_DEFINED',
@@ -860,6 +869,62 @@ export class ZephyrStrategy implements PlatformStrategy {
     return '';
   }
 
+  // ── Interrupt safety ─────────────────────────────────────────────────────
+  // Zephyr ISRs run above thread context: anything that sleeps (k_msleep),
+  // pends, or takes a driver lock is illegal there (asserted by the kernel in
+  // debug builds; corrupts scheduler state otherwise). The names below are the
+  // IR-level callees cuttlefish's interrupt-analysis pass matches (the same
+  // keys ArduinoStrategy uses; timing.delay/delay_microseconds hal-ops are
+  // mapped back to the bare names by the analyzer itself).
+  isrUnsafeOperations(): Map<string, { reason: string; severity: 'warning' | 'info' }> {
+    return new Map<string, { reason: string; severity: 'warning' | 'info' }>([
+      ['delay', {
+        reason: 'delay() lowers to k_msleep(), which sleeps the calling thread — illegal in Zephyr interrupt context (submit a k_work item or arm a k_timer instead)',
+        severity: 'warning',
+      }],
+      ['delayMicroseconds', {
+        reason: 'delayMicroseconds() busy-waits the CPU for the full delay, stalling every lower-priority interrupt and the scheduler for its duration',
+        severity: 'warning',
+      }],
+      ['console.log', {
+        reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
+        severity: 'info',
+      }],
+      ['console.error', {
+        reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
+        severity: 'info',
+      }],
+      ['console.warn', {
+        reason: 'console output lowers to printk(), which is ISR-legal but slow and lock-protected (CONFIG_PRINTK_SYNC) — it adds jitter to every interrupt behind it',
+        severity: 'info',
+      }],
+      ['I2C0', {
+        reason: 'I2C transactions may sleep (driver locking + clock stretching) and are not callable from Zephyr interrupt context',
+        severity: 'warning',
+      }],
+      ['I2C1', {
+        reason: 'I2C transactions may sleep (driver locking + clock stretching) and are not callable from Zephyr interrupt context',
+        severity: 'warning',
+      }],
+      ['SPI0', {
+        reason: 'SPI transfers take driver locks and may wait on DMA completion — not safe in Zephyr interrupt context',
+        severity: 'warning',
+      }],
+      ['SPI1', {
+        reason: 'SPI transfers take driver locks and may wait on DMA completion — not safe in Zephyr interrupt context',
+        severity: 'warning',
+      }],
+      ['UART0', {
+        reason: 'UART output via uart_poll_out blocks until the TX FIFO has room — a full FIFO stalls the ISR',
+        severity: 'info',
+      }],
+      ['UART1', {
+        reason: 'UART output via uart_poll_out blocks until the TX FIFO has room — a full FIFO stalls the ISR',
+        severity: 'info',
+      }],
+    ]);
+  }
+
   ambientTypeDeclarations(): string[] {
     // Preferences is the only HAL surface the framework lowers that is used as
     // a bare global (the HAL Preferences class is exported, but the canonical
@@ -1218,7 +1283,11 @@ struct __tc_StaticArray {
         id: 'async_runtime',
         domain: 'embedded',
         requiredIncludes: [],
-        forwardDeclarations: [],
+        // Polyfill definitions emit before shimLines, but the runtime's
+        // timer bodies call millis() (defined in shimLines) — declare it
+        // first so the polyfill compiles even for programs whose source
+        // has no explicit timing call.
+        forwardDeclarations: ['unsigned long millis();'],
         helperStructs: [generateStaticAsyncRuntime(8, this.getAsyncRuntimeConfig().waitForPinEdge)],
         helperFunctions: [],
         shimMacros: [],
@@ -1325,11 +1394,12 @@ struct __tc_StaticArray {
 
   // ── Strategy-owned display/touch adapter seam ────────────────────────────
   // Zephyr owns its display + touch adapters: the UI display adapter bridges
-  // the in-tree CuttlefishGFX class to Zephyr's display_write() API (see
-  // src/display/ui-adapter.ts), and the FT6336U touch adapter drives the I2C
-  // controller via Zephyr's i2c API (src/display/touch-adapter.ts). Both live
-  // in this package so cuttlefish carries no Zephyr/Wiring-specific display or
-  // touch knowledge. Mirrors ArduinoStrategy's provides*/resolve* pattern.
+  // the in-tree CuttlefishGFX class to the panel (per-controller init + wire
+  // format, see src/display/ui-adapter.ts), and the touch adapters drive the
+  // FT6336U (I2C capacitive) and XPT2046 (SPI resistive) controllers via
+  // Zephyr's bus APIs (src/display/touch-adapter.ts). Both live in this
+  // package so cuttlefish carries no Zephyr/Wiring-specific display or touch
+  // knowledge. Mirrors ArduinoStrategy's provides*/resolve* pattern.
 
   providesDisplayAdapter(): boolean { return true; }
 

package/src/toolchain/index.ts

@@ -206,12 +206,17 @@ export const Toolchain = {
     // for either driver. Thread a non-default profile here only if a future
     // board carries a display node under a different nodelabel.
     const displayProfile = usesDisplay ? DEFAULT_ZEPHYR_DISPLAY_PROFILE : undefined;
+    // Touch controller kind comes from which DT nodelabel the emitted adapter
+    // references (FT6336U on I2C, XPT2046 on the display's SPI bus).
+    const usesTouch = uses('ft6336u') || uses('touch_');
+    const usesXpt = uses('xpt2046');
     const overlay = generateOverlay(chip, {
       usesI2c: uses('i2c_'),
       usesSpi: uses('spi_'),
       usesUart: uses('uart_'),
       usesDisplay,
-      usesTouch: uses('ft6336u') || uses('touch_'),
+      usesTouch: usesTouch || usesXpt,
+      touchController: usesXpt ? 'xpt2046' : 'ft6336u',
     }, displayProfile);
     const overlayDir = join(projectRoot, 'boards');
     mkdirSync(overlayDir, { recursive: true });
@@ -303,23 +308,49 @@ export const Toolchain = {
             backlightPin: typeof dispCfg.backlightPin === 'number' ? dispCfg.backlightPin : undefined,
           }
         : undefined;
-      // Extract touch pin wiring (irq/resetPin/sda/scl) from the config
-      // display.touch section so the DT overlay wires the I2C bus + touch node.
+      // Extract touch pin wiring from the config display.touch section so the
+      // DT overlay wires the bus + touch node. I2C (FT6336U) carries
+      // irq/resetPin/sda/scl; SPI (XPT2046) carries irq/cs + the calibration
+      // range the xptek,xpt2046 binding requires.
       const touchCfg = dispCfg?.touch as Record<string, unknown> | undefined;
-      const touchWiring: TouchWiring | undefined = touchCfg
+      const isXpt = touchCfg?.library === 'XPT2046_Touchscreen';
+      const touchCal = touchCfg?.calibration as
+        { xMin?: unknown; xMax?: unknown; yMin?: unknown; yMax?: unknown } | undefined;
+      const num = (v: unknown): number | undefined => (typeof v === 'number' ? v : undefined);
+      let touchWiring: TouchWiring | undefined = touchCfg
         ? {
-            irq: typeof touchCfg.irq === 'number' ? touchCfg.irq : undefined,
-            resetPin: typeof touchCfg.resetPin === 'number' ? touchCfg.resetPin : undefined,
-            sda: typeof touchCfg.sda === 'number' ? touchCfg.sda : undefined,
-            scl: typeof touchCfg.scl === 'number' ? touchCfg.scl : undefined,
+            controller: isXpt ? 'xpt2046' : 'ft6336u',
+            irq: num(touchCfg.irq),
+            resetPin: num(touchCfg.resetPin),
+            sda: num(touchCfg.sda),
+            scl: num(touchCfg.scl),
+            cs: num(touchCfg.cs),
+            calibration: touchCal
+              ? {
+                  xMin: num(touchCal.xMin) ?? 0,
+                  xMax: num(touchCal.xMax) ?? 4095,
+                  yMin: num(touchCal.yMin) ?? 0,
+                  yMax: num(touchCal.yMax) ?? 4095,
+                }
+              : undefined,
+            minPressure: num(touchCfg.minPressure),
           }
         : undefined;
+      // Touch controller kind for Kconfig (bus driver selection) and the DT
+      // node shape: from the config when available, else from the DT nodelabel
+      // the emitted adapter references. Forced onto touchWiring so a source
+      // scan match without a config section still emits the right node.
+      const usesXpt = isXpt || uses('xpt2046');
+      if (usesXpt) {
+        touchWiring = { controller: 'xpt2046', ...(touchWiring ?? {}) };
+      }
       const overlay = generateOverlay(chip, {
         usesI2c: uses('i2c_'),
         usesSpi: uses('spi_'),
         usesUart: uses('uart_'),
         usesDisplay,
-        usesTouch: uses('ft6336u') || uses('touch_'),
+        usesTouch: uses('ft6336u') || uses('touch_') || usesXpt,
+        touchController: usesXpt ? 'xpt2046' : 'ft6336u',
         psram: o.psram,
       }, displayProfile, wiring, touchWiring);
       const overlayDir = join(projectRoot, 'boards');

package/src/toolchain/scaffold.ts

@@ -130,8 +130,10 @@ export function scaffoldZephyrProject(projectRoot: string, debug = false, userKc
     '',
     'project(zephyr_app)',
     '',
-    '# Collect cuttlefish-emitted sources.',
-    'file(GLOB app_sources src/*.cpp src/*.c)',
+    '# Collect cuttlefish-emitted sources. CONFIGURE_DEPENDS makes CMake re-',
+    '# check the glob when the source set changes (e.g. the transpiler removes',
+    '# a stale entry), instead of linking a file list from the last configure.',
+    'file(GLOB app_sources CONFIGURE_DEPENDS src/*.cpp src/*.c)',
     '',
     'target_sources(app PRIVATE ${app_sources})',
     // When PSRAM is configured, define BOARD_HAS_PSRAM so the UI runtime's

package/src/toolchain/west-discover.ts

@@ -97,9 +97,12 @@ export function isZephyrBase(dir: string): boolean {
 // ── Strategy 1: `west` on PATH ──────────────────────────────────────────────
 
 export function discoverFromPath(): WestInstall | null {
+  // shell only on Windows (where.exe resolution through cmd) — an args array
+  // with shell: true triggers Node's DEP0190 deprecation warning on Linux/
+  // macOS, where `which` is a plain executable that needs no shell.
   const which = spawnSync(IS_WIN ? 'where' : 'which', ['west'], {
     encoding: 'utf8',
-    shell: true,
+    shell: IS_WIN,
     windowsHide: true,
   });
   if (which.status !== 0) return null;