BeagleBone debugging with OpenOCD

The original BeagleBone (White) comes with a built-in JTAG emulator which allows you to debug your code without needing to go out and buy an expensive JTAG debugger. There's a neat tool called OpenOCD which, among many other things, can be used to debug code on your BeagleBone. I found that the few guides and tutorials available didn't work for me when I was trying to get it going, so I'm posting what I did in hopes that it'll help someone else and save them some time.

I did this on Gentoo Linux using OpenOCD 0.6.1, but similar steps should apply elsewhere. The first step is to install OpenOCD as well as usbutils. You'll need OpenOCD built with usb and ftd2xx support. In Gentoo, there are USE flags for this (USE="usb ftd2xx"). Connect your BeagleBone to your computer via USB, and then run `lsusb` as root. You should find a "Future Technology Devices International, Ltd FT2232C Dual USB-UART/FIFO IC" in the list (ID: 0403:6010). If you don't, then the driver isn't installed properly.

The next part is to configure OpenOCD. This is where I ran into problems. There is a default configuration script for the BeagleBone called ti_beaglebone.cfg. You specify it when you run OpenOCD like this `openocd -s /usr/share/openocd/scripts -f board/ti_beaglebone.cfg`. The '-s' is to specify the base of the scripts directory.


Unfortunately, as you can see above, the default script doesn't work out of the box. It prompts you to add a line for your device with this message: "Error: please add "ft2232_device_desc <string>" or "ft2232_serial <string>" to your .cfg file". It wasn't 100% clear how to find out the serial number or device description so I experimented. I found that if you put in a bogus serial number, it will list the available serial numbers. I added the following line to /usr/share/openocd/scripts/board/ti_beaglebone.cfg:

ft2232_serial "XXX"

Then I ran openocd...


From that list I found the serial number "TIWKAE5U A". I edited /usr/share/openocd/scripts/board/ti_beaglebone.cfg again with that serial number and executed `openocd -s /usr/share/openocd/scripts -f board/ti_beaglebone.cfg` again. This time it worked.


Once the OpenOCD server is up, you can connect to it via telnet on port 4444. From there you can issue commands. In the example below I display the value of the I2C revision of the first I2C controller.