@typecad/cuttlefish 1.0.0-alpha.13 → 1.0.0-alpha.15

package/dist/board-catalog/dts-reader.d.ts

@@ -0,0 +1,220 @@
+/** A GPIO reference inside the devicetree: controller nodelabel + pin + flags. */
+export interface DtsGpioRef {
+    /** Controller nodelabel, e.g. 'gpioa', 'gpio0'. */
+    readonly controller: string;
+    /** Pin number within the controller. */
+    readonly pin: number;
+    /** Raw flag tokens as written (macros stay opaque): ['GPIO_ACTIVE_LOW', 'GPIO_PULL_UP']. */
+    readonly flags: readonly string[];
+}
+/** A gpio-leds / gpio-keys child with its devicetree alias when aliased. */
+export interface DtsGpioNode extends DtsGpioRef {
+    /** Node's own nodelabel, e.g. 'user_led', 'button0'. */
+    readonly nodelabel: string;
+    /** Devicetree alias pointing here, e.g. 'led0', 'sw0' (from the aliases node). */
+    readonly alias?: string;
+}
+/** A connector nexus (e.g. the XIAO's D0–D10 gpio-map). */
+export interface DtsConnector {
+    /** Connector nodelabel, e.g. 'xiao_d', 'arduino_header_d'. */
+    readonly nodelabel: string;
+    /** Compatible string, e.g. 'seeed,xiao-gpio', 'arduino-header-r3'. */
+    readonly compatible?: string;
+    /** Silkscreen-ish label (from the map's trailing comments) → ref. */
+    readonly pins: Readonly<Record<string, DtsGpioRef>>;
+}
+/** Everything the reader could extract from one board DTS (post local includes). */
+export interface DtsBoardFacts {
+    /** alias name → nodelabel ('led0' → 'user_led', 'sw0' → 'button0'). */
+    readonly aliases: Readonly<Record<string, string>>;
+    /** chosen property → nodelabel ('zephyr,console' → 'uart0'). */
+    readonly chosen: Readonly<Record<string, string>>;
+    /** gpio-leds children. */
+    readonly leds: readonly DtsGpioNode[];
+    /** gpio-keys children. */
+    readonly buttons: readonly DtsGpioNode[];
+    /** Connector nexus maps. */
+    readonly connectors: readonly DtsConnector[];
+    /** Wired analog channels from connector io-channel-maps, joined to pads
+     *  through the connectors' gpio-maps (the DKs' A0-A5 ↔ AIN wiring). */
+    readonly connectorAdc: readonly {
+        source: string;
+        channel: number;
+        controller: string;
+        pin: number;
+    }[];
+    /** Name↔pinmux-value disagreement warnings from the pinctrl harvest —
+     *  each names a route that was DROPPED as untrustworthy. Surfaced through
+     *  the catalog record so board-module generation can report them. */
+    readonly pinctrlWarnings?: readonly string[];
+    /** Addressable user LED (worldsemi,ws2812-*): the pad driving the pixel.
+     *  NOT a gpio-leds node — consumers must treat it as a plain GPIO LED
+     *  (no led0 devicetree spec), same as a curated board override. */
+    readonly stripLed?: DtsGpioRef;
+    /** PWM-driven LEDs (pwm-leds children), in board order. `alias` is the
+     *  devicetree alias ('pwm-led0') — the addressable form; non-aliased
+     *  channels carry their controller+channel only. */
+    readonly pwmLeds: readonly DtsPwmLed[];
+    /** The board's USB device wiring: 'enabled' when the DTS turns the device
+     *  controller on (zephyr_udc0/&usbd status okay), 'disabled' when it
+     *  explicitly turns it off, undefined when the DTS is silent (the app
+     *  overlay may still compose a CDC device). */
+    readonly usbDevice?: 'enabled' | 'disabled';
+    /** The USB device controller nodelabel backing usbDevice ('zephyr_udc0',
+     *  or the board's own label for &usbd). */
+    readonly usbController?: string;
+    /** Bus controller nodelabels the board DTS wires up (&i2c0/&spi2/&usart1
+     *  status-okay overrides; &ref blocks). Board-level facts only — a bus
+     *  enabled solely in the SoC dtsi is invisible here, by design. */
+    readonly buses: {
+        readonly i2c: readonly string[];
+        readonly spi: readonly string[];
+        readonly uart: readonly string[];
+    };
+    /** Silicon PWM routes from the SoC pinctrl files the board's include
+     *  chain reaches (STM32 vendor HAL ships per-soc *-pinctrl.dtsi with
+     *  `tim4_ch1_pb6`-style nodes). Empty for SoCs whose pinctrl data lives
+     *  elsewhere (Atmel C headers) or whose PWM is a matrix (ESP32 LEDC) —
+     *  those are family conventions in the manifest generator. */
+    readonly pwmPins: readonly DtsPwmPin[];
+    /** Silicon analog-input routes from the SoC pinctrl files (STM32
+     *  `adc1_in1_pa1`-style nodes). Same raw-harvest contract as pwmPins. */
+    readonly adcPins: readonly DtsAdcPin[];
+    /** Silicon analog-output routes from the SoC pinctrl files (STM32
+     *  `dac1_out1_pa4`-style nodes). Same raw-harvest contract as pwmPins. */
+    readonly dacPins: readonly DtsDacPin[];
+    /** SoC-level ADC/DAC device nodelabels found in the include chain
+     *  (adc1:/dac1: device nodes). Pinctrl routes whose source device is
+     *  absent here are dropped by the manifest generator — a route for an
+     *  undeclared device would emit DEVICE_DT_GET against nothing. */
+    readonly analogDevices: readonly string[];
+    /** SoC-level watchdog node reached through the include chain (compatible
+     *  `*-watchdog`), for boards whose own DTS writes no watchdog0 alias —
+     *  the hardware exists on nearly every SoC; the alias is authorial habit.
+     *  Board-level watchdog0 alias wins over this. */
+    readonly wdtSocNode?: string;
+    /** ESP32 LEDC matrix controller nodelabel ('ledc0'), when the include
+     *  chain declares one. */
+    readonly ledcNode?: string;
+    /** Labeled PWM controller device nodes in the include chain (nRF's
+     *  psel-routed `pwm0`..`pwm3` — any GPIO pad can carry any of a
+     *  peripheral's channels: the matrix the manifest generator synthesizes
+     *  from, like the ESP32 LEDC). Sorted. */
+    readonly pwmNodes?: readonly string[];
+    /** Flash size in KB (the largest flash@ reg DT_SIZE_K across the include
+     *  chain — the variant dtsi overrides the SoC default). Feeds the storage
+     *  partition synthesis. */
+    readonly flashKb?: number;
+    /** True when the board's own chain already defines a storage_partition
+     *  label — synthesis must not redeclare it (west errors on a doubly
+     *  defined node). */
+    readonly hasStoragePartition?: boolean;
+    /** The board's own storage_partition reg, when the chain defines one —
+     *  offset/size in bytes. Boards that ship the partition (ESP32 AMP layout)
+     *  carry their real facts instead of a synthesized region; the overlay
+     *  only writes the /chosen pointer for them, never a redeclaration. */
+    readonly storageReg?: {
+        offsetBytes: number;
+        sizeBytes: number;
+    };
+    /** Counter-capable devices reached through the include chain, in source
+     *  order. Two forms: a labeled node whose compatible IS a counter
+     *  (nRF `rtc1:` nordic,nrf-rtc; STM32 `rtc:` st,stm32-rtc — the counter
+     *  driver binds the node itself), or an unlabeled `counter {}` child
+     *  under a labeled timer parent (ESP32 timer0-2, Ambiq) — the manifest
+     *  generator assigns those labels in the generated overlay. */
+    readonly counterNodes: readonly DtsCounterNode[];
+    /** GPIO controller device nodes (gpio-controller property) from the SoC
+     *  dtsi include chain — the full port inventory, not just the ports the
+     *  board's own facts name. Sorted by nodelabel. */
+    readonly gpioControllers: readonly DtsGpioController[];
+}
+/** A pwm-leds child: one PWM-driven LED channel. */
+export interface DtsPwmLed {
+    /** Devicetree alias ('pwm-led0') when aliased — the DT_ALIAS addressing form. */
+    readonly alias?: string;
+    /** PWM controller nodelabel ('pwm1'). */
+    readonly controller: string;
+    readonly channel: number;
+    /** Period cell from the pwms property, when present. */
+    readonly periodNs?: number;
+    /** Flag tokens (PWM_POLARITY_INVERTED, …). Macro expressions like
+     *  PWM_MSEC(20) are period shorthand — never flags. */
+    readonly flags?: readonly string[];
+}
+/** A silicon PWM route harvested from an SoC pinctrl file: a timer channel
+ *  reachable on a specific pad, e.g. STM32 `tim4_ch1_pb6` (TIM4 CH1 on PB6).
+ *  RAW — ports/bits as the pinctrl file states them; the board manifest
+ *  generator maps them to global pin numbers using its derived controller
+ *  table and applies the family's nodelabel conventions (tim4 → pwm4). */
+export interface DtsPwmPin {
+    /** Pinctrl-source peripheral name, e.g. 'tim4'. */
+    readonly source: string;
+    /** Channel number within the peripheral. */
+    readonly channel: number;
+    /** GPIO port letter as written ('A', 'B', …). */
+    readonly port: string;
+    /** Pad bit within the port. */
+    readonly bit: number;
+    /** The pinctrl node's own name — the token the generated overlay composes
+     *  `pinctrl-0 = <&name>` references from ('tim4_ch1_pb6'). */
+    readonly pinctrl: string;
+}
+/** A silicon analog-input route harvested from an SoC pinctrl file, e.g.
+ *  STM32 `adc1_in1_pa1` (ADC1 channel 1 on PA1). RAW, like DtsPwmPin. */
+export interface DtsAdcPin {
+    /** ADC controller name as written, e.g. 'adc1'. */
+    readonly source: string;
+    /** Input channel number. */
+    readonly channel: number;
+    readonly port: string;
+    readonly bit: number;
+    readonly pinctrl: string;
+}
+/** A silicon analog-OUTPUT route harvested from an SoC pinctrl file, e.g.
+ *  STM32 `dac1_out1_pa4` (DAC1 channel 1 on PA4). RAW, like DtsPwmPin. */
+export interface DtsDacPin {
+    /** DAC controller name as written, e.g. 'dac1' — the DT nodelabel on
+     *  STM32 (dac1: dac@40007400), so it maps straight to the device spec. */
+    readonly source: string;
+    /** Output channel number. */
+    readonly channel: number;
+    readonly port: string;
+    readonly bit: number;
+    readonly pinctrl: string;
+}
+/** A counter-capable device node from the include chain. */
+export interface DtsCounterNode {
+    /** The counter binding's compatible (e.g. 'nordic,nrf-rtc',
+     *  'espressif,esp32-counter') — identifies the driver. */
+    readonly compatible: string;
+    /** Labeled-self form: the node's own nodelabel (nRF rtc1, STM32 rtc).
+     *  Undefined in the child form. */
+    readonly nodeLabel?: string;
+    /** Child form: the labeled TIMER PARENT's nodelabel (ESP32 timer0) — the
+     *  counter device is an unlabeled `counter {}` child; the overlay defines
+     *  the label there. Undefined in the self form. */
+    readonly parentLabel?: string;
+}
+/** A GPIO controller device node reached through the include chain (a node
+ *  carrying the universal `gpio-controller` property). This is the SoC's
+ *  FULL port inventory — the board's own facts only name the ports it
+ *  happens to wire, so without this the pin sweep systematically
+ *  under-reports a board's pads. `ngpios` carries the declared width when
+ *  the dtsi states one (nRF, Atmel, …); families that omit it (STM32) rely
+ *  on the derived port-width conventions. */
+export interface DtsGpioController {
+    readonly nodelabel: string;
+    readonly ngpios?: number;
+}
+/**
+ * Read one board DTS file (following its local include chain) and extract
+ * the board-level facts. `zephyrBoardsRoot` (e.g. <zephyr>/boards) resolves
+ * `<../boards/common/...>` style includes; `moduleDtsRoots` resolve the
+ * vendor HAL modules' pinctrl dtsi (`<st/f4/...-pinctrl.dtsi>` lives under
+ * modules/hal/stm32/dts — Zephyr's MODULE_DTS_ROOTS, mirrored here).
+ */
+export declare function readBoardDts(dtsPath: string, opts?: {
+    zephyrBoardsRoot?: string;
+    moduleDtsRoots?: readonly string[];
+}): DtsBoardFacts;