How to use GDB

Below are some useful GDB commands that can help us debug our programs. This assumes you have flashed a program onto your microcontroller and attached GDB to a cargo-embed session.

General Debugging

NOTE: Many of the commands you see below can be executed using a short form. For example, continue can simply be used as c, or break $location can be used as b $location. Once you have experience with the commands below, try to see how short you can get the commands to go before GDB doesn't recognize them!

Dealing with Breakpoints

• break $location: Set a breakpoint at a place in your code. The value of $location can include:
  • break *main - Break on the exact address of the function main
  • break *0x080012f2 - Break on the exact memory location 0x080012f2
  • break 123 - Break on line 123 of the currently displayed file
  • break main.rs:123 - Break on line 123 of the file main.rs
• info break: Display current breakpoints
• delete: Delete all breakpoints
  • delete $n: Delete breakpoint $n (n being a number. For example: delete $2)
• clear: Delete breakpoint at next instruction
  • clear main.rs:$function: Delete breakpoint at entry of $function in main.rs
  • clear main.rs:123: Delete breakpoint on line 123 of main.rs
• enable: Enable all set breakpoints
  • enable $n: Enable breakpoint $n
• disable: Disable all set breakpoints
  • disable $n: Disable breakpoint $n

Controlling Execution

• continue: Begin or continue execution of your program
• next: Execute the next line of your program
  • next $n: Repeat next $n number times
• nexti: Same as next but with machine instructions instead
• step: Execute the next line, if the next line includes a call to another function, step into that code
  • step $n: Repeat step $n number times
• stepi: Same as step but with machine instructions instead
• jump $location: Resume execution at specified location:
  • jump 123: Resume execution at line 123
  • jump 0x080012f2: Resume execution at address 0x080012f2

Printing Information

• print /$f $data - Print the value contained by the variable $data. Optionally format the output with $f, which can include:

  x: hexadecimal
  d: signed decimal
  u: unsigned decimal
  o: octal
  t: binary
  a: address
  c: character
  f: floating point
  

  • print /t 0xA: Prints the hexadecimal value 0xA as binary (0b1010)

• x /$n$u$f $address: Examine memory at $address. Optionally, $n define the number of units to display, $u unit size (bytes, halfwords, words, etc.), $f any print format defined above

  • x /5i 0x080012c4: Print 5 machine instructions staring at address 0x080012c4
  • x/4xb $pc: Print 4 bytes of memory starting where $pc currently is pointing

• disassemble $location

  • disassemble /r main: Disassemble the function main, using /r to show the bytes that make up each instruction

Looking at the Symbol Table

• info functions $regex: Print the names and data types of functions matched by $regex, omit $regex to print all functions
  • info functions main: Print names and types of defined functions that contain the word main
• info address $symbol: Print where $symbol is stored in memory
  • info address GPIOC: Print the memory address of the variable GPIOC
• info variables $regex: Print names and types of global variables matched by $regex, omit $regex to print all global variables
• ptype $data: Print more detailed information about $data
  • ptype cp: Print detailed type information about the variable cp

Poking around the Program Stack

• backtrace $n: Print trace of $n frames, or omit $n to print all frames
  • backtrace 2: Print trace of first 2 frames
• frame $n: Select frame with number or address $n, omit $n to display current frame
• up $n: Select frame $n frames up
• down $n: Select frame $n frames down
• info frame $address: Describe frame at $address, omit $address for currently selected frame
• info args: Print arguments of selected frame
• info registers $r: Print the value of register $r in selected frame, omit $r for all registers
  • info registers $sp: Print the value of the stack pointer register $sp in the current frame

Controlling cargo-embed Remotely

• monitor reset: Reset the CPU, starting execution over again