Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bensampson5/libsv

An open source, parameterized SystemVerilog digital hardware IP library
https://github.com/bensampson5/libsv

asic asic-library digital-design fpga fpga-library hardware hardware-designs hardware-libraries hdl ip systemverilog verilog

Last synced: about 1 month ago
JSON representation

An open source, parameterized SystemVerilog digital hardware IP library

Awesome Lists containing this project

README 

        
.. image:: https://raw.githubusercontent.com/bensampson5/libsv/main/docs/source/_static/libsv_logo.svg

   :align: center

   :height: 150

   :alt: LibSV



------------------------------------------------------------------------------------------------------------------------



.. image:: https://img.shields.io/pypi/v/libsv

   :target: https://pypi.org/project/libsv/

   :alt: PyPI



.. image:: https://github.com/bensampson5/libsv/actions/workflows/ci.yml/badge.svg

   :target: https://github.com/bensampson5/libsv/actions/workflows/ci.yml



.. image:: https://readthedocs.org/projects/libsv/badge/?version=latest

   :target: https://libsv.readthedocs.io/en/latest/?badge=latest

   :alt: Documentation Status



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///.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:



.. code-block:: bash



  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:



.. code-block:: SystemVerilog



  `include "libsv///.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:



.. code-block:: bash



  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:



.. code-block:: bash



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



Finally, within the Docker container, run ``pytest``:



.. code-block:: bash



  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:



.. code-block:: bash



  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:



.. code-block:: bash



  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.