Skip to content
Tutorials Center
My learning

Topics

Lesson 32 of 37 ยท Debugging, Testing and Low Power

Debugging Embedded Systems

Learn the embedded debugging toolbox: SWD and JTAG probes, breakpoints, logging, logic analyzers, hard fault analysis, stack high-water marks and defensive techniques like assert and watchdogs.

Debugging firmware is different from debugging a desktop program. There is often no screen, no console and no file system. The bug may depend on timing, on a sensor's noise, or on an interrupt that fires once in a million cycles. Stopping the program at a breakpoint can hide the problem, because real hardware keeps running (a motor keeps spinning while your CPU is paused). A good embedded developer builds a toolbox and a habit: make the problem visible, then narrow it down.

This lesson surveys the tools, shows how to read a hard fault, and builds two practical techniques that you can use in any project: a stack high-water mark and a fault-register decoder.

The debug probe: JTAG and SWD

A debug probe (ST-Link, J-Link, CMSIS-DAP and others) connects your PC to the chip's debug port. Two protocols are common:

  • JTAG: a standard 4 or 5-wire interface (TCK, TMS, TDI, TDO, optional TRST) that can daisy-chain many devices; also used for boundary-scan testing of boards.
  • SWD (Serial Wire Debug): ARM's two-wire alternative (SWCLK and SWDIO), standard on Cortex-M, with the same abilities as JTAG for debugging.

Through the probe, the debugger (GDB with OpenOCD, or your IDE) can flash the firmware, halt and resume the CPU, read and write memory and registers, and set breakpoints and watchpoints. The debug logic sits in hardware, so it does not need any code on your side:

  • Breakpoints stop when the CPU fetches a given instruction. Chips have only a handful of hardware breakpoints (often 4 to 8) when code runs from flash, because flash cannot be rewritten for each one.
  • Watchpoints (data breakpoints) stop when a variable or address is read or written. They are the fastest way to find "who is overwriting my variable?"
  • Single-stepping and call stack inspection work as on a PC, but interrupts may keep firing as you step (check whether your debugger masks them).
  • Peripheral register views (SVD files) show the bits of the timers, UARTs and GPIOs in a readable form.

Ways to see what the program is doing

Technique How Cost / caveat
LED or GPIO toggle Set a pin at the start of a section and clear it at the end; watch with a scope or logic analyzer Almost free; measures timing exactly; great for ISR duration
printf over UART Retarget printf to a serial port Slow, uses stack and time, changes timing; avoid in ISRs
Semihosting The debugger services I/O calls Very slow, halts the CPU on each call; needs a debugger
SWO / ITM One-wire trace output on Cortex-M3 and up Fast, but needs a probe and a pin
SEGGER RTT Ring buffers in RAM read by the probe Fast, non-blocking, no pins
Event log in RAM Store event codes and timestamps in a ring buffer, dump on demand or after a crash Tiny, safe inside ISRs
Logic analyzer Records digital signals; decodes UART, SPI and I2C See what is really on the wires
Oscilloscope Shows analog quality: ringing, slow edges, noise, voltage dips Essential for power and signal-integrity problems
Trace (ETM) Hardware records every executed instruction Expensive tool, full history without stopping

The best tool depends on the bug. Timing problems need a pin and a scope; protocol problems need a logic analyzer; memory bugs need watchpoints and fault analysis; logic bugs often yield to a host-side unit test (see testing embedded code).

Reading a hard fault

When the CPU hits something illegal (an access to a non-existent address, an undefined instruction, a divide by zero on a core that traps it), a Cortex-M raises a fault exception. If you have no handler, you land in an infinite HardFault_Handler loop and the program appears dead. A useful handler captures the evidence:

  1. The stacked registers: the hardware pushes R0 to R3, R12, LR, PC and xPSR before entering the handler. The stacked PC is the address of the faulting (or next) instruction, and the stacked LR shows where the function was called from.
  2. The Configurable Fault Status Register (CFSR) at address 0xE000ED28: bits say what kind of fault it was.
  3. MMFAR and BFAR: the offending address, if the matching "valid" bit is set.

With the PC, you run arm-none-eabi-addr2line -e firmware.elf 0x08001234 (or look in the map file) to get the source line.

The decoder below turns a CFSR value into text. Bit positions follow the ARMv7-M architecture: the low byte is the memory-management fault status, the next byte the bus fault status, and the upper half-word the usage fault status.

C Decode a Cortex-M fault status register

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

Typical causes behind the usual fault types:

  • PRECISERR with a strange BFAR: a wild or null pointer, an array index out of range, or a peripheral whose clock is not enabled.
  • UNDEFINSTR or INVSTATE: a corrupted function pointer, a return address overwritten by a buffer overflow, or code built for the wrong core.
  • STKERR or a fault with an absurd stack pointer: stack overflow.
  • DIVBYZERO: you enabled the divide-by-zero trap and divided by zero.
  • UNALIGNED: a cast like *(uint32_t *)&buf[1] on a core that does not allow it.

Stack overflow: the silent killer

Each task and each interrupt context shares a fixed amount of stack. If you exceed it, the stack grows into neighboring memory (other variables, another task's stack), with effects that appear far from the cause. Two defenses:

  1. Fill the stack with a known pattern at startup (the "paint" trick). Later, scan from the bottom: the first word that is not the pattern marks the high-water mark, the deepest use so far.
  2. Place guard words (canaries) at the end of the stack and check them periodically. If a canary changes, the stack overflowed. Many RTOSes (FreeRTOS configCHECK_FOR_STACK_OVERFLOW) do this automatically.
C Stack painting and a canary guard

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.

In a real project, print or log the high-water mark of each task after running every feature, and aim to leave at least 25% spare. A mark that sits at 95% is one new feature away from a crash.

Defensive techniques

  • assert for conditions that must never be false: a null pointer parameter, an index range, an impossible state. In firmware, an assertion failure handler should capture the file and line, log it, and either halt in a debuggable loop (development) or reset into a safe state (production).
  • Watchdog timer (WDT). A hardware counter that resets the chip unless software "kicks" it regularly. Kick it from one place that proves the whole system is healthy (all tasks checked in), not from a timer interrupt, or a hung main loop keeps the watchdog happy. Record the reset cause at boot so you know a watchdog reset happened.
  • Compile with warnings on (-Wall -Wextra) and treat them as errors. Use static analyzers (clang-tidy, cppcheck) and follow a coding standard like MISRA C if your domain needs it.
  • Keep the debug build close to the release build. Optimization can change timing and expose bugs such as missing volatile. If a bug disappears at -O0, suspect undefined behavior or a data race, not the optimizer.
  • Read the errata. Chips have bugs too; vendors publish the list, and sometimes the bug is not yours.

A debugging routine

  1. Reproduce. Find the smallest steps that trigger the bug; add a counter or timestamp to see how often.
  2. Observe before changing. Capture a log, a scope trace, or a core dump first.
  3. Bisect. Disable half of the system (tasks, peripherals, interrupts) to find which half contains the bug.
  4. Check the hardware. Power rails, reset line, clock, pull-ups and connections cause more "software" bugs than you might think.
  5. Fix one thing, test, and write a regression test so it does not come back.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which tool tells you immediately which code writes to a corrupted global variable?

    A watchpoint halts the CPU on the exact instruction that writes the address.
  2. 2. On a Cortex-M hard fault, what does the stacked PC value tell you?

    Looking it up with addr2line or the map file gives the source line near the failure.
  3. 3. How does stack painting find the high-water mark?

    Untouched words keep the pattern, so the first changed word shows how deep the stack ever grew.
  4. 4. Why is toggling a GPIO pin useful for measuring an ISR's run time?

    Set the pin on entry and clear it on exit; the pulse width is the ISR duration, without printf's overhead.
  5. 5. Where should you kick a watchdog?

    Kicking from an ISR would hide a hung main loop. The kick should prove the system is really working.

Summary

  • A debug probe over SWD or JTAG gives breakpoints, watchpoints and memory access; pin toggles, RTT, ITM and logic analyzers show behavior without stopping the system.
  • A hard fault handler should capture the stacked PC, LR and the CFSR so you can find the faulting line.
  • Paint stacks and check canaries to measure and catch stack overflow; leave generous margin.
  • Use asserts, a properly fed watchdog, strict warnings and a disciplined reproduce, observe, bisect routine.

Next: Testing Embedded Code