Ecosyste.ms: Awesome

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

https://github.com/zachjs/sv2v

SystemVerilog to Verilog conversion
https://github.com/zachjs/sv2v

conversion systemverilog verilog yosys

Last synced: 3 months ago
JSON representation

SystemVerilog to Verilog conversion

Lists

README 

        
# sv2v: SystemVerilog to Verilog



sv2v converts SystemVerilog ([IEEE 1800-2017]) to Verilog ([IEEE 1364-2005]),

with an emphasis on supporting synthesizable language constructs.



[IEEE 1800-2017]: https://ieeexplore.ieee.org/servlet/opac?punumber=8299593

[IEEE 1364-2005]: https://ieeexplore.ieee.org/servlet/opac?punumber=10779



The primary goal of this project is to create a completely free and open-source

tool for converting SystemVerilog to Verilog. While methods for performing this

conversion already exist, they generally either rely on commercial tools, or are

limited in scope.



This project was originally developed to target [Yosys], and so allows for

disabling the conversion of (passing through) those [SystemVerilog features that

Yosys supports].



[Yosys]: https://yosyshq.net/yosys/

[SystemVerilog features that Yosys supports]: https://github.com/YosysHQ/yosys#supported-features-from-systemverilog



The idea for this project was shared with me while I was an undergraduate at

Carnegie Mellon University as part of a joint Computer Science and Electrical

and Computer Engineering research project on open hardware under Professors [Ken

Mai] and [Dave Eckhardt]. I have greatly enjoyed collaborating with the team at

CMU since January 2019, even after my graduation the following May.



[Ken Mai]: https://engineering.cmu.edu/directory/bios/mai-kenneth.html

[Dave Eckhardt]: https://www.cs.cmu.edu/~davide/



## Dependencies



All of sv2v's dependencies are free and open-source.



* Build Dependencies

    * [Haskell Stack](https://www.haskellstack.org/) - Haskell build system

    * Haskell dependencies are managed in `sv2v.cabal`

* Test Dependencies

    * [Icarus Verilog](https://steveicarus.github.io/iverilog/) - for Verilog

      simulation

    * [shUnit2](https://github.com/kward/shunit2) - test framework

    * Python 3.x - for evaluating certain test cases



## Installation



### Pre-built binaries



Binaries for Ubuntu, macOS, and Windows are available on the [releases page]. If

your system is not covered, or you would like to build the latest commit, simple

instructions for building from source are below.



[releases page]: https://github.com/zachjs/sv2v/releases



### Building from source



You must have [Stack] installed to build sv2v. Then you can:



[Stack]: https://www.haskellstack.org/



```

git clone https://github.com/zachjs/sv2v.git

cd sv2v

make

```



This creates the executable at `./bin/sv2v`. Stack takes care of installing

exact (compatible) versions of the compiler and sv2v's build dependencies.



You can install the binary to your local bin path (typically `~/.local/bin`) by

running `stack install`, or copy over the executable manually.



## Usage



sv2v takes in a list of files and prints the converted Verilog to `stdout` by

default. Users should typically pass all of their SystemVerilog source files to

sv2v at once so it can properly resolve packages, interfaces, type parameters,

etc., across files. Using `--write=adjacent` will create a converted `.v` for

every `.sv` input file rather than printing to `stdout`. `--write`/`-w` can also

be used to specify a path to a `.v` output file. Undefined modules and

interfaces can be automatically loaded from library directories using

`--libdir`/`-y`.



Users may specify `include` search paths, define macros during preprocessing,

and exclude some of the conversions. Specifying `-` as an input file will read

from `stdin`.



Below is the current usage printout.



```

sv2v [OPTIONS] [FILES]



Preprocessing:

  -I --incdir=DIR           Add a directory to the include search path

  -y --libdir=DIR           Add a directory to the library search path used

                            when looking for undefined modules and interfaces

  -D --define=NAME[=VALUE]  Define a macro for preprocessing

     --siloed               Lex input files separately, so macros from

                            earlier files are not defined in later files

     --skip-preprocessor    Disable preprocessing of macros, comments, etc.

Conversion:

     --pass-through         Dump input without converting

  -E --exclude=CONV         Exclude a particular conversion (Always, Assert,

                            Interface, Logic, or UnbasedUnsized)

  -v --verbose              Retain certain conversion artifacts

  -w --write=MODE/FILE/DIR  How to write output; default is 'stdout'; use

                            'adjacent' to create a .v file next to each input;

                            use a path ending in .v to write to a file; use a

                            path to an existing directory to create a .v within

                            for each converted module

     --top=NAME             Remove uninstantiated modules except the given

                            top module; can be used multiple times

Other:

     --oversized-numbers    Disable standard-imposed 32-bit limit on unsized

                            number literals (e.g., 'h1_ffff_ffff, 4294967296)

     --dump-prefix=PATH     Create intermediate output files with the given

                            path prefix; used for internal debugging

     --help                 Display this help message

     --version              Print version information

     --numeric-version      Print just the version number

```



## Supported Features



sv2v supports most synthesizable SystemVerilog features. Current notable

exceptions include `defparam` on interface instances, certain synthesizable

usages of parameterized classes, and the `bind` keyword. Assertions are also

supported, but are simply dropped during conversion.



If you find a bug or have a feature request, please [create an issue].

Preference will be given to issues that include examples or test cases.



[create an issue]: https://github.com/zachjs/sv2v/issues/new



## SystemVerilog Front End



This project contains a preprocessor, lexer, and parser, and an abstract syntax

tree representation for a subset of the SystemVerilog specification. The parser

is not very strict. The AST allows for the representation of syntactically (and

semantically) invalid Verilog. The goal is to be more general in the

representation to enable more standardized and straightforward conversion

procedures. This could be extended into an independent and more fully-featured

front end if there is significant interest.



## Testing



Once the [test dependencies] are installed, tests can be run with `make test`.

GitHub Actions is used to [automatically test] commits. Please review the [test

documentation] for guidance on adding, debugging, and interpreting tests.



[test dependencies]: #dependencies

[test documentation]: test/README.md

[automatically test]: https://github.com/zachjs/sv2v/actions



There is also a [SystemVerilog compliance suite] that tests open-source tools'

SystemVerilog support. Although not every test in the suite is applicable, it

has been a valuable asset in finding edge cases.



[SystemVerilog compliance suite]: https://github.com/chipsalliance/sv-tests



## Acknowledgements



This project was originally forked from [Tom Hawkin's Verilog parser]. While the

front end has changed substantially to support the larger SystemVerilog

standard, his project was a great starting point.



[Tom Hawkin's Verilog parser]: https://github.com/tomahawkins/verilog



Reid Long was invaluable in developing this tool, providing significant tests

and advice, and isolating many bugs.



Edric Kusuma helped me with the ins and outs of SystemVerilog, with which I had

no prior experience, and has also helped with test cases.



Since sv2v's public release, many people have taken the time to file detailed

bug reports and feature requests. I greatly appreciate their help in furthering

the project.