@typecad/framework-zephyr 1.0.0-alpha.8

package/src/dt-config/kconfig.ts

@@ -0,0 +1,308 @@
+// ---------------------------------------------------------------------------
+// Kconfig fragment resolver — extracts the prj.conf symbol logic
+//
+// Previously inline in scaffold.ts as token-scanning of the emitted source.
+// Formalized here as a typed, unit-testable function keyed off a usage-analysis
+// object (the same ctx.analysis.usesX flags the strategy uses). scaffold.ts
+// calls this instead of inlining the scan, keeping prj.conf generation honest
+// and testable.
+// ---------------------------------------------------------------------------
+
+export interface KconfigUsage {
+  usesAdc?: boolean;
+  usesPwm?: boolean;
+  usesI2c?: boolean;
+  usesSpi?: boolean;
+  usesUart?: boolean;
+  usesWdt?: boolean;
+  usesBle?: boolean;
+  usesDisplay?: boolean;
+  usesPower?: boolean;
+  usesWifi?: boolean;
+  usesHttp?: boolean;
+  usesMqtt?: boolean;
+  usesPreferences?: boolean;
+  usesRandom?: boolean;
+  /** Touch controller referenced (UI touch adapter emits DT_NODELABEL(ft6336u)). */
+  usesTouch?: boolean;
+  /** PSRAM type ('opi' | 'quad') when the target board has PSRAM. Emits the
+   *  CONFIG_SPIRAM symbols so the ESP heap serves PSRAM for canvas allocations. */
+  psram?: 'opi' | 'quad';
+}
+
+/**
+ * Resolve the Kconfig symbol→value map for a prj.conf. Returns a Map preserving
+ * insertion order (callers join with '\n'). Core GPIO + C++ + workqueue symbols
+ * are always present; driver symbols are usage-gated.
+ */
+export function resolveKconfigFragments(
+  usage: KconfigUsage,
+  debug: boolean,
+): Map<string, string> {
+  const m = new Map<string, string>();
+
+  // Core driver + console.
+  m.set('CONFIG_GPIO', 'y');
+  m.set('CONFIG_PRINTK', 'y');
+  m.set('CONFIG_PRINTK_SYNC', 'y');
+  m.set('CONFIG_CONSOLE', 'y');
+
+  if (usage.usesAdc) m.set('CONFIG_ADC', 'y');
+  if (usage.usesPwm) m.set('CONFIG_PWM', 'y');
+  if (usage.usesI2c) m.set('CONFIG_I2C', 'y');
+  if (usage.usesSpi) m.set('CONFIG_SPI', 'y');
+  if (usage.usesWdt) m.set('CONFIG_WATCHDOG', 'y');
+  if (usage.usesDisplay) {
+    m.set('CONFIG_DISPLAY', 'y');
+    m.set('CONFIG_SPI', 'y');
+    m.set('CONFIG_MIPI_DBI', 'y');
+    // Enable GDMA so the ESP32 SPI driver uses DMA for panel transfers instead
+    // of PIO through the 64-byte hardware FIFO. Without DMA a full 480x320 fill
+    // takes ~110ms (effectively ~4MHz); with DMA the same transfer runs at the
+    // configured SPI clock (~80MHz) and drops into the low tens of ms. The
+    // display overlay pairs this with dma-enabled + dmas on the spi2 node.
+    m.set('CONFIG_DMA', 'y');
+    // Disable the MIPI DBI SPI bridge + ST7796S drivers. The display adapter
+    // drives the panel directly via spi_write. Binding these drivers would
+    // allocate a tearing-effect GPIO interrupt that conflicts with the SPI/I2C
+    // driver interrupts — the VECDESC_FL_SHARED assertion crashes on touch.
+    m.set('CONFIG_MIPI_DBI_SPI', 'n');
+    m.set('CONFIG_ST7796S', 'n');
+  }
+  if (usage.usesTouch) {
+    m.set('CONFIG_I2C', 'y');           // FT6336U touch on I2C
+  }
+  // PSRAM: enable the ESP SPIRAM driver + route malloc/heap to external RAM so
+  // large canvas allocations (scroll viewports, lists) can use PSRAM instead of
+  // failing in internal SRAM. Zephyr's ESP32 PSRAM support uses CONFIG_ESP_SPIRAM
+  // (not CONFIG_SPIRAM — that's an ESP-IDF symbol). The mode choice selects the
+  // PSRAM type: OCT for OPI (ESP32-S3), QUAD for quad-spi. CONFIG_ESP_SPIRAM
+  // selects SHARED_MULTI_HEAP automatically, which routes heap_caps_malloc to
+  // PSRAM. The SoC dtsi already carries the psram0 DT node.
+  if (usage.psram) {
+    m.set('CONFIG_ESP_SPIRAM', 'y');
+    if (usage.psram === 'opi') {
+      m.set('CONFIG_SPIRAM_MODE_OCT', 'y');
+    } else {
+      m.set('CONFIG_SPIRAM_MODE_QUAD', 'y');
+    }
+  }
+  // deep_sleep_pin wake needs PM + PM_DEVICE.
+  if (usage.usesPower) {
+    m.set('CONFIG_PM', 'y');
+    m.set('CONFIG_PM_DEVICE', 'y');
+  }
+  if (usage.usesWifi) {
+    // Master networking switch — every CONFIG_NET_* symbol depends on NETWORKING
+    // (without it, Kconfig silently forces them all to n).
+    m.set('CONFIG_NETWORKING', 'y');
+    m.set('CONFIG_WIFI', 'y');
+    m.set('CONFIG_WIFI_ESP32', 'y');            // ESP32-specific driver (sole WiFi target)
+    m.set('CONFIG_NET_L2_ETHERNET', 'y');
+    m.set('CONFIG_NET_IPV4', 'y');
+    m.set('CONFIG_NET_UDP', 'y');               // transitive dep of NET_DHCPV4
+    m.set('CONFIG_NET_DHCPV4', 'y');
+    // NOT CONFIG_NET_CONFIG_SETTINGS: that runs net_config_init() at boot which
+    // BLOCKS up to NET_CONFIG_INIT_TIMEOUT (default 30s) waiting for the iface
+    // to come up — but our shim brings the iface up itself in setup() (connect),
+    // so net_config waits the full 30s, then the dual management of the same
+    // iface crashes the driver. Our shim owns connectivity (net_mgmt connect/
+    // disconnect + conn_mgr monitor for L4), exactly like the standalone Zephyr
+    // WiFi samples that omit NET_CONFIG_SETTINGS.
+    m.set('CONFIG_NET_MGMT', 'y');
+    m.set('CONFIG_NET_MGMT_EVENT', 'y');        // required for the net_mgmt callbacks
+    m.set('CONFIG_NET_CONNECTION_MANAGER', 'y'); // conn_mgr — the connect portability layer
+    // Networking stack sizes. The defaults are tiny (NET_MGMT_EVENT_STACK_SIZE
+    // is 768 on non-x86) and the WiFi connect result/event handlers run on that
+    // stack — overflowing it freezes the chip mid-connect (silent hard fault,
+    // no panic dump). The official Zephyr WiFi samples (samples/net/wifi/*)
+    // bump exactly these; mirror them. MAIN_STACK 4096→5200 because esp_wifi
+    // device init is stack-hungry and 4096 is marginal on the ESP32-S3.
+    m.set('CONFIG_NET_MGMT_EVENT_STACK_SIZE', '4096');
+    m.set('CONFIG_NET_TX_STACK_SIZE', '2048');
+    m.set('CONFIG_NET_RX_STACK_SIZE', '2048');
+    m.set('CONFIG_MAIN_STACK_SIZE', '5200');
+    // NOTE: wifi.set_tx_power needs no Kconfig symbol. esp_wifi_set_max_tx_power
+    // programs the radio at runtime; its ceiling is baked into the prebuilt
+    // libphy.a / PHY init data, not a prj.conf knob. The ESP-IDF symbol
+    // ESP_PHY_MAX_WIFI_TX_POWER lives in components/esp_phy/Kconfig, which the
+    // Zephyr module integration does NOT source — assigning it here would abort
+    // the build ("undefined symbol").
+  }
+  if (usage.usesHttp) {
+    // HTTP/S rides on the networking stack. The shim does its own
+    // socket/getaddrinfo/connect, so it needs the BSD socket layer + POSIX
+    // DNS surface + the http client lib, plus the TLS sockopt layer (which
+    // selects mbedTLS) and the DNS resolver. HTTP needs the same IP base as
+    // WiFi, so this emits the networking primitives even when usesWifi is
+    // false — an http-only program still has to reach the internet. Map.set
+    // is idempotent, so overlaps with the wifi block are harmless.
+    m.set('CONFIG_NETWORKING', 'y');
+    m.set('CONFIG_NET_IPV4', 'y');
+    m.set('CONFIG_NET_DHCPV4', 'y');
+    m.set('CONFIG_NET_TCP', 'y');            // http_client_req needs a TCP socket
+    // NET_MAX_CONTEXTS caps the network 5-tuple (socket) pool — the default 6 is
+    // exhausted after a handful of sequential HTTP requests even when each is
+    // closed (closed TCP contexts linger in TIME_WAIT), and socket() then returns
+    // -EPERM. The hardware CRUD harness makes ~17 sequential requests, so raise
+    // this well above the default.
+    m.set('CONFIG_NET_MAX_CONTEXTS', '16');
+    // NET_MAX_CONN is the connection-registry pool (default 8 with v4+v6), a
+    // *separate* limit from NET_MAX_CONTEXTS. Closed TCP entries linger briefly
+    // in the registry, so rapid sequential HTTP requests exhaust the default and
+    // connect() then returns -EPERM. Pair it with NET_MAX_CONTEXTS so both the
+    // socket (5-tuple) and connection-registry pools have headroom.
+    m.set('CONFIG_NET_MAX_CONN', '16');
+    // ZVFS_OPEN_MAX must be set above 0 or socket() returns -EPERM (errno 1): the
+    // fd table is allocated to exactly ZVFS_OPEN_MAX entries, and the default 0
+    // (even with the ZVFS_OPEN_ADD_SIZE_* "min" contributors) yields zero usable
+    // descriptors. HTTP tests open/close a socket per request; give headroom over
+    // the per-subsystem contributors (NET=6, POSIX=3).
+    m.set('CONFIG_ZVFS_OPEN_MAX', '16');
+    // NET_SOCKETS is the user-facing switch for the BSD socket API + ZVFS. The
+    // shim uses bare POSIX names (connect/socket/close/getaddrinfo/freeaddrinfo)
+    // rather than the zsock_ forms; those bare names resolve under CONFIG_POSIX_API
+    // (the official samples/net/sockets/http_client sample sets exactly this).
+    // Without it, <zephyr/posix/unistd.h> gates `int close(int)` behind
+    // #ifdef CONFIG_POSIX_API and the build fails with "'close' was not declared".
+    m.set('CONFIG_NET_SOCKETS', 'y');
+    m.set('CONFIG_POSIX_API', 'y');
+    m.set('CONFIG_DNS_RESOLVER', 'y');       // getaddrinfo for hostnames
+    m.set('CONFIG_DNS_SERVER_IP_ADDRESSES', 'y');
+    m.set('CONFIG_HTTP_CLIENT', 'y');        // <zephyr/net/http/client.h> + http_client_req
+    // HTTPS via Zephyr socket TLS (IPPROTO_TLS_1_2 + SOL_TLS sockopts, driven by
+    // the shim's __tc_http_open_socket https branch). NET_SOCKETS_SOCKOPT_TLS
+    // selects mbedTLS, but its ssl layer (mbedtls_ssl_*) needs the rest of this
+    // matrix to actually link + a working TLS 1.2 protocol + key exchange.
+    m.set('CONFIG_NET_SOCKETS_SOCKOPT_TLS', 'y');
+    m.set('CONFIG_TLS_CREDENTIALS', 'y');    // tls_credential_add for caCert()
+    m.set('CONFIG_MBEDTLS', 'y');
+    m.set('CONFIG_MBEDTLS_BUILTIN', 'y');
+    // Enable TLS 1.2 via a single ciphersuite rather than the broad
+    // SSL_PROTO_TLS1_2 + KEY_EXCHANGE_ALL_ENABLED (the latter selects KEXes whose
+    // PSA_WANT_* deps are unsatisfied → Kconfig abort) or a bare
+    // SSL_PROTO_TLS1_2 (no key exchange → check_config.h "no key exchange
+    // methods defined"). A ciphersuite is the proven path the in-tree HTTPS
+    // samples use (samples/net/prometheus): it transitively selects
+    // MBEDTLS_SSL_PROTO_TLS1_2 + its one key exchange + every PSA_WANT_* key/alg
+    // that key exchange needs, with no dangling deps. ECDHE_RSA matches the test
+    // server's RSA cert (rsa:2048) and is widely offered; add more ciphersuites
+    // here to broaden server compatibility.
+    m.set('CONFIG_MBEDTLS_CIPHERSUITE_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256', 'y');
+    // Handshake/protocol buffers allocate from the mbedTLS heap; MBEDTLS_HEAP_SIZE
+    // must hold ~2x MBEDTLS_SSL_MAX_CONTENT_LEN plus working state. 65000 fits on
+    // the ESP32; mbedTLS requires the full libc and PEM (not DER) cert format.
+    m.set('CONFIG_MBEDTLS_ENABLE_HEAP', 'y');
+    m.set('CONFIG_MBEDTLS_HEAP_SIZE', '65000');
+    m.set('CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN', '16384');
+    m.set('CONFIG_MBEDTLS_PEM_CERTIFICATE_FORMAT', 'y');
+    m.set('CONFIG_PSA_CRYPTO', 'y');
+    m.set('CONFIG_REQUIRES_FULL_LIBC', 'y');
+    // The http client + TLS handshake are stack-hungry; mirror the wifi bumps
+    // (NET_*_STACK_SIZE) and keep the larger main-stack value (TLS handshake
+    // overflows the default main stack).
+    m.set('CONFIG_NET_MGMT_EVENT_STACK_SIZE', '4096');
+    m.set('CONFIG_NET_TX_STACK_SIZE', '2048');
+    m.set('CONFIG_NET_RX_STACK_SIZE', '2048');
+    if (!usage.usesWifi) m.set('CONFIG_MAIN_STACK_SIZE', '5200');
+  }
+  if (usage.usesMqtt) {
+    // MQTT rides on the networking stack. CONFIG_MQTT_LIB selects NET_SOCKETS;
+    // the shim getaddrinfo-resolves the broker and runs its own poll k_thread.
+    // CONFIG_MQTT_LIB_TLS enables MQTT_TRANSPORT_SECURE + mqtt_sec_config; the
+    // mbedTLS matrix is the same one HTTP uses (it's idempotent via Map.set).
+    m.set('CONFIG_NETWORKING', 'y');
+    m.set('CONFIG_NET_IPV4', 'y');
+    m.set('CONFIG_NET_DHCPV4', 'y');
+    m.set('CONFIG_NET_TCP', 'y');
+    m.set('CONFIG_NET_SOCKETS', 'y');
+    m.set('CONFIG_MQTT_LIB', 'y');
+    m.set('CONFIG_MQTT_LIB_TLS', 'y');
+    // NET_MAX_CONTEXTS / NET_MAX_CONN: same exhaustion risk as HTTP — sequential
+    // connections linger after close. Give the broker session + headroom.
+    m.set('CONFIG_NET_MAX_CONTEXTS', '16');
+    m.set('CONFIG_NET_MAX_CONN', '16');
+    m.set('CONFIG_ZVFS_OPEN_MAX', '16');
+    // mbedTLS matrix for mqtts:// (mirrors the HTTP block; overlaps are harmless).
+    m.set('CONFIG_NET_SOCKETS_SOCKOPT_TLS', 'y');
+    m.set('CONFIG_TLS_CREDENTIALS', 'y');
+    m.set('CONFIG_MBEDTLS', 'y');
+    m.set('CONFIG_MBEDTLS_BUILTIN', 'y');
+    m.set('CONFIG_MBEDTLS_CIPHERSUITE_TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256', 'y');
+    m.set('CONFIG_MBEDTLS_ENABLE_HEAP', 'y');
+    m.set('CONFIG_MBEDTLS_HEAP_SIZE', '65000');
+    m.set('CONFIG_MBEDTLS_SSL_MAX_CONTENT_LEN', '16384');
+    m.set('CONFIG_MBEDTLS_PEM_CERTIFICATE_FORMAT', 'y');
+    m.set('CONFIG_PSA_CRYPTO', 'y');
+    m.set('CONFIG_REQUIRES_FULL_LIBC', 'y');
+    m.set('CONFIG_NET_TX_STACK_SIZE', '2048');
+    m.set('CONFIG_NET_RX_STACK_SIZE', '2048');
+    if (!usage.usesWifi && !usage.usesHttp) m.set('CONFIG_MAIN_STACK_SIZE', '5200');
+  }
+  if (usage.usesBle) {
+    m.set('CONFIG_BT', 'y');
+    m.set('CONFIG_BT_PERIPHERAL', 'y');
+    m.set('CONFIG_BT_GATT_DYNAMIC_DB', 'y');
+  }
+  // Preferences: ZMS-backed settings. CONFIG_SETTINGS_ZMS depends on ZMS +
+  // FLASH_MAP (it does NOT select them), so all three must be set explicitly.
+  // The backend locates the storage_partition fixed-partition automatically
+  // (or the /chosen zephyr,settings-partition — see dt-config/overlay.ts); no
+  // partition macro is needed in the shim. ZMS is preferred over NVS per the
+  // Zephyr docs ("as of 4.1 the recommended backend is NVS or ZMS").
+  if (usage.usesPreferences) {
+    m.set('CONFIG_FLASH', 'y');
+    m.set('CONFIG_FLASH_MAP', 'y');
+    m.set('CONFIG_ZMS', 'y');
+    m.set('CONFIG_SETTINGS', 'y');
+    m.set('CONFIG_SETTINGS_ZMS', 'y');
+  }
+  // usesUart: the board enables the console UART by default; the overlay (not
+  // Kconfig) is where a UART node would be enabled, so no symbol here.
+  // Random: <zephyr/random/random.h> sys_rand_get is backed by the random
+  // generator subsystem. CONFIG_RANDOM_GENERATOR is the umbrella that selects a
+  // working backend for the board (nRF52840 → hardware RNG via the entropy
+  // driver; QEMU/host → the test generator). CONFIG_ENTROPY_GENERATOR is its
+  // hard dependency on hardware targets. Both default on for most boards, but
+  // setting them explicitly keeps the symbol set honest and survives a board
+  // whose defconfig leaves them off.
+  if (usage.usesRandom) {
+    m.set('CONFIG_ENTROPY_GENERATOR', 'y');
+    m.set('CONFIG_RANDOM_GENERATOR', 'y');
+  }
+
+  // System workqueue — bumped for worker-offload AND timer callbacks. The
+  // workqueue itself is unconditionally built (no CONFIG_SYSTEM_WORKQUEUE symbol
+  // exists in Zephyr — that was a phantom that broke real builds); only the
+  // stack size is a real Kconfig knob.
+  m.set('CONFIG_SYSTEM_WORKQUEUE_STACK_SIZE', '8192');
+
+  // C++ support.
+  m.set('CONFIG_CPP', 'y');
+  m.set('CONFIG_NEWLIB_LIBC', 'y');
+  m.set('CONFIG_REQUIRES_FULL_LIBCPP', 'y');
+  m.set('CONFIG_STD_CPP14', 'y');
+
+  // Main thread stack. WiFi already bumps this to 5200 (esp_wifi device init
+  // is stack-hungry); HTTP/MQTT + TLS also bump it (the mbedTLS handshake is
+  // stack-hungry). The UI runtime (ui_tick) renders a large node tree with AA
+  // text + canvas compositing per frame, so 4096 is marginal headroom and we
+  // bump to 8192 for displays. NOTE: a Zephyr panic dump that prints
+  // `EXCCAUSE 63` is NOT necessarily a stack overflow — on the Zephyr Xtensa
+  // port EXCCAUSE 63 is the reserved software-exception used for k_oops/abort,
+  // and the ESP32 port reaches it via abort() in intc_esp32.c (the
+  // esp_intr_noniram_disable/enable unbalanced-flag guards). Resolve the dump's
+  // PC against the .elf (xtensa_arch_except → abort) before treating it as a
+  // stack overflow; 8192 is kept here because deep ui_tick call nesting still
+  // wants the headroom.
+  if (!usage.usesWifi && !usage.usesHttp && !usage.usesMqtt) {
+    m.set('CONFIG_MAIN_STACK_SIZE', usage.usesDisplay ? '8192' : '4096');
+  }
+
+  if (debug) {
+    m.set('CONFIG_DEBUG', 'y');
+    m.set('CONFIG_DEBUG_OPTIMIZATIONS', 'y');
+  }
+
+  return m;
+}

package/src/dt-config/overlay.ts

@@ -0,0 +1,293 @@
+// ---------------------------------------------------------------------------
+// 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 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). */
+export interface TouchWiring {
+  irq?: number;
+  resetPin?: number;
+  sda?: number;
+  scl?: 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);
+  }
+  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.
+    emitDisplayNode(lines, display, wiring);
+  }
+  // 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).
+  if (usage.usesTouch) {
+    emitTouchNode(lines, touch);
+  }
+
+  // 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 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.
+ */
+function emitDisplayNode(lines: string[], display: ZephyrDisplayProfile, wiring?: DisplayWiring): void {
+  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) {
+    lines.push('&spim2_default {');
+    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('&spi2 {');
+  lines.push('    status = "okay";');
+  lines.push(`    cs-gpios = <&${gpioController(cs)} ${cs} 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 = <&spi2>;');
+  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('            reg = <0>;');
+  lines.push(`            mipi-max-frequency = <${freq}>;`);
+  lines.push('            mipi-mode = "MIPI_DBI_MODE_SPI_4WIRE";');
+  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];');
+  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('');
+  }
+}
+
+/**
+ * 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.
+ */
+function emitTouchNode(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('');
+}