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.

Lattice Diamond

TODO

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 emulate an official Lattice programming cable. This method allows third-party hardware to be recognized by Lattice Diamond Programmer in the same way as the ECP5 Evaluation Board’s built-in interface.

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.

For the FTDI chip to function as a Lattice-compatible JTAG programmer, it must be configured with specific USB descriptor settings and internal port configurations. These settings are not publicly documented by Lattice, making direct manual configuration difficult.

The most straightforward approach is to clone the FTDI configuration from a Lattice ECP5 Evaluation Board onto the target FTDI chip. This process ensures the necessary USB descriptors and settings are correctly applied.

Configuration Steps

To replicate the FTDI configuration:

  1. Obtain an ECP5 Evaluation Board: Ensure access to a board with a functional FTDI interface.

  2. Extract the FTDI Configuration: Use an FTDI configuration tool (e.g., FT_Prog or ftdi_eeprom utilities) to read the EEPROM settings from the evaluation board’s FT2232H chip.

  3. Write the Configuration to the Target FTDI Chip: Load the extracted settings onto the new FT2232H chip, ensuring it matches the reference board.

  4. Verify Device Recognition: Connect the modified FTDI chip to Lattice Diamond Programmer and confirm that it is detected as a valid JTAG programmer.

By following this approach, developers can integrate their own FTDI-based JTAG programmers into the HotRIO ecosystem while maintaining full compatibility with Lattice Diamond software.

Required Hardware

To complete the FTDI debugger cloning process, the following hardware is required:

  1. Linux Machine – A computer running Linux is required to perform the FTDI EEPROM read, write, and configuration procedures.

  2. (Optional) ECP5 Evaluation Board – An original ECP5 evaluation board with an embedded FTDI chip can be used to extract the reference FTDI configuration. This step is optional, as a pre-configured EEPROM file may be provided as an alternative.

  3. FT2232H-Based JTAG Debugger – The target FTDI-based JTAG debugger that will be reconfigured to emulate an official Lattice programmer.

  4. Available USB Port – At least one free USB port on the Linux machine to connect the FTDI device for programming.

With the above hardware, the developer can proceed with the FTDI configuration process to ensure compatibility with Lattice Diamond Programmer.

Installing FTDI Chip Tools

Before proceeding with the FTDI configuration, ensure that the necessary software packages are installed on the Linux machine. The required tools include:

  • libftdi1 – Library for interfacing with FTDI chips.

  • libftdi1-dev – Development headers for libftdi1.

  • ftdi-eeprom – Utility for reading and writing FTDI EEPROM configurations.

On Debian-based systems (e.g., Ubuntu), these packages can be installed using the following command:

sudo apt install libftdi1 libftdi1-dev ftdi-eeprom

Once installed, the system is ready to interact with FTDI-based JTAG debuggers.

Downloading the Configuration from an Original ECP5 Evaluation Product

This step is optional and intended for developers who want to extract the original FTDI configuration directly from an ECP5 evaluation board. Alternatively, a pre-configured EEPROM file is available for download in the next section.

Steps to Extract FTDI Configuration:

  1. Connect the ECP5 Evaluation Board:

    • Attach the ECP5 evaluation board to a Linux machine and ensure it’s powered on.

    • Run the command: lsusb

      • You should see an entry like:

      0403:6010 Future Technology Devices International, Ltd FT2232C/D/H Dual UART/FIFO IC

    • Tip: To avoid device misidentification, ensure only one FTDI chip is connected to the computer during this process.

  2. Create a Configuration File:

    • Navigate to a directory of your choice and create a configuration file named lattice_ftdi.conf with the following contents:

      vendor_id=0x0403
product_id=0x6010  # Update this if lsusb shows a different Product ID
filename="lattice_ftdi_eeprom.bin"  # Destination file for EEPROM contents
flash_raw=true

  3. Download the EEPROM Configuration:

    • Execute the following command to read the EEPROM: sudo ftdi_eeprom --read-eeprom lattice_ftdi.conf

    • If successful, a file named lattice_ftdi_eeprom.bin will be created, containing the EEPROM memory contents of the FTDI chip from the ECP5 Evaluation Board.

Flashing the Configuration into the Target FTDI Chip Once the EEPROM configuration has been extracted from an original ECP5 evaluation board (or obtained from a provided file), it must be written to the target FTDI chip. This process modifies the USB descriptors and internal settings to match those of an official Lattice programmer, ensuring compatibility with Lattice Diamond Programmer.

In the event that the developer does not have access to an evaluation product, the following configuration file is available to configure the FTDI chip eeprom : FT2232H EEPROM Configuration FIle

  1. Connect the Target FTDI Device:

    • Plug the FT2232H-based debugger into a USB port on the Linux machine.

    • Verify its detection using: lsusb

    • Ensure an entry like the following appears: 0403:6010 Future Technology Devices International, Ltd FT2232H Dual UART/FIFO IC

    • If multiple FTDI devices are connected, disconnect any unnecessary ones to avoid flashing the wrong device.

  2. Prepare the Configuration File:

    • If you extracted the EEPROM file from an ECP5 evaluation board, ensure lattice_ftdi_eeprom.bin is available in your working directory.

    • If using a pre-configured EEPROM file, download it and place it in the working directory.

  3. Modify the Configuration File (if needed):

    • If the target FTDI chip has a different product_id (as shown by lsusb), update the product_id field in lattice_ftdi.conf accordingly:

      vendor_id=0x0403
product_id=0x6010  # Ensure this matches the target FTDI chip
filename="lattice_ftdi_eeprom.bin"
flash_raw=true

  4. Write the EEPROM Configuration:

    • Execute the following command to flash the configuration: sudo ftdi_eeprom --flash-eeprom lattice_ftdi.conf

    • If successful, the FTDI chip will be updated with the new configuration.

  5. Verify the Flashing Process:

    • Unplug and reconnect the FTDI device.

    • Run lsusb again and check that the device is still detected under the expected vendor and product ID.

    • Optionally, use ftdi_eeprom --read-eeprom to verify the contents match the original EEPROM file.

  6. Test with Lattice Diamond Programmer:

    • Open Lattice Diamond Programmer and check if the newly configured FTDI chip is recognized as a valid JTAG debugger.

    • If successful, the FTDI-based debugger can now be used for FPGA programming and debugging within the HotRIO ecosystem.

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

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.