Over a million developers have joined DZone.

Debugging ARM Cortex-M Hard Faults with GDB Custom Command

DZone 's Guide to

Debugging ARM Cortex-M Hard Faults with GDB Custom Command

· Performance Zone ·
Free Resource

In “A Processor Expert Component to Help with Hard Faults” I’m using a C handler with some assembly code, created with Processor Expert, to help me with debugging hard faults on ARM Cortex-M. Inspired by a GNU gdb script here, I have now an alternative way. As this approach is using the GDB command line approach, it works both with an Eclipse GUI and with using GDB in command line mode only :-).

Image title

-- GDB script to debug ARM Hard Faults

The idea is:

  1. Set a breakpoint in the hard fault exception handler
  2. When a hard fault occurs, the CPU will call the hard fault exception handler, and the debugger will stop the target
  3. Execute the ‘armex’ (ARM Exception) script/command in GDB to dump the stacked registers to show the program counter where the problem happened.

.gdbinit Script

There are several ways to extend GDB with own commands. One easy way is to add the extra functions into the .gdbinit scrip which is loaded by GDB on startup.

I have added the following to my .gdbinit file to define my ‘armex’ command:

define armex
  printf "EXEC_RETURN (LR):\n",
  info registers $lr
    if $lr & 0x4 == 0x4
    printf "Uses MSP 0x%x return.\n", $MSP
    set $armex_base = $MSP
    printf "Uses PSP 0x%x return.\n", $PSP
    set $armex_base = $PSP
    printf "xPSR            0x%x\n", *($armex_base+28)
    printf "ReturnAddress   0x%x\n", *($armex_base+24)
    printf "LR (R14)        0x%x\n", *($armex_base+20)
    printf "R12             0x%x\n", *($armex_base+16)
    printf "R3              0x%x\n", *($armex_base+12)
    printf "R2              0x%x\n", *($armex_base+8)
    printf "R1              0x%x\n", *($armex_base+4)
    printf "R0              0x%x\n", *($armex_base)
    printf "Return instruction:\n"
    x/i *($armex_base+24)
    printf "LR instruction:\n"
    x/i *($armex_base+20)
document armex
ARMv7 Exception entry behavior.
xPSR, ReturnAddress, LR (R14), R12, R3, R2, R1, and R0

You can place the .gdbinit file anywhere. I have it placed where my gdb is located inside the Freescale Kinetis Design Studio (C:\Freescale\KDS_3.0.0\toolchain\bin).

To make sure GDB finds the .gdbinit, I specify the path to it in the Eclipse workspace preferences:

Image title

-- GDB Command File in Eclipse Workspace Preferences

Debugging Hard Fault

To debug a hard fault, I set a breakpoint in my hard fault interrupt handler to stop the debugger when the fault happens:

Image title

-- stopped on hard fault

To find out where the problem occurred, I use now the ‘armex’ command in the gdb console:

    Use the ‘triangle’ menu of the console to switch to the arm-none-eabi-gdb view

Image title

-- armex command in gdb console

The armex command lists the stacked registers (same as with my handler shown in “Debugging Hard Faults on ARM Cortex-M“). The important information is either the return instruction or the LR instruction information. I can enter that address in the disassembly view to find out where the problem happened:

Disassembly View of Hard Fault Reason

In the above example, the LR (Link Register or Return Address) was 0xbd2 (0xbd3 with the Thumb Bit set). In the disassembly view this is the address where the handler would return to, so the problem must be just before that. Checking the assembly code there is a branch register indirect

blx r3

The stacked register shows

R3              0x0

Which causes the hard fault. If the problem is not that clear, then simply set a breakpoint around that location and restart the application to debug what happens before the hardfault is triggered. With this, it should be hopefully easy to find and fix the problem.


I have now yet another way to debug my hard faults: using my custom gdb command to dump the stacked registers. The advantage of this approach is that it does not need any additional resources on the target (no extra handler in the code and no variables), compared to my earlier solution. And the added benefit is now that I know how to extend GDB with my custom commands :-).

performance ,iot ,debugging

Published at DZone with permission of

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}