Welcome to LibSV’s documentation!

LibSV is an open source, parameterized SystemVerilog digital hardware IP library. While similar libraries may already exist, LibSV is unique in that it takes advantage of open-source, state-of-the-art development best practices and tools from across the software and digital design community, including:

Trivial installation. LibSV is hosted on PyPI and can easily be installed using pip or whichever Python package manager of your choice.
Easy-to-use. Simply add `include "libsv/<path>/<to>/<module>.sv" to where you want to use a LibSV module and then add the site-packages/ folder, where LibSV was installed, to the include path when building your project.
Automated testbenches, written in Python, that use pytest to run Cocotb + Verilator under the hood for simple and fast logic simulation
All testbenches output waveform files in FST format for viewing with GTKWave
Extensive documention using Sphinx
Automated formatting and lint checks using Verible
Continuous integration (CI) workflows integrated with Docker
LibSV Docker images published to Docker Hub

Getting Started

LibSV is very easy to use. First, install the libsv package from PyPI:

pip install libsv

We recommend using a Python virtual environment so that the installation is project-specific and isolated from the rest of your system.

Then add the site-packages/ folder, where LibSV was just installed, to your include path when building your project so that your design tools can find LibSV.

Finally, at the top of your design file where you want to use LibSV modules, for each module you want to use, add:

`include "libsv/<path>/<to>/<module>.sv"

Running Testbenches

Running the LibSV testbenches require Cocotb, Verilator, and a number of other dependencies to be installed. Instead of trying to install everything manually on your machine, the easier and recommended way to run the LibSV testbenches is to use the pre-built LibSV Docker images on Docker Hub that have the complete set of LibSV developer tools already installed.

To use a LibSV Docker image, first you’ll need to install Docker, if you don’t already have it.

Next, pull the latest LibSV Docker image:

docker build --pull -f Dockerfile.dev \
  --build-arg UID=$(id -u) \
  --build-arg GID=$(id -g) \
  -t libsv .

Then, start a new Docker container using the LibSV image and mount the project folder to the container:

docker run --rm -it -v $(pwd):/code libsv

Finally, within the Docker container, run pytest:

pytest

This will run all the LibSV testbenches for the entire library (Warning: This may take a while!).

Instead, to list all the available LibSV testbenches, run:

pytest --co

Then, you can run an individual or subset of testbenches using the -k flag which will only run tests which match the given substring expression:

pytest -k EXPRESSION

Each testbench generates an associated .fst waveform file that is written to the build/ directory and can be viewed using GTKWave.

Bugs/Feature Requests

Please use LibSV’s GitHub issue tracker to submit bugs or request features.

Contributing

Contributions are much welcomed and appreciated! Take a look at the Contributing page to get started.

License

Distributed under the terms of the MIT license, LibSV is free and open source software.

Table of Contents: