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

package/dist/lowering/pwm.js

@@ -6,22 +6,81 @@
 // `pwm_set_pulse_dt` / `pwm_set_dt`. Duty is scaled from the Arduino-style
 // 0–255 (or 0–1023) range to nanoseconds against the spec's period.
 // ---------------------------------------------------------------------------
-/** Look up a PWM spec by HAL pin number. */
-function findPwmSpec(chip, pin) {
-    return chip.pwm?.specs.find((s) => s.pin === pin);
+/**
+ * The DT alias a PWM spec is addressed by. Board-shipped specs carry their
+ * alias in `dtSpec`; synthesized specs (controller + channel) get a
+ * `tc-pwm<pin>` alias that the overlay generator creates in
+ * <board>.overlay — both sides derive the name from the pin so they agree.
+ */
+export function pwmDtAlias(spec) {
+    return spec.dtSpec ?? `tc-pwm${spec.pin}`;
+}
+/**
+ * The C macro token for a spec's alias. Zephyr's devicetree macros replace
+ * dashes in alias names with underscores (`pwm-led0` in DTS is
+ * DT_ALIAS(pwm_led0) in C) — the dashed spelling is a subtraction
+ * expression and fails to compile (caught by the blackpill E2E west build).
+ */
+export function pwmDtAliasToken(spec) {
+    return pwmDtAlias(spec).replace(/-/g, '_');
+}
+/**
+ * Look up a PWM spec by HAL pin number. Matrix pins (ESP32 LEDC) synthesize
+ * a spec on the fly: the channel is inert here — the emitted C++ addresses
+ * the pin only via its `tc-pwm<pin>` alias (the DT pwms cell carries the
+ * real channel, assigned by the overlay generator over the driven pins).
+ */
+export function findPwmSpec(chip, pin) {
+    const spec = chip.pwm?.specs.find((s) => s.pin === pin);
+    if (spec)
+        return spec;
+    const m = chip.pwm?.matrix;
+    if (m && m.pins.includes(pin))
+        return { pin, controller: m.controller, channel: 0 };
+    return undefined;
 }
 /** The C variable name emitted for a PWM channel's spec. */
 function pwmVarName(spec) {
-    return `__tc_pwm_${spec.dtSpec.replace(/-/g, '_')}`;
+    return `__tc_pwm_${pwmDtAliasToken(spec)}`;
 }
 /**
  * Emit the per-channel PWM spec declarations. One per spec in the chip
- * descriptor. Called from shimLines when the program uses PWM.
+ * descriptor that the PROGRAM ACTUALLY DRIVES (`usedPins`) — a spec for an
+ * untouched pin is unused code in the emitted TU (and would need a dead DT
+ * alias in the overlay). When `usedPins` is omitted (probe paths with no
+ * program), every spec is emitted. Called from shimLines when the program
+ * uses PWM.
  */
-export function pwmInitLines(chip) {
+export function pwmInitLines(chip, usedPins, userSpecs) {
     const lines = ['// CUTTLEFISH_PWM_BEGIN'];
     for (const spec of chip.pwm?.specs ?? []) {
-        lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${spec.dtSpec}));`);
+        if (usedPins && !usedPins.has(spec.pin))
+            continue;
+        lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`);
+    }
+    // Inline-override pins (the escape hatch): the construction opts vouch for
+    // controller+channel on a pin the manifest does not map — the alias var
+    // the lowered calls reference (the DT node itself comes from the overlay
+    // regen's marker merge).
+    for (const spec of userSpecs ?? []) {
+        if (chip.pwm?.specs.some((s) => s.pin === spec.pin))
+            continue;
+        if (usedPins && !usedPins.has(spec.pin))
+            continue;
+        lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`);
+    }
+    // Matrix pins (ESP32 LEDC): one alias per driven pin, ascending — the same
+    // order the overlay generator assigns channels in, though the C++ never
+    // needs the channel (the DT pwms cell carries it). An omitted usage set
+    // (probe paths) emits every matrix pin, mirroring the static behavior.
+    const m = chip.pwm?.matrix;
+    if (m) {
+        const pins = (usedPins ? [...usedPins].filter((p) => m.pins.includes(p)) : [...m.pins])
+            .sort((a, b) => a - b);
+        for (const pin of pins) {
+            const spec = { pin, controller: m.controller, channel: 0 };
+            lines.push(`static const struct pwm_dt_spec ${pwmVarName(spec)} = PWM_DT_SPEC_GET(DT_ALIAS(${pwmDtAliasToken(spec)}));`);
+        }
     }
     lines.push('// CUTTLEFISH_PWM_END');
     return lines;
@@ -32,7 +91,20 @@ export function pwmInitLines(chip) {
  */
 export function lowerPwm(op, chip) {
     const o = op;
-    const spec = findPwmSpec(chip, o.pin);
+    // Construction-time controller/channel overrides (hal/pwm-pin.ts opts):
+    // the user vouches for the routing. The spec synthesizes from the
+    // override (addressing rides the tc-pwm<pin> alias like a matrix pin) and
+    // a marker comment carries controller+channel to the overlay regen, which
+    // synthesizes the DT node — the transpiler cannot.
+    const hasOverride = (typeof o.controllerOverride === 'string' && o.controllerOverride !== '')
+        || (typeof o.channelOverride === 'number' && o.channelOverride >= 0);
+    const spec = hasOverride
+        ? {
+            pin: o.pin,
+            controller: o.controllerOverride ?? 'pwm0',
+            channel: o.channelOverride ?? 0,
+        }
+        : findPwmSpec(chip, o.pin);
     if (!spec) {
         // Probe / unlisted pin: return a comment so the resolver reports non-
         // undefined (the manifest validator's probe sends pin:0 with no spec).
@@ -40,18 +112,34 @@ export function lowerPwm(op, chip) {
         return { code: `/* pwm on pin ${o.pin}: no PWM spec in chip descriptor */` };
     }
     const v = pwmVarName(spec);
+    // The overlay regen (toolchain) parses this into a synthesized pwm-leds
+    // spec: pin → controller/channel. Comment placement inside the block
+    // braces is legal C.
+    const marker = hasOverride
+        ? `/* cuttlefish-user-facts: pwm pin=${spec.pin} controller=${spec.controller} channel=${spec.channel} */ `
+        : '';
     switch (op.operation) {
-        case 'pwm.write': {
-            // Duty is 0–255 (Arduino analogWrite). Scale to ns against the period.
-            return { code: `pwm_set_pulse_dt(&${v}, (static_cast<uint32_t>(${o.duty}) * ${v}.period) / 255);` };
+        // ── Thin PWM (hal/pwm-pin.ts) — ns-true verbs ──────────────────────────
+        // Zephyr 4.4 has pwm_set_dt (period + pulse) and pwm_set_pulse_dt (pulse
+        // only) — no period-only setter. The construction period is established
+        // once via pwm_set_dt(period, pulse 0 = line idle), then every set is one
+        // pwm_set_pulse_dt. No 0–255 scaling anywhere.
+        case 'pwm.set_pulse': {
+            return {
+                code: `{ ${marker}static bool __tc_pwm_p${o.pin}_prd = false; if (!__tc_pwm_p${o.pin}_prd) { (void)pwm_set_dt(&${v}, ${o.periodNs}, 0); __tc_pwm_p${o.pin}_prd = true; } (void)pwm_set_pulse_dt(&${v}, ${o.pulseNs}); }`,
+            };
+        }
+        case 'pwm.set_duty': {
+            // duty is 0.0–1.0; pulse = duty × the construction period.
+            return {
+                code: `{ ${marker}static bool __tc_pwm_p${o.pin}_prd = false; if (!__tc_pwm_p${o.pin}_prd) { (void)pwm_set_dt(&${v}, ${o.periodNs}, 0); __tc_pwm_p${o.pin}_prd = true; } (void)pwm_set_pulse_dt(&${v}, static_cast<uint32_t>(static_cast<double>(${o.duty}) * static_cast<double>(${o.periodNs}))); }`,
+            };
         }
-        case 'pwm.get_frequency': {
-            // period is in ns; frequency = 1e9 / period (Hz).
-            return { expression: `(${v}.period ? (1000000000ULL / ${v}.period) : 0)` };
+        case 'pwm.set_period': {
+            // No period-only API: pwm_set_dt applies the new period and resets the
+            // pulse to idle — follow with setPulse/setDuty to drive the line.
+            return { code: `${marker}(void)pwm_set_dt(&${v}, ${o.periodNs}, 0);` };
         }
-        case 'pwm.get_resolution':
-            // Arduino-compatible 8-bit duty range.
-            return { expression: '8' };
         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/random.js

@@ -5,7 +5,7 @@
 // the configured entropy source (the nRF52840 hardware RNG when
 // CONFIG_HARDWARE_DEVICE_RANDOM_GENERATOR is selected, or the default test/
 // xoroshiro generator otherwise). It is seeded automatically at boot from the
-// entropy driver, so unlike Arduino there is no implicit seeding step.
+// entropy driver, so there is no implicit seeding step.
 //
 // The HAL random surface is the Arduino-core model:
 //   random.int()    → a non-negative 31-bit integer [0, 2^31 - 1]
@@ -70,7 +70,7 @@ export function randomInitLines() {
         `}`,
         ``,
         `// Re-seed the PRNG. After this call the sequence is deterministic from`,
-        `// \`seed\`, matching Arduino randomSeed. A literal zero seed is accepted and`,
+        `// \`seed\`, matching the platform's randomSeed. A literal zero seed is accepted and`,
         `// remapped to the same odd constant (xorshift32 cannot start from 0).`,
         `static inline void __tc_rand_seed(uint32_t seed) {`,
         `    __tc_rand_state = (seed == 0U) ? 0x9E3779B9U : seed;`,
@@ -84,7 +84,7 @@ export function randomInitLines() {
         `}`,
         ``,
         `// Half-open range [min, max-1]. Implements the HAL contract directly rather`,
-        `// than calling Arduino random(min, max): the modulus rejection-free form`,
+        `// than calling the platform random(min, max): the modulus rejection-free form`,
         `// avoids the modulo bias a naive (rand % (max-min)) introduces. max > min`,
         `// is assumed (the HAL validates this at the source level).`,
         `static inline int32_t __tc_rand_range(int32_t min, int32_t max) {`,

package/dist/lowering/sensor.d.ts

@@ -0,0 +1,37 @@
+import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
+/** Strip the 'SENSOR.' property-access prefix from a part token arg. */
+export declare function sensorPartKey(part: string): string;
+/** Strip the 'CHAN.' property-access prefix from a channel arg. */
+export declare function sensorChanName(chan: string): string;
+/** All names a constructed sensor is known by, derived from the op facts. */
+export interface SensorNames {
+    /** DT nodelabel of the child node the overlay emits
+     *  (tc_<part>_i2c<N>_0x<addr> / tc_<part>_spi<N>_cs<pin>). */
+    dtLabel: string;
+    /** C device-handle variable (__tc_sensor_<stem>_dev). */
+    devVar: string;
+    /** C sensor_value scratch variable (__tc_sensor_<stem>_val). */
+    valVar: string;
+    /** The controller index the bus string carries. */
+    busIndex: number;
+    /** The bus port: I2C address or SPI CS pin. */
+    port: number;
+    /** 'i2c' | 'spi'. */
+    busKind: 'i2c' | 'spi';
+}
+/** Derive a sensor's DT/C++ names. The scanner regexes the emitted __tc_
+ *  prefix form, so the part group must stay [a-z0-9_]+ and greedy. */
+export declare function sensorNames(part: string, bus: string, port: number | string, busKind?: string): SensorNames;
+/**
+ * Emit the per-sensor state block (device handle + sensor_value scratch).
+ * Called from shimLines for each distinct sensor the program's ops reference.
+ */
+export declare function sensorStateLines(part: string, bus: string, port: number | string, busKind?: string, spiHz?: number | string, spiMode?: number | string, alertPin?: number | string): string[];
+/**
+ * Resolve a HAL sensor.* op to Zephyr C++.
+ * Returns `{ code }` for fetch (statement), `{ expression }` for get (value).
+ */
+export declare function lowerSensor(op: HALOpIR): {
+    code?: string;
+    expression?: string;
+};

package/dist/lowering/sensor.js

@@ -0,0 +1,119 @@
+// ---------------------------------------------------------------------------
+// Sensor lowering — Zephyr's uniform sensor API over the generated catalog
+//
+// One code shape for every part in @typecad/hal's sensor catalog: the op's
+// part token resolves to the DT compatible, the bus string to the controller
+// index, and the address to the I2C reg. The names are derived identically
+// here (device handles), in strategy.ts state blocks, and in the overlay
+// scanner (dt-config/overlay.ts + toolchain/index.ts) — the tc-pwm<pin>
+// discipline: both sides derive from the same facts, so they cannot drift.
+//
+// Kconfig: nothing per-part. The in-tree driver Kconfigs are `default y` on
+// DT_HAS_<COMPAT>_ENABLED, so the overlay's child node IS the enable switch;
+// CONFIG_SENSOR (the umbrella under `if SENSOR`) is usage-gated in
+// dt-config/kconfig.ts off the lowered `sensor_` tokens.
+// ---------------------------------------------------------------------------
+import { SENSOR_PART_INFO } from '@typecad/hal';
+import { parseControllerIndex } from './util.js';
+/** Strip the 'SENSOR.' property-access prefix from a part token arg. */
+export function sensorPartKey(part) {
+    return part.replace(/^SENSOR\./, '');
+}
+/** Strip the 'CHAN.' property-access prefix from a channel arg. */
+export function sensorChanName(chan) {
+    return chan.replace(/^CHAN\./, '');
+}
+/** Derive a sensor's DT/C++ names. The scanner regexes the emitted __tc_
+ *  prefix form, so the part group must stay [a-z0-9_]+ and greedy. */
+export function sensorNames(part, bus, port, busKind = 'i2c') {
+    const partKey = sensorPartKey(String(part));
+    const busIndex = parseControllerIndex(typeof bus === 'string' ? bus : String(bus));
+    const portNum = typeof port === 'number' ? port : parseInt(String(port));
+    const stem = busKind === 'spi'
+        ? `${partKey}_spi${busIndex}_cs${portNum}`
+        : `${partKey}_i2c${busIndex}_0x${portNum.toString(16)}`;
+    return {
+        dtLabel: `tc_${stem}`,
+        devVar: `__tc_sensor_${stem}_dev`,
+        valVar: `__tc_sensor_${stem}_val`,
+        busIndex,
+        port: portNum,
+        busKind: busKind === 'spi' ? 'spi' : 'i2c',
+    };
+}
+/**
+ * Resolve the part token against the generated catalog, validating the bus
+ * kind and (when the driver scan knows them) the channel. Throws a build-time
+ * error with the Zephyr-facing name — the same words the user would meet in
+ * Zephyr docs, checked before west ever runs.
+ */
+/** @internal */
+function requirePartInfo(partKey) {
+    const info = SENSOR_PART_INFO[partKey];
+    if (!info) {
+        throw new Error(`Sensor part '${partKey}' is not in the Zephyr sensor catalog (SENSOR in @typecad/hal). ` +
+            `Check the token against the catalog — it is the compatible with , and - replaced by _.`);
+    }
+    return info;
+}
+/** Validate the op's bus kind against the part's bindings. */
+function requireBusKind(partKey, info, busKind) {
+    if (!info.buses.includes(busKind)) {
+        throw new Error(`Sensor part '${partKey}' (${info.compatible}) does not bind on ${busKind.toUpperCase()} — ` +
+            `its bindings are ${info.buses.join('/').toUpperCase()}.`);
+    }
+}
+/**
+ * Emit the per-sensor state block (device handle + sensor_value scratch).
+ * Called from shimLines for each distinct sensor the program's ops reference.
+ */
+export function sensorStateLines(part, bus, port, busKind = 'i2c', spiHz = 0, spiMode = 0, alertPin = -1) {
+    const partKey = sensorPartKey(String(part));
+    requireBusKind(partKey, requirePartInfo(partKey), busKind);
+    const n = sensorNames(part, bus, port, busKind);
+    // The config comment carries construction facts (SPI clock, mode, alert
+    // GPIO) to the overlay scanner — they shape the DT node, not the C++.
+    const cfg = `// tc-sensor-cfg: ${n.dtLabel} hz=${Number(spiHz)} mode=${Number(spiMode)} alert=${Number(alertPin)}`;
+    return [
+        '// CUTTLEFISH_SENSOR_BEGIN',
+        `static const struct device* ${n.devVar} = DEVICE_DT_GET(DT_NODELABEL(${n.dtLabel}));`,
+        `static struct sensor_value ${n.valVar};`,
+        cfg,
+        '// CUTTLEFISH_SENSOR_END',
+    ];
+}
+/**
+ * Resolve a HAL sensor.* op to Zephyr C++.
+ * Returns `{ code }` for fetch (statement), `{ expression }` for get (value).
+ */
+export function lowerSensor(op) {
+    const o = op;
+    const partKey = sensorPartKey(String(o.part));
+    const info = requirePartInfo(partKey);
+    requireBusKind(partKey, info, String(o.busKind ?? 'i2c'));
+    const n = sensorNames(o.part, o.bus, o.port ?? o.address, String(o.busKind ?? 'i2c'));
+    switch (op.operation) {
+        case 'sensor.fetch':
+            // sensor_sample_fetch. The leading (void) keeps the value scratch
+            // referenced under Zephyr's -Werror when the program fetches but never
+            // reads a channel (the state block is emitted per referenced sensor).
+            return {
+                code: `(void)${n.valVar}; sensor_sample_fetch(${n.devVar});`,
+            };
+        case 'sensor.get': {
+            const chan = sensorChanName(String(o.chan));
+            if (info.channels.length > 0 && !info.channels.includes(chan)) {
+                throw new Error(`Sensor part '${partKey}' (${info.compatible}) does not serve channel '${chan}' — ` +
+                    `its driver serves: ${info.channels.join(', ')}.`);
+            }
+            // sensor_value is val1 + val2 * 1e-6; evaluate once per read.
+            return {
+                expression: `(sensor_channel_get(${n.devVar}, SENSOR_CHAN_${chan}, &${n.valVar}), ` +
+                    `static_cast<double>(${n.valVar}.val1) + static_cast<double>(${n.valVar}.val2) / 1000000.0)`,
+            };
+        }
+        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/spi.d.ts

@@ -1,5 +1,17 @@
 import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
 import type { ZephyrChipDescriptor } from '../chips/types.js';
+export interface SpiTargetNames {
+    dtLabel: string;
+    varName: string;
+    busIndex: number;
+    cs: number;
+}
+/** Derive a thin SPI target's names from the op facts. */
+export declare function spiTargetNames(bus: string, cs: number | string): SpiTargetNames;
+/** 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 declare function spiTargetStateLines(bus: string, cs: number | string, hz?: number | string, mode?: number | string): string[];
 /**
  * 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

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 } 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})), ${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.`);
+    }
+}