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

package/dist/toolchain/debug-config.d.ts

@@ -1,3 +1,10 @@
+/** The gdb server port west's openocd/jlink runners default to. */
+export declare const DEBUG_SERVER_PORT = 3333;
+/** west's openocd tcl port — pinned in the debugserver invocation and used
+ *  as the READINESS probe: its listener opens at the END of openocd's init
+ *  (after the gdb listener and the startup halt), and probe connections
+ *  there never consume the gdb server's single client slot. */
+export declare const DEBUG_SERVER_TCL_PORT = 6333;
 export interface DebugConfigOptions {
     /** Absolute path to the Zephyr project root (contains CMakeLists.txt + src/). */
     projectRoot: string;
@@ -11,108 +18,61 @@ export interface DebugConfigOptions {
     buildDir: string;
     /** Absolute path to the emitted source map (*.thcppmap.json), if any. */
     sourceMapPath?: string;
+    /**
+     * Create-time best-effort gdb (from the SDK + the board's silicon) — used
+     * only when runners.yaml doesn't exist yet (pre-first-build). The first
+     * build's west-resolved gdb replaces it, and a mismatch triggers the
+     * artifact rewrite (debugArtifactsNeedRewrite).
+     */
+    starterGdbPath?: string;
 }
-/**
- * Resolve the GDB binary path for the target from the build cache, falling
- * back to a filesystem scan of known Zephyr SDK locations when no build
- * exists yet (the create-time starter artifacts path). Zephyr records
- * ZEPHYR_SDK_INSTALL_DIR in CMakeCache.txt at configure time, and the
- * xtensa GDB lives at <sdk>/xtensa-espressif_esp32s3_zephyr-elf/bin/... (note
- * the Zephyr-SDK naming, distinct from the ESP-IDF xtensa-esp32s3-elf-gdb).
- *
- * Returns the absolute gdb path on success, or undefined (the launch.json then
- * omits gdbPath and relies on Cortex-Debug's default resolution).
- */
-export declare function resolveGdbPath(buildDir: string, target: string): string | undefined;
-/** The GDB location inside a Zephyr SDK root, per target architecture:
- *  ARM boards use the arm-zephyr-eabi toolchain (verified against
- *  zephyr-sdk-0.17.4), Espressif the xtensa-espressif_esp32s3_zephyr-elf one.
- *  Returns a forward-slash absolute path or undefined. */
-export declare function gdbPathFromSdkRoot(sdkRoot: string, target?: string): string | undefined;
-/**
- * Probe the well-known Zephyr SDK install locations, newest version first:
- *   1. $ZEPHYR_SDK_INSTALL_DIR (the var board.cmake reads)
- *   2. <MAMBA_ROOT_PREFIX | ~/micromamba>/zephyr-sdk/zephyr-sdk-<ver> — the
- *      the bundled Zephyr installer layout
- *   3. ~/zephyr-sdk-<ver> — the standalone download layout
- *
- * Only roots that actually contain the esp32s3 GDB are useful to callers;
- * this returns candidate roots (gdbPathFromSdkRoot does the existence check)
- * so tests can inject home/env overrides.
- */
-export declare function discoverZephyrSdkRoots(opts?: {
-    home?: string;
-    env?: Record<string, string | undefined>;
-}): string[];
-/**
- * Resolve the OpenOCD binary path. The esp32s3 needs the Espressif OpenOCD
- * fork (openocd-esp32) — not the Zephyr SDK's openocd and not a
- * generic/GDB-stub build — because only it carries the Xtensa + esp_usb_jtag
- * support. ARM targets prefer the Zephyr SDK's own openocd (it ships the
- * interface/target cfgs boards reference); the Espressif fork is only
- * consulted for esp32 targets.
- *
- * Discovery order:
- *   1. ESPRESSIF_TOOLCHAIN_PATH env (the var board.cmake reads) — esp32
- *      targets; its openocd-esp32/bin/openocd.exe.
- *   2. The standard ESP-IDF install layout: ~/.espressif/tools/openocd-esp32/
- *      <version>/openocd-esp32/bin/openocd.exe (esp32 targets; newest first).
- *   3. A Zephyr SDK root (discoverZephyrSdkRoots) — its
- *      tools/opt/openocd/bin/openocd(.exe), any target.
- * Returns undefined if not found (the launch.json then omits openOCDPath and
- * Cortex-Debug falls back to PATH / its openocdPath setting).
- */
-export declare function resolveOpenOcdPath(target?: string): string | undefined;
-/**
- * Resolve where to write the VS Code debug artifacts and how to express paths
- * in them.
- *
- * VS Code reads `.vscode/` from the folder the user has OPENED — and for a
- * cuttlefish project that is almost always the **cuttlefish project root**
- * (the directory containing `cuttlefish.config.ts`), NOT the git repo root.
- * The toolchain's `projectRoot` is the Zephyr *app* dir (e.g.
- * `<projectRoot>/src/out`), which sits below the cuttlefish config dir. So we
- * walk up from `projectRoot` to the nearest `cuttlefish.config.ts` and treat
- * THAT as the workspace root. This makes F5 work when a user opens the project
- * folder directly, and keeps launch.json paths relative to it.
- *
- * Returns { workspaceRoot, appRel } where workspaceRoot is the cuttlefish
- * project root (the `.vscode/` target) and appRel is the Zephyr app dir
- * (`projectRoot`) relative to it (e.g. 'src/out').
- */
+/** Task labels (also the preLaunchTask/postDebugTask references in launch.json). */
+export declare const DEBUG_BUILD_TASK = "typecad-hal: build + flash (debug)";
+export declare const DEBUG_SERVER_TASK = "typecad-hal: debug server (west)";
+export declare const DEBUG_SERVER_STOP_TASK = "typecad-hal: stop debug server";
 export declare function resolveDebugLocations(projectRoot: string): {
     workspaceRoot: string;
     appRel: string;
 };
 /**
- * Generate the GDB Python frame-filter that rewrites cuttlefish's hoisted
- * lambda frame names (`${prefix}_isr_N`) into readable `<lambda> @ file:line`
- * in the call stack. Only emitted when the source map references `_isr_N`
- * symbols; otherwise returns null (launch.json omits the `source` initCommand).
- *
- * Ported verbatim from the deleted framework-esp32/toolchain/gdb-script.ts —
- * the filter is cuttlefish-internal (lambda hoisting is framework-agnostic).
+ * Whether the workspace's gdb debug artifacts need rewriting: missing, still
+ * in an older (self-managed-server) shape, written before a build resolved
+ * the gdb path (the create-time starter omits gdbPath), or referencing an app
+ * root other than the current one (an outDir rename). Only OUR entries count
+ * (`TypeCAD Debug (Zephyr, …)`); user-authored ones are never judged.
  */
-export declare function generateGdbScript(sourceMapPath?: string): string | null;
-export declare function writeDebugConfig(o: DebugConfigOptions): void;
+export declare function debugArtifactsNeedRewrite(workspaceRoot: string, appRel: string, currentGdb?: string): boolean;
 /**
- * Create-time starter debug artifacts. Called by the cuttlefish `create` flow
- * (via the package's `writeProjectDebugArtifacts` export) so a fresh project
- * has a working F5 before any build exists:
- *
- * The launch.json's preLaunchTask runs `cuttlefish build --compile --upload
- * --debug`, which builds + flashes AND rewrites this same launch entry (merged
- * by name) with the CMakeCache-resolved gdbPath — so the starter files upgrade
- * themselves on the first debug build.
- *
- * No-ops (returns []) for targets without native GDB support (debugMode() !==
- * 'gdb'); the gdb frame-filter script is skipped (no source map exists yet).
+ * Write the debug artifacts: the cortex-debug launch entry (merged by name)
+ * and the three tasks (merged by label). Returns the workspace-relative
+ * paths written, for CLI reporting.
+ */
+export declare function writeDebugConfig(o: DebugConfigOptions): string[];
+/**
+ * Create-time starter debug artifacts: the same west-driven launch entry and
+ * tasks, minus gdbPath (no build exists yet — runners.yaml is absent). The
+ * first build upgrades the entry (debugArtifactsNeedRewrite fires on the
+ * missing gdbPath), so F5 after a compile is fully resolved.
  *
- * Returns the workspace-relative paths written, for CLI reporting.
+ * No-ops (returns []) for targets without gdb debug facts (no debug-capable
+ * probe method in the board's table — printf instrumentation territory).
  */
 export declare function writeProjectDebugArtifacts(o: {
-    /** Absolute path to the cuttlefish project root (contains cuttlefish.config.ts). */
+    /** Absolute path to the typecad-hal project root (contains typecad-hal.config.ts). */
     workspaceRoot: string;
     /** The Zephyr board id from the project config (frameworkData.buildTarget). */
     buildTarget?: string;
+    /**
+     * The scaffolded app dir, workspace-relative with forward slashes.
+     * Defaults to the standard layout ('src/out'); typecad-hal create passes
+     * its config's actual entry + outDir resolution so a non-standard scaffold
+     * still gets correct starter paths.
+     */
+    appRel?: string;
+    /**
+     * Create-time best-effort gdb from typecad-hal create (SDK + silicon) —
+     * see DebugConfigOptions.starterGdbPath. Plain JSON string.
+     */
+    gdbPath?: string;
 }): string[];
+export declare function generateGdbScript(sourceMapPath?: string): string | null;