Build and Run OpenOCD on Windows 10 with Cygwin

We show how to build OpenOCD from source on Windows 10 using a Cygwin environment. The JTAG controller is an FTDI FT2232H on our Darsena development board for network security.

updated: Feb 03, 2021

Overview

We utilize an NXP Kinetis K02 microcontroller on Darsena, and the board has integrated hardware debug support utilizing an FTDI FT2232H device configured as a USB-based JTAG controller. We use OpenOCD to enable communication between a GDB debugger and the FT2232H device.

This article explains how we build & use OpenOCD on Windows 10 for Darsena in a Cygwin environment.

OpenOCD (On-Chip Debugger) is an excellent open source, community project for debugging and programming of embedded processors and FPGAs.

The FT2232H is a USB 2.0 Hi-Speed (480Mb/s) UART/FIFO/JTAG device. It has the capability of being configured in a variety of industry standard serial or parallel interfaces, and we use it on Darsena as a dual JTAG controller for both the NXP K02 and a Lattice ECP5UM FPGA.¹

The NXP Kinetis K02 integrates an ARM Cortex M4 (ARMv7) and provides the following interfaces: I2C, SPI, UART, ADC, and DAC, all of which are utilized on Darsena.

JTAG is a 4-wire protocol defined by the IEEE (Std 1149.1-2013). The signals that comprise the Test Access Port (TAP) are TCK, TMS, TDI, and TDO. Various implementations also make use of additional pins for test and programming (i.e., TRST). Support of these additional signals can be accomplished with the FT2232 device through general purpose I/Os.

For an IDE, we use either NXP's MCUXpresso or the mainline Eclipse. In either case, we configure OpenOCD operation the same, which is described below.

Install Cygwin

We build & run OpenOCD in a Cygwin shell. Cygwin is an excellent solution for having a Linux environment on a Windows 10 OS. In addition to OpenOCD, we use it extensively as an X windows server and secure shell (SSH) for networking with Linux PCs from a Windows desktop.

Installation of Cygwin is straight forward, but choosing the right packages can be tricky. We suggest that you follow the instructions on the Cygwin homepage, and here is a summary of the steps we use:

Download and run/install setup-x86_64.exe (64-bit installation).
Choose "Install from Internet" as the download source.
Install the packages listed below.
Let the installer create a Cygwin terminal on the Desktop and then launch the terminal / shell after installer finishes

Cygwin Devel packages to install:

autobuild
autoconf
autoconf-archive
automake
dos2unix
git
gcc-core
libtool
libusb1.0
libusb1.0-devel
make
pkg-config
usbutils

Build OpenOCD from Source / Git Repo

From the Cygwin terminal:

$ mkdir -p /build; cd /build
$ git clone https://git.code.sf.net/p/openocd/code  openocd
Cloning into 'openocd'...
remote: Enumerating objects: 60802, done.
remote: Counting objects: 100% (60802/60802), done.
...

Let's examine what we now have.

$ cd openocd
$ git log
commit c69b4deae36a7bcbab5df80ec2a5dbfd652e25ac (HEAD -> master, origin/master, origin/HEAD)
Author: Antonio Borneo 
Date:   Sat Dec 19 22:31:29 2020 +0100

    gdb_server: fix HW thread status at gdb attach

    At gdb attach, the event TARGET_EVENT_GDB_ATTACH is in charge of
    halting the target.
    For HW thread, rtos_update_threads() should be called after the
    event to detect and record the new 'halted' status. Instead it is
    called immediately before the event, thus reading the status
    before the halt.

    Move after the event the call to rtos_update_threads().

    Change-Id: Iab3480ea0f5283ed6580f0f6c11200083197d1e9
    Signed-off-by: Antonio Borneo 
    Reviewed-on: http://openocd.zylin.com/5983
    Tested-by: jenkins

Now we'll build OpenOCD in it's own build sub-directory after we initialize the tools:

$ cd /build/openocd/

$ ./bootstrap
./bootstrap: line 3: $'\r': command not found
: invalid optione 5: set: -
set: usage: set [-abefhkmnptuvxBCHP] [-o option-name] [--] [arg ...]

$ dos2unix.exe bootstrap
dos2unix: converting file bootstrap to Unix format...

$ dos2unix configure.ac
$ dos2unix Makefile.am

$ ./bootstrap
$ ./bootstrap
+ aclocal --warnings=all
+ libtoolize --automake --copy
+ autoconf --warnings=all
+ autoheader --warnings=all
+ automake --warnings=all --gnu --add-missing --copy
...
Bootstrap complete. Quick build instructions:
./configure ....

$ mkdir build
$ cd build
$ ../configure --enable-ftdi
...
OpenOCD configuration summary
--------------------------------------------------
MPSSE mode of FTDI based devices        yes
ST-Link Programmer                      yes (auto)
TI ICDI JTAG Programmer                 yes (auto)
Keil ULINK JTAG Programmer              yes (auto)
Altera USB-Blaster II Compatible        yes (auto)
Bitbang mode of FT232R based devices    yes (auto)
Versaloon-Link JTAG Programmer          yes (auto)
TI XDS110 Debug Probe                   yes (auto)
CMSIS-DAP v2 Compliant Debugger         yes (auto)
OSBDM (JTAG only) Programmer            yes (auto)
eStick/opendous JTAG Programmer         yes (auto)
Andes JTAG Programmer                   yes (auto)
USBProg JTAG Programmer                 no
Raisonance RLink JTAG Programmer        no
Olimex ARM-JTAG-EW Programmer           no
CMSIS-DAP Compliant Debugger            no
Nu-Link Programmer                      no
Cypress KitProg Programmer              no
Altera USB-Blaster Compatible           no
ASIX Presto Adapter                     no
OpenJTAG Adapter                        no
Linux GPIO bitbang through libgpiod     no
SEGGER J-Link Programmer                yes (auto)


$ make

$ make install

$ which openocd
/usr/local/bin/openocd

Configuring OpenOCD Operation with Darsena

You'll want to connect your Windows PC to Darsena via a USB cable and provide power to the unit. See the figure below and Getting Started with Darsena for more details. Keep in mind that the K02 is connected to the second port (B) of the FTDI FT2232H. Also, Darsena utilizes the FTDI device without a dedicated external ROM, so its signature remains the device's factory default:

$ lsusb | grep FT2232

Bus 002 Device 002: ID 0403:6010 Future Technology Devices International, Ltd FT2232C Dual USB-UART/FIFO IC

Figure 1. Darsena connected for OpenOCD Debugging

Create "darsena.cfg" in /build/openocd/tcl/interface/ftdi. Note that we specify "ftdi_channel 1" for Port B.

#
# Darsena
#

interface ftdi
ftdi_channel 1
ftdi_vid_pid 0x0403 0x6010

# Every pin set as high impedance except TCK, TDI, TDO and TMS
ftdi_layout_init 0x0008 0x000b

# nSRST defined on pin CN2-13 of the MiniModule (pin ADBUS5 [AD5] on the FT2232H chip)
# This choice is arbitrary. Use other GPIO pin if desired.
ftdi_layout_signal nSRST -data 0x0020 -oe 0x0020

Also, create a launch script (k02.sh) in /build/openocd:

#!/bin/sh

openocd -f tcl/interface/ftdi/darsena.cfg -f tcl/target/kx.cfg

Make sure the script has executable permissions:

$ chmod +x k02.sh

Note: add a -c "bindto <host ip address>" after kx.cfg in your launch script if you plan to use a different machine to launch the IDE / run GDB.

Zadig

We currently rely on Zadig to make changes to our Windows 10 USB driver installation. We are using a dual-port FT2232H. Port A is routed to the FPGA JTAG, and Port B is routed to the K02 JTAG. Therefore, we want to use OpenOCD with Port B to debug the K02.

We're following the Zadig basic usage instructions documented here. Our goal is to replace the FTDI driver on Port B with the Microsoft WinUSB driver, so OpenOCD and libusb can communicate with the FT2232H Port B JTAG controller / device.

The figure below shows our Device Manager before running Zadig. COM5, COM6, and USB Serial Converter A and B represent the drivers for the two FTDI ports.

zadig modal — Figure 2. Device Manager After Running Zadig

The next figure is the Zadig application. In order to see our FTDI device, we chose "Options->List All Devices". We selected Interface 1 for Port B. After selecting the device, we clicked "Replace Driver".

The figure below is our Device Manager after running Zadig. You can see that COM6 and USB Serial Converter B disappeared. In its place is "Dual RS232-HS", which represents a WinUSB driver.

Run OpenOCD

We're ready to run openocd, so run the k02.sh script we created earlier (from /build/openocd):

$ ./k02.sh 
Open On-Chip Debugger 0.10.0+dev-00808-gdea90ae4 (2019-04-28-17:21)
Licensed under GNU GPL v2
For bug reports, read
        http://openocd.org/doc/doxygen/bugs.html
Info : auto-selecting first available session transport "jtag". To override use 'transport select <transport>'.
Info : add flash_bank kinetis kx.pflash
adapter speed: 1000 kHz
none separate
cortex_m reset_config sysresetreq
Info : Listening on port 6666 for tcl connections
Info : Listening on port 4444 for telnet connections
Info : clock speed 1000 kHz
Info : JTAG tap: kx.cpu tap/device found: 0x4ba00477 (mfg: 0x23b (ARM Ltd.), part: 0xba00, ver: 0x4)
Info : MDM: Chip is unsecured. Continuing.
Info : kx.cpu: hardware has 6 breakpoints, 4 watchpoints
Info : kx.cpu: external reset detected
Info : Listening on port 3333 for gdb connections

Note the line above Listening on port 3333 for gdb connections. This is what we'll connect to with GDB inside our IDE.

Now, start your IDE of choice and open or start a test C project. In this article, we assume you are using NXP's MCUXpresso.

Open Debug Configurations: Run -> Debug Configurations

Create a new configuration under "GDB Hardware Debugging" and set up the debugger tab as shown in the figure below. In our case, we run the IDE on a different PC than OpenOCD, so we specify the IP address of the machine where openocd is running.

Figure 5. Debugger Configuration for OpenOCD Debugging

Configure your "Startup" settings as shown:

Figure 6. Debugger Configuration - Startup Tab

When you're ready, click "Debug". You should see both the IDE and the openocd terminal window update. If you have errors, please report them below, and we'll try our best to help you.

Footnotes

Darsena supports multiplexing FT2232H Port A with the FPGA JTAG and a UART. For more information see Darsena Hardware Specification.

Didn't find an answer to your question? Post your issue below or in our new FORUM, and we'll try our best to help you find a solution.

And please note that we update our site daily with new content related to our open source approach to network security and system design. If you would like to be notified about these changes, then please join our mailing list.

Getting Started with Darsena	A quick start guide for working with Darsena, the Private Island development board for FPGA-based open source networking
Darsena Hardware Specification	Darsena FPGA Development Board for Open Source FPGA-Based Network Security Project
Review of Ethernet Packet and Packet Processing using an FPGA-based Open Source Network Processor	We examine the fields within an Ethernet packet and discuss how they are processed by an open source FPGA network processor.
Review of Connector Choices for Arduino Shields, Bases, and Compatibles	A review of configurations and connector choices for systems that are compatible with an Arduino form factor.
Gigabit Shields	Gigabit data rate shields using standard 100-mil connectors for Arduino form-factor boards including Darsena. Our new SMA Shield design now released as open source.
Use OpenOCD with Darsena on Linux	We review the steps necessary to use OpenOCD with Darsena on Linux. Also, we build OpenOCD from source using its Git repo and run it on an Ubuntu 16.04 system making use of an Eclipse-based IDE.
Private Island: Open Source FPGA-Based Network Processor for Privacy, Security, IoT, and Control	Overview of the Private Island project for networking including highlights, goals, and a brief description of the development board.