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

package/dist/lowering/hid.js

@@ -0,0 +1,244 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ----------------------------------------------------------------------------
+/** KEY.* token → Zephyr usage macro. Digits and the four modifiers are the
+ *  spellings that differ; everything else maps name-for-name. */
+const KEY_TOKENS = {
+    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 = {
+    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) {
+    return token.startsWith('KEY.') && KEY_MODIFIER_TOKENS[token.slice(4)] !== undefined;
+}
+/** Map a modifier token to its Zephyr bitmask macro. */
+function hidModifierMacro(token) {
+    return KEY_MODIFIER_TOKENS[token.slice(4)];
+}
+const MOUSE_TOKENS = {
+    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, kind) {
+    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) {
+    // 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, chip) {
+    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;
+    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/dist/lowering/i2c.d.ts

@@ -5,6 +5,14 @@ import type { ZephyrChipDescriptor } from '../chips/types.js';
  * controller the program uses (gated on ctx.analysis.usesI2C).
  */
 export declare function i2cInitLines(chip: ZephyrChipDescriptor, controllerIndex: number): string[];
+/**
+ * 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 declare function i2cResponderStateLines(chip: ZephyrChipDescriptor, controllerIndex: number, address: number, rx: number, tx: number): string[];
 /**
  * Resolve a HAL i2c.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.

package/dist/lowering/i2c.js

@@ -40,6 +40,106 @@ function speedForHz(hz) {
         return 'I2C_SPEED_FAST_PLUS';
     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, address) {
+    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, idx) {
+    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, controllerIndex, address, rx, tx) {
+    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
@@ -91,6 +191,46 @@ export function lowerI2c(op, chip) {
             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 = o.bytes ?? [];
+            const isBuffer = bytes.length === 1 && typeof bytes[0] === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(bytes[0]);
+            if (isBuffer) {
+                const name = bytes[0];
+                // 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}\`. ` +
                 `Open an issue or use rawCpp() to emit it manually.`);

package/dist/lowering/i2s.d.ts

@@ -0,0 +1,27 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/** 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 declare function i2sInitLines(chip: ZephyrChipDescriptor, controllerIndex: number, blockBytes: number, usage: I2sUsage): string[];
+/**
+ * Resolve a HAL i2s.* op to Zephyr C++.
+ * Returns `{ code }` for write, `{ expression }` for read/readAt.
+ */
+export declare function lowerI2s(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/i2s.js

@@ -0,0 +1,98 @@
+// ---------------------------------------------------------------------------
+// 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.
+// ---------------------------------------------------------------------------
+/** The C variable names for an I2S controller's state. */
+function prefix(idx) {
+    return `__tc_i2s${idx}`;
+}
+/**
+ * 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, controllerIndex, blockBytes, usage) {
+    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 = [
+        '// 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, chip) {
+    const o = op;
+    // 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 ?? []);
+            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 = [];
+            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/dist/lowering/index.d.ts

@@ -21,7 +21,15 @@ import { lowerFs } from './fs.js';
 import { lowerSensor } from './sensor.js';
 import { lowerHwtimer, lowerCounter } from './hwtimer.js';
 import { lowerThread } from './thread.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, };
+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, lowerTrace, lowerStrip, lowerHid, lowerMatrix, lowerPower, lowerClock, lowerCan, lowerI2s, };
 /**
  * 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

@@ -38,7 +38,15 @@ import { lowerFs } from './fs.js';
 import { lowerSensor } from './sensor.js';
 import { lowerHwtimer, lowerCounter } from './hwtimer.js';
 import { lowerThread } from './thread.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, };
+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, lowerTrace, lowerStrip, lowerHid, lowerMatrix, lowerPower, lowerClock, lowerCan, lowerI2s, };
 /**
  * Lower a HAL op to Zephyr C++. Returns undefined for unsupported categories
  * (mirrors lowerHalOp in framework-esp32/src/lowering/index.ts).
@@ -94,6 +102,22 @@ export function lowerHalOp(op) {
         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
     // validator confirms the unsupported declaration.

package/dist/lowering/matrix.d.ts

@@ -0,0 +1,15 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * Emit the matrix trampoline state. Called from shimLines when the program
+ * uses matrix.* — the listener targets the synthesized tc_matrix node, the
+ * handler pointer is assigned by the on_key lowering.
+ */
+export declare function matrixInitLines(): string[];
+/**
+ * Resolve a HAL matrix.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export declare function lowerMatrix(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};