FPGA and Microcontroller Debugging Tools

This section outlines the supported programming tools for FPGA and microcontroller ICs within the HotRIO product ecosystem. Developers can use this guide to configure their own debugging environments using the recommended hardware and software, ensuring seamless compatibility across different toolchains.

FPGA Programming and Debugging

This section details the software and hardware tools required for programming and debugging FPGA devices. It provides a comprehensive list of supported tools, along with step-by-step guidance on their setup and usage.

Below is an overview of FPGA families supported by HotRIO products, along with their respective development toolchains.

ECP5 FPGA Family

The ECP5 FPGA family from Lattice Semiconductor has been selected as the core FPGA technology for remote data acquisition and processing within the HotRIO ecosystem.

For development, the Lattice Diamond software suite is the preferred toolchain. It provides an integrated environment for:

  • Synthesis: Compiling HDL designs into FPGA-compatible bitstreams.

  • Programming: Flashing the synthesized design onto the FPGA.

  • Debugging: Real-time analysis and troubleshooting of FPGA logic using built-in debugging features.

Further sections will detail the specific configuration steps and hardware interfaces required to program and debug ECP5 devices efficiently.

Hardware Debugger

The ECP5 FPGA is programmed, debugged, and interfaced using a JTAG connection, facilitated by a hardware debugger. While numerous commercially available JTAG interfaces exist, most are incompatible with Lattice Diamond due to the software’s strict requirement for official Lattice programming cables. As a result, using an unsupported JTAG adapter prevents proper communication with the FPGA through Lattice’s toolchain.

FT2232H JTAG debugger (Standard JTAG solution)

Lattice Diamond Programmer, the software responsible for JTAG communication with the FPGA, is designed to work exclusively with Lattice’s official programming cables. However, since ECP5 evaluation boards integrate a USB-to-JTAG bridge via an FT2232H FTDI chip, developers can leverage this chip family to program and debug Lattice FPGAs.

This is regarded as the standard solution for utilizing a readily accessible JTAG programmer. Developers are encouraged to implement this approach given the widespread availability of these boards. In cases where a more tailored and specialized debugging system is necessary, please refer to the detailed instructions in the subsequent section.

Custom JTAG debugger using FTDI FT chip family

This section offers further guidance on utilizing a JTAG debugger within Lattice Diamond using FTDI FT series chips. It also covers how to customize certain parameters, such as the interface name, which is particularly useful when debugging multiple FPGAs simultaneously to distinguish them easily. Additionally, it explains how to modify the USB header product ID and serial number, enabling differentiation between multiple FTDI devices when several debugger interfaces are in use.

TODO

Programming and debugging with Lattice Diamond

The Lattice Diamond software can be used to program and debug any Lattice FPGA, without any license restrictions. Owners of a valid Diamond license for the target device may perform these actions from the main Diamond GUI, while without it the programming and debugging functions must be executed separately using standalone Diamond tools (Diamond Programmer and Reveal Analyzer).

Programming from Diamond GUI

To program the FPGA from the main Diamond GUI (provided availability of a valid license), follow the steps below:

  1. Open a Lattice Diamond project targeting the specific device to be flashed (usually the same project used to build the bitstream).

  2. In the drop-down menu at the top of the UI, navigate to Tools –> Programmer

  3. Select “Create a New Project from a JTAG Scan”. If this option is unavailable, check that cable drivers are installed (installation guide available on the Lattice website) and that the board to be programmed is connected to the PC via the USB-to-JTAG bridge through FT2232 or equivalent chip.

  4. Select the cable and port corresponding to the device to be programmed and click OK.

  5. Ensure that Device family is correct and that Operation is set to “Fast Program”.

  6. Under Filename, browse to the path of the bitstream to be flashed.

  7. Click the Program button at the top of the Programmer UI, represented by a chip with a green downwards arrow on top.

A board programmed in such a way will lose its configuration, thus needing to be reprogrammed, whenever power to the FPGA is removed.

Debugging from Diamond GUI

To debug a firmware using Lattice’s integrated logic analyzer tool (Reveal) from the main Diamond GUI (provided availability of a valid license), follow the steps below:

  1. Open a Lattice Diamond project targeting the specific device to be flashed (usually the same project used to build the bitstream).

  2. In the drop-down menu at the top of the UI, navigate to Tools –> Reveal Analyzer.

  3. Select “Create a New File” and browse to the “impl1” folder of the project to be debugged, then click Detect.

  4. If detection failed, check that cable drivers are installed (installation guide available on the Lattice website) and that the board to be programmed is connected to the PC via the USB-to-JTAG bridge through FT2232 or equivalent chip. Otherwise, select the USB port corresponding to the device to be debugged.

  5. Click Scan. If the scan fails, it is likely because the bitstream flashed to the board does not contain a valid debug core. Scanning always takes some time, waiting up to one minute might be needed.

  6. Under “RVL Source”, browse to the RVL file generated by the Reveal Inserter Diamond tool after definition of the debug core to be included in the design.

  7. Click OK, then use the green play button to start debugging, and the blue arrow button to trigger a manual acquisition.

Programming and debugging with standalone Diamond tools

In absence of a valid Diamond license for the target FPGA device, or in case it is desired not to open the Diamond GUI to perform a program or debug operation, standalone tools can be used with similar procedures as the ones described above.

  • To open the standalone Diamond Programmer, use the following command:

    diamond -pgr

  • To open the standalone Reveal Analyzer, use the following command:

    diamond -rva

After opening any of these tools, follow the instructions in the previous sections from point 3 onwards. Note that while it is possible to debug without a license, it is not possible to generate the debug core without it.

Programming with openFPGALoader

The openFPGALoader tool provides an open-source alternative to the Diamond Programmer for the purpose of flashing bitstreams to Lattice FPGAs, as well as other FPGAs from several different vendors.

Documentation and instructions to install this software can be consulted at the GitHub page of the project.

Compared to Diamond Programmer, openFPGALoader offers speed and automation advantages due to its command-line nature in contrast with the official GUI tool, although it requires manual setup of the correct options to program successfully.

Two minimal examples are presented for the most common use-cases:

  • To flash a bitstream to a Lattice ECP5 Evaluation Board, use the following command after installing openFPGALoader:

    openFPGALoader -b ecp5_evn <path/to/bitstream>

  • To flash a bitstream to a Lattice ECP5 FPGA through a USB-to-JTAG bridge mediated by an FT2232H chip, use the following command after installing openFPGALoader:

    openFPGALoader -c ft2232 <path/to/bitstream>

If more than one USB-to-JTAG peripheral is connected to the PC, the destination USB port must be selected with the “-d”, “–busdev-num”, “–ftdi-serial” and/or “–ftdi-channel” arguments. See the help message of the tool for more information by running openFPGALoader -h.

STM32 Microcontroller Programming and Debugging

For STM32 microcontrollers, software flashing, debugging, and other maintenance tasks are performed using OpenOCD (Open On-Chip Debugger). The FT2232H chip can be configured to function as an SWD-compatible debugger, allowing seamless integration with OpenOCD to program and debug STM32 microcontrollers on HotRIO boards.

Setting Up FT2232H for OpenOCD

The FT2232H chip includes two independent channels that can be configured for JTAG/SWD debugging. OpenOCD supports using this chip as an SWD adapter by mapping its GPIO pins to the correct SWD signals.

Step-by-Step Setup

1. Install OpenOCD

On a Debian-based Linux system, install OpenOCD and related dependencies:

sudo apt update
sudo apt install openocd libftdi1 libftdi1-dev

For other distributions, OpenOCD can usually be installed via the package manager (brew install openocd on macOS, pacman -S openocd on Arch, etc.).

2. Connect the FT2232H to the STM32 Microcontroller

Wire the FT2232H pins to the STM32 microcontroller as follows:

FT2232H Pin

STM32 Pin

Function

AD0 (TCK)

SWCLK

SWD Clock

AD1 (TDI)

(Not used in SWD mode)

AD2 (TDO)

SWO (Optional)

Serial Wire Output for tracing

AD3 (TMS)

SWDIO

SWD Data I/O

GND

GND

Common Ground

VCC

VCC

Power (if needed)

Ensure that the STM32 microcontroller is powered correctly before proceeding.

3. Create an OpenOCD Configuration File

To use the FT2232H as a debugger, create a configuration file (ft2232h_swd.cfg) with the following content:

interface ftdi
ftdi_vid_pid 0x0403 0x6010
ftdi_layout_init 0x0808 0x0a1b
ftdi_layout_signal nTRST -data 0x0800
ftdi_layout_signal nSRST -oe 0x0400
adapter_khz 1000
transport select swd
reset_config srst_only

This configures the FT2232H to operate in SWD mode for STM32 debugging.

4. Launch OpenOCD with FT2232H

Run OpenOCD with the custom configuration file:

sudo openocd -f ft2232h_swd.cfg -f target/stm32<specificTargetFile>.cfg

Replace <specificTargetFile> with the correct target file for your specific STM32 microcontroller family (stm32f1x.cfg, stm32h7x.cfg, etc.).

If successful, OpenOCD will start and listen for GDB connections on port 3333.

5. Connect to OpenOCD using GDB

To debug or flash firmware, start GDB with the STM32 toolchain:

arm-none-eabi-gdb

Inside GDB, connect to OpenOCD:

target extended-remote localhost:3333
monitor reset halt

To flash firmware:

load firmware.elf

To set a breakpoint and continue execution (only hardware breakpoints are supported on STM32 targets):

hbreak main
continue

6. Flashing Firmware using OpenOCD Directly

You can also flash firmware without using GDB by running:

sudo openocd -f ft2232h_swd.cfg -f target/stm32f4x.cfg -c "program firmware.hex verify reset exit"

Replace firmware.hex with the actual firmware file.