GDB, the GNU Project Debugger is a debugging tool provided with the GNU Compiler Collection (GCC). GDB allows you to stop and start a running program, examine its functioning, and make changes.
GDB Support in OpenOCD
The configure script provided with OpenOCD 0.5.0 already compiles OpenOCD to support the GDB debugger. If you have installed OpenOCD according to the guides on the Compiling OpenOCD page, your version of OpenOCD already supports GDB.
The -g flag tells the gcc compiler to build with GDB support. OpenOCD's configure script already includes the -g flag.
You will need to download or compile a version of GDB that supports embedded devices. One such GDB build is provided with the CodeSourcery ARM toolchain.
Installing the CodeSourcery ARM Toolchain
CodeSourcery provides development tools for use with embedded devices, including a GCC cross-compiler and a GDB build for ARM targets. Download the latest version of the .bin installer from http://www.codesourcery.com/sgpp/lite/arm/portal/release1592. Direct link to the Windows installer is here.
Download and run the installer. You should see a loading bar followed by an installer GUI. The installer is fairly straightforward. This guide will assume that you choose the default option on each page.
The installer installs the CodeSourcery toolchain, by default to C:\Program Files\CodeSourcery\Sourcery G++ Lite (or C:\Program Files (x86)\CodeSourcery\Sourcery G++ Lite on 64-bit Windows). It also adds this path to your system PATH variable so you can run arm-none-eabi-gdb and other tools from any directory.
In the windows command console, type arm-none-eabi-gdb and press Enter. You can do this from any directory. If you're unsure how to open the Windows command console, see Running OpenOCD on Windows. You can also run GDB directly from "Run" in the Start menu.
Either way you should look like the image below, with a prompt reading (gdb) in place of the normal > command prompt.
Connecting to OpenOCD
Run OpenOCD as normal, as described in Running OpenOCD on Windows. To connect to OpenOCD, start GDB as above:
OpenOCD listens for GDB connections on port 3333. In GDB, connect to OpenOCD by typing target remote localhost:3333. (In this guide if you see (gdb) at the beginning of a command, that means enter that line into the GDB command prompt. Don't actually type the characters (gdb).)
(gdb) target remote localhost:3333
Before doing anything else, run reset init on the target. Use the monitor command to tell GDB to send the command to OpenOCD, like this:
(gdb) monitor reset init
This is important. You need to do this while GDB is connected to the OpenOCD, or you won't be able to halt or reset the target. If you don't run monitor reset init, you will encounter errors like this:
Sending Commands to OpenOCD
You can send commands to OpenOCD through GDB just like you can through a telnet connection. Type monitor, then the command, then enter. You can see a list of common OpenOCD commands here.
You can use the Linux command cd to change the current working directory in GDB. This changes the current directory only for GDB, not for Linux; when you exit GDB, you will be back in the directory where you started.
To quit GDB, type quit.
Instead of typing commands yourself every time you start GDB, you can create a script to always start GDB with the same series of commands. This script file is named .gdbinit. GDB looks for it in the current working directory.
You can use the script below to have GDB automatically connect to OpenOCD and run reset init on the target. Create a new folder on your C:\ drive called GDB_OpenOCD_init, and create a new text file in that folder. Copy the code below into the file:
echo Executing GDB with .gdbinit to connect to OpenOCD.\n # Connect to OpenOCD target remote localhost:3333 # Reset the target and call its init script monitor reset init # Halt the target. The init script should halt the target, but just in case monitor halt
Save the file as .gdbinit and close it. Note that in Windows Explorer you can't give a file a name that begins with a period. You will need to save it with the name .gdbinit from within a text editor. Alternatively, name the file gdbinit without a period and then rename it from the command line:
cd C:\GDB_OpenOCD_init move gdbinit .gdbinit
To test the init script, start OpenOCD as normal. Then in the command line, navigate to C:\GDB_OpenOCD_init and run CodeSourcery GDB.
cd C:\GDB_OpenOCD_init arm-none-eabi-gdb
You should see something like the image below. (In this image the target device is the Beagleboard. With different hardware the output of reset init will be different.)