Connect to a running TRACE32 PowerView instance.

Args: node: TRACE32 host address (default from config or 'localhost') port: TRACE32 API port (default from config or 20000) protocol: Communication protocol - TCP or UDP (default from config or 'TCP')

Returns: Connection status message with TRACE32 version info

Disconnect from TRACE32 PowerView.

Returns: Disconnection confirmation message

Get current connection status and TRACE32 system information.

Returns: Connection state, TRACE32 version, and target CPU state

Get the current call stack (backtrace) with function names and arguments.

The target must be halted. Shows the complete call chain from the current function up to the entry point, including function arguments and source context.

Returns: Formatted call stack with frame numbers, function names, and arguments

Get the call stack with all local variables for each frame.

The target must be halted. Shows local variable names and values for every function in the call stack. Useful for understanding program state at the point of a breakpoint or crash.

Returns: Call stack with local variables expanded per frame

Get a formatted memory dump (hex + ASCII) from the target.

Similar to TRACE32's Data.dump window. Shows memory contents in the standard hex dump format with address, hex values, and ASCII representation.

Args: address: Start address (e.g., "0xD0000000", "D:0x80000000") length: Number of bytes to dump (default: 256) width: Access width in bits — 8, 16, 32, or 64 (default: 32)

Returns: Formatted hex dump with addresses, hex values, and ASCII

View a C/C++ variable, structure, array, or expression with full expansion.

Shows the complete content of complex data types including nested structs, arrays, and pointer targets. Much more detailed than read_variable.

The target must be halted.

Args: expression: C variable name, struct member, array, or expression (e.g., "myStruct", "array[0]", "pTask->state", "%SpotLight")

Returns: Formatted variable view showing all fields and values

Get the full register view with all CPU registers and flags.

Shows all registers organized by type (data, address, system) with flags decoded. More comprehensive than read_register/read_registers.

Returns: Complete formatted register dump including flags and special registers

Get the text content of any TRACE32 window command.

This is the most flexible view tool — any TRACE32 command that produces a window can have its content retrieved. Use this for specialized views not covered by other tools.

Examples: - "Data.List" — disassembly listing - "Var.Watch" — variable watch window - "Frame.view /Locals /ALL" — all frames with locals - "Trace.List" — trace buffer contents - "TASK.List" — OS task/thread list

Args: command: TRACE32 window command (e.g., "Data.List", "Var.Watch")

Returns: Formatted text content of the specified window

Start or continue program execution on the target.

Returns: Confirmation that execution was started

Single-step program execution.

Args: mode: Step mode — "into" (step into functions), "over" (step over), "out" (step out of current function)

Returns: New program counter address after step

Stop (break) program execution on the target.

Returns: CPU state after halting

Reset the target CPU.

Returns: Confirmation of reset

Get the current CPU/target execution state.

Returns: Current state: running, stopped, power-down, or other system state

Get the current source file and line of the halted CPU.

Returns the HLL source location (file:line) and enclosing function name for the current PC. The target must be halted and symbols must be loaded.

Returns: Formatted source location (file, line, function, module)

List all supported step modes and their behavior.

Returns: Table of step modes with descriptions

Get the name of the function the CPU is currently executing.

Returns: Function name (or address if no debug symbols)

Run until execution reaches a specific source file line.

Sets a temporary breakpoint at the given source location and resumes execution. The target stops when that line is reached.

Args: file: Source file name (can be partial, e.g., 'main.c' or full path) line: Line number in the source file

Returns: Confirmation of temporary breakpoint

Get quick run/halt statistics for the target.

Combines CPU state, current function, source location, and elapsed runtime (if available) in one call.

Returns: Aggregated run statistics

Get the state of any running PRACTICE (.cmm) script.

Shows whether a PRACTICE script is active, which script is running, and the current line being executed.

Returns: PRACTICE script state

Abort the currently running PRACTICE script.

Stops the active .cmm script execution immediately.

Returns: Confirmation

Read the current TRACE32 message line content.

The message line is the status bar at the bottom of the TRACE32 window that displays status messages from commands and scripts.

Returns: Current message line text

Read memory from the target at a given address.

Args: address: Memory address as hex string (e.g., "0x80000000") or symbol name (e.g., "main") length: Number of bytes to read width: Access width in bits — 8, 16, 32, or 64 (default: 32) access: Access class prefix (e.g., "D:" for data, "P:" for program). Empty = default.

Returns: Hex dump of memory contents

Write data to target memory at a given address.

Args: address: Memory address as hex string (e.g., "0x80000000") or symbol name data: Hex string of bytes to write (e.g., "DEADBEEF" for 4 bytes) width: Access width in bits — 8, 16, 32, or 64 (default: 32) access: Access class prefix (e.g., "D:" for data). Empty = default.

Returns: Confirmation with number of bytes written

Read memory using cache-aware access (D: prefix).

Shows data as the CPU sees it through its data cache, not the stale value on the bus. Essential for debugging code that modifies cached memory (e.g., shared variables in LMU on TC39x).

Args: address: Memory address as hex string (e.g., "0x80000000") length: Number of bytes to read width: Access width in bits — 8, 16, 32, or 64 (default: 32)

Returns: Hex dump of cached memory contents

Read physical memory bypassing the CPU cache.

Reads the actual value on the memory bus, which may differ from what the CPU sees if the data cache has not been flushed.

Args: address: Memory address as hex string (e.g., "0x80000000") length: Number of bytes to read width: Access width in bits — 8, 16, 32, or 64 (default: 32)

Returns: Hex dump of physical memory contents

List all available memory access classes for TRACE32.

Shows the different access class prefixes that can be used to read memory through different paths (cache, bus, peripheral, etc.).

Returns: Table of access classes with descriptions

Read a single CPU register by name.

Args: name: Register name (e.g., "PC", "SP", "R0", "D0", "A0")

Returns: Register name and its current value

Read multiple CPU registers.

Args: names: List of register names to read. If empty/None, reads all registers. core: Filter by core/unit (e.g., "CPU", "FPU"). Empty = all.

Returns: Table of register names and values

Write a value to a CPU register.

Args: name: Register name (e.g., "PC", "SP", "R0") value: Integer value to write

Returns: Confirmation with the register's new value

Set a breakpoint at the specified address or symbol.

Args: address: Address (hex e.g. "0x80001000") or symbol name (e.g. "main") type: Breakpoint type — "program", "read", "write", or "readwrite" impl: Implementation — "auto", "soft" (software), or "hard" (hardware)

Returns: Breakpoint details confirming the set operation

List all active breakpoints.

Returns: Table of all breakpoints with address, type, and state

Delete a breakpoint at the specified address or symbol.

Args: address: Address or symbol name of the breakpoint to delete

Returns: Confirmation of deletion

Delete all breakpoints at once.

Use this to clean up all breakpoints and let the program run freely.

Returns: Confirmation that all breakpoints were cleared

Enable or disable a breakpoint without deleting it.

Args: address: Address or symbol name of the breakpoint enabled: True to enable, False to disable

Returns: New breakpoint state

Get the total number of breakpoints currently set.

Returns: Count of all breakpoints (enabled and disabled)

Read a C/C++ variable from the target by its symbol name.

The target must be halted (stopped) for variable reads to work.

Args: name: Variable name as it appears in source code (e.g., "counter", "myStruct.field")

Returns: Variable name and its current value

Write a value to a C/C++ variable on the target.

The target must be halted (stopped) for variable writes to work.

Args: name: Variable name as it appears in source code value: Value to write (integer, float, or string representation)

Returns: Confirmation with the new value

Look up a debug symbol by its name to get its address.

Args: name: Symbol name (function, variable, label — e.g., "main", "g_counter")

Returns: Symbol address and access info

Look up a debug symbol by its address to get its name.

Args: address: Memory address as hex string (e.g., "0x80001000")

Returns: Symbol name at or near the given address

Get the current DebugForge project configuration.

Returns project-specific paths (ELF, MAP, scripts) and TRACE32 settings loaded from debugforge.toml and environment variables. Call this at the start of a debug session to learn about the project context.

Returns: Formatted project configuration including paths and connection settings

Execute any TRACE32 PRACTICE command string.

This is the most flexible tool — any command you can type in the TRACE32 command line can be executed here (e.g., "SYStem.Up", "Data.LOAD.Elf ...", "Break.Set main", "Var.View myVar").

Args: command: TRACE32 command string to execute

Returns: Success confirmation or error message from TRACE32

Run a PRACTICE (.cmm) script and wait for it to complete.

Args: script: Path to the .cmm script file (absolute or relative to TRACE32) timeout: Maximum time to wait for script completion in seconds (default: 60)

Returns: Script execution result (success or error message)

Evaluate a TRACE32 PRACTICE function or expression.

Useful for querying system state, hardware info, or computing values. Examples: "SOFTWARE.VERSION()", "REGISTER(PC)", "sYmbol.BEGIN(main)"

Args: expression: TRACE32 PRACTICE function or expression to evaluate

Returns: Evaluation result as a string

Set a conditional breakpoint that only stops when a condition is true.

Args: address: Address or symbol (e.g., "main", "0x80001000", "sieve\11") condition: Condition expression. HLL example: "(counter > 10) && (flag == 1)" TRACE32 example: "Register(D0)>5" language: "hll" for C/C++ syntax, "t32" for TRACE32 PRACTICE syntax

Returns: Confirmation of conditional breakpoint

Set a data breakpoint that triggers on memory read/write access, optionally matching a value.

Args: address: Variable name or memory address (e.g., "myVar", "0xD0000100") access: Access type — "read", "write", or "readwrite" data_value: Optional data value to match (e.g., "0x33", "0x0"). Empty = any value. data_width: Width for value matching — "byte", "word", "long", "quad", "auto"

Returns: Confirmation of data breakpoint

Set a count breakpoint that stops after N-th hit.

Useful for breaking in a loop at a specific iteration.

Args: address: Address or symbol name count: Number of hits before stopping (e.g., 100 = stop on 100th hit) impl: "auto", "soft" (software counter, intrusive), or "hard" (on-chip counter, real-time)

Returns: Confirmation of count breakpoint

Set a task-specific breakpoint that only triggers for a specific OS task/thread.

Requires OS-awareness to be configured.

Args: address: Address or symbol name task: Task identifier — name (e.g., "idle_task"), ID (e.g., "14"), or magic number

Returns: Confirmation of task breakpoint

Set an action breakpoint that executes a TRACE32 command when hit.

The target briefly stops, the command executes, then optionally resumes. Useful for logging variable values, collecting trace data, etc.

Args: address: Address or symbol name command: TRACE32 command to execute on hit (e.g., "Var.print counter") resume: True to auto-resume after command (default), False to stay stopped

Returns: Confirmation of action breakpoint

Set a temporary breakpoint that auto-deletes after first hit.

Equivalent to "run to this address once".

Args: address: Address or symbol name

Returns: Confirmation

Run until a specific address is reached (temporary breakpoint).

Args: address: Target address or symbol to run to (e.g., "main", "0x80001000")

Returns: State after reaching the address (or timeout info)

Run until the current function returns to its caller (step out).

Returns: State after returning to caller

Run to the last instruction of the current function (before return).

Unlike go_up, this stops INSIDE the current function at its return point.

Returns: State at function return point

Get disassembly listing at an address (or current PC if not specified).

Shows mixed source and assembly code for understanding what the CPU is executing.

Args: address: Start address or symbol. Empty = current PC. lines: Approximate number of lines to return (default: 30)

Returns: Disassembly listing with source code interleaved

Get the source code listing around the current execution point.

Shows HLL (C/C++) source with line numbers. The target must be halted.

Args: address: Address or symbol. Empty = current PC.

Returns: Source code listing

Set a C/C++ variable to a new value on the target.

The target must be halted. Supports any assignable lvalue.

Args: name: Variable name (e.g., "counter", "myStruct.field", "array[0]") value: New value as C expression (e.g., "42", "0xFF", "NULL")

Returns: Confirmation of variable modification

Get the list of OS tasks/threads (requires OS-awareness configured).

Returns: Task list with names, IDs, states, and priorities

Get stack information for OS tasks.

Args: task: Task name or ID. Empty = all tasks.

Returns: Task stack usage information

View peripheral register contents.

Args: peripheral: Peripheral name or address. Empty = open general view.

Returns: Peripheral register values

Write a value directly to a memory address using Data.Set.

Args: address: Memory address (e.g., "D:0xF0036250", "0x80000000") value: Value to write (e.g., "0x00000008", "0xFF") width: Data width — "byte", "word" (16-bit), "long" (32-bit), "quad" (64-bit)

Returns: Confirmation of write

Build the project using the configured build command.

Executes the build command defined in debugforge.toml [build] section. Returns the build output including any errors or warnings.

Returns: Build output (stdout + stderr) with success/failure status

Clean the project build artifacts using the configured clean command.

Returns: Clean output with success/failure status

Disassemble a function or address range from the project ELF file.

Uses the configured objdump tool to produce disassembly output.

Args: symbol: Function name to disassemble (e.g., "main", "ISR_Handler") address: Start address in hex (e.g., "0x80001000"). Used if symbol is empty. lines: Maximum number of lines to return (default: 50)

Returns: Disassembly listing

Analyze the project MAP file to understand memory layout.

Shows memory section sizes, symbol addresses, or searches for a specific symbol.

Args: section: Filter by section name (e.g., ".text", ".bss", ".data"). Empty for overview. symbol: Search for a specific symbol in the MAP file.

Returns: MAP file analysis (memory layout, section sizes, or symbol info)

Analyze the project ELF file structure.

Uses readelf to inspect ELF headers, sections, or symbols.

Args: detail: What to show — "headers", "sections", "symbols", or "size" (default: headers)

Returns: ELF analysis output

Flash firmware to target and run to a breakpoint (default: main).

Composite operation:

1. Execute the configured flash script (downloads firmware)

2. Reset the target

3. Set a breakpoint at the specified symbol

4. Run to that breakpoint

Args: break_at: Symbol to break at after flashing (default: "main"). Set empty to skip.

Returns: Step-by-step execution results

Full cycle: build the project, flash firmware, and run to breakpoint.

Composite operation:

1. Build the project (compile)

2. Flash the firmware to target

3. Reset and run to the specified breakpoint

This is the core "edit-compile-debug" loop tool.

Args: break_at: Symbol to break at after flashing (default: "main")

Returns: Step-by-step results for the entire build-flash-run cycle

List all available debug skills in the project knowledge base.

Returns skill names, categories, and brief descriptions from the configured skills directory.

Returns: Formatted list of available debug skills

Get the full content of a specific debug skill.

Args: name: Skill name or filename (e.g., "stack-overflow" or "stack-overflow.md")

Returns: Full skill content including symptoms, debug strategy, root causes, and fix patterns

Search debug skills by keywords matching symptoms or categories.

Searches through skill names, keywords, categories, and content body.

Args: keywords: Space-separated search terms (e.g., "HardFault stack crash")

Returns: Matching skills with relevance ranking

Save a new debug skill to the knowledge base.

Call this after successfully debugging a new type of issue to capture the experience for future reuse.

Args: name: Short kebab-case name (e.g., "dma-transfer-timeout") category: Category — memory, fault, peripheral, timing, rtos, general keywords: Comma-separated keywords for search matching symptoms: Description of observable symptoms (what the user sees) strategy: Step-by-step debug strategy that worked root_causes: Common root causes for this type of issue fix_patterns: Patterns for fixing this type of issue

Returns: Confirmation with the saved file path

Start on-chip trace recording using MCDS.

Configures and starts the MCDS trace engine. Must be called before running the target. Call trace_stop() and trace_list() after the target halts.

Args: sources: List of trace sources to enable. Supported values: "program" — instruction flow (PC trace) "write_addr" — data write addresses "write_data" — data write values "read_addr" — data read addresses "read_data" — data read values Default: ["program"] timestamps: Enable trace timestamps (default: True)

Returns: Confirmation of trace configuration

Stop the on-chip trace recording.

Call after the target halts (e.g., at a breakpoint or after manual halt).

Returns: Confirmation that trace recording stopped

Display the recorded trace buffer contents.

Shows the trace list with instruction flow, data accesses, and timestamps (if enabled). The target must be halted.

Args: max_records: Maximum number of trace records to display (default: 100)

Returns: Formatted trace listing

Clear the trace buffer.

Resets the MCDS trace buffer for a fresh recording.

Returns: Confirmation

Set a trace trigger breakpoint.

Configures a breakpoint that controls trace recording start/stop.

Args: address: Function name, symbol, or address (e.g., "sieve", "0x80001000"). Supports symbol.EXIT(func) syntax for function exit triggers. trigger_type: "stop" — stop recording at this point (TraceTrigger) "enable" — enable recording at this point (TraceEnable) "disable" — disable recording at this point

Returns: Confirmation of trace trigger

Configure data write trace on a variable.

Records every write access to the specified variable in the trace buffer. Optionally filters by data value.

Args: variable: Variable name or address (e.g., "flags[12]", "myVar", "0xD0000100") data_value: Optional filter — only trace writes matching this value (e.g., "0x33") data_width: Data width for value matching — "byte", "word", "long", "quad", "auto"

Returns: Confirmation of data write trace setup

Configure data read trace on a variable.

Records every read access to the specified variable in the trace buffer.

Args: variable: Variable name or address (e.g., "myVar", "0xD0000100")

Returns: Confirmation of data read trace setup

Display a profile chart from recorded trace data.

Shows instruction execution statistics per function based on trace data. Requires trace data to have been recorded first.

Returns: Formatted profile chart

Get current MCDS trace state and configuration.

Shows the MCDS state window with current trace source settings, buffer status, and configuration.

Returns: MCDS state information

Select the active CPU core for debugging.

In multicore setups, switches the debugger focus to the specified core. Subsequent commands (breakpoints, register reads, etc.) target this core.

Args: core: Core number (0-based, e.g., 0, 1, 2 for TC397)

Returns: Confirmation with current core state

Get the detected chip/device information.

Returns chip stepping, device variant, and CPU configuration. Useful for verifying the correct CPU is selected.

Returns: Chip stepping, CPU type, and stepping information

Configure multicore topology for AURIX devices.

Mounts multiple cores into one chip for shared resources (trace, MCDS). Must be called before SYStem.Up in multicore scenarios.

Based on SYStem.CONFIG.CORE command from debugger_tricore.pdf: SYStem.CONFIG.CORE maps each core to a chip position.

Args: core_count: Number of cores to configure (e.g., 6 for TC397, 3 for TC377)

Returns: Configuration results per core

Synchronize Go/Step/Break across multiple cores.

Uses the SYnch command to coordinate execution state between cores in SMP or synchronized AMP mode.

Args: action: Synchronization action: "go" — run all synchronized cores "break" — halt all synchronized cores "step" — single-step all synchronized cores

Returns: Confirmation of sync operation

Get the execution state of all CPU cores.

Queries each core's running/stopped status and PC value. Useful in multicore debugging to understand the global system state.

Returns: Table showing state of each core

Auto-detect the connected AURIX device.

Uses SYStem.DETECT.CPU to identify the connected chip automatically. Works with TC27x, TC37x, TC39x and other AURIX families.

Returns: Detected CPU type and stepping

Configure a BenchMark Counter to count a specific hardware event.

Maps a performance event to a counter slot. The counter accumulates while the target runs. Read with bmc_read() after halting.

Args: counter: Counter slot — "M1CNT", "M2CNT", "M3CNT", "M4CNT", etc. event: Hardware event to count. Common TriCore events: "CYCLECOUNT" — CPU clock cycles "INSTRUCTIONCOUNT" — instructions executed "DATA_X_HIT" — data cache/buffer hits "DATA_X_CLEAN" — data cache/buffer misses "DATA_READ" — data read accesses "DATA_WRITE" — data write accesses "PROGRAM_X_HIT" — instruction cache hits "PROGRAM_X_MISS" — instruction cache misses "JUMP" — jump/branch instructions "BRANCH_PREDICTED" — correctly predicted branches "BRANCH_NOT_PREDICTED" — mispredicted branches

Returns: Confirmation of counter configuration

Read current BenchMark Counter values.

Target must be halted. Returns raw counter values since last reset.

Args: counters: List of counter names to read (e.g., ["M1CNT", "M2CNT"]). If empty/None, reads all available counters.

Returns: Counter names and their current values

Reset all BenchMark Counters to zero.

Clears all counter values for a fresh measurement.

Returns: Confirmation

Run a quick cache performance analysis.

Configures counters for cache hit/miss ratio, runs the target briefly, then reports the results. Useful for identifying cache bottlenecks.

Args: function: Function to analyze (empty = current execution point) run_duration_ms: How long to run in milliseconds (default: 1000)

Returns: Cache hit/miss statistics

Enable or disable A-to-B mode on a BMC counter.

In A-to-B mode, the counter only counts events between the Alpha and Bravo marker breakpoints. Use set_breakpoint with actions "alpha"/"bravo" to set markers.

Args: counter: Counter name (e.g., "M1CNT") enabled: True to enable A-to-B mode, False to disable

Returns: Confirmation

Display a BMC profile chart with counter data mapped to instruction flow.

Shows which functions/addresses consumed the most events (cycles, cache misses, etc.). Requires BMC counters to have been recorded during execution.

Args: counters: Counter names to include (e.g., ["M1CNT", "M2CNT"]). Empty = all configured counters.

Returns: Profile chart showing event distribution across code

Configure reset behavior for the debugger.

Determines how TRACE32 handles soft resets, hard resets, and power cycles.

Args: behavior: Reset behavior mode: "restore_go" — halt briefly to restore debug resources, then continue "run_restore" — restore debug resources while CPU runs (may miss breakpoints) "halt" — halt CPU at reset vector after reset

Returns: Confirmation of reset behavior setting

Enable or disable cache-aware memory reads.

When ON, the default data access class (D:) shows cached data from the CPU's point of view instead of stale bus-level data. Essential for debugging code that modifies cached memory (e.g., LMU on TC39x).

Args: enabled: True to enable cache-aware reads, False to disable

Returns: Confirmation

Enable or disable automatic peripheral suspend when CPU halts.

When ON, peripheral modules (timers, watchdogs, communication) are automatically suspended when the debugger halts the CPU. This prevents watchdog timeouts and timer overflows during debugging.

Args: enabled: True to enable peripheral suspend, False to disable

Returns: Confirmation

Configure suspend mode for a specific peripheral module.

Sets how a peripheral responds when the CPU is halted by the debugger.

Args: peripheral: Peripheral register name (e.g., "GPT120_OCS", "STM0_OCS") suspend_mode: "hard" — suspend immediately on CPU halt "soft" — suspend after current operation completes "none" — never suspend

Returns: Confirmation

Enable or disable standby mode for power cycle detection.

When ON, TRACE32 monitors VTREF to detect power cycles and can automatically reconnect and restore debug state.

Args: enabled: True to enable standby mode, False to disable

Returns: Confirmation

Get the current system options and configuration.

Shows all active SYStem.Option settings including PERSTOP, DCREAD, reset behavior, and other debug options.

Returns: Formatted system options

Load debug symbols from an ELF file.

Loads symbol and debug information for source-level debugging. If no path given, uses the configured ELF path from debugforge.toml.

Args: elf_path: Path to ELF file. Empty = use configured path.

Returns: Confirmation of symbol loading

Execute a TRACE32 PRACTICE (.cmm) script file.

Args: script_path: Path to the .cmm script file timeout: Maximum execution time in seconds (default: 30)

Returns: Script execution result