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

package/src/lowering/hwtimer.ts

@@ -1,101 +1,139 @@
-// ---------------------------------------------------------------------------
-// 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.
-// ---------------------------------------------------------------------------
-
-import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
-import type { ZephyrChipDescriptor } from '../chips/types.js';
-
-/** Per-instance emitted symbol stems. */
-function devVar(instance: number): string {
-  return `__tc_hw_dev_${instance}`;
-}
-function hzVar(instance: number): string {
-  return `__tc_hw_hz_${instance}`;
-}
-function cbVar(instance: number): string {
-  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: ZephyrChipDescriptor): string[] {
-  const controllers = chip.hwtimer?.controllers ?? [];
-  if (controllers.length === 0) return [];
-  const lines: string[] = ['// 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: HALOpIR,
-  chip: ZephyrChipDescriptor,
-): { code?: string; expression?: string } {
-  const o = op as any;
-  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.`,
-      );
-  }
-}
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+
+/** Per-instance emitted symbol stems. */
+function devVar(instance: number): string {
+  return `__tc_hw_dev_${instance}`;
+}
+function hzVar(instance: number): string {
+  return `__tc_hw_hz_${instance}`;
+}
+function cbVar(instance: number): string {
+  return `__tc_hw_cb_${instance}`;
+}
+/** The trampoline matching counter_top_callback_t: (dev, user_data). */
+function trampVar(instance: number): string {
+  return `__tc_hw_tramp_${instance}`;
+}
+
+/**
+ * Emit the per-instance counter device handles + frequency/callback state.
+ * Called from shimLines when the program uses hardware timers.
+ */
+export function hwtimerInitLines(chip: ZephyrChipDescriptor): string[] {
+  const controllers = chip.hwtimer?.controllers ?? [];
+  if (controllers.length === 0) return [];
+  const lines: string[] = ['// 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 void (*${cbVar(i)})(void) = NULL;`,
+      `static void ${trampVar(i)}(const struct device* dev, void* user_data) {`,
+      `    (void)dev; (void)user_data;`,
+      `    if (${cbVar(i)}) { ${cbVar(i)}(); }`,
+      `}`,
+    );
+  });
+  lines.push('// CUTTLEFISH_HWTIMER_END');
+  return lines;
+}
+
+/**
+ * Resolve a HAL hwtimer.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerHwtimer(
+  op: HALOpIR,
+  chip: ZephyrChipDescriptor,
+): { code?: string; expression?: string } {
+  const o = op as any;
+  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) {
+    default:
+      throw new Error(
+        `framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+          `Open an issue or use rawCpp() to emit it manually.`,
+      );
+  }
+}
+
+export function lowerCounter(
+  op: HALOpIR,
+  chip: ZephyrChipDescriptor,
+): { code?: string; expression?: string } {
+  const o = op as any;
+  const controllers = chip.hwtimer?.controllers ?? [];
+
+  if (controllers.length === 0) {
+    return { code: `/* ${op.operation}: 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: `/* counter instance ${o.instance}: out of range on ${chip.id} (${controllers.length} declared) */` };
+  }
+
+  switch (op.operation) {
+    case 'counter.on_alarm':
+      return { code: `${cbVar(instance)} = (${o.handler});` };
+    case 'counter.start': {
+      // Apply the construction hz as the top value, arm the alarm callback,
+      // start. hz rides the op, so no ordering constraint exists. The API
+      // is counter_set_top_value(dev, const counter_top_cfg*) with a
+      // (dev, user_data) callback — the trampoline in hwtimerInitLines
+      // adapts the user's void() handler.
+      return {
+        code: [
+          `{`,
+          `  ${hzVar(instance)} = ${o.hz};`,
+          `  uint32_t __f = counter_get_frequency(${devVar(instance)});`,
+          `  uint32_t __top = __f ? (__f / ${hzVar(instance)}) : 0U;`,
+          `  if (__top > 0U) {`,
+          `    struct counter_top_cfg __cfg = { .ticks = __top, .callback = ${trampVar(instance)}, .user_data = NULL, .flags = 0U };`,
+          `    (void)counter_set_top_value(${devVar(instance)}, &__cfg);`,
+          `  }`,
+          `  (void)counter_start(${devVar(instance)});`,
+          `}`,
+        ].join(' '),
+      };
+    }
+    case 'counter.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/src/lowering/i2c.ts

@@ -1,126 +1,116 @@
-// ---------------------------------------------------------------------------
-// I2C lowering — transactional txbuf accumulator + per-call i2c_write
-//
-// Mirrors the ESP32 stateful model but simpler: Zephyr's `i2c_write(bus, buf,
-// len, addr)` takes the address per-call, so there's no device-handle cache.
-// The begin_transmission → write* → end_transmission sequence accumulates into
-// `__tc_i2c<N>_txbuf` and flushes as one `i2c_write` at end_transmission.
-// Reads go through request_from → i2c_read into `__tc_i2c<N>_rxbuf`, consumed
-// by subsequent i2c.read / i2c.available calls.
-//
-// The device handle resolves at compile time via DEVICE_DT_GET(DT_NODELABEL(...)).
-// ---------------------------------------------------------------------------
-
-import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
-import type { ZephyrChipDescriptor } from '../chips/types.js';
-import { parseControllerIndex } from './util.js';
-
-const TXBUF_SIZE = 32;
-const RXBUF_SIZE = 32;
-
-/** The C variable prefix for a controller's state. */
-function prefix(idx: number): string {
-  return `__tc_i2c${idx}`;
-}
-
-/**
- * Emit the per-controller I2C state. Called from shimLines for each
- * controller the program uses (gated on ctx.analysis.usesI2C).
- */
-export function i2cInitLines(chip: ZephyrChipDescriptor, controllerIndex: number): string[] {
-  const ctrl = chip.i2c?.controllers[controllerIndex];
-  if (!ctrl) return [];
-  const p = prefix(controllerIndex);
-  return [
-    '// CUTTLEFISH_I2C_BEGIN',
-    `static const struct device* ${p}_dev = DEVICE_DT_GET(DT_NODELABEL(${ctrl.nodeLabel}));`,
-    `static uint16_t ${p}_addr = 0xFFFF;`,
-    `static uint8_t ${p}_txbuf[${TXBUF_SIZE}];`,
-    `static size_t ${p}_txlen = 0;`,
-    `static uint8_t ${p}_rxbuf[${RXBUF_SIZE}];`,
-    `static size_t ${p}_rxlen = 0;`,
-    `static size_t ${p}_rxpos = 0;`,
-    '// CUTTLEFISH_I2C_END',
-  ];
-}
-
-/** Map a clock speed in Hz to an I2C_SPEED_* define. */
-function speedForHz(hz: number): string {
-  if (hz <= 100_000) return 'I2C_SPEED_STANDARD';
-  if (hz <= 400_000) return 'I2C_SPEED_FAST';
-  if (hz <= 1_000_000) return 'I2C_SPEED_FAST_PLUS';
-  return 'I2C_SPEED_HIGH';
-}
-
-/**
- * Resolve a HAL i2c.* op to Zephyr C++.
- * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
- */
-export function lowerI2c(
-  op: HALOpIR,
-  chip: ZephyrChipDescriptor,
-): { code?: string; expression?: string } {
-  const o = op as any;
-  const idx = parseControllerIndex(o.bus);
-  const p = prefix(idx);
-
-  switch (op.operation) {
-    case 'i2c.begin':
-      // Zephyr resolves the device at compile time; begin is a no-op (device
-      // ready check is folded into the driver calls).
-      return { code: `(void)${p}_dev;` };
-    case 'i2c.end':
-      return { code: `(void)${p}_dev;` };
-    case 'i2c.set_clock': {
-      const hz = typeof o.hz === 'number' ? o.hz : parseInt(String(o.hz), 10);
-      const speed = isNaN(hz) ? 'I2C_SPEED_STANDARD' : speedForHz(hz || 100000);
-      return { code: `i2c_configure(${p}_dev, I2C_SPEED_SET(${speed}));` };
-    }
-    case 'i2c.begin_transmission':
-      // Record the target address + reset the pending write buffer.
-      return { code: `${p}_addr = static_cast<uint16_t>(${o.address}); ${p}_txlen = 0;` };
-    case 'i2c.write':
-      // Append one byte (clamped to capacity).
-      return { code: `if (${p}_txlen < ${TXBUF_SIZE}) { ${p}_txbuf[${p}_txlen++] = static_cast<uint8_t>(${o.data}); }` };
-    case 'i2c.write_bytes': {
-      const bytes: unknown[] = o.bytes ?? [];
-      const stmts = bytes.map(
-        (b) => `if (${p}_txlen < ${TXBUF_SIZE}) { ${p}_txbuf[${p}_txlen++] = static_cast<uint8_t>(${b}); }`,
-      );
-      return { code: stmts.join(' ') };
-    }
-    case 'i2c.write_buffer': {
-      // Copy from a user buffer (its name is o.data), clamped to capacity.
-      return {
-        code: `for (size_t __i = 0; __i < sizeof(${o.data}) && ${p}_txlen < ${TXBUF_SIZE}; __i++) { ${p}_txbuf[${p}_txlen++] = reinterpret_cast<const uint8_t*>(${o.data})[__i]; }`,
-      };
-    }
-    case 'i2c.end_transmission':
-      // Flush the accumulated txbuf to the cached address.
-      return { code: `i2c_write(${p}_dev, ${p}_txbuf, ${p}_txlen, ${p}_addr);` };
-    case 'i2c.request_from': {
-      const qty = o.quantity;
-      return {
-        code: `i2c_read(${p}_dev, ${p}_rxbuf, static_cast<uint32_t>(${qty}), static_cast<uint16_t>(${o.address})); ${p}_rxlen = ${qty}; ${p}_rxpos = 0;`,
-      };
-    }
-    case 'i2c.available':
-      return { expression: `(${p}_rxlen - ${p}_rxpos)` };
-    case 'i2c.read':
-      return { expression: `(${p}_rxpos < ${p}_rxlen ? ${p}_rxbuf[${p}_rxpos++] : -1)` };
-    case 'i2c.read_buffer': {
-      // Read straight into the user's buffer (o.buffer), count bytes.
-      const count = o.count;
-      return {
-        code: `i2c_read(${p}_dev, reinterpret_cast<uint8_t*>(${o.buffer}), static_cast<uint32_t>(${count}), ${p}_addr);`,
-      };
-    }
-    case 'i2c.recover':
-      return { code: `i2c_recover_bus(${p}_dev);` };
-    default:
-      throw new Error(
-        `framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
-          `Open an issue or use rawCpp() to emit it manually.`,
-      );
-  }
-}
+// ---------------------------------------------------------------------------
+// I2C lowering — transactional txbuf accumulator + per-call i2c_write
+//
+// Mirrors the ESP32 stateful model but simpler: Zephyr's `i2c_write(bus, buf,
+// len, addr)` takes the address per-call, so there's no device-handle cache.
+// The begin_transmission → write* → end_transmission sequence accumulates into
+// `__tc_i2c<N>_txbuf` and flushes as one `i2c_write` at end_transmission.
+// Reads go through request_from → i2c_read into `__tc_i2c<N>_rxbuf`, consumed
+// by subsequent i2c.read / i2c.available calls.
+//
+// The device handle resolves at compile time via DEVICE_DT_GET(DT_NODELABEL(...)).
+// ---------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+import { parseControllerIndex } from './util.js';
+
+/** The C variable prefix for a controller's state. */
+function prefix(idx: number): string {
+  return `__tc_i2c${idx}`;
+}
+
+/**
+ * Emit the per-controller I2C state. Called from shimLines for each
+ * controller the program uses (gated on ctx.analysis.usesI2C).
+ */
+export function i2cInitLines(chip: ZephyrChipDescriptor, controllerIndex: number): string[] {
+  const ctrl = chip.i2c?.controllers[controllerIndex];
+  if (!ctrl) return [];
+  const p = prefix(controllerIndex);
+  return [
+    '// CUTTLEFISH_I2C_BEGIN',
+    `static const struct device* ${p}_dev = DEVICE_DT_GET(DT_NODELABEL(${ctrl.nodeLabel}));`,
+    '// CUTTLEFISH_I2C_END',
+  ];
+}
+
+/** Map a clock speed in Hz to an I2C_SPEED_* define. */
+function speedForHz(hz: number): string {
+  if (hz <= 100_000) return 'I2C_SPEED_STANDARD';
+  if (hz <= 400_000) return 'I2C_SPEED_FAST';
+  if (hz <= 1_000_000) return 'I2C_SPEED_FAST_PLUS';
+  return 'I2C_SPEED_HIGH';
+}
+
+/**
+ * The (void) comma expression begin/end lower to — a no-op that references
+ * the controller's whole state block (device + transaction buffers) so a
+ * program calling only begin() stays -Werror clean (-Wunused-variable).
+ */
+function i2cKeepAlive(p: string): string {
+  return `(void)${p}_dev;`;
+}
+
+/** The thin-device bus-speed preamble: apply the construction hz once
+ *  (i2c_configure with Zephyr's I2C_SPEED_SET tier mapping), or '' when the
+ *  target constructed without hz. Guarded per controller, so the cost after
+ *  the first op is one bool test. */
+function i2cSpeedGuard(p: string, hz: unknown): string {
+  const n = typeof hz === 'number' ? hz : parseInt(String(hz ?? 0), 10);
+  if (!n || isNaN(n)) return '';
+  const speed = speedForHz(n);
+  const done = `${p}_spd_done`;
+  return `{ static bool ${done} = false; if (!${done}) { (void)i2c_configure(${p}_dev, I2C_SPEED_SET(${speed})); ${done} = true; } } `;
+}
+
+/**
+ * Resolve a HAL i2c.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export function lowerI2c(
+  op: HALOpIR,
+  chip: ZephyrChipDescriptor,
+): { code?: string; expression?: string } {
+  const o = op as any;
+  const idx = parseControllerIndex(o.bus);
+  const p = prefix(idx);
+
+  switch (op.operation) {
+    // ── Thin I2C device (hal/i2c-target.ts) — Zephyr register verbs ──────
+    // One call per op against the controller device handle; the optional
+    // construction hz applies once via a guarded i2c_configure (the same
+    // call i2c.set_clock lowers to).
+    case 'i2c.reg_write': {
+      const pre = i2cSpeedGuard(p, o.hz);
+      return { code: `${pre} i2c_reg_write_byte(${p}_dev, static_cast<uint16_t>(${o.address}), static_cast<uint8_t>(${o.reg}), static_cast<uint8_t>(${o.value}));` };
+    }
+    case 'i2c.reg_read': {
+      const pre = i2cSpeedGuard(p, o.hz);
+      return { expression: `({ ${pre} uint8_t __v = 0; (void)i2c_reg_read_byte(${p}_dev, static_cast<uint16_t>(${o.address}), static_cast<uint8_t>(${o.reg}), &__v); __v; })` };
+    }
+    case 'i2c.reg_update': {
+      const pre = i2cSpeedGuard(p, o.hz);
+      return { code: `${pre} (void)i2c_reg_update_byte(${p}_dev, static_cast<uint16_t>(${o.address}), static_cast<uint8_t>(${o.reg}), static_cast<uint8_t>(${o.mask}), static_cast<uint8_t>(${o.value}));` };
+    }
+    case 'i2c.dev_write': {
+      const pre = i2cSpeedGuard(p, o.hz);
+      const bytes: unknown[] = o.bytes ?? [];
+      // Identifier-shaped only — a single-byte literal array arrives as
+      // numeric text ("159") and must take the literal path.
+      const isBuffer = bytes.length === 1 && typeof bytes[0] === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(bytes[0] as string);
+      if (isBuffer) {
+        const name = bytes[0] as string;
+        // A named user buffer: i2c_write against its storage directly.
+        return { code: `${pre} (void)i2c_write(${p}_dev, reinterpret_cast<const uint8_t*>(${name}), sizeof(${name}), static_cast<uint16_t>(${o.address}));` };
+      }
+      const arr = `static const uint8_t __tc_i2cw[] = { ${bytes.join(', ')} };`;
+      return { code: `${pre} ${arr} (void)i2c_write(${p}_dev, __tc_i2cw, sizeof(__tc_i2cw), static_cast<uint16_t>(${o.address}));` };
+    }
+    default:
+      throw new Error(
+        `framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+          `Open an issue or use rawCpp() to emit it manually.`,
+      );
+  }
+}