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

package/dist/lowering/interrupts.js

@@ -5,11 +5,13 @@
 // `struct gpio_callback` per pin, registered with gpio_add_callback, with a
 // trampoline that calls the user's C handler. The descriptor's gpio.interruptPins
 // lists the pins with DT specs (buttons). The user's handler is a free C
-// function; the trampoline calls it with no args (Arduino attachInterrupt style).
+// function; the trampoline calls it with no args.
 //
 // Each interrupt pin gets a static callback struct + a trampoline in shimLines.
 // attach enables + adds the callback; detach disables + removes it.
 // ---------------------------------------------------------------------------
+import { controllerNodelabelForPin, controllerRawPinForPin, controllerRangeForPin } from '../chips/controllers.js';
+import { ZEPHYR_GPIO_INTS } from '@typecad/hal';
 /** Look up an interrupt pin spec by HAL pin number. */
 function findIntPin(chip, pin) {
     return chip.gpio.interruptPins?.find((p) => p.pin === pin);
@@ -18,62 +20,142 @@ function findIntPin(chip, pin) {
 function dtSpecVar(dtSpec) {
     return `__tc_int_${dtSpec.replace(/-/g, '_')}`;
 }
-/** Map a HAL interrupt mode string to Zephyr GPIO_INT_* flags. */
-function modeToFlags(mode) {
-    switch (mode.toLowerCase()) {
-        case 'rising': return 'GPIO_INT_EDGE_RISING';
-        case 'falling': return 'GPIO_INT_EDGE_FALLING';
-        case 'change': return 'GPIO_INT_EDGE_BOTH';
-        case 'high': return 'GPIO_INT_LEVEL_HIGH';
-        case 'low': return 'GPIO_INT_LEVEL_LOW';
-        default: return 'GPIO_INT_EDGE_BOTH';
+// ── Thin GPIO interrupts (hal/gpio-pin.ts onInterrupt) — INT_* tokens ─────
+//
+// The name set comes from the GENERATED Zephyr token table (parsed from the
+// pinned tree's drivers/gpio.h).
+const GPIO_INT_TOKENS = Object.fromEntries(ZEPHYR_GPIO_INTS.map((f) => [`GPIO.${f}`, `GPIO_${f}`]));
+/** Map thin-GPIO INT token text to the GPIO_INT_* macro. */
+export function gpioIntTokenToMacro(intFlags) {
+    const token = String(intFlags ?? '').trim();
+    const m = GPIO_INT_TOKENS[token];
+    if (!m) {
+        throw new Error(`GPIO interrupt flag '${token}' is not a known GPIO.INT_* token — valid: ${Object.keys(GPIO_INT_TOKENS).join(', ')}.`);
     }
+    return m;
 }
 /**
  * Emit the per-pin interrupt callback state + trampolines. Called from shimLines
  * when the program uses interrupts. The trampoline calls a user function via a
  * function-pointer static, set at attach time.
+ *
+ * Two paths:
+ *  - descriptor `gpio.interruptPins` (buttons with DT specs): callback state
+ *    against the DT spec, polarity-correct via gpio_*_dt.
+ *  - `usedPins` (any other pin the program attaches to): raw-controller state —
+ *    GPIO.onInterrupt() works on EVERY GPIO, not just DT-aliased buttons. Each
+ *    such pin gets its own callback struct + trampoline addressed by the owning
+ *    controller (STM32 splits gpioa/gpiob/gpioc) and port-relative bit.
  */
-export function interruptInitLines(chip) {
+export function interruptInitLines(chip, usedPins) {
     const pins = chip.gpio.interruptPins ?? [];
-    if (pins.length === 0)
-        return [];
     const lines = ['// CUTTLEFISH_INT_BEGIN'];
     for (const pin of pins) {
         const v = dtSpecVar(pin.dtSpec);
         lines.push(`static const struct gpio_dt_spec ${v} = GPIO_DT_SPEC_GET(DT_ALIAS(${pin.dtSpec}), gpios);`, `static struct gpio_callback ${v}_cb;`, `static void (*${v}_handler)(void) = NULL;`, `static void ${v}_tramp(const struct device* port, struct gpio_callback* cb, gpio_port_pins_t pins_v) {`, `    (void)port; (void)cb; (void)pins_v;`, `    if (${v}_handler) { ${v}_handler(); }`, `}`);
     }
+    if (usedPins) {
+        for (const pin of usedPins) {
+            if (pins.some((p) => p.pin === pin))
+                continue;
+            const v = `__tc_int_raw${pin}`;
+            lines.push(`static const struct device* ${v}_dev = DEVICE_DT_GET(DT_NODELABEL(${controllerNodelabelForPin(chip, pin)}));`, `static struct gpio_callback ${v}_cb;`, `static void (*${v}_handler)(void) = NULL;`, `static void ${v}_tramp(const struct device* port, struct gpio_callback* cb, gpio_port_pins_t pins_v) {`, `    (void)port; (void)cb; (void)pins_v;`, `    if (${v}_handler) { ${v}_handler(); }`, `}`);
+        }
+    }
     lines.push('// CUTTLEFISH_INT_END');
     return lines;
 }
+/**
+ * Collect the pin numbers the program attaches interrupts to (any GPIO — not
+ * just descriptor-listed buttons). Feeds interruptInitLines' raw-path state.
+ */
+export function collectInterruptPins(program) {
+    const pins = new Set();
+    const visit = (node) => {
+        if (!node || typeof node !== 'object')
+            return;
+        const n = node;
+        const op = n.operation;
+        if (op && typeof op === 'object') {
+            const o = op;
+            if (o.operation === 'interrupt.attach_flags' && typeof o.pin === 'number') {
+                pins.add(o.pin);
+            }
+        }
+        for (const v of Object.values(n)) {
+            if (Array.isArray(v)) {
+                for (const item of v)
+                    visit(item);
+            }
+            else if (v && typeof v === 'object')
+                visit(v);
+        }
+    };
+    visit(program);
+    return pins;
+}
 /**
  * Resolve a HAL interrupt.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.
  *
- * Note: attach requires the pin to be in the descriptor's interruptPins. If a
- * program attaches to an unlisted pin, we fall back to a diagnostic comment
- * (the probe uses an unknown pin, so the manifest marks these 'supported' via
- * the comment lowering — the probe sees a non-undefined return).
+ * Two paths: pins listed in the descriptor's gpio.interruptPins (DT-aliased
+ * buttons) go through the polarity-correct gpio_*_dt chain; every other GPIO
+ * attaches through the raw-controller chain (any GPIO is interrupt-capable on
+ * the supported SoCs — the descriptor list exists for DT specs, not as a
+ * capability gate). The manifest probe's synthetic op keeps the comment
+ * fallback (no program ⇒ no shim state was emitted for the raw path).
  */
 export function lowerInterrupt(op, chip) {
     const o = op;
     const pin = findIntPin(chip, o.pin);
     if (!pin) {
+        // Raw-controller path — state comes from interruptInitLines' usedPins.
+        // Only for pins a declared controller range covers: an out-of-range number
+        // (e.g. pin 99 on a 34-pin SoC) keeps the diagnostic comment. Single-
+        // controller chips declare no ranges, so every number is taken as real and
+        // the driver rejects invalid bits at runtime (Arduino-like behavior).
+        const knownPin = typeof o.pin === 'number' && Number.isInteger(o.pin)
+            && (!chip.gpioControllers || chip.gpioControllers.length === 0
+                || controllerRangeForPin(chip, o.pin) !== undefined);
+        if (knownPin) {
+            const v = `__tc_int_raw${o.pin}`;
+            const raw = controllerRawPinForPin(chip, o.pin);
+            if (op.operation === 'interrupt.attach_flags') {
+                // Thin GPIO: INT_* tokens instead of mode strings. The pin's
+                // input/pull configuration already came from the construction flags
+                // (the class emits gpio.configure ahead of this op) — no INPUT
+                // override here, unlike the legacy raw path above.
+                const flags = gpioIntTokenToMacro(o.intFlags);
+                return {
+                    code: [
+                        `${v}_handler = (${o.handler});`,
+                        `gpio_init_callback(&${v}_cb, ${v}_tramp, BIT(${raw}));`,
+                        `gpio_pin_interrupt_configure(${v}_dev, ${raw}, ${flags});`,
+                        `gpio_add_callback(${v}_dev, &${v}_cb);`,
+                    ].join(' '),
+                };
+            }
+            if (op.operation === 'interrupt.detach') {
+                return {
+                    code: `gpio_pin_interrupt_configure(${v}_dev, ${raw}, GPIO_INT_DISABLE); gpio_remove_callback(${v}_dev, &${v}_cb); ${v}_handler = NULL;`,
+                };
+            }
+        }
         // Fallback (also covers the manifest probe): a diagnostic comment so the
         // resolver returns non-undefined. Real attach needs a descriptor entry.
-        if (op.operation === 'interrupt.attach') {
-            return { code: `/* interrupt.attach(pin ${o.pin}): no DT spec — add to chip descriptor gpio.interruptPins */` };
+        if (op.operation === 'interrupt.attach_flags') {
+            return { code: `/* interrupt.attach_flags(pin ${o.pin}): no DT spec — add to chip descriptor gpio.interruptPins */` };
         }
         return { code: `/* interrupt.detach(pin ${o.pin}): no DT spec */` };
     }
     const v = dtSpecVar(pin.dtSpec);
     switch (op.operation) {
-        case 'interrupt.attach': {
-            const flags = modeToFlags(o.mode);
+        case 'interrupt.attach_flags': {
+            // Thin GPIO: INT_* tokens; construction flags already configured the pin.
+            const flags = gpioIntTokenToMacro(o.intFlags);
             return {
                 code: [
                     `${v}_handler = (${o.handler});`,
-                    `gpio_pin_configure_dt(&${v}, GPIO_INPUT);`,
                     `gpio_init_callback(&${v}_cb, ${v}_tramp, BIT(${v}.pin));`,
                     `gpio_pin_interrupt_configure_dt(&${v}, ${flags});`,
                     `gpio_add_callback(${v}.port, &${v}_cb);`,

package/dist/lowering/mqtt.js

@@ -3,11 +3,11 @@
 //
 // Zephyr's MQTT library is event-driven but has no internal task: the app
 // must call mqtt_input() when the socket is readable and mqtt_live()
-// periodically for keepalive. The generated firmware is setup()/loop(),
-// and the user's loop() is not ours to edit — so the connect shim spawns a
+// periodically for keepalive. The generated firmware is main()-based and
+// the user's main() is not ours to edit — so the connect shim spawns a
 // dedicated k_thread that runs the poll loop (poll() → mqtt_input/mqtt_live)
 // until disconnect. This mirrors a "managed client" model (like ESP-IDF's
-// esp_mqtt internal task) and keeps the user's loop() untouched.
+// esp_mqtt internal task) and keeps the user's main() untouched.
 //
 // mqtt_connect() does no DNS — the broker is a resolved sockaddr — so the
 // shim getaddrinfo-resolves the broker host itself (like the HTTP shim).
@@ -266,8 +266,6 @@ export function mqttInitLines() {
         `        (void)mqtt_abort(&__tc_mqtt.client);`,
         `        return;`,
         `    }`,
-        `    printk("tc-mqtt: connecting to %s:%u\\n", __tc_mqtt.host,`,
-        `           static_cast<unsigned int>(__tc_mqtt.port));`,
         `    // Drive input locally until CONNACK arrives (poll thread hasn't started).`,
         `    // mqtt_connect opened the socket; poll it for the connect-ack. Cap the wait`,
         `    // so a silent broker doesn't hang setup forever.`,
@@ -290,7 +288,15 @@ export function mqttInitLines() {
         `    (void)k_thread_create(&__tc_mqtt.poll_thread, __tc_mqtt_stack,`,
         `                          K_THREAD_STACK_SIZEOF(__tc_mqtt_stack),`,
         `                          __tc_mqtt_poll_thread, nullptr, nullptr, nullptr,`,
-        `                          5, 0, K_NO_WAIT);`,
+        `                          5, 0, K_FOREVER);`,
+        `#ifdef CONFIG_SMP`,
+        `    // On SMP targets park the poll thread on the app core so the network`,
+        `    // stack never competes with the main/UI thread for core 0. k_thread_cpu_pin`,
+        `    // is SMP-only; the pin happens before k_thread_start (which is why the`,
+        `    // thread is created K_FOREVER). Compiles away on !SMP builds.`,
+        `    (void)k_thread_cpu_pin(&__tc_mqtt.poll_thread, 1);`,
+        `#endif`,
+        `    k_thread_start(&__tc_mqtt.poll_thread);`,
         `}`,
         ``,
         `static inline void __tc_mqtt_set_on_message(__tc_mqtt_msg_cb_t fn) {`,

package/dist/lowering/power.js

@@ -28,10 +28,6 @@ export function lowerPower(op) {
             // Best-effort: force a shallow suspend on the next idle. pm_state_force
             // requires a pm_state_info; SUSPEND_TO_IDLE is a common shallow state.
             return { code: `pm_state_force(0, &(const struct pm_state_info){ .state = PM_STATE_SUSPEND_TO_IDLE, .substate_id = 0 });` };
-        case 'power.set_cpu_frequency':
-            // nRF52 has a fixed 64 MHz HFXO; no portable dynamic scaling from C++.
-            // Documented no-op (best-effort), matching Arduino's approach.
-            return { code: `/* power.set_cpu_frequency(${o.mhz}): nRF52 fixed 64 MHz HFXO — no portable scaling */` };
         case 'power.deep_sleep_pin': {
             // Configure the pin as a GPIO wake source (level interrupt), then k_sleep
             // until the interrupt fires. A static gpio_callback + a no-op handler (the

package/dist/lowering/preferences.js

@@ -29,6 +29,9 @@
 // Runtime Exception (RUNTIME_EXCEPTION.md at the repo root).
 // ---------------------------------------------------------------------------
 /** Render a HAL field: pass through (already rendered by the resolver). */
+function unq(v) {
+    return String(v).replace(/^"|"$/g, '');
+}
 function s(v) {
     return String(v);
 }
@@ -73,10 +76,7 @@ export function preferencesInitLines() {
         `    bool used;`,
         `};`,
         ``,
-        `// Active namespace prefix ("tc/<ns>/"). begin() overwrites it; end() clears.`,
-        `// prefs_ns is deliberately sized to hold "tc/" + a 16-char ns + "/" + NUL.`,
         `static struct {`,
-        `    char ns[24];`,
         `    bool loaded;`,
         `    __tc_prefs_slot slots[__TC_PREFS_SLOT_COUNT];`,
         `} __tc_prefs;`,
@@ -96,15 +96,18 @@ export function preferencesInitLines() {
         `            __tc_prefs.slots[i].len = static_cast<uint8_t>(got);`,
         `            // Type is encoded as the first byte of the stored value (see put_*).`,
         `            __tc_prefs.slots[i].type = __tc_prefs.slots[i].val[0];`,
-        `            (void)snprintf(__tc_prefs.slots[i].key, __TC_PREFS_KEY_LEN, "%s", name);`,
+        `            // h_set hands us the name RELATIVE to the handler's "tc"`,
+        `            // subtree ("rig/marker") — the cache keys full names, so`,
+        `            // re-attach the prefix or loaded entries never match a lookup.`,
+        `            (void)snprintf(__tc_prefs.slots[i].key, __TC_PREFS_KEY_LEN, "tc/%s", name);`,
         `            __tc_prefs.slots[i].used = true;`,
         `            return 0;`,
         `        }`,
         `    }`,
         `    return 0;  // cache full — silently drop (matches ESP32 NVS-full behavior)`,
         `}`,
-        `static int __tc_prefs_h_get(const char* key, char* val, int val_len_max) {`,
-        `    (void)key; (void)val; (void)val_len_max;`,
+        `static int __tc_prefs_h_get(const char* full, char* val, int val_len_max) {`,
+        `    (void)full; (void)val; (void)val_len_max;`,
         `    return -ENOENT;`,
         `}`,
         `static int __tc_prefs_h_commit(void) { return 0; }`,
@@ -122,12 +125,6 @@ export function preferencesInitLines() {
         `    }`,
         `}`,
         ``,
-        `// Build the full settings name "tc/<ns>/<key>" into out. ns is the active`,
-        `// prefix set by begin(); the slot's key[] stores this full path so remove()`,
-        `// and clear() can settings_delete the exact stored name.`,
-        `static void __tc_prefs_full(char* out, size_t outsz, const char* key) {`,
-        `    (void)snprintf(out, outsz, "%s%s", __tc_prefs.ns, key);`,
-        `}`,
         ``,
         `// Slot lookup by full settings name. Returns nullptr when absent (the get_*`,
         `// helpers then fall back to the caller's default value, matching the ESP32`,
@@ -159,9 +156,8 @@ export function preferencesInitLines() {
         `// as val[0] so h_set can recover it on the next boot without a separate`,
         `// name→type map.`,
         `template <typename T>`,
-        `static inline void __tc_prefs_put(const char* key, uint8_t tag, const T& value) {`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `static inline void __tc_prefs_put(const char* full, uint8_t tag, const T& value) {`,
+        `    __tc_prefs_ensure_loaded();   // begin() is gone — mount lazily here`,
         `    uint8_t buf[1U + sizeof(T)];`,
         `    buf[0] = tag;`,
         `    (void)memcpy(&buf[1], &value, sizeof(T));`,
@@ -177,9 +173,8 @@ export function preferencesInitLines() {
         `}`,
         ``,
         `template <typename T>`,
-        `static inline T __tc_prefs_get(const char* key, uint8_t tag, T def) {`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `static inline T __tc_prefs_get(const char* full, uint8_t tag, T def) {`,
+        `    __tc_prefs_ensure_loaded();`,
         `    __tc_prefs_slot* slot = __tc_prefs_find(full);`,
         `    if (slot == nullptr || slot->type != tag || slot->len < (1U + sizeof(T))) {`,
         `        return def;`,
@@ -192,23 +187,12 @@ export function preferencesInitLines() {
         `// ── Lifecycle (session model on top of the flat key-space) ──────────────`,
         `// begin records "tc/<ns>/" as the prefix every subsequent key is built under.`,
         `// end clears the prefix (NOT the cache). Both are cheap on Zephyr: the real`,
-        `// work is in settings_load() at boot. They exist for portability with the`,
-        `// ESP32 NVS session model and so a future session-needing backend has a hook.`,
-        `static inline void __tc_prefs_begin(const char* ns, bool readOnly) {`,
-        `    (void)readOnly;`,
-        `    __tc_prefs_ensure_loaded();`,
-        `    (void)snprintf(__tc_prefs.ns, sizeof(__tc_prefs.ns), "tc/%s/", ns);`,
-        `}`,
-        `static inline void __tc_prefs_end(void) {`,
-        `    __tc_prefs.ns[0] = '\\0';`,
-        `}`,
         ``,
         `// remove: drop one key from flash and the cache. Falls back to no-op if the`,
         `// slot isn't cached (settings_delete on a missing key returns -ENOENT, which`,
         `// we swallow).`,
-        `static inline void __tc_prefs_remove(const char* key) {`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `static inline void __tc_prefs_remove(const char* full) {`,
+        `    __tc_prefs_ensure_loaded();`,
         `    (void)settings_delete(full);`,
         `    __tc_prefs_slot* slot = __tc_prefs_find(full);`,
         `    if (slot != nullptr) { slot->used = false; }`,
@@ -218,11 +202,12 @@ export function preferencesInitLines() {
         `// authoritative list of keys we have written) and settings_delete each whose`,
         `// full name starts with the active ns prefix, then mark the slot free. Only`,
         `// the active namespace is cleared — keys under other namespaces survive.`,
-        `static inline void __tc_prefs_clear(void) {`,
-        `    const size_t plen = strlen(__tc_prefs.ns);`,
+        `static inline void __tc_prefs_clear(const char* prefix) {`,
+        `    __tc_prefs_ensure_loaded();`,
+        `    const size_t plen = strlen(prefix);`,
         `    for (int i = 0; i < __TC_PREFS_SLOT_COUNT; i++) {`,
         `        if (__tc_prefs.slots[i].used &&`,
-        `            strncmp(__tc_prefs.slots[i].key, __tc_prefs.ns, plen) == 0) {`,
+        `            strncmp(__tc_prefs.slots[i].key, prefix, plen) == 0) {`,
         `            (void)settings_delete(__tc_prefs.slots[i].key);`,
         `            __tc_prefs.slots[i].used = false;`,
         `        }`,
@@ -232,39 +217,38 @@ export function preferencesInitLines() {
         `// ── Typed accessors ─────────────────────────────────────────────────────`,
         `// Each put_* stamps its tag byte and persists; each get_* reads the cache and`,
         `// returns the default on miss/type-mismatch (mirrors ESP32 Preferences).`,
-        `static inline void __tc_prefs_put_int(const char* key, int32_t v) {`,
-        `    __tc_prefs_put<int32_t>(key, ${TAG.INT}, v);`,
+        `static inline void __tc_prefs_put_int(const char* full, int32_t v) {`,
+        `    __tc_prefs_put<int32_t>(full, ${TAG.INT}, v);`,
         `}`,
-        `static inline int32_t __tc_prefs_get_int(const char* key, int32_t def) {`,
-        `    return __tc_prefs_get<int32_t>(key, ${TAG.INT}, def);`,
+        `static inline int32_t __tc_prefs_get_int(const char* full, int32_t def) {`,
+        `    return __tc_prefs_get<int32_t>(full, ${TAG.INT}, def);`,
         `}`,
-        `static inline void __tc_prefs_put_uint(const char* key, uint32_t v) {`,
-        `    __tc_prefs_put<uint32_t>(key, ${TAG.UINT}, v);`,
+        `static inline void __tc_prefs_put_uint(const char* full, uint32_t v) {`,
+        `    __tc_prefs_put<uint32_t>(full, ${TAG.UINT}, v);`,
         `}`,
-        `static inline uint32_t __tc_prefs_get_uint(const char* key, uint32_t def) {`,
-        `    return __tc_prefs_get<uint32_t>(key, ${TAG.UINT}, def);`,
+        `static inline uint32_t __tc_prefs_get_uint(const char* full, uint32_t def) {`,
+        `    return __tc_prefs_get<uint32_t>(full, ${TAG.UINT}, def);`,
         `}`,
-        `static inline void __tc_prefs_put_bool(const char* key, bool v) {`,
+        `static inline void __tc_prefs_put_bool(const char* full, bool v) {`,
         `    uint8_t b = v ? 1U : 0U;`,
-        `    __tc_prefs_put<uint8_t>(key, ${TAG.BOOL}, b);`,
+        `    __tc_prefs_put<uint8_t>(full, ${TAG.BOOL}, b);`,
         `}`,
-        `static inline bool __tc_prefs_get_bool(const char* key, bool def) {`,
-        `    uint8_t b = __tc_prefs_get<uint8_t>(key, ${TAG.BOOL}, def ? 1U : 0U);`,
+        `static inline bool __tc_prefs_get_bool(const char* full, bool def) {`,
+        `    uint8_t b = __tc_prefs_get<uint8_t>(full, ${TAG.BOOL}, def ? 1U : 0U);`,
         `    return b != 0U;`,
         `}`,
-        `static inline void __tc_prefs_put_float(const char* key, float v) {`,
-        `    __tc_prefs_put<float>(key, ${TAG.FLOAT}, v);`,
+        `static inline void __tc_prefs_put_float(const char* full, float v) {`,
+        `    __tc_prefs_put<float>(full, ${TAG.FLOAT}, v);`,
         `}`,
-        `static inline float __tc_prefs_get_float(const char* key, float def) {`,
-        `    return __tc_prefs_get<float>(key, ${TAG.FLOAT}, def);`,
+        `static inline float __tc_prefs_get_float(const char* full, float def) {`,
+        `    return __tc_prefs_get<float>(full, ${TAG.FLOAT}, def);`,
         `}`,
         ``,
         `// Strings are length-prefixed into the value buffer (capped at STR_LEN so the`,
         `// whole slot still fits in __TC_PREFS_VAL_LEN). get copies out with a NUL and`,
         `// returns def when the slot is absent or the wrong type.`,
-        `static inline void __tc_prefs_put_string(const char* key, const char* v) {`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
+        `static inline void __tc_prefs_put_string(const char* full, const char* v) {`,
+        `    __tc_prefs_ensure_loaded();`,
         `    uint8_t buf[1U + __TC_PREFS_STR_LEN];`,
         `    buf[0] = ${TAG.STRING};`,
         `    size_t n = strlen(v);`,
@@ -280,10 +264,9 @@ export function preferencesInitLines() {
         `        slot->used = true;`,
         `    }`,
         `}`,
-        `static inline const char* __tc_prefs_get_string(const char* key, const char* def) {`,
+        `static inline const char* __tc_prefs_get_string(const char* full, const char* def) {`,
+        `    __tc_prefs_ensure_loaded();`,
         `    static char out[__TC_PREFS_STR_LEN + 1U];`,
-        `    char full[__TC_PREFS_KEY_LEN];`,
-        `    __tc_prefs_full(full, sizeof(full), key);`,
         `    __tc_prefs_slot* slot = __tc_prefs_find(full);`,
         `    if (slot == nullptr || slot->type != ${TAG.STRING} || slot->len < 1U) {`,
         `        return def;`,
@@ -307,37 +290,26 @@ export function preferencesInitLines() {
 export function lowerPreferences(op) {
     const o = op;
     switch (op.operation) {
-        case 'preferences.begin':
-            // readOnly is honored as a no-op: Zephyr settings has no read-only mount,
-            // and silently ignoring it matches the ESP32 Preferences behavior when
-            // an RO handle is written (the put returns an error the app doesn't see).
-            return { code: `__tc_prefs_begin(${s(o.namespace)}, ${o.readOnly ? 'true' : 'false'});` };
-        case 'preferences.end':
-            return { code: `__tc_prefs_end();` };
         case 'preferences.clear':
-            return { code: `__tc_prefs_clear();` };
+            return { code: `__tc_prefs_clear("tc/${unq(o.ns)}/");` };
         case 'preferences.remove':
-            return { code: `__tc_prefs_remove(${s(o.key)});` };
+            return { code: `__tc_prefs_remove("tc/${unq(o.ns)}/${unq(o.key)}");` };
         case 'preferences.put_int':
-            return { code: `__tc_prefs_put_int(${s(o.key)}, ${s(o.value)});` };
+            return { code: `__tc_prefs_put_int("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.value)});` };
         case 'preferences.get_int':
-            return { expression: `__tc_prefs_get_int(${s(o.key)}, ${s(o.defaultValue)})` };
-        case 'preferences.put_uint':
-            return { code: `__tc_prefs_put_uint(${s(o.key)}, ${s(o.value)});` };
-        case 'preferences.get_uint':
-            return { expression: `__tc_prefs_get_uint(${s(o.key)}, ${s(o.defaultValue)})` };
+            return { expression: `__tc_prefs_get_int("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.defaultValue)})` };
         case 'preferences.put_bool':
-            return { code: `__tc_prefs_put_bool(${s(o.key)}, ${o.value ? 'true' : 'false'});` };
+            return { code: `__tc_prefs_put_bool("tc/${unq(o.ns)}/${unq(o.key)}", ${o.value ? 'true' : 'false'});` };
         case 'preferences.get_bool':
-            return { expression: `__tc_prefs_get_bool(${s(o.key)}, ${o.defaultValue ? 'true' : 'false'})` };
+            return { expression: `__tc_prefs_get_bool("tc/${unq(o.ns)}/${unq(o.key)}", ${o.defaultValue ? 'true' : 'false'})` };
         case 'preferences.put_float':
-            return { code: `__tc_prefs_put_float(${s(o.key)}, ${s(o.value)});` };
+            return { code: `__tc_prefs_put_float("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.value)});` };
         case 'preferences.get_float':
-            return { expression: `__tc_prefs_get_float(${s(o.key)}, ${s(o.defaultValue)})` };
+            return { expression: `__tc_prefs_get_float("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.defaultValue)})` };
         case 'preferences.put_string':
-            return { code: `__tc_prefs_put_string(${s(o.key)}, ${s(o.value)});` };
+            return { code: `__tc_prefs_put_string("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.value)});` };
         case 'preferences.get_string':
-            return { expression: `__tc_prefs_get_string(${s(o.key)}, ${s(o.defaultValue)})` };
+            return { expression: `__tc_prefs_get_string("tc/${unq(o.ns)}/${unq(o.key)}", ${s(o.defaultValue)})` };
         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/pulse.js

@@ -7,7 +7,7 @@
 // implementations (no hardware pulse capture on nRF for the HAL surface); they
 // are correct but not high-precision.
 // ---------------------------------------------------------------------------
-import { controllerNodelabelForPin } from '../chips/controllers.js';
+import { controllerNodelabelForPin, controllerRawPinForPin } from '../chips/controllers.js';
 /** `DEVICE_DT_GET(DT_NODELABEL(<owning-controller>))` for a HAL pin. */
 function devForPin(chip, pin) {
     return `DEVICE_DT_GET(DT_NODELABEL(${controllerNodelabelForPin(chip, pin)}))`;
@@ -23,9 +23,9 @@ export function lowerPulseOrShift(op, chip) {
             // for the start edge is bounded by the timeout; the measurement of the
             // pulse itself is intentionally unbounded (that IS the pulse length).
             // Returns -1 (0) if the start edge never arrives within the timeout.
-            const pin = o.pin;
+            const pin = controllerRawPinForPin(chip, o.pin);
             const want = o.value;
-            const dev = devForPin(chip, pin);
+            const dev = devForPin(chip, o.pin);
             const timeout = o.timeout ?? 1_000_000; // default 1s in us
             return {
                 expression: `({ int64_t __max = static_cast<int64_t>(${timeout} / 1000); int64_t __t0 = k_uptime_get(); bool __ok = true; while (gpio_pin_get_raw(${dev}, ${pin}) != ${want}) { if ((k_uptime_get() - __t0) > __max) { __ok = false; break; } } int32_t __ret = 0; if (__ok) { int64_t __start = k_uptime_get(); while (gpio_pin_get_raw(${dev}, ${pin}) == ${want}) { } __ret = static_cast<int32_t>((k_uptime_get() - __start) * 1000); } __ret; })`,
@@ -36,45 +36,14 @@ export function lowerPulseOrShift(op, chip) {
             // with NO timeout (the comment claimed "no overflow concern" but the
             // real risk was hanging the thread on a stuck pin). Apply the same
             // timeout-bounded start-edge wait as pulse.in (bug Q5).
-            const pin = o.pin;
+            const pin = controllerRawPinForPin(chip, o.pin);
             const want = o.value;
-            const dev = devForPin(chip, pin);
+            const dev = devForPin(chip, o.pin);
             const timeout = o.timeout ?? 3_000_000; // default 3s in us (long pulses)
             return {
                 expression: `({ int64_t __max = static_cast<int64_t>(${timeout} / 1000); int64_t __t0 = k_uptime_get(); bool __ok = true; while (gpio_pin_get_raw(${dev}, ${pin}) != ${want}) { if ((k_uptime_get() - __t0) > __max) { __ok = false; break; } } int32_t __ret = 0; if (__ok) { int64_t __start = k_uptime_get(); while (gpio_pin_get_raw(${dev}, ${pin}) == ${want}) { } __ret = static_cast<int32_t>((k_uptime_get() - __start) * 1000); } __ret; })`,
             };
         }
-        case 'shift.out': {
-            // Bit-bang `value` (MSB or LSB first) via dataPin + clockPin. The two
-            // pins may sit on different GPIO controllers on multi-controller SoCs
-            // (ESP32-S3), so each is resolved to its own owning controller.
-            const dataPin = o.dataPin;
-            const clockPin = o.clockPin;
-            const dataDev = devForPin(chip, dataPin);
-            const clockDev = devForPin(chip, clockPin);
-            const msbFirst = o.bitOrder === 'msb';
-            const init = msbFirst ? '7' : '0';
-            const test = msbFirst ? '(__i >= 0)' : '(__i < 8)';
-            const step = msbFirst ? '__i--' : '__i++';
-            return {
-                code: `for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${dataDev}, ${dataPin}, (${o.value} >> __i) & 1); gpio_pin_set_raw(${clockDev}, ${clockPin}, 1); k_busy_wait(1); gpio_pin_set_raw(${clockDev}, ${clockPin}, 0); }`,
-            };
-        }
-        case 'shift.in': {
-            // Read 8 bits (MSB or LSB first) from dataPin, clocking on clockPin.
-            const dataPin = o.dataPin;
-            const clockPin = o.clockPin;
-            const dataDev = devForPin(chip, dataPin);
-            const clockDev = devForPin(chip, clockPin);
-            const msbFirst = o.bitOrder === 'msb';
-            const init = msbFirst ? '7' : '0';
-            const test = msbFirst ? '(__i >= 0)' : '(__i < 8)';
-            const step = msbFirst ? '__i--' : '__i++';
-            const accum = msbFirst ? '__v = (__v << 1)' : '__v |= (bit << __i)';
-            return {
-                expression: `({ uint8_t __v = 0; for (int __i = ${init}; ${test}; ${step}) { gpio_pin_set_raw(${clockDev}, ${clockPin}, 1); k_busy_wait(1); int bit = gpio_pin_get_raw(${dataDev}, ${dataPin}); gpio_pin_set_raw(${clockDev}, ${clockPin}, 0); ${accum}; } __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/pwm.d.ts

@@ -1,10 +1,39 @@
 import type { HALOpIR } from '@typecad/cuttlefish/api/shared';
-import type { ZephyrChipDescriptor } from '../chips/types.js';
+import type { ZephyrChipDescriptor, ZephyrPwmSpec } from '../chips/types.js';
+/**
+ * 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 declare function pwmDtAlias(spec: ZephyrPwmSpec): string;
+/**
+ * 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 declare function pwmDtAliasToken(spec: ZephyrPwmSpec): string;
+/**
+ * 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 declare function findPwmSpec(chip: ZephyrChipDescriptor, pin: number): ZephyrPwmSpec | undefined;
 /**
  * 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 declare function pwmInitLines(chip: ZephyrChipDescriptor): string[];
+export declare function pwmInitLines(chip: ZephyrChipDescriptor, usedPins?: ReadonlySet<number>, userSpecs?: readonly {
+    pin: number;
+    controller: string;
+    channel: number;
+}[]): string[];
 /**
  * Resolve a HAL pwm.* op to Zephyr C++.
  * Returns `{ code }` for statement ops, `{ expression }` for value-returning ops.