Debug Tools: GDB Toolbox, Core Dump, and Memory Viewer

CodeFusion Studio includes three advanced debugging tools that extend the standard VS Code debug experience with embedded-specific capabilities. The GDB Toolbox automates repetitive GDB command sequences through JSON-defined scripts, letting you capture register dumps, analyze stack usage, or decode fault registers with a single click. The Core Dump Analysis Tool provides retrospective debugging for supported Zephyr-based SoCs, reconstructing the full program state — threads, stack frames, registers, and memory — from a crash dump stored in flash or captured over UART. The CFS Memory Viewer offers a multi-core-aware hex and ASCII grid that reads device memory during live and post-mortem debug sessions and auto-refreshes each time execution halts.

GDB Toolbox

The GDB Toolbox is a scripted automation layer on top of GDB. Rather than typing the same sequence of GDB commands every debugging session, you define the sequence once in a JSON file and run it with a single click from the sidebar. Scripts can read registers, dump memory, analyze threads, walk stack frames, and save formatted reports to the workspace.

Where scripts are stored

When you create a CFS workspace, the extension creates a .cfs/gdb_toolbox/ directory with two subdirectories:

configs/ — JSON script definitions. Each file is one runnable script. Default scripts are pre-populated here.
gdb/ — Optional GDB script files (.gdb) referenced by JSON scripts. These contain raw GDB commands or Python code using the GDB Python API.

User scripts are saved to:

<userHome>/cfs/<cfs_version>/<project_name>/.cfs/gdb_toolbox/configs/

You can also drop scripts manually into this directory — they appear in the GDB Toolbox view automatically the next time a debug session starts.

Built-in scripts

The following default scripts are available in every new CFS workspace. Only scripts compatible with the active core and firmware platform are shown during a session.

Script	Description	Core	Platform
Analyze Crash	Analyzes a crash and generates a JSON report of faulting threads	Core agnostic	Zephyr
Analyze Faults	Reads and decodes fault status registers; prints an ARM fault summary	ARM	MSDK, Zephyr
Analyze Global Heap	Reports total, used, and peak heap usage	Core agnostic	Zephyr
Analyze Stack	Traverses stack frames, prints locals/arguments, and reports used/remaining stack space	Core agnostic	MSDK
Analyze Stack High-water Mark	Reports maximum stack depth using a known fill pattern (run Paint Stack first)	Core agnostic	MSDK
Analyze Threads	Extracts stack usage, register state, and call trace for all active threads	Core agnostic	Zephyr
Dump Memory	Dumps the current memory state to a log file	Core agnostic	MSDK, Zephyr, SHARC-FX
Dump Registers	Dumps the current register state to a log file	Core agnostic	MSDK, Zephyr, SHARC-FX
Interrupt Status	Reads the NVIC state to identify enabled, active, and pending interrupts	ARM	MSDK
Paint Stack	Fills the stack with `0xDEADBEEF` to enable high-water mark analysis	Core agnostic	MSDK

Analyze Threads requires an OpenOCD debug configuration (for example, CFS: Debug with GDB and OpenOCD (Arm Embedded)). J-Link GDB server configurations do not support Zephyr thread awareness, which causes this script to fail when using a J-Link debug configuration.

Accessing the GDB Toolbox

Start a debug session

Click the Run and Debug icon in the Activity Bar, select your configuration, and press F5 (or use the CFS: debug task). The GDB Toolbox panel appears in the sidebar once the session starts.

Pause execution

Set a breakpoint in your application source code and let execution reach it, or use the Pause button to halt the target manually. Scripts only run when the debug session is paused or halted.

Run a script

Click the script name in the GDB Toolbox panel. Output appears in the Debug Console. In multi-core projects, the Debug Console is context-aware — use the dropdown to switch between cores.

Creating and editing scripts

Create a new script

In the GDB Toolbox panel, click Create Script. Enter a name (for example, Dump Stack) and press Enter to generate a template JSON file.

Edit the JSON definition

The template opens in the editor. Define the GDB commands and post-command actions. Save with Ctrl+S / Cmd+S.

Edit an existing script

Hover over a script name in the GDB Toolbox and click the Edit Script pencil icon. The JSON file opens in the editor.

Filter scripts

Click Filter Scripts, enter a name or description, and press Enter. The panel updates to show only matching scripts. Click Clear Filter to restore the full list.

Script JSON reference

Every GDB Toolbox script is a JSON file with the following top-level structure:

{
  "name": "Analyze Faults",
  "description": "Analyzes faults and exceptions...",
  "core": "arm",
  "firmwarePlatform": "zephyr",
  "soc": "MAX32690",
  "commands": [
    {
      "command": "source {defaultScriptsDirectory}/fault-analyzer-arm.gdb",
      "actions": [
        {
          "type": "appendFile",
          "filePath": "gdb_toolbox/reports/${input:filename}.md",
          "content": "${markdownReport}"
        }
      ]
    }
  ],
  "inputs": [
    {
      "id": "filename",
      "type": "inputBox",
      "title": "Log Filename",
      "prompt": "Enter a name for the log file"
    }
  ]
}

Top-level fields:

Field	Type	Required	Description
`name`	string	✅	Display name shown in the GDB Toolbox UI
`description`	string	✅	Tooltip text in the UI
`core`	array	❌	Filters visibility by core type: `arm`, `riscv`
`firmwarePlatform`	string	❌	Filters by platform: `zephyr`, `msdk`
`soc`	string	❌	Filters by SoC name, for example `MAX32690`
`commands`	array	✅	Ordered list of GDB commands and their post-run actions
`inputs`	array	❌	User input prompts referenced by `${input:<id>}` in commands

Action types

Each commands entry may include an actions array that runs after the GDB command completes:

Type	Fields	Description
`log`	`message`	Writes a message to the Debug Console
`writeFile`	`filePath`, `content`	Writes output to a file in the project directory
`appendFile`	`filePath`, `content`	Appends output to an existing file
`showMessage`	`message`, `level`	Displays a VS Code pop-up (`info`, `warning`, or `error`)
`openFile`	`filePath`, `lineNumber`	Opens a file in the editor at the given line
`openDisassembly`	—	Opens the Disassembly view at the current PC
`setVariable`	`name`, `regex`	Extracts a value from GDB output using a capturing regex for reuse
`conditional`	`condition`, `then`, `else`	Runs actions conditionally using a Jexl expression

Script variables

Variable	Description	Supported in
`${gdbOutput}`	Captures the raw output of the current GDB command	`content`, `message`
`${input:<id>}`	Prompts the user for input, referencing an `inputs[]` entry by ID	`command`, `filePath`, `content`
`${markdownReport}`	Inserts a pre-formatted Markdown version of GDB output	`content`
`${timestamp}`	Inserts the current ISO 8601 timestamp	`filePath`, `content`
`${<name>}`	Value previously captured by a `setVariable` action	`filePath`, `content`, `message`, `condition`

Example: run a GDB command and save output to a timestamped log

{
  "name": "Run GDB Command and Save Output",
  "description": "Lets you choose a GDB command and saves the output to a log file.",
  "commands": [
    {
      "command": "${input:command}",
      "actions": [
        {
          "type": "writeFile",
          "filePath": "logs/output_${timestamp}.log",
          "content": "${gdbOutput}"
        }
      ]
    }
  ],
  "inputs": [
    {
      "id": "command",
      "type": "quickPick",
      "title": "Select a Command",
      "prompt": "Choose a command to run:",
      "choices": ["info registers", "info threads", "bt"]
    }
  ]
}

On macOS, the GDB binary used for GDB Toolbox is not Python-enabled by default. Install Python 3.10 and update your launch.json to point to the Python-enabled GDB binary. See the CFS release notes for details.

Core Dump Analysis

The Core Dump Analysis Tool enables post-mortem debugging of Zephyr-based firmware. When your application crashes, Zephyr writes a snapshot of program state to a reserved flash partition. CFS can retrieve that dump over JTAG (J-Link) or decode a UART log capture, then present the results in a structured view showing active threads, register state, stack usage, and memory content at the time of the fault.

Supported processors

Core dump analysis supports the following MAX32 family SoCs running Zephyr RTOS:

MAX32650

MAX32655

MAX32657

MAX32658

MAX32660

MAX32662

MAX32666

MAX32670

MAX32672

MAX32690

MAX78000

MAX78002

Support extends to all processor cores included in these SoCs.

Enabling core dump support

Zephyr workspace template (automatic)
Manual workspace configuration
UART backend (optional)

If you select a Zephyr-based workspace template in the Workspace Creation Wizard, core dump support is enabled by default. The template provides:

A reserved flash partition for storing crash data
Pre-configured prj.conf settings for dump generation and storage

No additional configuration is required.

By default, core dumps are stored in flash and retrieved as binary (.bin) files. To stream the dump over UART instead, add the following to prj.conf:

CONFIG_DEBUG_COREDUMP_BACKEND_LOGGING=y

Capture the UART output (containing #CD: records) with Minicom, Tera Term, or PuTTY. Save the output to a file (for example, coredump.log). CFS automatically decodes the log and converts it to a .bin file when you run Analyze Existing Core Dump.

Configuring core dump settings

Before running the tool, verify that the VS Code settings match your flash partition configuration. Open Settings and search for cfs.coreDump:

Setting	Description	Default
`cfs.coreDump.address`	Flash address where the core dump partition starts	`0x102F0000`
`cfs.coreDump.size`	Size of the core dump partition to retrieve	`0x10000`
`cfs.coreDump.elfFile`	Path to the application ELF file (required for symbol resolution)	—
`cfs.coreDump.binFile`	Path where the retrieved binary dump is saved	`core-dump.bin`
`cfs.coreDump.logFile`	(Optional) Path to a UART log file for UART-backend dumps	—
`cfs.coreDump.gdbServerPort`	GDB server port for analysis (default: 1234 for J-Link)	`1234`

If cfs.coreDump.address and cfs.coreDump.size do not match the flash partition defined in System Planner → Memory Allocation, the tool displays: Core dump analysis failed. Error: Neither Zephyr core dump magic header nor 'ZE' marker found in bin file.Always verify that both the System Planner partition settings and the VS Code settings use matching addresses and sizes.

Retrieving and analyzing a core dump

Trigger a crash

Build and flash your application. To simulate a crash for testing, add k_panic(); to main.c. After the crash, reset or power-cycle the board to ensure the dump is fully written to flash before retrieval.

Open the Core Dump Analysis view

In VS Code, go to the Run and Debug view. The Core Dump Analysis section appears below your debug configurations with four action buttons.

Choose a retrieval method

Retrieve Core Dump (JLink) — Downloads the .bin from the device without opening the analysis view. Connect via J-Link first.
Analyze Existing Core Dump — Opens a previously saved .bin or UART .log file for analysis without connecting to the device.
Retrieve and Analyze Core Dump — Retrieves the dump from flash and immediately opens it in the analysis view. The typical full workflow.
Export Core Dump Report — Packages the current analysis, ELF file, and core dump binary into a ZIP archive for sharing.

Inspect the results

The analysis view shows the program state at crash time: active threads and their stack usage, register values including fault status registers, the faulting address, and a call stack trace to the offending function.

You can also run core dump actions from the Command Palette:

Command	Command Palette Entry
Retrieve Core Dump	`cfs.retrieveCoreDump`
Analyze Existing Core Dump	`cfs.analyzeExistingCoreDump`
Retrieve and Analyze Core Dump	`cfs.retrieveAndAnalyzeCoreDump`
Export Core Dump Report	`cfs.downloadCoreDumpReport`

Memory Viewer

The CFS Memory Viewer is a multi-core-aware alternative to the Memory tab provided by the Cortex-Debug extension. It integrates directly with the CFS debug infrastructure, supports both live and post-mortem (core dump) sessions, and auto-refreshes memory contents each time the debugger halts — without requiring a manual refresh between steps.

Opening the Memory Viewer

The CFS Memory tab appears automatically in the bottom panel when you start a debug session. You can also open it any time via the Command Palette:

Ctrl+Shift+P → CFS Memory: Focus on CFS Memory Viewer View

Navigating to a memory address

In the Go to field in the toolbar, enter an address in hexadecimal (for example, 0x20000000) or decimal format.
Press Enter. The memory grid loads data starting from that address.

If the address is already within the loaded region, the grid scrolls to it without a new fetch. The Go to field displays an inline error if the address is invalid, the session is not active, or the target is currently running.

Memory grid display

The scrollable grid shows three columns:

Address — the hex address of the first byte in each row
Hex values — bytes in the selected format, grouped by the byte grouping setting
ASCII — printable ASCII representation of the same bytes; non-printable characters render as .

The grid uses infinite scroll — as you approach the end of the loaded region, the viewer fetches the next chunk automatically.

Display settings

Configure the grid layout using the footer controls:

Control	Options	Effect
Byte grouping	1 Byte, 2 Bytes, 4 Bytes	Groups bytes into hex cells; cycle by clicking the label
Endianness	Big Endian, Little Endian	Shown when grouping is 2 or 4 bytes
Columns	4, 8, 16, 32, 64	Number of hex cells per row (default: 16)
Display format	Hexadecimal, Decimal	Toggle by clicking the format label

Auto-refresh

Once you navigate to an address, the viewer automatically re-reads memory each time the debugger halts — on every step or breakpoint. When execution resumes (Continue), the viewer marks current data as Stale to indicate the values may no longer reflect the target state. To manually refresh while already halted (for example, after writing a value from the Debug Console), click the Refresh button in the toolbar.

Example: watching a static variable update step by step

Declare a static variable in your source so the compiler assigns it a fixed address in SRAM:

static int count = 0;

With the debugger halted at a breakpoint:

Add &count as a Watch expression, or run print &count in the Debug Console to get the address.
Enter that address in the Go to field.
Set footer to 1 Byte grouping and Decimal display.
Press F10 (Step Over) repeatedly.

The Memory Viewer re-reads the address on each halt. Watch the bytes at count’s address update as the value increments — no manual refresh needed.

Session status indicators

The toolbar shows the following status badges for the active session:

LIVE — connected to a running target
POST-MORTEM — reading from a core dump (read-only mode)
Halted — target is stopped; data is current
Stale — target resumed since last read; data may be out of date

Multi-core support

In multi-core environments, the Memory Viewer tracks all active debug sessions simultaneously. It displays memory for whichever core’s session you select in the Call Stack view, and updates automatically when you switch cores. Each session’s lifecycle (start, halt, continue, stop) is tracked independently.

Error states

State	Viewer message
No debug session	Start a debug session to view memory.
Target running	Halt execution to read memory.
No address entered	Enter an address in ‘Go to’ to inspect target memory.
Invalid address	Inline error in the Go to field
Unmapped address	Read memory error: Unable to read memory
Read timeout (>5 s)	Request is cancelled and an error is displayed

Retrospective debugging

The Memory Viewer works with Core Dump Analysis sessions. When a post-mortem session is open, the POST-MORTEM badge appears and the viewer operates in read-only mode. Enter any valid address in the Go to field to inspect the memory state captured at crash time.

Get Started

Workspace & System Planner

Build, Flash & Debug

Embedded AI

Developer Tools

Documentation Index

​GDB Toolbox

​Where scripts are stored

​Built-in scripts

​Accessing the GDB Toolbox

​Creating and editing scripts

​Script JSON reference

​Action types

​Script variables

​Core Dump Analysis

​Supported processors

MAX32650

MAX32655

MAX32657

MAX32658

MAX32660

MAX32662

MAX32666

MAX32670

MAX32672

MAX32690

MAX78000

MAX78002

​Enabling core dump support

​Configuring core dump settings

​Retrieving and analyzing a core dump

​Memory Viewer

​Opening the Memory Viewer

​Navigating to a memory address

​Memory grid display

​Display settings

​Auto-refresh

​Session status indicators

​Multi-core support

​Error states

​Retrospective debugging

Build docs developers (and LLMs) love

GDB Toolbox

Where scripts are stored

Built-in scripts

Accessing the GDB Toolbox

Creating and editing scripts

Script JSON reference

Action types

Script variables

Core Dump Analysis

Supported processors

Enabling core dump support

Configuring core dump settings

Retrieving and analyzing a core dump

Memory Viewer

Opening the Memory Viewer

Navigating to a memory address

Memory grid display

Display settings

Auto-refresh

Session status indicators

Multi-core support

Error states

Retrospective debugging