Internal Debugger (IDB) for Xilinx FPGAs

IDB is a GDB like tool for debugging hardware designs that are running on an FPGA. It allows you to drive signals, single and multi-step your logic, set break conditions and view signals live as a wave form. All of this can be done via a command line interface with GDB like commands, key bindings and word completion.

Main Features:

• Drive any signal.
• View any signal (wave form).
• Single step.
• Multi step.
• Reset your logic.
• Drive an enable/disable signal.
• Set break conditions.
• Continue until a break condition is met.
• Automated parsing of debug information (signals, sizes, names, etc.).
• Communication via UART.

Requirements:

• A UART to USB adapter and two available pins (for RX and TX) on the FPGA. Or use a UART to USB hardware component.
• Your FPGA needs to contain design elements for clock gating. The current version was develop on/for Xilinx FPGAs (7-Series) and uses its BUFGCTRL global clock gating design element. If you use any other FPGA manufacturer, you need to replace it with an equivalent design element.

Usage Guide

The debugger consists of two parts: the hardware and software. This sections shows you how to set it up and use it.

Connecting your logic to the IDB hardware Component.

While reading this, I recommend you look at one of the examples in the examples directory.

The idb component's ports are:

module idb
	#(
		parameter CLK_FREQ=100000000,
		parameter DBG_DRIVER_SIZE=1,
		parameter DBG_CAPTURE_SIZE=1
	)(
		input wire i_clk,
		input wire i_reset,

		input wire [DBG_CAPTURE_SIZE-1:0]i_dbg_capture,

		output wire [DBG_DRIVER_SIZE-1:0]o_dbg_driver,
		output wire o_dbg_clk,
		output wire o_dbg_reset,
		output wire o_dbg_enable,

		input wire i_Rx,
		output wire o_Tx
	);

The IDB hardware component uses a UART interface to send and receive data and commands. Connect the i_Rx and o_Tx pins accordingly.The value of the CLK_FREQ parameter (in Hz) needs to be the same as the frequency of the input clock i_clk.

The o_dbg_clk, o_dbg_reset and o_dbg_enable signals should be directly connected to your logic's clock, enable and reset signals. The reset and enable are active high. Initially the reset is held low and the enable is held high. Stepping the logic is done via o_dbg_clk. Connecting o_dbg_reset or o_dbg_enable is not necessary.

The i_dbg_capture signal is used to capture all signals that you want to view. The o_dbg_driver signal is used to set the values of all the signals you want to drive. When connecting these there are two rules you need to follow:

1) Assigning signals to be driven and captured can only be done using the following assignemt structure:

assign capture = {cap_sig1, cap_sig2, cap_sig3};
assign {drv_sig1, drv_sig2} = drive;

This is the assignment structure that my verilog parser expects. Any other structure is not recognized at the moment, due to my parser not being advanced enough. You then connect capture and drive to i_dbg_capture and o_dbg_driver respectively. The capture and driver signals (cap_sig*, drv_sig*) need to also obey rule 2).

2) When declaring capture and drive signals, the size parameters need to be literals

This is valid: wire [7:0]valid_sig;
This is not valid: wire [SOME_SIZE-1:0]invalid_sig;

The reason for this is, that my verilog parser is currently not advanced enough and can only handle literals as size parameters. The DBG_DRIVER_SIZE parameter needs to be equal to the sum of the sizes of the driven signals (drv_sig*). The same goes for the DBG_CAPTURE_SIZE parameter. Currently you are forced to assign something to i_dbg_capture and o_dbg_driver even if you don't want to drive or capture any signals.

Building the IDB software.

Dependencies:
The IDB software uses libreadline. You can install it with: sudo apt-get install libreadline-dev. Every thing else should be standard library.

Build Software:
Run make.

Running the IDB software.

To start IDB you have to run ./idb <serial port name> <top level verilog file name> By top level verilog file name I mean the one where you connect your logic to the idb module. After stating the debugger you will see the debug "meta-data". It is just the automatically parsed debug information such as signals, their sizes and names. You should examine it and see if it matches up with what you expect. For instructions on how to run the software you can also run ./idb without any parameters. When running the debugger you can execute the help command to see a list of available commands and how to use them.

Viewing captured signals

The captured signals are written to a VCD file named idb_trace.vcd. The file gets updated every dbg_clk cycle. You can for example use GTKWave to view the trace.