Profiling Testbench Code

cocotb provides two ways to profile your testbench code (and cocotb itself). One is by using the built-in tracing profilers in Python, and the other is by using a sampling profiler such as py-spy.

cProfile tracing profiler

The built-in cProfile profiler is a tracing profiler that records every function call and its duration. This is capable of a very high degree of accuracy, but it can also introduce significant execution overhead. Additionally, it is only capable of profiling Python code, so it will not capture time spent in cocotb’s C++ code.

To profile a test run, set the COCOTB_ENABLE_PROFILING to 1 before running your tests. This will create a file named cocotb.prof in the directory where the test was run.

export COCOTB_ENABLE_PROFILING=1

pytest
# or
make

There are many ways to view the resulting profile data, but one of the most common is to use the snakeviz tool to visualize the data in a web browser.

pip install snakeviz
snakeviz cocotb.prof

py-spy sampling profiler

A sampling profiler such as py-spy is not as accurate as a tracing profiler, but, in general, it has less execution overhead than a tracing profiler, which may be preferable for long-running simulations. Additionally, some profilers such as py-spy are able to capture time spent in C++ code, which can be useful for profiling extension modules.

To profile with py-spy, prefix the simulation command with py-spy using SIM_CMD_PREFIX.

export SIM_CMD_PREFIX="py-spy record --format speedscope -o profile.ss --"

pytest
# or
make

It’s recommended to use the speedscope output format which provides a more interactive visualization of the profile data. You can open the output file in the speedscope website, or you can view it locally by installing speedscope. This requires you install Node.js and npm first.

npm install -g speedscope
speedscope profile.ss