C/RTL Cosimulation with Vivado and Python

Summary

Xilinx's xsim simulator (UG900) includes the Xilinx Simulator Interface (XSI), a way to embed a RTL simulation kernel inside a C/C++ program. This page further embeds XSI kernels within a Python session, creating a layered simulation environment where Python, C/C++, and RTL coexist. Testbenches can be coded in a mixture of the three languages, removing the hard boundaries that surround an RTL-only testbench environment.

Warning: As of Vivado 2020.2, fatal exceptions in RTL (VHDL: assert False severity failure) currently leave the simulator kernel in a deeply inconsistent state. Xilinx is aware and has promised a fix in an upcoming Vivado release. You will have to demote your exceptions to a non-fatal severity in the meantime.

Motivation

RTL testbenches are a good way to verify low-level design elements, but RTL testbenches alone are not good enough.

Most importantly, I want to test RTL using best-of-breed tools from the software world. I want to automate regression testing, launch tests quickly and in parallel, and automatically discover tests. I want tests to be parameterized, randomized, and able to execute remotely without struggling to manage licensing limitations.

Next, I want to verify a combination of C and RTL code, where the interface between C and RTL is complex and malleable. Driving a wedge between C code and RTL code so I can extract test vectors via file I/O feels like a monumental distraction.

Also, I need to generate or post-process test data in Python. For signal-processing analysis, my go-to environment is Python/Scipy/Matplotlib. For data analysis, there is nothing in C or RTL that offer the same broad reach and high productivity. You can do this by running pre- and post-processing scripts, but it is brittle and frustrating for no justifiable reason.

Yes, there's more: I want my test environment to resemble my deployment environment. My design is an amalgam of C and RTL when it's deployed; why should the testing environment be different? (Here, ASIC designers will be tearing out their hair. It's OK, I understand.) Combining C and RTL reduces the amount of hassle associated with testing, which allows me to focus on solving problems and not fighting tools.

Finally: I need all of this to work with mixed languages (SystemVerilog/VHDL) and encrypted IP. This, unfortunately, shuts out all of the open-source simulators (Verilator, GHDL, CXXRTL) I would love to be supporting and using. While the open-source tools are creeping closer to mixed-language simulation, it is difficult to see a (legal) path towards supporting encrypted IP in an open simulator. Practically speaking, I'm stuck with either Xilinx's simulator (xsim), or very expensive commercial options.

Compounding the issue further: many excellent test environments (cocotb, VUnit, UVVM) do not work with Xilinx's simulator. As a result, my options for higher-level testing constructs focused on an RTL world dwindle from "frustrating" to "squalid". This is largely Xilinx's fault: although it is slowly improving, xsim's support for SystemVerilog and VHDL-2008 constructs lags other simulators [1].

Demonstration

The following sections show a start-to-finish build, from checking out the source code to completing a test.

$ git clone https://github.com/gsmecher/pyxsi.git
Cloning into 'pyxsi'...
remote: Enumerating objects: 14, done.
remote: Counting objects: 100% (14/14), done.
remote: Compressing objects: 100% (12/12), done.
remote: Total 14 (delta 0), reused 14 (delta 0), pack-reused 0
Receiving objects: 100% (14/14), 6.72 KiB | 6.72 MiB/s, done.

$ cd pyxsi
pyxsi$ . /opt/xilinx/Vivado/2019.2/settings64.sh
pyxsi$ make rtl
xelab work.widget -prj rtl/widget.prj -debug all -dll -s widget
Vivado Simulator 2019.2
Copyright 1986-1999, 2001-2019 Xilinx, Inc. All Rights Reserved.
Running: /opt/xilinx/Vivado/2019.2/bin/unwrapped/lnx64.o/xelab work.widget -prj rtl/widget.prj -debug all -dll -s widget
Multi-threading is on. Using 2 slave threads.
Determining compilation order of HDL files.
INFO: [VRFC 10-163] Analyzing VHDL file "/home/foo/bar/baz/pyxsi/rtl/widget.vhd" into library work
INFO: [VRFC 10-3107] analyzing entity 'widget'
Starting static elaboration
Completed static elaboration
Starting simulation data flow analysis
Completed simulation data flow analysis
Time Resolution for simulation is 1ps
Compiling package std.standard
Compiling package std.textio
Compiling package ieee.std_logic_1164
Compiling package ieee.numeric_std
Compiling architecture behav of entity work.widget
Built XSI simulation shared library xsim.dir/widget/xsimk.so

pyxsi$ make
g++ -fPIC -std=c++17 -I/usr/include/python3.8 -I/opt/xilinx/Vivado/2019.2/data/xsim/include -Isrc -c -o pybind.o src/pybind.cpp
g++ -fPIC -std=c++17 -I/usr/include/python3.8 -I/opt/xilinx/Vivado/2019.2/data/xsim/include -Isrc -c -o xsi_loader.o src/xsi_loader.cpp
g++ -fPIC -std=c++17 -I/usr/include/python3.8 -I/opt/xilinx/Vivado/2019.2/data/xsim/include -Isrc -shared -o pyxsi.so pybind.o xsi_loader.o -ldl

pyxsi$ make test
============================= test session starts ==============================
platform linux -- Python 3.8.3rc1, pytest-4.6.9, py-1.8.1, pluggy-0.13.0
rootdir: /home/foo/bar/baz/pyxsi
plugins: xdist-1.32.0, forked-1.1.3
collected 2 items
[...]
=========================================== 2 passed in 7.16 seconds ===========================================

Conclusions

This is only a skeletal example, with just enough scaffolding to build on.

Since this article was first published, I've extended my own experiments into a fully-fledged regression-testing environment. It's perfect for signal-path environments. If you're curious, please ask for details.