Vicoco

Vicoco: Vivado's simulator with Cocotb

So far when testing your code, you've used the Icarus (or iVerilog) simulator alongside Cocotb to run your testbenches. However, there are ways that Icarus behaves differently that Vivado/our FPGAs; so sometimes you might want to run your testbenches using Vivado instead. Cocotb doesn't support that natively, but we have an add-on we can use to launch the Vivado simulator from cocotb. It's called Vicoco, and it's your TA Kiran's thesis project!

How to Install and use it

In your local Python virtual environment (which is where you have cocotb etc. already installed), you can install vicoco from its GitHub repository with:

pip install git+https://github.com/kiran-vuksanaj/vicoco.git@stable

Testbench file modifications

In order to use Vicoco in a testbench of yours, you'll need to swap out two lines;

1. Replace the import of the get_runner function

   Where your testbench currently imports get_runner from cocotb, like

   from cocotb.runner import get_runner
   

   you should now instead import get_runner from vicoco, with the line:

   from vicoco.vivado_runner import get_runner
   

   This new function still lets you run cocotb with Icarus/other simulators, but adds in the option of using the Vivado simulator as well.

2. Replace the current simulator choice

   In your test launcher function (likely the boilerplate at the bottom of your testbench), you should make vivado be your default simulator, which can be done by replacing the current line that defines sim with:

   sim = os.getenv("SIM","vivado")
   

   (or a similar line.) If you want to run your testbench with Icarus after this change, you can launch your testbench with SIM=icarus python <testbench_name.py>.

Launching your testbench

If you have Vivado installed locally on your computer, you can run your testbench with the same Python script you've previously used, i.e. python <testbench_name>.py. If you're using lab-bc to access Vivado, you can instead use the simulate argument to send up your testbench and have it use the Vivado simulator, e.g. (from your project's base directory):

lab-bc simulate . sim/<testbench_name>.py

When to use it

While there's a little bit of activation energy required in order to get vicoco running, it can likely be useful for some number of your testbenches; consider using it if:

• You have signed math logic (e.g. convolution lab) or other Verilog logic that you're not convinced will operate the same between Icarus simulation and Vivado synthesis
• You have Xilinx encrypted IP that you can't simulate in Icarus; if you add the appropriate xci file as a source, vicoco will build the IP with your simulation.
• You want to see the inputs and outputs of Xilinx primitives or macros that you might be using in your top level (some we've seen in lab include our clock-domain crossing FIFOs, the OSERDES2 HDMI output, among others); they'll be defined when you run your simulation with Vivado.

Limitations/when not to use it

Vicoco is still presently EXPERIMENTAL as heck. As a result, there may sometimes be weird errors you run into while simulating with vicoco, and currently the best source of documentation when that happens is emailing Kiran or finding her in office hours... This will hopefully change soon. There are also certain features that don't exist due to limitations in the code interface for launching the Vivado simulator:

• You can only access/write to signals that are inputs/outputs from the module you're simulating. Any internally defined logics or signals nested inside internal modules, can't be accessed.
• Clocks, or anything in an @(posedge) or @(negedge) argument, should be generated from Cocotb. So you presently can't simulate clocking wizards, you'll have to launch a clock from python for every clock signal you need.

If you encounter issues using Vicoco, please post on Piazza/raise an issue on GitHub/email Kiran/find her in office hours! She wants to know!