debugger

name	debugger
description	Embedded debugging skill using CmBacktrace + GDB for crash log analysis, symbolication, GDB session management, and Cortex-M hardfault analysis
trigger	**/*.c, **/*.h, **/*.elf, **/*.map, **/*.log, crash log, hardfault, gdb session

Embedded Debugger Skill

Overview

This skill covers embedded debugging using CmBacktrace and GDB for Cortex-M based MCUs. It provides structured workflows for crash log collection, address symbolication, GDB session management, and hardfault analysis.

Trigger Conditions

Activate this skill when the user mentions:

• debug, crash, hardfault, cmbacktrace, gdb
• backtrace, stack overflow, fault analysis
• addr2line, Cortex-M fault registers, OpenOCD, J-Link
• call stack, crash log, verify call stack

Entry Prompt

"I need to debug a crash on an embedded Cortex-M system. I have a CmBacktrace crash log / GDB session log. Can you help me analyze it and identify the root cause?"

Debug Workflow

Step 1: Collect Crash Information

1. Obtain the raw crash log from the device (UART output, RTT, or saved log file)
2. Identify the firmware .elf file used for symbolication
3. Note the MCU architecture and toolchain (ARM GCC, IAR, Keil)

Step 2: Parse the Crash Log

Extract from the crash log:

• Fault type: HardFault, MemManage, BusFault, UsageFault
• Register dump: R0–R12, LR, PC, xPSR, MSP, PSP
• Call stack: List of return addresses
• CFSR: Configurable Fault Status Register
• HFSR/UFSR/BFSR/MMFSR: Specific fault status registers

Step 3: Symbolicate the Call Stack

For each address in the call stack:

arm-none-eabi-addr2line -e firmware.elf -f <address>

This converts raw addresses to function_name + file:line_number.

Step 4: Analyze the Fault

• Check if PC is in valid flash range
• Verify stack pointer (MSP/PSP) is within valid RAM bounds
• Decode CFSR to determine fault cause:
  • CFSR & 0x0000FF: MemManage faults
  • CFSR & 0x00FF00: Bus faults
  • CFSR & 0xFF0000: Usage faults
• For HardFault: check SCB->HFSR for forced hardfault

Step 5: GDB Session Analysis (if GDB log available)

1. Parse register values from GDB output
2. Correlate GDB info registers with crash log registers
3. Use backtrace / bt output to verify call stack matches
4. Use x/100x <sp> to dump stack memory around stack pointer
5. Check for stack corruption patterns (0xFFFFFFFF, 0x00000000 near SP)

Step 6: Generate Debug Report

Output the analysis in the requested format:

• CmBacktrace report → cmbacktrace_report.md
• GDB session report → gdb_session_report.md

Safety Rules

WARNING: Read-only commands only on live hardware.

When connected to live hardware via J-Link, OpenOCD, or ST-Link:

• ✅ SAFE: info registers, backtrace, x/100x <addr>, print <var>
• ✅ SAFE: disassemble, info breakpoints, info threads
• ❌ NEVER: set, delete, break, continue, run, step on production systems
• ❌ NEVER: Write memory or flash while debugging a production device

For post-mortem analysis (crash logs, ELF files, offline analysis):

• All commands are safe — no live hardware involved
• Use arm-none-eabi-addr2line, arm-none-eabi-objdump freely

Output Format

CmBacktrace Report (cmbacktrace_report.md)

# CmBacktrace Crash Analysis Report

## Device Information
- MCU: STM32F407VG (Cortex-M4)
- Firmware: firmware.elf
- Toolchain: ARM GCC 10.3.1

## Fault Information
- Fault Type: HardFault
- Timestamp: 2024-01-15 14:23:45

## Register Dump
| Register | Value |
|----------|-------|
| R0 | 0x20001234 |
| R1 | 0x00000000 |
| ... | ... |

## Call Stack (Symbolicated)
| # | Address | Location |
|---|---------|----------|
| 0 | 0x08001234 | main.c:125 `app_main` |
| 1 | 0x08003456 | sensor.c:89 `sensor_read` |

## Fault Analysis
- Root cause: Stack overflow in `sensor_read()` (sensor.c:89)
- Recommendation: Increase stack size for sensor task

## Raw Crash Log
<include raw log>

GDB Session Report (gdb_session_report.md)

# GDB Session Analysis Report

## Session Info
- Target: STM32F407VG via J-Link
- ELF: firmware.elf
- GDB Command Log: gdb_session.log

## Register Correlation
| GDB Value | Crash Log Value | Match |
|-----------|-----------------|-------|
| R0 = 0x20001234 | R0 = 0x20001234 | ✓ |

## Backtrace Comparison
| Frame | GDB | Crash Log | Status |
|-------|-----|-----------|--------|
| #0 | main.c:125 | main.c:125 | ✓ |
| #1 | sensor.c:89 | sensor.c:89 | ✓ |

## Stack Analysis
- Stack pointer (MSP): 0x20003FFC (valid RAM range)
- Stack content near SP: [normal values, no corruption detected]

## Conclusions
- Call stack verified: matches crash log exactly
- No evidence of stack corruption
- Root cause confirmed: NULL pointer dereference in sensor_read()

Key Files Referenced

• domains/debugging/cmbacktrace.md — CmBacktrace library usage
• domains/debugging/hardfault.md — Cortex-M fault exception handling
• domains/debugging/gdb.md — GDB commands and configuration
• domains/debugging/crash_log_analysis.md — Crash log parsing
• debug/cmbacktrace_workflow.md — Step-by-step CmBacktrace workflow
• debug/templates/cmbacktrace_report.md — Report template
• debug/templates/gdb_session_report.md — GDB report template
• debug/gdb_safety_policy.md — Safety rules for live debugging
• debug/gdb_commands/stm32_hardfault.gdb — GDB script for HardFault analysis