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

package/dist/chips/board-overrides.d.ts

@@ -0,0 +1,7 @@
+export interface BoardOverride {
+    /** LED pin name for boards whose user LED is not a gpio-leds node (the
+     *  ESP32-S3 DevKitC's addressable RGB on GPIO48 — driven as plain GPIO,
+     *  same as the deleted board package did). */
+    readonly led?: string;
+}
+export declare const BOARD_OVERRIDES: Readonly<Record<string, BoardOverride>>;

package/dist/chips/board-overrides.js

@@ -0,0 +1,11 @@
+// ---------------------------------------------------------------------------
+// board-overrides.ts — curated board-level facts the devicetree cannot
+// express. The honest residue of the board-package deletion: things a board
+// vendor documents in a datasheet but never encodes in DTS.
+//
+// Keyed by the bare board id (the first segment of the qualified target, so
+// every variant/qualifier of the board inherits the override).
+// ----------------------------------------------------------------------------
+export const BOARD_OVERRIDES = {
+    esp32s3_devkitc: { led: 'GPIO48' },
+};

package/dist/chips/controllers.d.ts

@@ -1,4 +1,4 @@
-import type { ZephyrChipDescriptor } from './types.js';
+import type { ZephyrChipDescriptor, ZephyrGpioController } from './types.js';
 /**
  * Resolve the devicetree nodelabel of the GPIO controller that owns `pin`.
  *
@@ -9,13 +9,33 @@ import type { ZephyrChipDescriptor } from './types.js';
  */
 export declare function controllerNodelabelForPin(chip: ZephyrChipDescriptor, pin: number): string;
 /**
- * Emit the C++ source for a runtime pin → GPIO-device dispatcher.
+ * The owning controller range for a HAL pin, if the chip declares a split.
+ */
+export declare function controllerRangeForPin(chip: ZephyrChipDescriptor, pin: number): ZephyrGpioController | undefined;
+/**
+ * The PORT-RELATIVE pin index for the raw gpio_pin_*_raw() API — the Zephyr
+ * raw calls address the index WITHIN the controller, not the global HAL pin
+ * number. For split SoCs each controller's `minPin` is its base (STM32:
+ * gpiob minPin 16, so PB12 = pin 28 → raw 12); single-controller SoCs have
+ * no offset. Emitting the global number against a port driver would address
+ * a nonexistent port bit (STM32 gpiob is 0–15) and fail at runtime.
+ */
+export declare function controllerRawPinForPin(chip: ZephyrChipDescriptor, pin: number): number;
+/**
+ * Emit the C++ source for runtime pin → GPIO-device / port-relative-index
+ * dispatchers.
+ *
+ * Returns lines defining:
+ *  - `static inline const struct device* __tc_gpio_dev(uint32_t pin)` — the
+ *    owning controller's device, resolved via DEVICE_DT_GET(DT_NODELABEL(...))
+ *    at compile time (the macro is evaluated per branch, so it is always
+ *    statically valid); only `pin` is runtime.
+ *  - `static inline gpio_pin_t __tc_gpio_pin(uint32_t pin)` — the
+ *    port-relative index for gpio_pin_*_raw() (see controllerRawPinForPin).
+ *    The runtime shim paths (UI pin-watch, safety voters) take a runtime pin,
+ *    so they cannot bake the offset in at emit time.
  *
- * Returns lines defining `static inline const struct device* __tc_gpio_dev(uint32_t pin)`.
- * Each branch resolves its controller via `DEVICE_DT_GET(DT_NODELABEL(...))` at
- * compile time (the macro is evaluated per branch, so it is always statically
- * valid); only `pin` is runtime. For a single-controller SoC this collapses to
- * a one-liner returning that controller, so the existing XIAO nRF52840 behavior
- * is byte-for-byte unchanged.
+ * For a single-controller SoC both collapse to one-liners, so the existing
+ * XIAO nRF52840 behavior is byte-for-byte unchanged.
  */
 export declare function emitGpioDevDispatcher(chip: ZephyrChipDescriptor): string[];

package/dist/chips/controllers.js

@@ -27,23 +27,47 @@
  * for out-of-range pins (e.g. the manifest probe's synthetic pin 0).
  */
 export function controllerNodelabelForPin(chip, pin) {
+    const hit = controllerRangeForPin(chip, pin);
+    return hit ? hit.nodelabel : chip.gpioController;
+}
+/**
+ * The owning controller range for a HAL pin, if the chip declares a split.
+ */
+export function controllerRangeForPin(chip, pin) {
     const ranges = chip.gpioControllers;
     if (ranges && ranges.length > 0) {
-        const hit = ranges.find((r) => pin >= r.minPin && pin <= r.maxPin);
-        if (hit)
-            return hit.nodelabel;
+        return ranges.find((r) => pin >= r.minPin && pin <= r.maxPin);
     }
-    return chip.gpioController;
+    return undefined;
 }
 /**
- * Emit the C++ source for a runtime pin → GPIO-device dispatcher.
+ * The PORT-RELATIVE pin index for the raw gpio_pin_*_raw() API — the Zephyr
+ * raw calls address the index WITHIN the controller, not the global HAL pin
+ * number. For split SoCs each controller's `minPin` is its base (STM32:
+ * gpiob minPin 16, so PB12 = pin 28 → raw 12); single-controller SoCs have
+ * no offset. Emitting the global number against a port driver would address
+ * a nonexistent port bit (STM32 gpiob is 0–15) and fail at runtime.
+ */
+export function controllerRawPinForPin(chip, pin) {
+    const hit = controllerRangeForPin(chip, pin);
+    return pin - (hit?.minPin ?? 0);
+}
+/**
+ * Emit the C++ source for runtime pin → GPIO-device / port-relative-index
+ * dispatchers.
+ *
+ * Returns lines defining:
+ *  - `static inline const struct device* __tc_gpio_dev(uint32_t pin)` — the
+ *    owning controller's device, resolved via DEVICE_DT_GET(DT_NODELABEL(...))
+ *    at compile time (the macro is evaluated per branch, so it is always
+ *    statically valid); only `pin` is runtime.
+ *  - `static inline gpio_pin_t __tc_gpio_pin(uint32_t pin)` — the
+ *    port-relative index for gpio_pin_*_raw() (see controllerRawPinForPin).
+ *    The runtime shim paths (UI pin-watch, safety voters) take a runtime pin,
+ *    so they cannot bake the offset in at emit time.
  *
- * Returns lines defining `static inline const struct device* __tc_gpio_dev(uint32_t pin)`.
- * Each branch resolves its controller via `DEVICE_DT_GET(DT_NODELABEL(...))` at
- * compile time (the macro is evaluated per branch, so it is always statically
- * valid); only `pin` is runtime. For a single-controller SoC this collapses to
- * a one-liner returning that controller, so the existing XIAO nRF52840 behavior
- * is byte-for-byte unchanged.
+ * For a single-controller SoC both collapse to one-liners, so the existing
+ * XIAO nRF52840 behavior is byte-for-byte unchanged.
  */
 export function emitGpioDevDispatcher(chip) {
     const ranges = chip.gpioControllers;
@@ -53,14 +77,27 @@ export function emitGpioDevDispatcher(chip) {
             `    (void)pin;`,
             `    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`,
             '}',
+            'static inline gpio_pin_t __tc_gpio_pin(uint32_t pin) {',
+            `    return (gpio_pin_t)pin;`,
+            '}',
         ];
     }
     const lines = [
         'static inline const struct device* __tc_gpio_dev(uint32_t pin) {',
     ];
+    const pinLines = [
+        'static inline gpio_pin_t __tc_gpio_pin(uint32_t pin) {',
+    ];
     for (const r of ranges) {
         lines.push(`    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return DEVICE_DT_GET(DT_NODELABEL(${r.nodelabel})); }`);
+        if (r.minPin === 0) {
+            pinLines.push(`    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return (gpio_pin_t)pin; }`);
+        }
+        else {
+            pinLines.push(`    if (pin >= ${r.minPin} && pin <= ${r.maxPin}) { return (gpio_pin_t)(pin - ${r.minPin}); }`);
+        }
     }
     lines.push(`    return DEVICE_DT_GET(DT_NODELABEL(${chip.gpioController}));`, '}');
-    return lines;
+    pinLines.push(`    return (gpio_pin_t)pin;`, '}');
+    return [...lines, ...pinLines];
 }

package/dist/chips/esp32s3.js

@@ -51,4 +51,53 @@ export const ESP32S3_DEVKITC = {
     // WiFi: the ESP32-S3 has a 2.4GHz radio; conn_mgr + the esp32 wifi driver
     // (CONFIG_WIFI_ESP32) provide connectivity. Omitted on radioless targets.
     wifi: { supported: true },
+    // User buses, mirroring the devkit's verified facts (the
+    // board-constants path is authoritative in real builds; this registry
+    // entry is the fallback when board constants are absent — e.g. the
+    // transpile test harness). uart1 (not uart0 — the console) with the
+    // pinctrl group + current-speed the esp32-uart binding requires; i2c0;
+    // spi2/spi3.
+    i2c: { controllers: [{ nodeLabel: 'i2c0' }] },
+    spi: { controllers: [{ nodeLabel: 'spi2' }, { nodeLabel: 'spi3' }] },
+    uart: {
+        controllers: [
+            {
+                nodeLabel: 'uart1',
+                pinctrlRef: 'uart1_default',
+                props: ['current-speed = <115200>;'],
+            },
+        ],
+    },
+    // USB CDC-ACM over the S3's native USB-OTG (D-/D+ on the dedicated GPIO19/20
+    // pads, no GPIO matrix). The board DTS already aliases the DWC2 controller
+    // node and enables it (`zephyr_udc0: &usb_otg { status = "okay"; }` —
+    // esp32s3_devkitc_procpu.dts), and the UDC DWC2 driver is DT-default-on, so
+    // declaring it here is all usb.* needs: the overlay composes one CDC-ACM
+    // instance child and the kconfig resolver enables the "next" USB stack.
+    // Console stays on uart0 (the devkit's USB-serial bridge) unless
+    // `console.output: 'usb'` rebinds zephyr,console to the CDC port.
+    usb: { controller: 'zephyr_udc0', cdcInstances: 1, vid: '0x2FE3', pid: '0x0006' },
+    // PWM: the LEDC controller (ledc0 in esp32s3_common.dtsi) — 8 channels, each
+    // routable to nearly any pad through the GPIO matrix, so this is a matrix
+    // (channels assigned to the driven pins at build time), not a static spec
+    // list. Pin selection excludes: GPIO0 (boot strap / BOOT button), GPIO19/20
+    // (USB D-/D+), GPIO26–32 (SPI flash/PSRAM), GPIO33–37 (octal PSRAM on OPI
+    // modules), GPIO43/44 (uart0 console pads). The driver
+    // (CONFIG_PWM_LED_ESP32, DT-default-on) requires a pinctrl group routing
+    // each used channel (LEDC_CH<ch>_GPIO<pin> pinmux tokens, all 8×46 pairs in
+    // esp32s3-pinctrl.h) plus per-channel child nodes (reg + timer) — both
+    // emitted by the overlay generator (dt-config/overlay.ts emitPwmNodes).
+    pwm: {
+        specs: [],
+        matrix: {
+            controller: 'ledc0',
+            channelCount: 8,
+            pins: [
+                1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18,
+                21,
+                38, 39, 40, 41, 42,
+                45, 46, 47, 48,
+            ],
+        },
+    },
 };

package/dist/chips/index.d.ts

@@ -1,15 +1,9 @@
 import type { ZephyrChipDescriptor } from './types.js';
-import { XIAO_BLE } from './xiao-ble.js';
-import { ESP32S3_DEVKITC } from './esp32s3.js';
-import { ESP32_DEVKITC } from './esp32.js';
-export { XIAO_BLE, ESP32S3_DEVKITC, ESP32_DEVKITC };
-export type { ZephyrChipDescriptor, ZephyrGpioDtSpec } from './types.js';
-export declare function setActiveChip(d: ZephyrChipDescriptor): void;
-export declare function getActiveChip(): ZephyrChipDescriptor;
 /**
- * Resolve a chip descriptor from the Zephyr board target string
- * (frameworkData.buildTarget / frameworkData.target). Accepts the bare board
- * id ('xiao_ble', 'esp32s3_devkitc', 'esp32_devkitc') or a board/qualifier
- * path ('esp32s3_devkitc/esp32s3/procpu', 'esp32_devkitc/esp32/procpu').
+ * The no-board fallback: no controllers, no buses, no silicon facts. The
+ * lowering treats it as "unsupported operation" per subsystem, which is the
+ * honest answer when no board resolved.
  */
-export declare function chipForTarget(target?: string): ZephyrChipDescriptor;
+export declare const NO_BOARD_CHIP: ZephyrChipDescriptor;
+export declare function setActiveChip(d: ZephyrChipDescriptor): void;
+export declare function getActiveChip(): ZephyrChipDescriptor;

package/dist/chips/index.js

@@ -1,45 +1,29 @@
 // ---------------------------------------------------------------------------
-// Chip descriptor registry — maps Zephyr board target → ZephyrChipDescriptor
+// Chip descriptor cache — the mechanism the strategy's lowering reads.
 //
-// Mirrors framework-esp32/src/chips/index.ts: a module-level activeChip,
-// setActiveChip/getActiveChip, and chipForTarget resolving from
-// frameworkData.buildTarget. The strategy calls setActiveChip during profile
-// resolution so the lowering reads a single cached descriptor.
+// There is no curated descriptor registry: every board's chip view is
+// reconstructed from its generated board manifest via resolveChipFromBoard
+// (src/chips/resolve.ts). This module only caches that resolved descriptor
+// for the process lifetime (setActiveChip during profile resolution, the
+// lowering reads getActiveChip) and provides the empty fallback for
+// contexts with no board at all.
 // ---------------------------------------------------------------------------
-import { XIAO_BLE } from './xiao-ble.js';
-import { ESP32S3_DEVKITC } from './esp32s3.js';
-import { ESP32_DEVKITC } from './esp32.js';
-export { XIAO_BLE, ESP32S3_DEVKITC, ESP32_DEVKITC };
 /**
- * Default chip used when no buildTarget is supplied. The XIAO nRF52840 is the
- * canonical MVP target; subsequent board additions extend the switch below.
+ * The no-board fallback: no controllers, no buses, no silicon facts. The
+ * lowering treats it as "unsupported operation" per subsystem, which is the
+ * honest answer when no board resolved.
  */
-const DEFAULT_CHIP = XIAO_BLE;
-let activeChip = DEFAULT_CHIP;
+export const NO_BOARD_CHIP = {
+    id: 'no-board',
+    soc: '',
+    gpioController: 'gpio0',
+    gpio: { dtSpecs: [] },
+    probeMethods: [],
+};
+let activeChip = NO_BOARD_CHIP;
 export function setActiveChip(d) {
     activeChip = d;
 }
 export function getActiveChip() {
     return activeChip;
 }
-/**
- * Resolve a chip descriptor from the Zephyr board target string
- * (frameworkData.buildTarget / frameworkData.target). Accepts the bare board
- * id ('xiao_ble', 'esp32s3_devkitc', 'esp32_devkitc') or a board/qualifier
- * path ('esp32s3_devkitc/esp32s3/procpu', 'esp32_devkitc/esp32/procpu').
- */
-export function chipForTarget(target) {
-    const t = (target ?? '').trim().toLowerCase();
-    const boardId = t.split('/')[0];
-    switch (boardId) {
-        case 'xiao_ble':
-            return XIAO_BLE;
-        case 'esp32s3_devkitc':
-            return ESP32S3_DEVKITC;
-        case 'esp32_devkitc':
-            return ESP32_DEVKITC;
-        case '':
-        default:
-            return DEFAULT_CHIP;
-    }
-}

package/dist/chips/resolve.d.ts

@@ -1,9 +1,23 @@
 import type { BoardConstants } from '@typecad/cuttlefish/api/shared';
-import type { ZephyrChipDescriptor } from './types.js';
+import type { ZephyrChipDescriptor, ZephyrPwmSpec } from './types.js';
 /**
  * Try to derive a ZephyrChipDescriptor from board/MCU package constants.
  *
  * Returns null when no zephyr info is available in the board constants
- * (the caller should fall back to the hardcoded chipForTarget registry).
+ * (the caller should treat the board as unresolved — NO_BOARD_CHIP).
  */
 export declare function resolveChipFromBoard(bc: BoardConstants | undefined): ZephyrChipDescriptor | null;
+/**
+ * Board-level PWM specs from the generated board manifest (zephyr.pwm.specs.*
+ * — the pwm-leds facts boardgen emits on virtual pins 8192+). The active
+ * chip's spec table is silicon-curated; these JOIN it (see mergeBoardPwmSpecs)
+ * so a board's own devicetree-aliased PWM LED is addressable without curation.
+ */
+export declare function boardPwmSpecsFromConstants(bc: BoardConstants | undefined): ZephyrPwmSpec[];
+/**
+ * Merge board-level PWM specs into a chip descriptor. Collision rule: a
+ * board spec whose pin OR dtSpec already exists in the chip's table is
+ * dropped (the curated entry wins — e.g. the XIAO's hand-tuned pwm-led0
+ * spec). Returns the chip unchanged when nothing joins.
+ */
+export declare function mergeBoardPwmSpecs(chip: ZephyrChipDescriptor, boardSpecs: readonly ZephyrPwmSpec[]): ZephyrChipDescriptor;