Home

Awesome

Verilog Parser

Documentation Build Status Coverage Status Licence: MIT

This repository contains a flex / bison parser for the IEEE 1364-2001 Verilog Standard.

Getting Started

This will get you going workspace wise.

$> make all
$> make test-all

This will download the test suite files, setup the build directory, and compile the parser, library and test app.

To start using the parser in your own code, take a look at main.c which is a simple demonstration app used for testing and coverage. The basic code which you need is something like this:

// Initialise the parser.
verilog_parser_init();

// Open A File handle to read data in.
FILE * fh = fopen("my_verilog_file.v", "r");

// Parse the file and store the result.
int result = verilog_parse_file(fh);

if(result == 0)
    printf("Parse successful\n");
else
    printf("Parse failed\n");

fclose(fh);

You can keep calling verilog_parse_file(fh) on as many different file handles as you like to build up a multi-file project AST representation. The parser will automatically follow any include directives it finds.

For an example of using the library in a realish situation, the verilog-dot project shows how the library can be integrated into an existing project and used.

Testing

The test suite is comprised of example code taken from the fantastic ASIC World tutorial on Verilog. The idea being that by using a well-known and comprehensive set of tutorial examples, almost all of the syntactic features of the language can be hit very easily with little effort.

The repository also contains an archive of verilog source code taken from the OpenSPARCT1 microprocessor from Oracle. This archive is unpacked into the tests/ directory when make setup is run, and ensures that the parser is able to handle a real-life source base in terms of scale and complexity. The full workspace environment required to run or analyse the OpenSPARCT1 is not provided, the files only demonstrate the ability to correctly parse a large project, and handle the various internal header files and preprocessor definitions.

Contributing

Of-course, the current test suite does not test everything and I expect there to be awkward bugs. This is the first time I have written a parser of this size and complexity. I have set up automatic coverage collection after each CI build, this gives a good indication of which parts of the code are tested and dependable. Hitting 100% coverage for a parser is a pain, but hopefully over time it will tend that way. The current situation is that all of the verilog language features that are used commonly are tested for. The main missing bits are due to a lack of test cases for user defined primitives (UDPs).

If you find a bug, or otherwise want to contribute, then please don't hesitate to file a pull request. If you have found a bug, please add a test for the bug in the tests/ folder. This should trigger the bug in the original code, and ideally, not trigger in you're submitted fix! I'm open to people just submitting bugs as well, but it might take longer for me to get round to fixing it!

There is more information on how to help in the contributing guide.

Design Choices

Why C, why not something more modern?

This comes down to who will use this tool, and who will develop this tool. Ideally, these are the same people. The current demographic of people working in ASIC / RTL design is that of (please excuse my generalising) electronic engineers, with (again, sorry) little experience of recent programming language technologies like Haskell (great for parsing and formal/state-based assertions) and Python (perl is still king in ASIC design flows, but this is changing). Further, the size and complexity of many RTL designs means you need a language that has lots of low-level acceleration potential, as well as being tried-and-tested. C meets most of these points, while also being something that electronics engineers are more likely to be familiar with and comfortable using.

Why flex/bison, why not Boost::Sprint, ANTLR, or something custom?

Similar to the above answer. These are tools that are very old, and very stable. They are more likely to be available and supported for the kinds of development environments RTL designers work in which are often at least a decade old. What flex and bison loose in terms of nice features, syntactic sugar, and, sadly, ease of use - they make up for in stability and likelihood of familiarity for the people I hope will use this project. Many of the design decisions around this project have been equal parts social and engineering in their justification.

Why not adapt an existing parser?

Good question. I looked at the parsers found in Icarus Verilog and yosys but found that while they were excellent in and of themselves, they were too well adapted to their end use to be made into a general purpose parser. They did inform me well on how to parse the trickier parts of the grammar though, and I certainly cannot fault them in any other way! This parser has been written to correspond very closely to the IEEE Verilog 2001 Syntax specification. This means it is longer (by line count) but much easier to understand and relate to the original specification. For example, each grammar rule in the Bison file matches almost exactly with it's namesake in the IEEE spec.

Todo

There are some things that the parser does not support:

Wishlist

This is a wishlist of tools that I would like to use the parser in. If anyone else would like to use the parser as the basis for their own tools like this, I am more than happy to help!