@typecad/framework-zephyr 1.0.0-alpha.14 → 1.0.0-alpha.16

package/dist/lowering/spi.js

@@ -12,11 +12,54 @@
 // DEVICE_DT_GET(DT_NODELABEL(spi2)) and call spi_transceive directly.
 // ---------------------------------------------------------------------------
 import { parseControllerIndex } from './util.js';
-import { controllerNodelabelForPin, controllerRawPinForPin } from '../chips/controllers.js';
 /** The C variable prefix for a controller's state. */
 function prefix(idx) {
     return `__tc_spi${idx}`;
 }
+/** Derive a thin SPI target's names from the op facts. */
+export function spiTargetNames(bus, cs) {
+    const busIndex = parseControllerIndex(typeof bus === 'string' ? bus : String(bus));
+    const csNum = typeof cs === 'number' ? cs : parseInt(String(cs), 10);
+    const stem = `spit_spi${busIndex}_cs${csNum}`;
+    return { dtLabel: `tc_${stem}`, varName: `__tc_${stem}_spec`, busIndex, cs: csNum };
+}
+/** The per-target state block: one spi_dt_spec against the DT child node the
+ *  overlay emits, plus the tc-spit-cfg comment the overlay scanner reads (the
+ *  tc-sensor-cfg channel). Called from shimLines for each distinct target. */
+export function spiTargetStateLines(bus, cs, hz = 0, mode = 0) {
+    const n = spiTargetNames(bus, cs);
+    return [
+        '// CUTTLEFISH_SPIT_BEGIN',
+        // Zephyr 4.4's SPI_DT_SPEC_GET takes the base operation explicitly (mode
+        // bits come from the DT node's spi-cpol/spi-cpha via SPI_CONFIG_DT).
+        `static const struct spi_dt_spec ${n.varName} = SPI_DT_SPEC_GET(DT_NODELABEL(${n.dtLabel}), SPI_OP_MODE_MASTER | SPI_WORD_SET(8), 0);`,
+        `// tc-spit-cfg: ${n.dtLabel} hz=${Number(hz)} mode=${Number(mode)}`,
+        '// CUTTLEFISH_SPIT_END',
+    ];
+}
+/** Build the tx buffer declaration + set for a thin SPI op. A literal byte
+ *  array becomes a local array; a single identifier is the user's own buffer
+ *  (its storage + sizeof drive length). spi_buf.buf is void*, and the user's
+ *  buffer may be const-qualified — cast through const void* to stay legal
+ *  under -Werror without mutating anyone's qualifications. */
+function spiTxBuffers(tx, tag) {
+    const bytes = (Array.isArray(tx) ? tx : []);
+    // Only an identifier-shaped string is a real caller buffer — the resolver
+    // collapses a single-byte literal array to buffer-kind with NUMERIC text
+    // (e.g. "159"), which must take the literal path below.
+    const isIdentifier = bytes.length === 1 && typeof bytes[0] === 'string' && /^[A-Za-z_][A-Za-z0-9_]*$/.test(bytes[0]);
+    if (isIdentifier) {
+        const name = bytes[0];
+        return {
+            decl: `const struct spi_buf __tb${tag} = { .buf = const_cast<void*>(static_cast<const void*>(${name})), .len = sizeof(${name}) }; const struct spi_buf_set __txs${tag} = { .buffers = &__tb${tag}, .count = 1 };`,
+            set: `__txs${tag}`,
+        };
+    }
+    return {
+        decl: `uint8_t __tx${tag}[] = { ${bytes.join(', ')} }; const struct spi_buf __tb${tag} = { .buf = __tx${tag}, .len = sizeof(__tx${tag}) }; const struct spi_buf_set __txs${tag} = { .buffers = &__tb${tag}, .count = 1 };`,
+        set: `__txs${tag}`,
+    };
+}
 /**
  * Emit the per-controller SPI state. The bus device resolves at compile time;
  * a static spi_config holds the base operation flags, and mutable runtime fields
@@ -39,7 +82,9 @@ export function spiInitLines(chip, controllerIndex) {
         `};`,
         `static void ${p}_init(void) {`,
         `    if (!${p}_ready) {`,
-        `        ${p}_cfg.bus = ${p}_dev;`,
+        // NOTE: no .bus assignment — struct spi_config lost its `bus` member in
+        // Zephyr 4.x (deprecated 3.5, removed 4.0); spi_transceive takes the
+        // device alongside the config, which the ops below already do.
         `        ${p}_cfg.operation = SPI_OP_MODE_MASTER | SPI_WORD_SET(8)`,
         `            | (${p}_lsb ? SPI_TRANSFER_LSB : SPI_TRANSFER_MSB)`,
         `            | ((${p}_mode & 0x1) ? SPI_MODE_CPOL : 0)`,
@@ -59,51 +104,31 @@ export function lowerSpi(op, chip) {
     const idx = parseControllerIndex(o.bus);
     const p = prefix(idx);
     switch (op.operation) {
-        case 'spi.begin':
-            return { code: `${p}_init();` };
-        case 'spi.end':
-            return { code: `spi_release(${p}_dev, &${p}_cfg);` };
-        case 'spi.begin_transaction':
-            // Config is static; transaction begin is a no-op (frequency/mode baked in).
-            return { code: `${p}_init();` };
-        case 'spi.end_transaction':
-            return { code: `(void)0;` };
-        case 'spi.set_mode':
-            // Apply CPOL/CPHA: store the mode byte then re-init so the next transfer
-            // picks up the rebuilt operation flags. The ready flag is cleared so
-            // _init() rebuilds rather than early-returning.
-            return { code: `{ ${p}_mode = static_cast<uint8_t>(${o.mode}); ${p}_ready = false; ${p}_init(); }` };
-        case 'spi.set_bit_order': {
-            // The HAL payload `order` is a string ("lsb" | "msb"), per SpiSetBitOrderOp.
-            // Normalize here in TS so we emit a boolean literal, not the raw string
-            // (which would be an undeclared C++ identifier).
-            const key = String(o.order).replace(/^["']|["']$/g, '').toLowerCase();
-            const lsb = (key === 'lsb' || key === 'lsbfirst') ? 'true' : 'false';
-            return { code: `{ ${p}_lsb = ${lsb}; ${p}_ready = false; ${p}_init(); }` };
-        }
-        case 'spi.transfer': {
-            // Single-byte full-duplex, returns the received byte (GCC stmt-expr).
+        case 'spi.transceive': {
+            const v = spiTargetNames(o.bus, o.cs).varName;
+            const tx = spiTxBuffers(o.tx, 't');
+            const rxName = String(o.rx ?? '');
+            const rx = rxName
+                ? `struct spi_buf __rb = { .buf = const_cast<void*>(static_cast<const void*>(${rxName})), .len = sizeof(${rxName}) }; const struct spi_buf_set __rbs = { .buffers = &__rb, .count = 1 };`
+                : `const struct spi_buf_set __rbs = { .buffers = NULL, .count = 0 };`;
             return {
-                expression: `({ uint8_t __tx = static_cast<uint8_t>(${o.data}); uint8_t __rx = 0; struct spi_buf __tb = { .buf = &__tx, .len = 1 }; struct spi_buf_set __tbs = { .buffers = &__tb, .count = 1 }; struct spi_buf __rb = { .buf = &__rx, .len = 1 }; struct spi_buf_set __rbs = { .buffers = &__rb, .count = 1 }; ${p}_init(); spi_transceive(${p}_dev, &${p}_cfg, &__tbs, &__rbs); __rx; })`,
+                code: `{ ${tx.decl} ${rx} (void)spi_transceive_dt(&${v}, &${tx.set}, &__rbs); }`,
             };
         }
-        case 'spi.read_buffer': {
-            // Read count bytes by sending 0xFF dummy bytes (full-duplex read).
-            const count = o.count;
+        case 'spi.dev_write': {
+            const v = spiTargetNames(o.bus, o.cs).varName;
+            const tx = spiTxBuffers(o.tx, 'w');
             return {
-                code: `{ uint8_t __dummy[${count}] = {0}; for (int __i = 0; __i < (int)(${count}); __i++) __dummy[__i] = 0xFF; struct spi_buf __tb = { .buf = __dummy, .len = ${count} }; struct spi_buf_set __tbs = { .buffers = &__tb, .count = 1 }; struct spi_buf __rb = { .buf = reinterpret_cast<void*>(${o.buffer}), .len = ${count} }; struct spi_buf_set __rbs = { .buffers = &__rb, .count = 1 }; ${p}_init(); spi_transceive(${p}_dev, &${p}_cfg, &__tbs, &__rbs); }`,
+                code: `{ ${tx.decl} (void)spi_write_dt(&${v}, &${tx.set}); }`,
             };
         }
-        case 'spi.cs_low':
-        case 'spi.cs_high': {
-            // CS driven as a plain GPIO via the owning controller (the CS pin comes
-            // from the op's `pin` field; Zephyr uses gpio_pin_set_raw). Resolve the
-            // controller by pin so a CS on a high-numbered pin (ESP32-S3 gpio1) lands
-            // on the right node.
-            const val = op.operation === 'spi.cs_low' ? 0 : 1;
-            const gpioController = controllerNodelabelForPin(chip, o.pin);
+        case 'spi.reg_read': {
+            // One-byte register read against an INTERNAL buffer — no caller array
+            // (sidesteps the file-scope Uint8Array promotion issue; also just the
+            // right shape for ID/status registers).
+            const v = spiTargetNames(o.bus, o.cs).varName;
             return {
-                code: `gpio_pin_set_raw(DEVICE_DT_GET(DT_NODELABEL(${gpioController})), ${controllerRawPinForPin(chip, o.pin)}, ${val});`,
+                expression: `({ uint8_t __txr = static_cast<uint8_t>(${o.reg}); uint8_t __rxr = 0; struct spi_buf __tbr = { .buf = &__txr, .len = 1 }; const struct spi_buf_set __txsr = { .buffers = &__tbr, .count = 1 }; struct spi_buf __rbr = { .buf = &__rxr, .len = 1 }; const struct spi_buf_set __rxsr = { .buffers = &__rbr, .count = 1 }; (void)spi_transceive_dt(&${v}, &__txsr, &__rxsr); __rxr; })`,
             };
         }
         default:

package/dist/lowering/thread.d.ts

@@ -0,0 +1,14 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/**
+ * Emit the per-thread state. Called from shimLines for each distinct thread
+ * the program starts.
+ */
+export declare function threadStateLines(instance: number, stackBytes: number): string[];
+/**
+ * Resolve a HAL thread.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export declare function lowerThread(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/thread.js

@@ -0,0 +1,55 @@
+// ---------------------------------------------------------------------------
+// Thread lowering — Zephyr kernel threads (k_thread_create / k_thread_join)
+//
+// One state block per thread identity slot the program STARTS: a static
+// K_THREAD_STACK_DEFINE (sized by the construction stackKb), the k_thread
+// struct, and an entry trampoline bridging Zephyr's (void*, void*, void*)
+// entry signature to the no-argument registered callback. start() creates
+// and schedules (K_NO_WAIT); join() blocks (K_FOREVER).
+//
+// No devicetree, no Kconfig — kernel.h (always included) is the whole
+// dependency. State emission is keyed on thread.start ops only, so a
+// join-only program emits nothing (and its join guards on the same slot).
+// ---------------------------------------------------------------------------
+/** Per-instance symbol stem. */
+function stem(instance) {
+    return `__tc_thrd${instance}`;
+}
+/**
+ * Emit the per-thread state. Called from shimLines for each distinct thread
+ * the program starts.
+ */
+export function threadStateLines(instance, stackBytes) {
+    const p = stem(instance);
+    return [
+        '// CUTTLEFISH_THREAD_BEGIN',
+        `K_THREAD_STACK_DEFINE(${p}_stack, ${stackBytes});`,
+        `static struct k_thread ${p}_thread;`,
+        `static void (*${p}_fn)(void) = NULL;`,
+        `static void ${p}_tramp(void* a, void* b, void* c) { (void)a; (void)b; (void)c; if (${p}_fn) { ${p}_fn(); } }`,
+        '// CUTTLEFISH_THREAD_END',
+    ];
+}
+/**
+ * Resolve a HAL thread.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops.
+ */
+export function lowerThread(op) {
+    const o = op;
+    const instance = typeof o.instance === 'number' ? o.instance : 0;
+    const p = stem(instance);
+    switch (op.operation) {
+        case 'thread.start': {
+            // Store the entry, create + schedule immediately. The stack size comes
+            // from the state block (the construction fact), via K_THREAD_STACK_SIZEOF.
+            return {
+                code: `${p}_fn = (${o.handler}); (void)k_thread_create(&${p}_thread, ${p}_stack, K_THREAD_STACK_SIZEOF(${p}_stack), ${p}_tramp, NULL, NULL, NULL, ${o.priority ?? 5}, 0, K_NO_WAIT);`,
+            };
+        }
+        case 'thread.join':
+            return { code: `(void)k_thread_join(&${p}_thread, K_FOREVER);` };
+        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/timing.js

@@ -1,13 +1,9 @@
 // ---------------------------------------------------------------------------
 // Timing lowering — Zephyr kernel timing
 //
-// delay/millis/delay_microseconds/micros/free_heap lower directly. The four
-// timer ops (set_interval/set_timeout/clear_interval/clear_timeout) call the
-// timer_methods polyfill helpers (k_timer + k_work pool), declared as 'polyfill'
-// status in the manifest — the validator skips the resolver probe for these
-// (they legitimately return polyfill-helper calls, not direct lowering).
-// free_heap has no portable Zephyr query without CONFIG_SYS_HEAP_RUNTIME_STATS;
-// it returns 0 with a comment (honest limitation).
+// sleep/now/now_us/busy_wait_us lower directly to kernel calls. Periodic or
+// deferred work is NOT a timing op: it is a Thread (k_thread) or a Counter
+// (hardware timer), each with its own lowering.
 // ---------------------------------------------------------------------------
 /**
  * Resolve a HAL timing.* op to Zephyr C++.
@@ -16,46 +12,24 @@
 export function lowerTiming(op) {
     const o = op;
     switch (op.operation) {
-        case 'timing.delay': {
-            // Milliseconds — k_msleep is the blocking Zephyr call. Because
-            // isRtosTarget() returns true, the transpiler does not warn about
-            // blocking delays inside loop().
-            const ms = o.ms;
-            return { code: `k_msleep(${ms});` };
-        }
-        case 'timing.delay_microseconds': {
-            // k_busy_wait spins (does not yield); for cooperative μs delays.
+        case 'timing.sleep':
+            // Time.sleep — yielding ms sleep (k_msleep), delay()'s replacement.
+            return { code: `k_msleep(${o.ms});` };
+        case 'timing.now':
+            // Time.now — ms since boot as a double (k_uptime_get is int64_t ms).
+            return { expression: 'static_cast<double>(k_uptime_get())' };
+        case 'timing.now_us':
+            // Time.nowUs — µs since boot, uptime-derived for EVERY board: the
+            // cycle-counter form (k_cyc_to_us_floor64(k_cycle_get_64())) reads a
+            // constant on SoCs without a free-running 64-bit counter, so the one
+            // uniform expression that is monotonic and advancing everywhere is
+            // the kernel uptime scaled to µs. Resolution is therefore the uptime
+            // tick (millisecond), uniformly. A double holds µs exactly for ~285
+            // years.
+            return { expression: 'static_cast<double>(k_uptime_get() * 1000)' };
+        case 'timing.busy_wait_us':
+            // Time.busyWaitUs — spin, no yield; delayMicroseconds's honest name.
             return { code: `k_busy_wait(${o.us});` };
-        }
-        case 'timing.millis':
-            // k_uptime_get_32() returns int64_t milliseconds since boot. Cast to the
-            // Arduino-millis() return type (uint32_t) so overflow wraps identically.
-            return { expression: 'static_cast<uint32_t>(k_uptime_get_32())' };
-        case 'timing.micros': {
-            // Convert hardware cycles to microseconds. k_cycle_get_32 + the cycles/sec
-            // macro (note: sys_clock_hw_cycles_per_sec is a MACRO — needs parens).
-            return {
-                expression: '(uint32_t)(((uint64_t)k_cycle_get_32() * 1000000ULL) / sys_clock_hw_cycles_per_sec())',
-            };
-        }
-        case 'timing.free_heap':
-            // No portable free-heap query without CONFIG_SYS_HEAP_RUNTIME_STATS.
-            // Return 0 with a comment so callers don't get a link error.
-            return { expression: '(0 /* free_heap: enable CONFIG_SYS_HEAP_RUNTIME_STATS for real value */)' };
-        case 'timing.set_interval':
-            // Backed by the timer_methods polyfill (k_timer + k_work). The handler is
-            // the resolved C++ callback name; timeout is the repeat period (ms).
-            // NOTE: these ops are declared 'polyfill' in the manifest, so setInterval
-            // is rewritten to __tc_setInterval before reaching the lowering — these
-            // cases are a fallback/defense and use the real op fields (handler/timeout).
-            return { expression: `__tc_setInterval(${o.handler}, ${o.timeout})` };
-        case 'timing.set_timeout':
-            // One-shot: k_timer with K_FOREVER period.
-            return { expression: `__tc_setTimeout(${o.handler}, ${o.timeout})` };
-        case 'timing.clear_interval':
-            return { code: `__tc_clearInterval(${o.id});` };
-        case 'timing.clear_timeout':
-            return { code: `__tc_clearTimeout(${o.id});` };
         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/tone.js

@@ -11,7 +11,16 @@
 // matching the synchronous Arduino tone() semantics. For non-blocking tone,
 // a workqueue would be needed (deferred).
 // ---------------------------------------------------------------------------
-import { pwmDtAliasToken } from './pwm.js';
+import { findPwmSpec, pwmDtAliasToken } from './pwm.js';
+/**
+ * The PWM spec a tone op drives: the op's own pin when it maps to a spec
+ * (matrix chips — ESP32 LEDC — resolve any driven pad), else the board's
+ * first spec (the aliased LED channel, e.g. pwm-led0 on the XIAO).
+ */
+function toneSpec(chip, pin) {
+    return (typeof pin === 'number' ? findPwmSpec(chip, pin) : undefined)
+        ?? chip.pwm?.specs[0];
+}
 /**
  * Resolve a HAL tone.* op to Zephyr C++ via PWM.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
@@ -23,14 +32,17 @@ export function lowerTone(op, chip) {
             // period_ns = 1e9 / freq; pulse_ns = period / 2 (50% duty).
             // Build a fake pwm.write would need the spec var directly; emit the
             // pwm_set_dt call against the same spec var the PWM lowering uses.
-            const spec = chip.pwm?.specs[0];
+            const spec = toneSpec(chip, o.pin);
             if (!spec) {
                 return { code: `/* tone.play(${o.frequency}): no PWM spec in chip descriptor */` };
             }
             const v = `__tc_pwm_${pwmDtAliasToken(spec)}`;
             const freq = o.frequency;
             const duration = o.duration;
-            const setTone = `uint32_t __period = (${freq} > 0) ? (1000000000ULL / static_cast<uint64_t>(${freq})) : 0; pwm_set_dt(&${v}, __period, __period / 2);`;
+            // Braced: two tone ops in one statement-scope (e.g. tone(440).for(50)
+            // lowers tone.play + tone.play_for back-to-back) would otherwise
+            // redeclare __period.
+            const setTone = `{ uint32_t __period = (${freq} > 0) ? (1000000000ULL / static_cast<uint64_t>(${freq})) : 0; pwm_set_dt(&${v}, __period, __period / 2); }`;
             if (duration !== undefined) {
                 // Blocking tone for the requested duration, then stop.
                 return { code: `${setTone} k_msleep(${duration}); pwm_set_pulse_dt(&${v}, 0);` };
@@ -38,7 +50,7 @@ export function lowerTone(op, chip) {
             return { code: setTone };
         }
         case 'tone.stop': {
-            const spec = chip.pwm?.specs[0];
+            const spec = toneSpec(chip, o.pin);
             if (!spec)
                 return { code: `/* tone.stop: no PWM spec */` };
             const v = `__tc_pwm_${pwmDtAliasToken(spec)}`;

package/dist/lowering/uart.d.ts

@@ -5,6 +5,12 @@ import type { ZephyrChipDescriptor } from '../chips/types.js';
  * when the program uses UART.
  */
 export declare function uartInitLines(chip: ZephyrChipDescriptor, controllerIndex: number): string[];
+/** Render a string/number/boolean value to a per-byte poll_out loop via the
+ *  __tc_dev_put overloads (the const char* overload streams a string; the
+ *  double overload formats a number with __tc_fmt_num_buf). The value passes
+ *  through verbatim — C++ overload resolution picks the right overload for a
+ *  string literal, a number literal, or a runtime variable of either type. */
+export declare function renderWrite(dev: string, value: string, newline: boolean): string;
 /**
  * Resolve a HAL uart.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
@@ -13,3 +19,10 @@ export declare function lowerUart(op: HALOpIR): {
     code?: string;
     expression?: string;
 };
+/** The per-port RX ring state: a construction-sized static buffer, free-running
+ *  head/tail counters (available = head - tail, no wrap ambiguity), and the
+ *  ISR that drains the FIFO. A byte arriving with a full ring is dropped —
+ *  the embedded-honest answer (no unbounded buffering). Emitted only for
+ *  ports whose uart.rx_* ops were emitted (collectUartRings), so an unused
+ *  ISR never trips -Wunused-function. */
+export declare function uartRingStateLines(index: number, ring: number): string[];

package/dist/lowering/uart.js

@@ -2,9 +2,8 @@
 // UART lowering — uart_poll_out / uart_poll_in per-byte
 //
 // Zephyr's UART API is byte-oriented (uart_poll_out / uart_poll_in). The HAL's
-// uart.print/println/write lower to per-byte poll_out loops. For console output
-// the strategy's transformConsoleCall routes to printk; these uart.* ops are
-// for a specific UART port (the XIAO exposes uart0 on D6/D7).
+// uart.print/println/write lower to per-byte poll_out loops; these uart.* ops
+// are for a specific UART port (the XIAO exposes uart0 on D6/D7).
 //
 // The device resolves at compile time via DEVICE_DT_GET(DT_NODELABEL(uart0)).
 // uart.begin configures the baud via uart_configure.
@@ -33,16 +32,14 @@ export function uartInitLines(chip, controllerIndex) {
         '// CUTTLEFISH_UART_END',
     ];
 }
-/** Render a string-literal or expression to a per-byte poll_out loop. */
-function renderWrite(dev, value, newline) {
-    // String literal → emit a char-array loop (known length). Otherwise fall back
-    // to a const char* cast with a strlen-guarded loop.
-    if (/^".*"$/.test(value)) {
-        const body = `for (size_t __i = 0; __i < sizeof(${value}) - 1; __i++) { uart_poll_out(${dev}, (${value})[__i]); }`;
-        return newline ? `${body} uart_poll_out(${dev}, '\\n');` : body;
-    }
-    const body = `for (const char* __s = (const char*)(${value}); *__s; __s++) { uart_poll_out(${dev}, *__s); }`;
-    return newline ? `${body} uart_poll_out(${dev}, '\\n');` : body;
+/** Render a string/number/boolean value to a per-byte poll_out loop via the
+ *  __tc_dev_put overloads (the const char* overload streams a string; the
+ *  double overload formats a number with __tc_fmt_num_buf). The value passes
+ *  through verbatim — C++ overload resolution picks the right overload for a
+ *  string literal, a number literal, or a runtime variable of either type. */
+export function renderWrite(dev, value, newline) {
+    const put = `__tc_dev_put(${dev}, ${value});`;
+    return newline ? `${put} uart_poll_out(${dev}, '\\n');` : put;
 }
 /**
  * Resolve a HAL uart.* op to Zephyr C++.
@@ -54,49 +51,73 @@ export function lowerUart(op) {
     const p = prefix(idx);
     const dev = `${p}_dev`;
     switch (op.operation) {
-        case 'uart.begin':
-            return { code: `${p}_init(static_cast<uint32_t>(${o.baud}));` };
-        case 'uart.end':
-            return { code: `(void)${dev};` };
-        case 'uart.print':
-            return { code: renderWrite(dev, o.value, false) };
-        case 'uart.println':
-            return { code: renderWrite(dev, o.value, true) };
-        case 'uart.write':
-            return { code: renderWrite(dev, o.data, false) };
-        case 'uart.printf': {
-            // snprintf into a buffer, then poll_out each byte.
-            const fmt = o.format;
-            const args = (o.args ?? []).join(', ');
-            const argList = args ? `, ${args}` : '';
+        case 'uart.poll_write': {
+            const pre = uartBaudGuard(p, o.baud);
+            return { code: `${pre} ${renderWrite(dev, o.data, false)}` };
+        }
+        // ── Thin UART RX (hal/uart-port.ts) — interrupt-drained ring ──────────
+        // The first receive call arms the driver IRQ (guarded); the ISR drains
+        // the FIFO into the construction-sized static ring (uartRingStateLines).
+        // available/peek/read are then pure ring arithmetic — the calls the poll
+        // API honestly could not support.
+        case 'uart.rx_arm':
+        case 'uart.rx_available':
+        case 'uart.rx_peek':
+        case 'uart.rx_read': {
+            const r = `__tc_uartrx${idx}`;
+            const arm = `{ static bool ${r}_armed = false; if (!${r}_armed) { uart_irq_callback_user_data_set(${dev}, ${r}_isr, NULL); uart_irq_rx_enable(${dev}); ${r}_armed = true; } }`;
+            if (op.operation === 'uart.rx_arm')
+                return { code: arm };
+            if (op.operation === 'uart.rx_available') {
+                return { expression: `({ ${arm} (${r}_head - ${r}_tail); })` };
+            }
+            if (op.operation === 'uart.rx_peek') {
+                return { expression: `({ ${arm} (${r}_tail < ${r}_head ? ${r}_buf[${r}_tail % ${o.ring}] : -1); })` };
+            }
             return {
-                code: `char __buf[128]; int __n = snprintk(__buf, sizeof(__buf), ${fmt}${argList}); for (int __i = 0; __i < __n; __i++) { uart_poll_out(${dev}, __buf[__i]); }`,
+                expression: `({ ${arm} (${r}_tail < ${r}_head ? ${r}_buf[(${r}_tail)++ % ${o.ring}] : -1); })`,
             };
         }
-        case 'uart.read':
-            // Non-blocking poll; returns the byte or -1 if none available.
-            return { expression: `({ unsigned char __b = 0; (uart_poll_in(${dev}, &__b) == 0) ? (int)__b : -1; })` };
-        case 'uart.peek':
-            // The poll API has no buffered-byte store, so there is no true peek.
-            // Return -1 (the Arduino "no data" sentinel) rather than blocking. This
-            // is an honest limitation of the byte-level poll driver; an interrupt- or
-            // DMA-backed UART driver would be needed for real peek semantics.
-            return { expression: '(-1)' };
-        case 'uart.available':
-            // The poll API reports only "at least one byte ready" via uart_poll_in's
-            // return code — it has no buffered-byte count, and probing with poll_in
-            // would DRAIN the very byte the caller next wants to read. So we cannot
-            // honestly report availability. Return 0 (Arduino's "no data" value)
-            // rather than the old truthy -1, so `if (uart.available())` loops don't
-            // spin forever on a false-positive. Callers should instead just call
-            // uart.read() directly (it returns -1 when no byte is ready). For true
-            // buffered availability, use an interrupt/DMA-backed UART driver.
-            return { expression: '(0)' };
-        case 'uart.flush':
-            // poll_out is synchronous (blocking until sent); flush is a no-op.
-            return { code: `(void)${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.`);
     }
 }
+/** The thin-port baud preamble: apply the construction baud once via the
+ *  shim's `_init` helper (uart_configure). Guarded per controller. */
+function uartBaudGuard(p, baud) {
+    const n = typeof baud === 'number' ? baud : parseInt(String(baud ?? 0), 10);
+    if (!n || isNaN(n))
+        return '';
+    const done = `${p}_baud_done`;
+    return `{ static bool ${done} = false; if (!${done}) { ${p}_init(static_cast<uint32_t>(${n})); ${done} = true; } } `;
+}
+/** The per-port RX ring state: a construction-sized static buffer, free-running
+ *  head/tail counters (available = head - tail, no wrap ambiguity), and the
+ *  ISR that drains the FIFO. A byte arriving with a full ring is dropped —
+ *  the embedded-honest answer (no unbounded buffering). Emitted only for
+ *  ports whose uart.rx_* ops were emitted (collectUartRings), so an unused
+ *  ISR never trips -Wunused-function. */
+export function uartRingStateLines(index, ring) {
+    const r = `__tc_uartrx${index}`;
+    const dev = `__tc_uart${index}_dev`;
+    return [
+        '// CUTTLEFISH_UARTRX_BEGIN',
+        `static uint8_t ${r}_buf[${ring}];`,
+        `static volatile uint32_t ${r}_head = 0;`,
+        `static volatile uint32_t ${r}_tail = 0;`,
+        `static void ${r}_isr(const struct device* dev, void* user_data) {`,
+        `    (void)user_data;`,
+        `    uart_irq_update(dev);`,
+        `    while (uart_irq_rx_ready(dev)) {`,
+        `        uint8_t __c = 0;`,
+        `        (void)uart_fifo_read(dev, &__c, 1);`,
+        `        if ((${r}_head - ${r}_tail) < ${ring}) {`,
+        `            ${r}_buf[${r}_head % ${ring}] = __c;`,
+        `            ${r}_head++;`,
+        `        }`,
+        `    }`,
+        `}`,
+        '// CUTTLEFISH_UARTRX_END',
+    ];
+}

package/dist/lowering/usb.d.ts

@@ -0,0 +1,34 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Emit the shared USB device context (USBD_DEVICE_DEFINE + string/config
+ * descriptors + configuration + class registration + usbd_enable). Emitted
+ * ONCE per program when the chip declares `usb` — the next stack has one
+ * device context on the UDC controller, regardless of how many CDC instances
+ * hang off it.
+ *
+ * VID/PID default to the Zephyr-project testing IDs (0x2fe3/0x0001); a board
+ * overrides via `zephyr.usb.vid`/`zephyr.usb.pid`. Full-speed only — the
+ * boards this framework targets (STM32 OTG_FS, nRF USBD) are FS controllers,
+ * and the HS path would need a second USBD_CONFIGURATION_DEFINE.
+ *
+ * Symbol/API shapes verified against Zephyr 4.3:
+ * subsys/usb/device_next/Kconfig, include/zephyr/usb/usbd.h, and
+ * samples/subsys/usb/common/sample_usbd_init.c.
+ */
+export declare function usbdDeviceLines(chip: ZephyrChipDescriptor): string[];
+/**
+ * Emit the per-instance CDC device + init helper. Called from shimLines when
+ * the program uses USB and the chip declares `usb`; must be paired with one
+ * usbdDeviceLines() block. The init starts the device stack (guarded) and
+ * applies the line coding.
+ */
+export declare function usbInitLines(chip: ZephyrChipDescriptor, instanceIndex: number): string[];
+/**
+ * Resolve a HAL usb.* op to Zephyr C++.
+ * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
+ */
+export declare function lowerUsb(op: HALOpIR, chip: ZephyrChipDescriptor): {
+    code?: string;
+    expression?: string;
+};