README.md

Verilog VCD Parser

This project implements a no-frills Value Change Dump (VCD) file parser, as described in the IEEE System Verilog 1800-2012 standard. It can be used to write custom tools which need to read signal traces dumped out by Verilog (or VHDL) simulators.

---

Getting Started

After cloning the repository to your local machine, run the following in a shell:

$> cd ./verilog-vcd-parser
$> make all

This will build both the demonstration executable in build/vcd-parser and the API documentation in build/docs.

Code Example

This code will load up a VCD file and print the hierarchy of the scopes and signals declared in it.

VCDFileParser parser;

VCDFile * trace = parser.parse_file("path-to-my-file.vcd");

if(trace == nullptr) {
    // Something went wrong.
} else {

    for(VCDScope * scope : *trace -> get_scopes()) {

        std::cout << "Scope: "  << scope ->  name  << std::endl;

        for(VCDSignal * signal : scope -> signals) {

            std::cout << "\t" << signal -> hash << "\t" 
                      << signal -> reference;

            if(signal -> size > 1) {
                std::cout << " [" << signal -> size << ":0]";
            }
            
            std::cout << std::endl;

        }
    }

}

We can also query the value of a signal at a particular time. Because a VCD file can have multiple signals in multiple scopes which represent the same physical signal, we use the signal hash to access it's value at a particular time:

// Get the first signal we fancy.
VCDSignal * mysignal = trace -> get_scope("$root") -> signals[0];

// Print the value of this signal at every time step.

for (VCDTime time : *trace -> get_timestamps()) {

    VCDValue * val = trace -> get_signal_value_at( mysignal -> hash, time);

    std::cout << "t = " << time
              << ", "   << mysignal -> reference
              << " = ";
    
    // Assumes val is not nullptr!
    switch(val -> get_type()) {
        case (VCD_SCALAR):
            std::cout << VCDValue::VCDBit2Char(val -> get_value_bit());
            break;
        case (VCD_VECTOR):
            VCDBitVector * vecval = val -> get_value_vector()
            for(auto it = vecval -> begin();
                     it != vecval -> end();
                     ++it) {
                std::cout << VCDValue::VCDBit2Char(*it);
            }
            break;
        case (VCD_REAL):
            std::cout << val -> get_value_real();
        default:
            break;
    }

    std::cout << endl;

}

The example above is deliberately verbose to show how common variables and signal attributes can be accessed.

Integration

It is assumed that given a set of source files, it will be easy for people to integrate this as a submodule of their own projects. However, Flex and Bison must be run before all compilable source files are present. If integrating this into a larger project, you will want to ensure the following commands are run before compiling any of the VCD parser sources.

$> make parser-srcs

This will run flex and bison on the .ypp and .l files in src/ and put the generated parser and lexer code in build/. The complete file list for inclusion in a larger project is:

src/VCDFile.cpp
src/VCDFileParser.cpp
src/VCDValue.cpp
build/VCDParser.cpp
build/VCDScanner.cpp

With header files located in both src/ and build/.

Tools

• The parser and lexical analyser are written using Bison and Flex respectively.
• The data structures and other functions are written using C++ 2011.
• The build system is GNU Make.
• The codebase is documented using Doxygen.