Debugging Embedded Systems with JTAG/SWD

1. The Debugging Ecosystem: From Host to Target

Before typing any commands, it's crucial to understand the components that make on-chip debugging possible. The system is a chain of hardware and software working in concert.

The complete toolchain typically looks like this:

1. Host PC: Runs your development environment. This is where the GDB client runs.
2. GDB Client: This is the program you interact with (e.g., arm-none-eabi-gdb or the debugger integrated into your IDE). It understands your source code, symbol information from the ELF file, and provides the command interface for debugging.
3. GDB Server: A program like OpenOCD (Open On-Chip Debugger) or SEGGER J-Link GDB Server. It acts as a translator, converting GDB's high-level commands (e.g., "set a breakpoint at main") into low-level commands specific to the debug probe.
4. Debug Probe: The physical hardware (like an ST-Link or J-Link) that connects your PC's USB port to the target board. It translates the GDB server's commands into electrical signals for the JTAG or SWD interface.
5. Target MCU: The microcontroller being debugged. It contains a dedicated On-Chip Debug (OCD) module (part of the ARM CoreSight architecture, as shown above) that listens for JTAG/SWD signals and can halt the CPU, access registers, and read/write memory.

To see this entire system explained, please start with the following video.

The article "Debugging with JTAG" also provides an excellent textual summary and diagram of this client-server architecture.

2. The GDB Session: A Practical Walkthrough

While IDEs provide a graphical interface for debugging, they are fundamentally just front-ends for GDB. Understanding the underlying GDB commands is a powerful skill, especially for automation, scripting, and situations where you only have command-line access.

The following video demonstrates setting up a command-line session using OpenOCD and GDB.

With the session established, let's explore the core commands you'll use to debug your program.

Controlling Execution

Your primary tools for controlling the program flow are breakpoints and stepping commands.

Breakpoints vs. Watchpoints

• Breakpoint: Halts execution when the program counter (PC) reaches a specific address.
  • Hardware Breakpoints: Implemented in dedicated hardware comparators inside the CPU. They are very fast and can be placed anywhere, including in read-only memory (ROM). Their number is limited (e.g., 4-8 on many Cortex-M cores).
  • Software Breakpoints: Implemented by the debugger by replacing the instruction at the target address with a special BKPT instruction. When the CPU executes BKPT, it halts and enters debug mode. This requires the code to be in writable memory (RAM or Flash) and has a slight performance overhead. Debug probes like J-Link can manage "unlimited" software breakpoints by smartly swapping them in and out of flash memory.
• Watchpoint (or Data Breakpoint): Halts execution when a specific memory location is read or written. These are incredibly powerful for tracking down memory corruption bugs. They rely on hardware support and are usually very limited in number (e.g., 2-4).

Core GDB Commands:

The presentation slide below from Linaro provides a concise summary of essential GDB commands. We will refer to these as we proceed.

1. Setting Breakpoints:

   • break main or b main: Set a breakpoint at the entry of the main function.
   • b my_file.c:42: Set a breakpoint at line 42 of a specific file.
   • b my_function if x == 10: Set a conditional breakpoint that only triggers if the condition is true.
   • watch my_variable: Set a watchpoint that triggers whenever my_variable is written to.
   • info breakpoints / info watchpoints: List all active breakpoints and watchpoints.

2. Running and Stepping:

   • continue or c: Resume execution until a breakpoint/watchpoint is hit or the program ends.
   • next or n: Execute the current line and move to the next line, stepping over function calls.
   • step or s: Execute the current line, stepping into any function calls.
   • finish: Continue execution until the current function returns.
   • Ctrl+C: Halt program execution immediately.

Inspecting State

Once the program is halted, you can inspect its complete state.

1. Inspecting CPU Registers: This is critical for low-level debugging.

   • info registers or i r: Display the values of all core registers (e.g., r0-r12, sp, lr, pc, xpsr).
   • p/x $pc: Print the value of a specific register (in this case, the program counter in hex).

2. Inspecting Memory and Variables:

   • print my_variable or p my_variable: Print the current value of a variable. You can use formatting, e.g., p/x my_var (hex) or p/t my_var (binary).
   • info locals / info args: Display the values of local variables and function arguments in the current stack frame.
   • x/<n><f><u> <address>: The "examine" command is a power tool for viewing raw memory.
     • n: Number of units to display.
     • f: Format (x for hex, d for decimal, i for instruction, c for char).
     • u: Unit size (b for byte, h for half-word (16-bit), w for word (32-bit)).
     • Example: x/32xw 0x20000000 means "examine 32 words (w) in hexadecimal (x) starting at address 0x20000000".

3. Debugging Demonstration

Let's see these commands used in a practical context. The following video demonstrates a full debugging session in an IDE, which graphically exposes all the features we've just discussed with GDB commands.

Conclusion

In this lesson, we established the fundamental theory and practice of on-chip debugging. This is the bedrock upon which more advanced debugging techniques are built. Being able to confidently navigate a program's execution and inspect its state on-target is a mark of a senior embedded engineer.

Key Takeaways:

• The Debugging Stack: Debugging involves a client-server architecture: GDB Client ↔ GDB Server (OpenOCD) ↔ Debug Probe ↔ Target MCU.
• Physical Interfaces: JTAG and SWD are the primary electrical interfaces for connecting a debug probe to an ARM core's on-chip debug hardware.
• Execution Control: You can control program flow using breakpoints (halting on instruction execution) and watchpoints (halting on data access). You navigate code with commands like continue, next, step, and finish.
• State Inspection: When halted, you have full visibility into the system state via commands like info registers to see CPU registers, print to check variables, and examine (x) to inspect raw memory.

Preview of the Next Lesson:

Now that you're equipped with the tools to halt a program and inspect its state, we can tackle a classic and critical interview topic: debugging a system crash. In the next lesson, we will focus on this outcome: Perform a post-mortem hard fault analysis by reading the stacked exception frame (LR, PC, PSR) to find the faulting instruction. We will use the GDB skills learned today to decode the processor state immediately following a crash to pinpoint its root cause.