Bfd Debug Interface

Log and Evidence Policy (Required)

• Save debug session logs and register snapshots under repository paths.
• Use:
  • logs/debug/ for session and register logs
  • logs/hw_error/ for fault records
• Do not keep final artifacts in /tmp.
• Fail-fast when .codex/bfd/active_profile.env is missing.

Tool Resolution

Quick Session (5 Steps)

1. Start GDB server.

JLinkGDBServerCLExe -device "${STM32_DEVICE}" -if "${STM32_IF}" -speed "${STM32_SPEED_KHZ}" -port 2331
# or
ST-LINK_gdbserver -p 61234 -m 1

2. Connect GDB.

arm-none-eabi-gdb "${STM32_ELF}"
(gdb) target remote localhost:2331
# or
(gdb) target remote localhost:61234

3. Initialize target.

(gdb) monitor reset halt
(gdb) load

4. Set critical breakpoints.

(gdb) break main
(gdb) break HardFault_Handler

5. Run and capture evidence.

(gdb) continue
(gdb) backtrace
(gdb) info registers

Full Command Reference

1) Connect and Load

target remote localhost:2331         connect to J-Link
target remote localhost:61234        connect to ST-Link
file ${STM32_ELF}                    load symbols
load                                 load program to target

2) Execution Control

run                          start execution (with load)
continue                     continue execution
continue <count>             continue, ignore count-1 breaks
step                         step into (source line)
stepi                        step into (instruction)
next                         step over (source line)
nexti                        step over (instruction)
finish                       run until function returns
until                        run until line/address
jump *0x08001000             jump to address

3) Breakpoint Management

Set Breakpoints

break main                    break at function
break file.c:123              break at line
break *0x08001234             break at address
break func if var > 10        conditional breakpoint
tbreak main                   temporary breakpoint
hbreak HardFault_Handler      hardware breakpoint
thbreak func                  temporary hardware breakpoint

Manage Breakpoints

info breakpoints              list all breakpoints
delete <num>                  delete breakpoint
disable <num>                 disable breakpoint
enable <num>                  enable breakpoint
clear main                    clear by function
clear file.c:123              clear by line
ignore <num> <count>          ignore breakpoint N times
condition <num> <expr>        set condition
commands <num>                on-hit command list
  > print var
  > continue
  > end

Hardware vs Software Breakpoints

4) Watchpoints and Variable Display

watch variable_name           break on write
rwatch variable_name          break on read
awatch variable_name          break on read/write
info watchpoints              list watchpoints
delete <num>                  delete watchpoint

print variable_name
print/x variable_name
print variable_name[0]@10
display variable_name
display/x variable_name
undisplay <num>

5) Register Read and Write

Core Registers

info registers
info all-registers
print $r0
print $pc
print $sp
print $lr
print $xpsr

Write Registers

set $r0 = 0x12345678
set $pc = 0x08001000
set $sp = 0x2001FFF0

Cortex-M Fault Registers

monitor memU32 0xE000ED28 1   CFSR
monitor memU32 0xE000ED2C 1   HFSR
monitor memU32 0xE000ED34 1   MMFAR
monitor memU32 0xE000ED38 1   BFAR

6) Memory Read and Write

Read

x/10x 0x20000000
x/20b 0x20000000
x/5i $pc
x/s 0x20001000
x/10wx 0x20000000

Format Specifiers

Write

set {int}0x20000000 = 0x12345678
set {char}0x20000000 = 0x55
set {short}0x20000000 = 0x1234
set {int[10]}0x20000000 = {0}

7) Stack and Call Chain Analysis

backtrace
backtrace full
frame <num>
info frame
info locals
info args
x/20x $sp

8) Flash, Reset, and Semihosting

Flash Programming

JLinkExe -device "${STM32_DEVICE}" -if "${STM32_IF}" -speed "${STM32_SPEED_KHZ}"
J-Link> loadfile firmware.hex
J-Link> r
J-Link> g

ST-LINK_CLI -P firmware.hex -V

Reset

monitor reset
monitor reset halt
monitor halt
monitor go

Semihosting

monitor semihosting enable
monitor semihosting disable

HardFault Playbook

1. Break at fault entry.

(gdb) break HardFault_Handler
(gdb) continue

2. Read core and fault status.

(gdb) info registers
(gdb) print/x *(uint32_t*)0xE000ED28   CFSR
(gdb) print/x *(uint32_t*)0xE000ED2C   HFSR
(gdb) print/x *(uint32_t*)0xE000ED34   MMFAR
(gdb) print/x *(uint32_t*)0xE000ED38   BFAR

3. Decode stack frame.

(gdb) x/8x $sp
R0, R1, R2, R3, R12, LR, PC, xPSR

4. Save evidence.

• logs/debug/hardfault_<timestamp>.log
• logs/hw_error/<date>/...

5. Hand off to bfd-fault-logger.

Error Detection and Auto-Trigger

RTT Keyword Monitor

Trigger Conditions

1. HardFault breakpoint is hit.
2. CFSR indicates BusFault-related bits.
3. Peripheral status registers expose error flags.
4. RTT stream contains high-risk keywords.

Minimal Automation Snippet

break HardFault_Handler
commands
  silent
  info registers
  print/x *(uint32_t*)0xE000ED28
  print/x *(uint32_t*)0xE000ED2C
  print/x *(uint32_t*)0xE000ED34
  print/x *(uint32_t*)0xE000ED38
  x/8x $sp
  continue
end

Context Fields for bfd-fault-logger

{
  "error_type": "HardFault|BusFault|PeripheralError|LogError",
  "timestamp": "<debug timestamp>",
  "registers": {
    "pc": "<program counter>",
    "lr": "<link register>",
    "sp": "<stack pointer>",
    "cfsr": "<fault status>",
    "hfsr": "<hard fault status>",
    "bfar": "<bus fault address>",
    "mmfar": "<memmanage fault address>"
  },
  "stack_trace": "<backtrace output>",
  "rtt_log": "<relevant log lines>",
  "peripheral": "<optional peripheral>"
}

Hard Rules

• Capture evidence before proposing fixes.
• Fault analysis must include core registers, fault registers, and stack context.
• Save session logs under logs/ subdirectories.
• Use bfd-rtt-logger for RTT capture to avoid session conflicts.
• Use bfd-fault-logger for structured fault archival.

Scripts

Reference Documentation

• references/debug-interface-reference.md

Related Skills

• bfd-project-init
• bfd-debug-executor
• bfd-fault-logger
• bfd-rtt-logger