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

package/dist/display/index.d.ts

@@ -2,7 +2,7 @@ import type { DisplayHALOp } from '@typecad/cuttlefish/api/shared';
 import { type ZephyrDisplayProfile } from './profiles.js';
 export { zephyrUiDisplayAdapter, zephyrDisplayAdapterGenerator } from './ui-adapter.js';
 export { zephyrTouchAdapter } from './touch-adapter.js';
-export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
+export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE, BUILT_IN_PROFILES } from './profiles.js';
 export type { ZephyrDisplayProfile } from './profiles.js';
 export interface DisplayState {
     initialized: boolean;

package/dist/display/index.js

@@ -15,7 +15,7 @@ import { DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
 // and consumers can reach them from the package barrel.
 export { zephyrUiDisplayAdapter, zephyrDisplayAdapterGenerator } from './ui-adapter.js';
 export { zephyrTouchAdapter } from './touch-adapter.js';
-export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE } from './profiles.js';
+export { ZEPHYR_DISPLAY_PROFILES, DEFAULT_ZEPHYR_DISPLAY_PROFILE, BUILT_IN_PROFILES } from './profiles.js';
 /** Fresh display state (used by the strategy per-build). */
 export function newDisplayState() {
     return { initialized: false, profile: DEFAULT_ZEPHYR_DISPLAY_PROFILE };

package/dist/display/profiles.d.ts

@@ -48,3 +48,11 @@ export declare function panelControllerFor(profile: Pick<ZephyrDisplayProfile, '
 export declare const ZEPHYR_DISPLAY_PROFILES: Record<string, ZephyrDisplayProfile>;
 /** The default profile used when resolveDisplayOp is probed without a display.init. */
 export declare const DEFAULT_ZEPHYR_DISPLAY_PROFILE: ZephyrDisplayProfile;
+/**
+ * The Zephyr profiles mapped to the shared DisplayProfile shape — the single
+ * mapping, so no consumer needs to know the DT-binding descriptor layout.
+ * The strategy's getProfileRegistry() and the preview's profile-registry
+ * loader both consume this (the same role `BUILT_IN_PROFILES` plays in
+ * framework-arduino's displays modules).
+ */
+export declare const BUILT_IN_PROFILES: Record<string, import('@typecad/cuttlefish/api/shared').DisplayProfile>;

package/dist/display/profiles.js

@@ -69,3 +69,22 @@ export const ZEPHYR_DISPLAY_PROFILES = {
 };
 /** The default profile used when resolveDisplayOp is probed without a display.init. */
 export const DEFAULT_ZEPHYR_DISPLAY_PROFILE = ZEPHYR_DISPLAY_PROFILES['ili9341-zephyr'];
+/**
+ * The Zephyr profiles mapped to the shared DisplayProfile shape — the single
+ * mapping, so no consumer needs to know the DT-binding descriptor layout.
+ * The strategy's getProfileRegistry() and the preview's profile-registry
+ * loader both consume this (the same role `BUILT_IN_PROFILES` plays in
+ * framework-arduino's displays modules).
+ */
+export const BUILT_IN_PROFILES = Object.fromEntries(Object.entries(ZEPHYR_DISPLAY_PROFILES).map(([name, p]) => [
+    name,
+    {
+        driver: p.driver,
+        width: p.width,
+        height: p.height,
+        nativeWidth: p.nativeWidth,
+        nativeHeight: p.nativeHeight,
+        colorFormat: p.colorFormat,
+        rotation: p.rotation ?? 1,
+    },
+]));

package/dist/display/ui-adapter.d.ts

@@ -10,6 +10,10 @@ export interface ZephyrDisplayReadbackOptions {
     scanlineSync?: boolean;
     /** MISO/SDO GPIO; readback is disabled when it is not explicitly wired. */
     miso?: number;
+    /** Tearing-effect GPIO (panel TE output). When set, panel updates wait for
+     *  the TE frame pulse instead of GET_SCANLINE readback — no MISO required.
+     *  The overlay adds te-gpios to the display DT node from this. */
+    tearingEffectPin?: number;
 }
 export declare function zephyrUiDisplayAdapter(profile: ZephyrDisplayProfile, readback?: ZephyrDisplayReadbackOptions): DisplayAdapterCode;
 /**

package/dist/display/ui-adapter.js

@@ -55,6 +55,9 @@ export function zephyrUiDisplayAdapter(profile, readback = {}) {
     // react badly to GSCAN reads. Both an explicit opt-in and an explicit MISO
     // pin are required before emitting an active synchronization path.
     const scanlineSync = readback.scanlineSync === true && readback.miso !== undefined;
+    // TE (hardware tearing-effect) sync: strictly opt-in via a configured GPIO.
+    // Preferred over GET_SCANLINE when wired — no readback traffic, no MISO.
+    const tePin = typeof readback.tearingEffectPin === 'number' ? readback.tearingEffectPin : undefined;
     const includes = [
         `// --- Zephyr UI display adapter (${profile.driver}) ---`,
         `// Native CuttlefishGFX path: do NOT #define CuttlefishCanvas16 so the`,
@@ -118,6 +121,22 @@ export function zephyrUiDisplayAdapter(profile, readback = {}) {
         `// controller-specific validation are required; otherwise the display stays`,
         `// on the existing retained/composited path with no extra SPI reads.`,
         `static const bool __tc_pnl_scanline_sync = ${scanlineSync ? 'true' : 'false'};`,
+        `// Tearing-effect (TE) hardware sync: the panel pulses its TE line once`,
+        `// per frame. When te-gpios is present on the display DT node, panel`,
+        `// updates arm on the TE edge — tear-free writes with no MISO readback.`,
+        `#if DT_NODE_HAS_PROP(DT_NODELABEL(${dtLabel}), te_gpios)`,
+        `#define __TC_TE_SYNC 1`,
+        `static const struct gpio_dt_spec __tc_te =`,
+        `    GPIO_DT_SPEC_GET(DT_NODELABEL(${dtLabel}), te_gpios);`,
+        `static struct gpio_callback __tc_te_cb;`,
+        `static volatile uint32_t __tc_te_count = 0;`,
+        `static void __tc_te_isr(const struct device* port, struct gpio_callback* cb, uint32_t pins) {`,
+        `    (void)port; (void)cb; (void)pins;`,
+        `    __tc_te_count++;`,
+        `}`,
+        `#else`,
+        `#define __TC_TE_SYNC 0`,
+        `#endif`,
         `// Stashed address window from the last setAddrWindow call. The runtime`,
         `// calls setAddrWindow + writePixels as a matched pair, so we stash the rect`,
         `// here and consume it in writePixels.`,
@@ -134,6 +153,17 @@ export function zephyrUiDisplayAdapter(profile, readback = {}) {
     // with DT_HAS_ALIAS (the safe primitive for an alias that may be absent —
     // DT_NODE_HAS_STATUS(DT_ALIAS(...)) is version-dependent when the alias is
     // missing and can fail the build).
+    // TE pin: input + rising-edge interrupt (the ST7796 TE pulse), then tell
+    // the controller to drive the line (TEON 0x35, mode 1 = vertical sync only).
+    const teInit = tePin !== undefined ? `#if __TC_TE_SYNC
+    if (device_is_ready(__tc_te.port)) {
+      gpio_pin_configure_dt(&__tc_te, GPIO_INPUT);
+      gpio_init_callback(&__tc_te_cb, __tc_te_isr, BIT(__tc_te.pin));
+      (void)gpio_add_callback(__tc_te.port, &__tc_te_cb);
+      (void)gpio_pin_interrupt_configure_dt(&__tc_te, GPIO_INT_EDGE_RISING);
+      __tc_pnl_cmd1(0x35, 0x01); // TEON: TE output = vsync pulse
+    }
+#endif` : '';
     const blInit = backlightAlias
         ? `#if DT_HAS_ALIAS(${backlightAlias})\n    const struct gpio_dt_spec __bl = GPIO_DT_SPEC_GET(DT_ALIAS(${backlightAlias}), gpios);\n    if (device_is_ready(__bl.port)) { gpio_pin_configure_dt(&__bl, GPIO_OUTPUT_ACTIVE); }\n#endif`
         : '';
@@ -452,6 +482,19 @@ static uint16_t __tc_pnl_read_scanline(void) {
 // have no safe post-rectangle interval, so they retain the normal single-burst
 // behavior; the caller's framebuffer still prevents intermediate software frames.
 static void __tc_pnl_wait_for_safe_rect(int16_t y, int16_t rh) {
+#if __TC_TE_SYNC
+  // TE variant: arm on the next frame pulse, then start the burst — the write
+  // chases the scan beam from the top of the rect. Bounded so a stuck TE line
+  // can never hang the UI loop.
+  if (rh < 8 || y < 0) return;
+  uint32_t __was = __tc_te_count;
+  uint32_t __deadline = k_uptime_get_32() + 25U;
+  while (__tc_te_count == __was) {
+    if (static_cast<int32_t>(k_uptime_get_32() - __deadline) >= 0) break;
+    k_msleep(0);
+  }
+  return;
+#endif
   if (!__tc_pnl_scanline_sync || rh < 8 || y < 0) return;
   int16_t __last = static_cast<int16_t>(y + rh - 1);
   if (__last >= static_cast<int16_t>(${h} - 2)) return;
@@ -551,8 +594,10 @@ const CuttlefishPanelOps __tc_display_ops = {
 CuttlefishGFX __tc_display(&__tc_display_ops, nullptr);
 ${initBlock}
 // ── display_init (called from setup) ────────────────────────────────────
+
 static inline void display_init() {
   printk("TC_DISPLAY: device ready\\n");
+${teInit}
 ${blInit}
   gpio_pin_configure_dt(&__tc_pnl_cs, GPIO_OUTPUT);
   gpio_pin_configure_dt(&__tc_pnl_dc, GPIO_OUTPUT);
@@ -699,5 +744,6 @@ export const zephyrDisplayAdapterGenerator = (display) => {
     return zephyrUiDisplayAdapter(profile, {
         scanlineSync: display.scanlineSync,
         miso: display.spiPins?.miso,
+        tearingEffectPin: display.tearingEffectPin,
     });
 };

package/dist/dt-config/overlay.d.ts

@@ -10,6 +10,9 @@ 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
@@ -49,4 +52,8 @@ export interface TouchWiring {
      *  panels need a few hundred 12-bit counts; default 400. */
     minPressure?: number;
 }
-export declare function generateOverlay(chip: ZephyrChipDescriptor, usage: KconfigUsage, display: ZephyrDisplayProfile | undefined, wiring?: DisplayWiring, touch?: TouchWiring): string;
+export interface OverlayDiagnostic {
+    severity: "warning" | "error";
+    message: string;
+}
+export declare function generateOverlay(chip: ZephyrChipDescriptor, usage: KconfigUsage, display: ZephyrDisplayProfile | undefined, wiring?: DisplayWiring, touch?: TouchWiring, diagnostics?: OverlayDiagnostic[]): string;

package/dist/dt-config/overlay.js

@@ -11,7 +11,18 @@
 // library headers into .d.ts; Zephyr does it by enabling DT nodes + Kconfig.)
 // ---------------------------------------------------------------------------
 import { PANEL_CONTROLLER_DEFAULTS, panelControllerFor } from '../display/profiles.js';
-export function generateOverlay(chip, usage, display, wiring, touch) {
+export function generateOverlay(chip, usage, display, wiring, touch, diagnostics = []) {
+    // 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 = [
         '/* Auto-generated by @typecad/framework-zephyr from cuttlefish.config.ts. */',
         '/* Enables peripherals the program uses. West merges this over the board DT. */',
@@ -177,6 +188,13 @@ function emitDisplayNode(lines, display, wiring, spiTouchCs) {
     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,

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export { ZephyrStrategy as FrameworkStrategy } from './strategy.js';
 export { ZephyrStrategy } from './strategy.js';
 export { Toolchain } from './toolchain/index.js';
+export { writeProjectDebugArtifacts } from './toolchain/debug-config.js';
 export { runDoctor as doctor } from './doctor.js';
 export { runLicensesPresenter as licenses } from './licenses.js';
 export { chipForTarget, setActiveChip, getActiveChip, XIAO_BLE, } from './chips/index.js';

package/dist/index.js

@@ -8,6 +8,11 @@
 export { ZephyrStrategy as FrameworkStrategy } from './strategy.js';
 export { ZephyrStrategy } from './strategy.js';
 export { Toolchain } from './toolchain/index.js';
+// Create-time starter debug artifacts. The `cuttlefish create` flow reads this
+// optional named export off the loaded framework module (same loader pattern
+// as doctor/licenses) and calls it for freshly scaffolded projects, so F5 in
+// VS Code works before the first build. No-ops for non-GDB targets.
+export { writeProjectDebugArtifacts } from './toolchain/debug-config.js';
 // `cuttlefish doctor` — verify the installed Zephyr is reachable + inside the
 // declared compat range, and preview board-target normalization. Re-exported
 // under the dispatcher-facing alias `doctor` so the loader picks it up as

package/dist/lowering/gpio.js

@@ -113,9 +113,13 @@ function lowerGpioRaw(op, chip) {
         case 'gpio.read':
             return { expression: `gpio_pin_get_raw(${controller}, ${pin})` };
         case 'gpio.toggle':
-            return {
-                code: `gpio_pin_set_raw(${controller}, ${pin}, !gpio_pin_get_raw(${controller}, ${pin}));`,
-            };
+            // Native atomic toggle — never read-modify-write. gpio_pin_get_raw on
+            // a direction-only output reads the input latch, which is undefined on
+            // SoCs that don't latch it. Zephyr's toggle API has no _raw variant —
+            // gpio_pin_toggle is the driver-level atomic toggle, and for pins
+            // configured without GPIO_ACTIVE_LOW the logical level equals the
+            // physical one, so it matches the get_raw/set_raw used elsewhere.
+            return { code: `gpio_pin_toggle(${controller}, ${pin});` };
         default:
             throw new Error(`framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
                 `Open an issue or use rawCpp() to emit it manually.`);

package/dist/strategy.d.ts

@@ -32,6 +32,26 @@ export declare class ZephyrStrategy implements PlatformStrategy {
      * nodes whose resolved `raw` code references it.
      */
     private programUsesAsyncRuntime;
+    /** Pins referenced by gpio.* hal-ops in the program IR. lowerGpio routes a
+     *  pin to its devicetree spec by pin NUMBER, so the structured hal-op pins
+     *  are the authoritative signal for which __tc_dt_* specs are needed —
+     *  regardless of when the final call text is rendered. */
+    private collectGpioPinUsage;
+    /** Run `re` (global) against every raw string in the IR — raw expression
+     *  values plus raw hal-op codes — returning capture group 1 of each match
+     *  (the full match when the regex has no group). This is how references the
+     *  text scanners must see but that never appear as IR call nodes (e.g. a
+     *  rawCpp() escape hatch naming `__tc_dt_sw0` directly) are discovered. */
+    private collectRawMatches;
+    /** Whether the wiring-compat GPIO read surface (__tc_gpio_read definition,
+     *  __tc_gpio_dev dispatcher, and the wiring_compat polyfill's digitalRead /
+     *  HIGH / LOW macros) must be emitted. Consumers: user digitalRead() calls
+     *  (usesDigitalRead), the @typecad/safety voter (calls __tc_gpio_read
+     *  directly via lowered raw text), and the UI runtime header's
+     *  unconditional digitalRead() poll (entryHasUI — build-global, so every TU
+     *  in a UI build carries the macros). With no analysis present (capability
+     *  query), default to emitting — same convention as the uses() helper. */
+    private needsGpioReadShim;
     shimLines(program?: ProgramIR, ctx?: PlatformContext): string[];
     profileDiagnostics(program?: ProgramIR, ctx?: PlatformContext): Diagnostic[];
     /**