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

package/dist/lowering/fs.js

@@ -0,0 +1,121 @@
+// ---------------------------------------------------------------------------
+// Filesystem lowering — Zephyr FS API (littlefs on the storage partition)
+//
+// HAL `fs.*` (begin/read_text/write_text/exists/remove) maps onto Zephyr's
+// <zephyr/fs/fs.h>. A littlefs filesystem is mounted at "/lfs" on the board's
+// `storage_partition` fixed-partition (the same partition the ZMS settings
+// backend uses for preferences — a program should not use both surfaces at
+// once without dedicating separate partitions). The mount is lazy: it formats
+// + remounts on first use when the partition is unformatted.
+//
+// The HAL paths are treated as paths WITHIN the filesystem: the shim joins the
+// mount point, so fs.read_text("/data.txt") reads "/lfs/data.txt". This keeps
+// the mount point an implementation detail.
+//
+// Requires Kconfig CONFIG_FILE_SYSTEM + CONFIG_FILE_SYSTEM_LITTLEFS (+ FLASH /
+// FLASH_MAP) — emitted by the scaffold when the program uses fs.* — and the
+// storage_partition node (added by the overlay).
+// ---------------------------------------------------------------------------
+/**
+ * Emit the littlefs mount + the typed helper API the lowering calls into.
+ * Called from shimLines when the program uses the filesystem. The helpers are
+ * `static` so multiple TUs that carry the shim (guarded by the include guard)
+ * do not collide.
+ */
+export function fsInitLines() {
+    return [
+        '// CUTTLEFISH_FS_BEGIN',
+        'static struct fs_mount_t __tc_fs_mp;',
+        'static bool __tc_fs_mounted = false;',
+        '',
+        'FS_LITTLEFS_DECLARE_DEFAULT_CONFIG(__tc_fs_data);',
+        'static struct fs_mount_t __tc_fs_mp_init = {',
+        '    .type = FS_LITTLEFS,',
+        '    .fs_data = &__tc_fs_data,',
+        '    .storage_dev = (void *)FIXED_PARTITION_ID(storage_partition),',
+        '    .mnt_point = "/lfs",',
+        '};',
+        '',
+        'static void __tc_fs_ensure_mount(void) {',
+        '    if (__tc_fs_mounted) return;',
+        '    __tc_fs_mp = __tc_fs_mp_init;',
+        '    int rc = fs_mount(&__tc_fs_mp);',
+        '    if (rc == -ENODATA || rc == -EINVAL) {',
+        '        // Unformatted partition — format it for littlefs, then remount.',
+        '        (void)fs_mkfs(FS_LITTLEFS, static_cast<uintptr_t>(FIXED_PARTITION_ID(storage_partition)), NULL, 0);',
+        '        (void)fs_mount(&__tc_fs_mp);',
+        '    }',
+        '    __tc_fs_mounted = true;',
+        '}',
+        '',
+        '// Join the mount point with the user path (paths are within the FS).',
+        'static const char* __tc_fs_path(const char* p) {',
+        '    static char buf[128];',
+        '    if (!p) return "/lfs";',
+        '    const char* s = (p[0] == \'/\') ? p + 1 : p;',
+        '    (void)snprintf(buf, sizeof(buf), "/lfs/%s", s);',
+        '    return buf;',
+        '}',
+        '',
+        'static bool __tc_fs_begin(void) { __tc_fs_ensure_mount(); return true; }',
+        '',
+        'static const char* __tc_fs_read_text(const char* path) {',
+        '    __tc_fs_ensure_mount();',
+        '    static char buf[256];',
+        '    buf[0] = 0;',
+        '    struct fs_file_t f;',
+        '    fs_file_t_init(&f);',
+        '    if (fs_open(&f, __tc_fs_path(path), FS_O_READ) == 0) {',
+        '        (void)fs_read(&f, buf, sizeof(buf) - 1);',
+        '        buf[sizeof(buf) - 1] = 0;',
+        '        (void)fs_close(&f);',
+        '    }',
+        '    return buf;',
+        '}',
+        '',
+        'static void __tc_fs_write_text(const char* path, const char* content) {',
+        '    __tc_fs_ensure_mount();',
+        '    struct fs_file_t f;',
+        '    fs_file_t_init(&f);',
+        '    if (fs_open(&f, __tc_fs_path(path), FS_O_WRITE | FS_O_CREATE | FS_O_TRUNC) == 0) {',
+        '        (void)fs_write(&f, content, (content ? strlen(content) : 0));',
+        '        (void)fs_close(&f);',
+        '    }',
+        '}',
+        '',
+        'static bool __tc_fs_exists(const char* path) {',
+        '    __tc_fs_ensure_mount();',
+        '    struct fs_dirent ent;',
+        '    return fs_stat(__tc_fs_path(path), &ent) == 0;',
+        '}',
+        '',
+        'static bool __tc_fs_remove(const char* path) {',
+        '    __tc_fs_ensure_mount();',
+        '    return fs_unlink(__tc_fs_path(path)) == 0;',
+        '}',
+        '// CUTTLEFISH_FS_END',
+    ];
+}
+/**
+ * Resolve a HAL fs.* op to Zephyr C++.
+ * Returns `{ code }` — each op's code is the body of the HAL FS class method.
+ */
+export function lowerFs(op) {
+    const o = op;
+    switch (op.operation) {
+        case 'fs.begin':
+            // No payload (the op carries only its discriminator).
+            return { code: 'return __tc_fs_begin();' };
+        case 'fs.read_text':
+            return { code: `return __tc_fs_read_text(${o.path});` };
+        case 'fs.write_text':
+            return { code: `__tc_fs_write_text(${o.path}, ${o.content});` };
+        case 'fs.exists':
+            return { code: `return __tc_fs_exists(${o.path});` };
+        case 'fs.remove':
+            return { code: `return __tc_fs_remove(${o.path});` };
+        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/hwtimer.d.ts

@@ -0,0 +1,15 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the per-instance counter device handles + frequency/callback state.
+ * Called from shimLines when the program uses hardware timers.
+ */
+export declare function hwtimerInitLines(chip: ZephyrChipDescriptor): string[];
+/**
+ * Resolve a HAL hwtimer.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export declare function lowerHwtimer(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/hwtimer.js

@@ -0,0 +1,84 @@
+// ---------------------------------------------------------------------------
+// Hardware-timer lowering — Zephyr counter API
+//
+// HAL `hwtimer.*` (instance → frequency/overflow/start/stop) maps onto Zephyr's
+// counter driver (<zephyr/drivers/counter.h>). A chip declares the counter
+// devices it exposes (e.g. nRF RTC1 — RTC0 is kernel-owned) via
+// `hwtimer.controllers[instance].nodeLabel`.
+//
+// Frequency model: a Zephyr counter has a fixed clock; the HAL
+// set_frequency(hz) is realized as a top value of counter_freq/hz with an alarm
+// callback (the on_overflow handler). start() arms both the top value and the
+// callback so the call order (setFrequency → onOverflow → start, or any
+// permutation) is handled uniformly.
+//
+// Targets without a free counter omit `hwtimer`; usage lowers to a comment and
+// profileDiagnostics flags it. The JS setInterval/setTimeout polyfill
+// (k_timer) is a separate surface and is unaffected.
+// ---------------------------------------------------------------------------
+/** Per-instance emitted symbol stems. */
+function devVar(instance) {
+    return `__tc_hw_dev_${instance}`;
+}
+function hzVar(instance) {
+    return `__tc_hw_hz_${instance}`;
+}
+function cbVar(instance) {
+    return `__tc_hw_cb_${instance}`;
+}
+/**
+ * Emit the per-instance counter device handles + frequency/callback state.
+ * Called from shimLines when the program uses hardware timers.
+ */
+export function hwtimerInitLines(chip) {
+    const controllers = chip.hwtimer?.controllers ?? [];
+    if (controllers.length === 0)
+        return [];
+    const lines = ['// CUTTLEFISH_HWTIMER_BEGIN'];
+    controllers.forEach((c, i) => {
+        lines.push(`static const struct device* ${devVar(i)} = DEVICE_DT_GET(DT_NODELABEL(${c.nodeLabel}));`, `static uint32_t ${hzVar(i)} = 1;`, `static counter_top_callback_t ${cbVar(i)} = NULL;`);
+    });
+    lines.push('// CUTTLEFISH_HWTIMER_END');
+    return lines;
+}
+/**
+ * Resolve a HAL hwtimer.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerHwtimer(op, chip) {
+    const o = op;
+    const controllers = chip.hwtimer?.controllers ?? [];
+    // No counter on this target. Comment + (in profileDiagnostics) a clear error.
+    if (controllers.length === 0) {
+        return { code: `/* hwtimer instance ${o.instance}: no counter device on ${chip.id} */` };
+    }
+    const instance = typeof o.instance === 'number' ? o.instance : parseInt(String(o.instance), 10);
+    if (isNaN(instance) || instance < 0 || instance >= controllers.length) {
+        return { code: `/* hwtimer instance ${o.instance}: out of range on ${chip.id} */` };
+    }
+    switch (op.operation) {
+        case 'hwtimer.set_frequency':
+            return { code: `${hzVar(instance)} = ${o.hz};` };
+        case 'hwtimer.on_overflow':
+            return { code: `${cbVar(instance)} = (${o.handler});` };
+        case 'hwtimer.start':
+            // Arm the top value (counter_freq / desired_hz) + the overflow callback,
+            // then start the counter. Doing both here handles any call order — the
+            // HAL typical sequence (setFrequency → onOverflow → start) and permutations.
+            return {
+                code: [
+                    `{`,
+                    `  uint32_t __f = counter_get_frequency(${devVar(instance)});`,
+                    `  uint32_t __top = __f ? (__f / ${hzVar(instance)}) : 0U;`,
+                    `  if (__top > 0U) { (void)counter_set_top_value(${devVar(instance)}, __top, ${cbVar(instance)}, NULL); }`,
+                    `  (void)counter_start(${devVar(instance)});`,
+                    `}`,
+                ].join(' '),
+            };
+        case 'hwtimer.stop':
+            return { code: `(void)counter_stop(${devVar(instance)});` };
+        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/index.d.ts

@@ -18,7 +18,10 @@ import { lowerMqtt } from './mqtt.js';
 import { lowerPreferences } from './preferences.js';
 import { lowerBoard } from './board.js';
 import { lowerRandom } from './random.js';
-export { lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart, lowerInterrupt, lowerWdt, lowerPower, lowerTone, lowerPulseOrShift, lowerBle, lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom, };
+import { lowerDac } from './dac.js';
+import { lowerFs } from './fs.js';
+import { lowerHwtimer } from './hwtimer.js';
+export { lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart, lowerInterrupt, lowerWdt, lowerPower, lowerTone, lowerPulseOrShift, lowerBle, lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom, lowerDac, lowerFs, lowerHwtimer, };
 /**
  * Lower a HAL op to Zephyr C++. Returns undefined for unsupported categories
  * (mirrors lowerHalOp in framework-esp32/src/lowering/index.ts).

package/dist/lowering/index.js

@@ -3,8 +3,8 @@
 //
 // Routes a HALOpIR to the per-category lowering module by category prefix
 // (e.g. 'gpio.write' → lowerGpio). Returns undefined for categories the
-// framework does not lower (display/fs/mdns/ota/rmt/dac/
-// hwtimer/capacitive/temp/espnow/crypto/i2s/twai/usb/eth/pcnt/mcpwm — see
+// framework does not lower (display/mdns/ota/rmt/
+// capacitive/temp/espnow/crypto/i2s/twai/usb/eth/pcnt/mcpwm — see
 // the manifest), so the transpiler falls back and the manifest validator
 // cross-checks the unsupported categories. (board.* is registered below but is
 // a dead-letter — its values are constant-folded at IR-build time.)
@@ -36,7 +36,10 @@ import { lowerMqtt } from './mqtt.js';
 import { lowerPreferences } from './preferences.js';
 import { lowerBoard } from './board.js';
 import { lowerRandom } from './random.js';
-export { lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart, lowerInterrupt, lowerWdt, lowerPower, lowerTone, lowerPulseOrShift, lowerBle, lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom, };
+import { lowerDac } from './dac.js';
+import { lowerFs } from './fs.js';
+import { lowerHwtimer } from './hwtimer.js';
+export { lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart, lowerInterrupt, lowerWdt, lowerPower, lowerTone, lowerPulseOrShift, lowerBle, lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom, lowerDac, lowerFs, lowerHwtimer, };
 /**
  * Lower a HAL op to Zephyr C++. Returns undefined for unsupported categories
  * (mirrors lowerHalOp in framework-esp32/src/lowering/index.ts).
@@ -51,6 +54,8 @@ export function lowerHalOp(op) {
         return lowerAdc(op, chip);
     if (op.operation.startsWith('pwm.'))
         return lowerPwm(op, chip);
+    if (op.operation.startsWith('dac.'))
+        return lowerDac(op, chip);
     if (op.operation.startsWith('i2c.'))
         return lowerI2c(op, chip);
     if (op.operation.startsWith('spi.'))
@@ -61,6 +66,8 @@ export function lowerHalOp(op) {
         return lowerInterrupt(op, chip);
     if (op.operation.startsWith('wdt.'))
         return lowerWdt(op);
+    if (op.operation.startsWith('hwtimer.'))
+        return lowerHwtimer(op, chip);
     if (op.operation.startsWith('power.'))
         return lowerPower(op);
     if (op.operation.startsWith('tone.'))
@@ -80,6 +87,8 @@ export function lowerHalOp(op) {
         return lowerMqtt(op);
     if (op.operation.startsWith('preferences.'))
         return lowerPreferences(op);
+    if (op.operation.startsWith('fs.'))
+        return lowerFs(op);
     // board.resolve is constant-folded at IR-build time; lowerBoard is the
     // dead-letter reached only on an unresolvable path.
     if (op.operation.startsWith('board.'))

package/dist/strategy.d.ts

@@ -78,6 +78,10 @@ export declare class ZephyrStrategy implements PlatformStrategy {
     passthroughMacroNames(): ReadonlySet<string>;
     apiReservedEnumNames(): ReadonlySet<string>;
     apiReservedEnumGuard(): string;
+    isrUnsafeOperations(): Map<string, {
+        reason: string;
+        severity: 'warning' | 'info';
+    }>;
     ambientTypeDeclarations(): string[];
     needsIostream(): boolean;
     needsStdString(): boolean;