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

package/src/doctor.ts

@@ -1,77 +1,110 @@
-// ---------------------------------------------------------------------------
-// @typecad/framework-zephyr — Zephyr environment doctor
-//
-// `cuttlefish doctor` (Zephyr framework) — verify west (the Zephyr build tool)
-// is installed + responsive, the Zephyr RTOS is inside the framework's declared
-// compat range, and the configured board target exists in the checkout. Exits 0
-// if the environment is OK, non-zero otherwise. Mirrors framework-arduino's
-// doctor shape (dispatched via the framework's `doctor` export) and reuses
-// checkZephyrEnv so the detection logic can be shared with the build/test gates.
-// ---------------------------------------------------------------------------
-
-import * as ui from '@typecad/cuttlefish/utils/ui';
-import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
-import { checkZephyrEnv } from './toolchain/env-check.js';
-
-/**
- * Verify west is installed + responsive, the Zephyr RTOS is inside the supported
- * range, and the configured board target exists in the checkout. Sets
- * process.exitCode = 1 on failure. Thin presenter over checkZephyrEnv.
- */
-export function runDoctor(): void {
-  ui.printHeader();
-  ui.printStep('Checking Zephyr environment...');
-
-  const config = loadCuttlefishConfig(process.cwd());
-  const buildTarget = config?.buildTarget;
-
-  const result = checkZephyrEnv(buildTarget);
-  const c = result.check;
-
-  // west (the Zephyr build tool) — the analog of arduino-cli presence.
-  if (c.westFound) {
-    const ver = c.westVersion ?? 'found';
-    const src = c.westSource ? `  (${c.westSource})` : '';
-    ui.printInfo(`west ............. ${ver}  ✓${src}`);
-  } else {
-    ui.printError('west ............. NOT FOUND');
-  }
-
-  // Zephyr RTOS version + declared compat range.
-  ui.printInfo(`ZEPHYR_BASE ...... ${c.zephyrBase ?? '(not set)'}`);
-  ui.printInfo(`Zephyr version .. ${c.zephyrVersion ?? 'unknown (could not read ZEPHYR_BASE/VERSION)'}`);
-  ui.printInfo(`Supported range . ${c.compatRange ?? '(none declared)'}`);
-
-  if (c.compatStatus === 'out-of-range') {
-    ui.printError(`Zephyr ${c.zephyrVersion} is OUTSIDE the supported range (${c.compatRange}).`);
-  } else if (c.compatStatus === 'undetectable') {
-    ui.printWarning('Could not detect the Zephyr version (is ZEPHYR_BASE set?) — compat check skipped.');
-  } else {
-    ui.printInfo('Zephyr compat ... OK');
-  }
-
-  // Board target — the analog of the Arduino core presence check.
-  if (buildTarget) {
-    const resolved = c.resolvedBoardTarget ?? buildTarget;
-    const arrow = resolved === buildTarget ? '' : ` → ${resolved}`;
-    if (c.boardTargetSupported === false) {
-      ui.printError(`Board target .... ${buildTarget}${arrow}  NOT found in this Zephyr checkout`);
-      ui.printInfo('  → check the board id, or run: west boards');
-    } else if (c.boardTargetSupported === undefined) {
-      ui.printInfo(`Board target .... ${buildTarget}${arrow}`);
-      ui.printInfo('(could not verify board presence — no ZEPHYR_BASE boards/ tree found)');
-    } else {
-      ui.printInfo(`Board target .... ${buildTarget}${arrow}`);
-    }
-  } else {
-    ui.printInfo('(no buildTarget in cuttlefish.config.ts — skipping board check)');
-  }
-
-  // Exit code — mirrors framework-arduino's doctor.
-  if (result.ok) {
-    ui.printSuccess('Environment OK');
-    return; // exitCode stays unset => 0
-  }
-  for (const line of result.messages) ui.printInfo(line);
-  process.exitCode = 1;
-}
+// ---------------------------------------------------------------------------
+// @typecad/framework-zephyr — Zephyr environment doctor
+//
+// `cuttlefish doctor` (Zephyr framework) — verify west (the Zephyr build tool)
+// is installed + responsive, the Zephyr RTOS is inside the framework's declared
+// compat range, and the configured board target exists in the checkout. Exits 0
+// if the environment is OK, non-zero otherwise. Follows the same contract
+// doctor shape (dispatched via the framework's `doctor` export) and reuses
+// checkZephyrEnv so the detection logic can be shared with the build/test gates.
+// ---------------------------------------------------------------------------
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import * as ui from '@typecad/cuttlefish/utils/ui';
+import { loadCuttlefishConfig } from '@typecad/cuttlefish/config-loader';
+import { checkZephyrEnv } from './toolchain/env-check.js';
+import { PINNED_ZEPHYR_MANIFEST_REV, PINNED_ZEPHYR_SDK_VERSION, sdkFingerprint } from '@typecad/cuttlefish/board-catalog';
+import { resolveChipFromBoard } from './chips/resolve.js';
+
+/**
+ * Verify west is installed + responsive, the Zephyr RTOS is inside the supported
+ * range, and the configured board target exists in the checkout. Sets
+ * process.exitCode = 1 on failure. Thin presenter over checkZephyrEnv.
+ */
+export function runDoctor(): void {
+  ui.printHeader();
+  ui.printStep('Checking Zephyr environment...');
+
+  const config = loadCuttlefishConfig(process.cwd());
+  const buildTarget = config?.buildTarget;
+
+  const result = checkZephyrEnv(buildTarget);
+  const c = result.check;
+
+  // west (the Zephyr build tool) presence.
+  if (c.westFound) {
+    const ver = c.westVersion ?? 'found';
+    const src = c.westSource ? `  (${c.westSource})` : '';
+    ui.printInfo(`west ............. ${ver}  ✓${src}`);
+  } else {
+    ui.printError('west ............. NOT FOUND');
+  }
+
+  // Zephyr RTOS version + declared compat range.
+  ui.printInfo(`ZEPHYR_BASE ...... ${c.zephyrBase ?? '(not set)'}`);
+  ui.printInfo(`Zephyr version .. ${c.zephyrVersion ?? 'unknown (could not read ZEPHYR_BASE/VERSION)'}`);
+  ui.printInfo(`Workspace pin ... ${PINNED_ZEPHYR_MANIFEST_REV} (SDK ${PINNED_ZEPHYR_SDK_VERSION})`);
+  const fp = c.zephyrBase ? sdkFingerprint(c.zephyrBase) : undefined;
+  ui.printInfo(`SDK fingerprint . ${fp ?? '(no tree — run ' + 'npx --package @typecad/framework-zephyr zephyr-installer)'}`);
+  ui.printInfo(`Supported range . ${c.compatRange ?? '(none declared)'}`);
+
+  if (c.compatStatus === 'out-of-range') {
+    ui.printError(`Zephyr ${c.zephyrVersion} is OUTSIDE the supported range (${c.compatRange}).`);
+  } else if (c.compatStatus === 'undetectable') {
+    ui.printWarning('Could not detect the Zephyr version (is ZEPHYR_BASE set?) — compat check skipped.');
+  } else {
+    ui.printInfo('Zephyr compat ... OK');
+  }
+
+  // Board target availability.
+  if (buildTarget) {
+    const resolved = c.resolvedBoardTarget ?? buildTarget;
+    const arrow = resolved === buildTarget ? '' : ` → ${resolved}`;
+    if (c.boardTargetSupported === false) {
+      ui.printError(`Board target .... ${buildTarget}${arrow}  NOT found in this Zephyr checkout`);
+      ui.printInfo('  → check the board id, or run: west boards');
+    } else if (c.boardTargetSupported === undefined) {
+      ui.printInfo(`Board target .... ${buildTarget}${arrow}`);
+      ui.printInfo('(could not verify board presence — no ZEPHYR_BASE boards/ tree found)');
+    } else {
+      ui.printInfo(`Board target .... ${buildTarget}${arrow}`);
+    }
+  } else {
+    ui.printInfo('(no buildTarget in cuttlefish.config.ts — skipping board check)');
+  }
+
+  // Probe methods — from the board package's table, via the board constants
+  // the transpile persists (candidates cover the standard out-dir layouts).
+  // The debug line lists the debug-capable subset (bootloaders can't debug).
+  if (buildTarget) {
+    const bcPath = [
+      join(process.cwd(), 'out', 'src', 'board-constants.json'),
+      join(process.cwd(), 'out', 'board-constants.json'),
+      join(process.cwd(), 'src', 'out', 'src', 'board-constants.json'),
+      join(process.cwd(), 'src', 'out', 'board-constants.json'),
+    ].find((p) => existsSync(p));
+    if (bcPath) {
+      try {
+        const raw = JSON.parse(readFileSync(bcPath, 'utf8')) as Record<string, string | number | boolean>;
+        const chip = resolveChipFromBoard(new Map(Object.entries(raw)));
+        const methods = chip?.probeMethods ?? [];
+        if (methods.length > 0) {
+          ui.printInfo(`Probe methods .... ${methods.map((m) => m.id).join(', ')}  (zephyr.probe / --probe)`);
+          const debuggable = methods.filter((m) => m.debug !== false).map((m) => m.id);
+          ui.printInfo(`Debug methods .... ${debuggable.join(', ') || '(none — an external probe is required)'}`);
+        }
+      } catch { /* best-effort listing */ }
+    } else {
+      ui.printInfo('Probe methods .... (build once to list them)');
+    }
+  }
+
+  // Exit code — 0 ok, non-zero otherwise.
+  if (result.ok) {
+    ui.printSuccess('Environment OK');
+    return; // exitCode stays unset => 0
+  }
+  for (const line of result.messages) ui.printInfo(line);
+  process.exitCode = 1;
+}

package/src/dt-config/custom-board.ts

@@ -0,0 +1,325 @@
+// ---------------------------------------------------------------------------
+// Custom board generation — an out-of-tree Zephyr board for an MCU-only target
+//
+// When a project targets an MCU package with no board package (`mcu:` set,
+// `board:` absent) there may be no Zephyr board for the user's hardware. The
+// chip descriptor's `customBoard` block (silicon facts from the MCU package:
+// SoC name, devicetree includes, default console mux, default clock plan) is
+// all a minimal HWMv2 board needs, so we generate one into the project:
+//
+//   boards/typecad/<name>/board.yml       — board + SoC declaration
+//   boards/typecad/<name>/<name>.dts      — includes, chosen, console, clocks
+//   boards/typecad/<name>/Kconfig.<name>  — BOARD_<NAME> symbol selecting the SoC
+//   boards/typecad/<name>/<name>_defconfig— baseline (GPIO + console) every
+//                                           in-tree board carries
+//
+// The app's CMakeLists.txt adds the project root to BOARD_ROOT (see
+// toolchain/scaffold.ts), so Zephyr discovers the board without touching the
+// checkout. Everything else (buses, ADC, PWM, USB) stays usage-driven: the
+// overlay generator keeps layering `boards/<name>.overlay` on top exactly as
+// it does for upstream boards.
+//
+// Verified against Zephyr 4.3/4.4 (HWMv2): a minimal board is exactly these
+// four files — Kconfig.<name> + CONFIG_GPIO=y are load-bearing (a board
+// without them fails with "ARCH not defined" / gpio link errors).
+// ---------------------------------------------------------------------------
+
+import { mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+import { writeIfChanged } from '../toolchain/scaffold.js';
+
+/** The vendor segment of the generated board path + board.yml. */
+const CUSTOM_BOARD_VENDOR = 'typecad';
+
+/**
+ * Sanitize a raw name into a legal Zephyr board name: lowercase, `[a-z0-9_]`
+ * (dashes/dots/spaces collapse to underscores, leading/trailing underscores
+ * trimmed). Board names become C identifiers in Kconfig symbols, so anything
+ * stricter would break `config BOARD_<NAME>`.
+ */
+export function sanitizeBoardName(raw: string): string {
+  const cleaned = raw
+    .toLowerCase()
+    .replace(/[^a-z0-9_]+/g, '_')
+    .replace(/^_+|_+$/g, '');
+  return cleaned.length > 0 ? cleaned : 'custom_board';
+}
+
+/** Kconfig symbol fragment: `cb_f411` → `CB_F411`. */
+function kconfigFragment(name: string): string {
+  return name.toUpperCase();
+}
+
+/** Generated-board file set, all under `<projectRoot>/boards/typecad/<name>/`. */
+export interface GeneratedCustomBoard {
+  /** Absolute directory of the generated board. */
+  dir: string;
+  /** The sanitized board name (the `west build -b` argument). */
+  name: string;
+  /** Whether any file changed (idempotent regeneration signal). */
+  changed: boolean;
+}
+
+/**
+ * Emit the custom board for a chip whose descriptor carries `customBoard`
+ * silicon data. No-op (returns null) when the chip has no generator inputs —
+ * board-resolved chips don't need one.
+ */
+export function generateCustomBoard(
+  projectRoot: string,
+  chip: ZephyrChipDescriptor,
+  rawName: string,
+): GeneratedCustomBoard | null {
+  const cb = chip.customBoard;
+  if (!cb) return null;
+
+  const name = sanitizeBoardName(rawName);
+  const soc = cb.socs[0];
+  if (!soc) return null;
+
+  const dir = join(projectRoot, 'boards', CUSTOM_BOARD_VENDOR, name);
+  mkdirSync(dir, { recursive: true });
+
+  let changed = false;
+
+  // ── board.yml ────────────────────────────────────────────────────────────
+  changed =
+    writeIfChanged(
+      join(dir, 'board.yml'),
+      [
+        '# Auto-generated by @typecad/framework-zephyr from the MCU package',
+        '# silicon definition. Regenerated on every compile — edit the MCU',
+        '# package (or add a board package) instead of this file.',
+        'board:',
+        `  name: ${name}`,
+        `  full_name: Cuttlefish custom board (${chip.soc})`,
+        `  vendor: ${CUSTOM_BOARD_VENDOR}`,
+        '  socs:',
+        `    - name: ${soc}`,
+        '',
+      ].join('\n'),
+    ) || changed;
+
+  // ── Kconfig.<name> — the board symbol selecting the SoC ─────────────────
+  // Load-bearing: without the BOARD_<NAME> symbol selecting SOC_<SOC>, Kconfig
+  // completes with no SoC and the build dies with "ARCH not defined".
+  changed =
+    writeIfChanged(
+      join(dir, `Kconfig.${name}`),
+      [
+        '# Auto-generated by @typecad/framework-zephyr. Do not edit.',
+        '',
+        `config BOARD_${kconfigFragment(name)}`,
+        `\tselect SOC_${kconfigFragment(soc)}`,
+        '',
+      ].join('\n'),
+    ) || changed;
+
+  // ── <name>.dts — includes, chosen, console, clock plan ───────────────────
+  const lines: string[] = [
+    '// Auto-generated by @typecad/framework-zephyr from the MCU package',
+    '// silicon definition. Regenerated on every compile — edit the MCU',
+    '// package (or add a board package) instead of this file.',
+    '/dts-v1/;',
+    ...cb.dtsIncludes.map((inc) => `#include <${inc}>`),
+    '',
+    '/ {',
+    `	model = "Cuttlefish custom board (${chip.soc})";`,
+    `	compatible = "${CUSTOM_BOARD_VENDOR},${name.replace(/_/g, '-')}";`,
+    '',
+    '	chosen {',
+    `		zephyr,console = &${cb.console.nodeLabel};`,
+    '		zephyr,sram = &sram0;',
+    '		zephyr,flash = &flash0;',
+    '	};',
+    '};',
+    '',
+  ];
+
+  // The chip descriptor's DT-aliased GPIOs (sw0/led0 from the reference
+  // board data): the generated firmware addresses them via DT_ALIAS, so the
+  // custom board must define the nodes. Pins map through gpioControllers
+  // (port-block numbering: pin = minPin + port bit).
+  const controllerFor = (pin: number): { label: string; bit: number } | undefined => {
+    const c = chip.gpioControllers?.find((c) => pin >= c.minPin && pin <= c.maxPin);
+    if (c) return { label: c.nodelabel, bit: pin - c.minPin };
+    return undefined;
+  };
+  const keys = chip.gpio.dtSpecs.filter((s) => s.dtSpec.startsWith('sw') || s.dtSpec.startsWith('button'));
+  const leds = chip.gpio.dtSpecs.filter((s) => s.dtSpec.startsWith('led'));
+  if (keys.length > 0 || leds.length > 0) {
+    lines.push('/ {');
+    if (leds.length > 0) {
+      lines.push('	leds {', '		compatible = "gpio-leds";');
+      for (const l of leds) {
+        const c = controllerFor(l.pin);
+        if (!c) continue;
+        lines.push(
+          `		${l.dtSpec}_node: ${l.dtSpec.replace(/_/g, '-')} {`,
+          `			gpios = <&${c.label} ${c.bit} GPIO_ACTIVE_LOW>;`,
+          '		};',
+        );
+      }
+      lines.push('	};');
+    }
+    if (keys.length > 0) {
+      lines.push('	gpio_keys {', '		compatible = "gpio-keys";');
+      for (const k of keys) {
+        const c = controllerFor(k.pin);
+        if (!c) continue;
+        lines.push(
+          `		${k.dtSpec}_node: ${k.dtSpec.replace(/_/g, '-')} {`,
+          `			gpios = <&${c.label} ${c.bit} (GPIO_ACTIVE_LOW | GPIO_PULL_UP)>;`,
+          '		};',
+        );
+      }
+      lines.push('	};');
+      lines.push('	aliases {');
+      for (const k of keys) lines.push(`		${k.dtSpec} = &${k.dtSpec}_node;`);
+      for (const l of leds) lines.push(`		${l.dtSpec} = &${l.dtSpec}_node;`);
+      lines.push('	};');
+    }
+    lines.push('};', '');
+  }
+
+  lines.push(
+    // Console UART — the one controller the board enables unconditionally;
+    // every other bus is enabled by the usage-driven overlay.
+    `&${cb.console.nodeLabel} {`,
+    `	pinctrl-0 = <&${cb.console.tx} &${cb.console.rx}>;`,
+    '	pinctrl-names = "default";',
+    '	status = "okay";',
+    `	current-speed = <${cb.console.speed}>;`,
+    '};',
+    '',
+  );
+
+  // USB: alias the silicon node under the Zephyr convention the descriptor's
+  // usb.controller names (e.g. zephyr_udc0: &usbotg_fs), pre-enabled with its
+  // pinctrl — the st,stm32-otgfs binding requires pinctrl-0 on an enabled
+  // node, and the overlay's CDC composition only flips status/enables the
+  // stack (Kconfig-gated), never pins. Mirrors the blackpill board shape.
+  if (cb.usbNode && chip.usb) {
+    lines.push(
+      `${chip.usb.controller}: &${cb.usbNode} {`,
+      ...(cb.usbPinctrl && cb.usbPinctrl.length > 0
+        ? [
+          `	pinctrl-0 = <${cb.usbPinctrl.map((p) => `&${p}`).join(' ')}>;`,
+          '	pinctrl-names = "default";',
+        ]
+        : []),
+      '	status = "okay";',
+      '};',
+      '',
+    );
+  }
+
+  // PWM: the overlay enables `&pwm<N>` and synthesizes pwm-leds consumers
+  // against it — but the pwm<N> LABEL only exists when a board DTS declares
+  // it (the SoC dtsi ships the timers' pwm child unlabeled), and the
+  // st,stm32-pwm binding requires pinctrl-0 on an enabled node. Emit the
+  // blackpill-shape block per controller whose specs all carry pinctrl
+  // tokens; controllers without full token coverage stay to board packages.
+  if (chip.pwm) {
+    const byController = new Map<string, { n: string; tokens: string[]; complete: boolean }>();
+    for (const s of chip.pwm.specs) {
+      if (!s.controller) continue;
+      const timersMatch = s.controller.match(/^pwm(\d+)$/);
+      if (!timersMatch) continue;
+      const entry = byController.get(s.controller) ?? { n: timersMatch[1], tokens: [], complete: true };
+      if (s.pinctrl) {
+        entry.tokens.push(s.pinctrl);
+      } else {
+        entry.complete = false;
+      }
+      byController.set(s.controller, entry);
+    }
+    for (const [controller, entry] of byController) {
+      if (!entry.complete || entry.tokens.length === 0) continue;
+      lines.push(
+        `&timers${entry.n} {`,
+        '	status = "okay";',
+        '',
+        `	${controller}: pwm {`,
+        `		pinctrl-0 = <${entry.tokens.map((t) => `&${t}`).join(' ')}>;`,
+        '		pinctrl-names = "default";',
+        '		status = "okay";',
+        '	};',
+        '};',
+        '',
+      );
+    }
+  }
+
+  // ADC: some SoC drivers require board-DTS properties on an enabled adc node
+  // (STM32 F4: st,adc-clock-source + st,adc-prescaler, or the binding rejects
+  // the node when the usage-driven overlay enables it). Pre-enable with the
+  // silicon-required props + a baseline pinctrl; the overlay rewrites
+  // pinctrl-0 to the channels the program actually reads.
+  if (cb.adcNode) {
+    const a = cb.adcNode;
+    lines.push(
+      `&${a.nodeLabel} {`,
+      `	pinctrl-0 = <&${a.pinctrl}>;`,
+      '	pinctrl-names = "default";',
+      `	st,adc-clock-source = "${a.clockSource}";`,
+      `	st,adc-prescaler = <${a.prescaler}>;`,
+      '	status = "okay";',
+      '};',
+      '',
+    );
+  }
+
+  // Clock plan — STM32 F4 shape today (the only family carrying a clocks
+  // block so far): HSE crystal, PLL, RCC prescalers. SoCs whose dtsi clocks
+  // work out of the box ship no clocks block and emit nothing here.
+  const clk = cb.clocks;
+  lines.push(
+    `&clk_hse {`,
+    `	clock-frequency = <DT_FREQ_M(${clk.hseMHz})>;`,
+    '	status = "okay";',
+    '};',
+    '',
+    '&pll {',
+    `	div-m = <${clk.pll.divM}>;`,
+    `	mul-n = <${clk.pll.mulN}>;`,
+    `	div-p = <${clk.pll.divP}>;`,
+    `	div-q = <${clk.pll.divQ}>;`,
+    '	clocks = <&clk_hse>;',
+    '	status = "okay";',
+    '};',
+    '',
+    '&rcc {',
+    '	clocks = <&pll>;',
+    `	clock-frequency = <DT_FREQ_M(${clk.sysMHz})>;`,
+    `	ahb-prescaler = <${clk.ahbPrescaler}>;`,
+    `	apb1-prescaler = <${clk.apb1Prescaler}>;`,
+    `	apb2-prescaler = <${clk.apb2Prescaler}>;`,
+    '};',
+    '',
+  );
+
+  changed = writeIfChanged(join(dir, `${name}.dts`), lines.join('\n')) || changed;
+
+  // ── <name>_defconfig — the baseline every in-tree board carries ──────────
+  // Load-bearing: without CONFIG_GPIO the STM32 pinctrl driver's gpio_ports
+  // table references devices that are never built (undefined __device_dts_ord
+  // at link). Console/serial match what the DTS enables.
+  changed =
+    writeIfChanged(
+      join(dir, `${name}_defconfig`),
+      [
+        '# Auto-generated by @typecad/framework-zephyr. Do not edit.',
+        '',
+        'CONFIG_GPIO=y',
+        'CONFIG_SERIAL=y',
+        'CONFIG_CONSOLE=y',
+        'CONFIG_UART_CONSOLE=y',
+        '',
+      ].join('\n'),
+    ) || changed;
+
+  return { dir, name, changed };
+}