Debugging Using FPGA Integrated Logic Analyzers (ILA)

Sometimes it takes too long to simulate FireSim on RTL simulators, and in some occasions we would also like to debug the simulation infrastructure itself. For these purposes, we can use the Xilinx Integrated Logic Analyzer resources on the FPGA.

ILAs allows real time sampling of pre-selected signals during FPGA runtime, and provided and interface for setting trigger and viewing samples waveforms from the FPGA. For more information about ILAs, please refer to the Xilinx guide on the topic.

MIDAS, in its targetutils package, provides annotations for labeling signals directly in the Chisel source. These will be consumed by a downstream FIRRTL pass which wires out the annotated signals, and binds them to an appropriately sized ILA instance.

Annotating Signals

In order to annotate a signal, we must import the midas.targetutils.FpgaDebug annotator. FpgaDebug’s apply method accepts a vararg of chisel3.Data. Invoke it as follows:

import midas.targetutils.FpgaDebug

class SomeModuleIO(implicit p: Parameters) extends SomeIO()(p){
   val out1 = Output(Bool())
   val in1 = Input(Bool())
   FpgaDebug(out1, in1)

You can annotate signals throughout FireSim, including in MIDAS and Rocket-Chip Chisel sources, with the only exception being the Chisel3 sources themselves (eg. in Chisel3.util.Queue).

Note: In case the module with the annotated signal is instantiated multiple times, all instatiations of the annotated signal will be wired to the ILA.

Using the ILA at Runtime

Prerequisite: Make sure that ports 3121 and 10201 are enabled in the firesim AWS security group.

In order to use the ILA, we must enable the GUI interface on our manager instance. This can be done by running the following commands:

curl -o /home/centos/src/scripts/
sudo sed -i 's/enabled=0/enabled=1/g' /etc/yum.repos.d/CentOS-CR.repo
# keep manager paramiko compatibility
sudo pip2 uninstall gssapi

When the command will finish running, a temporary password will be printed out. This password will be used to access the GUI interface of the master instance. We will connect to the GUI interface of the manager instance using an RDP client. Use the public IP address of the manager instances in order to connect using the RDP client. The username is centos, and the password is the temporary password that was printed out at the end of the previous command. An additional login screen with the username Cloud-User and the same password may appear in some occasion. More information about the AWS GUI interface can be found in the ~/src/GUI_README on the manager instance.

After access the GUI interface, open a terminal, and open vivado. Follow the instructions in the AWS-FPGA guide for connecting xilinx hardware manager on vivado (running on a remote machine) to the debug target .

where <hostname or IP address> is the internal IP of the simulation instance (not the manager instance. i.e. The IP starting with 192.168.X.X). The probes file can be found in the manager instance under the path firesim/deploy/results-build/<build_identifier>/cl_firesim/build/checkpoints/<probes_file.ltx>

Select the ILA with the description of WRAPPER_INST/CL/CL_FIRESIM_DEBUG_WIRING_TRANSFORM, and you may now use the ILA just as if it was on a local FPGA.