McuBuddy

Resume target execution. max_condition_loops: max number of conditional breakpoint skips before giving up. Lower this (e.g. 10) for high-frequency breakpoints where you want an early abort.

Route a user-level symptom to the most relevant diagnosis tool. Examples: - diagnose("Board crashed into HardFault") - diagnose("USART2 no output from TX pin", peripheral="USART2") - diagnose("PLL clock switch is stuck")

Scan stack and heap regions for corruption evidence. Reads stack bounds from ELF linker symbols (_estack / _Min_Stack_Size or __StackTop / __StackLimit), checks whether current SP is in bounds, scans for stack canary high-water mark, and samples heap boundaries for known corruption magic values. stack_canary: 4-byte fill pattern written to unused stack at startup (default 0xCCCCCCCC). Common values: 0xCCCCCCCC (Keil/IAR default), 0xDEADBEEF, 0xA5A5A5A5. Requires ELF loaded and probe connected.

Diagnose why a peripheral is not working. Reads peripheral registers (via SVD) and checks RCC clock enable. Common root causes: clock not enabled in RCC, wrong pin AF mode, wrong baud rate. Requires SVD loaded and probe connected. Example: diagnose_peripheral_stuck('USART2', 'no output from TX pin')

Diagnose potential stack overflow on a Cortex-M target. Reads VTOR (0xE000ED08) to locate the vector table, extracts the initial SP from word 0, and compares it with the current SP. If an ELF is loaded and _Min_Stack_Size is available, reports remaining stack space and detects overflow. Requires probe connected and target halted.

Disassemble Thumb/Thumb-2 instructions at the given address. Reads count*4 bytes from target memory and disassembles using capstone. Annotates each instruction with source file:line if DWARF is loaded. Requires probe connected and target halted. Example: disassemble(0x08001234, 10)

Find Keil project files, targets, and likely AXF/ELF outputs under a directory.

Run a read-only environment, dependency, probe, target, and config preflight.

Read and display memory in formatted form. format options: 'hex' — classic hex dump with address, hex bytes, and ASCII sidebar 'u8' — array of unsigned bytes 'u16' — array of unsigned 16-bit values (little-endian) 'u32' — array of unsigned 32-bit values (little-endian) 'u64' — array of unsigned 64-bit values (little-endian) columns: bytes per row for hex format (default 16). Requires probe connected and target halted. Example: dump_memory(0x20000000, 64) Example: dump_memory(0x20000100, 32, 'u32')

Accurate call stack using DWARF .debug_frame CFI rules. For each frame, computes the Canonical Frame Address (CFA) from the CFI table and reads the saved return address from the stack. Falls back to LR for leaf functions or frames without CFI entries. More accurate than the heuristic backtrace(); requires ELF with .debug_frame. Requires probe connected and target halted.

Look up the source file and line number for a given address using DWARF .debug_line. Returns file name, line number, and nearest function symbol. Requires ELF loaded with DWARF debug info. Example: elf_addr_to_source(0x08001234)

List all function symbols from the loaded ELF with address and size. name_filter: optional substring to filter function names (case-insensitive). Useful for finding candidate breakpoint locations without a map file. Example: elf_list_functions('uart') → all UART-related functions Requires ELF loaded (no probe needed).

Return address, size, type, and source location for a single symbol. Looks up the exact symbol name in the ELF symbol table. Useful for checking a variable's address before setting a watchpoint. Example: elf_symbol_info('g_uart_handle') Example: elf_symbol_info('SystemCoreClock') Requires ELF loaded (no probe needed).

Erase target flash memory. Use chip_erase=True to erase the whole chip, or provide start/end addresses for a range erase. Requires probe connected.

Stop registered actuators, reset and run the target, then disconnect.

Run the safest first board contact flow and suggest next debug tools.

Flash a raw binary file with erase, program, verify, and optional reset. path must be within security.allowed_file_paths when that allowlist is configured. erase_mode accepts 'sector' (default) or 'chip'. This persistent operation requires explicit confirmation and both flash erase and programming to be enabled.

Return whether the pyOCD GDB server is running and which ports it uses.

Return whether the J-Link GDB server is running and which port it uses.

Read local variables and parameters at the current PC using DWARF .debug_info. Resolves each variable's location (stack offset, register, or absolute address) and reads its current value from the target. Variables optimized out or using complex location expressions will have value=null. Requires ELF with DWARF loaded and probe connected and target halted.

Return alias-match and device-patch info for a target on a given backend.

Read target-project memory or prepare a read-only onboarding proposal.

List all registered conditional breakpoints in the current session.

List all probes currently connected to this machine. Start here if unsure what probe to use.

List all FreeRTOS tasks with state, priority, and stack usage. Walks pxReadyTasksLists, xDelayedTaskList*, and xSuspendedTaskList to enumerate all tasks. Reads TCB fields: name, priority, stack base, stack top pointer. max_priorities: upper bound for scanning pxReadyTasksLists (default 32). task_name_len: configMAX_TASK_NAME_LEN in your FreeRTOS build (default 16). Requires ELF loaded and probe connected with target halted.

List built-in target profiles and validation metadata for a backend.

List safety levels for public McuBuddy tools.

List machine-readable real-hardware validation records.

Step through code and record each unique source line visited. Executes up to max_steps instructions, collecting distinct (file, line) pairs in execution order. Stops early when max_lines unique lines are reached. Useful for tracing execution paths through unfamiliar code. Requires ELF with debug info (.debug_line) and probe connected.

Resolve a chip alias to a backend-specific target name.

Re-read a snapshotted memory region and return a byte-level diff. Returns changed_bytes (individual byte changes) and changed_regions (grouped contiguous runs). Call memory_snapshot first to establish a baseline. Example: memory_diff('before_init')

Search a memory region for a byte pattern. Returns all non-overlapping match addresses. Useful for finding magic numbers, string literals, or corrupted canary values in RAM. pattern: list of byte values, e.g. [0xDE, 0xAD, 0xBE, 0xEF] Example: memory_find(0x20000000, 0x10000, [0xDE, 0xAD, 0xBE, 0xEF]) Example: memory_find(0x20000000, 0x10000, [0x53, 0x45, 0x47, 0x47, 0x45, 0x52])

Capture a memory region snapshot for later comparison. Use before an operation (step, continue, write) then call memory_diff to see what changed. Multiple snapshots can be stored simultaneously using different labels. Example: memory_snapshot(0x20000000, 256, 'before_init')

Find and checksum-verify the managed CMSIS-Pack for a target.

Download and checksum-verify a managed CMSIS-Pack after confirmation.

Remove all hardware watchpoints.

Read bytes from target memory at the given address. Returns raw bytes plus convenience integer interpretations (u8/u16/u32 little-endian). Requires probe connected and target halted. Example: probe_read_memory(0x20000000, 4)

Remove a hardware watchpoint at the given address.

Set a hardware data watchpoint on a memory address. Halts the target when the address is accessed according to watch_type. watch_type: 'read', 'write', or 'read_write' size: number of bytes to watch (1, 2, or 4; Cortex-M supports up to 4 watchpoints) Requires probe connected and target halted. Example: probe_set_watchpoint(0x20000010, 4, 'write')

Execute one instruction and return the new PC (with symbol if ELF is loaded).

Write bytes to target memory. data is a list of integers (0-255).

Program target flash memory from raw byte data. address: flash destination address data: list of byte values (0-255) verify: read back and compare after programming Requires probe connected.

Read the DWT cycle counter when supported by the active probe backend. Useful for lightweight execution progress and timing checks. Requires probe connected.

Return the Cortex-M address space layout and ELF section map. Always returns the fixed Cortex-M region boundaries (Code/SRAM/Peripheral etc.). If an ELF is loaded, also returns each section's name, VMA, and size. No probe connection required.

Read Segger RTT log output directly from target RAM via probe (no UART needed). Scans the specified RAM range for the RTT control block ('SEGGER RTT' magic), then reads the ring buffer of the requested up-channel. channel: RTT up-channel index (default 0). search_start: start of RAM scan (default 0x20000000). search_size: bytes to scan (default 0x50000 = 320 KB). Requires probe connected and target halted (or briefly halted to read).

Scan FreeRTOS task stacks for the canary high-water mark. FreeRTOS fills unused stack with 0xa5 (tskSTACK_FILL_BYTE). Scans each task's stack from base upward and counts intact canary words. Reports min_free_bytes (never-used stack) per task. canary: fill byte pattern used at init (default 0xa5a5a5a5). max_priorities: upper bound for scanning pxReadyTasksLists (default 32). Requires ELF loaded and probe connected with target halted.

Read bytes from the J-Link SWO host buffer when supported by the active probe backend. cpu_speed_hz: target CPU clock in Hz swo_speed_hz: SWO bitrate in Hz max_bytes: maximum bytes to return port_mask: ITM stimulus port mask used when enabling SWO Requires probe connected.

Read the value of a symbol (variable, linker symbol) by name from target memory. Resolves the symbol address via ELF, then reads 'size' bytes at that address. Returns raw bytes plus u8/u16/u32 interpretations (little-endian). Requires ELF loaded and probe connected. Example: read_symbol_value('g_error_count', 4) Example: read_symbol_value('_Min_Stack_Size', 4)

Reset the target and immediately trace execution from the reset vector. Calls reset(halt=True) then steps through code collecting unique source lines. Useful for seeing the startup path (clocks, peripherals, RTOS init). Requires ELF with debug info and probe connected.

Switch CPU context to a blocked or suspended FreeRTOS task. Uses the saved exception frame from the task's stack (stored in TCB.pxTopOfStack), constructs a new exception frame on the current stack, and sets LR to EXC_RETURN so that stepping once enters the task context. After switching, you can step or continue to execute the target task. Requires ELF loaded and probe connected with target halted. Example: rtos_switch_context('idle_task')

Read the saved register context of a blocked or suspended FreeRTOS task. Parses the Cortex-M4F context switch stack frame stored in the task's TCB. Reconstructs R0-R12, SP, LR, PC, xPSR and resolves PC to a symbol/source line. Automatically detects whether FPU context was saved (EXC_RETURN bit 4). If the named task is currently running, returns live register values instead. task_name: exact task name as passed to xTaskCreate (case-sensitive). task_name_len: configMAX_TASK_NAME_LEN in your FreeRTOS build (default 16). Requires ELF loaded and probe connected with target halted.

Set a breakpoint on a function by name, resume, and wait for it to be hit. Combines set_breakpoint + continue_target into one step. Requires ELF loaded and probe connected. Example: run_to_function('HAL_UART_Transmit') Example: run_to_function('main', timeout_seconds=3.0)

Run target until execution reaches a specific source file and line number. Looks up the address for file:line in the DWARF line table, sets a breakpoint there, and resumes. Matches on filename suffix so you can pass just the basename (e.g. 'main.c') or a full path. Requires ELF with DWARF loaded and probe connected. Example: run_to_source('main.c', 42)

Set a breakpoint, optionally with a condition. If condition_symbol or condition_register is given, continue_target will automatically skip this breakpoint (resume) whenever the condition is not met. condition_op: eq | ne | lt | gt | le | ge

Set breakpoints on all ELF functions whose address falls between two symbols. Useful for tracing all calls within a module (e.g. start=_uart_start, end=_uart_end). Requires ELF loaded and probe connected.

Write an integer value to a local variable by name at the current PC. Resolves the variable's location via DWARF .debug_info and writes the value to the corresponding stack address or absolute address. Variables in registers or with complex locations cannot be written this way. Requires ELF with DWARF loaded and probe connected and target halted. Example: set_local('count', 0)

Execute instructions until the source line changes (source-level single step). Uses DWARF .debug_line to detect line boundaries. Falls back to a single instruction step if no DWARF info is available. Requires ELF loaded with DWARF info and probe connected and target halted.

Start a pyOCD GDB server for the configured target. Uses the current probe config when target/unique_id are omitted. Example: start_gdb_server() Example: start_gdb_server(port=3334, persist=True)

Start a J-Link GDB server for the configured target. Uses the current probe config when target/serial_no are omitted. Example: start_jlink_gdb_server(target='STM32F103C8', serial_no='240710115') Example: start_jlink_gdb_server(port=2332, speed=1000)

Execute count assembly instructions, recording PC and symbol at each step. Returns a trace list. Useful for precisely tracking execution through small code sequences without source-level stepping. Maximum 100 steps per call (truncated=True if count exceeded). Requires probe connected and target halted.

Run until the current function returns (step out). Sets a breakpoint at the current LR (return address) and resumes. Requires probe connected and target halted.

Execute one source line, stepping OVER function calls (bl/blx). Disassembles the current instruction. If it is a BL/BLX call, sets a breakpoint at the return address and resumes, skipping the callee body. Otherwise falls through to source_step (step into). Requires probe connected and target halted.

Stop the active pyOCD GDB server process if one is running.

Stop the active J-Link GDB server process if one is running.

Return the register layout for a peripheral without reading hardware. Useful to understand what registers and fields exist before reading values. Example: svd_get_registers('USART2')

List all peripherals in the loaded SVD (UART, SPI, I2C, GPIO, TIM, etc.).

Load a CMSIS-SVD file to enable peripheral register interpretation. SVD files define the register map of a chip. You can find SVD files in your chip vendor's SDK, or at https://github.com/posborne/cmsis-svd-data Example: svd_load('/path/to/STM32L496.svd')

Read all register values for a peripheral and interpret each field. Combines hardware register reads with SVD field definitions to produce a structured, human-readable view of peripheral state. Requires probe connected and target halted. Example: svd_read_peripheral('USART2')

Write a value to a single bit-field in a peripheral register (read-modify-write). Reads the current register value, updates only the target field bits, writes back. Safer than svd_write_register when you only want to change one field. Example: svd_write_field('RCC', 'CR', 'PLLON', 1) Example: svd_write_field('GPIOA', 'MODER', 'MODER5', 2)

Write a 32-bit value to a peripheral register by name using SVD addressing. Looks up the register address from the loaded SVD, then writes the value. Requires SVD loaded and probe connected. Example: svd_write_register('USART2', 'CR1', 0x000C) Example: svd_write_register('GPIOA', 'ODR', 0x0001)

Send an actuator command and register its matching safe-stop command.

Verify target flash contents against expected raw byte data. address: flash start address data: expected byte values (0-255) Requires probe connected.

Poll a symbol's value until it changes or timeout expires. Reads the symbol at each poll interval and returns as soon as the value differs from the initial read. Reports old/new values and elapsed time. Requires ELF loaded and probe connected. Example: watch_symbol('g_state', 4, timeout_seconds=5.0)

Write canonical memory inside a confirmed target project.

Write an integer value to a symbol (variable) by name in target memory. Resolves the symbol address via ELF, then writes 'size' bytes (little-endian). Requires ELF loaded and probe connected. Example: write_symbol_value('g_error_count', 0, 4) Example: write_symbol_value('g_mode', 1, 1)