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

package/dist/chips/soc/stm32f411xe.js

@@ -0,0 +1,251 @@
+// Hand-maintained descriptor table — mechanically migrated from the
+// board-blackpill-f411ce + mcu-stm32f411 package data (the exact flatten+reconstruct the build
+// performed). Curated additions: tier/pinNaming/excludedPins. Regenerate
+// only alongside a descriptor-type change (edit this file; the original
+// migration script was never committed).
+export const STM32F411XE_SOC = {
+    "id": "blackpill_f411ce/stm32f411xe",
+    "soc": "stm32f411xe",
+    "gpioController": "gpioa",
+    "gpioControllers": [
+        {
+            "nodelabel": "gpioa",
+            "minPin": 0,
+            "maxPin": 15
+        },
+        {
+            "nodelabel": "gpiob",
+            "minPin": 16,
+            "maxPin": 31
+        },
+        {
+            "nodelabel": "gpioc",
+            "minPin": 32,
+            "maxPin": 47
+        }
+    ],
+    "gpio": {
+        "dtSpecs": [
+            {
+                "pin": 45,
+                "dtSpec": "led0"
+            },
+            {
+                "pin": 0,
+                "dtSpec": "sw0"
+            }
+        ],
+        "interruptPins": [
+            {
+                "pin": 0,
+                "dtSpec": "sw0"
+            }
+        ]
+    },
+    "i2c": {
+        "controllers": [
+            {
+                "nodeLabel": "i2c1"
+            }
+        ]
+    },
+    "spi": {
+        "controllers": [
+            {
+                "nodeLabel": "spi1"
+            }
+        ]
+    },
+    "uart": {
+        "controllers": [
+            {
+                "nodeLabel": "usart1"
+            }
+        ]
+    },
+    "pwm": {
+        "specs": [
+            {
+                "pin": 22,
+                "controller": "pwm4",
+                "channel": 1,
+                "periodNs": 20000000,
+                "pinctrl": "tim4_ch1_pb6"
+            },
+            {
+                "pin": 23,
+                "controller": "pwm4",
+                "channel": 2,
+                "periodNs": 20000000,
+                "pinctrl": "tim4_ch2_pb7"
+            }
+        ],
+        "clockHz": 96000000,
+        "maxFrequencyHz": 50000000,
+        "resolutionBits": 16
+    },
+    "adc": {
+        "nodeLabel": "adc1",
+        "resolution": 12,
+        "vrefMv": 3300,
+        "channels": [
+            {
+                "pin": 0,
+                "channel": 0,
+                "pinctrl": "adc1_in0_pa0"
+            },
+            {
+                "pin": 1,
+                "channel": 1,
+                "pinctrl": "adc1_in1_pa1"
+            },
+            {
+                "pin": 2,
+                "channel": 2,
+                "pinctrl": "adc1_in2_pa2"
+            },
+            {
+                "pin": 3,
+                "channel": 3,
+                "pinctrl": "adc1_in3_pa3"
+            },
+            {
+                "pin": 4,
+                "channel": 4,
+                "pinctrl": "adc1_in4_pa4"
+            },
+            {
+                "pin": 5,
+                "channel": 5,
+                "pinctrl": "adc1_in5_pa5"
+            },
+            {
+                "pin": 6,
+                "channel": 6,
+                "pinctrl": "adc1_in6_pa6"
+            },
+            {
+                "pin": 7,
+                "channel": 7,
+                "pinctrl": "adc1_in7_pa7"
+            },
+            {
+                "pin": 16,
+                "channel": 8,
+                "pinctrl": "adc1_in8_pb0"
+            },
+            {
+                "pin": 17,
+                "channel": 9,
+                "pinctrl": "adc1_in9_pb1"
+            }
+        ],
+        "gain": "ADC_GAIN_1",
+        "reference": "ADC_REF_INTERNAL"
+    },
+    "wdt": {
+        "nodeLabel": "iwdg"
+    },
+    "storage": {
+        "offset": 262144,
+        "size": 262144
+    },
+    "usb": {
+        "controller": "zephyr_udc0",
+        "cdcInstances": 1,
+        "vid": "0x2FE3",
+        "pid": "0x0002"
+    },
+    "consoleDescription": "usart1 on PA9 (TX) / PA10 (RX)",
+    "probeMethods": [
+        {
+            "id": "stlink",
+            "runner": "openocd",
+            "args": [
+                "--cmd-pre-init=reset_config none"
+            ],
+            "description": "ST-Link or any SWD probe openocd supports (no BOOT0 needed)",
+            "debug": true,
+            "debugInterface": "swd",
+            "debugCfg": [
+                "reset_config none"
+            ],
+            "debugCfgSource": [
+                "interface/stlink.cfg",
+                "target/stm32f4x.cfg"
+            ]
+        },
+        {
+            "id": "stlink-srst",
+            "runner": "openocd",
+            "args": [
+                "--cmd-pre-init=reset_config srst_only srst_nogate connect_assert_srst"
+            ],
+            "description": "ST-Link with the RST/SRST line wired — connect under reset (recovers wedged targets)",
+            "debug": true,
+            "debugInterface": "swd",
+            "debugCfg": [
+                "reset_config srst_only srst_nogate connect_assert_srst"
+            ],
+            "debugCfgSource": [
+                "interface/stlink.cfg",
+                "target/stm32f4x.cfg"
+            ]
+        },
+        {
+            "id": "dfu",
+            "runner": "dfu-util",
+            "description": "Built-in USB bootloader: hold BOOT0, tap reset",
+            "debug": false
+        },
+        {
+            "id": "jlink",
+            "runner": "jlink",
+            "description": "J-Link probe (SWD)",
+            "debug": true,
+            "debugInterface": "swd",
+            "debugDevice": "STM32F411CE"
+        }
+    ],
+    "customBoard": {
+        "socs": [
+            "stm32f411xe"
+        ],
+        "dtsIncludes": [
+            "st/f4/stm32f411Xe.dtsi",
+            "st/f4/stm32f411c(c-e)ux-pinctrl.dtsi"
+        ],
+        "console": {
+            "nodeLabel": "usart1",
+            "tx": "usart1_tx_pa9",
+            "rx": "usart1_rx_pa10",
+            "speed": 115200
+        },
+        "clocks": {
+            "hseMHz": 25,
+            "pll": {
+                "divM": 25,
+                "mulN": 192,
+                "divP": 2,
+                "divQ": 4
+            },
+            "sysMHz": 96,
+            "ahbPrescaler": 1,
+            "apb1Prescaler": 2,
+            "apb2Prescaler": 1
+        },
+        "usbNode": "usbotg_fs",
+        "usbPinctrl": [
+            "usb_otg_fs_dm_pa11",
+            "usb_otg_fs_dp_pa12"
+        ],
+        "adcNode": {
+            "nodeLabel": "adc1",
+            "clockSource": "SYNC",
+            "prescaler": 2,
+            "pinctrl": "adc1_in1_pa1"
+        }
+    },
+    "tier": "validated",
+    "pinNaming": "stm32-port"
+};

package/dist/chips/types.d.ts

@@ -43,6 +43,49 @@ export interface ZephyrGpioController {
 export interface ZephyrBusController {
     /** Devicetree nodelabel, e.g. 'i2c1', 'spi2', 'uart0'. */
     readonly nodeLabel: string;
+    /**
+     * Counter child form only: the labeled TIMER PARENT's nodelabel (ESP32
+     * timer0-3). The counter device is an unlabeled `counter {}` child; the
+     * nodeLabel above is a label the generated overlay defines on that child,
+     * and this field tells the overlay which parent to attach it to.
+     */
+    readonly counterParent?: string;
+    /**
+     * Synthesized pinctrl group, for controllers whose board DT ships no
+     * default group (e.g. uart1 on rpi_pico/rpi_pico2 — the mainline board DT
+     * only pins uart0). When present, the overlay generator emits the group
+     * under `&pinctrl` and wires `pinctrl-0`/`pinctrl-names` onto the
+     * controller when enabling it. RP2xxx pinmux is fully muxable per pad, so
+     * the group is pure data: which pads carry the signals.
+     */
+    readonly pinctrl?: {
+        /** Pinmux header to #include (token definitions). */
+        readonly include: string;
+        /** Output-signal pinmux tokens (emitted as group1). */
+        readonly pinmux: readonly string[];
+        /** Input-signal pinmux tokens (emitted as group2 with input-enable). */
+        readonly inputPinmux?: readonly string[];
+        /**
+         * `#define` lines emitted (ifndef-guarded) BEFORE the include — for
+         * upstream header bugs where a token's macro body references an
+         * undefined helper (e.g. RP2_PINCTRL_GPIO_FUNC_UART_ALT in Zephyr's
+         * rp2350 pinctrl headers, unreferenced by mainline so never noticed).
+         */
+        readonly defines?: readonly string[];
+    };
+    /**
+     * Reference an EXISTING pinctrl group (defined in the board's pinctrl
+     * dtsi but not attached to the node) instead of synthesizing one — e.g.
+     * uart1_default on esp32s3_devkitc. The overlay wires
+     * `pinctrl-0 = <&<group>>` when enabling the controller.
+     */
+    readonly pinctrlRef?: string;
+    /**
+     * Raw devicetree property lines emitted inside the enable block — for
+     * bindings with required properties the board DTS only sets on its own
+     * wired-up nodes (e.g. `current-speed` on the Picos' PL011 UARTs).
+     */
+    readonly props?: readonly string[];
 }
 /**
  * A PWM channel described as a devicetree spec.
@@ -78,6 +121,44 @@ export interface ZephyrPwmSpec {
     readonly periodNs?: number;
     /** Synthesized form: PWM polarity flag. Default PWM_POLARITY_NORMAL. */
     readonly polarity?: string;
+    /**
+     * SoC pinctrl dtsi token muxing this channel's pin to the timer (e.g.
+     * 'tim4_ch1_pb6' on STM32). Required on custom boards — the st,stm32-pwm
+     * binding demands pinctrl-0 on an enabled node and only a board DTS (or
+     * the custom-board generator, fed by this token) can provide it. Also
+     * gates the generated board's `pwmN: pwm { }` label declaration: the
+     * overlay references `&<controller>`, a label that otherwise exists only
+     * when a board DTS defines it.
+     */
+    readonly pinctrl?: string;
+}
+/**
+ * A "PWM matrix" controller: any listed pin can carry any channel, routed by
+ * the SoC's GPIO matrix rather than a fixed timer-channel↔pad map.
+ *
+ * ESP32 LEDC is the shape (espressif,esp32-ledc): 8 channels, each routable
+ * to (almost) any pad via a pinctrl pinmux token (`LEDC_CH<ch>_GPIO<pin>`).
+ * A static `specs` list cannot express this — two arbitrary pins would
+ * collide on a statically assigned channel — so the channel assignment is
+ * made at build time: the pins the program actually drives are assigned
+ * channels 0..N-1 (ascending pin order, capped at `channelCount`), and the
+ * overlay generator emits the pinctrl group + per-channel child nodes the
+ * espressif,esp32-ledc binding requires. The emitted C++ is channel-blind:
+ * it addresses each pin via the same `DT_ALIAS(tc-pwm<pin>)` the synthesized
+ * static form uses, so the two paths share the lowering.
+ */
+export interface ZephyrPwmMatrix {
+    /** PWM controller DT nodelabel, e.g. 'ledc0'. */
+    readonly controller: string;
+    /** Channels the controller exposes (ESP32-S3 LEDC: 8). */
+    readonly channelCount: number;
+    /**
+     * HAL pins usable as PWM outputs. This is the safety filter as much as the
+     * capability list — on the ESP32-S3 it excludes the boot-strap pin, the
+     * USB D+/D− pads, the flash/PSRAM pins (GPIO 26–32), the octal-PSRAM pins
+     * (GPIO 33–37), and the console UART pads (GPIO 43/44).
+     */
+    readonly pins: readonly number[];
 }
 /**
  * A GPIO pin usable as an interrupt source.
@@ -103,6 +184,14 @@ export interface ZephyrAdcChannel {
     readonly pin: number;
     /** ADC channel index (nRF SAADC AIN0–AIN7; STM32 ADC1_IN0–IN9). */
     readonly channel: number;
+    /**
+     * ADC device node label that OWNS this channel when the SoC has more than
+     * one ADC controller (STM32 adc1/adc2, ESP32 units), e.g. 'adc2'. Omitted
+     * for channels on the descriptor's primary controller (`adc.nodeLabel`) —
+     * a single-controller manifest is unchanged. Channel indices are unique
+     * only WITHIN a controller; the pair (controller, channel) is the key.
+     */
+    readonly controller?: string;
     /**
      * Pinctrl node label that muxes this pin to analog mode, e.g.
      * 'adc1_in0_pa0' (STM32). When present, the overlay generator rewrites the
@@ -123,6 +212,8 @@ export interface ZephyrDacChannel {
     readonly channel: number;
     /** DAC resolution in bits (ESP32 DAC is 8-bit). */
     readonly resolution: number;
+    /** Pinctrl node name routing the channel to its pad (STM32 harvest). */
+    readonly pinctrl?: string;
 }
 /**
  * Pure-data descriptor for a Zephyr board + its SoC's peripheral layout.
@@ -132,6 +223,33 @@ export interface ZephyrChipDescriptor {
     readonly id: string;
     /** SoC family, e.g. 'nrf52840'. */
     readonly soc: string;
+    /**
+     * How confident the framework is in this descriptor's facts.
+     * - 'validated' — the soc is part of the hardware-tested set; every field
+     *   was verified against the pinned Zephyr tree and real hardware.
+     * - 'derived' — reconstructed from data (board/MCU packages, DTS reading)
+     *   but never hardware-verified; capability errors may be less precise.
+     */
+    readonly tier?: 'validated' | 'derived';
+    /**
+     * Datasheet pin-naming convention — how a controller/pin pair becomes the
+     * schematic-facing name the generated board module exports (the
+     * `Pin.fromPort()` identity). One of:
+     * - 'esp32-gpio'   — flat numbering, `GPION` (esp32, esp32s3, esp32c*)
+     * - 'stm32-port'   — one controller per port, `P<port><bit>` (PA5, PB12)
+     * - 'nrf-port'     — P0.28 / P1.11 style (`P<port>.<bit>`)
+     * - 'rp-gpio'      — `GP<n>` flat numbering
+     * - 'samd-port'    — PA/PB ports like stm32-port
+     * Absent on tier-3 socs with no known convention (the generated board
+     * exposes only connector/alias pins + LED/BUTTON).
+     */
+    readonly pinNaming?: 'esp32-gpio' | 'stm32-port' | 'nrf-port' | 'rp-gpio' | 'samd-port';
+    /**
+     * Pins that exist in the controller ranges but must NOT be exported as
+     * usable GPIOs — strapping pads, flash/PSRAM, USB D+/-. The generated
+     * board module's pin list subtracts these.
+     */
+    readonly excludedPins?: readonly number[];
     /**
      * Default GPIO controller nodelabel for the raw-pin fallback. Pins not in
      * `gpio.dtSpecs` are addressed via
@@ -176,9 +294,68 @@ export interface ZephyrChipDescriptor {
     readonly uart?: {
         readonly controllers: readonly ZephyrBusController[];
     };
+    /**
+     * USB device (CDC-ACM serial) capability. Zephyr "next" USB device stack:
+     * the UDC controller node (uniformly `zephyr_udc0` on every USB-capable
+     * board) plus `cdcInstances` CDC-ACM class child nodes, both composed in
+     * the generated overlay. The lowering addresses instance N as
+     * DT_NODELABEL(cdc_acm_uart<N>) — a UART-class device driven with the
+     * plain uart_* API. Boards without USB device support omit this field;
+     * usb.* HAL ops then fail with a clear "board does not expose USB" error.
+     */
+    readonly usb?: {
+        /** UDC controller nodelabel (convention: 'zephyr_udc0'). */
+        readonly controller: string;
+        /** How many CDC-ACM serial instances to compose (≥1). */
+        readonly cdcInstances: number;
+        /** USB vendor ID for the device descriptor ('0x2fe3' Zephyr-test default). */
+        readonly vid?: string;
+        /** USB product ID for the device descriptor ('0x0001' default). */
+        readonly pid?: string;
+        /**
+         * 1200-baud touch-to-reset (BOSSA-bootloader boards, e.g. SAM D21).
+         *
+         * Present = two things happen automatically:
+         * - Device side: the emitted USB shim registers a usbd message callback;
+         *   when the host sets the CDC baud rate to 1200, the shim writes the
+         *   bootloader's "stay resident" magic to the flag address and reboots —
+         *   the board lands in the bootloader with no button press.
+         * - Host side: the bossac upload path opens the app's console port at
+         *   1200 baud to trigger the above, waits for the bootloader's USB
+         *   identity, and points bossac at that port.
+         * Omit on boards without a cooperative bootloader (probe- or
+         * UF2-flashed boards don't need it).
+         */
+        readonly touchReset?: {
+            /** RAM address of the bootloader's stay-resident flag word
+             * (SAMD21G18A: 0x20007FFC — the last word of the 32 KB SRAM). */
+            readonly flagAddress: number;
+            /** Magic word the bootloader checks there (Arduino SAMD: 0x07738135). */
+            readonly magic: number;
+            /** Bootloader USB vendor id, hex string ('0x2341') — host-side watch. */
+            readonly bootloaderVid?: string;
+            /** Bootloader USB product id, hex string ('0x0057') — host-side watch. */
+            readonly bootloaderPid?: string;
+        };
+    };
     /** PWM channels with DT specs. */
     readonly pwm?: {
         readonly specs: readonly ZephyrPwmSpec[];
+        /**
+         * Matrix PWM capability (ESP32 LEDC) — channels assigned to the driven
+         * pins at build time instead of enumerated statically. `specs` may be
+         * empty when only the matrix is declared.
+         */
+        readonly matrix?: ZephyrPwmMatrix;
+        /**
+         * Timer input clock (Hz) for the synthesized specs' controllers — the
+         * number the 16-bit overflow check divides by (STM32: APB clock × the
+         * timer multiplier; blackpill TIM4 = 96 MHz). When set, the overlay
+         * generator derives an `st,prescaler` for the timers node so slow
+         * periods (servo 20 ms) fit the 16-bit ARR — without it pwm_stm32
+         * rejects the channel ("period cycles exceeds 16-bit timer limit").
+         */
+        readonly clockHz?: number;
     };
     /** ADC: the ADC device node label + the pin→channel map. */
     readonly adc?: {
@@ -215,6 +392,25 @@ export interface ZephyrChipDescriptor {
     readonly wdt?: {
         readonly nodeLabel: string;
     };
+    /**
+     * Storage partition to synthesize when the board DTS ships none. Boards
+     * with an MCUboot-style partition map (most STM32s) define boot/slot
+     * partitions but no `storage_partition`, which the Preferences/FS backends
+     * (ZMS/littlefs) require. Present = "the overlay generator must declare
+     * this partition under &flash0"; boards whose DTS already carries one
+     * (ESP32 devkits) omit it — the overlay only adds the /chosen pointer.
+     * The region must cover ≥2 flash pages (ZMS minimum) and stay clear of
+     * the linked application image.
+     */
+    readonly storage?: {
+        /** Partition start offset in flash, page-aligned. */
+        readonly offset: number;
+        /** Partition size in bytes, a multiple of the flash page size. */
+        readonly size: number;
+        /** True when the board's own DTS already declares this partition — the
+         *  overlay must only point /chosen at it, never redeclare the node. */
+        readonly preexisting?: boolean;
+    };
     /**
      * Hardware timers exposed as Zephyr counter devices. `instance` (the HAL
      * hwtimer.* op's instance index) maps to `controllers[instance].nodeLabel`.
@@ -232,4 +428,127 @@ export interface ZephyrChipDescriptor {
     readonly wifi?: {
         readonly supported: true;
     };
+    /**
+     * Probe methods the board supports, in user-facing terms. Each entry maps a
+     * friendly id (`stlink`, `dfu`, `jlink`, …) to the west runner it drives
+     * plus any args the method always needs — the hardware quirks (e.g. openocd
+     * needing `reset_config none` when the SRST line is unwired) live here,
+     * verified with the board, instead of in user configs. One probe method
+     * serves BOTH flashing and debugging (the same attach session); entries
+     * that cannot debug (bootloaders) set `debug: false`. Users select one via
+     * `zephyr.probe` in cuttlefish.config.ts or `--probe` on the CLI;
+     * `zephyr.runner`/`runnerArgs` remain the raw escape hatch underneath.
+     */
+    readonly probeMethods?: readonly ZephyrProbeMethod[];
+    /**
+     * Silicon-level inputs for the custom-board generator — present when the
+     * chip was resolved from an MCU package's `zephyr` block (an MCU-only
+     * config with no board package). The generator emits an out-of-tree Zephyr
+     * board (`boards/typecad/<name>/` in the project) from exactly this data:
+     * SoC name, devicetree includes, the default console mux, and the default
+     * clock plan. Absent on board-resolved chips (their board already exists).
+     */
+    readonly customBoard?: ZephyrCustomBoardData;
+}
+/**
+ * Everything the custom-board generator needs from the silicon to emit a
+ * minimal, buildable out-of-tree board for a chip with no board package.
+ */
+export interface ZephyrCustomBoardData {
+    /** Zephyr SoC name(s) for board.yml + the Kconfig SOC_* selection. */
+    readonly socs: readonly string[];
+    /** Devicetree includes for the generated board DTS root (SoC + pinctrl). */
+    readonly dtsIncludes: readonly string[];
+    /** The default console the generated board enables. */
+    readonly console: {
+        /** Controller nodelabel, e.g. 'usart1'. */
+        readonly nodeLabel: string;
+        /** TX pinctrl token from the SoC's pinctrl dtsi, e.g. 'usart1_tx_pa9'. */
+        readonly tx: string;
+        /** RX pinctrl token, e.g. 'usart1_rx_pa10'. */
+        readonly rx: string;
+        /** Baud rate (the DT `current-speed`). */
+        readonly speed: number;
+    };
+    /**
+     * Default clock plan — the numbers the generated DTS writes into the SoC's
+     * clock nodes (HSE crystal frequency, PLL dividers, bus prescalers). A
+     * board package overrides with its own crystal/plan; a custom board uses
+     * this silicon default.
+     */
+    readonly clocks: {
+        /** HSE crystal frequency in MHz. */
+        readonly hseMHz: number;
+        /** PLL divider/multiplier plan. */
+        readonly pll: {
+            readonly divM: number;
+            readonly mulN: number;
+            readonly divP: number;
+            readonly divQ: number;
+        };
+        /** System clock frequency in MHz (the &rcc clock-frequency). */
+        readonly sysMHz: number;
+        readonly ahbPrescaler: number;
+        readonly apb1Prescaler: number;
+        readonly apb2Prescaler: number;
+    };
+    /**
+     * Silicon USB node to alias as `usb.controller` in the generated DTS
+     * (e.g. 'usbotg_fs' aliased as 'zephyr_udc0'). Omit when usb is absent.
+     */
+    readonly usbNode?: string;
+    /**
+     * Pinctrl tokens muxing the USB node's pins (e.g.
+     * 'usb_otg_fs_dm_pa11'/'usb_otg_fs_dp_pa12'). The st,stm32-otgfs binding
+     * requires pinctrl-0 on an enabled node, so the generated board pre-enables
+     * the USB node with exactly these (the blackpill shape). Omit when the
+     * SoC's USB needs no board-side muxing.
+     */
+    readonly usbPinctrl?: readonly string[];
+    /**
+     * ADC node the generated board must pre-enable with the SoC driver's
+     * required properties — e.g. the STM32 F4 binding rejects an enabled adc
+     * node without `st,adc-clock-source`/`st,adc-prescaler` (upstream boards
+     * set them in their DTS; a custom board has none, so the generator emits
+     * them from this data). The baseline pinctrl satisfies the binding's
+     * pinctrl-0 requirement; the usage-driven overlay rewrites it to the
+     * channels the program actually reads. Omit on SoCs whose ADC needs no
+     * board-side enabling.
+     */
+    readonly adcNode?: {
+        readonly nodeLabel: string;
+        /** The binding's clock-source property value (e.g. 'SYNC'). */
+        readonly clockSource: string;
+        /** The binding's prescaler property value (e.g. 2). */
+        readonly prescaler: number;
+        /** Baseline pinctrl token (e.g. 'adc1_in1_pa1'). */
+        readonly pinctrl: string;
+    };
+}
+/**
+ * A named way to attach a probe to a board — what the user picks, and what
+ * flashing/debugging lower to.
+ */
+export interface ZephyrProbeMethod {
+    /** User-facing id, stable per board (`stlink`, `dfu`, `jlink`, `uf2`, …). */
+    readonly id: string;
+    /** The west runner this method drives (flash and debug). */
+    readonly runner: string;
+    /** Args always passed with this method (before any user runnerArgs). */
+    readonly args?: readonly string[];
+    /** One-line human description for the wizard, doctor, and error messages. */
+    readonly description?: string;
+    /** Whether this method can debug (default true — SWD/JTAG probes can,
+     *  bootloaders cannot and set this false explicitly). */
+    readonly debug?: boolean;
+    /** cortex-debug: the wire protocol (default 'swd'; esp_usb_jtag is 'jtag'). */
+    readonly debugInterface?: 'swd' | 'jtag';
+    /** cortex-debug servertype=jlink: the J-Link device name (e.g. 'STM32F411CE'). */
+    readonly debugDevice?: string;
+    /** Raw OpenOCD cfg lines for the debug server config (e.g. 'reset_config
+     *  none') — the cfg-file form of the quirks `args` carry for west. */
+    readonly debugCfg?: readonly string[];
+    /** OpenOCD cfg `source [find …]` lines for the debug server (interface +
+     *  target configs). Omitted entries fall back to the framework default. */
+    readonly debugCfgSource?: readonly string[];
 }

package/dist/chips/xiao-ble.js

@@ -52,6 +52,15 @@ export const XIAO_BLE = {
     uart: {
         controllers: [{ nodeLabel: 'uart0' }],
     },
+    // nRF52840 native USB device (USBD). The board DTS carries `zephyr_udc0`
+    // (the nRF USBD driver node); the overlay enables it + composes one CDC-ACM
+    // instance when a program uses USB0. (The console on this board is already
+    // USB-CDC via the board's own chosen cdc_acm_uart0 — this field exposes the
+    // same peripheral to usb.* HAL ops.)
+    usb: {
+        controller: 'zephyr_udc0',
+        cdcInstances: 1,
+    },
     pwm: {
         // pwm-led0 drives the board PWM LED (PWM_OUT0 on P0.17, inverted).
         specs: [{ pin: 17, dtSpec: 'pwm-led0' }],
@@ -76,4 +85,16 @@ export const XIAO_BLE = {
     // Verified against the nRF52840 SoC dtsi (rtc0/rtc1 nodes). The kernel uses
     // RTC0 for the system tick; RTC1 is available for application use.
     hwtimer: { controllers: [{ nodeLabel: 'rtc1' }] },
+    // Mirror of board-xiao-nrf52840's probeMethods (registry fallback parity —
+    // the board package's zephyr field wins when board constants are present).
+    probeMethods: [
+        { id: 'jlink', runner: 'jlink', description: 'J-Link probe (SWD)',
+            debug: true, debugInterface: 'swd', debugDevice: 'nRF52840_xxAA' },
+        { id: 'openocd', runner: 'openocd',
+            description: 'Any SWD probe openocd supports (CMSIS-DAP, cheap clones)',
+            debug: true, debugInterface: 'swd',
+            debugCfgSource: ['interface/stlink.cfg', 'target/nrf52.cfg'] },
+        { id: 'uf2', runner: 'uf2', description: 'Bootloader UF2 drag-and-drop: double-tap reset',
+            debug: false },
+    ],
 };

package/dist/display/profiles.js

@@ -40,7 +40,7 @@ export const ZEPHYR_DISPLAY_PROFILES = {
         // ST7796S SPI TFT, 320x480 RGB565 mounted landscape (effective 480x320).
         // Same DT nodelabel convention as the ILI9341 — the board's devicetree
         // carries the `display0` node bound to the ST7796 driver; the overlay
-        // enables it via status="okay". Effective dims match the Arduino
+        // enables it via status="okay". Effective dims match the display
         // st7796-spi profile (480x320 landscape, rotation 1).
         driver: 'st7796-zephyr',
         dtLabel: 'display0',