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

package/dist/toolchain/index.d.ts

@@ -1,4 +1,32 @@
 import type { ToolchainOptions, CompileResult, UploadResult } from '@typecad/cuttlefish/api/shared';
+import type { ZephyrChipDescriptor } from '../chips/types.js';
+/**
+ * Distinct DT-bound sensors the emitted sources reference — the lowering's
+ * state blocks name each one `__tc_sensor_<part>_i2c<N>_0x<addr>_dev`
+ * (lowering/sensor.ts sensorNames), so var-presence is the authoritative
+ * signal. Feeds the overlay's DT child nodes; the part group is greedy so a
+ * compatible containing '_i2c<N>_' still resolves to the longest part match.
+ */
+export interface ScannedSensorPart {
+    part: string;
+    busIndex: number;
+    port: number;
+    busKind: 'i2c' | 'spi';
+    spiHz: number;
+    spiMode: number;
+    alertPin: number;
+}
+export interface ScannedSpiTarget {
+    busIndex: number;
+    cs: number;
+    hz: number;
+    mode: number;
+}
+/** Scan the emitted source for thin SPI targets (hal/spi-target.ts): the
+ *  spi_dt_spec state block's tc-spit-cfg comment carries the construction
+ *  facts, the same channel tc-sensor-cfg uses. */
+export declare function scanSpiTargets(src: string): ScannedSpiTarget[];
+export declare function scanSensorParts(src: string): ScannedSensorPart[];
 /**
  * Derive the Zephyr project root from the cuttlefish-emitted source path.
  *
@@ -26,7 +54,83 @@ export declare function projectRootFromOptions(o: ToolchainOptions): string;
  * Exported (pure) so the runner-selection contract is unit-testable without
  * spawning west.
  */
-export declare function buildFlashArgs(buildDir: string, board: string, userRunner: string | undefined, port: string | undefined, runnerArgs?: readonly string[]): string[];
+/**
+ * Resolve HOW this build attaches to the board for flashing OR debugging:
+ * the friendly `zephyr.probe` id from the board's probeMethods table (quirks
+ * included), or the raw `zephyr.runner` escape hatch. Exported (pure) so the
+ * selection contract is unit-testable without spawning west.
+ *
+ * Rules:
+ * - `probe` + `runner` together is an error (two ways of saying it — pick one).
+ * - An unknown `probe` id is an error listing what the board supports; a board
+ *   with no probeMethods table gets a hint to use `runner` directly.
+ * - purpose 'debug': the chosen method must be debug-capable (`debug` is not
+ *   false — a bootloader is not a debugger). Non-capable or unknown ids list
+ *   the debug-capable methods.
+ * - User `runnerArgs` are appended AFTER the method's args, so they can
+ *   override the method's baked-in flags (argparse takes the last value).
+ */
+export type ProbeResolution = {
+    ok: true;
+    runner?: string;
+    args: string[];
+} | {
+    ok: false;
+    error: string;
+};
+export declare function resolveProbeMethod(zc: Record<string, unknown> | undefined, chip: ZephyrChipDescriptor, purpose?: 'flash' | 'debug'): ProbeResolution;
+/**
+ * Run an openocd session against the board's probe config — the shared
+ * engine for the pre-flash quiesce and the post-flash SYSRESETREQ (see the
+ * call sites in upload()). The config is the probe method's verbatim
+ * debugCfg from the board catalog (the same lines `west debug` uses);
+ * `commands` are appended after `-f <cfg> -c init`. Returns a flash note on
+ * success, undefined when skipped or failed (best-effort by design).
+ */
+/**
+ * Resolve the openocd binary (plus script search dirs) for the probe session.
+ *
+ * Resolution order mirrors how west's own openocd runner finds the binary, so
+ * the session and `west flash` drive the SAME openocd:
+ *   1. $OPENOCD — the variable Zephyr's CMake reads into the build cache.
+ *   2. A Zephyr-SDK-hosted install ($ZEPHYR_SDK_INSTALL_DIR, else the
+ *      discovered west install's SDK). Layout differs by SDK generation —
+ *      hosttools/openocd/share/openocd/scripts vs hosttools/openocd/scripts —
+ *      so both script dirs are collected.
+ *   3. PATH — Linux distro / conda / micromamba installs (a micromamba-env
+ *      openocd is the common Linux setup; the SDK layout check alone made the
+ *      deterministic probe session unreachable there, silently dropping every
+ *      Linux flash to the racy `west flash` fallback).
+ *
+ * A non-SDK binary resolves with no explicit -s dirs: it finds its own
+ * interface/target scripts via its compiled-in search path. Returns undefined
+ * when no openocd can be found (the caller then uses the west fallback).
+ *
+ * Exported (pure) so the resolution contract is unit-testable without
+ * spawning openocd.
+ */
+export interface SessionOpenOcd {
+    readonly exe: string;
+    readonly searchDirs: readonly string[];
+}
+export declare function resolveSessionOpenOcd(env?: {
+    OPENOCD?: string | undefined;
+    ZEPHYR_SDK_INSTALL_DIR?: string | undefined;
+    PATH?: string | undefined;
+}, sdkInstallDir?: string): SessionOpenOcd | undefined;
+/**
+ * Whether a flash runner carries the upload over a serial port. Runner-gated,
+ * never board-name-gated: esptool and bossac are the only runners
+ * `buildFlashArgs` forwards `--port` to, so they are the only ones that
+ * cannot flash without one. Probe runners (openocd, jlink) and USB flows
+ * (dfu-util, uf2 mass storage) need no port — a missing `--port` must not
+ * block them.
+ *
+ * Exported (pure) so the port-requirement contract is unit-testable without
+ * spawning west.
+ */
+export declare function uploadRequiresPort(runner: string | undefined): boolean;
+export declare function buildFlashArgs(buildDir: string, userRunner: string | undefined, port: string | undefined, flashRunner?: string, runnerArgs?: readonly string[]): string[];
 /**
  * Classify a `west flash` result as success/failure.
  *
@@ -46,6 +150,16 @@ export declare function buildFlashArgs(buildDir: string, board: string, userRunn
  * Exported (pure) so the classification is unit-testable without spawning west.
  */
 export declare function classifyUploadResult(runner: string | undefined, status: number | null, output: string): boolean;
+/**
+ * Whether a `west flash` (openocd) output carries one of the known
+ * target-ignored-SWD signatures — the DAP connect failing ("init mode
+ * failed (unable to connect to the target)", i.e. the DPIDR read never
+ * succeeded) or a reset/halt never landing ("timed out while waiting for
+ * target halted" / "TARGET: <name> - Not halted"). Both mean the board (or
+ * probe) needs a power-cycle or the SWD-free DFU path, not a retry of the
+ * same command. Centralized so the upload hint stays testable.
+ */
+export declare function isTargetSwdFailure(output: string): boolean;
 /**
  * Cleanse the `west flash` output shown to the user.
  *