Debugging with SWD, GDB, and Fault Handlers

  Debug toolchain:

  +-------+  GDB RSP   +---------+  USB  +--------+
  |  GDB  |<---------->| OpenOCD |<----->| ST-Link|
  | (PC)  | port 3333  | (PC)    |       | V2     |
  +-------+            +---------+       +---+----+
                                             |
                                          SWD (2 wires)
                                             |
                                         +---+------+
                                         | STM32    |
                                         | Cortex-M3|
                                         | (target) |
                                         +----------+

# Connect to OpenOCD
target remote localhost:3333

# Load firmware into flash
monitor reset halt
load

# Set a breakpoint at main
break main

# Start execution
continue

# Break when entering uart_send_string
break uart_send_string

# Conditional breakpoint: only when adc_value > 3000
break main.c:85 if adc_values[0] > 3000

# Temporary breakpoint (deleted after first hit)
tbreak process_command

# Delete all breakpoints
delete

# Break when 'counter' variable is written
watch counter

# Break when 'counter' is read
rwatch counter

# Break when memory at specific address is written
watch *(uint32_t*)0x20000100

# Useful for finding who corrupts a specific variable
watch stack_canary

# Examine the stack (16 32-bit words at current SP)
x/16xw $sp

# Examine the vector table
x/16xw 0x08000000

# Examine a peripheral register (e.g., RCC->CR)
x/xw 0x40021000

# Examine a struct
print *((GPIO_TypeDef*)0x40010800)

  HardFault stack frame (pushed by HW):

  Higher address (older data)
  +----------------+
  | xPSR           |  SP + 28
  +----------------+
  | PC (return)    |  SP + 24  <-- faulting
  +----------------+               instruction
  | LR             |  SP + 20
  +----------------+
  | R12            |  SP + 16
  +----------------+
  | R3             |  SP + 12
  +----------------+
  | R2             |  SP + 8
  +----------------+
  | R1             |  SP + 4
  +----------------+
  | R0             |  SP + 0
  +----------------+
  Lower address (SP after fault)

  In GDB: print/x stack_frame[6]
  gives the PC of the faulting instruction.

void HardFault_Handler(void) {
    __asm volatile (
        "TST   LR, #4          \n"  /* Check which stack was in use */
        "ITE   EQ               \n"
        "MRSEQ R0, MSP          \n"  /* Main stack pointer */
        "MRSNE R0, PSP          \n"  /* Process stack pointer */
        "B     hard_fault_handler_c \n"
    );
}

void hard_fault_handler_c(uint32_t *stack_frame) {
    volatile uint32_t r0  = stack_frame[0];
    volatile uint32_t r1  = stack_frame[1];
    volatile uint32_t r2  = stack_frame[2];
    volatile uint32_t r3  = stack_frame[3];
    volatile uint32_t r12 = stack_frame[4];
    volatile uint32_t lr  = stack_frame[5];
    volatile uint32_t pc  = stack_frame[6];  /* Faulting instruction */
    volatile uint32_t psr = stack_frame[7];

    /* Configurable Fault Status Register */
    volatile uint32_t cfsr = SCB->CFSR;
    volatile uint32_t hfsr = SCB->HFSR;
    volatile uint32_t mmfar = SCB->MMFAR;  /* Memory fault address */
    volatile uint32_t bfar = SCB->BFAR;    /* Bus fault address */

    /* Suppress unused variable warnings */
    (void)r0; (void)r1; (void)r2; (void)r3;
    (void)r12; (void)lr; (void)psr;
    (void)cfsr; (void)hfsr; (void)mmfar; (void)bfar;

    /*
     * In GDB, set a breakpoint here and examine:
     *   print/x pc    -> address of faulting instruction
     *   print/x lr    -> return address (caller)
     *   print/x cfsr  -> fault type bits
     *   info line *pc -> source file and line number
     */

    while (1);  /* Halt here for debugger */
}

# When the firmware hits the HardFault handler:
break hard_fault_handler_c

# After it breaks, examine the saved PC (faulting instruction)
print/x stack_frame[6]

# Look up which source line that address corresponds to
info line *0x08001A3C

# Examine the fault status registers
print/x *(uint32_t*)0xE000ED28    # CFSR
print/x *(uint32_t*)0xE000ED2C    # HFSR

# Examine the faulting address (if MemManage or BusFault)
print/x *(uint32_t*)0xE000ED34    # MMFAR
print/x *(uint32_t*)0xE000ED38    # BFAR

  ITM trace output path:

  Firmware            Cortex-M3 debug HW
  +---------+        +------------------+
  | ITM     |  write | ITM stimulus     |
  | PORT[0] |------->| port 0           |
  | .u8 = c |        +--------+---------+
  +---------+                  |
                               v
                        +------+------+
                        | TPIU        |
                        | (Trace Port)|
                        +------+------+
                               |
                            SWO pin (PB3)
                               |
                        +------+------+
                        | ST-Link V2  |
                        +------+------+
                               |
                        +------+------+
                        | OpenOCD     |
                        | /tmp/itm.fifo
                        +-------------+

/* Send a character via ITM stimulus port 0 */
void itm_putc(char c) {
    while (ITM->PORT[0].u32 == 0);  /* Wait until port is ready */
    ITM->PORT[0].u8 = (uint8_t)c;
}

void itm_puts(const char *str) {
    while (*str) {
        itm_putc(*str++);
    }
}

/* Bug: passing NULL */
sensor_config_t *config = NULL;
sensor_init(config);  /* Dereferences config->i2c_addr, causing HardFault */

/* Fix: initialize the struct */
sensor_config_t config = { .i2c_addr = 0x76, .oversample = 1 };
sensor_init(&config);

/* Bug: recursive call without base case */
void log_message(const char *msg) {
    if (log_buf_full()) {
        log_flush();
        log_message(msg);  /* Stack grows each time if flush fails */
    }
    /* ... */
}

/* Fix: use a loop instead of recursion */
void log_message(const char *msg) {
    if (log_buf_full()) {
        log_flush();
        if (log_buf_full()) return;  /* Drop message if still full */
    }
    /* ... */
}

/* Bug: enabling SPI1 clock instead of ADC1 */
RCC->APB2ENR |= RCC_APB2ENR_SPI1EN;

/* Fix: enable ADC1 clock */
RCC->APB2ENR |= RCC_APB2ENR_ADC1EN;

/* Bug: no synchronization */
oled_clear();           /* Writes to framebuffer */
draw_dashboard();       /* Writes to framebuffer */
oled_update_dma();      /* Starts DMA transfer */
/* Main loop immediately starts modifying framebuffer again */

/* Fix: wait for DMA transfer to complete before modifying buffer */
while (spi_dma_busy);   /* Wait for previous transfer */
oled_clear();
draw_dashboard();
oled_update_dma();

/* Bug: infinite wait if sensor not configured */
while (!(i2c_read_reg(BME280_ADDR, 0xF3) & 0x08));  /* Wait for data ready */

/* Fix: add timeout */
uint32_t start = systick_ms;
while (!(i2c_read_reg(BME280_ADDR, 0xF3) & 0x08)) {
    if ((systick_ms - start) > 100) {
        return SENSOR_TIMEOUT;  /* Bail out after 100 ms */
    }
    iwdg_feed();  /* Keep watchdog alive while waiting */
}