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

package/dist/lowering/tone.js

@@ -1,63 +0,0 @@
-// ---------------------------------------------------------------------------
-// Tone lowering — PWM-based square-wave generation
-//
-// tone is a convenience wrapper around PWM: a square wave at `frequency` Hz with
-// a 50% duty cycle. The lowering maps frequency → period (ns) and sets the PWM
-// channel to a 50% pulse. stop turns the output off (0% duty). The PWM spec is
-// resolved from the chip descriptor (pwm-led0 on the XIAO).
-//
-// An optional duration is honored by scheduling a stop via k_sleep in a detached
-// fashion — but the simple lowering is blocking (k_msleep(duration) then stop),
-// matching the synchronous Arduino tone() semantics. For non-blocking tone,
-// a workqueue would be needed (deferred).
-// ---------------------------------------------------------------------------
-import { findPwmSpec, pwmDtAliasToken } from './pwm.js';
-/**
- * The PWM spec a tone op drives: the op's own pin when it maps to a spec
- * (matrix chips — ESP32 LEDC — resolve any driven pad), else the board's
- * first spec (the aliased LED channel, e.g. pwm-led0 on the XIAO).
- */
-function toneSpec(chip, pin) {
-    return (typeof pin === 'number' ? findPwmSpec(chip, pin) : undefined)
-        ?? chip.pwm?.specs[0];
-}
-/**
- * Resolve a HAL tone.* op to Zephyr C++ via PWM.
- * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
- */
-export function lowerTone(op, chip) {
-    const o = op;
-    switch (op.operation) {
-        case 'tone.play': {
-            // period_ns = 1e9 / freq; pulse_ns = period / 2 (50% duty).
-            // Build a fake pwm.write would need the spec var directly; emit the
-            // pwm_set_dt call against the same spec var the PWM lowering uses.
-            const spec = toneSpec(chip, o.pin);
-            if (!spec) {
-                return { code: `/* tone.play(${o.frequency}): no PWM spec in chip descriptor */` };
-            }
-            const v = `__tc_pwm_${pwmDtAliasToken(spec)}`;
-            const freq = o.frequency;
-            const duration = o.duration;
-            // Braced: two tone ops in one statement-scope (e.g. tone(440).for(50)
-            // lowers tone.play + tone.play_for back-to-back) would otherwise
-            // redeclare __period.
-            const setTone = `{ uint32_t __period = (${freq} > 0) ? (1000000000ULL / static_cast<uint64_t>(${freq})) : 0; pwm_set_dt(&${v}, __period, __period / 2); }`;
-            if (duration !== undefined) {
-                // Blocking tone for the requested duration, then stop.
-                return { code: `${setTone} k_msleep(${duration}); pwm_set_pulse_dt(&${v}, 0);` };
-            }
-            return { code: setTone };
-        }
-        case 'tone.stop': {
-            const spec = toneSpec(chip, o.pin);
-            if (!spec)
-                return { code: `/* tone.stop: no PWM spec */` };
-            const v = `__tc_pwm_${pwmDtAliasToken(spec)}`;
-            return { code: `pwm_set_pulse_dt(&${v}, 0);` };
-        }
-        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/lowering/worker-backing.d.ts

@@ -1,14 +0,0 @@
-import type { WorkerBacking } from "@typecad/cuttlefish/api/shared";
-export interface ZephyrWorkerBackingOptions {
-    /** Initial count of each per-slot semaphore. Default 0 (empty). */
-    initialSemCount?: number;
-}
-/**
- * Build the Zephyr (k_work + k_sem) worker backing.
- *
- * Per slot: a `struct k_work _work_<i>` and a `struct k_sem _done_sem_<i>`.
- * submit resets the semaphore and submits the work to the system workqueue;
- * the work handler runs the trampoline; the trampoline signals completion via
- * k_sem_give; done polls via k_sem_take(K_NO_WAIT).
- */
-export declare function buildZephyrWorkerBacking(_options?: ZephyrWorkerBackingOptions): WorkerBacking;

package/dist/lowering/worker-backing.js

@@ -1,79 +0,0 @@
-// ---------------------------------------------------------------------------
-// Zephyr worker-offload backing (system workqueue + counting semaphore)
-//
-// Supplies the spawn/signal/poll primitives that the shared worker_runtime
-// polyfill calls into, for Zephyr targets. This is the Zephyr-native analog of
-// the ESP32 FreeRTOS backing (framework-esp32/src/lowering/worker-backing.ts):
-//
-//   ESP32 (FreeRTOS)            Zephyr
-//   ─────────────────────────   ─────────────────────────────────────────
-//   xTaskCreate + vTaskDelete   k_work_submit to the system workqueue
-//   xTaskNotifyGive (barrier)   k_sem_give (kernel barrier)
-//   ulTaskNotifyTake(0)         k_sem_take(K_NO_WAIT)
-//
-// The worker runs on the system workqueue thread (a real kernel thread, not an
-// ISR), so it can execute a full function. Completion is signalled via a per-
-// slot counting semaphore given from workqueue thread context (k_sem_give is
-// safe from thread context — NOT k_sem_give from an ISR; workqueue handlers run
-// in thread context). k_sem provides the memory barrier the contract requires.
-//
-// IMPORTANT: the system workqueue has a fixed stack (CONFIG_SYSTEM_WORKQUEUE_
-// STACK_SIZE). The scaffold bumps it because heavy workers (TLS, sensor fusion)
-// overflow the default ~2 KB. Pin a large worker to a private workqueue if it
-// exceeds the system queue's stack.
-// ---------------------------------------------------------------------------
-/**
- * Build the Zephyr (k_work + k_sem) worker backing.
- *
- * Per slot: a `struct k_work _work_<i>` and a `struct k_sem _done_sem_<i>`.
- * submit resets the semaphore and submits the work to the system workqueue;
- * the work handler runs the trampoline; the trampoline signals completion via
- * k_sem_give; done polls via k_sem_take(K_NO_WAIT).
- */
-export function buildZephyrWorkerBacking(_options = {}) {
-    return {
-        requiredIncludes: ['<zephyr/kernel.h>', '<zephyr/work/work.h>'],
-        declarations: [
-            `// Zephyr worker backing: per-slot work item + completion semaphore.`,
-            `// Declared inside the typecad_worker namespace alongside the slots.`,
-        ],
-        slotDeclarations: (handleId, trampolineName) => {
-            // Per-slot completion semaphore (given from workqueue thread context).
-            // Declared before the trampoline so the trampoline's signalDoneExpr can
-            // reference it. The trampoline itself is forward-declared by the shared
-            // runtime above this block.
-            return [
-                `// Per-slot completion semaphore.`,
-                `K_SEM_DEFINE(_done_sem_${handleId}, 0, 1);`,
-                ``,
-                `// Per-slot work item + handler. The handler forwards to the shared-`,
-                `// runtime trampoline (which runs the submitted fn + signals the sem).`,
-                `static void ${trampolineName}_work_handler(struct k_work* work) {`,
-                `  (void)work;`,
-                `  ${trampolineName}(nullptr);`,
-                `}`,
-                `K_WORK_DEFINE(_work_${handleId}, ${trampolineName}_work_handler);`,
-            ];
-        },
-        spawnLines: (handleId, trampolineName, _waiterExpr) => {
-            // The waiter field is unused on Zephyr (the semaphore IS the signal).
-            // Reset the completion semaphore, then submit the work item to the
-            // system workqueue. The work handler (bound via K_WORK_DEFINE above)
-            // runs the shared-runtime trampoline.
-            return [
-                `(void)0; // waiter unused: k_sem is the signal`,
-                `k_sem_reset(&_done_sem_${handleId});`,
-                `(void)k_work_submit(&_work_${handleId});   // ${trampolineName} on sys workqueue`,
-            ];
-        },
-        signalDoneExpr: (handleId) => 
-        // Given from workqueue thread context (k_sem_give is thread-safe here).
-        // k_sem provides the kernel memory barrier making the worker's outputs
-        // visible to the consumer once k_sem_take succeeds.
-        `k_sem_give(&_done_sem_${handleId})`,
-        isDoneExpr: (handleId) => 
-        // Non-blocking take; its barrier makes the worker's outputs safe to read.
-        // The shared runtime fast-paths on the volatile done flag first.
-        `(k_sem_take(&_done_sem_${handleId}, K_NO_WAIT) == 0)`,
-    };
-}

package/dist/lowering/worker.d.ts

@@ -1,6 +0,0 @@
-import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
-/** Resolve a HAL worker.* op to C++ against the shared __tc_worker contract. */
-export declare function lowerWorker(op: HALOpIR): {
-    code?: string;
-    expression?: string;
-} | undefined;

package/dist/lowering/worker.js

@@ -1,14 +0,0 @@
-// ---------------------------------------------------------------------------
-// Zephyr worker-offload lowering
-//
-// Delegates the shared worker.* op contract to the cross-framework helper
-// lowerWorkerOp (worker-runtime.ts). The per-framework primitives are supplied
-// by the Zephyr worker backing (worker-backing.ts: k_work + k_sem), emitted via
-// the worker_runtime polyfill when the program uses worker.* ops. See the
-// Zephyr strategy's worker backing wiring + generateNativePolyfills.
-// ---------------------------------------------------------------------------
-import { lowerWorkerOp } from '@typecad/cuttlefish/api/shared';
-/** Resolve a HAL worker.* op to C++ against the shared __tc_worker contract. */
-export function lowerWorker(op) {
-    return lowerWorkerOp(op);
-}

package/dist/sdk/board-data.generated.d.ts

@@ -1,2 +0,0 @@
-export { BOARD_DATA } from '@typecad/cuttlefish/api/shared';
-export type { BoardDataEntry } from '@typecad/cuttlefish/api/shared';

package/dist/sdk/board-data.generated.js

@@ -1,4 +0,0 @@
-// The board data pack lives in cuttlefish (src/create/) so the scaffolder
-// and the framework share one catalog. Re-exported here for boardgen + the
-// existing sdk imports.
-export { BOARD_DATA } from '@typecad/cuttlefish/api/shared';

package/dist/sdk/catalog-walker.d.ts

@@ -1,90 +0,0 @@
-import type { BoardDataEntry } from '@typecad/cuttlefish/api/shared';
-/** Provenance of a walked catalog — pins it to the exact tree it describes. */
-export interface BoardCatalogProvenance {
-    /** The Zephyr base directory the walk read (resolved). */
-    readonly zephyrBase: string;
-    /** VERSION file contents rendered 'MAJOR.MINOR.PATCH' (best-effort). */
-    readonly version: string;
-    /** Git HEAD of the tree when readable (best-effort; tarballs carry none). */
-    readonly gitHead?: string;
-    /** Boards-dir mtime (epoch ms) — the fallback change signal for git-less trees. */
-    readonly boardsMtimeMs: number;
-    /** ISO timestamp of the walk. */
-    readonly generatedAt: string;
-    /** Variant count, carried for quick display without loading `boards`. */
-    readonly variants: number;
-}
-/** A completed walk: records in boards/ directory order + provenance. */
-export interface BoardCatalogWalkResult {
-    readonly boards: Readonly<Record<string, BoardDataEntry>>;
-    readonly provenance: BoardCatalogProvenance;
-    readonly stats: {
-        readonly variants: number;
-        readonly withFacts: number;
-        readonly failures: number;
-    };
-}
-/** board.yml soc lookup, both formats Zephyr ships:
- *  - legacy single-board (`board:` / top-level `socs:`): every soc listed
- *    under the socs: block → `uniqueSocs`;
- *  - multi-board directories (top-level `boards:` list — lyra_24_dvk,
- *    lyra_dvk, …): each entry carries its own socs; single-soc entries map
- *    board name → soc in `byName`. Multi-soc entries stay unmapped (their
- *    variant yamls carry qualified identifiers).
- *  `boardNames` lists every declared board name (the `boards:` entries and
- *  the legacy `board:` name) — the CONFIG_BOARD_<X> stem a variant's
- *  board.cmake guards its runner args with. */
-export interface BoardYmlSocIndex {
-    readonly byName: ReadonlyMap<string, string>;
-    readonly uniqueSocs: readonly string[];
-    readonly boardNames: readonly string[];
-}
-/** Read board.yml's board→soc index (see BoardYmlSocIndex). */
-export declare function boardYmlSocIndex(dir: string): BoardYmlSocIndex;
-/** How the caller pins runner args to ONE variant of a shared board dir. */
-export interface VariantPin {
-    /** CONFIG_BOARD stems to try in order: the board.yml entry name this
-     *  target belongs to, then the full underscored target name. */
-    readonly boardConfigs?: readonly string[];
-    /** The target's soc segment ('nrf5340'). */
-    readonly soc?: string;
-    /** Qualifier segments after the soc ('cpunet', ['a53','smp']). */
-    readonly quals?: readonly string[];
-}
-export declare function boardProbeMethods(dir: string, variant?: VariantPin): BoardDataEntry['probeMethods'];
-/** VERSION file → 'MAJOR.MINOR.PATCH' ('' when unreadable). */
-export declare function zephyrVersionOf(zephyrBase: string): string;
-/**
- * Git HEAD of the tree, read straight off the filesystem (no git spawn —
- * sync runs where git may be absent). Handles the plain clone (.git dir,
- * HEAD → ref → loose ref or packed-refs) and the worktree/submodule form
- * (.git file pointing at a gitdir). Best-effort: undefined when unreadable.
- */
-export declare function gitHeadOf(zephyrBase: string): string | undefined;
-/** Every build target a board.yml declares, with the naming facts the
- *  synthesizer needs (board.yml-driven dirs ship NO per-variant yamls —
- *  nucleo_n657x0_q's sb target exists only as a board.yml entry). */
-export interface BoardYmlTarget {
-    readonly identifier: string;
-    /** The board entry name the target belongs to (CONFIG_BOARD stem). */
-    readonly boardName: string;
-    readonly soc?: string;
-    /** Variant chain segments after the soc ('sb', ['a53','smp']). */
-    readonly chain: readonly string[];
-    readonly fullName?: string;
-    readonly vendor?: string;
-}
-/**
- * Parse board.yml into its declared build targets, both shapes:
- * multi-board (`boards:` list) and legacy (`board:` block), with socs and
- * (nested) variants. Variant chains accumulate through nesting levels
- * (board/soc/v1/v2).
- */
-export declare function boardYmlTargets(dir: string): BoardYmlTarget[];
-/**
- * Walk `<zephyrBase>/boards` and extract one record per board variant.
- * Reader failures degrade to the base record (identifier/name/vendor/dts +
- * probe methods) — a board whose DTS defeats the reader still resolves, it
- * just carries no pin facts.
- */
-export declare function walkBoardCatalog(zephyrBase: string): BoardCatalogWalkResult;