@typecad/framework-zephyr 1.0.0-alpha.10

package/src/lowering/i2c.ts

@@ -0,0 +1,126 @@
+// ---------------------------------------------------------------------------
+// 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.`,
+      );
+  }
+}

package/src/lowering/index.ts

@@ -0,0 +1,86 @@
+// ---------------------------------------------------------------------------
+// HAL lowering dispatcher
+//
+// 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
+// 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.)
+//
+// Prefix dispatch (matching framework-esp32's lowerHalOp) keeps this resilient:
+// a new op added to a category's lowering fn is picked up here automatically,
+// without also editing a 40-case switch. The per-fn default arm still throws a
+// clear "unsupported op" error for ops that fall within a category prefix but
+// aren't handled, so coverage stays honest.
+// ---------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import { getActiveChip } from '../chips/index.js';
+import { lowerGpio } from './gpio.js';
+import { lowerTiming } from './timing.js';
+import { lowerAdc } from './adc.js';
+import { lowerPwm } from './pwm.js';
+import { lowerI2c } from './i2c.js';
+import { lowerSpi } from './spi.js';
+import { lowerUart } from './uart.js';
+import { lowerInterrupt } from './interrupts.js';
+import { lowerWdt } from './wdt.js';
+import { lowerPower } from './power.js';
+import { lowerTone } from './tone.js';
+import { lowerPulseOrShift } from './pulse.js';
+import { lowerBle } from './ble.js';
+import { lowerWorker } from './worker.js';
+import { lowerWifi } from './wifi.js';
+import { lowerHttp } from './http.js';
+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,
+};
+
+/**
+ * Lower a HAL op to Zephyr C++. Returns undefined for unsupported categories
+ * (mirrors lowerHalOp in framework-esp32/src/lowering/index.ts).
+ */
+export function lowerHalOp(
+  op: HALOpIR,
+): { code?: string; expression?: string } | undefined {
+  const chip = getActiveChip();
+
+  if (op.operation.startsWith('gpio.'))       return lowerGpio(op, chip);
+  if (op.operation.startsWith('timing.'))     return lowerTiming(op);
+  if (op.operation.startsWith('adc.'))        return lowerAdc(op, chip);
+  if (op.operation.startsWith('pwm.'))        return lowerPwm(op, chip);
+  if (op.operation.startsWith('i2c.'))        return lowerI2c(op, chip);
+  if (op.operation.startsWith('spi.'))        return lowerSpi(op, chip);
+  if (op.operation.startsWith('uart.'))       return lowerUart(op);
+  if (op.operation.startsWith('interrupt.'))  return lowerInterrupt(op, chip);
+  if (op.operation.startsWith('wdt.'))        return lowerWdt(op);
+  if (op.operation.startsWith('power.'))      return lowerPower(op);
+  if (op.operation.startsWith('tone.'))       return lowerTone(op, chip);
+  // pulse.* and shift.* share a bit-bang lowering module.
+  if (op.operation.startsWith('pulse.') || op.operation.startsWith('shift.'))
+    return lowerPulseOrShift(op, chip);
+  if (op.operation.startsWith('ble.'))        return lowerBle(op);
+  if (op.operation.startsWith('worker.'))     return lowerWorker(op);
+  if (op.operation.startsWith('wifi.'))       return lowerWifi(op);
+  if (op.operation.startsWith('http.'))       return lowerHttp(op);
+  if (op.operation.startsWith('mqtt.'))       return lowerMqtt(op);
+  if (op.operation.startsWith('preferences.')) return lowerPreferences(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.')) return lowerBoard(op);
+  if (op.operation.startsWith('random.')) return lowerRandom(op);
+
+  // raw / snprintf.emit / display.* / ... — not lowered by this
+  // framework. Return undefined so the transpiler falls back and the manifest
+  // validator confirms the unsupported declaration.
+  return undefined;
+}

package/src/lowering/interrupts.ts

@@ -0,0 +1,114 @@
+// ---------------------------------------------------------------------------
+// Interrupt lowering — gpio_init_callback + gpio_add_callback
+//
+// The most complex lowering: Zephyr's GPIO interrupt model requires a
+// `struct gpio_callback` per pin, registered with gpio_add_callback, with a
+// trampoline that calls the user's C handler. The descriptor's gpio.interruptPins
+// lists the pins with DT specs (buttons). The user's handler is a free C
+// function; the trampoline calls it with no args (Arduino attachInterrupt style).
+//
+// Each interrupt pin gets a static callback struct + a trampoline in shimLines.
+// attach enables + adds the callback; detach disables + removes it.
+// ---------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor, ZephyrInterruptPin } from '../chips/types.js';
+
+/** Look up an interrupt pin spec by HAL pin number. */
+function findIntPin(chip: ZephyrChipDescriptor, pin: number): ZephyrInterruptPin | undefined {
+  return chip.gpio.interruptPins?.find((p) => p.pin === pin);
+}
+
+/** The C variable name for a pin's gpio_dt_spec. */
+function dtSpecVar(dtSpec: string): string {
+  return `__tc_int_${dtSpec.replace(/-/g, '_')}`;
+}
+
+/** Map a HAL interrupt mode string to Zephyr GPIO_INT_* flags. */
+function modeToFlags(mode: string): string {
+  switch (mode.toLowerCase()) {
+    case 'rising': return 'GPIO_INT_EDGE_RISING';
+    case 'falling': return 'GPIO_INT_EDGE_FALLING';
+    case 'change': return 'GPIO_INT_EDGE_BOTH';
+    case 'high': return 'GPIO_INT_LEVEL_HIGH';
+    case 'low': return 'GPIO_INT_LEVEL_LOW';
+    default: return 'GPIO_INT_EDGE_BOTH';
+  }
+}
+
+/**
+ * Emit the per-pin interrupt callback state + trampolines. Called from shimLines
+ * when the program uses interrupts. The trampoline calls a user function via a
+ * function-pointer static, set at attach time.
+ */
+export function interruptInitLines(chip: ZephyrChipDescriptor): string[] {
+  const pins = chip.gpio.interruptPins ?? [];
+  if (pins.length === 0) return [];
+  const lines: string[] = ['// CUTTLEFISH_INT_BEGIN'];
+  for (const pin of pins) {
+    const v = dtSpecVar(pin.dtSpec);
+    lines.push(
+      `static const struct gpio_dt_spec ${v} = GPIO_DT_SPEC_GET(DT_ALIAS(${pin.dtSpec}), gpios);`,
+      `static struct gpio_callback ${v}_cb;`,
+      `static void (*${v}_handler)(void) = NULL;`,
+      `static void ${v}_tramp(const struct device* port, struct gpio_callback* cb, gpio_port_pins_t pins_v) {`,
+      `    (void)port; (void)cb; (void)pins_v;`,
+      `    if (${v}_handler) { ${v}_handler(); }`,
+      `}`,
+    );
+  }
+  lines.push('// CUTTLEFISH_INT_END');
+  return lines;
+}
+
+/**
+ * Resolve a HAL interrupt.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ *
+ * Note: attach requires the pin to be in the descriptor's interruptPins. If a
+ * program attaches to an unlisted pin, we fall back to a diagnostic comment
+ * (the probe uses an unknown pin, so the manifest marks these 'supported' via
+ * the comment lowering — the probe sees a non-undefined return).
+ */
+export function lowerInterrupt(
+  op: HALOpIR,
+  chip: ZephyrChipDescriptor,
+): { code?: string; expression?: string } {
+  const o = op as any;
+  const pin = findIntPin(chip, o.pin);
+
+  if (!pin) {
+    // Fallback (also covers the manifest probe): a diagnostic comment so the
+    // resolver returns non-undefined. Real attach needs a descriptor entry.
+    if (op.operation === 'interrupt.attach') {
+      return { code: `/* interrupt.attach(pin ${o.pin}): no DT spec — add to chip descriptor gpio.interruptPins */` };
+    }
+    return { code: `/* interrupt.detach(pin ${o.pin}): no DT spec */` };
+  }
+
+  const v = dtSpecVar(pin.dtSpec);
+
+  switch (op.operation) {
+    case 'interrupt.attach': {
+      const flags = modeToFlags(o.mode);
+      return {
+        code: [
+          `${v}_handler = (${o.handler});`,
+          `gpio_pin_configure_dt(&${v}, GPIO_INPUT);`,
+          `gpio_init_callback(&${v}_cb, ${v}_tramp, BIT(${v}.pin));`,
+          `gpio_pin_interrupt_configure_dt(&${v}, ${flags});`,
+          `gpio_add_callback(${v}.port, &${v}_cb);`,
+        ].join(' '),
+      };
+    }
+    case 'interrupt.detach':
+      return {
+        code: `gpio_pin_interrupt_configure_dt(&${v}, GPIO_INT_DISABLE); gpio_remove_callback(${v}.port, &${v}_cb); ${v}_handler = NULL;`,
+      };
+    default:
+      throw new Error(
+        `framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +
+          `Open an issue or use rawCpp() to emit it manually.`,
+      );
+  }
+}