OpenOCD

Description

OpenOCD (the open on-chip debugger) is an open source tool for debugging and flashing microcontrollers. In RIOT we try to use this tool for as many platforms as possible to reduce the overhead of having to keep track of many different (and sometimes proprietary) tools.

Versions

Many of the boards supported by RIOT use top-edge hardware that is only supported by very recent versions of OpenOCD. The OpenOCD versions that come with Linux distributions (e.g. 0.7.0 in Mint 17) are mostly not up-to-date. For this reason we recommend that you manually build the current upstream version.

How to build/install

The following steps are for building and installing OpenOCD under Linux Mint 17. But this howto should work unchanged also for recent Ubuntu versions. For other Linux distributions the steps have to slightly altered, Windows is TODO.

Linux Ubuntu/Mint

1. Install prerequisites
   sudo apt-get install build-essential pkg-config autoconf automake libtool libusb-dev libusb-1.0-0-dev libhidapi-dev libftdi-dev
2. Clone the OpenOCD git repository
   git clone git://git.code.sf.net/p/openocd/code openocd
3. Switch into the directory
   cd openocd
4. Bootstrap the build environment
   ./bootstrap
5. Call configure. Make sure all devices are put to yes in the configuration summary. (libgpiod can be ignored if the host computer is not a SoC with exposed GPIO pins.) ./configure
6. Build the thing
   make
7. Install it
   sudo make install
8. Test if everything worked out properly
   openocd --version

This should give you the version you have just build, probably something like 0.9.0-dev-xxxx. Voila, that's it!

OS X

1. Using homebrew one can install the most recent version of openocd by
   brew install openocd --HEAD
2. Test if everything worked out properly
   openocd --version

This should give you the version you have just build, probably something like 0.9.0-dev-xxxx. Voila, that's it!

Problems & Fixes

When using OpenOCD on Mac OS X and you encounter an error similar to

Error: libusb_claim_interface() failed with LIBUSB_ERROR_ACCESS
Error: unable to open ftdi device with vid 0403, pid 6010, description '*' and serial '*'

make sure you are running make flash with sudo and that the system ftdi driver is unloaded:

From OpenOCD documentation ( source ):

If you're using a USB adapter and have a driver kext matched to it,
you will need to unload it prior to running OpenOCD. E.g. with Apple
driver (OS X 10.9 or later) for FTDI run:
  sudo kextunload -b com.apple.driver.AppleUSBFTDI
for FTDI vendor driver use:
  sudo kextunload FTDIUSBSerialDriver.kext

OpenOCD always return error even if flashing succeeded

The introduction of #2897 always return a failed flashing even if it actually succeeds.

We recommend to install an OpenOCD version higher than Open On-Chip Debugger 0.9.0-dev-gbdd8312 (2016-01-12-18:06), if possible version 0.10 or higher. A reference to this issue can be found at #6043.

Flashing with ST-Link

If you run the last released version of OpenOCD (0.10) instead of building yourself, you will have to specify the version of your ST-Link. The default is 2.1, if you are using an older adapter try to set

STLINK_VERSION=2

if you have the error Error: open failed.

The Makefile tells OpenOCD to do a reset on the board. If you have a simple ST-LINK adapter or the reset is not connected you can get the error: Error: jtag status contains invalid mode value - communication failure You can disable the reset via OpenOCD with the variable:

RSRT=none

This might require multiple retries or pushing the reset manually on the board just after starting the download.

Transports and board support

To figure out if a board is supported by OpenOCD it's best to a look on the scripts that come with OpenOCD. On Ubuntu/Mint these are put into /usr/local/share/openocd/scripts/. RIOT uses these OpenOCD scripts via its own Makefiles. You can find them in the ./RIOT/makefiles/tools/openocd-adapters/ directory.

udev rules

When using OpenOCD on Linux and you encounter something similar to

Error: libusb_open() failed with LIBUSB_ERROR_ACCESS
Error: no device found
Error: unable to open ftdi device with vid 0403, pid 6010, description 'FITECO M3' and serial '*'
in procedure 'init'

chances are you have to configure udev rules to work with the device. When built from source, OpenOCD provides examples in contrib/99-openocd.rules. Copy this file to your udev configuration directory make sure your vid and pid are covered and adjust the GROUP to some group you are part of.