bensampson5 / libsv

An open source, parameterized SystemVerilog digital hardware IP library

---

Welcome to LibSV! Click here to go 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.

libsv's Issues

Make test job dependent on docker job

Test should always run after Docker so we get the new image to run tests with!

Figure out how to add circuit block diagrams to documentation

Thought that https://github.com/SymbiFlow/sphinxcontrib-hdl-diagrams might be a good fit but it doesn't parse SystemVerilog. Maybe we can follow up with them to get support for SystemVerilog because it looks like Yosys can synthesize SV.

Add simple example for counter

Write Verilator testbench for counter

Add install instructions and usage examples to README and online docs

See if catch2 can be leveraged for unit testing IP

Each branch gets it's own dockerfile

Add functionality to ci.yml so that each branch gets its own docker image on openhdl's docker hub. Here are the rules:

1. If new branch created, then retag the source branch's docker image so that new branch has it's own image
2. If branch == "main" or starts with "docker-" then always build and push a new docker image with every commit
3. All other CI steps run with the specific branch's docker image
4. Upon branch deletion, then remove that docker image from Docker Hub

Add make docs step to ci pipeline

BCD Decoder

Develop a purely combinatorial circuit for a BCD decoder (bcd -> bin)

Fix image link error in README.rst

Oops. Forgot to change it back

Add ability for testbench to output waveforms and view results

Ultimately, I would like to add some examples as well where you can view the waveform

Add c++ linter

clang-tidy?

Add formatting for C++ code

Use clang-format. Will have to pick a style

Task list:

• Pick a formatting style
• Add format style file to project
• Add C++ formatting step to precommit script

try cocotb

Add half adder IP

Add README link to libsv on PyPI after first publish

Remove verilator directives from sv source

Fix branch creation

Add mux ip block

BCD encoder

Implement a BCD encoder

Add github action to automatic docker hub image deletion

Consider adding a github action to automatically delete a docker hub openhdl image if the branch was deleted in the openhdl github repository

Add constant ip block

Add IP block for constant values of variable width

Add concat IP block

Change back counter.sv to use logic instead of reg or wire

Fix docker job if statement

Task list:

• Should not be startsWith for main comparison, should just be ==
• Retag docker image on new remote branch creation (only builds docker if branch == main or starts with "docker-"

Add dockerfile.dev that pulls from Docker Hub openhdl image

Add automated testing to ci workflow

Add Create Issue Branch?

https://github.com/marketplace/actions/create-issue-branch

Always build new docker image on push to main

Add badges to README

Useful badges:

• current pypi version
• main ci status
• docs build status (on main branch)

Update docker meta job

Must update to resolve issue with multiple tags being generated for only getting the right one from ${{ steps.docker_meta.outputs.tags }}. Also migrate to metadata-action instead of crazy-max/ghaction-docker-meta

Full adder documentation missing

Create logo for LibSV

Make unit test simulations downloadable from docs webpage

Add cmake file formatter

.cmake-format.yaml?

Write up a contributing guide

Create a CONTRIBUTING.md with instructions on how to add to the project

Automate docker build and push to docker hub

Add README documentation

How to build docker image, how to run testbenches and view simulation results

Write some kind of IP

The catalog needs to be started with at least one kind of IP. Let's pick a parameterized counter that counts up.

Tasks:

• Create a new Verilog file counter.v
• Write a testbench for it
• Simulate it to validate it's operation

SystemVerilog/Verilog linter

Add a linter for SystemVerilog/Verilog.

I think Verilator has one but Verible definitely has one. So compare and pick one

Retag docker image from origin branch instead of rebuilding

A docker image is completely rebuilt on a push to a new branch but this is very time consuming. Ideally, the better alternative is just to retag the docker image from the source branch for the new created branch.

Figure out auto formatting tool for HDL

Add slice IP block

Figure out package distribution

Maybe use pip initially?

Figure out auto documentation tool for project

Create different version of docs for each branch

Using readthedocs

iwyu for c++

Add Include What You Use (IWYU) check for C++ code

Fix toctrees in docs

Add format check ci step

Applies to all branches

Task list:

• Implement format check for C++ files
• Implement format check for SystemVerilog/Verilog files

Add support to ModuleWrapper for optional clock and reset

Currently ModuleWrapper requires 1 clock and 1 reset signal in the module. Make this optional.