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

package/src/lowering/hid.ts

@@ -0,0 +1,261 @@
+// ---------------------------------------------------------------------------
+// HID lowering — USB keyboard/mouse over the Zephyr "next" device stack
+//
+// One HID interface per program (Zephyr's zephyr,hid-device node — a v1
+// ceiling like the nRF PWM matrix: Keyboard OR Mouse, not both). The shim
+// block declares the interface device + the boot report buffer + the report
+// descriptor macro; the overlay generator synthesizes the DT node with the
+// protocol the program uses (key verbs → keyboard, mouse verbs → mouse).
+// Key/button arguments arrive as KEY.*/MOUSE.* token text (or runtime
+// expressions) — the token map below translates name-for-name onto Zephyr's
+// HID_KEY_* / button macros, with a build error naming the valid spellings.
+// ----------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+
+/** KEY.* token → Zephyr usage macro. Digits and the four modifiers are the
+ *  spellings that differ; everything else maps name-for-name. */
+const KEY_TOKENS: Record<string, string> = {
+  A: 'HID_KEY_A', B: 'HID_KEY_B', C: 'HID_KEY_C', D: 'HID_KEY_D', E: 'HID_KEY_E',
+  F: 'HID_KEY_F', G: 'HID_KEY_G', H: 'HID_KEY_H', I: 'HID_KEY_I', J: 'HID_KEY_J',
+  K: 'HID_KEY_K', L: 'HID_KEY_L', M: 'HID_KEY_M', N: 'HID_KEY_N', O: 'HID_KEY_O',
+  P: 'HID_KEY_P', Q: 'HID_KEY_Q', R: 'HID_KEY_R', S: 'HID_KEY_S', T: 'HID_KEY_T',
+  U: 'HID_KEY_U', V: 'HID_KEY_V', W: 'HID_KEY_W', X: 'HID_KEY_X', Y: 'HID_KEY_Y',
+  Z: 'HID_KEY_Z',
+  N1: 'HID_KEY_1', N2: 'HID_KEY_2', N3: 'HID_KEY_3', N4: 'HID_KEY_4', N5: 'HID_KEY_5',
+  N6: 'HID_KEY_6', N7: 'HID_KEY_7', N8: 'HID_KEY_8', N9: 'HID_KEY_9', N0: 'HID_KEY_0',
+  ENTER: 'HID_KEY_ENTER', ESC: 'HID_KEY_ESC', BACKSPACE: 'HID_KEY_BACKSPACE',
+  TAB: 'HID_KEY_TAB', SPACE: 'HID_KEY_SPACE',
+  MINUS: 'HID_KEY_MINUS', EQUAL: 'HID_KEY_EQUAL',
+  LEFTBRACE: 'HID_KEY_LEFTBRACE', RIGHTBRACE: 'HID_KEY_RIGHTBRACE',
+  BACKSLASH: 'HID_KEY_BACKSLASH', SEMICOLON: 'HID_KEY_SEMICOLON',
+  APOSTROPHE: 'HID_KEY_APOSTROPHE', GRAVE: 'HID_KEY_GRAVE',
+  COMMA: 'HID_KEY_COMMA', DOT: 'HID_KEY_DOT', SLASH: 'HID_KEY_SLASH',
+  CAPSLOCK: 'HID_KEY_CAPSLOCK',
+  F1: 'HID_KEY_F1', F2: 'HID_KEY_F2', F3: 'HID_KEY_F3', F4: 'HID_KEY_F4',
+  F5: 'HID_KEY_F5', F6: 'HID_KEY_F6', F7: 'HID_KEY_F7', F8: 'HID_KEY_F8',
+  F9: 'HID_KEY_F9', F10: 'HID_KEY_F10', F11: 'HID_KEY_F11', F12: 'HID_KEY_F12',
+  // Zephyr names usage 70 HID_KEY_SYSRQ (the /* PRINTSCREEN */ comment is
+  // its only mention of the name) — the HAL token keeps the datasheet word.
+  PRINTSCREEN: 'HID_KEY_SYSRQ', SCROLLLOCK: 'HID_KEY_SCROLLLOCK',
+  PAUSE: 'HID_KEY_PAUSE', INSERT: 'HID_KEY_INSERT', HOME: 'HID_KEY_HOME',
+  PAGEUP: 'HID_KEY_PAGEUP', DEL: 'HID_KEY_DELETE', END: 'HID_KEY_END',
+  PAGEDOWN: 'HID_KEY_PAGEDOWN', RIGHT: 'HID_KEY_RIGHT', LEFT: 'HID_KEY_LEFT',
+  DOWN: 'HID_KEY_DOWN', UP: 'HID_KEY_UP',
+};
+
+/** Modifier tokens — a separate bitmask enum in Zephyr (usage codes start
+ *  at 4, which collides with modifier bits, so the two kinds CANNOT share
+ *  one runtime branch: the lowering emits different code per kind).
+ *  Exported for the hid.h drift-guard test (every mapped macro must exist
+ *  in Zephyr's header). */
+export const KEY_MODIFIER_TOKENS: Record<string, string> = {
+  CTRL: 'HID_KBD_MODIFIER_LEFT_CTRL',
+  SHIFT: 'HID_KBD_MODIFIER_LEFT_SHIFT',
+  ALT: 'HID_KBD_MODIFIER_LEFT_ALT',
+  // HID usage tables call the Windows/Apple/GUI key "UI" — Zephyr follows.
+  GUI: 'HID_KBD_MODIFIER_LEFT_UI',
+};
+
+/** Is this KEY.* token a modifier (bitmask) rather than a usage code? */
+export function isHidModifierToken(token: string): boolean {
+  return token.startsWith('KEY.') && KEY_MODIFIER_TOKENS[token.slice(4)] !== undefined;
+}
+
+/** Map a modifier token to its Zephyr bitmask macro. */
+function hidModifierMacro(token: string): string {
+  return KEY_MODIFIER_TOKENS[token.slice(4)]!;
+}
+
+const MOUSE_TOKENS: Record<string, string> = {
+  LEFT: 'BIT(0)', RIGHT: 'BIT(1)', MIDDLE: 'BIT(2)',
+};
+
+/** Map a KEY or MOUSE token (or pass a runtime expression through) to C. */
+export function hidTokenToMacro(token: string, kind: 'key' | 'button'): string {
+  const prefix = kind === 'key' ? 'KEY.' : 'MOUSE.';
+  if (!token.startsWith(prefix)) return token; // runtime expression
+  const name = token.slice(prefix.length);
+  const table = kind === 'key' ? KEY_TOKENS : MOUSE_TOKENS;
+  const mapped = table[name];
+  if (!mapped) {
+    const valid = Object.keys(table).map((k) => prefix + k).join(', ');
+    throw new Error(
+      `Unknown ${kind} token '${token}'. Valid spellings: ${valid} (or a runtime number expression).`,
+    );
+  }
+  return mapped;
+}
+
+/**
+ * Emit the HID interface state for one protocol. Called from shimLines when
+ * the program uses hid.* — one device handle, one report buffer, the boot
+ * report descriptor, and the guarded register helper that also starts the
+ * shared usbd context (the same one CDC rides).
+ */
+export function hidInitLines(protocol: 'keyboard' | 'mouse'): string[] {
+  // The boot descriptors: keyboard takes no args; mouse takes its button
+  // count (3 — the MOUSE.LEFT/RIGHT/MIDDLE surface).
+  const desc = protocol === 'keyboard' ? 'HID_KEYBOARD_REPORT_DESC()' : 'HID_MOUSE_REPORT_DESC(3)';
+  // Driver-contract buffers: USB_STATIC_BUF_DEFINE gives pointer alignment
+  // (the DWC2 driver rejects unaligned IN buffers with "Buffer not aligned"
+  // and the completion still fires — every submit silently failed before
+  // this) and the nocache section on builds that require it.
+  const buf = protocol === 'keyboard'
+    ? 'USB_STATIC_BUF_DEFINE(__tc_kb_report, 8);'
+    : 'USB_STATIC_BUF_DEFINE(__tc_mouse_report, 4);';
+  const pragmaWrap = protocol === 'mouse'
+    ? [
+        '#pragma GCC diagnostic push',
+        '#pragma GCC diagnostic ignored "-Wnarrowing"',
+      ]
+    : [];
+  const pragmaUnwrap = protocol === 'mouse' ? ['#pragma GCC diagnostic pop'] : [];
+  return [
+    '// CUTTLEFISH_HID_BEGIN',
+    'static const struct device* __tc_hid_dev = DEVICE_DT_GET_ONE(zephyr_hid_device);',
+    ...pragmaWrap,
+    `static const uint8_t __tc_hid_desc[] = ${desc};`,
+    ...pragmaUnwrap,
+    buf,
+    'static bool __tc_hid_registered = false;',
+    // The API contract: get_report is required for every HID device type
+    // (hid_dev_register rejects NULL ops with -EINVAL), set_protocol is
+    // required for boot-subclass devices (both descriptors here), and
+    // set_report when an output report is declared. Minimal stubs — the
+    // verbs never read host->device state in v1.
+    'static int __tc_hid_get_report(const struct device* dev, const uint8_t type, const uint8_t id, const uint16_t len, uint8_t* const buf) {',
+    '    (void)dev; (void)type; (void)id; (void)len; (void)buf;',
+    '    return -ENOTSUP;',
+    '}',
+    'static int __tc_hid_set_report(const struct device* dev, const uint8_t type, const uint8_t id, const uint16_t len, const uint8_t* const buf) {',
+    '    (void)dev; (void)type; (void)id; (void)len; (void)buf;',
+    '    return 0;',
+    '}',
+    'static void __tc_hid_set_protocol(const struct device* dev, const uint8_t protocol) {',
+    '    (void)dev; (void)protocol;',
+    '}',
+    'static bool __tc_hid_ready = false;',
+    'static void __tc_hid_iface_ready(const struct device* dev, const bool ready) {',
+    '    (void)dev;',
+    '    __tc_hid_ready = ready;',
+    '}',
+    'static uint32_t __tc_hid_idle = 0;',
+    'static void __tc_hid_set_idle(const struct device* dev, const uint8_t id, const uint32_t duration) {',
+    '    (void)dev; (void)id;',
+    '    __tc_hid_idle = duration;',
+    '}',
+    'static uint32_t __tc_hid_get_idle(const struct device* dev, const uint8_t id) {',
+    '    (void)dev; (void)id;',
+    '    return __tc_hid_idle;',
+    '}',
+    'static void __tc_hid_output_report(const struct device* dev, const uint16_t len, const uint8_t* const buf) {',
+    '    (void)dev; (void)len; (void)buf;',
+    '}',
+    'static const struct hid_device_ops __tc_hid_ops = {',
+    '    .iface_ready = __tc_hid_iface_ready,',
+    '    .get_report = __tc_hid_get_report,',
+    '    .set_report = __tc_hid_set_report,',
+    '    .set_idle = __tc_hid_set_idle,',
+    '    .get_idle = __tc_hid_get_idle,',
+    '    .set_protocol = __tc_hid_set_protocol,',
+    '    .output_report = __tc_hid_output_report,',
+    '};',
+    'static void __tc_hid_register(void) {',
+    '    if (__tc_hid_registered) { return; }',
+    '    __tc_hid_registered = true;',
+    '    int err = hid_device_register(__tc_hid_dev, __tc_hid_desc, sizeof(__tc_hid_desc), &__tc_hid_ops);',
+    '    if (err != 0) { printk("typecad-hal hid: register failed: %d\\n", err); return; }',
+    '    __tc_usbd_start();',
+    '}',
+    'static void __tc_hid_submit(const uint8_t* rep, uint16_t len) {',
+    '    int err = hid_device_submit_report(__tc_hid_dev, len, rep);',
+    '    // -EACCES is the normal pre-enumeration race (submit before the',
+    '    // host configures the interface) — not worth a printk; every other',
+    '    // errno (e.g. the alignment error that silently ate reports once)',
+    '    // deserves to be loud.',
+    '    if (err != 0 && err != -EACCES) { printk("typecad-hal hid: submit failed: %d\\n", err); }',
+    '}',
+    '// CUTTLEFISH_HID_END',
+  ];
+}
+
+/**
+ * Resolve a HAL hid.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerHid(op: HALOpIR, chip: ZephyrChipDescriptor): { code?: string; expression?: string } {
+  if (!chip.usb) {
+    throw new Error(
+      `framework-zephyr: \`${op.operation}\` needs a USB device stack, but this board's chip data declares no \`zephyr.usb\` ` +
+      `(controller + cdcInstances). Boards whose Zephyr DTS has no enabled UDC controller node ` +
+      `(zephyr_udc0) cannot provide USB HID.`,
+    );
+  }
+  const o = op as any;
+
+  switch (op.operation) {
+    case 'hid.kb_begin':
+      return { code: '__tc_hid_register();' };
+    case 'hid.kb_press': {
+      // Modifier tokens are compile-time bitmasks — a different emit than
+      // the usage-code slot logic (runtime expressions take the key path).
+      if (isHidModifierToken(String(o.key))) {
+        const mod = hidModifierMacro(String(o.key));
+        return {
+          code: `{ __tc_hid_register(); __tc_kb_report[0] = static_cast<uint8_t>(__tc_kb_report[0] | ${mod}); __tc_hid_submit(__tc_kb_report, 8U); }`,
+        };
+      }
+      const key = hidTokenToMacro(String(o.key), 'key');
+      return {
+        code: `{ __tc_hid_register(); uint8_t __tc_k = static_cast<uint8_t>(${key}); for (uint32_t __tc_slot = 2U; __tc_slot < 8U; ++__tc_slot) { if (__tc_kb_report[__tc_slot] == 0U) { __tc_kb_report[__tc_slot] = __tc_k; break; } } __tc_hid_submit(__tc_kb_report, 8U); }`,
+      };
+    }
+    case 'hid.kb_release': {
+      if (isHidModifierToken(String(o.key))) {
+        const mod = hidModifierMacro(String(o.key));
+        return {
+          code: `{ __tc_hid_register(); __tc_kb_report[0] = static_cast<uint8_t>(__tc_kb_report[0] & static_cast<uint8_t>(~${mod})); __tc_hid_submit(__tc_kb_report, 8U); }`,
+        };
+      }
+      const key = hidTokenToMacro(String(o.key), 'key');
+      return {
+        code: `{ __tc_hid_register(); uint8_t __tc_k = static_cast<uint8_t>(${key}); for (uint32_t __tc_slot = 2U; __tc_slot < 8U; ++__tc_slot) { if (__tc_kb_report[__tc_slot] == __tc_k) { __tc_kb_report[__tc_slot] = 0U; } } __tc_hid_submit(__tc_kb_report, 8U); }`,
+      };
+    }
+    case 'hid.kb_release_all':
+      return {
+        code: `{ __tc_hid_register(); for (uint32_t __tc_slot = 0U; __tc_slot < 8U; ++__tc_slot) { __tc_kb_report[__tc_slot] = 0U; } __tc_hid_submit(__tc_kb_report, 8U); }`,
+      };
+    case 'hid.mouse_begin':
+      return { code: '__tc_hid_register();' };
+    case 'hid.mouse_move': {
+      return {
+        code: `{ __tc_hid_register(); int32_t __tc_mx = static_cast<int32_t>(${o.dx}); int32_t __tc_my = static_cast<int32_t>(${o.dy}); int32_t __tc_mw = static_cast<int32_t>(${o.wheel}); if (__tc_mx > 127) { __tc_mx = 127; } if (__tc_mx < -127) { __tc_mx = -127; } if (__tc_my > 127) { __tc_my = 127; } if (__tc_my < -127) { __tc_my = -127; } if (__tc_mw > 127) { __tc_mw = 127; } if (__tc_mw < -127) { __tc_mw = -127; } __tc_mouse_report[1] = static_cast<uint8_t>(__tc_mx); __tc_mouse_report[2] = static_cast<uint8_t>(__tc_my); __tc_mouse_report[3] = static_cast<uint8_t>(__tc_mw); __tc_hid_submit(__tc_mouse_report, 4U); }`,
+      };
+    }
+    case 'hid.mouse_press':
+    case 'hid.mouse_release': {
+      const btn = hidTokenToMacro(String(o.button), 'button');
+      const opText = op.operation === 'hid.mouse_press' ? '|' : '&';
+      const mask = op.operation === 'hid.mouse_press'
+        ? btn
+        : `static_cast<uint8_t>(~${btn})`;
+      return {
+        code: `{ __tc_hid_register(); __tc_mouse_report[0] = static_cast<uint8_t>(__tc_mouse_report[0] ${opText} ${mask}); __tc_hid_submit(__tc_mouse_report, 4U); }`,
+      };
+    }
+    case 'hid.mouse_click': {
+      const btn = hidTokenToMacro(String(o.button), 'button');
+      return {
+        code: `{ __tc_hid_register(); __tc_mouse_report[0] = static_cast<uint8_t>(__tc_mouse_report[0] | ${btn}); __tc_hid_submit(__tc_mouse_report, 4U); __tc_mouse_report[0] = static_cast<uint8_t>(__tc_mouse_report[0] & static_cast<uint8_t>(~${btn})); __tc_hid_submit(__tc_mouse_report, 4U); }`,
+      };
+    }
+    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

@@ -43,6 +43,109 @@ function speedForHz(hz: number): string {
   return 'I2C_SPEED_HIGH';
 }
 
+// ── I2C responder (hal/i2c-responder.ts) — this board as an I2C target ────
+//
+// One state block per constructed responder (bus + address), the i2c_target
+// vocabulary verbatim: the five driver callbacks behind two user-facing ones
+// (onReceive fires at STOP with the receive ring's new byte count; onRequest
+// fires at read start — the write() refill point). Registration
+// (i2c_target_register) is once-guarded at the first op, against the
+// controller handle the master-side init block emitted (__tc_i2c<N>_dev).
+
+/** The C symbol prefix for one responder's state. */
+function respPrefix(idx: number, address: number): string {
+  return `__tc_i2cresp${idx}_a${address.toString(16)}`;
+}
+
+/** The once-guarded registration every responder op carries — the UART arm
+ *  discipline: the first emitted call registers the address, so the
+ *  callbacks installed early in setup make it answer from boot. An
+ *  unsupported controller prints loudly (the CAN policy: -ENOSYS from a
+ *  driver with no target mode must not be a silent empty responder). */
+function respRegisterGuard(p: string, idx: number): string {
+  return `{ if (!${p}_registered) { ${p}_registered = true; int __tc_err = i2c_target_register(__tc_i2c${idx}_dev, &${p}_cfg); if (__tc_err != 0) { printk("typecad-hal i2c responder: target_register failed: %d\\n", __tc_err); } } } `;
+}
+
+/**
+ * Emit one responder's state: receive ring (UART discipline — free-running
+ * head/tail, overflow-drop), response buffer with its served position, the
+ * two handler slots, the five i2c_target callbacks, and the config the ops'
+ * registration guard passes to i2c_target_register. Called from shimLines
+ * for each constructed responder (collectI2cResponders).
+ */
+export function i2cResponderStateLines(chip: ZephyrChipDescriptor, controllerIndex: number, address: number, rx: number, tx: number): string[] {
+  const ctrl = chip.i2c?.controllers[controllerIndex];
+  if (!ctrl) return [];
+  const p = respPrefix(controllerIndex, address);
+  return [
+    '// CUTTLEFISH_I2CRESP_BEGIN',
+    `static uint8_t ${p}_rx[${rx}];`,
+    `static volatile uint32_t ${p}_head = 0;`,
+    `static volatile uint32_t ${p}_tail = 0;`,
+    `static uint8_t ${p}_tx[${tx}];`,
+    `static volatile uint32_t ${p}_txlen = 0;`,
+    `static volatile uint32_t ${p}_txpos = 0;`,
+    `static void (*${p}_on_rx)(double) = NULL;`,
+    `static void (*${p}_on_rq)(void) = NULL;`,
+    // A controller write transaction: reset the ring, then take each byte.
+    // A byte arriving with a full ring is dropped — the embedded-honest
+    // answer (no unbounded buffering), same as the UART RX ring.
+    `static int ${p}_write_requested(struct i2c_target_config* cfg) {`,
+    '    (void)cfg;',
+    `    ${p}_head = 0;`,
+    `    ${p}_tail = 0;`,
+    '    return 0;',
+    '}',
+    `static int ${p}_write_received(struct i2c_target_config* cfg, uint8_t val) {`,
+    '    (void)cfg;',
+    `    if ((${p}_head - ${p}_tail) < ${rx}U) {`,
+    `        ${p}_rx[${p}_head % ${rx}U] = val;`,
+    `        ${p}_head++;`,
+    '    }',
+    '    return 0;',
+    '}',
+    // A controller read transaction: the user's refill point first, then the
+    // first byte. Past the buffer's end the controller reads 0xFF (the bus
+    // has no NACK for a too-long read; the value is the honest filler).
+    `static int ${p}_read_requested(struct i2c_target_config* cfg, uint8_t* val) {`,
+    '    (void)cfg;',
+    `    if (${p}_on_rq != NULL) { ${p}_on_rq(); }`,
+    `    ${p}_txpos = 1U;`,
+    `    *val = (${p}_txlen > 0U) ? ${p}_tx[0] : 0xFFU;`,
+    '    return 0;',
+    '}',
+    `static int ${p}_read_processed(struct i2c_target_config* cfg, uint8_t* val) {`,
+    '    (void)cfg;',
+    `    *val = (${p}_txpos < ${p}_txlen) ? ${p}_tx[${p}_txpos] : 0xFFU;`,
+    `    ${p}_txpos++;`,
+    '    return 0;',
+    '}',
+    // End of transaction: announce a completed controller write with the
+    // count now waiting in the ring (the Wire onReceive(len) semantic).
+    `static int ${p}_stop(struct i2c_target_config* cfg) {`,
+    '    (void)cfg;',
+    `    if ((${p}_on_rx != NULL) && (${p}_head > ${p}_tail)) {`,
+    `        ${p}_on_rx(static_cast<double>(${p}_head - ${p}_tail));`,
+    '    }',
+    '    return 0;',
+    '}',
+    `static const struct i2c_target_callbacks ${p}_cbs = {`,
+    `    .write_requested = ${p}_write_requested,`,
+    `    .read_requested = ${p}_read_requested,`,
+    `    .write_received = ${p}_write_received,`,
+    `    .read_processed = ${p}_read_processed,`,
+    `    .stop = ${p}_stop,`,
+    '};',
+    `static struct i2c_target_config ${p}_cfg = {`,
+    '    .flags = 0U,',
+    `    .address = ${address}U,`,
+    `    .callbacks = &${p}_cbs,`,
+    '};',
+    `static bool ${p}_registered = false;`,
+    '// CUTTLEFISH_I2CRESP_END',
+  ];
+}
+
 /** 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
@@ -98,6 +201,49 @@ export function lowerI2c(
       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}));` };
     }
+
+    // ── I2C responder (hal/i2c-responder.ts) — target-mode ops ───────────
+    // Every op carries the once-guarded registration; the state it touches
+    // is the per-responder block i2cResponderStateLines emitted.
+    case 'i2c.resp_on_receive': {
+      const rp = respPrefix(idx, o.address);
+      return { code: `${respRegisterGuard(rp, idx)} ${rp}_on_rx = ${o.handler};` };
+    }
+    case 'i2c.resp_on_request': {
+      const rp = respPrefix(idx, o.address);
+      return { code: `${respRegisterGuard(rp, idx)} ${rp}_on_rq = ${o.handler};` };
+    }
+    case 'i2c.resp_available': {
+      const rp = respPrefix(idx, o.address);
+      return { expression: `({ ${respRegisterGuard(rp, idx)} (${rp}_head - ${rp}_tail); })` };
+    }
+    case 'i2c.resp_read': {
+      const rp = respPrefix(idx, o.address);
+      return { expression: `({ ${respRegisterGuard(rp, idx)} (${rp}_tail < ${rp}_head ? ${rp}_rx[(${rp}_tail)++ % ${o.rx}U] : -1); })` };
+    }
+    case 'i2c.resp_write': {
+      const rp = respPrefix(idx, o.address);
+      const bytes: unknown[] = o.bytes ?? [];
+      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: copy its storage into the response buffer,
+        // clamped to the constructed size; the length lands last so an
+        // in-flight read never sees a torn buffer.
+        return {
+          code: `${respRegisterGuard(rp, idx)} { ${rp}_txlen = 0U; for (uint32_t __tc_i = 0U; (__tc_i < sizeof(${name})) && (__tc_i < ${o.tx}U); ++__tc_i) { ${rp}_tx[__tc_i] = ${name}[__tc_i]; } ${rp}_txlen = (sizeof(${name}) < ${o.tx}U) ? static_cast<uint32_t>(sizeof(${name})) : ${o.tx}U; }`,
+        };
+      }
+      if (bytes.length > Number(o.tx)) {
+        throw new Error(
+          `I2C responder write: the response buffer holds ${o.tx} bytes — got ${bytes.length}. Construct with a larger txBufferBytes.`,
+        );
+      }
+      const assigns = bytes
+        .map((b, i) => `${rp}_tx[${i}] = static_cast<uint8_t>(${b});`)
+        .join(' ');
+      return { code: `${respRegisterGuard(rp, idx)} { ${rp}_txlen = 0U; ${assigns} ${rp}_txlen = ${bytes.length}U; }` };
+    }
     default:
       throw new Error(
         `framework-zephyr does not yet support HAL op \`${op.operation}\`. ` +

package/src/lowering/i2s.ts

@@ -0,0 +1,143 @@
+// ---------------------------------------------------------------------------
+// I2S lowering — Zephyr's i2s API over the harvested controller node
+//
+// The controller is addressed by its DT nodelabel (chip.i2s, the harvested
+// i2s@ node — ESP32 I2S0/1). Each direction lazy-inits on first use (the
+// PWM discipline): configure + trigger START once, then every write/read is
+// one block. The shim owns the mem slab (2 blocks), the TX packing buffer,
+// and the RX receive buffer; blockAt/readAt index the last received block.
+// ---------------------------------------------------------------------------
+
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+
+/** The C variable names for an I2S controller's state. */
+function prefix(idx: number): string {
+  return `__tc_i2s${idx}`;
+}
+
+/** Which i2s.* verbs the program actually uses on a controller — the init
+ *  block emits only the state those verbs reference (a write-only program
+ *  must not carry an unused rx buffer: -Werror fails the build). */
+export interface I2sUsage {
+  write: boolean;
+  read: boolean;
+  readAt: boolean;
+}
+
+/**
+ * Emit the per-controller I2S state: device handle, mem slab, TX/RX block
+ * buffers, and the lazy per-direction init helpers. Called from shimLines
+ * when the program uses i2s.* on this controller and the chip declares it.
+ * The once-flags live HERE (shim scope), not in the lowered call sites — a
+ * second write() statement must not reconfigure/re-start a running stream
+ * (i2s_configure is legal only before the first trigger).
+ */
+export function i2sInitLines(chip: ZephyrChipDescriptor, controllerIndex: number, blockBytes: number, usage: I2sUsage): string[] {
+  const ctrl = chip.i2s?.controllers[controllerIndex];
+  if (!ctrl) return [];
+  const p = prefix(controllerIndex);
+  // readAt rides the RX engine too (its lowering lazily starts RX like read
+  // does) — a readAt-only program still references the whole engine state.
+  const needsEngine = usage.write || usage.read || usage.readAt;
+  const lines: string[] = [
+    '// CUTTLEFISH_I2S_BEGIN',
+    `static const struct device* ${p}_dev = DEVICE_DT_GET(DT_NODELABEL(${ctrl.nodeLabel}));`,
+  ];
+  if (needsEngine) {
+    lines.push(
+      `K_MEM_SLAB_DEFINE_STATIC(${p}_slab, ${blockBytes}, 2, 4);`,
+      `K_MEM_SLAB_DEFINE_STATIC(${p}_rxslab, ${blockBytes}, 2, 4);`,
+      `static void ${p}_init(uint32_t hz, uint8_t channels, uint8_t bits, size_t block_bytes) {`,
+      '    struct i2s_config cfg = { 0 };',
+      '    cfg.word_size = bits;',
+      '    cfg.channels = channels;',
+      '    cfg.format = I2S_FMT_DATA_FORMAT_I2S;',
+      '    cfg.options = 0;',
+      '    cfg.frame_clk_freq = hz;',
+      `    cfg.mem_slab = &${p}_slab;`,
+      '    cfg.block_size = block_bytes;',
+      '    cfg.timeout = 200;',
+      `    int err = i2s_configure(${p}_dev, I2S_DIR_TX, &cfg);`,
+      '    if (err != 0) { printk("typecad-hal i2s: tx configure failed: %d\\n", err); }',
+      `    cfg.mem_slab = &${p}_rxslab;`,
+      `    err = i2s_configure(${p}_dev, I2S_DIR_RX, &cfg);`,
+      '    if (err != 0) { printk("typecad-hal i2s: rx configure failed: %d\\n", err); }',
+      '}',
+      `static bool ${p}_init_done = false;`,
+    );
+  }
+  if (usage.write) {
+    lines.push(
+      `static int16_t ${p}_txbuf[${blockBytes / 2}];`,
+      `static bool ${p}_tx_started = false;`,
+    );
+  }
+  if (usage.read || usage.readAt) {
+    lines.push(`static int16_t ${p}_rxbuf[${blockBytes / 2}];`);
+    lines.push(`static bool ${p}_rx_started = false;`);
+  }
+  lines.push('// CUTTLEFISH_I2S_END');
+  return lines;
+}
+
+/**
+ * Resolve a HAL i2s.* op to Zephyr C++.
+ * Returns `{ code }` for write, `{ expression }` for read/readAt.
+ */
+export function lowerI2s(
+  op: HALOpIR,
+  chip: ZephyrChipDescriptor,
+): { code?: string; expression?: string } {
+  const o = op as any;
+  // DAC discipline: no harvested i2s@ node lowers to the honest comment.
+  if (!chip.i2s || chip.i2s.controllers.length === 0) {
+    return { code: `/* ${op.operation}: this board's chip data declares no I2S controller (no harvested i2s@ node) */` };
+  }
+  const idx = Math.min(Number(o.instance ?? 0), chip.i2s.controllers.length - 1);
+  const p = prefix(idx);
+  const hz = Number(o.hz ?? 16000);
+  const channels = Number(o.channels ?? 2);
+  const bits = Number(o.bits ?? 16);
+  const blockFrames = Number(o.blockFrames ?? 64);
+  const blockBytes = blockFrames * channels * (bits / 8);
+
+  switch (op.operation) {
+    case 'i2s.write': {
+      const samples = (o.samples ?? []) as (number | string)[];
+      const cap = blockFrames * channels;
+      if (samples.length > cap) {
+        throw new Error(
+          `I2S write: one block carries at most ${cap} samples (${blockFrames} frames × ${channels} channels) — got ${samples.length}.`,
+        );
+      }
+      // Zero-pad to the full block; samples are 16-bit.
+      const writes: string[] = [];
+      for (let i = 0; i < cap; i++) {
+        const v = i < samples.length ? samples[i] : 0;
+        writes.push(`${p}_txbuf[${i}] = static_cast<int16_t>(${v});`);
+      }
+      return {
+        code: `{ if (!${p}_init_done) { ${p}_init_done = true; ${p}_init(${hz}U, ${channels}U, ${bits}U, ${blockBytes}U); } ${writes.join(' ')} int err = i2s_buf_write(${p}_dev, ${p}_txbuf, ${blockBytes}U); if (err != 0) { printk("typecad-hal i2s: write failed: %d\\n", err); } else { if (!${p}_tx_started) { ${p}_tx_started = true; err = i2s_trigger(${p}_dev, I2S_DIR_TX, I2S_TRIGGER_START); if (err != 0) { printk("typecad-hal i2s: tx start failed: %d\\n", err); } } } }`,
+      };
+    }
+    case 'i2s.read': {
+      return {
+        expression: `({ if (!${p}_init_done) { ${p}_init_done = true; ${p}_init(${hz}U, ${channels}U, ${bits}U, ${blockBytes}U); } if (!${p}_rx_started) { ${p}_rx_started = true; int err = i2s_trigger(${p}_dev, I2S_DIR_RX, I2S_TRIGGER_START); if (err != 0) { printk("typecad-hal i2s: rx start failed: %d\\n", err); } } size_t got = 0U; int err = i2s_buf_read(${p}_dev, ${p}_rxbuf, &got); if (err != 0) { printk("typecad-hal i2s: read failed: %d\\n", err); } static_cast<double>(${p}_rxbuf[0]); })`,
+      };
+    }
+    case 'i2s.read_at': {
+      // Same lazy RX start as read(): readAt indexes the last RECEIVED
+      // block, so the stream must be running — and a readAt-only program
+      // references (and therefore compiles in) the whole engine state.
+      return {
+        expression: `({ if (!${p}_init_done) { ${p}_init_done = true; ${p}_init(${hz}U, ${channels}U, ${bits}U, ${blockBytes}U); } if (!${p}_rx_started) { ${p}_rx_started = true; int err = i2s_trigger(${p}_dev, I2S_DIR_RX, I2S_TRIGGER_START); if (err != 0) { printk("typecad-hal i2s: rx start failed: %d\\n", err); } } int32_t at = static_cast<int32_t>(${o.index}); double v = 0.0; if (at >= 0 && static_cast<uint32_t>(at) < (sizeof(${p}_rxbuf) / sizeof(${p}_rxbuf[0]))) { v = static_cast<double>(${p}_rxbuf[at]); } v; })`,
+      };
+    }
+    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

@@ -40,12 +40,21 @@ import { lowerFs } from './fs.js';
 import { lowerSensor } from './sensor.js';
 import { lowerHwtimer, lowerCounter } from './hwtimer.js';
 import { lowerThread } from './thread.js';
+import { lowerTrace } from './trace.js';
+import { lowerStrip } from './strip.js';
+import { lowerHid } from './hid.js';
+import { lowerMatrix } from './matrix.js';
+import { lowerPower } from './power.js';
+import { lowerClock } from './clock.js';
+import { lowerCan } from './can.js';
+import { lowerI2s } from './i2s.js';
 
 export {
   lowerGpio, lowerTiming, lowerAdc, lowerPwm, lowerI2c, lowerSpi, lowerUart,
   lowerUsb, lowerInterrupt, lowerWdt, lowerBle,
   lowerWifi, lowerHttp, lowerMqtt, lowerPreferences, lowerBoard, lowerRandom,
-  lowerDac, lowerFs, lowerHwtimer, lowerCounter, lowerSensor, lowerThread,
+  lowerDac, lowerFs, lowerHwtimer, lowerCounter, lowerSensor, lowerThread, lowerTrace,
+  lowerStrip, lowerHid, lowerMatrix, lowerPower, lowerClock, lowerCan, lowerI2s,
 };
 
 /**
@@ -83,6 +92,14 @@ export function lowerHalOp(
   if (op.operation.startsWith('random.')) return lowerRandom(op);
   if (op.operation.startsWith('sensor.')) return lowerSensor(op);
   if (op.operation.startsWith('thread.'))   return lowerThread(op);
+  if (op.operation.startsWith('trace.'))    return lowerTrace(op);
+  if (op.operation.startsWith('strip.'))    return lowerStrip(op, chip);
+  if (op.operation.startsWith('hid.'))      return lowerHid(op, chip);
+  if (op.operation.startsWith('matrix.'))   return lowerMatrix(op);
+  if (op.operation.startsWith('power.'))    return lowerPower(op, chip);
+  if (op.operation.startsWith('clock.'))    return lowerClock(op);
+  if (op.operation.startsWith('can.'))      return lowerCan(op, chip);
+  if (op.operation.startsWith('i2s.'))      return lowerI2s(op, chip);
 
   // raw / snprintf.emit / display.* / ... — not lowered by this
   // framework. Return undefined so the transpiler falls back and the manifest