Arduino/AVR GDB Cheat Sheet

List of common GDB commands for debugging AVR code.

Arduino/AVR GDB Cheat Sheet

Program Execution

Command Short form Description
continue c Run the program
advance setup adv setup Run the program and stop at the beginning of setup() *
next n Execute the next line of code (step over)
step s Step into the next line of code
finish fin Run the program until the current function returns (step out)
nexti n Execute the next instruction (step over)
stepi si Step into next instruction
until u Like next, but doesn't go back in loops
Ctrl+C Break the program at the current instruction

* The advance command will also stop if the current function returns

Breakpoints

Command Short form Description
info breakpoints i b Display a list of all the breakpoints
break loop b loop Set a breakpoint at the beginning of loop()
break 42 b 42 Set a breakpoint in line 42
break *0x156 b *0x156 Set a breakpoint at program address 0x156
tbreak loop tb loop Set a one-time (temporary) breakpoint in loop()
clear loop cl loop Delete any breakpoints on loop()
clear 42 cl 42 Delete any breakpoints on line 42
delete 1 d 1 Delete breakpoint number 1
disable dis Disable all breakpoints
disable 1 dis 1 Disable breakpoint number 1
enable en Enable all breakpoints
enable 1 en 1 Enable breakpoint number 1
enable once 1 en once 1 Enable breakpoint number 1 for a single hit

Call Stack

Command Short form Description
backtrace bt Display a backtrace of the current call stack
backtrace -full bt -fu Display backtrace including local variables
info args i ar Dump the arguments of the current function
info locals i lo Dump local variables and their values
info registers i r Dump MCU registers
faas info args fa i ar Dump the arguments of all functions in the call stack
frame 2 f 2 Select frame number 2
up Go one stack frame up (e.g. calling function)
down do Go one stack frame down

Inspecting Code

Command Short form Description
list loop l loop Show the source code of loop()
disassemble disas Disassemble the current program location
disassemble/s disas/s Disassemble including source code
disassemble/r disas/r Disassemble including opcodes (in hex)
disassemble loop disas loop Disassemble the loop() function

Inspecting Data

Command Short form Description
print $pc p $pc Print the value of PC (Program Counter)
print $r0 p $r0 Print the value of the R0 register
print i p i Print the value of the variable i
print PORTB p PORTB Print the value of the I/O register PORTB
dprint loop,"Loop\n" dp … Print "Loop" every time loop() starts
dprint loop,"%d\n",i dp … Print the value of i every time loop() starts
x/16b $sp Dump 16 memory bytes starting at $sp (stack pointer)
x/10w 0x800200 Dump 10 dwords starting at data space address 0x200
x/s 0x800151 Dump a string from the data space address 0x151
display someVar disp someVar Display the value of someVar whenever the program stops
info display i di List active auto-display (watch) expressions
delete display 1 d d 1 Delete auto-display expression number 1

Modifying Data

Command Short form Description
set i = 0 s i=0 Change the value of variable i to 0
set $pc = 0 s $pc=0 Jump to the beginning of the program
set $r12 = 0x55 s $r12=0x55 Set r12 to 0x55
set PORTB = 0xff s PORTB=0xff Set PORTB (I/O register) to 0xff
set {int}0x800200 = 50 s … Set an integer at dataspace address 0x200 to 50

Text User Interface (TUI)

Command Short form Description
tui enable tu e Enable the TUI mode (also Ctrl X+A)
tui disable tu d Disable the TUI mode (also Ctrl X+A)
tui reg all tu r a Display registers window
layout asm la a Switch to Assembly view
layout src la sr Switch to Source Code view
layout split la sp Switch to Split (Assembly + Source Code) view
update upd Show the current line in the Source Code window
Ctrl+L Redraw the screen

Other commands

Command Short form Description
(empty line) Repeat the previous command
help continue h c Show help about the "continue" command
help break h b Show help about the "break" command
help breakpoints h breakpoints Display a list of all breakpoint-related commands
quit q Exit GDB (in Wokwi Web GDB, GDB will restart)

Using GDB with the Wokwi Simulator

You can use the Wokwi simulator to play around with GDB and debug your Arduino code.

To start a GDB session, open any project on Wokwi (e.g. this Simon game), click on the code editor, and press F1. In the prompt that opens, type "GDB":

Then choose one of the options to launch GDB in a new browser tab. In general, the "debug build" is recommended for optimal debugging experience, but some libraries (e.g. FastLED) may not function correctly without the compiler optimizations.

I suggest to start with the "debug build", and switch to the "release build" only if the program doesn't work correctly.

The Web GDB app takes about 30 seconds to start for the first time, and should load within a few seconds after the first time.

When GDB is ready, it should print something like:

0x00000000 in __vectors ()
(gdb) 

At this point, you can write continue to start running the program, advance setup to run the program and stop at the beginning of the setup() function, or any other command from the GDB cheat sheet above.

P.S. if you are curious, here's how I got GDB to run in the browser.