Configuring OpenOCD for JTAG debugging

This tutorial explains various OpenOCD settings and shows how to configure it to use your JTAG programmer and board.

Before you begin please follow this tutorial to setup a basic VisualGDB project with OpenOCD.

  1. Open your project, right-click on the project node in Solution Explorer select “VisualGDB Project Properties” and open the “Debug Settings” page:01-dbgsettings
  2. For most of devices the configuration is easy: simply select the device type and the programming interface and press “Test selected OpenOCD settings” to verify the connection. However you can also switch to the manual setup mode and manually select the scripts used to configure OpenOCD:01b-manualOpenOCD supports 5 different types of configuration scripts:
    Script Description Example
    Interface Configures the JTAG programmer Olimex ARM-USB-OCD-H
    CPU Sets the target CPU (typically called by other scripts) ARM7TDMI
    Chip Provides information about a microcontroller family AT91SAM7X
    Board Specifies a known evaluation board (with known MCU) AT91SAM7-EK
    Target Specifies a microcontroller or an MCU family AT91SAM7X

    In order to get a minimal working configuration you typically need to specify an interface file and a board file that includes chip and target files. Alternatively you can specify the chip and target files manually.

  3. VisualGDB makes it easy to find the scripts for your interface and board. Simply press the search button and type the name of your board in the ‘filter’ box:02-at91
  4. Some JTAG debuggers require specifying the JTAG speed manually. You may encounter the following error while trying to debug your project:
    Error: An adapter speed is not selected in the init script. Insert a call to adapter_khz or jtag_rclk to proceed.
    in procedure 'init'

    If that happens, enable the “Explicitly specify JTAG speed” checkbox and set the JTAG speed. VisualGDB will prepend the “-c adapter_khz xxxx” command to the OpenOCD command line.03-jtagspeed

  5. If you receive the “target not halted” errors while trying to start debugging, the CPU, board or target script does not include a line resetting and halting the device. Please set the corresponding checkbox to let VisualGDB issue a corresponding command automatically.
  6. If you are using slightly different types or revisions of devices, you may need to customize the corresponding scripts. The scripts are essentially TCL files containing the relevant settings. E.g. the olimex-arm-usb-ocd-h.cfg contains the following lines:
    # Olimex ARM-USB-OCD-H
    interface ft2232
    ft2232_device_desc "Olimex OpenOCD JTAG ARM-USB-OCD-H"
    ft2232_layout olimex-jtag
    ft2232_vid_pid 0x15ba 0x002b

    A different revision of the device may have different Vendor/Device IDs and may need updating the file.

  7. At any moment you can use the “Test selected OpenOCD settings” button to let VisualGDB run OpenOCD and see whether it starts successfully with the parameters you have specified:04-test
  8. If OpenOCD reports that it cannot find your device, you may be missing the drivers. OpenOCD typically need one of the following drivers:
    • FTDI FT2232 drivers.
    • Libusb drivers.

    Both can be installed via the USB Driver Tool included with the OpenOCD package. You can determine which driver OpenOCD expects by analyzing its output or viewing the selected interface initalization script.

  9. Once your debugging session is active you can execute various OpenOCD commands by typing “mon <command>” in the GDB Session window. E.g. type “mon help” to let OpenOCD print information about supported commands. Note that the information will be shown in both OpenOCD pane and the GDB Session pane:05-help
  10. To learn more about OpenOCD please read the OpenOCD user manual.
  11. If you prefer solutions that work out-of-the-box, consider purchasing a JTAG programmer that has a vendor-provided GDB Server, such as Segger J-Link.