/ 
Verilog-VCD-0.08
River stage zero No dependents
/ Verilog::VCD

NAME

Verilog::VCD - Parse a Verilog VCD text file

VERSION

This document refers to Verilog::VCD version 0.08.

SYNOPSIS

use Verilog::VCD qw(parse_vcd);
my $vcd = parse_vcd('/path/to/some.vcd');

DESCRIPTION

Verilog is a Hardware Description Language (HDL) used to model digital logic. While simulating logic circuits, the values of signals can be written out to a Value Change Dump (VCD) file. This module can be used to parse a VCD file so that further analysis can be performed on the simulation data. The entire VCD file can be stored in a Perl data structure and manipulated using standard hash and array operations.

Input File Syntax

The syntax of the VCD text file is described in the documentation of the IEEE standard for Verilog. Both VCD formats (4-state and Extended) are supported. Since the input file is assumed to be legal VCD syntax, only minimal validation is performed.

SUBROUTINES

parse_vcd($file, $opt_ref)

Parse a VCD file and return a reference to a data structure which includes hierarchical signal definitions and time-value data for all the specified signals. A file name is required. By default, all signals in the VCD file are included, and times are in units specified by the $timescale VCD keyword.

my $vcd = parse_vcd('/path/to/some.vcd');

It returns a reference to a nested data structure. The top of the structure is a Hash-of-Hashes. The keys to the top hash are the VCD identifier codes for each signal. The following is an example representation of a very simple 4-state VCD file. It shows one signal named chip.cpu.alu.clk, whose VCD code is +. The time-value pairs are stored as an Array-of-Arrays, referenced by the tv key. The time is always the first number in the pair, and the times are stored in increasing order in the array.

{
  '+' => {
           'tv' => [
                     [
                       '0',
                       '1'
                     ],
                     [
                       '12',
                       '0'
                     ],
                   ],
           'nets' => [
                       {
                         'hier' => 'chip.cpu.alu.',
                         'name' => 'clk',
                         'type' => 'reg',
                         'size' => '1'
                       }
                     ]
         }
};

Since each code could have multiple hierarchical signal names, the names are stored as an Array-of-Hashes, referenced by the nets key. The example above only shows one signal name for the code.

For the Extended VCD format, the tv key returns an array of 4-element arrays:

time value strength0 strength1

OPTIONS

Options to parse_vcd should be passed as a hash reference.

timescale

It is possible to scale all times in the VCD file to a desired timescale. To specify a certain timescale, such as nanoseconds:

my $vcd = parse_vcd($file, {timescale => 'ns'});

Valid timescales are:

s ms us ns ps fs
siglist

If only a subset of the signals included in the VCD file are needed, they can be specified by a signal list passed as an array reference. The signals should be full hierarchical paths separated by the dot character. For example:

my @signals = qw(
    top.chip.clk
    top.chip.cpu.alu.status
    top.chip.cpu.alu.sum[15:0]
);
my $vcd = parse_vcd($file, {siglist => \@signals});

Limiting the number of signals can substantially reduce memory usage of the returned data structure because only the time-value data for the selected signals is loaded into the data structure.

use_stdout

It is possible to print time-value pairs directly to STDOUT for a single signal using the use_stdout option. If the VCD file has more than one signal, the siglist option must also be used, and there must only be one signal specified. For example:

my $vcd = parse_vcd($file, {
                use_stdout => 1,
                siglist    => [(top.clk)]
            });

The time-value pairs are output as space-separated tokens, one per line. For example, for a 4-state VCD file:

0 x
15 0
277 1
500 0

Times are listed in the first column. Time units can be controlled by the timescale option.

only_sigs

Parse a VCD file and return a reference to a data structure which includes only the hierarchical signal definitions. Parsing stops once all signals have been found. Therefore, no time-value data are included in the returned data structure. This is useful for analyzing signals and hierarchies.

my $vcd = parse_vcd($file, {only_sigs => 1});

list_sigs($file)

Parse a VCD file and return a list of all signals in the VCD file. Parsing stops once all signals have been found. This is helpful for deciding how to limit what signals are parsed.

Here is an example:

my @signals = list_sigs('input.vcd');

The signals are full hierarchical paths separated by the dot character

top.chip.cpu.alu.status
top.chip.cpu.alu.sum[15:0]

get_timescale( )

This returns a string corresponding to the timescale as specified by the $timescale VCD keyword. It returns the timescale for the last VCD file parsed. If called before a file is parsed, it returns an undefined value. If the parse_vcd timescale option was used to specify a timescale, the specified value will be returned instead of what is in the VCD file.

my $vcd = parse_vcd($file); # Parse a file first
my $ts  = get_timescale();  # Then query the timescale

get_endtime( )

This returns the last time found in the VCD file, scaled appropriately. It returns the last time for the last VCD file parsed. If called before a file is parsed, it returns an undefined value. This should not be confused with closetime.

my $vcd = parse_vcd($file); # Parse a file first
my $et  = get_endtime();    # Then query the endtime

get_closetime( )

For the Extended VCD format, this returns the time specified by the $vcdclose keyword in the VCD file, scaled appropriately. It returns the last closetime for the last VCD file parsed. If called before a file is parsed, it returns an undefined value. For the 4-state VCD format, it returns an undefined value.

my $vcd = parse_vcd($file); # Parse a file first
my $ct  = get_closetime();  # Then query the closetime

get_date( )

This returns a string corresponding to the date as specified by the $date VCD keyword. It returns the date for the last VCD file parsed. If called before a file is parsed, it returns an undefined value.

my $vcd  = parse_vcd($file); # Parse a file first
my $date = get_date();       # Then query the date

get_version( )

This returns a string corresponding to the version as specified by the $version VCD keyword. It returns the version for the last VCD file parsed. If called before a file is parsed, it returns an undefined value.

my $vcd     = parse_vcd($file); # Parse a file first
my $version = get_version();    # Then query the version

get_decl_comments( )

This returns an array corresponding to the comments as specified by the $comment VCD keyword in the declaration section of the VCD file. There may be any number of $comment keywords in the file. It returns the comments for the last VCD file parsed. If called before a file is parsed, it returns an empty array. If there are no $comment keywords in the declaration section of the file, it returns an empty array.

my $vcd   = parse_vcd($file);    # Parse a file first
my @comms = get_decl_comments(); # Then query the comments

get_sim_comments( )

This returns an array-of-hashes corresponding to the comments as specified by the $comment VCD keyword in the simulation section of the VCD file. There may be any number of $comment keywords in the file. It returns the comments for the last VCD file parsed. If called before a file is parsed, it returns an empty array. If there are no $comment keywords in the declaration section of the file, it returns an empty array.

my $vcd   = parse_vcd($file);    # Parse a file first
my @comms = get_sim_comments();  # Then query the comments

The time at which the comment occurred is included with each comment. An example returned structure is:

({time => 123, comment => '1st comment'},
 {time => 456, comment => '2nd comment'})

get_dumps( )

This returns a hash-of-arrays corresponding to the $dump* VCD keywords ($dumpvars, $dumpon, etc.) in the simulation section of the VCD file. The keys of the hash are the keywords, and the values are the simulation times at which the keywords occurred. It returns the dump commands for the last VCD file parsed. If called before a file is parsed, it returns an empty hash.

my $vcd   = parse_vcd($file);   # Parse a file first
my %dumps = get_dumps();        # Then query the dump commands

EXPORT

Nothing is exported by default. Functions may be exported individually, or all functions may be exported at once, using the special tag :all.

DIAGNOSTICS

Error conditions cause the program to die using croak from the Carp Core module.

LIMITATIONS

The default mode of parse_vcd is to load the entire VCD file into the data structure. This could be a problem for huge VCD files. The best solution to any memory problem is to plan ahead and keep VCD files as small as possible. When simulating, dump fewer signals and scopes, and use shorter dumping time ranges. Another technique is to parse only a small list of signals using the siglist option; this method only loads the desired signals into the data structure. Finally, the use_stdout option will parse the input VCD file line-by-line, instead of loading it into the data structure, and directly prints time-value data to STDOUT. The drawback is that this only applies to one signal.

BUGS

There are no known bugs in this module.

SEE ALSO

Refer to the following Verilog documentation:

IEEE Standard for SystemVerilog
Unified Hardware Design, Specification and Verification Language
IEEE Std 1800-2012
Section 21.7, "Value change dump (VCD) files"

AUTHOR

Gene Sullivan (gsullivan@cpan.org)

COPYRIGHT AND LICENSE

Copyright (c) 2012 Gene Sullivan. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.