Verilog::VCD - Parse a Verilog VCD text file
This document refers to Verilog::VCD version 0.08.
use Verilog::VCD qw(parse_vcd); my $vcd = parse_vcd('/path/to/some.vcd');
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.
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.
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.
$timescale
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.
chip.cpu.alu.clk
+
tv
{ '+' => { '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.
nets
For the Extended VCD format, the tv key returns an array of 4-element arrays:
time value strength0 strength1
Options to parse_vcd should be passed as a hash reference.
parse_vcd
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
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.
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:
use_stdout
siglist
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.
timescale
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});
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]
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
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
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.
$vcdclose
my $vcd = parse_vcd($file); # Parse a file first my $ct = get_closetime(); # Then query the closetime
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.
$date
my $vcd = parse_vcd($file); # Parse a file first my $date = get_date(); # Then query the date
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.
$version
my $vcd = parse_vcd($file); # Parse a file first my $version = get_version(); # Then query the version
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.
$comment
my $vcd = parse_vcd($file); # Parse a file first my @comms = get_decl_comments(); # Then query the 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'})
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.
$dump*
$dumpvars
$dumpon
my $vcd = parse_vcd($file); # Parse a file first my %dumps = get_dumps(); # Then query the dump commands
Nothing is exported by default. Functions may be exported individually, or all functions may be exported at once, using the special tag :all.
:all
Error conditions cause the program to die using croak from the Carp Core module.
croak
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.
There are no known bugs in this module.
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"
Gene Sullivan (gsullivan@cpan.org)
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.
To install Verilog::VCD, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Verilog::VCD
CPAN shell
perl -MCPAN -e shell install Verilog::VCD
For more information on module installation, please visit the detailed CPAN module installation guide.