arm-none-eabi-gdb
Embedded Debugging Mastery

# OpenOCD (ST-LINK v2/v3 on-board or standalone) — GDB port 3333
openocd -f interface/stlink.cfg -f target/stm32l4x.cfg

# texane/stlink st-util — GDB port 4242
st-util

# SEGGER J-Link — GDB port 2331, device name is mandatory
JLinkGDBServer -device STM32L4R5ZI -if SWD -speed 4000

# ST official ST-LINK GDB server (ships with STM32CubeIDE) — default port 61234
# -cp points at the STM32CubeProgrammer bin dir it needs for flashing
ST-LINK_gdbserver -p 61234 -e -d -cp /opt/st/stm32cubeide/.../tools/bin

arm-none-eabi-gdb build/firmware.elf

(gdb) target extended-remote localhost:3333   # OpenOCD
# (gdb) target extended-remote localhost:4242   # st-util
# (gdb) target extended-remote localhost:2331   # J-Link

(gdb) monitor reset halt        # 'monitor' forwards a raw command to the server
(gdb) info registers pc sp      # confirm the core is halted and reachable

(gdb) monitor reset halt          # stop the core before touching flash
(gdb) load                         # program all LOAD sections into flash @ 0x08000000
Loading section .isr_vector, size 0x30c lma 0x8000000
Loading section .text, size 0x5f14 lma 0x800030c
Loading section .data, size 0x88   lma 0x8006220
Start address 0x0800030c, load size 25228

(gdb) compare-sections             # read back flash and diff against the ELF
Section .text: matched.

(gdb) monitor reset halt           # re-run the vector table / SP from the fresh image
(gdb) break main
(gdb) continue

# st-flash writes a raw binary at an absolute address (flash base = 0x08000000)
arm-none-eabi-objcopy -O binary firmware.elf firmware.bin
st-flash write firmware.bin 0x08000000

# OpenOCD one-shot: program + verify + reset + exit
openocd -f interface/stlink.cfg -f target/stm32l4x.cfg \
        -c "program firmware.elf verify reset exit"

# J-Link via GDB script (see .gdbinit section) or J-Flash

(gdb) break main                 # by symbol
(gdb) break usart.c:142          # by file:line
(gdb) break *0x08001a3c          # by absolute address
(gdb) break HardFault_Handler    # by handler name

(gdb) tbreak SystemInit          # temporary: auto-deletes after first hit
(gdb) hbreak process_packet      # FORCE a hardware (FPB) breakpoint

(gdb) info breakpoints           # list, with hit counts
(gdb) delete 2                   # remove breakpoint #2
(gdb) disable 3                  # keep but deactivate

# conditional + counted breakpoints (evaluated on-target each pass)
(gdb) break adc_isr if channel == 7
(gdb) condition 4 count > 100
(gdb) ignore 4 50                # skip the next 50 hits of bp #4

# run a command list automatically at a breakpoint
(gdb) commands 1
> printf "tick=%u sp=0x%08x\n", g_ticks, $sp
> continue
> end

(gdb) watch  g_state            # break on WRITE to g_state
(gdb) rwatch g_state            # break on READ
(gdb) awatch g_state            # break on READ or WRITE (access)

# watch a raw address — perfect for "who is corrupting this?"
(gdb) watch *(uint32_t*)0x20000100

# scope-limited: only while a local is live
(gdb) watch buf[i] if i == 3

(gdb) continue
Hardware watchpoint 2: g_state
Old value = 0
New value = 3
process_event () at events.c:88

(gdb) next        / n     # step over — do not descend into calls
(gdb) step        / s     # step into — descend into called function
(gdb) nexti       / ni    # step over one machine instruction
(gdb) stepi       / si    # step into one machine instruction
(gdb) finish              # run until current function returns, print retval
(gdb) until 210           # run until source line 210 (skips loop iterations)
(gdb) continue    / c     # resume until next breakpoint / fault
(gdb) return 0            # force-return from current frame (careful!)

(gdb) backtrace   / bt     # full call chain, innermost first
#0  i2c_wait_flag (tmo=1000) at i2c.c:73
#1  0x08002c1a in i2c_write (addr=80) at i2c.c:120
#2  0x08003044 in sensor_read () at bme280.c:55
#3  0x080008e0 in main () at main.c:64

(gdb) bt full             # backtrace + every frame's local variables
(gdb) frame 2   / f 2     # select frame #2 (sensor_read)
(gdb) up                  # move one frame toward main
(gdb) down                # move one frame toward the fault
(gdb) info args           # arguments of the selected frame
(gdb) info locals         # locals of the selected frame
(gdb) info frame          # CFA, saved regs, return address of this frame

(gdb) x/8xw 0x20000000        # 8 words of SRAM1 in hex
(gdb) x/16xb &rx_buffer       # 16 raw bytes of a buffer
(gdb) x/s device_name         # a C string
(gdb) x/t 0x48000010          # GPIOA_IDR as binary
(gdb) x/8i $pc                # disassemble 8 instructions at PC
(gdb) x/i $pc                 # the exact instruction about to execute

# print expressions with explicit format
(gdb) p/x $lr                 # link register in hex
(gdb) p/t status_reg          # a variable in binary
(gdb) p (rx_len * 2) + 1      # arithmetic on target values
(gdb) p sizeof(struct config) # types resolved from DWARF

(gdb) info registers          # r0-r12, sp, lr, pc, xpsr
(gdb) info all-registers      # + FPU s0-s31, fpscr, and special regs
(gdb) info registers pc sp lr # just these three

# Cortex-M special registers (exposed by OpenOCD)
(gdb) p/x $msp                # Main stack pointer
(gdb) p/x $psp                # Process stack pointer
(gdb) p/x $primask            # global IRQ mask (1 = IRQs off)
(gdb) p/x $basepri            # priority threshold mask
(gdb) p/x $faultmask
(gdb) p/x $control            # bit0 nPRIV, bit1 SPSEL, bit2 FPCA

# write a register (e.g. redirect execution or fix a stuck flag)
(gdb) set $pc = 0x08001a3c
(gdb) set $r0 = 0
(gdb) set var g_error_flag = 0
(gdb) set *(uint32_t*)0x20000100 = 0xDEADBEEF

# Is the GPIOA clock even enabled? RCC_AHB2ENR = 0x40021000 + 0x4C, bit0 = GPIOAEN
(gdb) p/t *(uint32_t*)0x4002104C
$1 = 1                          # bit0 set -> GPIOA clocked. If 0, your writes do nothing.

# Read GPIOA_MODER, check PA5 (LED) is output (bits [11:10] = 01)
(gdb) x/t 0x48000000

# Read the pin levels on port A
(gdb) x/t 0x48000010            # GPIOA_IDR

# Toggle PA5 atomically via BSRR (set bit 5)
(gdb) set *(uint32_t*)0x48000018 = (1 << 5)      # BS5: drive high
(gdb) set *(uint32_t*)0x48000018 = (1 << 21)     # BR5: drive low

# Read a USART2 status/data register set (base 0x40004400)
(gdb) x/8xw 0x40004400          # ISR/RDR/TDR/BRR... dump the block

# Free-running cycle counter for micro-benchmarks (must enable DWT first)
(gdb) p/d *(uint32_t*)0xE0001004   # DWT_CYCCNT

(gdb) p/x *(uint32_t*)0xE000ED28      # CFSR
$1 = 0x00000082                        # MMFSR: DACCVIOL(1) + MMARVALID(7) -> bad data access
(gdb) p/x *(uint32_t*)0xE000ED2C      # HFSR
$2 = 0x40000000                        # FORCED -> escalated from the config fault above
(gdb) p/x *(uint32_t*)0xE000ED34      # MMFAR = the address that faulted
$3 = 0x00000000                        # NULL-pointer write

# Which SP was in use on entry? EXC_RETURN (in $lr) bit 2: 0 = MSP, 1 = PSP
(gdb) p/x $lr
$4 = 0xfffffff9                        # ...9 -> returns to MSP, thread mode

# The 8-word exception frame sits at that SP. Dump it:
(gdb) x/8xw $msp
(gdb) set $frame = (uint32_t*)$msp
(gdb) printf "stacked PC  = 0x%08x\n", $frame[6]   # the faulting instruction
(gdb) printf "stacked LR  = 0x%08x\n", $frame[5]
(gdb) printf "stacked xPSR= 0x%08x\n", $frame[7]
(gdb) list *$frame[6]                  # jump to the guilty source line

#include <stdint.h>

/* Fault sub-registers, architectural addresses (ARMv7-M). */
#define SCB_CFSR  (*(volatile uint32_t*)0xE000ED28u)
#define SCB_HFSR  (*(volatile uint32_t*)0xE000ED2Cu)
#define SCB_MMFAR (*(volatile uint32_t*)0xE000ED34u)
#define SCB_BFAR  (*(volatile uint32_t*)0xE000ED38u)

typedef struct {
    uint32_t r0, r1, r2, r3, r12, lr, pc, xpsr;
} ExcFrame;

/* Set a GDB breakpoint here, or log the fields, then inspect. */
void hard_fault_report(ExcFrame *ctx)
{
    volatile uint32_t cfsr  = SCB_CFSR;   /* why */
    volatile uint32_t hfsr  = SCB_HFSR;   /* escalated? */
    volatile uint32_t mmfar = SCB_MMFAR;  /* valid iff CFSR bit7  */
    volatile uint32_t bfar  = SCB_BFAR;   /* valid iff CFSR bit15 */
    (void)cfsr; (void)hfsr; (void)mmfar; (void)bfar;
    (void)ctx;                            /* ctx->pc = faulting instruction */
    __asm volatile ("bkpt #0");           /* trap into the debugger */
    for (;;) { }
}

__attribute__((naked)) void HardFault_Handler(void)
{
    __asm volatile (
        "tst  lr, #4          \n"   /* EXC_RETURN bit2: 0=MSP, 1=PSP  */
        "ite  eq              \n"
        "mrseq r0, msp        \n"
        "mrsne r0, psp        \n"
        "b    hard_fault_report\n"
    );
}

(gdb) tui enable            # or start gdb with:  arm-none-eabi-gdb -tui
(gdb) layout src           # source + command panes
(gdb) layout asm           # disassembly pane
(gdb) layout regs          # registers pane on top of src/asm
(gdb) layout split         # source AND disassembly together
(gdb) focus cmd            # send arrow keys to the command window
(gdb) focus src            # scroll the source window instead

# keybindings
#   Ctrl-x a   toggle TUI on/off
#   Ctrl-x 1   single window
#   Ctrl-x 2   two windows (cycle)
#   Ctrl-l     redraw (fixes a garbled screen)
#   Ctrl-p/Ctrl-n  command history while a non-cmd window has focus

set pagination off
set confirm off
set print pretty on
set history save on

# --- connect + reset + flash in one word ---
define reload
  monitor reset halt
  load
  monitor reset halt
end
document reload
  Reset target, reflash the current ELF, reset again.
end

# --- dump the Cortex-M fault registers by name ---
define faultregs
  printf "CFSR  = 0x%08x\n", *(unsigned int*)0xE000ED28
  printf "HFSR  = 0x%08x\n", *(unsigned int*)0xE000ED2C
  printf "MMFAR = 0x%08x\n", *(unsigned int*)0xE000ED34
  printf "BFAR  = 0x%08x\n", *(unsigned int*)0xE000ED38
  printf "SHCSR = 0x%08x\n", *(unsigned int*)0xE000ED24
end

# --- decode GPIOA by name (base 0x48000000) ---
define gpioa
  printf "MODER=0x%08x  IDR=0x%04x  ODR=0x%04x\n", \
    *(unsigned int*)0x48000000, \
    *(unsigned int*)0x48000010, \
    *(unsigned int*)0x48000014
end

# --- auto-print PC + instruction every time we stop ---
define hook-stop
  printf "-- stopped @ 0x%08x --\n", $pc
  x/i $pc
end

# --- connect on startup ---
target extended-remote localhost:3333
monitor reset halt
load
break main
tui enable
layout src