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

package/src/dt-config/kconfig.ts

@@ -1,3 +1,33 @@
+import { SENSOR_PART_INFO } from '@typecad/hal';
+
+/** A sensor part's catalog facts, as the exceptions helper consumes them. */
+interface SensorKconfigSource {
+  kconfig: readonly string[];
+}
+
+/**
+ * Apply the per-part Kconfig exceptions the generated catalog records, for
+ * exactly the parts the program constructs. Lines are CONFIG_<SYM>=<value>
+ * strings parsed into the map; a symbol the user set explicitly in
+ * zephyr.kconfig is left alone (scaffold.ts already skips user overrides for
+ * auto symbols, and Map.set idempotence covers the rest). The lookup is a
+ * parameter so tests can drive it with a synthetic catalog.
+ */
+export function applySensorKconfigExceptions(
+  m: Map<string, string>,
+  parts: readonly { part: string }[] | undefined,
+  lookup: Readonly<Record<string, SensorKconfigSource>> = SENSOR_PART_INFO,
+): void {
+  if (!parts) return;
+  for (const sp of parts) {
+    for (const line of lookup[sp.part]?.kconfig ?? []) {
+      const eq = line.indexOf('=');
+      if (eq <= 0) continue;
+      m.set(line.slice(0, eq), line.slice(eq + 1));
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Kconfig fragment resolver — extracts the prj.conf symbol logic
 //
@@ -17,24 +47,77 @@ export interface KconfigUsage {
   usesI2c?: boolean;
   usesSpi?: boolean;
   usesUart?: boolean;
+  /** USB CDC-ACM serial used (usb.* ops). Selects the "next" USB device
+   *  stack + CDC class; the class instances themselves are composed in the
+   *  DT overlay and auto-default on once the node exists (assigning the
+   *  class symbol keeps prj.conf explicit and survives DT-only probes). */
+  usesUsb?: boolean;
   usesWdt?: boolean;
   usesBle?: boolean;
   usesDisplay?: boolean;
-  usesPower?: boolean;
   usesWifi?: boolean;
   usesHttp?: boolean;
   usesMqtt?: boolean;
   usesPreferences?: boolean;
   usesRandom?: boolean;
+  /** A printf-family format specifier with a float conversion (%f, %.2f, %e,
+   *  …) appears in the emitted source — Zephyr's cbprintf only links float
+   *  conversions with FP_SUPPORT (which itself needs the COMPLETE impl). */
+  usesFloatFormat?: boolean;
+  /** DT-bound sensor parts used (sensor.* ops — the generic catalog). The
+   *  umbrella under which every driver sensor Kconfig lives (`if SENSOR`);
+   *  the per-driver symbols default on from their DT node presence. */
+  usesSensor?: boolean;
+  /** Distinct constructed sensors — only the overlay generator consumes this
+   *  (one DT child node per entry, on the given I2C controller index); prj.conf
+   *  ignores it. Same adcReadPins/pwmUsedPins pattern. */
+  sensorParts?: readonly { part: string; busIndex: number; port: number; busKind: 'i2c' | 'spi'; spiHz?: number; spiMode?: number; alertPin?: number }[];
+  /** Distinct thin SPI targets (hal/spi-target.ts) — one DT child node per
+   *  entry (no compatible — a raw spi_dt_spec peer), appended after sensor
+   *  CS entries in the controller's merged cs-gpios. */
+  spiTargets?: readonly { busIndex: number; cs: number; hz?: number; mode?: number }[];
   /** Touch controller referenced (UI touch adapter emits DT_NODELABEL(ft6336u)
    *  or DT_NODELABEL(xpt2046)). Selects the bus driver the node needs. */
   usesTouch?: boolean;
   /** Which touch controller the program uses — FT6336U rides I2C, XPT2046
    *  rides the display's SPI bus. Only meaningful with usesTouch. */
   touchController?: 'ft6336u' | 'xpt2046';
+  /** The emitted shim carries the STM32F4 DBGMCU keep-SWD-alive init
+   *  (__tc_stm32_dbgmcu token). Selects Zephyr's own "debugger attach in
+   *  stop/sleep" init (sets DBG_STOP via the LL headers); the shim's raw
+   *  register poke additionally covers DBG_SLEEP, which the Zephyr F4 path
+   *  does not set. */
+  usesStm32DebugSleep?: 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';
+  /** HAL pin numbers the program reads with adc.* — scanned from the emitted
+   *  `__tc_adc<N>_setup()` calls at compile time. Only the overlay generator
+   *  consumes this (to rewrite the ADC node's pinctrl-0 to the used channels
+   *  on SoCs that need pad muxing, e.g. STM32); prj.conf ignores it. */
+  adcReadPins?: readonly number[];
+  /** HAL pin numbers the program drives with dac.* — scanned from the
+   *  emitted lazy-setup guards (__tc_dact<pin>_done) at compile time. Only
+   *  the overlay generator consumes this (the DAC node's pinctrl-0 lists
+   *  the used channels); prj.conf ignores it. */
+  dacWritePins?: readonly number[];
+  /** HAL pin numbers the program drives with pwm.* — scanned from the
+   *  emitted `__tc_pwm_*` spec references at compile time. Only the overlay
+   *  generator consumes this (synthesized pwm-leds consumers + aliases are
+   *  emitted per used pin, so the DT carries no dead channels); prj.conf
+   *  ignores it. */
+  pwmUsedPins?: readonly number[];
+  /** Controller indexes per bus the program actually drives — scanned from
+   *  the emitted `__tc_<bus><N>_dev` state blocks at compile time. The
+   *  overlay enables only those controllers (an enabled-but-unused
+   *  controller claims its default pins — e.g. i2c0's GP4/GP5 on the Pico —
+   *  which a program using the OTHER controller may want as GPIO). Absent
+   *  (prepare-time overlays, driver-API-only users like the display
+   *  adapter) → every declared controller is enabled, preserving the old
+   *  behavior. prj.conf ignores these. */
+  i2cUsedInstances?: readonly number[];
+  spiUsedInstances?: readonly number[];
+  uartUsedInstances?: readonly number[];
 }
 
 /**
@@ -55,11 +138,54 @@ export function resolveKconfigFragments(
   m.set('CONFIG_CONSOLE', 'y');
 
   if (usage.usesAdc) m.set('CONFIG_ADC', 'y');
+  // Sensors: only the umbrella — each in-tree driver is `default y` on its
+  // DT_HAS_<COMPAT>_ENABLED, so the overlay's child node enables the driver.
+  if (usage.usesSensor) m.set('CONFIG_SENSOR', 'y');
+  // The rare driver that is NOT DT-default-on: the catalog records its
+  // Kconfig lines (from the driver's own Kconfig) and they are applied for
+  // exactly the parts the program constructs. Empty for every in-tree part
+  // today — this path is insurance for the next exception.
+  applySensorKconfigExceptions(m, usage.sensorParts);
+  // Float formatting: cbprintf builds float conversions only under
+  // FP_SUPPORT, which depends on the COMPLETE implementation — without these,
+  // %f silently prints garbage instead of the value.
+  if (usage.usesFloatFormat) {
+    m.set('CONFIG_CBPRINTF_COMPLETE', 'y');
+    m.set('CONFIG_CBPRINTF_FP_SUPPORT', 'y');
+  }
   if (usage.usesPwm) m.set('CONFIG_PWM', 'y');
   if (usage.usesDac) m.set('CONFIG_DAC', 'y');
   if (usage.usesI2c) m.set('CONFIG_I2C', 'y');
   if (usage.usesSpi) m.set('CONFIG_SPI', 'y');
+  // USB CDC-ACM serial: the "next" USB device stack + the CDC-ACM class.
+  // Symbol names verified against Zephyr 4.3 (subsys/usb/device_next/Kconfig):
+  //   - USB_DEVICE_STACK_NEXT is the new stack (selects UDC_DRIVER);
+  //     USB_DEVICE_STACK is the LEGACY stack — deprecated in 4.3 (selects
+  //     DEPRECATED) and its assignment is what trips the build.
+  //   - USBD_CDC_ACM_CLASS is the class (note the USBD_ prefix — a bare
+  //     CDC_ACM_CLASS is an undefined symbol). It depends on SERIAL +
+  //     DT_HAS_ZEPHYR_CDC_ACM_UART_ENABLED (the overlay's cdc-acm-uart node)
+  //     and selects UART_INTERRUPT_DRIVEN/RING_BUFFER itself; assigning it
+  //     keeps prj.conf explicit.
+  //   - UART_LINE_CTRL gates the driver's line_ctrl_get — usb.connected()
+  //     polls DTR through it.
+  if (usage.usesUsb) {
+    m.set('CONFIG_USB_DEVICE_STACK_NEXT', 'y');
+    m.set('CONFIG_USBD_CDC_ACM_CLASS', 'y');
+    m.set('CONFIG_UART_LINE_CTRL', 'y');
+    m.set('CONFIG_SERIAL', 'y');
+    // The device presents a serial-number string descriptor sourced from
+    // hwinfo (the SoC's unique ID). Without it Windows keys the CDC devnode
+    // on the physical USB port: replugs reuse stale nodes and repeated flash
+    // cycles wedge them into permanent "access denied" opens. A serial makes
+    // the instance path identity-based — stable across ports, immune to the
+    // port-keyed ghost pool.
+    m.set('CONFIG_HWINFO', 'y');
+  }
   if (usage.usesWdt) m.set('CONFIG_WATCHDOG', 'y');
+  // STM32: keep the debugger attachable in sleep/stop (see the shim's
+  // DBGMCU init — this covers the Zephyr-side DBG_STOP bit via LL headers).
+  if (usage.usesStm32DebugSleep) m.set('CONFIG_STM32_ENABLE_DEBUG_SLEEP_STOP', 'y');
   // Hardware timers via the counter driver.
   if (usage.usesHwtimer) m.set('CONFIG_COUNTER', 'y');
   if (usage.usesDisplay) {
@@ -113,24 +239,19 @@ export function resolveKconfigFragments(
       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_WIFI_ESP32', 'y');            // family-wide ESP32 driver (esp32/s3/c3/c6)
     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),
+    // to come up — but our shim brings the iface up itself in main() (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
@@ -215,13 +336,26 @@ export function resolveKconfigFragments(
     // 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');
+    // Ciphersuites only *depend on* X509_CRT_PARSE_C (they don't select it) —
+    // without it sockets_tls.c compiles out mbedtls_x509_crt_parse and every
+    // pinned-CA handshake fails with EPERM at connect (the insecure path
+    // skips verification, so it works either way).
+    m.set('CONFIG_MBEDTLS_X509_CRT_PARSE_C', 'y');
+    // KNOWN LIMITATION on this Zephyr tree: pinned-CA (verified TLS) fails at
+    // connect — the tf-psa-crypto mbedTLS needs a wider symbol matrix
+    // (RSA public-key parse + PEM/DER glue) than the single-ciphersuite
+    // select pulls in, and forcing the extra symbols regresses the insecure
+    // path. insecure() HTTPS is fully verified; caCert() chain verification
+    // stays open until the upstream matrix is mapped.
     // 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');
+    // 2x SSL_MAX_CONTENT_LEN record buffers + CA-chain parse state +
+    // handshake working memory. 65000 fit insecure-mode handshakes but the
+    // pinned-CA path (verification state) overflowed → EPERM at connect.
+    m.set('CONFIG_MBEDTLS_HEAP_SIZE', '100000');
     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
@@ -244,6 +378,12 @@ export function resolveKconfigFragments(
     m.set('CONFIG_NET_SOCKETS', 'y');
     m.set('CONFIG_MQTT_LIB', 'y');
     m.set('CONFIG_MQTT_LIB_TLS', 'y');
+    // The shim getaddrinfo-resolves the broker host — without the DNS
+    // resolver linked, getaddrinfo fails numeric AND hostname lookups with
+    // EAI_FAIL even while plain HTTP (which selects DNS via its own block)
+    // works.
+    m.set('CONFIG_DNS_RESOLVER', 'y');
+    m.set('CONFIG_DNS_SERVER_IP_ADDRESSES', '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');
@@ -255,10 +395,23 @@ export function resolveKconfigFragments(
     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');
+    // Ciphersuites only *depend on* X509_CRT_PARSE_C (they don't select it) —
+    // without it sockets_tls.c compiles out mbedtls_x509_crt_parse and every
+    // pinned-CA handshake fails with EPERM at connect (the insecure path
+    // skips verification, so it works either way).
+    m.set('CONFIG_MBEDTLS_X509_CRT_PARSE_C', 'y');
+    // KNOWN LIMITATION on this Zephyr tree: pinned-CA (verified TLS) fails at
+    // connect — the tf-psa-crypto mbedTLS needs a wider symbol matrix
+    // (RSA public-key parse + PEM/DER glue) than the single-ciphersuite
+    // select pulls in, and forcing the extra symbols regresses the insecure
+    // path. insecure() HTTPS is fully verified; caCert() chain verification
+    // stays open until the upstream matrix is mapped.
     m.set('CONFIG_MBEDTLS_ENABLE_HEAP', 'y');
-    m.set('CONFIG_MBEDTLS_HEAP_SIZE', '65000');
+    // 2x SSL_MAX_CONTENT_LEN record buffers + CA-chain parse state +
+    // handshake working memory. 65000 fit insecure-mode handshakes but the
+    // pinned-CA path (verification state) overflowed → EPERM at connect.
+    m.set('CONFIG_MBEDTLS_HEAP_SIZE', '100000');
     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');
@@ -295,19 +448,24 @@ export function resolveKconfigFragments(
     m.set('CONFIG_FLASH_MAP', 'y');
     m.set('CONFIG_FILE_SYSTEM', 'y');
     m.set('CONFIG_FILE_SYSTEM_LITTLEFS', 'y');
+    // fs_mkfs (the lazy first-use format in the shim) is gated behind this —
+    // without it the mount path links fine but the format call is undefined.
+    m.set('CONFIG_FILE_SYSTEM_MKFS', '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.
+  // generator subsystem's RNG_GENERATOR_CHOICE. There is no umbrella symbol —
+  // CONFIG_RANDOM_GENERATOR is a phantom in 4.x (assigning an undefined symbol
+  // aborts the build). The choice defaults to the entropy-device generator
+  // when the board has a driver (ENTROPY_HAS_DRIVER: nRF52840, ESP32, …);
+  // RNG-less SoCs (STM32F411 has no hardware RNG) need
+  // CONFIG_TEST_RANDOM_GENERATOR to unlock the timer-clock fallback, which
+  // the choice then picks by default. Setting both keys gets the best
+  // available source per board.
   if (usage.usesRandom) {
     m.set('CONFIG_ENTROPY_GENERATOR', 'y');
-    m.set('CONFIG_RANDOM_GENERATOR', 'y');
+    m.set('CONFIG_TEST_RANDOM_GENERATOR', 'y');
   }
 
   // System workqueue — bumped for worker-offload AND timer callbacks. The