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

package/dist/strategy.d.ts

@@ -1,4 +1,52 @@
 import type { PlatformStrategy, ProgramIR, Diagnostic, PlatformContext, BoardConstants, RuntimePolyfillIR, StdLibSupport, AsyncRuntimeConfig, GraphicsCapacity, HALOpIR, DisplayHALOp, ResolvedDisplay, DisplayAdapterCode, DisplayProfile, TouchProfile, TouchAdapterCodegen } from '@typecad/cuttlefish/api/shared';
+import { type BoardCatalogSyncReport, type BoardCatalogEnsureResult } from './sdk/board-catalog-sync.js';
+/**
+ * Collect the distinct DT-bound sensors the program's ops reference, as
+ * `${part}|${bus}|${address}` keys (same shape as peripheral-usage's
+ * sensorPartsUsed). Feeds the per-sensor device-handle state block — only
+ * constructed sensors emit state, and only sensors whose ops were emitted
+ * get a DT node.
+ */
+export declare function collectSensors(program: ProgramIR | undefined): Map<string, {
+    part: string;
+    bus: string;
+    port: number | string;
+    busKind: string;
+    spiHz: number | string;
+    spiMode: number | string;
+    alertPin: number | string;
+}> | undefined;
+/**
+ * Collect the distinct thin SPI targets the program's ops reference
+ * (spi.transceive / spi.dev_write), keyed `${bus}|${cs}`. Mirrors
+ * collectSensors: only constructed targets whose ops were emitted get a
+ * spi_dt_spec state block and a DT child node.
+ */
+export declare function collectSpiTargets(program: ProgramIR | undefined): Map<string, {
+    bus: string;
+    cs: number;
+    hz: number;
+    mode: number;
+}> | undefined;
+/**
+ * Collect the distinct UART RX rings the program reads (uart.rx_* ops),
+ * keyed by controller index. Mirrors collectSpiTargets: only ports whose RX
+ * ops were emitted get a ring + ISR (an unused ISR is -Wunused-function
+ * under Zephyr's -Werror).
+ */
+export declare function collectUartRings(program: ProgramIR | undefined): Map<number, {
+    index: number;
+    ring: number;
+}> | undefined;
+/**
+ * Collect the distinct threads the program STARTS (thread.start ops), keyed
+ * by instance. Only started threads emit state — see shimLines.
+ */
+export declare function collectThreads(program: ProgramIR | undefined): Map<number, {
+    instance: number;
+    stackBytes: number;
+    priority: number;
+}> | undefined;
 export declare class ZephyrStrategy implements PlatformStrategy {
     readonly id = "zephyr";
     /**
@@ -6,10 +54,39 @@ export declare class ZephyrStrategy implements PlatformStrategy {
      * by the methods that need the descriptor (shimLines, resolveHALOperation
      * via lowerHalOp).
      *
-     * Tries to derive the chip descriptor from the board/MCU package's zephyr
-     * fields (via boardConstants) first. Falls back to the hardcoded
-     * chipForTarget registry for boards that haven't shipped zephyr config yet.
+     * The chip descriptor derives from the board/MCU manifest's zephyr
+     * fields (via boardConstants). There is no registry fallback — a board
+     * that never generated a manifest stays NO_BOARD_CHIP.
      */
+    /**
+     * Eagerly resolve + cache the chip for `program`. The emitter calls this
+     * before rendering any bodies — hal-op lowering reads the module-global
+     * chip cache, and the lazy resolve (inside shimLines) runs later than the
+     * first lowered statement.
+     */
+    prepareChip(program: ProgramIR | undefined, ctx?: PlatformContext): void;
+    /**
+     * Contract-board generation: a custom PCB spec (typecad contract) names
+     * its wired pads and bus families; the SoC's bus controller labels come
+     * from the installed Zephyr tree's soc dtsi. Same builder as every board.
+     */
+    generateContractBoardModule(opts: {
+        soc: string;
+        zephyrBase: string;
+        pinNames: readonly string[];
+        padAliases?: readonly {
+            exportName: string;
+            padName: string;
+        }[];
+        peripherals: {
+            i2c: boolean;
+            spi: boolean;
+            uart: boolean;
+        };
+    }): {
+        boardTs: string;
+        boardJson: string;
+    };
     private resolveChip;
     /**
      * Resolve the debug mode for the active target from the platform context.
@@ -55,12 +132,19 @@ export declare class ZephyrStrategy implements PlatformStrategy {
     shimLines(program?: ProgramIR, ctx?: PlatformContext): string[];
     profileDiagnostics(program?: ProgramIR, ctx?: PlatformContext): Diagnostic[];
     /**
-     * `loop` is forward-declared `extern` by the main() bridge shim
-     * (extern void loop(void); → int main(void) {...}), so emitting a
-     * `static void loop()` definition redeclares it with conflicting linkage,
-     * which GCC rejects. Exclude it from the static forward-declaration path
-     * — mirrors how ArduinoStrategy excludes `loop` (the Arduino core forward-
-     * declares it extern). `setup` is already handled because it equals
+     * Strip Arduino library headers that @typecad/hal's class surfaces register
+     * (I2CBus → <Wire.h>, SPIBus → <SPI.h>). The Zephyr
+     * equivalents are usage-gated forcedIncludes (<zephyr/drivers/i2c.h>, …),
+     * so an unstripped Wire.h reaches the west build and gcc rejects it
+     * ("Wire.h: No such file or directory") — this hook is why I2C/SPI class
+     * usage on Zephyr used to fail at compile time.
+     */
+    filterRequiredIncludes(includes: string[]): string[];
+    /**
+     * Nothing to exclude: no shim or Zephyr core header forward-declares a user
+     * function extern (the old setup()/loop() bridge was the only consumer of
+     * this hook, excluding `loop`). The entrypoint itself (`main`) is already
+     * excluded from the static forward-declaration path because it equals
      * entrypointFunctionName().
      */
     forwardDeclarationExclusions(): string[];
@@ -89,9 +173,6 @@ export declare class ZephyrStrategy implements PlatformStrategy {
     renderBoardDefinitionAccess(chain: string[], boardConstants?: BoardConstants): string | undefined;
     promotesArrayLiteralsToStaticArray(): boolean;
     renderThrow(_valueExpr: string): string;
-    isConsoleCall(callee: string): boolean;
-    transformConsoleCall(method: string, renderedArgs: string, forHeader: boolean): string;
-    transformConsoleExpression(_method: string, _renderedArgs: string): string | undefined;
     objectFieldInitializer(): string | undefined;
     overrideClassFieldType(_fieldName: string, normalizedType: string): string;
     reservedNames(): ReadonlySet<string>;
@@ -110,14 +191,56 @@ export declare class ZephyrStrategy implements PlatformStrategy {
     needsStdFunction(): boolean;
     mathHeader(): string;
     cstringHeader(): string;
-    needsVectorOverload(): boolean;
     needsLargeEnumUnderlying(): boolean;
     renameStructField(fieldName: string): string;
     structFieldInitializer(): string | undefined;
     getAsyncRuntimeConfig(): AsyncRuntimeConfig;
+    /**
+     * Board module generation: join the Zephyr board data pack (extracted
+     * from the pinned tree) with the curated soc descriptors. See
+     * src/boardgen.ts.
+     */
+    generateBoardModule(target: string, opts?: {
+        factsJson?: string;
+        asBuiltJson?: string;
+    }): {
+        boardTs: string;
+        boardJson: string;
+        warnings?: readonly string[];
+    } | undefined;
+    /**
+     * Regenerate the board catalog overlay from the user's own Zephyr tree —
+     * `cuttlefish board sync`. After a `west update`, this is how new/changed/
+     * removed boards reach projects without a cuttlefish release. See
+     * src/sdk/board-catalog-sync.ts.
+     */
+    syncBoardCatalog(zephyrBase?: string): BoardCatalogSyncReport;
+    /**
+     * Refresh the overlay only when it is stale (provenance no longer matches
+     * the tree) — the pre-step `cuttlefish board regen` runs so a regen after
+     * `west update` picks up the tree's boards automatically. Tree walk only
+     * happens when there is actual refreshing to do.
+     */
+    ensureFreshBoardCatalog(): BoardCatalogEnsureResult;
     asyncLoopInjection(taskVarNames: string[], config: AsyncRuntimeConfig): string[];
     asyncLoopInjection(taskVarNames: string[], hasPromiseRuntime: boolean, hasTimers: boolean): string[];
     asyncDriverFunctionName(): string;
+    /**
+     * Zephyr's scheduler loop for event-driven programs (UI mounted). The
+     * emitter wraps the per-frame work — ui_tick plus the asyncLoopInjection
+     * lines — in `while (__tc_zephyr_event_loop) { ...; k_msleep(1); }`: a
+     * 1 ms cooperative yield to the kernel each frame, matching the cadence the
+     * old setup()/loop() bridge gave loop(). The flag is never cleared — the
+     * loop is the program's lifetime — but keeping the bool gives the condition
+     * a used symbol (a bare `while (true)` would leave nothing to name, and an
+     * unused flag would trip -Werror's -Wunused-variable).
+     */
+    hostEventLoop(): {
+        flagName: string;
+        continueCondition: string;
+        preIteration: string;
+        postIteration: string;
+    } | null;
     shouldSkipTypeAlias(): boolean;
     emitDiagnostics(): Diagnostic[];
     currentTimeMillis(): string;
@@ -146,11 +269,7 @@ export declare class ZephyrStrategy implements PlatformStrategy {
     isHalCall(name: string): boolean;
     analogReadCallNames(): ReadonlySet<string>;
     isRtosTarget(): boolean;
-    private _workerBacking;
     private _displayState;
-    workerSpawnLines(handleId: number, trampolineName: string, waiterExpr: string): string[] | undefined;
-    workerSignalDoneExpr(handleId: number): string | undefined;
-    workerIsDoneExpr(handleId: number): string | undefined;
     resolveDisplayOp(op: DisplayHALOp): {
         code?: string;
         expression?: string;