From 1117a51af03e917b1e25476e265ef4f499f9634f Mon Sep 17 00:00:00 2001 From: Yusef Karim Date: Mon, 4 May 2020 10:13:46 -0400 Subject: [PATCH 1/4] Add appendix entry on how to use GDB --- src/SUMMARY.md | 1 + src/appendix/2-how-to-use-gdb/README.md | 87 +++++++++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 src/appendix/2-how-to-use-gdb/README.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 98746dd34..2ffb575ac 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -73,6 +73,7 @@ --- [General troubleshooting](appendix/1-general-troubleshooting/README.md) +[How to use GDB](appendix/2-how-to-use-gdb/README.md) diff --git a/src/appendix/2-how-to-use-gdb/README.md b/src/appendix/2-how-to-use-gdb/README.md new file mode 100644 index 000000000..d080118df --- /dev/null +++ b/src/appendix/2-how-to-use-gdb/README.md @@ -0,0 +1,87 @@ +# How to use GDB + +Below are some useful GDB commands that can help us debug our programs. This assumes you have [flashed a program](../../05-led-roulette/flash-it.md) onto your microcontroller and attached to an OpenOCD 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`. While you are learning GDB try to see how short you can get the commands to go before GDB doesn't recognize it! + + +### Dealing with Breakpoints + +* `break $location`: Set a breakpoint at a place in your code. The value of `$location` can include: + * `b 123` - Break on line 123 of the currently displayed file + * `b main.rs:123` - Break on line 123 of `main.rs` +* `info break`: Display current breakpoints +* `delete`: Delete all breakpoints + * `d $n`: Delete breakpoint `$n` +* `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 + * `en $n`: Enable breakpoint `$n` +* `disable`: Disable all set breakpoints + * `dis $n`: Disable breakpoint `$n` + +### Controlling Execution + +* `continue`: Begin execution of your program +* `next`: Execute the next line of your program + * `n $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 + * `s $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: + ```txt + x: hexadecimal + d: signed decimal + u: unsigned decimal + o: octal + t: binary + a: address + c: character + f: floating point + ``` + * `p /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` + * `disas /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 + * `i func main`: Print names and types of defined functions that contain the word `main` +* `info address $symbol`: Print where `$symbol` is stored in memory + * `i addr 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 + * `bt 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 + * `i reg $sp`: Print the value of the stack pointer register `$sp` in the current frame + +### Controlling OpenOCD Remotely + +* `monitor reset run`: Reset the CPU, starting execution over again + * `monitor reset`: Same as above +* `monitor reset init`: Reset the CPU, halting execution at the start +* `monitor targets`: Display information and state of current target From 75f40ba3a651ae598d00c7055199392a57625f53 Mon Sep 17 00:00:00 2001 From: Yusef Karim Date: Mon, 4 May 2020 10:22:56 -0400 Subject: [PATCH 2/4] Add link in 05-led-roulette/debug-it.md to GDB section --- src/05-led-roulette/debug-it.md | 3 ++- src/appendix/2-how-to-use-gdb/README.md | 2 +- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/src/05-led-roulette/debug-it.md b/src/05-led-roulette/debug-it.md index d38f4453c..4131dfca9 100644 --- a/src/05-led-roulette/debug-it.md +++ b/src/05-led-roulette/debug-it.md @@ -213,6 +213,7 @@ Ending remote debugging. [gdb-dashboard]: https://github.com/cyrus-and/gdb-dashboard#gdb-dashboard Don't close OpenOCD though! We'll use it again and again later on. It's better -just to leave it running. +just to leave it running. If you want to learn more about what GDB can do, check out the section [How to use GDB](../appendix/2-how-to-use-gdb). + What's next? The high level API I promised. diff --git a/src/appendix/2-how-to-use-gdb/README.md b/src/appendix/2-how-to-use-gdb/README.md index d080118df..21b1105eb 100644 --- a/src/appendix/2-how-to-use-gdb/README.md +++ b/src/appendix/2-how-to-use-gdb/README.md @@ -4,7 +4,7 @@ Below are some useful GDB commands that can help us debug our programs. This ass ## 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`. While you are learning GDB try to see how short you can get the commands to go before GDB doesn't recognize it! +> **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`. While you are learning GDB try to see how short you can get the commands to go before GDB doesn't recognize it! ### Dealing with Breakpoints From 8ad3866ac8fbadaa1412275db000aac55586ae31 Mon Sep 17 00:00:00 2001 From: Yusef Karim Date: Wed, 2 Sep 2020 12:33:45 -0400 Subject: [PATCH 3/4] Removed shortcuts and made slight change to top comment on shortcuts --- src/appendix/2-how-to-use-gdb/README.md | 32 +++++++++++++------------ 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/src/appendix/2-how-to-use-gdb/README.md b/src/appendix/2-how-to-use-gdb/README.md index 21b1105eb..f5c08645d 100644 --- a/src/appendix/2-how-to-use-gdb/README.md +++ b/src/appendix/2-how-to-use-gdb/README.md @@ -4,33 +4,35 @@ Below are some useful GDB commands that can help us debug our programs. This ass ## 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`. While you are learning GDB try to see how short you can get the commands to go before GDB doesn't recognize it! +> **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 it! ### Dealing with Breakpoints * `break $location`: Set a breakpoint at a place in your code. The value of `$location` can include: - * `b 123` - Break on line 123 of the currently displayed file - * `b main.rs:123` - Break on line 123 of `main.rs` + * `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 - * `d $n`: Delete breakpoint `$n` + * `delete $n`: Delete breakpoint `$n` * `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 - * `en $n`: Enable breakpoint `$n` + * `enable $n`: Enable breakpoint `$n` * `disable`: Disable all set breakpoints - * `dis $n`: Disable breakpoint `$n` + * `disable $n`: Disable breakpoint `$n` ### Controlling Execution -* `continue`: Begin execution of your program +* `continue`: Begin or continue execution of your program * `next`: Execute the next line of your program - * `n $n`: Repeat `next` `$n` number times + * `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 - * `s $n`: Repeat `step` `$n` number times + * `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 @@ -49,20 +51,20 @@ Below are some useful GDB commands that can help us debug our programs. This ass c: character f: floating point ``` - * `p /t 0xA`: Prints the hexadecimal value `0xA` as binary (0b1010) + * `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` - * `disas /r main`: Disassemble the function `main`, using `/r` to show the bytes that make up each instruction + * `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 - * `i func main`: Print names and types of defined functions that contain the word `main` + * `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 - * `i addr GPIOC`: Print the memory address of the variable `GPIOC` + * `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` @@ -70,14 +72,14 @@ Below are some useful GDB commands that can help us debug our programs. This ass ### Poking around the Program Stack * `backtrace $n`: Print trace of `$n` frames, or omit `$n` to print all frames - * `bt 2`: Print trace of first 2 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 - * `i reg $sp`: Print the value of the stack pointer register `$sp` in the current frame + * `info registers $sp`: Print the value of the stack pointer register `$sp` in the current frame ### Controlling OpenOCD Remotely From 93e70b2699e6f17b578a3149e81a95bb48d9eb44 Mon Sep 17 00:00:00 2001 From: Yusef Karim <48184686+yusefkarim@users.noreply.github.com> Date: Thu, 3 Sep 2020 07:05:52 -0400 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Diego Barrios Romero --- src/appendix/2-how-to-use-gdb/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/appendix/2-how-to-use-gdb/README.md b/src/appendix/2-how-to-use-gdb/README.md index f5c08645d..4153c6dcc 100644 --- a/src/appendix/2-how-to-use-gdb/README.md +++ b/src/appendix/2-how-to-use-gdb/README.md @@ -4,7 +4,7 @@ Below are some useful GDB commands that can help us debug our programs. This ass ## 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 it! +> **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 @@ -16,7 +16,7 @@ Below are some useful GDB commands that can help us debug our programs. This ass * `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` + * `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`